Complete Guide: Kernel Configuration for Gentoo

Distribution kernels support every hardware configuration imaginable. They load hundreds of modules you’ll never use. They’re safe, generic, and slow.

Argo OS takes the opposite approach: the kernel supports exactly one computer. Everything else is disabled. The result is faster boot times, smaller attack surface, and a system you actually understand.

This guide covers everything from initial configuration to initramfs generation.

Part 1: Understanding Kernel Configuration Philosophy

Monolithic vs Modular

Distribution kernels: Almost everything is a module (<M>). The kernel is small, but it needs an initramfs to load the modules required to mount the root filesystem.

Argo OS kernel: Hardware we definitely have is built-in (<*>). Optional or rarely-used hardware is a module. Hardware we don’t have is disabled (< >).

Why prefer built-in for essential hardware?

  1. No initramfs dependency for basic boot (though we still use one for snapshots)
  2. Faster boot - no module loading phase for critical drivers
  3. Smaller attack surface - disabled code can’t have bugs
  4. Deterministic behavior - the kernel does the same thing every boot

What You Need to Know About Your Hardware

Before configuring, gather this information:

# CPU model and features
cat /proc/cpuinfo | grep -E "(model name|flags)" | head -5

# PCI devices (graphics, network, storage controllers)
lspci -nn

# USB devices
lsusb

# Block devices and partitions
lsblk

# Current loaded modules (if running another distro)
lsmod | sort

Save this output. You’ll reference it constantly during configuration.

Part 2: Kernel Source Setup

Installing Kernel Sources

# Install Gentoo's patched kernel sources
emerge sys-kernel/gentoo-sources

# Select the version you want to configure
eselect kernel list
eselect kernel set 1  # or whichever version

# Verify symlink
ls -la /usr/src/linux
# Should point to /usr/src/linux-6.x.x-gentoo

Starting Configuration

cd /usr/src/linux

# Option 1: Start fresh (not recommended unless you know what you're doing)
make mrproper
make menuconfig

# Option 2: Start from running kernel's config
zcat /proc/config.gz > .config
make olddefconfig
make menuconfig

# Option 3: Use distribution config as base
make localmodconfig  # Generates config from currently loaded modules
make menuconfig

Recommendation: If switching from another distro, use Option 2 or 3. Starting fresh requires knowing exactly which drivers your hardware needs.

Part 3: Essential Configuration Sections

Processor Type and Features

