chore: initialize gentoo-setup documentation repository
Add comprehensive documentation for Lenovo ThinkPad Gentoo Linux setup including: - Complete system configuration guides (power, Bluetooth, WiFi, audio) - Hardware setup documentation (touchpad, touchscreen, DisplayLink) - Management scripts with ZSH completions - Kernel configuration (6.12.41-gentoo-x86_64) - Lid automation and monitor management - Battery conservation system - User guides and troubleshooting Repository includes .gitignore to exclude logs, temporary files, and secrets. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
726
USER-GUIDE.md
Normal file
726
USER-GUIDE.md
Normal file
@@ -0,0 +1,726 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user