.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "BOOSTER" "1" "July 2023" ""
.SH "NAME"
\fBbooster\fR \- fast and secure initramfs generator
.SH "DESCRIPTION"
\fBBooster\fR is a tool to create initramfs images needed at the early stage of Linux boot process\. Booster is made with speed and full disk encryption use\-case in mind\.
.P
Booster advantages:
.IP "\[ci]" 4
Fast image build time and fast boot time\.
.IP "\[ci]" 4
Out\-of\-box support for LUKS\-based full disk encryption setup\.
.IP "\[ci]" 4
Clevis style data binding\. The encrypted filesystem can be bound to TPM2 chip or to a network service\. This helps to unlock the drive automatically but only if the TPM2/network service presents\.
.IP "\[ci]" 4
Automatically detects and unlocks systemd\-cryptenroll (fido2 and tpm2) type of partition encryption\.
.IP "\[ci]" 4
Easy to configure\.
.IP "\[ci]" 4
Automatic host configuration discovery\. This helps to create minimalistic images specific for the current host\.
.IP "" 0
.SH "CONFIG FILE"
\fBbooster\fR generator config file is located at \fB/etc/booster\.yaml\fR\. Here is a sample config file:
.IP "" 4
.nf
network:
  interfaces: enp0s31f2,2e:1d:61:30:a3:63
  dhcp: on
  # either dhcp above or static configuration below can be used
  ip: 10\.0\.2\.15/24
  gateway: 10\.0\.2\.255
  dns_servers: 192\.168\.1\.1,8\.8\.8\.8
