lenovo-gentoo/USER-GUIDE.md

Gentoo System User Guide

Quick reference for everyday tasks on your Gentoo workstation.

Table of Contents

• Package Management
• Service Management
• Network Management
• Audio Management
• Bluetooth Management
• System Updates
• Kernel Management
• Display & Monitors
• Power Management
• System Information

---

Package Management

Search for Packages

# Search by name
emerge --search firefox

# Search by description
emerge --searchdesc "web browser"

# Search with details
eix firefox

Install Packages

# Install a package
sudo emerge -av package-name

# Install without asking for confirmation
sudo emerge package-name

# Install specific version
sudo emerge =app-editors/vim-9.0.1627

Uninstall Packages

# Uninstall a package
sudo emerge -C package-name

# Uninstall and remove dependencies no longer needed
sudo emerge --depclean

# Safe depclean (ask before removing)
sudo emerge -av --depclean

Update Packages

# Update package list
sudo emerge --sync

# Check for updates
emerge -uDNp @world

# Update all packages (pretend/dry-run)
emerge -uDNp @world

# Actually update all packages
sudo emerge -uDN @world

# Update with asking
sudo emerge -uDNav @world

Package Information

# Show installed packages
qlist -I

# Show package details
emerge -pv package-name

# Show why a package is installed
emerge -p --depclean package-name

# List files installed by package
qlist package-name

USE Flags

# Show USE flags for a package
emerge -pv package-name

# Show all available USE flags
less /usr/portage/profiles/use.desc

# Edit USE flags for specific package
sudo nano /etc/portage/package.use/custom

---

Service Management

Gentoo uses OpenRC for service management.

Service Status

# Check if service is running
rc-service service-name status

# List all services
rc-status

# List services in default runlevel
rc-status default

Start/Stop Services

# Start a service
sudo rc-service service-name start

# Stop a service
sudo rc-service service-name stop

# Restart a service
sudo rc-service service-name restart

Enable/Disable Services (Auto-start at Boot)

# Enable service at boot (add to default runlevel)
sudo rc-update add service-name default

# Disable service at boot (remove from default runlevel)
sudo rc-update del service-name default

# Show which services are enabled
rc-update show

Common Services

# NetworkManager
sudo rc-service NetworkManager start/stop/restart/status
sudo rc-update add NetworkManager default

# Bluetooth
sudo rc-service bluetooth start/stop/restart/status
sudo rc-update add bluetooth default

# ACPI (lid events, power button)
sudo rc-service acpid start/stop/restart/status

# Docker
sudo rc-service docker start/stop/restart/status
sudo rc-update add docker default

---

Network Management

WiFi (using wifi-setup script)

# Show current connection
wifi-setup status

# List available networks
wifi-setup
wifi-setup scan

# Connect to network (prompts for password)
wifi-setup connect "NetworkName"

# Disconnect
wifi-setup disconnect

# List saved networks
wifi-setup list-saved

# Forget a network
wifi-setup forget "NetworkName"

WiFi (using nmcli directly)

# Show connection status
nmcli device status

# Show active connection details
nmcli connection show --active

# Connect to saved network
nmcli connection up "NetworkName"

# Disconnect
nmcli device disconnect wlp194s0

Network Information

# Show IP addresses
ip addr show

# Show specific interface
ip addr show wlp194s0

# Show routing table
ip route show

# Test connectivity
ping -c 4 8.8.8.8

---

Audio Management

Using audio-setup script

# Show current audio status
audio-setup

# List output devices (speakers, headphones, HDMI)
audio-setup list-outputs

# List input devices (microphones)
audio-setup list-inputs

# Switch output device
audio-setup output 2

# Switch input device
audio-setup input 2

# Set volume (0-100)
audio-setup volume 75

# Mute/unmute output
audio-setup mute
audio-setup unmute

# Mute/unmute input (microphone)
audio-setup mute-input
audio-setup unmute-input

Using pactl directly

# List sinks (outputs)
pactl list short sinks

# List sources (inputs)
pactl list short sources

# Set default sink
pactl set-default-sink SINK_NAME

