Kernel Operations Manual

This guide covers Gentoo kernel, module and initramfs maintenance. Running, installed and bootloader-selected versions are three separate states. A successful build does not establish bootability.

Task	Start here
Driver missing	Versions and modules
Install a new kernel	Build to boot chain
New kernel fails to boot	Initramfs and fallback
Tune or profile	Runtime changes

Match versions across layers

Running release, installed files, and source differ

# Read the currently running release
uname -r

# Read the arguments used for this boot
cat /proc/cmdline

Inspect root=, UUID, encryption, and recovery arguments. Editing boot files does not change this running value.

# List releases with installed module trees
ls /lib/modules/

A directory does not prove completeness or a usable boot entry.

# Inspect Gentoo source selections
eselect kernel list

# Resolve the current source symlink
readlink -f /usr/src/linux

Device → driver → module file → logs

# Identify drivers in use and available for PCI devices
lspci -k

For USB use its sysfs/USB tools. Replace MODULE below with the actual kernel module name.

# List currently loaded modules
lsmod

# Locate the module file for the current release
modinfo -F filename MODULE

# Inspect module build compatibility metadata
modinfo -F vermagic MODULE

A match is only one clue; check signatures, symbol versions, and actual load errors in logs.

# Inspect driver probing, firmware, and module errors
journalctl -k -b -n 150 --no-pager

Replace MODULE with the actual driver identified via lspci -k or sysfs. eselect kernel selects a source link, not the running kernel; built-in drivers do not appear in lsmod. Read /proc/config.gz or the matching /boot/config-release, not an unrelated source configuration.

The diagram orders verification items, not runtime boot execution. Match all four to the same target release.

Choose the maintenance path first

Path	Responsibility
gentoo-kernel / gentoo-kernel-bin	Distribution configuration/installkernel integration; verify host drivers, signing and bootloader
gentoo-sources + make	Own .config, build, module install, initramfs and boot entry
genkernel	Automates a workflow using its own versioned options, not dracut flags

Manual build: pin the source directory and save configuration

The following applies only to gentoo-sources + make. Distribution kernel packages use their package workflow. Prepare the source and .config for the target hardware and build as a writable non-root owner.

# Pin and display the target source directory in this shell
ops_ksrc=$(readlink -f /usr/src/linux)
printf "%s\n" "$ops_ksrc"

Verify the intended complete source path. Keep this shell; recheck if source/configuration changes.

# Check that the target configuration exists and is nonempty
test -s "${ops_ksrc:?Set the verified source path}/.config"

Stop on nonzero exit and prepare a suitable configuration first.

# Save pre-update configuration while retaining earlier backups
cp --backup=numbered "${ops_ksrc:?Set the verified source path}/.config" \
  "$ops_ksrc/.config.before-update"

# Update the old configuration for this source tree
make -C "${ops_ksrc:?Set the verified source path}" olddefconfig

New options take defaults. Compare old/new configuration, especially root devices, filesystems, and recovery drivers.

# Review and adjust target hardware configuration interactively
make -C "${ops_ksrc:?Set the verified source path}" menuconfig

Record the target release after a successful build

# Build the target kernel and modules
make -C "${ops_ksrc:?Set the verified source path}" -j"$(nproc)"

-j controls parallel jobs; lower it for limited memory. Resolve every build failure before installing.

# Record the complete release for modules and boot images
make -s -C "${ops_ksrc:?Set the verified source path}" kernelrelease

This need not match uname -r. If it collides with the fallback kernel, adjust the release suffix before installation.

Start with a reviewed .config. olddefconfig supplies defaults for new options; review them. localmodconfig may remove support for disconnected hardware, filesystems or recovery. modules_install/make install write system paths; verify boot/ESP mounts, space and retained fallback first.

Verify target mounts before installation

# Identify the filesystem backing /boot
findmnt --target /boot

--target may show the root filesystem. If /boot must be separate, verify the expected device, not merely nonempty output.

# Check capacity for both new and fallback kernels
df -h /boot

# Install built modules under the target release
sudo make -C "${ops_ksrc:?Set the verified source path}" modules_install

Verify installation; do not assume all external modules are handled automatically.

# Install the kernel through the host’s install integration
sudo make -C "${ops_ksrc:?Set the verified source path}" install

