Set and Verify Linux Hostnames with systemd-hostnamed

Every Linux box actually carries three hostnames at once, and systemd-hostnamed is the service that keeps them straight. This guide shows you how to inspect them, change a selected value with hostnamectl, and verify the result without editing system files by hand. The examples match the installed systemd 255 manpages and package version 255.4-1ubuntu8.17.

Allow about ten minutes. You need a shell and a local systemd host. Reading status is normally unprivileged. Changing hostname metadata is a privileged, system-wide operation and may require sudo or another policy-approved authentication method.

1. Check the client and current state

Start with read-only commands. They confirm which executable is in use and show the values that matter before you change anything:

$ command -v hostnamectl
/usr/bin/hostnamectl
$ hostnamectl status
   Static hostname: server.example.test
         Icon name: computer-server
           Chassis: server
        Machine ID: ...

The machine-specific lines vary, so do not compare the complete output character for character. The static hostname is the configured name. The transient hostname can come from network configuration, while the pretty hostname is intended for people and may contain spaces or other display characters.

$ old_hostname=$(hostnamectl --static)
$ printf 'current static hostname: %s\n' "$old_hostname"
current static hostname: server.example.test

If the command prints an empty value, there is no static hostname to restore. In that case, record the transient value separately with hostnamectl --transient and decide whether your network manager should continue supplying it.

2. Understand the three hostname roles

systemd-hostnamed exposes the current, static and pretty hostnames, along with an icon name and chassis type. hostnamectl also reports a transient hostname when one is present. These roles are easy to confuse:

• The static hostname is the persistent configured name, normally stored in /etc/hostname.
• The transient hostname is a temporary fallback, commonly supplied by network configuration. A valid static hostname takes precedence over it.
• The pretty hostname is a human-friendly label. It is stored with other machine metadata in /etc/machine-info.

Static and transient names are restricted to DNS-style labels or a valid fully qualified domain name, with a maximum of 64 characters on Linux. Pretty names have fewer character restrictions. Do not put a display name with spaces into a static hostname.

To query one value at a time, use the matching option:

$ hostnamectl --static
server.example.test
$ hostnamectl --transient
$ hostnamectl --pretty
Office build server

Blank output for transient or pretty means that value is not set. That is different from a failed command. Check the exit status immediately if a script needs to distinguish the cases:

$ hostnamectl --static >/dev/null
$ printf 'hostnamectl status: %s\n' "$?"
hostnamectl status: 0

3. Change only the value you intend to change

Choose a valid example name for your own environment. The following changes only the persistent static hostname:

$ sudo hostnamectl --static hostname build-01.example.test

This is a state-changing command. A hostname change can affect shell prompts, log labels, monitoring, certificates, access-control rules and applications that cache the old name. Before running it on a production host, check those dependencies and make sure you have console or out-of-band access.

To set a human-friendly label instead, leave the static hostname alone and update only the pretty value:

$ sudo hostnamectl --pretty hostname 'Build server - rack 2'

Quote names containing spaces. The command syntax is hostnamectl [selector] hostname NAME; the selector is optional and can be --static, --transient or --pretty. With no selector, setting a name changes the pretty, static and transient hostnames together. That default is broad, so use a selector in a script or whenever you want a narrow change.

There is no need to restart systemd-hostnamed.service after a successful change. The client talks to its D-Bus service, which is activated on request and exits when unused. Do not enable or start the unit as a boot service merely to make hostname changes work.

4. Verify the change at each layer

Run the same query you used to select the value, then inspect the complete state:

$ hostnamectl --static
build-01.example.test
$ hostnamectl status
   Static hostname: build-01.example.test
         Icon name: computer-server
           Chassis: server

For a static hostname, also check the persistent file without editing it:

$ sudo cat /etc/hostname
build-01.example.test

A successful command and a matching /etc/hostname confirm the configured value. They do not prove that DNS, reverse DNS, TLS certificates or every running application has been updated. Those are separate systems and must be checked according to your deployment.

Inspect service activation only when diagnosing the service itself:

$ systemctl status systemd-hostnamed.service --no-pager
● systemd-hostnamed.service - Hostname Service
     Loaded: loaded (.../systemd-hostnamed.service; static)
     Active: active (running) ...

The unit is normally static and on-demand. It may be inactive between requests, and that is not a fault. If hostnamectl status works, the D-Bus activation path is working; do not treat a short-lived or inactive unit as evidence that hostname management is broken.

5. Restore the previous value safely

If you saved the old name in old_hostname, restore only the static hostname:

$ sudo hostnamectl --static hostname "$old_hostname"
$ hostnamectl --static
server.example.test

If you changed the pretty hostname and want it unset, pass an empty string:

$ sudo hostnamectl --pretty hostname ''
$ hostnamectl --pretty

Do not remove /etc/hostname or /etc/machine-info as a shortcut. Those files hold persistent metadata, and manual edits can leave the running state and the stored state out of step. Use hostnamectl for a coordinated update, then verify the resulting files and status.

6. Diagnose the common traps

If a static or transient name is rejected, check its spelling, length, case and punctuation. Use lower-case DNS labels separated by dots, without spaces. A pretty hostname can be more relaxed, so selecting --pretty may be the correct fix when the requested value is a display label rather than a network name.

If a name appears to revert, check whether a network service is supplying a transient hostname and whether a static hostname was actually written. Query all three values with hostnamectl status. Avoid repeatedly overwriting the name until you know which component is authoritative.

If authentication fails, rerun the read-only queries without sudo, then use the privilege mechanism required by the host's policy. Do not weaken privilege rules or edit the unit to make a hostname change. If the D-Bus service cannot be contacted, inspect the system manager and logs with your normal incident procedure before changing anything.