Set Up finalrd for Shutdown Cleanup Hooks

If your iSCSI sessions or RAID arrays get dropped rudely at shutdown, finalrd is the small systemd piece that gives them a proper last word. You will enable it as a service, see which shutdown hooks exist, and verify the setup before you rely on it.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the installed service and version
2. Activate finalrd before the next shutdown
3. Understand the three hook locations
4. Treat the hook interface as two different phases
5. Check whether hooks can be copied
6. Verify the boundary without forcing a shutdown

Allow about fifteen minutes for a read-only review, or longer if you are writing and testing a custom hook.

Version. This guide covers the installed finalrd package 9build1, whose manual page identifies the program as finalrd 2.
You need: a systemd system and a shell with sudo access.

Warning

Enabling the service is a persistent, privileged change that affects shutdown. Do it in a maintenance window and keep a way to reach the machine in case shutdown does not behave as you expect.

1. Check the installed service and version

Start with ordinary, read-only checks. They confirm the package and show the service unit without running the generator:

$ command -v finalrd
/usr/bin/finalrd
$ dpkg-query -W -f='${Package} ${Version}\n' finalrd
finalrd 9build1
$ systemctl cat finalrd.service
[Service]
RemainAfterExit=yes
Type=oneshot
ExecStart=/bin/true
ExecStop=/usr/bin/finalrd

The service is deliberately a oneshot unit whose stop action runs finalrd. The normal workflow is to activate finalrd.service, not to invoke finalrd by hand. The generator prepares /run/initramfs for the later systemd shutdown pivot.

Checkpoint

If the package query fails, stop here and install or repair the package through your normal system administration process. Do not copy a random script into /usr/bin.

2. Activate finalrd before the next shutdown

Once you have a recovery path and a suitable window, enable and start the documented service. This needs elevated privileges:

$ sudo systemctl enable --now finalrd.service

The command enables the unit for future boots and starts its systemd state now. Check both pieces separately:

$ systemctl is-enabled finalrd.service
enabled
$ systemctl is-active finalrd.service
active

Checkpoint

active does not mean any shutdown hooks have run. The unit's service process is /bin/true, and finalrd is called by the unit's stop action as shutdown begins. All you are confirming here is that systemd knows the unit and has it enabled.

Recovery

To undo this activation before testing further, disable and stop the unit with root privileges. This removes the enablement and stops the active unit. It does not remove the finalrd package or delete hook files.

$ sudo systemctl disable --now finalrd.service

3. Understand the three hook locations

finalrd looks for executable files ending in .finalrd in three directories:

/usr/share/finalrd/*.finalrd
/etc/finalrd/*.finalrd
/run/finalrd/*.finalrd

/usr/share/finalrd. Distribution hooks.
/etc/finalrd. Administrator-managed hooks.
/run/finalrd. Temporary or generated hooks.

Inspect what is present without changing it:

$ find /usr/share/finalrd /etc/finalrd /run/finalrd \\
    -maxdepth 1 -type f -name '*.finalrd' -printf '%p %m\n' 2>/dev/null
/usr/share/finalrd/mdadm.finalrd 755
/usr/share/finalrd/open-iscsi.finalrd 755

Your list can be shorter, and permissions can differ. A hook must be executable to be useful. The installed examples handle mdadm arrays and open-iSCSI, but their presence does not mean either technology is configured on your machine.

Warning

Names matter. During setup, every matching hook in the /usr, /etc, then /run directories is run. If identical names occur in more than one directory, all copies are used for setup, but only the last copy is placed in the shutdown directory. Avoid duplicate names unless that replacement is deliberate.

4. Treat the hook interface as two different phases

A hook is a multi-purpose executable. During preparation it receives setup as its first argument and runs from the normal root filesystem. finalrd sets DESTDIR and DESTROOTDIR to the shutdown directory, so the hook can copy its programs and configuration with initramfs-tools or dracut tooling.

case "$1" in
    setup)
        # Copy every binary, library and configuration file needed later.
        ;;
    halt|poweroff|reboot|kexec)
        # Perform only the shutdown action needed for this operation.
        ;;
esac

At shutdown, hooks are copied into finalrd and run from there, in parallel, with one of halt, poweroff, reboot or kexec as the first argument. They no longer run against the ordinary root filesystem. A hook that works interactively in /usr can fail after the pivot if its interpreter, libraries, configuration or device tools were not copied during setup.

Safety boundary

A shutdown hook can stop storage, log out iSCSI sessions or wait for hardware. Test it with the exact host configuration and keep timeouts in any operation that can wait. Hooks run in parallel, so do not make one depend on another completing unless you provide an explicit coordination mechanism.

5. Check whether hooks can be copied

With initramfs-tools available, finalrd can use its copy functions during setup. Without it, the shutdown directory is still created, but hooks are neither copied nor executed. The manual calls this hookless operation. It gives systemd-shutdown somewhere to pivot, but it is not a working custom-hook deployment.

$ test -r /usr/share/initramfs-tools/hook-functions && echo 'hook support available' || echo 'hookless operation'
hook support available

This test is read-only and needs no sudo. If it reports hookless operation, do not claim a new hook will perform shutdown cleanup. Review the platform's initramfs and shutdown design first.

Checkpoint

Before adding a hook, write down every executable and configuration file it needs, the expected shutdown action, and how you will tell it completed. A successful setup stage alone does not prove the later off-root action can run.

6. Verify the boundary without forcing a shutdown

Warning

Do not run a new cleanup hook by calling it with halt or poweroff from an ordinary shell. That bypasses the finalrd environment and can stop live resources. Review the service and hook inputs instead, then use a maintenance-window reboot only after the hook has been tested on a disposable or non-critical target.

$ systemctl status finalrd.service --no-pager
$ systemctl show finalrd.service -p ExecStart -p ExecStop -p ActiveState
ExecStart={ path=/bin/true ; ... }
ExecStop={ path=/usr/bin/finalrd ; ... }

Status formatting varies between systemd releases. Verify that the unit is loaded, ExecStart is /bin/true, and ExecStop names /usr/bin/finalrd. A manually created /run/initramfs directory is not proof that the service's full shutdown preparation succeeded.

Done means

Versions known. You have the installed package and finalrd versions.
Enabled with a safety net. finalrd.service is enabled only when the host has a tested recovery path.
Hooks filed correctly. They sit in the right directory and duplicate names are understood.
Off-root ready. Each custom hook supplies everything it needs for the shutdown phase.
Copy support checked. You know whether initramfs-tools hook support is available.
No forced shutdown. Nothing was run from an ordinary shell, and the next test has a maintenance window and rollback plan.