Processor type and features --->
    Processor family (Haswell)
    [*] Supported processor vendors --->
        [*] Support Intel processors (disable AMD if you're Intel-only)
    < > CPU microcode loading support  # Often better to use early-microcode in initramfs

Setting the correct processor family enables:

  • AVX2 instructions in kernel code
  • AES-NI for cryptography
  • Optimized memory operations

Find your CPU family:

# Check supported march values
gcc -march=native -Q --help=target | grep march

Common families:

  • Haswell - Intel 4th gen (2013-2014)
  • Skylake - Intel 6th-7th gen (2015-2017)
  • Alderlake - Intel 12th gen (2021+)
  • Zen - AMD Ryzen 1000 series
  • Zen3 - AMD Ryzen 5000 series

File Systems

File systems --->
    <*> Btrfs filesystem support  # BUILT-IN - required for boot
    [*]   Btrfs POSIX Access Control Lists
    [*]   Btrfs with integrity check tool compiled in
    <M> The Extended 4 (ext4) filesystem  # Module - for USB drives
    DOS/FAT/EXFAT/NT Filesystems --->
        <*> VFAT (Windows-95) fs support  # Built-in for EFI partition
    Pseudo filesystems --->
        [*] /proc file system support
        [*] sysfs file system support
        [*] Tmpfs virtual memory file system support

Critical: Btrfs MUST be built-in if your root filesystem is Btrfs. If it’s a module, you need an initramfs to load it before mounting root.

Block Devices and Storage

Device Drivers --->
    <*> Block devices --->
        <*> Loopback device support  # For mounting images
    NVME Support --->
        <*> NVM Express block device  # Built-in for NVMe boot drives
    SCSI device support --->
        <*> SCSI device support
        <*> SCSI disk support  # For SATA drives
    <*> Serial ATA and Parallel ATA drivers --->
        <*> AHCI SATA support  # Your SATA controller
        [*] ATA ACPI Support

Graphics

This is hardware-specific. For NVIDIA:

Device Drivers --->
    Graphics support --->
        <*> Direct Rendering Manager --->
            < > Nouveau support  # DISABLE if using proprietary NVIDIA
        Frame buffer Devices --->
            <*> Simple framebuffer support  # For early boot display
        Console display driver support --->
            <*> Framebuffer Console support

Note: The actual NVIDIA drivers are out-of-tree and installed separately via emerge x11-drivers/nvidia-drivers. The kernel just needs to NOT include Nouveau.

Networking

Device Drivers --->
    Network device support --->
        Ethernet driver support --->
            # Find YOUR ethernet controller from lspci
            <*> Intel devices --->
                <*> Intel(R) PRO/1000 Gigabit Ethernet  # Example
        Wireless LAN --->
            # Find YOUR wifi chip from lspci
            <*> Intel Wireless WiFi Next Gen AGN  # Example

Input Devices

Device Drivers --->
    Input device support --->
        <*> Generic input layer
        <*> Event interface
        [*] Keyboards --->
            <*> AT keyboard
        [*] Mice --->
            <*> PS/2 mouse
        <*> Miscellaneous devices --->
            <*> PC Speaker support
    HID support --->
        <*> HID bus support
        <*> Generic HID driver
        <*> USB HID transport layer

Virtualization (Required for Docker)

[*] Virtualization --->
    <*> Kernel-based Virtual Machine (KVM) support
    <*>   KVM for Intel processors support (or AMD)

General setup --->
    [*] Namespaces support --->
        [*] UTS namespace
        [*] IPC namespace
        [*] User namespace
        [*] PID Namespaces
        [*] Network namespace
    [*] Control Group support --->
        [*] Memory controller
        [*] CPU controller
        [*] Cpuset controller
        [*] Block Izar-Orchestrator controller

Docker verification: After building, run:

# Install checker
emerge app-containers/docker
docker info
# Or use the dedicated script
emerge app-containers/gentoo-docker-config
gentoo-docker-config

Part 4: Building the Kernel

cd /usr/src/linux

# Build (parallel jobs = CPU cores)
make -j$(nproc)

# Install modules
make modules_install

# Install kernel
make install
# This copies vmlinuz to /boot/vmlinuz-<version>

# Verify installation
ls /boot/
# Should show: vmlinuz-6.x.x-gentoo, System.map-6.x.x-gentoo, config-6.x.x-gentoo

Part 5: Initramfs with Dracut

Even with a mostly-monolithic kernel, Argo OS uses an initramfs for one critical reason: Btrfs snapshot booting.

To boot into a snapshot, the bootloader tells the kernel to mount a specific subvolume as root. This logic happens in early userspace (initramfs) before the real root is mounted.

Install Dracut

emerge sys-kernel/dracut

Configuration

File: /etc/dracut.conf.d/commander.conf

# Host-only mode: only include drivers for THIS machine
hostonly="yes"
hostonly_cmdline="no"

# Compression
compress="zstd"

# Include Btrfs support
filesystems+=" btrfs "

# NVIDIA drivers for early KMS
add_drivers+=" nvidia nvidia_modeset nvidia_uvm nvidia_drm "

# Include firmware
install_items+=" /lib/firmware/i915/* "  # Intel graphics example

# Enable rescue shell on failure (useful for debugging)
kernel_cmdline="rd.shell rd.debug"

Generate Initramfs

# For current kernel
dracut --force

# For specific version
dracut --force --kver 6.6.65-gentoo

# Verbose mode (to see what's included)
dracut --force -v

Verify Initramfs Contents

# List contents
lsinitrd /boot/initramfs-6.6.65-gentoo.img

# Check for specific driver
lsinitrd /boot/initramfs-6.6.65-gentoo.img | grep nvidia
lsinitrd /boot/initramfs-6.6.65-gentoo.img | grep btrfs

Part 6: Bootloader Integration

GRUB Configuration

# Install GRUB to EFI partition
grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=Gentoo

# Generate configuration
grub-mkconfig -o /boot/grub/grub.cfg

Automatic GRUB Updates

Create a hook that regenerates GRUB config after kernel updates:

File: /etc/kernel/postinst.d/zz-grub

#!/bin/bash
# Regenerate GRUB config after kernel install
grub-mkconfig -o /boot/grub/grub.cfg
chmod +x /etc/kernel/postinst.d/zz-grub

Automatic Initramfs Generation

File: /etc/kernel/postinst.d/50-dracut

#!/bin/bash
# Generate initramfs for new kernel
if [ -x /usr/bin/dracut ]; then
    /usr/bin/dracut --force "/boot/initramfs-${1}.img" "${1}"
fi
chmod +x /etc/kernel/postinst.d/50-dracut

Part 7: Module Rebuild Automation

When you update the kernel, out-of-tree modules (like NVIDIA drivers) must be rebuilt.

The Problem

# After kernel update, before module rebuild:
modprobe nvidia
# Error: Module nvidia not found in /lib/modules/6.6.66-gentoo

# Symptom: Black screen at boot, no graphics

The Solution

File: /etc/kernel/postinst.d/91-module-rebuild

#!/bin/bash
# Rebuild out-of-tree modules after kernel update
emerge @module-rebuild
chmod +x /etc/kernel/postinst.d/91-module-rebuild

Now the complete post-kernel-install sequence is:

  1. Install new kernel (make install)
  2. Rebuild NVIDIA/other modules (@module-rebuild)
  3. Generate initramfs (dracut)
  4. Update GRUB (grub-mkconfig)

Part 8: Troubleshooting

Kernel Panic: VFS Unable to Mount Root

Cause: Root filesystem driver not available at boot time.

Fix: Either build the filesystem driver into the kernel (<*>) or ensure it’s in the initramfs.

# Check if btrfs is built-in
grep CONFIG_BTRFS_FS /usr/src/linux/.config
# Should be: CONFIG_BTRFS_FS=y

# If it's =m, regenerate initramfs
dracut --force

Black Screen After Boot

Possible causes:

  1. NVIDIA module not loaded (rebuild with emerge @module-rebuild)
  2. Nouveau driver conflicting (disable in kernel config)
  3. Missing initramfs NVIDIA modules (add to dracut.conf)

Debug: Add nomodeset to kernel command line to boot with basic graphics, then investigate.

WiFi Not Working

# Check if the driver is loaded
lsmod | grep iwl  # Intel WiFi

# If not, check if it's built as module
grep -i iwlwifi /usr/src/linux/.config

# If module, load it
modprobe iwlwifi

# Check for firmware errors
dmesg | grep -i firmware
# May need to install: emerge sys-kernel/linux-firmware

Quick Reference

# Kernel configuration
make menuconfig         # Configure
make -j$(nproc)        # Build
make modules_install    # Install modules
make install           # Install kernel

# Initramfs
dracut --force         # Generate for current kernel
lsinitrd               # List initramfs contents

# Module management
emerge @module-rebuild  # Rebuild out-of-tree modules
modprobe <module>      # Load module
lsmod                  # List loaded modules

# Verification
zcat /proc/config.gz | grep CONFIG_BTRFS  # Check running kernel config

A properly configured kernel is the foundation of a reliable system. Take the time to understand what each option does, and you’ll never wonder “why doesn’t this work” again.