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.
statuschangevalue.hostname_beforevalue.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
nameis a short name such asweb01or a fully qualified one such asweb01.example.com: letters, digits, and hyphens, in parts separated by dots, at most 64 characters.- Results and dryrun show
hostname_beforeandhostname_afterin.this_node_task.value.hostname_beforeis 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.