hostname

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin

Added in version 1.4.

You need further requirements to be able to use this module, see the Requirements section for details.

Synopsis

• Set system's hostname. Supports most OSs/Distributions including those using C(systemd).
• Windows, HP-UX, and AIX are not currently supported.

Requirements

The following Python packages are needed on the host that executes this module:

• hostname

Parameters

Parameter	Defaults / Choices	Comments
name str 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 str	Choices: alpine, debian, freebsd, generic, macos, macosx, darwin, openbsd, openrc, redhat, sles, solaris, systemd	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 V(systemd) should be specified for RHEL/EL/CentOS 7+. Older distributions should use V(redhat). Version Added: 2.9

Notes

Note

• This module does B(NOT) modify C(/etc/hosts). You need to modify it yourself using other modules such as M(ansible.builtin.template) or M(ansible.builtin.replace).
• On macOS, this module uses C(scutil) to set C(HostName), C(ComputerName), and C(LocalHostName). Since C(LocalHostName) cannot contain spaces or most special characters, this module will replace characters when setting C(LocalHostName).

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)