# Set volume
pactl set-sink-volume @DEFAULT_SINK@ 50%

# Mute/unmute
pactl set-sink-mute @DEFAULT_SINK@ toggle

---

Bluetooth Management

Using bluetooth-setup script

# List paired devices
bluetooth-setup

# Show Bluetooth status
bluetooth-setup status

# Scan for devices
bluetooth-setup scan

# Pair with device
bluetooth-setup pair AA:BB:CC:DD:EE:FF

# Connect to paired device
bluetooth-setup connect AA:BB:CC:DD:EE:FF

# Disconnect
bluetooth-setup disconnect

# Remove/forget device
bluetooth-setup remove AA:BB:CC:DD:EE:FF

# Power on/off
bluetooth-setup power on
bluetooth-setup power off

Using bluetoothctl directly

# Interactive mode
bluetoothctl

# Inside bluetoothctl:
power on
scan on
pair AA:BB:CC:DD:EE:FF
connect AA:BB:CC:DD:EE:FF
disconnect AA:BB:CC:DD:EE:FF
exit

---

System Updates

Full System Update

# 1. Sync package repository
sudo emerge --sync

# 2. Check what will be updated
emerge -uDNp @world

# 3. Update all packages
sudo emerge -uDNav @world

# 4. Clean old dependencies
sudo emerge -av --depclean

# 5. Rebuild preserved libraries (if any)
sudo emerge @preserved-rebuild

Update Mirrors (for fastest downloads)

# Install mirrorselect
sudo emerge -av app-portage/mirrorselect

# Select fastest mirrors (interactive)
sudo mirrorselect -i -o >> /etc/portage/make.conf

# Auto-select fastest mirrors
sudo mirrorselect -s3 -b10 -o >> /etc/portage/make.conf

# Or manually edit
sudo nano /etc/portage/make.conf
# Then find GENTOO_MIRRORS= line

Check for News

# Show unread Gentoo news
eselect news list

# Read news item
eselect news read 1

# Mark all as read
eselect news read all

---

Kernel Management

Check Kernel Version

# Current running kernel
uname -r

# Kernel config of running kernel
zcat /proc/config.gz | less

# Search kernel config
zcat /proc/config.gz | grep KEYWORD

Build New Kernel (Manual Method)

# Use the automated build script
cd /home/alexander/repository/git.hinrichs.dev/alexander/claude/gentoo-setup
sudo ./scripts/build-kernel.sh

# Or manually:
cd /usr/src/linux
sudo make menuconfig    # Edit configuration
sudo make -j16          # Build kernel
sudo make modules_install
sudo cp arch/x86_64/boot/bzImage /boot/vmlinuz-6.12.41-gentoo-x86_64
sudo dracut --force --kver 6.12.41-gentoo-x86_64 /boot/initramfs-6.12.41-gentoo-x86_64.img
sudo grub-mkconfig -o /boot/grub/grub.cfg

Install Kernel Modules

# List loaded modules
lsmod

# Load a module
sudo modprobe module-name

# Unload a module
sudo modprobe -r module-name

# Auto-load module at boot
echo "module-name" | sudo tee /etc/modules-load.d/module-name.conf

---

Display & Monitors

Hyprland Monitor Management

# List connected monitors
hyprctl monitors

# Reload Hyprland config
hyprctl reload

# Restart waybar
pkill waybar && waybar &

Check Display Information

# List all video outputs
ls /sys/class/drm/

# Check connected displays
cat /sys/class/drm/card*/status

---

Power Management

Battery Status

# Check battery status
cat /sys/class/power_supply/BAT0/capacity
cat /sys/class/power_supply/BAT0/status

# Check AC adapter status
cat /sys/class/power_supply/AC/online

Power Profiles

# Check current CPU governor
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

# Manual profile switch (already automatic via ACPI)
sudo /usr/local/bin/power-profile-ac        # Performance mode
sudo /usr/local/bin/power-profile-battery   # Power saving mode

# View power profile log
tail -f /var/log/power-profile.log

Suspend/Sleep

