Changes to dracut kernel module/microcode handling - 17/05/2024 00:00 GMT

Impact
====================

Several changes were made regarding out-of-tree kernel modules, CPU
microcode, and how these are handled in initial RAM file systems
(initramfs) generated by sys-kernel/dracut for distribution kernels.
Depending on the local Dracut and USE flag configuration, some
configuration adjustments may be required as a result of these changes.


Background (the problem)
====================

Previously Dracut implicitly included all out-of-tree kernel modules
it could find. This leads to several problems:
- It unnecessarily increases the size of the initramfs
- It creates a bit of a mess when using distribution kernels, consider
    the following:
        1) Distribution kernel is upgraded
        2) Initramfs for the new kernel is generated, it does not include
            any out-of-tree kernel modules.
        3) Portage triggers rebuild of the out-of-tree kernel modules
        4) If zfs is installed, its rebuild will trigger an initramfs
            re-installation. Otherwise no rebuild is triggered.
    Problem: What is and is not included in the initramfs is now
    ambiguous. It depends on the emerge order of the kernel modules
    when zfs is used. And will completely change if at some later stage
    regeneration of the initramfs is triggered manually via e.g.:
        emerge --config sys-kernel/gentoo-kernel
    As a result, Dracut's "--reproducible" setting is not working. And
    the functionality of the initramfs may change (seemingly) at random.


Background (the fix)
====================

Several things have been changed:
- Out-of-tree kernel modules installed by portage are explicitly omitted
    from the initramfs generated by Dracut by default.
- Packages that install a kernel module for which it might make sense to
    have it in the initramfs, have gained the "initramfs" USE flag. When
    this flag is enabled, Dracut is instructed to include the installed
    kernel modules. Packages for which it is essential that its kernel
    modules are included in the initramfs have this new flag enabled
    by default.
- When distribution kernels are used (USE=dist-kernel), and a module
    that should be in the initramfs is installed (USE=initramfs) the
    initramfs is always re-generated.
- The packages installing CPU microcode (sys-kernel/linux-firmware
    and sys-firmware/intel-microcode) have been adjusted to mirror the
    above changes for out-of-tree kernel modules. Both packages
    have gained the "dist-kernel" USE flag, and the "initramfs" flag is
    now enabled by default. When both flags are enabled, Dracut is
    configured to include the installed microcode in the initramfs, and
    then the initramfs is regenerated. When the "dist-kernel" flag is
    disabled, the "initramfs" flag behaves as it previously did.


User Action Required (Dracut and/or Distribution Kernel users)
====================

Users of sys-kernel/dracut and/or Distribution Kernels should double
check two things:
1) Please ensure that you are *not* globally enabling or disabling
    the "initramfs" USE flag. Enabling it globally might result in an
    unnecessarily large initramfs. Disabling it globally might result
    in missing functionality in the initramfs. Which could lead to boot
    failure if, for example, the zfs module is missing while the root
    partition is a zfs.
2) Any add_drivers, or omit_drivers lines in /etc/dracut.conf or
    /etc/dracut.conf.d/* may override the Dracut configuration snippets
    installed by the kernel module packages in
    /usr/lib/dracut/dracut.conf.d.  Please review your Dracut
    configuration files to ensure that you are not unintentionally
    overriding the settings set by Portage.


User Action Required (other users)
====================

Other users may wish to disable the "initramfs" USE flag on
sys-kernel/linux-firmware and/or sys-firmware/intel-microcode
if they already have other mechanisms in place for updating the CPU
microcode (such as kernel built-in CPU microcode). Users who do not
use sys-kernel/dracut or Distribution Kernels can safely disable
the "initramfs" USE flag globally.


Frequently Asked Questions
====================

A package installing a kernel module I would like in my initramfs has
not gained the "initramfs" USE flag. How do I proceed?

    Please report a new bug on bugs.gentoo.org, requesting that the
    package maintainer consider adding support to the package for
    including the modules in the initramfs. In the meantime you can
    locally override the configuration provided by the package (see
    below). Note though that when distribution kernels are used,
    regeneration of the initramfs must be triggered manually via e.g.:
        emerge --config sys-kernel/gentoo-kernel

How do I override the provided Dracut configuration snippets to
include/exclude a custom list of modules?

    To override the provided configuration snippet, create a new file
    /etc/dracut.conf.d/10-PACKAGENAME.conf, replacing PACKAGENAME with
    the name of the package providing the module. Add to this file:
        omit_drivers+=" my list of drivers to omit "
    and/or
        add_drivers+=" my list of drivers to include "