Set and inspect Linux host metadata through systemd-hostnamed

You will finish with a read-and-change workflow for the org.freedesktop.hostname1 D-Bus service: inspect the effective hostname, distinguish static from transient values, set a persistent name and verify related machine metadata. The local reference is the systemd 255 manpage installed with systemd 255.4-1ubuntu8.17.

Allow about fifteen minutes. You need a system running systemd, the gdbus utility, and permission to authenticate through polkit when making changes. The inspection commands are ordinary user commands. Changes affect the machine identity and may affect name resolution or service discovery, so check the proposed values before running them.

1. Confirm the service and inspect its interface

Start with D-Bus introspection. This reads the service definition and does not change the hostname:

$ gdbus introspect --system \
    --dest org.freedesktop.hostname1 \
    --object-path /org/freedesktop/hostname1

Look for the org.freedesktop.hostname1 interface. Its methods include SetHostname, SetStaticHostname, SetPrettyHostname, SetIconName, SetChassis, SetDeployment and SetLocation. The same interface exposes read-only properties such as Hostname, StaticHostname, PrettyHostname, HostnameSource and Chassis.

Checkpoint: if introspection reports that the destination cannot be found, stop. systemd-hostnamed.service normally starts on request, but a non-systemd environment, a missing package or a restricted system bus can still make it unavailable. Installing or starting a service is outside this read-only check.

2. Read the current hostname data

Describe returns the service's properties as one JSON value. The method takes an interactive polkit boolean, but this read operation normally needs no authentication:

$ gdbus call --system \
    --dest org.freedesktop.hostname1 \
    --object-path /org/freedesktop/hostname1 \
    --method org.freedesktop.hostname1.Describe false

Expect a tuple containing a JSON object. The exact values are host-specific. For a smaller, script-friendly view, read individual properties through the standard D-Bus properties interface:

$ gdbus call --system \
    --dest org.freedesktop.hostname1 \
    --object-path /org/freedesktop/hostname1 \
    --method org.freedesktop.DBus.Properties.Get \
    org.freedesktop.hostname1 Hostname
('server.example',)

The returned value is the actual kernel hostname and is never empty. StaticHostname is the persistent value from /etc/hostname; it can be empty even when Hostname is not. HostnameSource reports whether the current value is static, transient or default.

Do not infer persistence from Hostname alone. A transient hostname may have come from an external source and can change without a corresponding hostnamed property notification. If you need to observe the live kernel value, read it with hostname or inspect /proc/sys/kernel/hostname.

3. Choose safe static and pretty names

A static hostname is one DNS-style label. Use lowercase ASCII letters, digits and hyphens, with no leading or trailing hyphen, and keep it within 63 characters. For example, the presentation name Build Rack 1 maps sensibly to build-rack-1.

The pretty hostname is different: it is free-form UTF-8 intended for display. Keep the two values recognisably related so desktop tools, Bluetooth names and service browsers do not show conflicting identities. The pretty value is stored in /etc/machine-info; the static value is stored in /etc/hostname.

Checkpoint: review the exact values before the next step. Changing a hostname can alter prompts, logs, certificates, monitoring labels and local name lookup. Do not use a fully qualified name such as build-rack-1.example.com as the static value when the API expects one hostname label.

4. Set the persistent hostname

Run this as an ordinary user first. The service may ask polkit for authentication; passing true permits an interactive authentication prompt if policy requires it:

$ gdbus call --system \
    --dest org.freedesktop.hostname1 \
    --object-path /org/freedesktop/hostname1 \
    --method org.freedesktop.hostname1.SetStaticHostname \
    build-rack-1 true
()

The method writes the static configuration and usually updates the effective kernel hostname because the static value has the highest priority. It is equivalent to asking systemd-hostnamed to manage the relevant configuration, rather than editing /etc/hostname behind the daemon's back.

Now verify both values and their source:

$ hostname
build-rack-1
$ gdbus call --system \
    --dest org.freedesktop.hostname1 \
    --object-path /org/freedesktop/hostname1 \
    --method org.freedesktop.DBus.Properties.Get \
    org.freedesktop.hostname1 HostnameSource
('static',)

If polkit denies the request, inspect the policy and your session rather than repeatedly retrying with guessed privileges. The API's authentication actions are org.freedesktop.hostname1.set-hostname for transient names and org.freedesktop.hostname1.set-static-hostname for static and pretty names.

5. Add a display name and machine metadata

Set a pretty hostname separately when a human-facing name is useful:

$ gdbus call --system \
    --dest org.freedesktop.hostname1 \
    --object-path /org/freedesktop/hostname1 \
    --method org.freedesktop.hostname1.SetPrettyHostname \
    'Build Rack 1' true
()

Chassis metadata can help applications choose an icon. The installed interface accepts values such as desktop, laptop, server, tablet, handset, vm and container:

$ gdbus call --system \
    --dest org.freedesktop.hostname1 \
    --object-path /org/freedesktop/hostname1 \
    --method org.freedesktop.hostname1.SetChassis \
    server true
()

Only override chassis detection when firmware is wrong or supplies no useful answer. Passing an empty string re-enables automatic detection. The same pattern applies to deployment and location, but those fields are descriptive metadata, not access controls. Their polkit action is org.freedesktop.hostname1.set-machine-info.

6. Undo a change safely

There is no rollback transaction, so keep the old values from step 2 before changing them. To remove the static hostname and let the default or transient value take over, pass an empty string:

$ gdbus call --system \
    --dest org.freedesktop.hostname1 \
    --object-path /org/freedesktop/hostname1 \
    --method org.freedesktop.hostname1.SetStaticHostname \
    '' true
()

This removes the static configuration in /etc/hostname. That is a state-changing and potentially service-disrupting action. Restore the known-good name instead if you only meant to correct a typo:

$ gdbus call --system \
    --dest org.freedesktop.hostname1 \
    --object-path /org/freedesktop/hostname1 \
    --method org.freedesktop.hostname1.SetStaticHostname \
    OLD_STATIC_NAME true

To clear a pretty hostname or restore automatic chassis selection, call the corresponding setter with an empty string. Re-run Describe and hostname after any undo operation.