Understand systemd's Offline Update Boot Redirect

Boot into a strange minimal mode after an update and systemd-system-update-generator is usually why.

It diverts the boot into system-update.target whenever an offline update marker exists. You will learn how that redirect works, 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 normally runs during boot and reloads; it is not a command you invoke by hand in ordinary use. You need a shell for the read-only checks below. Elevated privileges are only needed for inspecting protected paths or removing a marker.

1. Confirm the generator and its role

Confirm 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

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. This generator does not take a command-line filename as input: it checks the fixed marker locations on the host filesystem.

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 one:

$ 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 update manager chooses the target directory. 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 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 plus the units that implement the update. It is an offline mode designed 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. Treat it as 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 outright.

Offline update services are meant to identify the marker they created, perform only their own update, and arrange a reboot once done. Several update services can be installed side by side, 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 check the owning package manager's logs and status. The generator does not download packages, select an update, or decide whether one is ready; it only redirects the 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 workflow that created it. A marker left behind by an interrupted update is 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 the update manager has actually finished, that no maintenance window is active, and that no service depends on the staged files. Keep a copy of the link target in your incident notes.

Once the owning workflow confirms 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 still be needed for recovery, and its ownership and cleanup rules belong to the update manager, not you.

Once 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 own recovery procedure rather than repeatedly deleting it.

Common traps

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