MKINITRAMFS.CONFIG(5) File Formats Manual MKINITRAMFS.CONFIG(5)

mkinitramfs.config — configuration file for mkinitramfs

/etc/mkinitramfs/config

configuration file is a list of environment variables. Each variable must be written in POSIX way, bashism not allowed.

Example:

key=value

If value contains spaces it must be quoted.

key="value value2"

If value contains special symbols like ‘$’, it must be escaped or quoted using single quotes.

key=\\$value
key='$value'

If line exceeded maximum space on your display and you want to make it more readable, you can concatenate them.

key=value
key="${key}value"

If you want to temporary undefine variable without actually deleting it, you can simply prepend ‘#’.

#key=value

=⟨0 | 1⟩
Monolithic kernel means kernel with builtin modules. If you didn't build kernel yourself, then in most cases you have modular kernel and you don't need to enable this option. To check if you have monolithic you need to check if “/lib/modules/<kernel_version>/modules” exist. If this directory doesn't exist you probably have monolithic kernel which means you need to set monolith to 1.
=⟨0 | 1⟩
Hostonly mode enumerates sysfs(5) and copies only necessary modules instead of copying all modules. Which means that this mode can dramatically reduce initramfs size.

This option will be ignored if monolith was set to 1.

=⟨COMMAND [ARGS ...]⟩
Specify which command will be used to compress initramfs image.

There is a lot of commands you can use, such as:

xz
 
zstd
 
gzip
 
bzip2
 
... and many more ...
 

You can set compression level by specifying “-[0-9]” in .

=⟨UUID | LABEL | /dev/* | PARTUUID⟩
Specify which way mkinitramfs(8) will use to look up root filesystem.

UUID
Lookup device by uuid.
LABEL
Lookup device by label.
/dev/*
Lookup device by full path.
PARTUUID
Lookup device by partition uuid.

You must install utility (available in , , or ) for ability to use UUID, LABEL, PARTUUID.

: only supported in blkid(8).

=⟨TYPE⟩
Explicitly set root filesystem type instead of automatically discovering via /proc/mounts. This option must be specified if you booted from Live CD.
=⟨OPTS⟩
See fstab(5) fourth field.
=⟨FILE ...⟩
Add extra s to image.
=⟨HOOK ...⟩
Hooks provide a flexible way to extend mkinitramfs(8) with custom scripts. .

List of shipped by default hooks:

  1. lvm
  2. luks
  3. smdev
  4. mdev
  5. proc (CONFIG_UEVENT_HELPER)
  6. mdevd
  7. eudev
  8. keymap
  9. resume (resume from hibernation)
  10. systemd-udevd

See below how to use them.

If hook doesn't have options, then it's not yet documented or can be used "as is".

More detailed information and how to write your own hooks described in mkinitramfs.hooks(7).

The hook has the following options:

=⟨TAG⟩
Specify LVM tag which will be used to trigger LVM.

This option will be ignored if lvm_name/lvm_group was specified.

=⟨NAME⟩
Specify LVM name which will be used to trigger LVM.

lvm_group (see below) must be specified.

=⟨GROUP⟩
Specify LVM group which will be used to trigger LVM.
=⟨0 | 1⟩
Include /etc/lvm/lvm.conf in initramfs.
=⟨0 | 1⟩
Pass “issue_discards” to LVM. Useful for SSD's.

The hook has the following options:

=⟨PATH⟩
Specify location to key.

GPG-encrypted key currently not supported.

=⟨NAME⟩
Specify which name will be registered to mapping table after cryptsetup(8) unlocks LUKS root.
=⟨UUID | LABEL | /dev/* | PARTUUID⟩
See root (above) for details.
=⟨PATH⟩
Specify location to detached header.
=⟨0 | 1⟩
Pass “--allow-discards” to cryptsetup(8). Useful for SSD's, but you must know that security will be decreased.

The keymap hook has the following options:

=⟨PATH⟩
Specify location to binary keymap.

Currently, this hook supports loading keymap only via .

not supported.

The resume hook has the following options:

=⟨UUID | LABEL | /dev/* | PARTUUID⟩
Specify which way mkinitramfs(8) will use to look up swap device to resume from hibernation.

See root (above) for argument details.

/etc/mkinitramfs/config
Configuration file for mkinitramfs(8).

Remember, these just examples! ! Your configuration may (and should) differ.

  1. Specify root device and add eudev hook: 
    hooks=eudev
root=/dev/sda1

  2. Specify root device, install monolith kernel (without modules) and add (CONFIG_UEVENT_HELPER) hook. 
    hooks=proc
monolith=1
root=/dev/nvme0n1p1

  3. Specify root device, copy only host modules for modular kernel, compress initramfs image through “gzip -9”, and add hook: 
    hostonly=1
hooks=mdevd
compress="gzip -9"
root=PARTUUID=8e05009d-a1d5-4fdb-b407-b0e79360555c

  4. Specify root device and root filesystem type, add eudev and keymap hooks, and specify keymap path: 
    root_type=f2fs
hooks="eudev keymap"
root=UUID=13bcb7cc-8fe5-4f8e-a1fe-e4b5b336f3ef
keymap_path=/usr/share/bkeymaps/colemak/en-latin9.bmap

  5. LUKS setup: 
    hooks="mdev luks"
root=LABEL=my_root
luks_discard=1
luks_key=/root/key
luks_header=/root/header
luks_root=PARTUUID=35f923c5-083a-4950-a4da-e611d0778121

  6. LUKS/LVM setup: 
    compress="lz4 -9"
hooks="eudev lvm luks"
root=/dev/disk/by-uuid/aa82d7bb-ab2b-4739-935f-fd8a5c9a6cb0
luks_discard=1
luks_root=/dev/sdb2
lvm_config=1
lvm_discard=1
lvm_name=lvm1
lvm_group=lvm_grp2

  7. LUKS setup + resume from hibernation: 
    hostonly=1
compress="gzip --fast"
hooks="eudev luks lvm resume"
root=/dev/mapper/root
root_type=ext4
resume=/dev/mapper/swap
luks_discard=1
luks_name=crypt
luks_root=/dev/sda2

mkinitramfs.cmdline(7), mkinitramfs.hooks(7), mkinitramfs(8)

May 22, 2024 Zeppe-Lin