hostname

hostname sets the node's host name, both the stored one (/etc/hostname) and the running one, with hostnamectl on the node. It does not edit /etc/hosts; if your servers need a line there, own that file with a file node task.

Inputs

  • name (string; required): a short name or a fully qualified one, at most 64 characters; own /etc/hosts with a file task

Outputs

The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.

  • status
  • change
  • value.hostname_before
  • value.hostname_after

What a dryrun reports

Supported; reads the stored and the running host name and reports the name that would be set.

Retries and time limits

Bounded automatic retries by default; retry: false turns them off.

The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.

Examples

Name the node after its inventory entry

- hostname:
    name: "{{ .node.name }}.example.com"

On the node, this node task sets the host name web01.example.com for a node named web01 in the inventory. MMX inspects the node first and reports unchanged when the node already has that name. A changed host name is reported with the old and the new name.

How it works

  • name is a short name such as web01 or a fully qualified one such as web01.example.com: letters, digits, and hyphens, in parts separated by dots, at most 64 characters.
  • Results and dryrun show hostname_before and hostname_after in .this_node_task.value. hostname_before is the stored host name, or the running one on a node that has none stored.

Errors and what they mean

The reason holds What the error means, and what to do
hostnamectl is not installed; install the package systemd first Install the systemd package in an earlier node task. A dryrun reports the hostname node task not checked, because an earlier node task may install hostnamectl.

Tested on

Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.

The suite tests/integration/node_settings.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, in containers on the first four and in virtual machines on the last two. The validation record has the latest results.

This page is docs/reference/modules/hostname.md in the MMX repository.