INITRAMFS-TOOLS(7)

🎀 initramfs-tools 🎀

okay bestie, this is the manual section 7 page from the Linux Programmer's Manual, and it's all about initramfs-tools 🧚 let's get into it 💅

✨ NAME ✨

initramfs-tools is an intro to writing scripts for mkinitramfs 💖

✨ DESCRIPTION ✨

okay so initramfs-tools has one main script and two different sets of subscripts 🫶 they run during different phases of execution. we'll go through each one separately, using an imaginary tool that frobnicates an lvm partition before the root partition gets mounted 🔥

Kernel Command Line

the boot loader picks the root filesystem for the kernel, same as always 👑 the old-school root=/dev/sda1 style device spec still works ✨ if you use a label like root=LABEL=rootPart, the initrd will search every available device for a filesystem with that label and mount it as root 🌸 and root=UUID=uuidnumber mounts the partition with that UUID as root 💜

Standard

• init= "<path to real init>" — the binary that takes over on the root fs once the initramfs scripts are finished 🦋
• initramfs.clear — clears the screen at the very beginning 🧹
• initramfs.runsize — sets the size of the /run tmpfs mount point. you can give it in bytes (suffixes work too) or as a percentage of your physical RAM 🧠 it gets passed as the size mount option to tmpfs. check https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt for the full details 📚 the default is 10% 💅
• root= "<path to blockdevice>" — the device node to mount as the root file system 🌈 the recommended move is to use the UUID, like root=UUID=xxx 🫶
• rootfstype — sets the root file system type 🍓
• roottimeout — sets a timeout in seconds for how long mountroot waits for root to show up ⏰ the default is 30 seconds 🙈
• rootdelay — an alias for roottimeout 🔁
• rootflags — sets the file system mount option string 🎀
• loop= "<path to image>" — a path inside the original root file system that gets loop-mounted and used as the real root file system 🔄
• loopfstype — sets the loop file system type, if that applies 🌸
• loopflags — sets the loop file system mount option string, if that applies 🦋
• nfsroot — can be either auto, which tries to grab the info from DHCP, or a string shaped like NFSSERVER:NFSPATH or NFSSERVER:NFSPATH:NFSOPTS 🌐 use root=/dev/nfs so NFS kicks in 💜 you can look up NFSOPTS in nfs(5) ✨
• ip — tells it how to configure the IP address 🧚 this lets you name a different NFS server than the DHCP server. check Documentation/filesystems/nfsroot.txt in any recent Linux source for the deets 📖 it's an optional parameter for NFS root 🫶
• vlan — tells it to create a VLAN tagged device 🏷️ you can set up one or multiple VLAN tagged devices with the vlan=$name.$id:$parent syntax, e.g. vlan=eth0.1:eth0 ✨ also optional for NFS root 💖
• BOOTIF — a MAC address in pxelinux format, with leading 01- and - as separators 🔥 pxelinux passes along the MAC address of the network card it PXE booted with using this bootarg 🎀
• boot — either local or NFS 👑 this decides which initramfs scripts run, so check the "Subdirectories" section under boot scripts 🧠
• resume — the resume hook tries to autodetect the resume partition and uses the first swap partition as its best guess 🔍 you can set the RESUME variable in /etc/initramfs-tools/conf.d/resume 🌸 the boot variable noresume overrides all of this 🙅‍♀️
• resume_offset — the offset from the partition given by resume= where the swap header of the swap file lives 🦋
• quiet — cuts down the amount of text printed to the console during boot 🤫
• ro — mounts the rootfs read-only 🔒
• rw — mounts the rootfs read-write 🔓
• blacklist — stops specific modules from loading 🚫 use the boot parameter blacklist=module1,module2,module3 💅

Debug

• panic — sets a timeout on panic 😭 panic=<sec> is a documented security feature, since it disables the debug shell 🔐
• debug — generates LOTS of output 📜 it writes a log to /run/initramfs/initramfs.debug. but if you pass it an arbitrary argument, the output goes to the console instead 🖥️ for example, debug=vc 💜
• break — spawns a shell in the initramfs image at the phase you pick (top, modules, premount, mount, mountroot, bottom, init) 🐚 this happens before the matching scripts (see the "Boot scripts" section) or action actually run 🎬 you can list several phases separated by commas 🫶 if you don't pick one, the default is premount 🌷

