Generate, Inspect and Derive IDs with systemd-id128

systemd-id128 is the small command that generates, inspects and derives 128-bit identifiers on any systemd host. You will finish with a repeatable toolkit: a fresh random ID, a lookup on a well-known systemd ID, and an application-specific value derived without ever storing another machine identifier. The examples match systemd 255, installed here as package version 255.4-1ubuntu8.17.

Allow about ten minutes. You need a shell and the installed systemd-id128 command. The normal examples do not need sudo, but reading a machine, boot or service invocation ID can disclose host or runtime identity, so treat those values as sensitive even though the command itself is read-only.

1. Confirm the installed command

Check which binary will run and which systemd release provides it:

$ command -v systemd-id128
/usr/bin/systemd-id128
$ systemd-id128 --version
systemd 255 (255.4-1ubuntu8.17)

The version line may differ on another distribution. This guide uses the systemd 255 interface documented by the local manpage. If your version is older, check its own help and manpage before relying on options added in later releases, especially --value.

Checkpoint: If command -v finds nothing, install the distribution's systemd package through its normal package-management process. Do not copy a binary from another host just to run this guide.

2. Generate a new random ID

Use new when you need a fresh random 128-bit value. Add --uuid when a program or document expects the familiar five-group UUID form:

$ systemd-id128 new --uuid
bd84f7fb-7b06-4b0c-aebe-7e8d9b581cff

Your value will be different every time you run it, which is the point: do not treat this as a reproducible application key or a way to look up an earlier ID. Capture the value explicitly if you need to pass it to another command:

new_id=$(systemd-id128 new --uuid) || exit $?
printf 'new ID: %s\n' "$new_id"

There is no undo needed here. Generating an ID changes nothing on the host; only a later command that stores or publishes the value creates any durable state.

3. Choose value or UUID output deliberately

Plain output prints 32 hexadecimal characters with no separators.
--uuid inserts hyphens into the familiar five-group form.
--value suppresses labels and surrounding output, which is what you want in a script.

$ systemd-id128 show --value user-home
773f91ef66d449b5bd83d683bf40ad16
$ systemd-id128 show --value --uuid user-home
773f91ef-66d4-49b5-bd83-d683bf40ad16

Do not parse the human-readable table when --value already gives you the exact field you need. A command that consumes a UUID may accept either spelling, but check that program's contract rather than assuming it.

Tip: For a shell variable, keep command substitution separate from display text and check the exit status:

id_value=$(systemd-id128 show --value --uuid user-home) || exit $?
printf 'user-home UUID: %s\n' "$id_value"

4. Inspect known IDs and arbitrary values

show recognises well-known IDs, including GPT partition type UUIDs. With no name or UUID it lists everything known to this systemd build, which can run long, so narrow it to one name when you know what you need:

$ systemd-id128 show user-home
NAME      ID
user-home 773f91ef66d449b5bd83d683bf40ad16

You can also give an ID value instead of a name. A recognised value gets its known name back; an arbitrary valid ID is shown with a placeholder name. The lookup does not contact a service and does not modify partition tables or any other storage:

$ systemd-id128 show 773f91ef-66d4-49b5-bd83-d683bf40ad16
NAME      ID
user-home 773f91ef66d449b5bd83d683bf40ad16

Add --uuid when the output feeds a document or tool that expects canonical UUID notation, and --value as well when the consumer must receive only the identifier.

5. Read host and runtime identifiers carefully

Three verbs read identity rather than generate it, and none of them are generic random tokens:

machine-id prints the current machine ID.
boot-id prints the current boot ID.
invocation-id is meant for a systemd service invocation, not an interactive shell.

$ systemd-id128 machine-id --uuid
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
$ systemd-id128 boot-id --uuid
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The masked output above shows the shape only. On a real machine that output identifies that host or boot. Avoid pasting it into a public issue, URL, log collection system or chat unless the disclosure is intentional.

Warning: Do not regenerate or edit /etc/machine-id just to make a test pass. That is a separate, disruptive identity-management operation and can affect services, leases and fleet enrolment.

When a script needs a correlation value that must survive a reboot, decide whether machine identity is genuinely appropriate first. If it only needs a value for one run, generate a new ID instead. When investigating a service, run systemd-id128 invocation-id inside that service's own environment.

6. Derive a stable application-specific ID

Use --app-specific with a valid application ID when you want a deterministic value derived from an application namespace and another ID. The application ID must itself be a 128-bit identifier. The result is not the original machine or boot ID, which makes it a useful boundary when an application needs a stable per-machine value without exposing the raw machine identity.

First create or choose the application namespace. This example uses a fixed value so the calculation can be reproduced:

$ app_id=1fb8f24b-02df-458d-9659-cc8ace68e28a
$ systemd-id128 machine-id --uuid --app-specific "$app_id"
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

That masked output changes with the current machine ID. To reproduce the same calculation on another host, pass both input IDs explicitly to show:

$ systemd-id128 show --value --uuid \
    3a9d668b-4db7-4939-8a4a-5e78a03bffb7 \
    --app-specific 1fb8f24b-02df-458d-9659-cc8ace68e28a
47b82cb1-5339-43da-b2a6-1c350aef1bd1

Both positional IDs and the application ID are inputs, not files to edit. An invalid application ID fails with a non-zero status:

$ systemd-id128 machine-id --app-specific not-an-id
Failed to parse "not-an-id" as application-ID: Invalid argument
$ printf 'exit status: %s\n' "$?"
exit status: 1

Example: Fix the identifier format rather than reaching for sudo. Elevated privileges do not make an invalid ID valid.

7. Use exit status and help in scripts

Success returns status 0; a failure returns non-zero. Script against status and captured values, not against the exact wording of diagnostics. Use --help or the local manpage when adapting a script to another systemd release:

if id_value=$(systemd-id128 show --value --uuid user-home); then
    printf '%s\n' "$id_value"
else
    status=$?
    printf 'systemd-id128 failed with status %s\n' "$status" >&2
    exit "$status"
fi

Recovery: Do not silently substitute new when machine-id or show fails. That changes the meaning of the data and can create hard-to-find identity bugs later.

Done means

You confirmed the installed systemd version and command path.
You can generate random IDs and choose compact or UUID output.
You can query a known ID with show and use --value safely in a script.
You know that machine, boot and invocation IDs carry identity and runtime context.
You can derive an application-specific value from explicit, valid inputs.
Your scripts check exit status and never replace a failed identity lookup with a fresh random ID.