mkinitcpio - Arch Linux initramfs generation tools

CHANGES WITH v40

        Breaking Change:

        * The build system has moved to meson. This enables configuration
          options for `mkinitcpio` to support build-time features. The
          `Makefile` is still being used for some auxiliary helper scripts.

            To build mkinitcpio:
              meson setup build
              meson compile -C build

            Run test suite:
              meson test -C build

            Install:
              meson install -C build

          See `meson.options` for a list of available options.

        * install/sd-encrypt no longer includes the cryptsetup plugin for
          pkcs11. This has been moved to install/sd-encrypt-opensc.


        New Features:

        * install/sd-verity enables dm-verity support in the initramfs. This
          allows one to specify the dm-verity protected drives to systemd. This
          enables support for authenticated encryption in the initramfs.

        * install/sd-volatile enables support for systemd-volatile in the
          initramfs. This hook replaces the root directory with a volatile
          in-memory file system. This enables stateless systems.

        * install/sd-encrypt-opensc enables support for unlocking LUKS2 volumes
          with the OpenSC PKCS#11 module and CCID driver.

        Changes in mkinitcpio:

        * --moduleroot would previously include the entire module root path into
          the initramfs. This has been fixed.

        * find_module_from_symbol now understands uncompressed kernel modules.

        * UKIs will no longer be outputted as executable files.

        * Now supports the new gzip/zstd-only compression mode 'zstd' introduced
          in Linux 6.13 and onwards.

        * /lib64 and /usr/lib64 is now properly symlinked on loongarch64.

        * A new --nopost flag is implemented to disable running mkinitcpio
          hooks.

        * mkinitcpio will now also look for vmlinux files.

        * add_binary now properly supports filemodes.

        Changes in mkinitcpio.conf:

        * <preset>_cmdline allows the preset to select which
          kernel command line file to be used with the UKI.

        * <preset>_splash allows the preset to select which splash image to be
          used with the UKI.

        * <preset>_kerneldest allows the preset to select the destination
          location for the kernel to boot with.

        Changes in hooks:

        * install/systemd includes the 20-systemd-stub.conf tmpfiles.d
          configuration file to preserve things like the tpm2 pcr public key.

        * install/systemd now supports systemd v258 and onwards.

        * install/systemd supports appending multiple shutdown hooks by placing
          a tmpfiles.d file into the initramfs that writes to the file
          /run/initramfs/mkinitcpio-shutdown.conf.

        * install/systemd now installs the appropriate systemd tmpfiles to
          enable PCR unlocking.

        * install/systemd now includes the services and binaries needed for
          validatefs.

        * install/resume had a bug where SYSTEMD_COLORS=1 would fail the hook as
          escape codes would be emitted.

        * install/filesystems will now omit the mount binaries of several
          filesystems that have no use in the early boot environment.

        * install/kms will now omit checking for privacy screens on kernel
          versions before 5.17.

        * install/block now includes low-level drivers for some pci/usb
          controllers.

        Changes in packaging:

        * The libalpm hooks will now properly trigger a rebuild when
          extramodules change.

        * The default kernel preset files no longer includes the fallback image.

        Contributions from: Andrew J. Hesford, Balakrishnan Balasubramanian,
        Christian Hesse, Christian Heusel, Diego Viola, Dmytro Bagrii,
        Felix Pehla, Felix Yan, Jonas Zinn, Josephine Pfeiffer,
        Luke T. Shumaker, Markus Weippert, Martin Stolpe, Mike Yuan,
        Morten Linderud, Philip H., Tiago de Paula, Vladimir Stoiakin,
        Xiaotian Wu, classabbyamp, cvlc12, kastik, ltsdw, nl6720

        - 2025-11-04

