Ansible hostname Module: Set System Hostname on Linux (Guide)

The ansible.builtin.hostname module sets the system hostname on managed hosts. It automatically detects the init system and uses the correct method for each OS.

Set Hostname

- name: Set hostname
  ansible.builtin.hostname:
    name: webserver01
  become: true

See also: ansible.builtin.template: Deploy Jinja2 Templates with Ansible (Guide)

Set Fully Qualified Domain Name

- name: Set FQDN hostname
  ansible.builtin.hostname:
    name: webserver01.prod.example.com
  become: true

Dynamic Hostname from Inventory

- name: Set hostname from inventory
  ansible.builtin.hostname:
    name: "{{ inventory_hostname }}"
  become: true
# Or use a short name
- name: Set short hostname
  ansible.builtin.hostname:
    name: "{{ inventory_hostname_short }}"
  become: true

See also: Ansible Concatenate Files: Merge Multiple Files in Order (Guide)

Set Hostname + Update /etc/hosts

The hostname module only changes the hostname — it doesn't update /etc/hosts. Do both:

- name: Set system hostname
  ansible.builtin.hostname:
    name: "{{ new_hostname }}"
  become: true
- name: Update /etc/hosts with new hostname
  ansible.builtin.lineinfile:
    path: /etc/hosts
    regexp: '^127\.0\.1\.1'
    line: "127.0.1.1 {{ new_hostname }}.{{ domain }} {{ new_hostname }}"
  become: true
  vars:
    new_hostname: webserver01
    domain: prod.example.com

Strategy Parameter

Choose the hostname implementation:

# Auto-detect (default — recommended)
- ansible.builtin.hostname:
    name: webserver01
    use: auto
# Force specific strategy
- ansible.builtin.hostname:
    name: webserver01
    use: systemd      # systemd-based (RHEL 7+, Ubuntu 16+, Fedora)
# Other options: debian, redhat, alpine, freebsd, openbsd, solaris, macos, sles

| Strategy | Systems | |----------|---------| | systemd | RHEL 7+, CentOS 7+, Fedora, Ubuntu 16+, Debian 8+ | | debian | Older Debian/Ubuntu (pre-systemd) | | redhat | RHEL 6, CentOS 6 | | alpine | Alpine Linux | | freebsd | FreeBSD | | macos | macOS | | sles | SUSE Linux Enterprise |

See also: Ansible reboot Module: Restart Hosts and Wait for Recovery (Complete Guide)

Cloud Instances (cloud-init)

Cloud providers often reset hostnames via cloud-init. Prevent this:

- name: Set hostname
  ansible.builtin.hostname:
    name: "{{ desired_hostname }}"
  become: true
- name: Prevent cloud-init from resetting hostname
  ansible.builtin.copy:
    content: |
      preserve_hostname: true
    dest: /etc/cloud/cloud.cfg.d/99_preserve_hostname.cfg
    mode: '0644'
  become: true
  when: ansible_service_mgr == 'systemd'

Hostname Variables Explained

- name: Show all hostname-related variables
  ansible.builtin.debug:
    msg:
      - "inventory_hostname: {{ inventory_hostname }}"
      - "inventory_hostname_short: {{ inventory_hostname_short }}"
      - "ansible_hostname: {{ ansible_hostname }}"
      - "ansible_fqdn: {{ ansible_fqdn }}"
      - "ansible_nodename: {{ ansible_nodename }}"

| Variable | Source | Example | |----------|--------|---------| | inventory_hostname | Inventory file | web01.prod.example.com | | inventory_hostname_short | Inventory (first part) | web01 | | ansible_hostname | Remote host (hostname -s) | web01 | | ansible_fqdn | Remote host DNS | web01.prod.example.com | | ansible_nodename | Remote host (uname -n) | web01 |

Set Hostname on Windows

- name: Set Windows hostname
  ansible.windows.win_hostname:
    name: WINSERVER01
  register: hostname_result
- name: Reboot if changed
  ansible.windows.win_reboot:
  when: hostname_result.reboot_required

Bulk Hostname Configuration

# inventory
[webservers]
192.168.1.10 desired_hostname=web01
192.168.1.11 desired_hostname=web02
192.168.1.12 desired_hostname=web03
# playbook
- name: Configure hostnames
  hosts: webservers
  become: true
  tasks:
    - name: Set hostname
      ansible.builtin.hostname:
        name: "{{ desired_hostname }}"
- name: Update /etc/hosts
      ansible.builtin.lineinfile:
        path: /etc/hosts
        regexp: '^127\.0\.1\.1'
        line: "127.0.1.1 {{ desired_hostname }}.example.com {{ desired_hostname }}"

FAQ

Does the hostname module update /etc/hosts?

No. It only changes the system hostname (via hostnamectl, /etc/hostname, etc.). You need a separate task with lineinfile to update /etc/hosts.

Why does my hostname reset after reboot?

Usually caused by cloud-init overriding it. Add preserve_hostname: true in /etc/cloud/cloud.cfg.d/ to prevent this. On DHCP clients, check if the DHCP server is pushing hostnames.

What's the difference between ansible_hostname and inventory_hostname?

inventory_hostname comes from your Ansible inventory file and never changes. ansible_hostname is gathered from the actual remote host at runtime. They may differ if the host's configured hostname doesn't match your inventory.

Conclusion

Use ansible.builtin.hostname to set hostnames idempotently. Always update /etc/hosts in the same play. For cloud instances, disable cloud-init hostname reset. Use inventory_hostname for inventory-driven naming.

Related Articles

• Ansible inventory_hostname vs ansible_hostname • Ansible lineinfile Cookbook • Ansible Facts Guide