universal: false
modules: \-*,hid_apple,kernel/sound/usb/,kernel/fs/btrfs/btrfs\.ko,kernel/lib/crc4\.ko\.xz
compression: zstd
mount_timeout: 5m6s
strip: true
extra_files: vim,/usr/share/vim/vim82/,fsck,fsck\.ext4
vconsole: true
enable_lvm: true
enable_mdraid: true
.fi
.IP "" 0
.IP "\[ci]" 4
\fBnetwork\fR node, if present, initializes the network at the boot time\. It is needed if mounting a root fs requires access to the network (e\.g\. in case of Tang binding)\. The network can be either configured dynamically with DHCPv4 or statically within this config\. In the former case \fBdhcp\fR is set to \fBon\fR\. In the latter case the config allows to specify \fBip\fR \- the machine IP address and its network mask, \fBgateway\fR \- default gateway, \fBdns_servers\fR \- comma\-separated list of DNS servers\. The \fBnetwork\fR node also accepts \fBinterfaces\fR property \- a comma\-separated list of network interfaces (specified either with name or MAC address) to enable at the boot time\. Network names like \fBenp0s31f6\fR get resolved to MAC addresses at generation time and then passed to init\. If \fBinterfaces\fR node is not specified then all the interfaces are activated at boot\.
.IP "\[ci]" 4
\fBuniversal\fR is a boolean flag that tells booster to generate a universal image\. By default booster generates a host\-specific image that includes kernel modules used at the current host\. For example if the host does not have a TPM2 chip then tpm modules are ignored\. Universal image includes many kernel modules and tools that might be needed at a broad range of hardware configurations\.
.IP "\[ci]" 4
\fBmodules\fR is a comma\-separated list of extra modules to add to or remove from the generated image\. One can use a module name or a path relative to the modules dir (/usr/lib/modules/$KERNEL_VERSION)\. The compression algorithm suffix (e\.g\. "\.xz", "\.gz) can be omitted from the module filename\. If the element starts with a minus sign (\fB\-\fR) then it means "do not add it to the image", otherwise modules are added\. If the path ends with a slash symbol (/) then it is considered a directory and all modules from this directory need to be added recursively\. A special symbol \fB*\fR (star) means all modules\. It can be used for example to add all modules or remove all predefined modules from the image\. Booster also takes module dependencies into account, all dependencies of the specified modules will be added to the image as well\.
.IP "\[ci]" 4
\fBmodules_force_load\fR list of module names that are forcibly loaded during the boot process before switching into user\-space\. Any module in this list automatically added to the image so there is no need to duplicate it at \fBmodules\fR property\.
.IP "\[ci]" 4
\fBcompression\fR is a flag that specifies compression for the output initramfs file\. Currently supported algorithms are "zstd", "gzip", "xz", "lz4", "none"\. If no option specified then "zstd" is used as a default compression\.
.IP "\[ci]" 4
\fBmount_timeout\fR timeout for waiting for the root filesystem to appear\. The field format is a decimal number and then unit number\. Valid units are "s", "m", "h"\. If no value specified then default timeout (3 minutes) is used\. To disable the timeout completely specify "0s"\.
.IP "\[ci]" 4
\fBstrip\fR is a boolean flag that enables ELF files stripping before adding it to the image\. Binaries, shared libraries and kernel modules are examples of ELF files that get processed with strip UNIX tool\.
.IP
This options is not compatible with signed modules\. If you see \fBbooster: finit(crc32,generic): key was rejected by service\fR boot error please set the \fBstrip\fR config option to \fBfalse\fR\.
.IP "\[ci]" 4
\fBextra_files\fR is a comma\-separated list of extra files to add to the image\. If an item starts with slash ("/") then it is considered an absolute path\. Otherwise it is a path relative to /usr/bin\. If the item is a directory then its content is added recursively\. There are a few special cases:
.IP "\[ci]" 4
adding \fBbusybox\fR to the image enables an emergency shell in case of a panic during the boot process\.
.IP "\[ci]" 4
adding \fBfsck\fR enables boot time filesystem check\. It also requires filesystem specific binary called \fBfsck\.$rootfstype\fR to be added to the image\. Filesystems are corrected automatically and if it fails then boot stops and it is responsibility of the user to fix the root filesystem\.
.IP "" 0

.IP "\[ci]" 4
\fBvconsole\fR is a flag that enables early\-user console configuration\. If it is set to \fBtrue\fR then booster reads configuration from \fB/etc/vconsole\.conf\fR and \fB/etc/locale\.conf\fR and adds required keymap and fonts to the generated image\. The following config properties are taken into account: \fBKEYMAP\fR, \fBKEYMAP_TOGGLE\fR, \fBFONT\fR, \fBFONT_MAP\fR, \fBFONT_UNIMAP\fR\. See also man vconsole\.conf \fIhttps://man\.archlinux\.org/man/vconsole\.conf\.5\.en\fR\.
.IP "\[ci]" 4
\fBenable_lvm\fR is a flag that enables LVM volume assembly at the boot time\. This flag also makes sure all the required modules/binaries are added to the image\.
.IP "\[ci]" 4
\fBenable_mdraid\fR is a flag that enables MdRaid assembly at the boot time\. This flag also makes sure all the required modules/binaries are added to the image\.
.IP "\[ci]" 4
\fBenable_zfs\fR is a flag that enables ZFS filesystem as root filesystem\. This flag also makes sure all the required modules/binaries are added to the image\. Note that if ZFS is enabled then \fBzfs=\fR boot option must be used instead of \fBroot=\fR boot option\.
.IP "" 0
.P
Once you are done modifying your config file and want to regenerate booster images under \fB/boot\fR please use \fB/usr/lib/booster/regenerate_images\fR\. It is a convenience script that performs the same type of image regeneration as if you installed \fBbooster\fR with your package manager\.
.SH "COMMAND\-LINE FLAGS"
.SS "Application Options"
.IP "\[ci]" 4
\fB\-v\fR, \fB\-\-verbose\fR Enable verbose output
.IP "" 0
.SS "SUBCOMMANDS"
.SS "build"
Build initrd image\. Usage: \fBbooster [OPTIONS] build [build\-OPTIONS] output\fR
.IP "\[ci]" 4
\fB\-f\fR, \fB\-\-force\fR Overwrite existing initrd file\.
.IP "\[ci]" 4
\fB\-\-init\-binary\fR <default: \fI/usr/lib/booster/init\fR> Booster \'init\' binary location\.
.IP "\[ci]" 4
\fB\-\-compression\fR <default: \fIzstd\fR> Output file compression\. Possible values: \fIzstd\fR, \fIgzip\fR, \fIxz\fR, \fIlz4\fR, \fInone\fR\.
.IP "\[ci]" 4
\fB\-\-kernel\-version\fR Linux kernel version to generate initramfs for\.
.IP "\[ci]" 4
\fB\-\-config\fR <default: \fI/etc/booster\.yaml\fR> Configuration file path\.
.IP "\[ci]" 4
\fB\-\-universal\fR Add wide range of modules/tools to allow this image boot at different machines\.
.IP "\[ci]" 4
\fB\-\-strip\fR Strip ELF files (binaries, shared libraries and kernel modules) before adding it to the image\.
.IP "" 0
.SS "cat"
Show content of the file inside the image\. Usage: \fBbooster [OPTIONS] cat image file\-in\-image\fR
.SS "ls"
List content of the image\. Usage: \fBbooster [OPTIONS] ls image\fR
.SS "unpack"
Unpack image\. Usage: \fBbooster [OPTIONS] unpack image output\-dir\fR
.SH "BOOT TIME KERNEL PARAMETERS"
Some parts of booster boot functionality can be modified with kernel boot parameters\. These parameters are usually set through bootloader config\. Booster boot uses following kernel parameters:
.IP "\[ci]" 4
\fBroot=$deviceref\fR device reference to root device\. See notes below for how to specify the device reference\. If \fBroot=\fR points to a LUKS partition then it automatically unlocked as a device \fB/dev/mapper/root\fR and mounted to root\. Booster also supports root partition autodiscovery \fIhttps://systemd\.io/DISCOVERABLE_PARTITIONS/\fR \- if no \fBroot=\fR parameter is specified then booster checks for partitions with specific GPT type and uses it to mount as root\.
.IP "\[ci]" 4
\fBrootfstype=$TYPE\fR (e\.g\. rootfstype=ext4)\. By default booster tries to detect the root filesystem type\. But if the autodetection does not work then this kernel parameter is useful\. Also please file a ticket so we can improve the code that detects filetypes\.
.IP "\[ci]" 4
\fBrootflags=$OPTIONS\fR mount options for the root filesystem, e\.g\. rootflags=user_xattr,nobarrier\. In partition autodiscovery mode GPT attribute 60 ("read\-only") is taken into account\.
.IP "\[ci]" 4
\fBrd\.luks\.uuid=$UUID\fR UUID of the LUKS partition where the root partition is enclosed\. booster will try to unlock this LUKS device\.
.IP "\[ci]" 4
\fBrd\.luks\.name=$UUID=$NAME\fR similar to rd\.luks\.uuid parameter but also specifies the name used for the LUKS device opening\.
.IP "\[ci]" 4
\fBrd\.luks\.key=$UUID=$PATH\fR absolute path to a keyfile in the initrd/initramfs which can be used to unlock the device identified by UUID, if this file does not exist or fails to unlock it will fall back to a password request\.
.IP "\[ci]" 4
\fBrd\.luks\.options=opt1,opt2\fR a comma\-separated list of LUKS flags\. Supported options are \fBdiscard\fR, \fBsame\-cpu\-crypt\fR, \fBsubmit\-from\-crypt\-cpus\fR, \fBno\-read\-workqueue\fR, \fBno\-write\-workqueue\fR\. Note that booster also supports LUKS v2 persistent flags stored with the partition metadata\. Any command\-line options are added on top of the persistent flags\.
.IP "\[ci]" 4
\fBrd\.modules_force_load\fR a comma\-separated list of extra kernel modules which should be force loaded\.
.IP "\[ci]" 4
\fBresume=$deviceref\fR device reference to suspend\-to\-disk device\.
.IP "\[ci]" 4
\fBzfs=$pool/$dataset\fR specifies what ZFS dataset needs to be used for root partition\. This option is only used if ZFS config option is enabled\. If ZFS filesystem is enabled then \fBroot=\fR boot param is ignored\.
.IP "\[ci]" 4
\fBbooster\.log\fR configures booster init logging\. It accepts a comma separated list of following values:
.IP
One of the level values (from more verbose to less verbose) \- \fBdebug\fR, \fBinfo\fR, \fBwarning\fR, \fBerror\fR\. If the level is not specified then \fBinfo\fR used by default\.
.IP
\fBconsole\fR \- print booster init logs to console\.
.IP
The debug log is also printed to the kernel kmsg buffer and available for reading either with \fBdmesg\fR or with \fBjournalctl \-b\fR\. If debug level is enabled then kmsg throttling gets disabled automatically\.
.IP "\[ci]" 4
\fBbooster\.debug\fR an obsolete option that is equivalent to \fBbooster\.log=debug,console\fR\.
.IP "\[ci]" 4
\fBquiet\fR Set booster init verbosity to minimum\. This option is ignored if \fBbooster\.debug\fR or \fBbooster\.log\fR is set\.
.IP "\[ci]" 4
\fBinit=$PATH\fR path to user\-space init binary\. If not specified then default value \fB/sbin/init\fR is used\.
.IP "" 0
.SH "NOTES"
.SS "Device Reference"
Device reference is a way to specify a device or partition in kernel parameters\. It is labeled as \fB$deviceref\fR above\. Device reference has one of the following values:
.IP "\[ci]" 4
\fB/dev/XXX\fR path to specific device file, it can be either a path to real device/partition like \fB/dev/sda1\fR, \fB/dev/nvme0n1\fR or path to dm\-mapper virtual device like \fB/dev/mapper/root\fR or \fB/dev/vg_mesos/lv_mesos_containers\fR\.
.IP "\[ci]" 4
\fBUUID=$UUID\fR or \fB/dev/disk/by\-uuid/$UUID\fR references device by its filesystem/LUKS UUID\. See notes about UUID formatting rules below\.
.IP "\[ci]" 4
\fBLABEL=$LABEL\fR or \fB/dev/disk/by\-label/$LABEL\fR references device by its filesystem/LUKS label\.
.IP "\[ci]" 4
\fBPARTUUID=$UUID\fR or \fB/dev/disk/by\-partuuid/$UUID\fR references device by GPT partition UUID\.
.IP "\[ci]" 4
\fBPARTUUID=$UUID/PARTNROFF=$OFFSET\fR references device by $OFFSET from a GPT partition specified by $UUID e\.g\. \fBPARTUUID=fd59d06d\-ffa8\-473b\-94f0\-6584cb2b6665/PARTNROFF=2\fR\.
.IP "\[ci]" 4
\fBPARTLABEL=$LABEL\fR or \fB/dev/disk/by\-partlabel/$LABEL\fR references device by GPT partition label\.
.IP "\[ci]" 4
\fBHWPATH=$PATH\fR or \fB/dev/disk/by\-path/$PATH\fR references device by deterministic hardware path e\.g\. \fBpci\-0000:02:00\.0\-nvme\-1\-part2\fR\.
.IP "\[ci]" 4
\fBWWID=$ID\fR or \fB/dev/disk/by\-id/$ID\fR references device by its wwid e\.g\. \fBnvme\-KXG6AZNV256G_TOSHIBA_40SA13GZF6B1\-part3\fR
.IP "" 0
.SS "UUID parameters"
Boot parameters such as \fBroot=UUID=$UUID\fR and \fBrd\.luks\.uuid=$UUID\fR allow you to specify the block device by its UUID\. The UUID format is \fBxxxxxxxx\-xxxx\-xxxx\-xxxx\-xxxxxxxxxxxx\fR where \fBx\fR is a hexadecimal symbol either in lower of upper case\. UUID parameter can optionally be enclosed with quote symbol \fB"\fR though it is not recommended\. Following examples show correct parameters format: \fBroot=UUID=ac8299a8\-91ce\-4bf6\-a524\-55a62844b787\fR, \fBroot=UUID="ac8299a8\-91ce\-4bf6\-a524\-55a62844b787"\fR (not recommended), \fBrd\.luks\.uuid=ac8299a8\-91ce\-4bf6\-a524\-55a62844b787\fR, \fBrd\.luks\.uuid="ac8299a8\-91ce\-4bf6\-a524\-55a62844b787"\fR (not recommended)\.
.SS "Modules selection"
It is a note to summarize the algorithm that computes what modules are going to end up in the generated booster image\. Initial module list for booster is \fBdefaultModulesList\fR \- a set of predefined hard\-coded modules defined at \fBgenerator\.go\fR\. These are selected modules that most likely cover most system boot needs \- disk, filesystem, keyboard, tpm, ethernet, usb drivers\.
.P
If the \fBuniversal\fR config option is set to false (default value) then so\-called host mode is used\. I\.e\. image is generated with the drivers needed for current host hardware only\. To achieve it booster fetches all currently loaded modules from \fB/sys/module/\fR and computes intersection with the \fBdefaultModulesList\fR\.
.P
Then booster looks at \fBmodules\fR config option, a comma\-separated list of elements\. It iterates over all the elements left\-to\-right\. The host mode filtering rule does not apply to this list of manually specified modules\.
.P
If the element starts with minus sign \fB\-\fR then it removes given modules from the image, otherwise modules are added to the image\.
.P
If the element is a module name then this module is added/removed\. Note that by convention a kernel module name can be computed from its filename by replacing all dashes to underscore, e\.g\. For the module \fBhid\-apple\.ko\.gz\fR name will be \fBhid_apple\fR\.
.P
If the element is a path to the module file relative to \fB/usr/lib/modules/$KERNEL_VERSION\fR then the module is added/removed\. Note that the compression algorithm suffix can be omitted from the module filename\.
.P
If the element ends with the slash symbol \fB/\fR then this element is considered a directory relative to \fB/usr/lib/modules/$KERNEL_VERSION\fR\. Booster goes over this directory recursively and adds/removes the modules to the image\. Minus sign can be used with the directories\.
.P
Star symbol \fB*\fR is a shortcut for "all modules", it can be used to add all modules or remove all modules from the image\.
.P
Next booster moves to the \fBmodules_force_load\fR option that consists of module names to load at the boot time\. All these modules are also added to the image\.
.P
At the final step booster computes dependency graphs between modules and all required dependencies\. For example if a user manually added \fBext4\fR and kernel build system says \fBext\fR module requires \fBmbcache\fR and \fBjbd2\fR then both \fBmbcache\fR and \fBjbd2\fR automatically added to the image\.
.SH "DEBUGGING"
If you have a problem with booster boot tool you can enable debug mode to get more information about what is going on\. Just add \fBbooster\.log=debug,console\fR kernel parameter and booster provide additional logs\.
.SH "EXAMPLES"
Create an initramfs file specific for the current kernel/host\. The output file is booster\.img:
.IP "" 4
.nf
$ booster build booster\.img
.fi
.IP "" 0
.P
Create an universal image with many modules (such as SATA/TPM/NVME/\|\.\|\.\|\. drivers) included:
.IP "" 4
.nf
$ booster build \-\-universal booster\.img
.fi
.IP "" 0
.P
Create an initramfs for kernel version 5\.4\.91\-1\-lts and copy it to /boot/booster\-lts\.img:
.IP "" 4
.nf
$ booster build \-\-kernel\-version 5\.4\.91\-1\-lts /boot/booster\-lts\.img
.fi
.IP "" 0
.P
Here is a \fBsystemd\-boot\fR configuration stored at /boot/loader/entries/booster\.conf\. In this example e122d09e\-87a9\-4b35\-83f7\-2592ef40cefa is a UUID for the LUKS partition and 08684949\-bcbb\-47bb\-1c17\-089aaa59e17e is a UUID for the encrypted filesystem (e\.g\. ext4)\. Please refer to your bootloader documentation for more info about its configuration\.
.IP "" 4
.nf
title Linux with Booster
linux /vmlinuz\-linux
initrd /booster\-linux\.img
options rd\.luks\.uuid=e122d09e\-87a9\-4b35\-83f7\-2592ef40cefa root=UUID=08684949\-bcbb\-47bb\-1c17\-089aaa59e17e rw
.fi
.IP "" 0
.P
Users of the Btrfs filesystem with a system installed on a subvolume should add rootflags corresponding to their entry in /etc/fstab\. In this example 69bc4dd2\-7f6c\-4821\-aa6b\-d80d9c97d470 is a UUID for Btrfs partition, with the system installed on subvolume called root and /etc/fstab looks like this:
.IP "" 4
.nf
UUID=69bc4dd2\-7f6c\-4821\-aa6b\-d80d9c97d470	/         	btrfs     	rw,relatime,autodefrag,compress=zstd:2,space_cache,subvol=root	0 0
.fi
.IP "" 0
.P
So /boot/loader/entries/booster\.conf should looks like this:
.IP "" 4
.nf
title Linux with Booster
linux /vmlinuz\-linux
initrd /booster\-linux\.img
options root=UUID=69bc4dd2\-7f6c\-4821\-aa6b\-d80d9c97d470 rw rootflags=relatime,autodefrag,compress=zstd:2,space_cache,subvol=root
.fi
.IP "" 0
.SH "COPYRIGHT"
Booster is Copyright (C) 2020 Anatol Pomazau \fIhttp://github\.com/anatol\fR
.SH "SEE ALSO"
Project homepage \fIhttps://github\.com/anatol/booster\fR