CHANGES WITH v39.2:

        Bugfix release:

        * install/udev: add libkmod.so. Instead of linking against it,
          systemd 256 now uses dlopen to load it which prevents it from being
          detected by add_binary. This is a stop-gap measure until add_binary
          gains support for parsing .note.dlopen.
        * lsinitcpio: fix typo in shopt command option. The issue is harmless,
          but it makes bash complain about it when lsinitcpio is run.
        * install/lvm2: do not show errors when kernel modules for optional LVM
          features are not available. E.g. when a kernel built without those
          modules is used.

        Contributions from: Christian Hesse, Markus Weippert, ltsdw

        – 2024-05-25

CHANGES WITH v39.1:

        Bugfix release:

        * Allow UKI tests to work outside Arch Linux by not relying on an Arch
          Linux specific /usr/share/systemd/bootctl/splash-arch.bmp file.
        * Skip tests using ukify if ukify is not available.
        * Tag tests that fail as root with a "no_root" tag to allow skipping
          them in CIs that run as root. E.g. set the environment variable
          BATS_ARGS="--filter-tags '!no_root'"
        * install/keyboard: revert inclusion of kernel modules from
          kernel/hid/*-hid directories to avoid triggering a kernel bug. The
          availability of i2c-hid* modules in early userspace somehow breaks the
          touchpad on Framework 16 laptops.
        * lsinitcpio: show out-of-tree modules (from the extramodules directory)
          in module list. This was accidentally lost in mkinitcpio v33.
        * functions: make sure to only execute functions when called with the
          run_mkinitcpio_func argument.

        Contributions from: Markus Weippert, Morten Linderud, classabbyamp,
        nl6720

        – 2024-05-13

CHANGES WITH v39:

       Announcement of future breaking changes:

        * The use of global variables for getting the value of cmdline parameters
          is now deprecated. Hook authors should update their hooks to use the
          getarg function instead. See mkinitcpio(8) for more information on
          getarg's usage. In a future release, global variables will no longer be
          assigned for cmdline parameters.

        New Features:

        * ARM zImage is now supported. The relevant code paths have also been
          cleaned up with more code sharing between the main implementation and
          the shell completions.

        * install/acpi_override is a new hook that allows ACPI table upgrades
          and overrides. It will look for `.aml` files in
          `/usr/initcpio/acpi_override/` and `/etc/initcpio/acpi_override/`
          which will be copied to `/kernel/firmware/acpi/` in the early
          uncompressed initramfs.

        Changes in mkinitcpio:

        * Compressed files are now placed in the uncompressed early cpio
          instead of the compressed cpio. This change ensures we are not double
          compressing files.

        * As compressed files are included in the early cpio, module
          decompression has been disabled by default to avoid compressing
          them using a weaker compression and improve boot speed for some
          weak CPUs.

        * MODULES_DECOMPRESS will now also decompress firmware files.

        * The values of arbitrary cmdline arguments can now be retrieved at runtime
          using the getarg function.

        * The default umask is now 022 to ensure files installed with hooks have
          the permission set to 644 by default.

        * gzip is used instead of zstd if the kernel version is below 5.9.

        * `add_all_modules_from_symbol` has been fixed to ensure we are not
          failing if no symbols can be found.

        * `add_file` will now use the source file name if the destination ends
          with a slash.

        * `add_file` now supports copying from file descriptors. This is useful
          for cases where you want to pipe files into the initramfs.

        * `add_file_early` and `add_dir_early` has been added to include files
          into the early CPIO.

        * Include `--no-cmdline` in the help output along with some missing
          options in the shell completion.

        * UKIs will now be created with `ukify` if it is available on the
          system.

        Changes in lsinitcpio:

        * lsinitcpio now supports listing, analyzing and extracting UKIs.

        * It will now provide a count of the number of included modules and
          binaries

        * Fixed a bug where the `[explicit]` marks in the output was lost.

        Changes in hooks:

        * install/resume and install/systemd includes the lzo and lz4 kernel
          modules to support resuming from hibernation when using a hibernation
          image compression algorithm other than the compile-time default.

        * install/keyboard now includes all modules under `kernel/hid/*-hid`
          directories, which may be required by some keyboards.

        * install/keyboard removed a workaround for Linux 3.5.

        * install/base now includes the umount binary. This avoids the
          mismatch where mount was from util-linux, while umount was provided
          by busybox.

        * install/lvm2 now includes the dm-vdo module introduced in Linux 6.9.

        Changes in packaging:

        * The libalpm hook will now rebuild the initramfs when kernel modules
          and firmware files are removed.

        * mkinitcpio-generate-shutdown-ramfs.service has gotten cleanups and
          hardening options enabled. `systemctl soft-reboot` pulls
          shutdown.target so the service is now removed from the mentioned
          target and included into `poweroff.target`, `halt.target`,
          `reboot.target` and `kexec.target`.

        * The distributed tarball now uses xz instead of gzip.

        * The Makefile now prefers to use asciidoctor if available.

        * Presets are now generated when mkinitcpio is installed.

        Contributions from: Bill Auger, Eva Kurchatova, Luke T. Shumaker,
        Markus Weippert, Mike Yuan, Morten Linderud, Onur Ankut, Ron Brown,
        classabbyamp, jay-wilkinson, nl6720

        - 2024-05-03


CHANGES WITH v38.1:

        Bugfix release:

        * Fixed bash completion test on non-i686/x86_64 platforms.
        * install/systemd & install/sd-encrypt: fixed a regression with reading
          library paths when looking up libraries to include in the initramfs.
        * Silenced useless "No such file or directory" messages from realpath
          when looking up firmware directories.
        * Fixed regression where the --generatedir flag was not honored. This
          consequentially fixes mkinitcpio-generate-shutdown-ramfs.service.
        * install/encrypt & install/sd-encrypt will now always include the
          hid-generic module which is required for FIDO tokens. Arch kernels
          previously build hid-generic as a builtin, but have changed it to a
          loadable module now.
        * hooks/encrypt: fixed a regression where cryptdevice and cryptkey
          device paths and crypto cipher containing a colon ":" could no
          longer be escaped with a backslash "\".
        * install/microcode: updated help text to match the hook behaviour. I.e.
          the hook prefers individual microcode files in /lib/firmware/*-ucode/,
          while /boot/*-ucode.img is only used as a fallback.

        Contributions from: Dang Huynh, Guilherme Silva, Markus Weippert,
        Mike Yuan, Morten Linderud, nl6720

        - 2024-03-13

CHANGES WITH v38:

        Announcement of breaking changes:

        * --microcode has been deprecated and replaced by the new microcode hook
          for early loading microcode files.

        New Features:

        * mkinitcpio gained support for generating an early CPIO image. This
          allows early loading of microcode and gives the possibility to create
          an ACPI table upgrade hook in the future. install/microcode is a new
          hook to install early microcode into the early CPIO.

        * lsinitcpio has learned to list the content of the early CPIO image.

        * The systemd, udev, sd-encrypt, lvm2 and mdadm_udev hooks are now
          provided by mkinitcpio. The symlinked `sd-lvm2` and `mdadm` names are
          dropped.

        Changes in mkinitcpio:

        * mkinitcpio will filter out nonexistent firmware directories to
          speed up firmware lookup when adding modules.

        * The output of the UKI generation will now be more quiet by default.
          Less important information, such as temporary file paths, will be
          omitted unless the -v/--verbose flag is used.

        Changes to newly merged hooks:

        * install/lvm2 now includes includes dm-writecache, dm-raid, raid0,
          raid1, raid10, raid456 and dm-integrity kernel modules. This fixes an
          issue where devices are not activated in late userspace (after
          switch root) because pvscan in early userspace (the initramfs phase)
          failed to activate them because of missing kernel modules.
          install/lvm2 will also symlink all thin-provisioning-tools to
          /usr/bin/pdata_tools by searching for symlinks instead of hardcoding
          their file names.

        * install/mdadm_udev now includes the mdmon binary for Intel Matrix
          Storage Manager (IMSM) and the systemd unit mdmon@.service.

        Changes in hooks:

        * hook/resume will now use systemd-hibernate-resume if it is available
          and honor the HibernateLocation EFI variable.

        Changes in packaging:

        * The libalm hook will now check if the _kver variable in a preset
          contains a file path or a kernel version before attempting to copy it
          over to /boot/.

        * The kernel-install hook will now prefix its output with "(mkinitcpio)".

        Contributions from: Christian Hesse, Jan Alexander Steffens, Luke T. Shumaker,
        Mike Yuan, Morten Linderud, Maxim Mikityanskiy, Philip H., Tobias Powalowski,
        cedric cvl, classabbyamp, nl6720

        - 2024-02-28

CHANGES WITH v37.3:

        Bugfix release:

        * Fix file copying when parent directory is a symlink.

        Contributions from: Andrew J. Hesford

        – 2024-01-19

CHANGES WITH v37.2:

        Bugfix release:

        * Fix tests to use system library loading mechanism instead of absolute
          paths.
        * Check if the parent directory is a symlink when adding a file. Add
          the full target directory and create the symlink to avoid placing
          duplicate files in the image thus increasing its size.
        * install/block: quote module names suffixed with "?" to prevent
          interpreting them as file globs.
        * 50-mkinitcpio.install: pass path to kernel image to mkinitcpio to
          avoid issues with a kernel image in a non-standard location.
        * kernel-install: account for upstream changes to the default value of
          KERNEL_INSTALL_UKI_GENERATOR.

        Contributions from: Levente Polyak, Thomas Weißschuh, cvlc12, nl6720

        – 2024-01-15

CHANGES WITH v37.1:

        Bugfix release:

        * The 40-microcode.install kernel-install script was missing from the
        Makefile.

        Contributions from: nl6720, Vladimir Kochnev

        – 2023-12-03

CHANGES WITH v37

        Breaking Change:

        * add_module_from_symbol has been renamed into
          add_all_modules_from_symbol.

        New Features:

        * add_checked_modules_from_symbol imports modules based off on the list
          generated by the autodetect hook. Similar to add_checked_modules.

        Changes in mkinitcpio:

        * Kernel version parser now supports zboot images.

        * /usr/local has been removed from the exported paths.

        * Drop-in configurations in /etc/mkinitcpio.conf.d/ and /etc/cmdline.d/
          can now be symlinks.

        * The kernel-install script was split into two scripts. One processing
          microcode (40-microcode.install) and one script for the assembly
          (50-mkinitcpio.install).

        * mkinitcpio will now to try to accurately detect the UEFI architecture
          during UKI generation.

        * The error message when binaries are not found will now be more
          helpful and include the name of the binary.

        Changes in hooks:

        * install/autodetect will now give up on autodetection if there are
          no modules found, or when encountering an error.

        * install/autodetect will attempt to retry its uevents lookup to try
          and avoid a race condition with udevadm settle.

        * install/consolefont now includes the setfont binary. Meaning the
          console font will now be loaded using the kbd project's setfont
          instead of the busybox's built-in one.

        * install/sd-vconsole now defaults to the 'us' keymap if there are no
          KEYMAP specified in /etc/vconsole.conf.

        * install/keymap and install/sd-vconsole now supports KEYMAP=@kernel in
          /etc/vconsole.conf which preserves the kernel keymap.

        * hook/consolefont now has a hack to ensure the font is changed during
          quiet boot.

        * install/block will now include all PCI controller modules to support
          virtio-blk devices.

        * install/autodetect got several changes that will more accurately try
          to find the correct kernel modules.

        * install/block will now include Linux voltage and current regulator
          modules as some MMC controllers require them.

        * install/sd-vconsole now installs systemd-vconsole-setup.service.

        * install/filesystems now attempts to unconditionally include external
          mount helper binaries needed by some filesystems.

        * install/block has had changes to it module list. This only affects
          unconditionally added modules, autodetect will still include them if
          they are in use.

            Removals:
                * sr_mod
                * firewire-sdp2

            Includes:
                * uas
                * virtio_scsi
                * achi
                * nvme

        Changes in packaging:

        * The libalpm hook has a new path target (usr/lib/firmware/*) to ensure
          the initrd is rebuilt when firmware packages are updated.

        * The libalpm hook will now rebuild the initramfs when there has been
          changes to /usr/src/*/dkms.conf. This is to ensure DKMS modules are
          always updated in the initramfs.

        Contributions from: classabbyamp, cvlc12, Damon Harris, Emil Velikov,
        Evan James, Felix Yan, Gene C, Leo Pham, Maxim Mikityanskiy,
        Morten Linderud, nl6720, solsTiCe d'Hiver, Xiaotian Wu

        - 2023-11-15