# Suspend system (sleep)
sudo rc-service elogind suspend

# Or via loginctl
loginctl suspend

---

System Information

Hardware Information

# CPU information
lscpu
cat /proc/cpuinfo

# Memory information
free -h
cat /proc/meminfo

# Disk usage
df -h
lsblk

# USB devices
lsusb
lsusb -v

# PCI devices
lspci
lspci -v

# Detailed hardware
hwinfo --short

System Information

# Gentoo version
cat /etc/gentoo-release

# Kernel version
uname -a

# System uptime
uptime

# Current processes
top
htop

# Disk usage by directory
du -sh /path/to/directory
du -sh /* | sort -h

Logs

# Kernel messages
dmesg | less
dmesg | grep -i error

# System logs (OpenRC)
tail -f /var/log/messages

# Service-specific logs
tail -f /var/log/syslog

---

File Management

Find Files

# Find by name
find /path -name "filename"

# Find by extension
find /path -name "*.txt"

# Find files modified in last 7 days
find /path -mtime -7

# Find large files (>100MB)
find /path -size +100M

Disk Usage

# Show disk usage
df -h

# Show directory sizes
du -sh *

# Show largest directories
du -h /home/alexander | sort -h | tail -20

# Disk usage analyzer (ncurses)
ncdu /

Permissions

# Change ownership
sudo chown user:group file

# Change permissions
chmod 755 file    # rwxr-xr-x
chmod 644 file    # rw-r--r--
chmod +x file     # Add execute

# Recursive
chmod -R 755 directory/

---

Development Tools

Docker

# Start Docker service
sudo rc-service docker start

# List containers
docker ps
docker ps -a

# Run container
docker run -it ubuntu bash

# Stop container
docker stop container_id

# Remove container
docker rm container_id

Git

# Clone repository
git clone https://github.com/user/repo.git

# Status
git status

# Add changes
git add .
git add file

# Commit
git commit -m "message"

# Push
git push origin main

# Pull
git pull

---

Tips & Tricks

Rebuild ZSH Completions

# Reload completions after installing new scripts
autoload -U compinit && compinit

Check System Health

# CPU temperature
sensors

# Disk health
sudo smartctl -a /dev/nvme0n1

# Memory test (requires memtester)
memtester 1G 1

Emergency Boot

If system doesn't boot:

1. Boot from GRUB menu
2. If GRUB shows no kernels, boot from live USB
3. Mount system and check /boot:

   mount /dev/nvme0n1p2 /mnt
   mount /dev/nvme0n1p1 /mnt/boot
   ls -la /mnt/boot
   

Clean Up System

# Remove unneeded dependencies
sudo emerge --depclean

# Clean package download cache
sudo eclean-dist --deep

# Clean old kernel modules
# (manually remove from /lib/modules/)

# Clean temporary files
rm -rf ~/.cache/*
sudo rm -rf /var/tmp/portage/*

---

Quick Reference Card

Task	Command
Install package	sudo emerge -av package
Remove package	sudo emerge -C package
Update system	sudo emerge --sync && sudo emerge -uDNav @world
Search package	emerge --search keyword
Start service	sudo rc-service name start
Enable service	sudo rc-update add name default
WiFi connect	wifi-setup connect "SSID"
Audio switch	audio-setup output 2
Bluetooth pair	bluetooth-setup pair MAC
Check logs	tail -f /var/log/messages
Disk usage	df -h
Free memory	free -h
Processes	htop

---

Getting Help

Man Pages

# Read manual for command
man command

# Search man pages
man -k keyword
apropos keyword

Gentoo Resources

• Gentoo Wiki: https://wiki.gentoo.org
• Gentoo Forums: https://forums.gentoo.org
• Package Search: https://packages.gentoo.org

Local Documentation

• Main system overview: Claude.md
• WiFi setup: scripts/wifi-setup/README.md
• Bluetooth setup: scripts/bluetooth-setup/README.md
• Audio setup: scripts/audio-setup/README.md
• Power management: Power-Management-Setup.md

---

Last Updated: 2025-11-05