Penguin Pages

Penguin Pages is built as a plain static website with separate HTML, CSS, and JavaScript files. The goal is to keep it readable, fast, easy to host, and easy to edit without needing a build system.

The design follows an old Linux documentation mirror style: simple boxes, small text, practical links, and direct reference material.

• Keep the site lightweight and static.
• Use real project links and official documentation where possible.
• Keep tabs organized by Linux topic.
• Keep the style consistent with early Linux reference pages.
• Avoid unnecessary frameworks, tracking, and heavy page effects.

Start with the boot parameters and virtual filesystems, then move to modules and logs. Most kernel troubleshooting begins with dmesg, /proc/cmdline, loaded modules, and the exact hardware or filesystem involved.

• docs.kernel.org - current rendered kernel documentation.
• kernel.org documentation index - documentation mirrored from kernel source.
• git.kernel.org - official kernel git browser.
• Bootlin Elixir - searchable Linux source browser.

# list loaded modules
lsmod

# inspect a module
modinfo i915

# load and unload manually
sudo modprobe loop
sudo modprobe -r loop

# show kernel ring buffer
sudo dmesg -T
                

# clone mainline from kernel.org
git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
cd linux

# or clone the GitHub mirror
git clone https://github.com/torvalds/linux.git
cd linux

# check current version
make kernelversion
                

# start from the running distro kernel config
cp /boot/config-$(uname -r) .config

# update config for the new tree
make olddefconfig

# optional terminal config menu
make menuconfig

# build kernel and modules
make -j$(nproc)

# install modules and kernel
sudo make modules_install
sudo make install
                

Many distributions handle bootloader updates differently. Keep an older working kernel in your boot menu.

# apply a patch
patch -p1 < ../some-kernel.patch

# inspect changes
git diff

# build after patching
make olddefconfig
make -j$(nproc)
                

For serious kernel work, use git branches, keep patches small, and read the kernel development process documentation.

Work in order. Check firmware entries, bootloader config, kernel files, initramfs contents, root filesystem UUIDs, and service logs. Random reinstalling usually hides the real problem.

# from a live USB, adjust partitions first
sudo mount /dev/nvme0n1p2 /mnt
sudo mount /dev/nvme0n1p1 /mnt/boot/efi
sudo mount --bind /dev /mnt/dev
sudo mount --bind /proc /mnt/proc
sudo mount --bind /sys /mnt/sys
sudo chroot /mnt

# example GRUB EFI reinstall
grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=Linux
grub-mkconfig -o /boot/grub/grub.cfg
                

Before editing config files, collect basic facts: what changed, which service failed, which log mentions it, which package owns the file, and whether the problem happens for a fresh user account.

Prefer commands that show state before commands that change state. Read with lsblk , findmnt , ip , ss , journalctl , and systemctl status before editing files or restarting services.

Use a source browser first, then clone the tree later. Follow one subsystem at a time. For example, a filesystem path usually touches fs/ , headers in include/ , and shared code in kernel/ or mm/ .

# configure
make menuconfig

# build with all cores
make -j$(nproc)

# install modules and kernel
sudo make modules_install
sudo make install

# update bootloader if your distro does not do it automatically
sudo grub-mkconfig -o /boot/grub/grub.cfg
                

First identify the GPU, kernel driver, session type, and userspace graphics libraries. Most desktop issues make more sense after checking whether the session is X11 or Wayland and whether hardware acceleration is active.

Choose a desktop environment when you want a complete session with panels, settings, file manager integration, portals, notifications, and login polish. Choose a window manager when you want a smaller, keyboard-focused setup and are willing to assemble more pieces yourself.

A window manager draws and arranges windows; it is not automatically a complete desktop. Plan for a terminal, launcher, notifications, policy-authentication agent, screen locker, clipboard, file manager, network and audio controls, wallpaper/output tools, and an xdg-desktop-portal backend. Wayland compositors may provide display and input configuration themselves, while X11 sessions commonly use separate tools.

For a normal install, ext4 is the quiet dependable choice. Btrfs is useful for snapshots and compression. XFS is strong for large files and server workloads. ZFS is excellent when storage integrity and pools matter more than being built into the mainline kernel.