CHANGES WITH v36:

        New Features:

        * Kernel command line options can now be read from the drop-in directory
          /etc/cmdline.d/.

        * mkinitcpio can now be configured from the drop-in directory
          /etc/mkinitcpio.conf.d/.

        * Hooks can now use a find_module_from_symbol function to include modules
          based on symbol lookups. This is useful to include all modules that
          provide a given function, instead of including all of them.

        * The --no-cmdline option omits embedding the kernel command line files,
          allowing to pass kernel command line options directly through the boot
          entry. This is practical if you need to retain the ability to edit
          these options, or override them during boot.

        Changes in mkinitcpio:

        * preset_options can now be a bash array.

        * Created UKIs now contain a .uname section in the binary.

        * The VERSION_ID in a UKI osrel section is now suffixed with the
          mkinitcpio preset name (except for "default"). This makes it easier
          to distinguish images generated for different kernels.

        Changes in hooks:

        * A regression was fixed where the busybox init hook did not wait for
          devices to come online before resolving them.

        * run_emergencyhook is a new function that allows running functions
          before the emergency shell is launched.

        Changes in packaging:

        * Split out make install into two new targets.
          install-generator installs the generated scripts from make prepare
          along with kernel-install hooks.  install-hooks installs the alpm
          hooks. install by defaults now runs both of these targets.

        Contributions from: Adam Maroti, Balló György, cvlc12, Joel McBride,
        Markus Weippert, Morten Linderud, nl6720, Yishen Miao

        – 2023-05-26

