|Description||Dist-kernel project maintains packages providing for zero-effort kernel install and upgrades|
|IRC channel||#gentoo-dist-kernel (webchat)|
No lead election date set
(and inherited member(s))
The Distribution Kernel project aims to maintain sys-kernel/*-kernel packages. These kernel packages have three goals:
- Covering kernel maintenance wholly within packages (install via emerge, upgrade as part of @world upgrade), without requiring additional actions from the user or resorting to non-portable hacks.
- Providing a default configuration that works for most of diverse systems, for users who are not interested in configuring their own kernel from scratch.
- Supporting different bootloaders and /boot layouts (LILO, GRUB, systemd-boot, EFI stub…) with minimal effort, including deploying self-built kernel binary packages over a fleet of heterogeneous systems.
The following packages are provided:
- sys-kernel/vanilla-kernel (built from source, customizable)
- sys-kernel/gentoo-kernel (built from source, customizable)
- sys-kernel/gentoo-kernel-bin (prebuilt)
The project currently maintains two LTS branches (5.4 and 5.10), plus newer branches that are marked stable at the time. Usually, the last EOL version is also kept for a short time.
Trying it out
If using out-of-source kernel modules like x11-drivers/nvidia-drivers or sys-fs/zfs, add
USE="dist-kernel"to /etc/portage/make.conf for automatic rebuilds!
Simply, either run
emerge -av sys-kernel/gentoo-kernel
emerge -av sys-kernel/gentoo-kernel-bin
depending on your preference for from-source builds or prebuilt binaries. You need to use the non-bin if you wish to customise your config.
For updating the bootloader's configuration files:
- Users of systemd-boot should have the kernel installed automatically into /boot.
- Users of GRUB can enable USE=grub on sys-kernel/installkernel-gentoo to automatically run grub-mkconfig after upgrades
It is possible to use a hook in /etc/kernel/install.d/ to automatically update other bootloaders or run arbitrary commands at the point of kernel installation.
See the AMD64 Handbook for more details.
Signed kernel modules
modules-sign global USE flag can be used to automatically sign the compiled kernel modules. When the flag is enabled the MODULES_SIGN_HASH, MODULES_SIGN_KEY (and optionally MODULES_SIGN_CERT) environment variables can be set to control the used key (or pkcs11 URI) and hashing algorithm (default: SHA512). When MODULES_SIGN_KEY is unset the kernel build system will automatically generate a new key.
As of version 6.4.13 the modules in the pre-built kernel packages (e.g. sys-kernel/gentoo-kernel-bin) are pre-signed though enforcing of valid module signatures is not enabled by default for these kernels. Enforcing can be enabled with the
module.sig_enforce=1 kernel command line argument, or by enabling Secure Boot. For these kernels the key that was used to sign the in-tree modules is not available to sign out-of-tree modules. If enforcing is enabled these must be signed with a different key and the certificate of this key must be added to the kernel's key-chain, see the Signed kernel module support article for more details.
When MODULES_SIGN_KEY is unset the kernel build system generates a new key, this key will end up in any generated binary packages. Binary packages are usually readable by regular users! As a result any user could use the key to sign a potentially malicious file, defeating the whole purpose of signing the modules in the first place.
secureboot global USE flag can be used to automatically sign the generated kernel images for use with Secure Boot. When the flag is enabled the SECUREBOOT_SIGN_KEY and SECUREBOOT_SIGN_CERT must be used to specify which key (or pkcs11 URI) and certificate should be used. When using Secure Boot it is required that the kernel modules are also signed, see the above section for more information on this.
As of version 6.4.13 the kernel image in the pre-built kernel packages (e.g. sys-kernel/gentoo-kernel-bin) is pre-signed. The certificate belonging to this signature can be found in
/usr/src/linux-x.y.z-gentoo-dist/certs/signing_key.x509. As with other kernel packages, this certificate must be accepted by the UEFI firmware or Shim in order to boot with Secure Boot enabled.
To successfully boot with Secure Boot enabled any bootloaders involved in the boot-chain must also be signed. Additionally the firmware must be configured to accept the used certificate, or alternatively Shim can be used as pre-loader.
Modifying kernel configuration
By default, a rather full-featured config is used. These steps are only necessary if a customized configuration is required.
To customize, use the from-source packages sys-kernel/gentoo-kernel or sys-kernel/vanilla-kernel, and not the the
The modern versions of Distribution Kernels support two mechanisms for changing the kernel configuration: savedconfig and/or config snippets.
- Replaces the entire package-provided config with an administrator-supplied config file. This approach is probably a better choice for those desiring to build an entirely custom kernel.
- config snippets
- Uses the /etc/kernel/config.d directory to hold configuration file "snippets" that will be merged on top of the package-provided configuration file. This approach offers a convenient method for use-cases that change some specific config options (I.E. enable or disable a certain feature entirely), but would like to continue receiving new changes from the package-provided config file.
Preparing a modified kernel config
The easiest way to modify the current kernel configuration is to run one the configuration UIs in the kernel build tree. To do that, select a kernel ebuild and run it up to the configure phase. For example:
ebuild /var/db/repos/gentoo/sys-kernel/gentoo-kernel/gentoo-kernel-5.9.8.ebuild configure
* linux-5.9.tar.xz BLAKE2B SHA512 size ;-) ... [ ok ] * genpatches-5.9-8.base.tar.xz BLAKE2B SHA512 size ;-) ... [ ok ] * genpatches-5.9-8.extras.tar.xz BLAKE2B SHA512 size ;-) ... [ ok ] * kernel-x86_64-fedora.config.5.9.2 BLAKE2B SHA512 size ;-) ... [ ok ] * Starting with 5.7.9, Distribution Kernels are switching from Arch * Linux configs to Fedora. Please keep a backup kernel just in case. >>> Unpacking source... >>> Unpacking linux-5.9.tar.xz to /tmp/portage/sys-kernel/gentoo-kernel-5.9.8/work [...] make: Leaving directory '/tmp/portage/sys-kernel/gentoo-kernel-5.9.8/work/modprep' >>> Source configured.
Note the directory used by make. Enter it and run a kernel configuration tool such as nconfig or menuconfig:
After saving changes, the new config will be written to the .config file (in the modprep directory).
To use savedconfig, put the kernel config into an appropriate /etc/portage/savedconfig directory. The filename can either match the package name, or name with version. For example, creating the following file will apply the same configuration anytime a version of the
gentoo-kernel package is emerged:
cp /var/tmp/portage/sys-kernel/gentoo-kernel-5.9.8/work/modprep/.config /etc/portage/savedconfig/sys-kernel/gentoo-kernel
Afterward, enable the
savedconfig USE flag on the relevant kernel package, then re-emerge the package:
echo "sys-kernel/gentoo-kernel savedconfig" >> /etc/portage/package.use
emerge --ask sys-kernel/gentoo-kernel
Note that the default Gentoo kernel configuration will not used if savedconfig has been enabled. When using an outdated configuration file, unset symbols (a.k.a newly added symbols) will take the upstream kernel's default values rather than Gentoo's default configuration. It is important to note there could be differences between the two.
To easily generate .config snippets, run diff --changed-group-format="%>" --unchanged-group-format="" .config.old .config | tee -a /etc/kernel/config.d/my-kernel.config in /var/tmp/portage/sys-kernel/gentoo-kernel-5.9.8/work/modprep.
To use the config.d approach, put a config override file into /etc/kernel/config.d directory. Make sure that the file has .config suffix. All files present in that directory will be merged in lexical order to the default Gentoo config.
# CONFIG_HZ_300 is not set CONFIG_HZ_1000=y CONFIG_HZ=1000
Note that the 'is not set' comments unset options.
Using different option files for different kernel versions or variants is not supported via the config.d configuration method at the moment.
- Bumping kernels — describes the ebuild revision bumping process.