Initialise a Machine ID Safely with systemd-machine-id-setup

systemd-machine-id-setup is normally an installer or image-building tool, and this guide gets you a verified machine ID in /etc/machine-id. The examples use systemd 255.4-1ubuntu8.17, installed here from the systemd package. Allow about ten minutes for a normal host, or twenty minutes if you are checking an image or container workflow.

This command writes persistent identity data, so treat it as a security-sensitive change. You need a root shell or sudo for the real system. Use an isolated alternate root first if you are learning the command or testing an image.

1. Check the installed contract

Start with read-only checks. They do not need elevated privileges:

$ command -v systemd-machine-id-setup
/usr/bin/systemd-machine-id-setup
$ dpkg-query -W -f='${Package} ${Version}\n' systemd
systemd 255.4-1ubuntu8.17
$ systemd-machine-id-setup --version
systemd 255 (255.4-1ubuntu8.17)

The command has no positional argument for an ID. Without --commit, it initialises /etc/machine-id only when that file is missing or empty; it does not replace a valid existing ID. The main options for this guide are --root=PATH, --image=PATH, --commit and --print.

Checkpoint: if you are about to run this on an ordinary, already-installed host, confirm that you intend to establish or repair that host's identity. Do not run it across a fleet image after cloning unless each resulting machine will receive a unique ID.

2. Inspect the current machine ID

Read the file before changing anything:

$ sudo test -r /etc/machine-id && sudo cat /etc/machine-id
a4130d7e8da74a81bd2d313d0d237852

A normal value is a newline-terminated, lower-case hexadecimal string containing 32 characters, representing 128 bits. The exact value is host-specific, so never copy the output into documentation, tickets or network requests. Treat it as confidential. If the file already holds a valid value, the setup command has nothing to initialise.

Check the state without assuming an absent file and an empty file mean the same thing:

$ sudo ls -l /etc/machine-id
$ sudo wc -c /etc/machine-id
33 /etc/machine-id

An image intended for reuse should generally have a missing or empty machine ID so each booted instance can establish its own identity. Do not clear the file on a running production host as a casual reset: that changes first-boot and identity behaviour for services and can make the host difficult to diagnose.

3. Test safely with an alternate root

--root=PATH prefixes the paths operated on, including /etc/machine-id. This lets you test an image tree without touching the host root:

$ test_root=$(mktemp -d /tmp/machine-id-root-XXXXXX)
$ mkdir -p "$test_root/etc"
$ sudo systemd-machine-id-setup --root="$test_root" --print
Initializing machine ID from random generator.
a4130d7e8da74a81bd2d313d0d237852
$ sudo cat "$test_root/etc/machine-id"
a4130d7e8da74a81bd2d313d0d237852

Your 32-character value will differ. In this test the command generated a new ID because the alternate root had no usable ID. --print prints the ID used after the operation, which is useful for verification but also means the value appears in your terminal history or logs if you capture the output.

Run it a second time to confirm a valid value is preserved:

$ sudo systemd-machine-id-setup --root="$test_root" --print
a4130d7e8da74a81bd2d313d0d237852

Checkpoint: the second output should match the first. If it changes, stop and investigate the root path, file contents and mounts before using the workflow for an image build.

4. Initialise the real host only when appropriate

When the target is the running host and /etc/machine-id is missing or empty, run:

$ sudo systemd-machine-id-setup --print
Initializing machine ID from random generator.
a4130d7e8da74a81bd2d313d0d237852

The installed systemd implementation chooses an existing valid D-Bus machine ID first. In a KVM guest it can use a configured VM UUID, and in a Linux container it can use a configured container UUID. Otherwise it generates a random ID. The caller is responsible for making sure any supplied virtual-machine or container UUID is unique for each instance.

Verify the resulting file and its format:

$ sudo awk 'length($0) == 32 && $0 ~ /^[0-9a-f]+$/ { found=1 } END { exit(found ? 0 : 1) }' /etc/machine-id
$ printf 'machine-id format: %s\n' "$?"
machine-id format: 0

This checks shape, not uniqueness. Compare the ID only with a trusted record for the same machine or image process. Never publish it as a harmless hostname substitute.

5. Understand --commit before using it

--commit is a different operation from initial setup. During early boot, systemd can place a transient machine ID from memory over /etc/machine-id when the filesystem is read-only or the file is not yet usable. Once /etc/ and the filesystem become writable, --commit writes that transient ID to disk and removes the temporary mount safely.

It does nothing when /etc/machine-id is not mounted from a memory filesystem, or when /etc/ remains read-only. It is primarily used by systemd-machine-id-commit.service, so do not add it to a general setup script just because it sounds like a finalisation step.

Inspect the current state first:

$ findmnt /etc/machine-id
$ findmnt -no TARGET,FSTYPE,OPTIONS /etc
$ systemctl status systemd-machine-id-commit.service --no-pager

These checks are read-only. If you deliberately need to commit a transient ID, use the command in the host's boot workflow and verify the mount afterwards. Do not force a read-only filesystem writable merely to make this option do something.

6. Handle failures and recovery

A non-zero status means the operation failed. Capture it explicitly when scripting:

$ if sudo systemd-machine-id-setup --print; then
>     printf '%s\n' 'machine ID setup succeeded'
> else
>     status=$?
>     printf 'machine ID setup failed with status %s\n' "$status" >&2
>     exit "$status"
> fi

Common traps are pointing --root at the wrong tree, assuming --commit generates a new ID, and forgetting that a cloned image must not carry the source machine's identity. A permissions or read-only error is a reason to inspect the target mount and ownership, not to delete the existing file.

Recovery: if you initialised the wrong disposable image tree, restore that tree from its clean image or snapshot. On a live host there is no general undo command: deleting or replacing /etc/machine-id can change the identity observed by applications. Use the host's documented rebuild or identity-rotation procedure, with service impact and a recovery copy agreed in advance.

Done means