CHANGES WITH v35.2:

        Bugfix release:

        * install/sd-vconsole: include font map and font unimap files in the
          initramfs.

        * Fix support for adding firmware files that a kernel module specifies
          using glob syntax.

        * Do not show a misleading "Possibly missing firmware for module"
          warning when a firmware file was already added once.

        * install/keymap: make sure keymap file adding works on non-UTF-8
          locales.

        Contributions from: Balló György, nl6720

        – 2023-03-24

CHANGES WITH v35.1:

        Bugfix release:

        * mkinitcpio failed to setup the required files in /dev/fd to support process
          substitution. This resulted in hooks/resume failing to work after a shellcheck
          fix up.

        Contributions from: Morten Linderud

        – 2023-03-19

CHANGES WITH v35:

        New Features:

        * mkinitcpio now has support for post-generation hooks. These can be
          used to act on generated initramfs images such as Secure Boot signing.
          The feature is documented in the mkinitcpio(8) man page.

        Changes in mkinitcpio:

        * Improved code quality of scripts with shellcheck.

        * Replaced hexdump usage with od.

        * The makefile was taught `coverage` which generates a coverage report of
          mkinitcpio.

        * Several improvements on the symlink handling of mkinitcpio.

        * add_binary was taught to check for script interpreters and warns about
          missing interpreters.

        * UKIs are now generated with dynamically allocated section sizes instead
          of the previous hard coded values.

        * xz compression is now always executed in "multithreaded mode" through
          the -T0 switch after the xz utility's recent improvements in reproducibility.

        * Several fixups to improve consistency for msg/error/warning messages.

        * Preset scripts are now documented in the mkinitcpio(8) man page.

        * mkinitcpio will now attempt to more thoroughly clean up its temporary files upon
          exit.

        * Modules included in the initramfs now retain their permissions instead of being
          hard coded to 644.

        * The kernel-install script will now utilize the staging area as expected by
          systemd.

        * The init script now passes file system labels, file system UUIDs, partition
          labels and partition UUIDs directly to the mount and fsck commands instead of
          resolving them.

        Changes in hooks:

        * install/sd-vconsole is now executed inside a subshell to avoid
          affecting the global scope.

        * install/sd-vconsole and install/consolefont now look for zstd compressed fonts.

        Changes in packaging:

        * The installed preset now includes commented-out suggestions for UKI and
          default_options.

        * libalpm/scripts/mkinitcpio will now also delete UKIs when
          uninstalling a kernel.

        Contributions from: Adam Maroti, cedric cvl, ff0x, Florian Eitel,
        Josephine Pfeiffer, Markus Weippert, Michael Kopp, Morten Linderud,
        nl6720, rogueai, Sebastian Wiesner, Tobias Powalowski, Yishen Miao

        – 2023-03-18

