# Gentoo System User Guide

Quick reference for everyday tasks on your Gentoo workstation.

## Table of Contents
- [Package Management](#package-management)
- [Service Management](#service-management)
- [Network Management](#network-management)
- [Audio Management](#audio-management)
- [Bluetooth Management](#bluetooth-management)
- [System Updates](#system-updates)
- [Kernel Management](#kernel-management)
- [Display & Monitors](#display--monitors)
- [Power Management](#power-management)
- [System Information](#system-information)

---

## Package Management

### Search for Packages
```bash
# Search by name
emerge --search firefox

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

# Search with details
eix firefox
```

### Install Packages
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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)
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# List connected monitors
hyprctl monitors

# Reload Hyprland config
hyprctl reload

# Restart waybar
pkill waybar && waybar &
```

### Check Display Information
```bash
# List all video outputs
ls /sys/class/drm/

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

---

## Power Management

### Battery Status
```bash
# 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
```bash
# 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
```bash
# Suspend system (sleep)
sudo rc-service elogind suspend

# Or via loginctl
loginctl suspend
```

---

## System Information

### Hardware Information
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Reload completions after installing new scripts
autoload -U compinit && compinit
```

### Check System Health
```bash
# 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:
   ```bash
   mount /dev/nvme0n1p2 /mnt
   mount /dev/nvme0n1p1 /mnt/boot
   ls -la /mnt/boot
   ```

### Clean Up System
```bash
# 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
```bash
# 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