mktirfs - tool for creating a tiny-initramfs image
mktirfs -o outputfile [options] [kernel-version]
The mktirfs script generates an initramfs image that
contains the tiny-initramfs init binary. Invoking mktirfs is
meant for expert users that want to have greater control over their
initramfs image. Typically it would be called from update-tirfs.
Images created with this utility are designed to be very small and
fast, and thus ideal for use cases where the amount of space available in
the boot loader is very low. If no modules and no microcode updates are
included in the image, it will be less than 16 kiB in size. This comes at
the cost of runtime flexibility and supported features of the generated
images. It is not meant to replace traditional initramfs implementations
(such as dracut or initramfs-tools) in the generic case, but
provide a lean alternative for common use cases.
Please read /usr/share/doc/tiny-initramfs-core/README.md
for an overview of the use cases it was designed for and the features it
supports.
- -o,
--output=imagefile
- Where to store the resulting initramfs image. This option must be
specified.
- -m,
--auto-modules=yes/no
- Whether to try to automatically detect which modules are required to mount
the / and /usr file systems and include them in the resulting initramfs
image.
Defaults to yes.
- --include-modules=mod1,mod2,...
- Which modules to directly add to the initramfs image, regardless of the
setting for -m. Dependencies of the modules will be resolved by
mktirfs. This option is useful if the required modules are not
properly detected or one wants to create an image for a different
computer.
By default this list is empty.
- -M,
--microcode=generic/yes/no
- Whether to prepend CPU microcode updates (if installed) to the initramfs
image. Microcode updates may be prepended to the initramfs, and the kernel
will automatically load them at boot time. (This requires the
CONFIG_MICROCODE_EARLY kernel option in conjunction with either
CONFIG_MICROCODE_INTEL or CONFIG_MICROCODE_AMD compiled into
the kernel.) The microcode updates can be found in the (non-free) packages
intel-microcode and amd64-microcode packages.
If the generic setting is specified, all installed
microcode updates will be added to the initramfs image; if yes is
specified only the update for the processor on which mktirfs was
run on will be included.
Microcode updates not being installed (or no microcode updates
for the specific processor being available) is not considered to be an
error and mktirfs will proceed regardless.
Defaults to yes. Is only supported on x86 processors
and will be ignored otherwise.
- -d,
--debug=yes/no
- If set to yes, this option will install a (larger) version of the
init binary into the initramfs image that prints additional debug
messages while booting, and waits 5 seconds after mounting the root file
system before handing control over to the system's init process.
This allows the administrator to debug boot problems with initramfs
images.
Defaults to no.
- kernel-version
- The kernel version for which to generate the initramfs image. This is only
relevant if modules are to be added (either automatically or manually) to
the initramfs image. If no modules are included in the initramfs image,
the resulting image may be used with any kernel that has the drivers
required to mount the root filesystem built in.
By default the version returned by uname -r is
used.
Except for -o and the kernel version, defaults for all the
options may be specified in a configuration file
/etc/tiny-initramfs/tiny-initramfs.conf. This file does not exist by
default, but an example version may be found in
/usr/share/doc/tiny-initramfs-core/tiny-initramfs.conf.example.
Any settings that update-tirfs is to use when calling
mktirfs should be set in that configuration file.
There are no hooks within the initramfs itself, the init
binary is a very small statically linked C program.
However mktirfs supports hooks when it comes to creating
the initramfs image. The overall logic of mktirfs is as follows:
- 1.
- Determine the list of kernel module names (without dependencies) to be
added to the initramfs.
- 2.
- Run start hooks.
- 3.
- Copy init executable, add directories, copy microcode.
- 4.
- Run middle hooks.
- 5.
- Determine dependencies of modules, add all module files.
- 6.
- Create initramfs image.
- 7.
- Run end hooks.
- 8.
- Copy image to its final location.
mktirfs looks for hooks in the
/usr/share/tiny-initramfs/hooks.type and
/etc/tiny-initramfs/hooks.type directories, e.g.
/etc/tiny-initramfs/hooks.start. The directory in /usr/share
is the domain of other Debian packages, while the directory in /etc
is designated for the administrator of the system. Hooks will be called in
alphabetical order, and hooks in /etc will override hooks in
/usr/share. run-parts(8) is used to determine what hooks
should be considered.
Hooks are sourced, not executed, so calling exit in
a hook aborts the creation of the initramfs image. It also allows the hooks
to modify variables that will be interpreted later.
Note that mktirfs uses /bin/sh as the interpreter,
which is dash(1) by default on Debian systems, so not all
bash(1) functionality is available within hooks.
The following shell variables are available from within hooksL
- VERSION
- The kernel version for which the initramfs is built.
- DEBUG
- The value of the -d command line option.
- AUTO_MODULES
- The value of the -m command line option.
- INCLUDE_MODULES
- The value of the --include-modules command line option.
- MICROCODE
- The value of the -M command line option.
- OUTPUT
- The value of the -o command line option. This should not be used,
as mktirfs should only replace it if image creation was
successful.
- image_name
- The temporary file name of the initramfs image that is to be created. Will
be empty except for end hooks.
- initramfs_dir
- The temporary directory that contains the contents of the initramfs image.
Any directories and files placed here will be part of the final initramfs
image.
- early_dir
- The temporary directory that contains the contents of the early part of
the initramfs image. This is used for storing microcode updates for the
CPU, but the kernel also supports other updates here, e.g. updates to ACPI
tables. If this directory is non-empty after the middle hooks an
uncompressed CPIO image of this directory will be prepended to the final
initramfs image by mktirfs. If it is empty (no microcode, no other
early updates), the initramfs image will just contain the compressed CPIO
archive of the initramfs_dir directory.
- modules_list
- The name of the temporary file that contains the list of module names that
will be added to the initramfs image (one line per module name). After the
middle hooks all modules, together with their dependencies, will be
added to the initramfs image, any module options defined in
/etc/modprobe.d for those modules will also be included.
Create a new initramfs image for the current kernel:
mktirfs -o /boot/initrd.img.tiny-$(uname -r)
Create a new initramfs image for a specific kernel:
mktirfs -o /boot/initrd.img.tiny-4.2.0 4.2.0
- /etc/tiny-initramfs/tiny-initramfs.conf
- If present, values in there will be used as defaults for the command line
arguments of mktirfs.
- /usr/share/doc/tiny-initramfs-core/tiny-initramfs.conf.example
- An example configuration file that may be copied to the above
location.
- /usr/share/tiny-initramfs/hooks.start
- /usr/share/tiny-initramfs/hooks.middle
- /usr/share/tiny-initramfs/hooks.end
- If present, hooks created by other Debian packages will be sourced from
these directories.
- /etc/tiny-initramfs/hooks.start
- /etc/tiny-initramfs/hooks.middle
- /etc/tiny-initramfs/hooks.end
- If present, hooks created by the system administrator will be sourced from
thsee directories. Hooks will replace those with the same name as hooks in
/usr/share.
Christian Seiler <christian@iwakd.de>