CHANGES WITH v34:

        Announcement of future breaking changes:

        * Preset variables *_efi_image are deprecated in favor of *_uki and
          option --uefi is deprecated in favor with --uki. The old variables and
          options still work, but emit a deprecation warning.

        Changes in mkinitcpio:

        * Preserve relativity of symbolic links that reside in the same
          directory as their targets.

        * Fix symbolic link creation and create target files with correct
          permissions.

        * Document add_udev_rule that has been available since v31.

        * Instead of using stat to get the file permissions and install to copy
          it, use cp unless custom permissions are specified. This improves
          overall speed of file additions.

        * Existing test suite is migrated to bats (Bash Automated Testing
          System) and more tests are now available.

        * Ensure /proc/cmdline is read as text and make sure to append a newline
          and NUL to the .cmdline embedded in unified kernel images. This works
          around an issue where /proc/cmdline contains garbage.

        * The kernel-install plugin now supports generating unified kernel
          images.

        * Warn if the interpreter (from the shebang) is missing when adding
          "binaries" that are actually scripts.

        Changes in hooks:

        * hooks/shutdown once again works when /run/initramfs/ already exists in
          the initramfs.

        * install/autodetect looks up modules in the target kernel version
          instead of the currently running one.

        * install/consolefont, install/keymap and install/sd-vconsole now
          declare vconsole.conf supported variables as local to prevent
          conflicts with misconstructed hooks may set these variables globally.

        * install/memdisk uses the add_udev_rule function available since v31.

        Contributions from: Adam Maroti, Christian Hesse, Geert Hendrickx,
        Hector Martin, Morten Linderud, Tcc, Tobias Powalowski, nl6720, rogueai

        – 2022-12-07