Service management is mostly dependency order, supervision, logging, and failure handling. Learn how your init system starts services, where it stores service definitions, and how to inspect logs for the current boot.

systemctl status sshd
journalctl -u sshd -b
rc-service sshd status
sv status /var/service/*
s6-rc -a list
dinitctl list
                

Patch regularly, expose fewer services, use SSH keys, limit sudo access, check listening ports, and know where authentication logs are stored. Security starts with fewer surprises.

Start at the bottom. Confirm the card exists with ALSA, then check the desktop sound server, then check the session manager and selected output device. Many audio problems are routing problems, not driver problems.

aplay -l
alsamixer
pactl info
wpctl status
pw-top
systemctl --user status pipewire wireplumber pipewire-pulse
                

Use a container when you want isolated userspace on the same kernel. Use a virtual machine when you need a separate kernel, stronger machine boundaries, firmware testing, or another operating system entirely.

sudo chroot /mnt
machinectl list
podman ps
docker ps
lxc-ls --fancy
virsh list --all
qemu-system-x86_64 --version
                

Observe, isolate, test, document. Avoid changing five things at once. A fix you cannot explain is hard to trust and harder to repeat.

This glossary is for quick orientation while reading the rest of the site. It keeps definitions short so you can get back to the command output, manual page, or source file you were looking at.

Use one primary GPU profile first. Hybrid laptops are a deliberate combination, not a reason to enable every driver globally.

• It is source-based. Many installs are real builds, not quick binary downloads.
• It uses Paludis and cave, not Portage/emerge.
• Package options are explicit. A small option change can cause same-version rebuilds.
• Package names are not always Gentoo names. Search instead of guessing.
• It expects you to understand boot, kernel, options, services, and config protection.
• It rewards notes, patience, and checking one layer at a time.

1. Boot a live Linux system with network access.
2. Partition the disk: EFI System Partition, root, optional home, optional swap.
3. Format and mount the filesystems under /mnt/exherbo.
4. Download and extract the Exherbo stage tarball.
5. Write /etc/fstab.
6. Bind mount /dev, /sys, and /proc, then chroot.
7. Configure Paludis, sync repositories, and set desktop options.
8. Build or install a kernel, initramfs, firmware, and bootloader.
9. Create the system identity, root password, normal user, locale, timezone, networking, and privilege policy.
10. Choose a console, desktop, or window-manager profile and only its required services.
11. Choose the matching GPU kernel driver, firmware, Mesa or vendor userspace, and portal stack.
12. Keep a known-good kernel and boot into the simpler session first if a new Wayland setup is questionable.
13. Audit the system before calling it daily-drivable.

This mirrors a practical desktop layout: FAT32 ESP mounted at /boot, ext4 root, and swap. Adjust device names before running anything.

# example only; replace disk and partition names
lsblk -f
sudo cfdisk /dev/nvme0n1

# suggested layout
# p1  EFI System  1G-2G    vfat    /boot
# p2  swap        4G-16G   swap    none
# p3  Linux root  rest     ext4    /

sudo mkfs.vfat -F32 /dev/nvme0n1p1
sudo mkswap /dev/nvme0n1p2
sudo mkfs.ext4 -L exherbo-root /dev/nvme0n1p3

sudo mkdir -p /mnt/exherbo
sudo mount /dev/nvme0n1p3 /mnt/exherbo
sudo mkdir -p /mnt/exherbo/boot
sudo mount /dev/nvme0n1p1 /mnt/exherbo/boot
sudo swapon /dev/nvme0n1p2
                

# get UUIDs
blkid

# /mnt/exherbo/etc/fstab
UUID=<root-uuid>  /      ext4  defaults,noatime  0 1
UUID=<esp-uuid>   /boot  vfat  defaults           0 2
UUID=<swap-uuid>  none   swap  sw                 0 0
                

Use UUIDs, not moving names like /dev/sda, especially on multi-boot machines.

On the live system, confirm the architecture, clock, network, boot mode, and stage integrity before extraction. Obtain the checksum or signature from the official stage source rather than trusting a copied value.

uname -m
date -u
ip route
test -d /sys/firmware/efi && echo UEFI || echo BIOS

cd /mnt/exherbo

# use the current stage URL from the official install guide
sudo curl -O https://stages.exherbo.org/x86_64-pc-linux-gnu/exherbo-x86_64-pc-linux-gnu-gcc-current.tar.xz
# Save the separately obtained official checksum as stage.sha256, then verify it.
sha256sum -c stage.sha256
sudo tar xJpf exherbo-x86_64-pc-linux-gnu-gcc-current.tar.xz

sudo mount -o rbind /dev /mnt/exherbo/dev
sudo mount --make-rslave /mnt/exherbo/dev
sudo mount -o rbind /sys /mnt/exherbo/sys
sudo mount --make-rslave /mnt/exherbo/sys
sudo mount -t proc none /mnt/exherbo/proc

# Do not follow a resolver symlink from the target into a nonexistent /run path.
readlink -f /etc/resolv.conf
sudo rm -f /mnt/exherbo/etc/resolv.conf
sudo cp -L /etc/resolv.conf /mnt/exherbo/etc/resolv.conf

sudo env -i TERM="$TERM" SHELL=/bin/bash HOME=/root chroot /mnt/exherbo /bin/bash
source /etc/profile
export PS1="(exherbo chroot) $PS1"
                

The rbind on /dev matters. Paludis and device-heavy builds can behave badly if the chroot is mounted lazily.

Run this part inside the chroot as root. Exact locale and administrative groups are policy choices; inspect the files and installed tools instead of assuming another distribution's defaults.

# identity and time
printf '%s\n' exherbo-host > /etc/hostname
ln -sf /usr/share/zoneinfo/Region/City /etc/localtime
printf '%s\n' '127.0.0.1 localhost' '127.0.1.1 exherbo-host' > /etc/hosts

# inspect available locales and configure the one you actually use
locale -a
locale

# credentials; use the user-management tools supplied by the stage
passwd
useradd -m -s /bin/bash alice
passwd alice
id alice
                

Install and configure either sudo or doas, then test it from a second root shell before closing the first. Add only the groups required by installed software; modern logind, udev, and polkit setups usually do not require broad legacy groups for ordinary desktop access.

Firmware is required by many AMD GPUs, Wi-Fi adapters, Bluetooth controllers, and Intel audio DSPs. CPU microcode is separate and should be loaded early. Package categories and split packages can change, so locate them rather than guessing.

cave search firmware
cave search microcode
cave show category/firmware-package

# after installation and reboot
journalctl -b -k | grep -iE 'firmware|microcode|amdgpu|radeon|iwlwifi|rtw|ath|sof'
dmesg | grep -i 'failed to load'
                

Start with shared session and input requirements, then add exactly one graphics snippet from the next table. Keep global options small; do not enable every attractive option or copy hardware settings from an unrelated machine.

# /etc/paludis/options.conf

# Add only the session features in use.
# */* X          # X.Org or Xwayland
# */* wayland    # Wayland compositor/toolkit support

