=encoding utf8

=head1 NAME

finalrd - final runtime directory generator for shutdown

=head1 SYNOPSIS

 systemctl enable --now finalrd.service

=head1 HOOKS DIRECTORIES

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

=head1 HOOKS INTERFACE

 foo.finalrd setup
 foo.finalrd halt|poweroff|reboot|kexec

=head1 DESCRIPTION

B<finalrd> generates a shutdown directory I</run/initramfs> which
B<systemd-shutdown> pivots to during shutdown. There system shutdown
can be finalised and arbitrary hooks can be executed off-root, to
safely cleanup rootfs and perform any other shutdown tasks.

For example, a hook may takeover monitoring external metadata RAID
arrays, wait for them to be clean, and stop them. If one is using
iscsiroot, it maybe needed to perform iscsi logout on shutdown.

Typically, one would not run B<finalrd> directly, but instead activate
B<finalrd.service>. This would execute B<finalrd> generator late in
the shutdown cycle, just in time for pivot.

=head1 HOOKLESS OPERATION

If initramfs-tools is not available, and thus copy_exec is not
available, hooks will not be executed or copied into the shutdown
directory. However, shutdown dir will still be created to ensure init
has somewhere to pivot, and attempt a cleaner shutdown without holding
up the root filesystem.

For example, Ubuntu Core is such system.

=head1 HOOKS INTERFACE DESCRIPTION

I<*.finalrd> hooks can be shipped in I</usr>, I</etc>, I</run>. These
directories are for distribution, sysadmin, and transient hooks
respectively.

They are multi-purpose binaries with action passed as the first
argument.

During setup stage, hooks are executed from the rootfs with one
argument B<setup> passed as the first arg. All hooks are executed in
all the directories in order, first everything in I</usr>, then from
I</etc>, then from I</run>. Environmental variables I<DESTDIR> and
I<DESTROOTDIR> are set pointing at the finalrd location. This is done
for convenience to use I<initramfs-tools>'s copy_exec function or
dracut-install, for copying binaries.

During shutdown stage, hooks are executed from finalrd in parallel
with one argument passed to them. The argument is one of B<halt>,
B<poweroff>, B<reboot>, B<kexec>.

Note if there are identically named hooks in multiple configuration
directories, all of them will be executed during setup stage. But only
the last one will be copied into the finalrd and executed during the
shutdown stage.

=head1 SEE ALSO

L<The initrd Interface of
systemd|https://www.freedesktop.org/wiki/Software/systemd/InitrdInterface>