CHANGES WITH v33:

        Announcements:

        * Development has moved to the Arch Linux GitLab instance. The new
          URL is https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio

        Changes in mkinitcpio:

        * Introduce DECOMPRESS_MODULES in mkinitcpio.conf. Allows the user to
          toggle if modules should be recompressed during initramfs creation or
          not. Defaults to "yes".

        * Support UKI generation on AArch64.

        * Introduce a new --remove switch which allows mkinitcpio to remove all
          mkinitcpio generated files. Only works together
          with the -p/-P switches currently.

        * In the initramfs the file /etc/os-release, symlinked to
          /etc/initrd-release, is now included. systemd enabled initramfs
          environments might need this file.

        * Supports finding kernel version in gzipped non-x86 kernels.

        * Try to properly resolve symlinks when adding files into the initramfs.

        Changes in hooks:

        * install/fsck now includes the e2fsck binary and symlinks fsck.ext*
          utilities to this binary.

        * install/fsck will no longer attempt to include nonexistent fsck
          helpers.

        * install/kms will attempt to include modules that implement the privacy
          screen feature. Currently the module names are hardcoded.

        Changes in packaging:

        * mkinitcpio-remove and mkinitcpio-install are now unified into a single
          script installed to 'libalpm/scripts/mkinitcpio'.

        Contributions from: 0x7F, Felix Yan, Hugo Osvaldo Barrera,
        Morten Linderud, nl6720, rogueai, Simon Brüggen, Tobias Powalowski

        – 2022-11-20
