Redirect a Linux Boot into systemd's Offline Update Mode

You will learn how systemd-system-update-generator diverts a boot into system-update.target when an offline update marker exists, how to inspect the state without starting an update, and how to clear a stale marker safely. Allow about 15 minutes for inspection. Creating a marker for a real update is a package-manager operation, not a harmless test.

Prerequisites and the safety boundary

This guide targets the installed systemd 255 package on this host. Check your own version first:

$ systemctl --version
systemd 255 (255.4-1ubuntu8.17)

Your package revision can differ. The generator itself is normally run by systemd during boot and reloads; it is not a command you usually invoke by hand. You need a shell for the read-only checks below. Elevated privileges are only needed when inspecting protected paths or removing a marker.

A marker is a high-impact boot switch. If /system-update or /etc/system-update exists, the generator redirects the boot to the offline update target. Do not create either path with touch, and do not reboot a host merely to see what happens. An update service may mount filesystems, change packages, and reboot the machine.

1. Confirm the generator and its role

Confirm that the package installed the generator where systemd expects it:

$ command -v systemctl
/usr/bin/systemctl
$ ls -l /usr/lib/systemd/system-generators/systemd-system-update-generator
-rwxr-xr-x 1 root root ... /usr/lib/systemd/system-generators/systemd-system-update-generator

The exact size and timestamp vary. The useful result is an executable at that path. Systemd invokes generators with output directories and uses their generated links or units for the current manager state. The update generator's input is not a command-line filename: it checks the fixed marker locations in the host filesystem.

Checkpoint: you have confirmed both the systemd release and the installed generator. Do not run the generator with guessed arguments and interpret an empty temporary directory as a simulation of a real boot.

2. Inspect the two marker locations

Check both locations without changing them. ls -ld is useful here because it shows a symlink itself, including a dangling symlink:

$ ls -ld /system-update /etc/system-update
ls: cannot access '/system-update': No such file or directory
ls: cannot access '/etc/system-update': No such file or directory

Those errors are the normal result when no offline update is pending. If one path is present, record its target before doing anything else:

$ ls -ld /system-update /etc/system-update 2>/dev/null
lrwxrwxrwx 1 root root 22 ... /system-update -> /var/lib/system-update

The target directory is chosen by the update manager. Do not infer which package manager created the marker from the filename alone, and do not replace the link with one of your own. A dangling symlink still matters to early-boot logic, so a failed target lookup is not proof that the marker is harmless.

3. Understand what the redirect changes

When either marker exists, the generator temporarily makes default.target resolve to system-update.target for that boot. The target pulls in the base system through sysinit.target and the units that implement the update. It is an offline mode intended to avoid conflicts between running services and files being replaced on disk.

Inspect the target and its dependency tree without activating it:

$ systemctl cat system-update.target
$ systemctl list-dependencies --all system-update.target
system-update.target
* ...

The dependency list depends on the installed package set. It is diagnostic output, not an instruction to start the target. Do not run systemctl isolate system-update.target as a test on a working machine: isolation changes the running system and may stop ordinary services.

Offline update services should identify the marker that they created, perform only their own update, and arrange a reboot after completion. Multiple update services can be installed, but only the one matching the marker should act. Running unrelated update services in parallel is unsafe.

4. Check whether a reboot is actually pending

Look for the update marker, then inspect the owning package manager's logs and status. The generator does not download packages, select an update, or decide whether an update is ready; it only redirects boot when the marker exists.

$ for path in /system-update /etc/system-update; do
>   if [ -e "$path" ] || [ -L "$path" ]; then
>     printf '%s: present\n' "$path"
>     ls -ld "$path"
>   else
>     printf '%s: absent\n' "$path"
>   fi
> done
/system-update: absent
/etc/system-update: absent

Use sudo only if your account cannot inspect the path or the update tool requires it. If a marker is present, stop before rebooting and identify the update workflow that created it. A marker left by an interrupted update can be a recovery problem, not a request to repeat the update blindly.

5. Recover from a stale marker

Do not remove a marker while an update is prepared or running. First confirm that the update manager has finished, that no maintenance window is active, and that no service is relying on the staged files. Keep a copy of the link target in your incident notes.

Once the owning workflow confirms that cancellation is safe, remove only the marker that is present. These commands remove directory entries, not the target directory:

$ sudo unlink /system-update
$ sudo unlink /etc/system-update

An absent path produces an error, which is safe to treat as 'nothing to remove'. Do not use a recursive removal command on /var/lib/system-update as a shortcut. The staged update data may be needed for recovery, and its ownership and cleanup rules belong to the update manager.

After a package manager has removed the marker or you have cancelled it with that tool, ask systemd to rebuild generated state:

$ sudo systemctl daemon-reload
$ ls -ld /system-update /etc/system-update
ls: cannot access '/system-update': No such file or directory
ls: cannot access '/etc/system-update': No such file or directory

daemon-reload reruns generators and reloads units; it does not apply packages and it does not undo an update already made. If the marker reappears, stop and use the update manager's recovery procedure rather than repeatedly deleting it.

Common traps

• An empty generator output directory from a hand-run test does not prove that the host will boot normally. The generator checks the host's own marker paths.
• The marker is not a general 'reboot into maintenance' switch. It belongs to a coordinated offline-update workflow.
• system-update.target is a target, not the update program. The installed update services determine what work occurs.
• A successful daemon-reload confirms that systemd accepted a reload, not that a package update succeeded.