Inspect installkernel configuration/hooks first; they may generate initramfs or boot entries. Check artifacts before repeating work.

# Read and verify the installed target release
ops_release=$(make -s -C "${ops_ksrc:?Set the verified source path}" kernelrelease)
printf "%s\n" "$ops_release"

# Inspect a required module for the new release
modinfo -k "${ops_release:?Set the verified target release}" -F filename MODULE

Use the required loadable driver name. Check configuration separately for built-ins.

# Check external module installation for the target release
dkms status

Skip if no modules use DKMS; installed for a different release is insufficient.

A DKMS installed entry must match the target release. Build/install the specific module with explicit name, version and kernel when needed; check make.log, signing and Secure Boot. Automatic hooks depend on installation integration.

Inspect initramfs and keep a fallback entry

Select the release before inspecting or generating images

# Enter the full release intended for the next boot
read -r ops_release

Enter the actual build output or installed release, not the literal RELEASE. Do not substitute the running uname -r for a newly installed release.

# Confirm the target module directory exists
ls -ld "/lib/modules/${ops_release:?Set the verified target release}"

# Verify the device when using this ESP mount point
findmnt /boot/efi

Replace with the actual ESP path; not all hosts use /boot/efi. Also verify /boot and capacity as above.

# Generate manually only when needed and the output is absent
sudo dracut --kver "${ops_release:?Set the verified target release}" \
  "/boot/initramfs-$ops_release.img"

Skip if an installation hook already generated it. Inspect an existing file rather than immediately adding --force.

# Inspect drivers, firmware, and configuration in the image
lsinitrd "/boot/initramfs-${ops_release:?Set the verified target release}.img"

# List dracut feature modules
lsinitrd -m "/boot/initramfs-${ops_release:?Set the verified target release}.img"

-m lists dracut modules, not all kernel drivers. Verify boot-entry kernel, initramfs, and root arguments match the intended release and disk.

Adapt boot mountpoints to the host. Avoid force for a new image so a known-good one is not overwritten. Host-only images depend on hardware and root layout; include required LUKS/LVM/RAID, drivers and firmware. dracut --add selects dracut modules, --add-drivers kernel drivers; genkernel flags are not interchangeable.

Symptom	Inspect
New kernel absent in menu	Install paths, ESP mount and the actual GRUB/systemd-boot/UKI workflow
Root device missing	Root UUID, initramfs, driver/decryption chain; use temporary rd.debug for evidence
Module format / key rejection	Release, vermagic, signature and boot policy; do not force mismatched modules

Before reboot, retain a selectable fallback and recovery access. After boot, verify uname -r, key devices and services. Do not unload the only remote network driver. Blacklisting chiefly affects alias-based loading; initramfs configuration changes need a rebuilt image.

Runtime settings and profiling

Read runtime parameters for the specific issue

# Check IPv4 forwarding state
sysctl net.ipv4.ip_forward

Relevant to routing/subnet forwarding; do not enable it as a generic performance fix.

# Read the memory reclaim policy parameter
sysctl vm.swappiness

# Check the per-user watch limit
sysctl fs.inotify.max_user_watches

# Inspect parameters supported by the module
modinfo -p MODULE

This lists parameter descriptions, not current values. Inspect /sys/module/MODULE/parameters/ with appropriate access for loaded values.

Performance sampling: define scope and output

# Check perf counting with a simple process
perf stat -- sleep 5

This measures sleep, not the system workload. Replace it with the target program or choose system-wide scope.

# Sample system-wide call stacks for ten seconds
sudo perf record -a -g -o perf-kernel-review.data -- sleep 10

-a is system-wide, -g records stacks, and -o selects output. Use a fresh filename during the symptom. Sampling adds overhead; symbols/unwinding affect results.

# Analyze the recorded sample file
sudo perf report -i perf-kernel-review.data

Inspect functions, processes, and call chains; q exits. A sample hotspot alone is not proof of root cause.

sysctl -w changes current values; persist scoped settings in sysctl.d and verify them. Swappiness is not limited to 0–100 and has no universal desktop optimum. System-wide perf needs permissions and incurs overhead; recording sleep without -a profiles sleep, not the host. Emergency SysRq reboot is not proof of durable writes.

Gentoo kernel configuration · dracut · Kernel admin guide