# Build behavior
*/* build_options: symbols=split jobs=8 -dwarf_compress -recommended_tests -trace work=tidyup

# Input stack
*/* input_devices: libinput

# KDE shutdown/reboot/unlock helpers
sys-apps/systemd polkit

# EFI GRUB
sys-boot/grub efi GRUB_PLATFORMS: efi-64 pc

# Archive support
app-arch/libarchive zstd

# KDE profile additions: omit or replace for another desktop
# Qt5 tooling for older KDE/theme packages
x11-libs/qtbase:5 sql sqlite

# KDE image and QR support
kde-frameworks/prison scanner pdf417
kde-frameworks/kimageformats avif

# Flatpak and portals
# This avoids the Qt6 libportal private-header trap seen on some Exherbo setups.
sys-libs/libportal PROVIDERS: gtk3 -gtk4 -qt5 -qt6

# Audio integration
media-sound/pulseaudio bluetooth
sys-sound/alsa-plugins pulseaudio
media-libs/libcanberra pulseaudio

# Bluetooth desktop integration
net-wireless/bluez obex

# GTK, tray, and device integration
dev-libs/at-spi2-core gobject-introspection
x11-libs/gtk+:3 gobject-introspection
core/json-glib gobject-introspection
dev-libs/libgusb gobject-introspection

