- Collection Index
- Collections in the Ansible Namespace
- Ansible.Builtin
- ansible.builtin.hostname module – Manage hostname
- Edit on GitHub
'; // Create a banner if we're not on the official docs site if (location.host == "docs.testing.ansible.com") { document.write('
' + '
This is the testing site for Ansible Documentation. Unless you are reviewing pre-production changes, please visit the official documentation website.
' + '
'); } // Create a banner current_url_path = window.location.pathname; var important = false; var msg = '
'; if (startsWith(current_url_path, "/ansible-core/")) { msg += 'You are reading documentation for Ansible Core, which contains no plugins except for those in ansible.builtin. For documentation of the Ansible package, go to the latest documentation.'; } else if (startsWithOneOf(current_url_path, ["/ansible/latest/", "/ansible/9/"])) { /* temp extra banner to advertise something */ banner += extra_banner; msg += 'This is the latest (stable) community version of the Ansible documentation. For Red Hat customers, see the difference between Ansible community projects and Red Hat supported products or Ansible Automation Platform Life Cycle for subscriptions.'; } else if (startsWith(current_url_path, "/ansible/2.9/")) { msg += 'You are reading the latest Red Hat released version of the Ansible documentation. Community users can use this version, or select latest from the version selector to the left for the most recent community version.'; } else if (startsWith(current_url_path, "/ansible/devel/")) { /* temp extra banner to advertise something */ banner += extra_banner; msg += 'You are reading the devel version of the Ansible documentation - this version is not guaranteed stable. Use the version selection to the left if you want the latest (stable) released version.'; } else { msg += 'You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the latest (stable) released version.'; /* temp extra banner to advertise something - this is for testing*/ banner += extra_banner; } msg += '
'; banner += '
'; banner += important ? '
' : ''; banner += msg; banner += important ? '
' : ''; banner += '
'; document.write(banner);
Note
This module is part of ansible-core and included in all Ansibleinstallations. In most cases, you can use the shortmodule namehostname even without specifying the collections keyword.However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.hostname for easy linking to themodule documentation and to avoid conflicting with other collections that may havethe same module name.
Synopsis
Set system’s hostname. Supports most OSs/Distributions including those using
systemd.Windows, HP-UX, and AIX are not currently supported.
Requirements
The below requirements are needed on the host that executes this module.
hostname
Parameters
Parameter | Comments |
|---|---|
name string / required | Name of the host. If the value is a fully qualified domain name that does not resolve from the given host, this will cause the module to hang for a few seconds while waiting for the name resolution attempt to timeout. |
use string added in Ansible 2.9 | Which strategy to use to update the hostname. If not set we try to autodetect, but this can be problematic, particularly with containers as they can present misleading information. Note that ‘systemd’ should be specified for RHEL/EL/CentOS 7+. Older distributions should use ‘redhat’. Choices:
|
Attributes
Attribute | Support | Description |
|---|---|---|
check_mode | Support: full | Can run in check_mode and return changed status prediction without modifying target |
diff_mode | Support: full | Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
facts | Support: full | Action returns an |
platform | Platform:posix | Target OS/families that can be operated against |
Notes
Note
This module does NOT modify
/etc/hosts. You need to modify it yourself using other modules such as ansible.builtin.template or ansible.builtin.replace.On macOS, this module uses
scutilto setHostName,ComputerName, andLocalHostName. SinceLocalHostNamecannot contain spaces or most special characters, this module will replace characters when settingLocalHostName.
Examples
- name: Set a hostname ansible.builtin.hostname: name: web01- name: Set a hostname specifying strategy ansible.builtin.hostname: name: web01 use: systemd
Authors
Adrian Likins (@alikins)
Hideki Saito (@saito-hideki)
