lenovo-gentoo/USER-GUIDE.md

# 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)
- [Backup Management](#backup-management)
- [Dotfile Management](#dotfile-management)
- [System Updates](#system-updates)
- [Kernel Management](#kernel-management)
- [Display & Monitors](#display--monitors)
- [Power Management](#power-management)
- [Security](#security)
- [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
```

---

## Backup Management

Automated backup system with network trigger and multiple backup types.

### Using backup-setup Script

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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**
```bash
# Configure the tool normally
nvim ~/.config/newtool/config
```

**Step 2: Test the config**
```bash
# Make sure it works
newtool --version
```

**Step 3: Add to chezmoi**
```bash
# Add to dotfile management
chezmoi add ~/.config/newtool/config

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

**Step 4: Commit**
```bash
# 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

```bash
# 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
```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
```

---

## Security

### Firewall Management (nftables)

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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
```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` |
| 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
```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

**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