mktirfs - tool for creating a tiny-initramfs image
-o outputfile [options] [kernel-version]
script generates an initramfs image that contains the
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
) 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.
- 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
By default this list is empty.
- 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
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
- -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.
- 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
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
. This file does not exist by
default, but an example version may be found in
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.
supports hooks when it comes to creating the initramfs
image. The overall logic of mktirfs
is as follows:
- Determine the list of kernel module names (without
dependencies) to be added to the initramfs.
- Run start hooks.
- Copy init executable, add directories, copy
- Run middle hooks.
- Determine dependencies of modules, add all module
- Create initramfs image.
- Run end hooks.
- Copy image to its final location.
looks for hooks in the
. The directory in /usr/share
the domain of other Debian packages, while the directory in /etc
designated for the administrator of the system. Hooks will be called in
alphabetical order, and hooks in /etc
will override hooks in
(8) is used to determine what hooks should
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
as the interpreter, which is
(1) by default on Debian systems, so not all bash
functionality is available within hooks.
The following shell variables are available from within hooksL
- The kernel version for which the initramfs is built.
- The value of the -d command line option.
- The value of the -m command line option.
- The value of the --include-modules command line
- The value of the -M command line option.
- The value of the -o command line option. This should
not be used, as mktirfs should only replace it if image creation
- The temporary file name of the initramfs image that is to
be created. Will be empty except for end hooks.
- 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.
- 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
- 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
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
- If present, values in there will be used as defaults for
the command line arguments of mktirfs.
- An example configuration file that may be copied to the
- If present, hooks created by other Debian packages will be
sourced from these directories.
- 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 <firstname.lastname@example.org>