Trigger systemd shutdown safely and understand the final hand-off

You will finish with the correct way to request a power-off, halt, reboot or kexec transition, and with a clear picture of what happens after systemd has stopped ordinary services. The examples match systemd 255.4-1ubuntu8.17 installed on this machine. Allow about ten minutes for the checks; a real shutdown takes however long your services and storage need.

You need a shell account allowed to manage the system. The inspection commands are normally unprivileged. The commands that actually change machine state need elevated privileges, usually through sudo. Save work and arrange console or remote-access recovery before using them.

1. Check the installed systemd version

Start by recording the implementation you are about to operate:

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

The installed manpage describes systemd 255. Behaviour, unit paths and package layout can differ on another distribution or release, so do not silently transplant these paths into a different host.

2. Choose the requested transition

Use systemctl to request the action. Do not start the service units named in the manpage directly:

$ sudo systemctl poweroff
$ sudo systemctl halt
$ sudo systemctl reboot
$ sudo systemctl kexec

Run only one of these commands. They are not four stages. poweroff turns the machine off, halt stops the operating system without necessarily removing power, reboot restarts it, and kexec transitions into a kernel loaded for kexec. The last option depends on a prepared kexec setup and is not a generic alternative to reboot.

3. Understand which unit is selected

The request enters a target, which pulls in the matching service:

Inspect the installed unit files without activating them:

$ systemctl cat systemd-poweroff.service systemd-halt.service systemd-reboot.service systemd-kexec.service
$ systemctl list-dependencies poweroff.target

Expected output includes unit definitions and a dependency tree. The exact ordering and additional dependencies are distribution-specific, so use the output from this host when diagnosing a delayed shutdown.

4. Know what happens after services stop

During the final hand-off, PID 1 is replaced by /usr/lib/systemd/systemd-shutdown. That separate binary is needed so an upgrade cannot leave the running manager dependent on libraries that have already disappeared. It attempts to unmount remaining file systems, or remount them read-only, disables remaining swap, detaches storage and kills remaining processes.

This is why a successful request can make the machine disappear before you see a neat final message. A stuck shutdown is not fixed by repeatedly starting the poweroff service. Check the previous boot from the next boot instead:

$ journalctl -b -1 -u systemd-poweroff.service
$ journalctl -b -1 -u systemd-shutdown.service

The second command may have little or no unit output because the final program is not an ordinary long-running service. Also inspect the previous boot's general journal if a particular mount or service held up the transition:

$ journalctl -b -1 -e

Reading the journal is normally unprivileged on a system where your account has journal access; use sudo if the journal is restricted.

5. Treat system-shutdown hooks as a constrained last step

Immediately before the final action, systemd-shutdown runs every executable in /usr/lib/systemd/system-shutdown/ in parallel. Each receives one argument: poweroff, halt, reboot or kexec. The shutdown action waits for all of them to finish.

Inspect the directory rather than adding a hook casually:

$ ls -l /usr/lib/systemd/system-shutdown/
total 4
-rwxr-xr-x 1 root root 160 ... mdadm.shutdown

Hooks run after services have stopped and most mounts have been detached. The root file system, /run/ and several API file systems remain, but /var/ is not a dependable writable location. A hook must therefore be self-contained, finish promptly, handle its action argument, and avoid relying on a service, network, or ordinary data hierarchy. Because hooks run in parallel, do not assume another hook has completed first.

6. Choose a soft reboot when hardware must stay put

If the goal is to restart the operating system userspace while leaving the kernel, firmware and hardware in place, investigate systemd-soft-reboot.service instead. That is a different mechanism from systemd-reboot.service and should not be substituted without checking that applications and the host environment support it:

$ systemctl cat systemd-soft-reboot.service
$ systemctl --help | grep -i soft

If the installed systemctl does not offer a soft-reboot command, do not invent one from the service name. Use the local systemd documentation and package documentation to determine whether that feature is exposed by this release.