MKINITRAMFS.HOOKS(7) Miscellaneous Information Manual MKINITRAMFS.HOOKS(7)

mkinitramfs.hooks — mkinitramfs hooks and related stuff

mkinitramfs hooks provides a way to extend initramfs' build and init process. Hooks must be written in POSIX shell. Bashisms and other non-portable extensions are prohibited.

Hooks can be located in /usr/share/mkinitramfs/hooks (system path) and /etc/mkinitramfs/hooks (user path). It is also allowed to specify custom location via mkinitramfs(8)' -H hooksdir option.

In order to write hooks you must know about hook structure. Example:

hooks/
`‐‐ <hook>/               ← Directory of hook scripts
    |‐‐ <hook>            ← Invoked in build process
    |‐‐ <hook>.init       ← Invoked in init process
    `‐‐ <hook>.init.late  ← Invoked after root filesystem
                             was mounted

The following functions can be used by hooks in build process:

PATH
Copy kernel module by PATH (full path to kernel module) to mkinitramfs working directory.
PATH | NAME
If PATH (full path to binary) was specified and it has executable bit, then it will be copied to /bin location of mkinitramfs working directory.

If NAME was specified, the mkinitramfs will try to find command by name in “PATH”. If success, command will be copied to /bin location of mkinitramfs working directory. Otherwise error message will appear.

FILE DEST MODE STRIP
FILE
Must be full path to file.
DEST
Must be full path where FILE should be stored. mkinitramfs will automatically create all leading directories if they aren't exist already. Also no need to prepend path of mkinitramfs working directory.
MODE
Permissions in octal format.
STRIP
If was set to , then mkinitramfs will attempt to run strip(1p) on file. mkinitramfs will silently ignore errors if strip doesn't exists or failed to strip binary.

The following functions can be used by hooks in init process:

UUID | LABEL | /dev/* | PARTUUID
Sets variable to full path of resolved UUID, LABEL, /dev/*, or PARTUUID.

The following functions can be used by hooks in both processes (build and init):

MESSAGE
Print message to stdout.
[MESSAGE]
If message was not specified, then mkinitramfs will print default error message. Otherwise, will be printed.

The following variables can be used by hooks in build process:

Full path of mkinitramfs working directory (initramfs rootfs in future).
Kernel version.
Kernel modules directory.
Path to init script.
Path to device-helper script.
Config location.
Output path where initramfs image is stored.

The following variables can be used by hooks in init process:

Breakpoint for debugging.

The following variables can be used by hooks in both processes (build and init):

Equals 1 if debug mode enabled.

See mkinitramfs.config(5) for additional information about available hooks.

This example will show how to handle soft dependencies of ext4 module. Create /etc/mkinitramfs/hooks/ext4 directory and copy below scripts with appropriate names to that directory. After that, prepend ext4 to option in mkinitramfs' config (/etc/mkinitramfs/config).

:
print "Copying ext4 dependencies"

for _mod in crc32c libcrc32c; do
        copy_kmod "$_mod"
done
:
modprobe -a crc32c libcrc32c

mkinitramfs.config(5), mkinitramfs.cmdline(7), mkinitramfs(8)

May 22, 2024 Zeppe-Lin