⚠️ beware: if both panic and break are present, initramfs won't spawn any shells and will reboot instead 💀

• netconsole — loads the netconsole linux modules with the args you choose 📡
• all_generic_ide — loads generic IDE/ATA chipset support on boot 💿

---

✨ SCRIPTS ✨

okay so valid boot and hook script names are made up only of alphabetics, numerics, dashes and underscores 🔤 anything else gets discarded 🗑️ bye bye 👋

Configuration hook scripts

these let you override the user configuration when you really need to 🛠️ for example, forcing busybox to be used instead of klibc utilities 🧰

Hook scripts

these run when an initramfs image gets created, and they are not part of the image itself 🏗️ they can still cause files to be included in the image though 📦 hook scripts run under errexit, so a hook script can abort the mkinitramfs build on errors (anything with exitcode != 0) 🚨

Boot scripts

these are included in the initramfs image and usually run during kernel boot in early user-space, before the root partition gets mounted 🌅

---

✨ CONFIGURATION HOOK SCRIPTS ✨

config hook scripts live in /usr/share/initramfs-tools/conf-hooks.d 📂 mkinitramfs sources them after the config files in /etc and before it runs any hook scripts 🧩 they can override any of the variables documented in initramfs.conf(5), but only do this if it's absolutely necessary 🙏 for example, if a package's boot script needs commands that klibc-utils doesn't provide, it should also install a configuration hook that sets BUSYBOX=y 💜

---

✨ HOOK SCRIPTS ✨

hooks can live in two places: /usr/share/initramfs-tools/hooks and /etc/initramfs-tools/hooks 🏠 they run while the initramfs image is being generated, and they're responsible for pulling in every component the image needs 📦 there are no guarantees about the order the scripts run in, unless you set up the prereqs in your script 🤷‍♀️

🚨 heads up: PREREQ is only honored inside a single directory 🫣 so the scripts in /usr/share/initramfs-tools get ordered by their PREREQ values and run first 🥇 then all the scripts in /etc/initramfs-tools get ordered by their PREREQ values and run 🥈 which means a local script in /etc/initramfs-tools can never run before one from the package in /usr/share/initramfs-tools 😭

if a hook script needs config beyond the exported variables listed further down, it should read its own private config file that lives separately from the /etc/initramfs-tools directory 🔐 it must not read initramfs-tools config files directly 🙅‍♀️

Header

to support prereqs, every script should start with these lines 💅

#!/bin/sh
PREREQ=""
prereqs()
{
     echo "$PREREQ"
}

case $1 in
prereqs)
     prereqs
     exit 0
     ;;
esac

. /usr/share/initramfs-tools/hook-functions
# Begin real processing below this line

for example, if you're writing a new hook script that relies on lvm, change the PREREQ line to PREREQ="lvm" ✨ that way the lvm hook script is guaranteed to run before yours 🫶

Help functions

/usr/share/initramfs-tools/hook-functions has a bunch of functions that handle common hook script tasks 🧰 slay 💅

• manual_add_modules — adds a module (plus any modules it depends on) to the initramfs image 🧩
  • example: manual_add_modules isofs