# Optional UI polish
app-misc/fastfetch X wayland opengl vulkan libdrm dbus
kde/kinfocenter usb
                

If cave resolve world shows only same-version r rebuilds after editing options, that usually means option drift, not corruption. It wants to rebuild packages so their recorded build options match the current file.

# Confirm names and available choices on this repository snapshot.
cave show x11-dri/mesa
cave search vulkan
cave resolve world
                

Paludis option names are repository metadata, not universal constants. If a listed token is unavailable, use the choices shown by cave show. Hardware detection comes first: lspci -nnk | grep -A3 -E 'VGA|3D|Display'.

cave resolve --execute \
  kde/plasma-desktop \
  kde/plasma-workspace \
  kde/kwin \
  kde/kwin-x11 \
  kde/systemsettings \
  kde/dolphin \
  kde/konsole \
  kde/kate \
  kde/ark \
  kde/gwenview \
  kde/kcalc \
  kde/spectacle \
  kde/okular \
  kde/kfind \
  kde/kmenuedit \
  kde/kdebugsettings \
  kde/kinfocenter \
  kde/kio-extras \
  kde/kio-admin \
  kde/kio-fuse \
  kde/ffmpegthumbs \
  kde/kdegraphics-thumbnailers \
  kde/breeze \
  kde/qqc2-breeze-style \
  kde/kde-gtk-config \
  kde/plasma-workspace-wallpapers \
  kde/ocean-sound-theme \
  kde/plasma-systemmonitor \
  kde/ksystemstats \
  kde/filelight \
  kde/colord-kde \
  kde/plasma-disks \
  kde/partitionmanager \
  kde/plasma-nm \
  kde/plasma-pa \
  kde/powerdevil \
  kde/kscreen \
  kde/sddm-kcm \
  kde/flatpak-kcm
                

Use cave search if any package name fails. Exherbo package names can move, slots matter, and repositories differ.

cave resolve --execute \
  sys-auth/sddm \
  net-apps/NetworkManager \
  sys-apps/power-profiles-daemon \
  sys-apps/upower \
  net-wireless/bluez \
  media/pipewire \
  sys-apps/xdg-desktop-portal \
  kde/xdg-desktop-portal-kde \
  sys-apps/flatpak \
  sys-apps/xdg-dbus-proxy \
  sys-libs/libportal \
  x11-server/xwayland \
  x11-libs/qtwayland \
  fonts/noto \
  fonts/noto-emoji \
  fonts/dejavu \
  fonts/liberation-fonts \
  x11-apps/xdg-user-dirs
                

Package sets vary across repositories. Search for the desktop, inspect its set or core package, preview the plan, and then add the integration pieces appropriate to that session.

cave search gnome        # substitute xfce, lxqt, i3, sway, etc.
cave show category/candidate-package-or-set
cave resolve category/candidate-package-or-set

# A display manager is optional. Inspect installed sessions:
find /usr/share/xsessions /usr/share/wayland-sessions -maxdepth 1 -type f 2>/dev/null
                

Choose portal backends for the active desktop and inspect which interfaces each provides. Some combinations are intentional: for example, a wlroots screen-capture backend may coexist with GTK for file choosing. Unplanned competing backends can still cause slow startup or the wrong chooser.

Enable only services installed for the chosen profile. A console server does not need SDDM, Bluetooth, or desktop power management; GNOME commonly uses GDM instead of SDDM.

systemctl enable sddm
systemctl enable NetworkManager
systemctl enable power-profiles-daemon
systemctl enable upower
systemctl enable bluetooth
systemctl enable systemd-timesyncd

# dbus and polkit are usually static/activation based; status matters more than enable
systemctl status dbus polkit --no-pager
                

NetworkManager is a convenient desktop default. A small server may instead use systemd-networkd or another deliberate stack. Do not run multiple DHCP clients or resolver managers on the same interface.

