alexander/lenovo-gentoo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
96f521a474a13e1b19f73694e1058ce0d3aeb1b8
lenovo-gentoo/USER-GUIDE.md

19 KiB
Raw Blame History

Gentoo System User Guide

Quick reference for everyday tasks on your Gentoo workstation.

Table of Contents

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

Backup Management

Automated backup system with network trigger and multiple backup types.

Using backup-setup Script

# Show backup status
backup-setup status

# Trigger manual backup
backup-setup backup [TYPE]

# List backups on NAS
backup-setup list

# View recent logs
backup-setup logs

# Test NAS connection
backup-setup test

Backup Types

# Full system backup (large, slow)
backup-setup backup full

# Home directory only (medium)
backup-setup backup home

# Incremental backup (small, fast)
backup-setup backup incremental

# Configuration files only (tiny, very fast)
backup-setup backup configs

Network Trigger Service

# Check monitor status
sudo rc-service backup-monitor status

# View monitor logs
tail -f ~/.local/var/log/backup-monitor.log

# View backup logs
tail -f ~/.local/var/log/backup.log

# Start/stop monitor
sudo rc-service backup-monitor start
sudo rc-service backup-monitor stop

Manual Backup Scripts

# Run backup scripts directly
/usr/local/bin/backup-full
/usr/local/bin/backup-home
/usr/local/bin/backup-incremental
/usr/local/bin/backup-configs

For complete backup guide, see: Backup-Setup.md

Dotfile Management

Dotfiles (configuration files) are managed with chezmoi for cross-platform sync across machines.

Quick Start

# Edit a dotfile
chezmoi edit ~/.zshrc

# Preview changes
chezmoi diff

# Apply changes
chezmoi apply

# Update from remote repository
chezmoi update

Common Tasks

Edit Configuration Files

# Edit shell config
chezmoi edit ~/.zshrc

# Edit git config
chezmoi edit ~/.gitconfig

# Edit neovim config
chezmoi edit ~/.config/nvim/init.lua

Add New Configuration Files

# Add a new dotfile
chezmoi add ~/.newconfig

# Add entire directory
chezmoi add --recursive ~/.config/newtool

# Add as template (for cross-platform configs)
chezmoi add --template ~/.config/tool/config

View Changes

# See what would change
chezmoi diff

# See rendered template
chezmoi cat ~/.zshrc

# Check which files are managed
chezmoi managed

# Show status
chezmoi status

Sync Changes

# Pull and apply latest changes from git
chezmoi update

# Apply without pulling
chezmoi apply

# Just pull without applying
chezmoi cd
git pull

Commit and Push Changes

# Go to chezmoi source directory
chezmoi cd

# Check what changed
git status
git diff

# Commit changes
git add .
git commit -m "feat: update zsh config"
git push

# Return to previous directory
exit  # or Ctrl+D

Advanced Usage

Convert File to Template

# Make a file a template (adds .tmpl extension)
chezmoi chattr +template ~/.zshrc

# Edit the template
chezmoi edit ~/.zshrc

# Add OS-specific logic:
# {{ if eq .chezmoi.os "darwin" -}}
# macOS-specific config
# {{- else if eq .osid "linux-gentoo" -}}
# Gentoo-specific config
# {{- end }}

Test Without Applying

# Dry run (preview what would happen)
chezmoi apply --dry-run --verbose

# View rendered template
chezmoi cat ~/.config/tool/config

# Execute template expression
chezmoi execute-template "{{ .chezmoi.os }}"

View Configuration

# Show chezmoi data (OS, machine type, etc.)
chezmoi data

# Edit chezmoi config
chezmoi edit-config

# Show source path
chezmoi source-path

Dotfiles Repository Structure

~/repository/git.hinrichs.dev/alexander/dotfiles/  # Main repo
~/.local/share/chezmoi/                             # Chezmoi working copy
~/.config/chezmoi/chezmoi.yaml                      # Generated config

Adding New Tools

When you install a new tool with configuration:

Step 1: Create the config

# Configure the tool normally
nvim ~/.config/newtool/config

Step 2: Test the config

# Make sure it works
newtool --version

Step 3: Add to chezmoi

# Add to dotfile management
chezmoi add ~/.config/newtool/config

# Or add entire directory
chezmoi add --recursive ~/.config/newtool

Step 4: Commit

# Go to dotfiles repo
chezmoi cd

# Commit
git add .
git commit -m "feat: add newtool configuration"
git push

Now the config will sync to all your machines!

Troubleshooting

# Reset and regenerate config
chezmoi init

# Force re-apply everything
chezmoi apply --force

# Remove a file from management
chezmoi forget ~/.file

# Purge chezmoi (removes all managed files)
chezmoi purge

For detailed documentation, see:

  • Dotfiles-Management.md - Complete guide
  • ~/repository/git.hinrichs.dev/alexander/dotfiles/README.md - Dotfiles repo docs

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

Security

Firewall Management (nftables)

# Start firewall
sudo rc-service nftables start

# Check firewall status
sudo rc-service nftables status

# View firewall rules
sudo nft list ruleset

# Reload configuration
sudo rc-service nftables restart

# Enable at boot
sudo rc-update add nftables default

Intrusion Prevention (fail2ban)

# Check fail2ban status
sudo fail2ban-client status

# Check SSH jail status
sudo fail2ban-client status sshd

# View banned IPs
sudo fail2ban-client status sshd

# Unban an IP
sudo fail2ban-client set sshd unbanip 1.2.3.4

# View fail2ban log
sudo tail -f /var/log/fail2ban.log

# Enable at boot
sudo rc-update add fail2ban default

SSH Security

# Test SSH configuration
sudo sshd -t

# Restart SSH service
sudo rc-service sshd restart

# View SSH logs
sudo tail -f /var/log/auth.log

# View recent SSH logins
last -10

# View failed SSH attempts
sudo grep "Failed password" /var/log/auth.log | tail -20

Security Monitoring

# Check open ports
sudo ss -tlnp

# Check SSH login attempts
sudo grep "sshd" /var/log/auth.log | tail -20

# Check for security updates
glsa-check -l

# View system logs
sudo tail -f /var/log/messages

For complete security hardening guide, see: Security-Hardening.md

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
Backup status backup-setup status
Trigger backup backup-setup backup incremental
Firewall status sudo nft list ruleset
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

Local Documentation

Quick Reference & Overview:

  • This guide: USER-GUIDE.md - Quick reference for everyday tasks
  • System overview: System-Overview.md - Hardware, software, design
  • Feature status: Feature-Status.md - Working features, session history
  • Troubleshooting: Troubleshooting.md - Troubleshooting all components

Complete Guides:

  • Backup system: Backup-Setup.md
  • Security hardening: Security-Hardening.md
  • Power management: Power-Management-Setup.md
  • Bluetooth setup: Bluetooth-Setup.md
  • Dotfile management: Dotfiles-Management.md
  • Lid automation: Lid-Automation-Working-Solution.md

Script Documentation:

  • WiFi setup: scripts/wifi-setup/README.md
  • Bluetooth setup: scripts/bluetooth-setup/README.md
  • Audio setup: scripts/audio-setup/README.md
  • Battery conservation: scripts/battery-setup/README.md
  • Monitor management: scripts/monitor-setup/README.md

For Claude Code:

  • Operational guidelines: CLAUDE.md

Last Updated: 2025-11-07