• add_modules_from_file — reads a file with a list of modules (one per line) and adds them to the initramfs image 📃 the file can have comments (lines starting with #), and you can pass arguments to a module by writing them on the same line as the module name 🎀
  • example: add_modules_from_file /tmp/modlist
• force_load — adds a module (and its dependencies) to the initramfs image AND unconditionally loads it during boot 💪 you can pass arguments to the module by listing them after the module name 🔥
  • example: force_load cdrom debug=1
• copy_modules_dir — copies an entire module directory from /lib/modules/KERNELVERSION/ into the initramfs image 📁
  • example: copy_modules_dir kernel/drivers/ata

Including binaries

if you need to copy an executable or shared library into the initramfs, use something like this 🦋

copy_exec /sbin/mdadm /sbin

mkinitramfs automatically detects which libraries your stuff depends on and copies them in for you 🤖 this means most executables, unless they were compiled with klibc, will pull glibc into the image too 😩 which can bloat it by several hundred kilobytes 💀

✨ BOOT SCRIPTS ✨

okay so boot scripts are basically hook scripts' hype cousin 💖 they live in two places too: /usr/share/initramfs-tools/scripts/ and /etc/initramfs-tools/scripts/. Inside those are a bunch of subdirectories, and each one decides when during boot the scripts get run 🎀

Header

same deal as hook scripts: there's no promise about what order the scripts in one subdirectory (see "Subdirectories" below) run in 🙈 if you want to set an order, you use a similar header as hook scripts:

#!/bin/sh
PREREQ=""
prereqs()
{
     echo "$PREREQ"
}

case $1 in
prereqs)
     prereqs
     exit 0
     ;;
esac

and yes, you tweak PREREQ to list any other scripts in the same subdirectory that need to go first if you need that 🫶

Help functions

there's a bunch of helper functions (mostly for output stuff) that boot scripts get for free, living in /scripts/functions ✨ these are giving toolkit energy:

• log_success_msg — logs a success message 🎉 Example: log_success_msg "Frobnication successful"
• log_failure_msg — logs a failure message 💀 Example: log_failure_msg "Frobnication component froobz missing"
• log_warning_msg — logs a warning message ⚠️ Example: log_warning_msg "Only partial frobnication possible"
• log_begin_msg — logs a message that some processing step has begun 🌸
• log_end_msg — logs a message that some processing step is finished 🦋

Example:

log_begin_msg "Frobnication begun"
# Do something
log_end_msg

• panic — logs an error message and drops you into a shell inside the initramfs image so you can poke around and figure out what went wrong 🙈 Example: panic "Frobnication failed"
• add_mountroot_fail_hook NN-name — Deprecated! this one is now a stub that basically does nothing 💀 it's going to be removed in a future version, so please go remove mountroot failure hooks from your existing packages accordingly 🥺

Subdirectories

both /usr/share/initramfs-tools/scripts and /etc/initramfs-tools/scripts have the following subdirectories, and the name of each one tells you its boot stage 👑

• init-top — the first scripts to run after sysfs and procfs get mounted 🌈 this one also runs the udev hook that fills up the /dev tree (udev keeps running until init-bottom).
• init-premount — runs after the modules from hooks and /etc/initramfs-tools/modules have been loaded 🧚
• local-top OR nfs-top — once these have run, the root device node is expected to be there (local) or the network interface is expected to be usable (NFS) 🔥
• local-block — these scripts get called with the name of a local block device 💜 after they've run, that device node should exist. if the local-top or local-block scripts fail to make the device node you wanted, the local-block scripts will keep getting called periodically to try again, so they're basically persistent 🥹
• local-premount OR nfs-premount — these run after the root device's sanity has been checked (local) or the network interface has been brought up (NFS), but before the actual root fs gets mounted 🌸
• local-bottom OR nfs-bottom — these run after the rootfs has been mounted (local) or the NFS root share has been mounted 🦋
• init-bottom — the very last scripts before procfs and sysfs get moved over to the real rootfs and control gets handed to the init binary (which should now be in the mounted rootfs). udev gets stopped here 🫶

Boot parameters

/conf/param.conf lets boot scripts change the exported variables that are listed at the top of init. just write the new values into it! it gets sourced after a boot script run if it exists ✨

✨ EXAMPLES ✨

Hook script

an example hook script would look something like this (and it would usually go in /etc/initramfs-tools/hooks/frobnicate) 💅

#!/bin/sh
# Example frobnication hook script

PREREQ="lvm"
prereqs()
{
     echo "$PREREQ"
}

case $1 in
prereqs)
     prereqs
     exit 0
     ;;
esac

. /usr/share/initramfs-tools/hook-functions
# Begin real processing below this line

if [ ! -x "/sbin/frobnicate" ]; then
     exit 0
fi

force_load frobnicator interval=10
copy_exec /sbin/frobnicate /sbin
exit 0