# identify the device, driver, radio state, address, route, then DNS
ip -br link
lspci -nnk | grep -A3 -iE 'ethernet|network'
rfkill list
ip -br address
ip route
resolvectl status 2>/dev/null || cat /etc/resolv.conf

# NetworkManager examples after its service is running
nmcli device status
nmcli device wifi list
nmcli device wifi connect 'SSID' --ask
nmcli connection show

# separate routing from DNS failures
ping -c 3 1.1.1.1
getent hosts exherbo.org
                

For a remote/headless first boot, install an SSH server, add a tested public key, verify the firewall and service from the local console, and only then rely on remote access. Never expose password-based root SSH as a shortcut around user setup.

Inside an installation chroot, uname -r reports the live medium's kernel. Derive the target version from the kernel you built and use that same value for modules, initramfs, and bootloader checks.

# Before using the commands below, locate and install the required tools.
cave search dracut
cave search grub
cave search efibootmgr
cave resolve category/dracut-package category/grub-package category/efibootmgr-package
cave resolve --execute category/dracut-package category/grub-package category/efibootmgr-package
                

cd /usr/src/linux
make menuconfig
make -j"$(nproc)"

# Record the target kernel version before installing it.
KVER="$(make -s kernelrelease)"
make modules_install
install -Dm755 arch/x86/boot/bzImage "/boot/vmlinuz-${KVER}"
depmod "$KVER"
dracut --force "/boot/initramfs-${KVER}.img" "$KVER"

test -s "/boot/vmlinuz-${KVER}"
test -s "/boot/initramfs-${KVER}.img"
test -d "/lib/modules/${KVER}"
                

The worked layout mounts the EFI System Partition at /boot. With efivarfs available and the machine booted in UEFI mode, install GRUB once, then regenerate its configuration after kernel changes.

test -d /sys/firmware/efi/efivars
findmnt /boot
grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id=Exherbo
grub-mkconfig -o /boot/grub/grub.cfg
efibootmgr -v
grep -nE 'vmlinuz|initramfs' /boot/grub/grub.cfg
                

If modprobe fuse says the module does not exist and Flatpak complains, build it from the same kernel tree used for the running kernel.

cd /usr/src/linux

./scripts/config --module FUSE_FS
./scripts/config --module CUSE
./scripts/config --disable FUSE_PASSTHROUGH
./scripts/config --disable FUSE_IO_URING
./scripts/config --disable FUSE_DAX

make olddefconfig
make -j"$(nproc)" fs/fuse/fuse.ko fs/fuse/cuse.ko
sudo make M=fs/fuse modules_install

KVER="$(uname -r)"
sudo depmod "$KVER"
sudo modprobe fuse
ls -lah /dev/fuse
                

If FUSE passthrough causes undefined symbols while building only the module, disable passthrough/io_uring unless you are intentionally wiring those dependencies.

Open drivers normally use kernel DRM plus Mesa. They do not use nvidia-smi, NVIDIA module parameters, or a nouveau blacklist. Get a working KMS console first, then confirm rendering, Vulkan if needed, and the desktop session.

lspci -nnk | grep -A3 -E 'VGA|3D|Display'
lsmod | grep -E 'amdgpu|radeon|i915|xe|nouveau|virtio_gpu'
journalctl -b -k | grep -iE 'drm|amdgpu|radeon|i915|xe|nouveau|virtio|firmware'
glxinfo -B
vulkaninfo --summary
                

For video decode, inspect the available VA-API/VDPAU packages and test with vainfo. Hardware rendering and hardware video decode are related but separate paths.

Keep the integrated GPU as the display device first, verify both drivers independently, then configure render offload for selected applications. Do not blacklist the integrated driver or force every application onto the discrete GPU.

lspci -nnk | grep -A3 -E 'VGA|3D|Display'
loginctl show-session "$XDG_SESSION_ID" -p Type -p Desktop
glxinfo -B

# Mesa render-offload example; verify the discrete renderer in the output
DRI_PRIME=1 glxinfo -B
                

Proprietary NVIDIA offload uses vendor-specific environment variables and matching userspace libraries. Confirm the current driver documentation, external-monitor wiring, and suspend behavior before enabling aggressive dGPU power management.

The practical NVIDIA rule: kernel modules, userspace libraries, EGL/Wayland pieces, GRUB flags, modprobe config, initramfs, and KWin must all agree. Mixing a half-installed driver stack is how you get llvmpipe, black screens, or a slideshow compositor.

# install/build driver package according to your repositories
sudo cave resolve --execute x11-drivers/nvidia-drivers

# verify modules exist
find "/lib/modules/$(uname -r)" -name 'nvidia*.ko*'

# /etc/modprobe.d/nvidia.conf
sudo tee /etc/modprobe.d/nvidia.conf >/dev/null <<'EOF'
options nvidia_drm modeset=1 fbdev=1
softdep nvidia post: nvidia-uvm
blacklist nouveau
EOF
                

Optional laptop features need separate validation. NVreg_DynamicPowerManagement=0x02 is for supported runtime-power-management setups. NVreg_PreserveVideoMemoryAllocations=1 requires the NVIDIA suspend/resume/hibernate units and enough backing storage; do not enable either as a universal desktop default.

GRUB kernel arguments:

nvidia-drm.modeset=1 nvidia-drm.fbdev=1
                

Verify after boot:

nvidia-smi
glxinfo -B
vulkaninfo --summary

sudo sh -c '
echo -n "modeset="; cat /sys/module/nvidia_drm/parameters/modeset
echo -n "fbdev="; cat /sys/module/nvidia_drm/parameters/fbdev
'
                

Good values are modeset=Y and fbdev=Y. If sysfs files are root-readable only, a normal user may see empty output.

After first boot, uname -r is suitable for rebuilding the running kernel's initramfs. During installation, reuse the explicit KVER from the kernel build section instead.

KVER="$(uname -r)"

sudo depmod "$KVER"
sudo dracut --force "/boot/initramfs-${KVER}.img" "$KVER"
sudo grub-mkconfig -o /boot/grub/grub.cfg

find /boot/EFI -maxdepth 4 -type f | sort
grep -nE 'vmlinuz|initrd' /boot/grub/grub.cfg
                

For KDE Wayland, screen sharing is not just Discord. It needs PipeWire, WirePlumber, xdg-desktop-portal, and the KDE portal backend. Flatpak apps also use the portal path.

systemctl --user status pipewire wireplumber pipewire-pulse xdg-desktop-portal --no-pager
ps aux | grep -E 'pipewire|wireplumber|xdg-desktop-portal' | grep -v grep
echo "$XDG_CURRENT_DESKTOP"
echo "$XDG_SESSION_TYPE"

pactl info
wpctl status
ls /usr/share/xdg-desktop-portal/portals
                

PipeWire services can show as disabled while sockets are enabled and the services are active. That is normal socket activation, not failure.

Use Flatpak Steam unless you intentionally want to build out Exherbo multiarch/32-bit userspace. The native Steam installer package can install the launcher but still fail with missing 32-bit libc.so.6.

flatpak remotes
flatpak install flathub com.valvesoftware.Steam
flatpak run com.valvesoftware.Steam

# optional permissions for a games folder
flatpak override --user --filesystem=/path/to/games com.valvesoftware.Steam
                

If native Steam says libc.so.6 is missing, check with find /usr /lib /lib32 /usr/lib32 -name libc.so.6 -exec file {} \;. If only 64-bit libc exists, native Steam will not run yet.

lookandfeeltool -a org.kde.breeze.desktop 2>/dev/null || true
plasma-apply-colorscheme BreezeDark 2>/dev/null || true
plasma-apply-desktoptheme breeze-dark 2>/dev/null || true
plasma-apply-cursortheme breeze_cursors 2>/dev/null || true

kbuildsycoca6 --noincremental
gtk-update-icon-cache -f /usr/share/icons/hicolor 2>/dev/null || true
gtk-update-icon-cache -f /usr/share/icons/breeze 2>/dev/null || true
gtk-update-icon-cache -f /usr/share/icons/Adwaita 2>/dev/null || true
                