Boot script

an example boot script would look something like this (and it would usually go in /etc/initramfs-tools/scripts/local-top/frobnicate) 🧚

#!/bin/sh
# Example frobnication boot script

PREREQ="lvm"
prereqs()
{
     echo "$PREREQ"
}

case $1 in
prereqs)
     prereqs
     exit 0
     ;;
esac

. /scripts/functions
# Begin real processing below this line
if [ ! -x "/sbin/frobnicate" ]; then
     panic "Frobnication executable not found"
fi

if [ ! -e "/dev/mapper/frobb" ]; then
     panic "Frobnication device not found"
fi

log_begin_msg "Starting frobnication"
/sbin/frobnicate "/dev/mapper/frobb" || panic "Frobnication failed"
log_end_msg

exit 0

Exported variables

init sets a bunch of variables for the boot scripts environment 💜

• ROOT — matches the root boot option 👑 advanced boot scripts like cryptsetup or live-initramfs need to play tricks with it. otherwise, leave it alone!
• ROOTDELAY, ROOTFLAGS, ROOTFSTYPE, IP — match the rootdelay, rootflags, rootfstype or ip boot options. Use of ROOTDELAY is deprecated 💀 instead of delaying or polling, you should write a local-block boot script.
• DPKG_ARCH — lets you do arch-specific boot actions 🌈
• blacklist, panic, quiet, resume, noresume, resume_offset — set according to their relevant boot options 🎀
• break — super useful for manual intervention during setup and when you're coding a boot script 🛠️
• REASON — the argument passed to the panic helper function. use it to figure out why you ended up in the initramfs shell 🙈
• init — passes the path to init(8), usually /sbin/init ✨
• readonly — the default for mounting root, and it matches the ro bootarg. it gets overridden by the rw bootarg 🍓
• rootmnt — the path where root gets mounted, usually /root 🦋
• debug — indicates that a debug log is captured for further investigation 🔍

✨ UPDATING THE INITRAMFS FROM ANOTHER PACKAGE ✨

okay this part is important, bestie 🚨 package maintainer scripts should not run update-initramfs directly 🙅‍♀️ instead, a package that installs hooks for initramfs-tools should ship a triggers file containing:

activate-noawait update-initramfs

kernel packages have their own rules: they must call the kernel hooks as documented in the Debian Kernel Handbook 📖

and a package that needs an initramfs to function, but isn't a kernel package, should ship a triggers file containing:

activate-await update-initramfs

✨ KERNEL HOOKS ✨

initramfs-tools comes with hook scripts that kernel packages call on installation and removal, so the initramfs gets created, updated or deleted automatically when needed 🤖 the hook scripts do nothing if the environment variable INITRD is set to No. that happens for kernel packages built with make deb-pkg (with CONFIG_BLK_DEV_INITRD not set in the kernel config), or built with make-kpkg without using the --initrd option 🙈

✨ DEBUG ✨

it's super easy to peek inside the generated initramfs and check what's in it 👀 you might want to double-check that it has the binaries, libs or modules you need:

lsinitramfs /boot/initrd.img-3.16-3-amd64

✨ FILES ✨

• /run/initramfs/fsck.log — log of the fsck commands run inside the initramfs, with their output 📜
• /run/initramfs/fsck-root — only exists if fsck ran successfully on the root filesystem ✅
• /run/initramfs/fsck-usr — only exists if fsck ran successfully on the /usr filesystem ✅

✨ AUTHOR ✨

the initramfs-tools were written by Maximilian Attems <maks@debian.org>, Jeff Bailey <jbailey@raspberryginger.com> and numerous others 🫶

this manual was written by David Härdeman <david@hardeman.nu>, and updated by Maximilian Attems <maks@debian.org> 💜

✨ SEE ALSO ✨

go check out these bestie-approved references 👑 initramfs.conf(5), mkinitramfs(8), update-initramfs(8), lsinitramfs(8) 🌈

---

📜 that's a wrap! this page comes from initramfs-tools, dated 2018/07/18, and it's INITRAMFS-TOOLS(7) 💖 go forth and frobnicate responsibly, periodt 💅✨