A complete modern desktop path needs kernel sound support, any device firmware, ALSA userspace, PipeWire, a session manager such as WirePlumber, and the PulseAudio compatibility service when desktop applications expect it.

cave search alsa-utils
cave search wireplumber
cave show media/pipewire

# after login as the desktop user
aplay -l
arecord -l
alsamixer
systemctl --user status pipewire wireplumber pipewire-pulse --no-pager
wpctl status
pactl info
                

cave search qemu
cave search libvirt
cave search virt-manager
cave show category/candidate-package
cave resolve category/qemu-package category/management-package
                

Service names and group policy depend on the selected libvirt build. Inspect installed units and sockets with systemctl list-unit-files | grep -i virt. PCI passthrough requires IOMMU planning and can make the host lose access to a device; it is not a first-boot task.

Before exiting, confirm the user, network service, filesystem table, kernel, initramfs, loader entry, and root filesystem UUID. Then leave the chroot and unmount in reverse order from the live system.

# inside chroot
getent passwd alice
findmnt --verify --verbose
ls -lh /boot/vmlinuz-* /boot/initramfs-*.img
grep -nE 'vmlinuz|initramfs|root=' /boot/grub/grub.cfg
exit

# live system
sudo umount -R /mnt/exherbo
sudo swapoff /dev/nvme0n1p2   # use the actual swap device
sudo reboot
                

At first boot, use a local TTY if the display manager fails. Verify the running kernel, root mount, network, clock, failed units, and boot errors before adding more packages:

uname -r
findmnt /
ip -br address
timedatectl
systemctl --failed
journalctl -b -p 3 --no-pager
                

Exherbo protects local config files. When package updates provide a new config, Paludis may leave files like /etc/._cfg0000_hostname. Do not delete blindly; inspect and merge.

sudo find /etc -name '._cfg*' -print

for f in $(sudo find /etc -name '._cfg*' -print); do
  echo "===== $f ====="
  target="$(dirname "$f")/$(basename "$f" | sed 's/^._cfg[0-9]*_//')"
  echo "TARGET: $target"
  sudo diff -u "$target" "$f" 2>/dev/null || sudo cat "$f"
done
                

sudo cave sync

# preview only
sudo cave resolve world

# execute only after reading the plan
sudo cave resolve --execute world
                

If world shows same-version r rebuilds after editing options.conf, it is usually not broken. It is trying to make installed package metadata match the current desired options.

uname -r
findmnt / /boot
ip -br address
systemctl --failed
journalctl -b -p 3 --no-pager

# graphical profiles
lspci -nnk | grep -A3 -E 'VGA|3D|Display'
glxinfo -B
echo "$XDG_CURRENT_DESKTOP / $XDG_SESSION_TYPE"
systemctl --user --failed
wpctl status
                

Good signs for any selected profile:

• The running kernel has a matching module tree and the intended root and boot filesystems are mounted.
• The expected GPU driver is bound and glxinfo -B names hardware rather than llvmpipe.
• PipeWire/WirePlumber, portals, and a display manager are checked only when that profile uses them.
• Laptops resume, reconnect networking, restore audio, and drive external displays after suspend.
• No priority error spam in journalctl -b -p 3.

For proprietary NVIDIA, additionally run nvidia-smi and inspect /sys/module/nvidia_drm/parameters/modeset. For AMD, Intel, nouveau, and virtio, inspect the matching DRM driver in lspci -nnk and the kernel log instead.

Collect a small evidence bundle before asking for help. Remove secrets, private hostnames, MAC addresses, and authentication data before posting it.

uname -a
cave print-id-environment
systemctl --failed
journalctl -b -p 3 --no-pager
lspci -nnk
findmnt
df -h
                

Pick a distro based on hardware support, package freshness, release model, documentation, driver needs, and how much maintenance you want. The best distro is the one whose tradeoffs match the machine and the job.

This page favors official documentation, source browsers, manuals, and long-lived project sites. Forum posts and random scripts can be useful, but primary docs should be checked first.