feat: Add backup and security hardening
This commit is contained in:
690
Troubleshooting.md
Normal file
690
Troubleshooting.md
Normal file
@@ -0,0 +1,690 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
This guide contains troubleshooting commands and procedures for common issues
|
||||
on the Gentoo ThinkPad system.
|
||||
|
||||
## Bluetooth Issues
|
||||
|
||||
### Check Bluetooth Status
|
||||
|
||||
```bash
|
||||
# Check controller
|
||||
bluetoothctl list
|
||||
|
||||
# Check modules
|
||||
lsmod | grep bt
|
||||
|
||||
# Check service
|
||||
rc-service bluetooth status
|
||||
|
||||
# Check kernel messages
|
||||
dmesg | grep -i bluetooth
|
||||
```
|
||||
|
||||
### Full Troubleshooting Guide
|
||||
|
||||
See `Bluetooth-Setup.md` for complete Bluetooth setup, troubleshooting, and
|
||||
technical details.
|
||||
|
||||
## Power Management Issues
|
||||
|
||||
### Check Power Profile Status
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
tail -50 /var/log/power-profile.log
|
||||
|
||||
# Check current state
|
||||
cat /sys/class/power_supply/AC/online # 1 = AC, 0 = battery
|
||||
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
|
||||
|
||||
# Manual profile test
|
||||
sudo /usr/local/bin/power-profile-ac # Performance mode
|
||||
sudo /usr/local/bin/power-profile-battery # Power saving mode
|
||||
```
|
||||
|
||||
### Full Troubleshooting Guide
|
||||
|
||||
See `Power-Management-Setup.md` for complete details and advanced
|
||||
configuration.
|
||||
|
||||
## WiFi Issues
|
||||
|
||||
### Check WiFi Status
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
wifi-setup status
|
||||
|
||||
# Check waybar integration
|
||||
emerge -pv gui-apps/waybar | grep network
|
||||
|
||||
# Check network interface
|
||||
ip link show wlp194s0
|
||||
|
||||
# Check NetworkManager
|
||||
nmcli device status
|
||||
```
|
||||
|
||||
### Full Troubleshooting Guide
|
||||
|
||||
See `scripts/wifi-setup/README.md` for complete setup instructions, usage
|
||||
examples, and troubleshooting.
|
||||
|
||||
## Audio Issues
|
||||
|
||||
### Check Audio Status
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
audio-setup status
|
||||
|
||||
# List devices
|
||||
audio-setup list-outputs
|
||||
audio-setup list-inputs
|
||||
|
||||
# Check PulseAudio
|
||||
pactl info
|
||||
|
||||
# Check ALSA
|
||||
aplay -l # List playback devices
|
||||
arecord -l # List recording devices
|
||||
```
|
||||
|
||||
### Full Troubleshooting Guide
|
||||
|
||||
See `scripts/audio-setup/README.md` for complete setup instructions, usage
|
||||
examples, and troubleshooting.
|
||||
|
||||
## Monitor/Lid Issues
|
||||
|
||||
### Check Monitor Configuration
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
cat /tmp/lid-handler.log
|
||||
|
||||
# Check monitor configuration
|
||||
monitor-setup status
|
||||
hyprctl monitors
|
||||
|
||||
# Check ACPI events
|
||||
acpi_listen # Run this, then open/close lid to see events
|
||||
|
||||
# Check elogind
|
||||
loginctl show-session $XDG_SESSION_ID
|
||||
|
||||
# Check Hyprland monitor script
|
||||
/home/alexander/.config/hypr/scripts/monitor-setup.sh
|
||||
```
|
||||
|
||||
### Full Troubleshooting Guides
|
||||
|
||||
- `Lid-Automation-Working-Solution.md` - Lid automation implementation
|
||||
- `Fix-DisplayLink-Artifacts.md` - DisplayLink optimization guide
|
||||
|
||||
## Monitor Management Issues
|
||||
|
||||
### Interactive Monitor Commands
|
||||
|
||||
```bash
|
||||
# Check current layout
|
||||
monitor-setup status
|
||||
|
||||
# List all monitors
|
||||
monitor-setup list
|
||||
|
||||
# Swap if order is wrong
|
||||
sudo monitor-setup swap
|
||||
|
||||
# Reset to auto-detection
|
||||
sudo monitor-setup reset
|
||||
```
|
||||
|
||||
### Full Troubleshooting Guide
|
||||
|
||||
See `scripts/monitor-setup/README.md` for complete setup instructions, usage
|
||||
examples, and troubleshooting.
|
||||
|
||||
## Battery Conservation Issues
|
||||
|
||||
### Check Battery Thresholds
|
||||
|
||||
```bash
|
||||
# Check current thresholds
|
||||
battery-setup status
|
||||
|
||||
# Check if thresholds are supported
|
||||
ls /sys/class/power_supply/BAT*/charge_control_*_threshold
|
||||
|
||||
# Check OpenRC service
|
||||
rc-service battery-thresholds status
|
||||
|
||||
# Manually set thresholds
|
||||
sudo battery-setup conservation
|
||||
|
||||
# Check battery health
|
||||
cat /sys/class/power_supply/BAT0/capacity
|
||||
cat /sys/class/power_supply/BAT0/cycle_count
|
||||
cat /sys/class/power_supply/BAT0/status
|
||||
|
||||
# Check ThinkPad ACPI module
|
||||
lsmod | grep thinkpad_acpi
|
||||
```
|
||||
|
||||
### Full Troubleshooting Guide
|
||||
|
||||
See `scripts/battery-setup/README.md` for complete setup instructions, battery
|
||||
science, and troubleshooting.
|
||||
|
||||
## Backup Issues
|
||||
|
||||
### Check Backup Status
|
||||
|
||||
```bash
|
||||
# Check backup status
|
||||
backup-setup status
|
||||
|
||||
# Check if NAS is reachable
|
||||
ping -c 3 192.168.2.171
|
||||
ssh alexander@192.168.2.171 "echo test"
|
||||
|
||||
# Check network trigger logs
|
||||
tail -20 ~/.local/var/log/backup-monitor.log
|
||||
|
||||
# Check backup logs
|
||||
tail -50 ~/.local/var/log/backup.log
|
||||
|
||||
# Check for active backups
|
||||
ls -la /tmp/backup-*.lock
|
||||
|
||||
# Remove stale lock files (if older than 6 hours)
|
||||
rm /tmp/backup-*.lock
|
||||
|
||||
# Check backup service
|
||||
sudo rc-service backup-monitor status
|
||||
```
|
||||
|
||||
### Manual Backup Commands
|
||||
|
||||
```bash
|
||||
# Run manual backup
|
||||
backup-setup full # Full system backup
|
||||
backup-setup home # Home directory only
|
||||
backup-setup configs # Configuration files only
|
||||
backup-setup incremental # Incremental backup
|
||||
|
||||
# Check last backup time
|
||||
cat ~/.local/var/backup/last-backup
|
||||
```
|
||||
|
||||
### Full Troubleshooting Guide
|
||||
|
||||
See `Backup-Setup.md` for complete backup guide - Automated NAS backups,
|
||||
network trigger, troubleshooting.
|
||||
|
||||
## Firewall Issues
|
||||
|
||||
### Check Firewall Status
|
||||
|
||||
```bash
|
||||
# Check firewall status
|
||||
sudo rc-service nftables status
|
||||
|
||||
# View firewall rules
|
||||
sudo nft list ruleset
|
||||
|
||||
# Test connectivity
|
||||
ping -c 3 8.8.8.8 # Internet connectivity
|
||||
ping -c 3 192.168.2.171 # NAS connectivity
|
||||
|
||||
# Check if port is blocked
|
||||
sudo nft list ruleset | grep <port_number>
|
||||
|
||||
# Restart firewall
|
||||
sudo rc-service nftables restart
|
||||
|
||||
# Test specific service
|
||||
telnet <host> <port>
|
||||
```
|
||||
|
||||
### Full Troubleshooting Guide
|
||||
|
||||
See `Security-Hardening.md` for complete security guide - Firewall, fail2ban,
|
||||
SSH hardening, monitoring.
|
||||
|
||||
## Ghostty Terminal Issues
|
||||
|
||||
### Check Ghostty Status
|
||||
|
||||
```bash
|
||||
# Test if Ghostty works
|
||||
ghostty
|
||||
|
||||
# Check if it's pure Wayland (should show nothing)
|
||||
ldd /usr/bin/ghostty | grep -i x11
|
||||
|
||||
# Check Hyprland keybinding
|
||||
grep ghostty ~/.config/hypr/hyprland.conf
|
||||
|
||||
# Check Ghostty config
|
||||
cat ~/.config/ghostty/config
|
||||
|
||||
# Run Ghostty with debug output
|
||||
ghostty --verbose
|
||||
```
|
||||
|
||||
### Ghostty Configuration
|
||||
|
||||
**Location**: `~/.config/ghostty/config`
|
||||
|
||||
**Package Configuration**: See `CLAUDE.md` section "Ghostty Terminal Emulator"
|
||||
for complete USE flags and build configuration.
|
||||
|
||||
## Neovim/LSP Issues
|
||||
|
||||
### Check LSP Status
|
||||
|
||||
```bash
|
||||
# Check LSP servers are working
|
||||
nvim # Open Neovim
|
||||
:LspInfo # Check LSP status
|
||||
|
||||
# Check for LSP errors
|
||||
:messages
|
||||
|
||||
# Verify new API is being used (no deprecation warnings)
|
||||
# Start nvim and check for warnings about lspconfig
|
||||
|
||||
# Test a file with LSP support
|
||||
nvim test.go # Should show LSP features
|
||||
|
||||
# Check Neovim version
|
||||
nvim --version # Should be 0.11+
|
||||
|
||||
# Check LSP config location
|
||||
ls -la ~/.config/nvim/lua/alxndrhi/plugins/lsp.lua
|
||||
```
|
||||
|
||||
### LSP Configuration
|
||||
|
||||
**Location**: `~/.config/nvim/lua/alxndrhi/plugins/lsp.lua`
|
||||
|
||||
**API**: Uses Neovim 0.11+ native `vim.lsp.config[]` API (not deprecated
|
||||
`require('lspconfig')`)
|
||||
|
||||
**Configured Servers**: html, cssls, gopls, clangd, jsonls, yamlls, bashls,
|
||||
dockerls, vimls, lua_ls, ruff, graphql, tailwindcss, vuels, cmake
|
||||
|
||||
## Theme/Waybar Issues
|
||||
|
||||
### Check Waybar Theme
|
||||
|
||||
```bash
|
||||
# Check waybar is using correct CSS file
|
||||
# Look for: "Using CSS file /home/alexander/.config/waybar/style.css"
|
||||
killall waybar && waybar 2>&1 | head -20
|
||||
|
||||
# Verify Nerd Font is available
|
||||
fc-list | grep -i hasklug
|
||||
|
||||
# Test icon display in terminal
|
||||
echo "CPU: RAM: WiFi: Volume: "
|
||||
|
||||
# Check if Catppuccin colors are applied
|
||||
cat ~/.config/waybar/style.css | grep "#1e1e2e" # Should show base color
|
||||
|
||||
# Restart waybar to apply changes
|
||||
killall waybar && waybar &
|
||||
|
||||
# Check Hyprland colors
|
||||
hyprctl clients | grep -A 5 "Window" # Should show borders
|
||||
|
||||
# View Hyprland color configuration
|
||||
cat ~/.config/hypr/mocha.conf
|
||||
```
|
||||
|
||||
### Waybar Configuration Files
|
||||
|
||||
- `~/.config/waybar/config` - Module configuration with icon definitions
|
||||
- `~/.config/waybar/style.css` - Catppuccin Mocha theme with color-coded
|
||||
modules
|
||||
- `~/.config/waybar/mocha.css` - Catppuccin Mocha color palette definitions
|
||||
|
||||
### Hyprland Theme Files
|
||||
|
||||
- `~/.config/hypr/hyprland.conf` - Window border colors
|
||||
- `~/.config/hypr/mocha.conf` - Catppuccin Mocha color variables
|
||||
|
||||
## Dotfile Management (chezmoi) Issues
|
||||
|
||||
### Common Chezmoi Problems
|
||||
|
||||
```bash
|
||||
# Warning about config template changed
|
||||
chezmoi init
|
||||
|
||||
# Diff shows nothing or just "pppp"
|
||||
chezmoi diff --use-builtin-diff | less
|
||||
|
||||
# File conflicts
|
||||
chezmoi merge ~/.zshrc
|
||||
# Or force overwrite:
|
||||
chezmoi apply --force
|
||||
|
||||
# Template errors
|
||||
chezmoi cat ~/.zshrc # See rendered output
|
||||
chezmoi execute-template "{{ .chezmoi.os }}" # Test expression
|
||||
|
||||
# Re-run installation scripts
|
||||
chezmoi state reset --bucket=scriptState
|
||||
chezmoi apply
|
||||
|
||||
# Check configuration
|
||||
chezmoi data # View all variables
|
||||
cat ~/.config/chezmoi/chezmoi.yaml
|
||||
|
||||
# Remove file from management
|
||||
chezmoi forget ~/.file
|
||||
|
||||
# Complete reset (DESTRUCTIVE - removes all managed files)
|
||||
chezmoi purge
|
||||
```
|
||||
|
||||
### Chezmoi Configuration
|
||||
|
||||
**Source Directory**: `~/.local/share/chezmoi` (git clone of dotfiles repo)
|
||||
|
||||
**Dotfiles Repository**: `~/repository/git.hinrichs.dev/alexander/dotfiles`
|
||||
|
||||
**Config File**: `~/.config/chezmoi/chezmoi.yaml` (generated from
|
||||
`.chezmoi.yaml.tmpl`)
|
||||
|
||||
### Full Troubleshooting Guide
|
||||
|
||||
See `Dotfiles-Management.md` for complete chezmoi guide - Managing dotfiles,
|
||||
adding new tools, editing configs.
|
||||
|
||||
## Kernel Issues
|
||||
|
||||
### Check Kernel Configuration
|
||||
|
||||
```bash
|
||||
# Check current kernel version
|
||||
uname -r
|
||||
|
||||
# Extract current running config
|
||||
zcat /proc/config.gz > /tmp/current-config
|
||||
|
||||
# Check specific kernel option
|
||||
zcat /proc/config.gz | grep CONFIG_PINCTRL_AMD
|
||||
|
||||
# Check loaded modules
|
||||
lsmod
|
||||
|
||||
# Check kernel messages
|
||||
dmesg | less
|
||||
|
||||
# Check for kernel errors
|
||||
dmesg | grep -i error
|
||||
dmesg | grep -i fail
|
||||
```
|
||||
|
||||
### Kernel Build Issues
|
||||
|
||||
**⚠️ CRITICAL**: NEVER use genkernel. Always use manual kernel compilation or
|
||||
the automated build script.
|
||||
|
||||
**Build Script**: `scripts/build-kernel.sh`
|
||||
|
||||
**Saved Config**: `kernel-6.12.41-gentoo-x86_64.config`
|
||||
|
||||
**Build Logs**: `logs/kernel-build-TIMESTAMP.log`
|
||||
|
||||
### Manual Kernel Build
|
||||
|
||||
```bash
|
||||
# Extract current running config
|
||||
zcat /proc/config.gz > /usr/src/linux/.config
|
||||
|
||||
# Edit config as needed
|
||||
cd /usr/src/linux
|
||||
sudo make menuconfig
|
||||
|
||||
# Or use automated script
|
||||
sudo ./scripts/build-kernel.sh
|
||||
```
|
||||
|
||||
See `CLAUDE.md` section "Kernel Configuration" for complete build process.
|
||||
|
||||
## Touchpad/Touchscreen Issues
|
||||
|
||||
### Check I2C HID Devices
|
||||
|
||||
```bash
|
||||
# Check if devices are detected
|
||||
dmesg | grep -i elan
|
||||
|
||||
# Check if modules are loaded
|
||||
lsmod | grep i2c_hid
|
||||
|
||||
# Check device nodes
|
||||
ls -la /dev/input/by-path/ | grep i2c
|
||||
|
||||
# Check Hyprland input devices
|
||||
hyprctl devices
|
||||
|
||||
# Test touchpad events
|
||||
libinput debug-events
|
||||
```
|
||||
|
||||
### Hardware Details
|
||||
|
||||
- **Touchpad**: ELAN901C I2C HID device (ACPI: ELAN901C:00, PNP0C50)
|
||||
- **Touchscreen**: ELAN0678 I2C HID multitouch display (ACPI: ELAN0678:00,
|
||||
PNP0C50)
|
||||
|
||||
### Required Kernel Options
|
||||
|
||||
- `CONFIG_I2C_HID=m`
|
||||
- `CONFIG_I2C_HID_ACPI=m`
|
||||
- `CONFIG_PINCTRL_AMD=y` (CRITICAL for GPIO interrupts on AMD platforms)
|
||||
|
||||
### Full Documentation
|
||||
|
||||
See `Touchpad-Touchscreen-Setup.md` and `POST-REBOOT-CHECKLIST.md`
|
||||
|
||||
## Webcam Issues
|
||||
|
||||
### Check Webcam Status
|
||||
|
||||
```bash
|
||||
# Check if webcam is detected
|
||||
lsusb | grep -i camera
|
||||
|
||||
# Check kernel messages
|
||||
dmesg | grep -i uvc
|
||||
|
||||
# List video devices
|
||||
ls -la /dev/video*
|
||||
|
||||
# Check video device capabilities (requires v4l-utils)
|
||||
v4l2-ctl --list-devices
|
||||
v4l2-ctl -d /dev/video0 --list-formats-ext
|
||||
|
||||
# Test capture (requires ffmpeg)
|
||||
ffmpeg -f v4l2 -i /dev/video0 -frames:v 1 test.jpg
|
||||
|
||||
# Check user permissions
|
||||
groups | grep video
|
||||
```
|
||||
|
||||
### Hardware Details
|
||||
|
||||
- **Model**: Luxvisions Innotech Limited Integrated RGB Camera
|
||||
- **USB ID**: 30c9:00f4
|
||||
- **Resolution**: 640x480 @ 30fps (default)
|
||||
- **Driver**: uvcvideo (USB Video Class)
|
||||
- **Device Nodes**: /dev/video0-3
|
||||
|
||||
## Docker Issues
|
||||
|
||||
### Check Docker Status
|
||||
|
||||
```bash
|
||||
# Check Docker service
|
||||
rc-service docker status
|
||||
|
||||
# Check Docker version
|
||||
docker --version
|
||||
|
||||
# Test Docker
|
||||
docker run hello-world
|
||||
|
||||
# Check Docker logs
|
||||
docker logs <container_id>
|
||||
|
||||
# Check Docker network
|
||||
docker network ls
|
||||
```
|
||||
|
||||
### Docker Firewall Integration
|
||||
|
||||
If Docker containers cannot reach the internet, check firewall rules:
|
||||
|
||||
```bash
|
||||
# Check if Docker chain exists in nftables
|
||||
sudo nft list ruleset | grep docker
|
||||
|
||||
# Uncomment Docker forwarding rules in /etc/nftables.conf
|
||||
# Then restart:
|
||||
sudo rc-service nftables restart
|
||||
```
|
||||
|
||||
See `Security-Hardening.md` for Docker firewall integration.
|
||||
|
||||
## General System Troubleshooting
|
||||
|
||||
### Service Management (OpenRC)
|
||||
|
||||
```bash
|
||||
# List all services
|
||||
rc-status -a
|
||||
|
||||
# Start/stop/restart service
|
||||
sudo rc-service <service> start
|
||||
sudo rc-service <service> stop
|
||||
sudo rc-service <service> restart
|
||||
|
||||
# Enable/disable service at boot
|
||||
sudo rc-update add <service> default
|
||||
sudo rc-update del <service> default
|
||||
|
||||
# Check service logs
|
||||
tail -f /var/log/<service>.log
|
||||
```
|
||||
|
||||
### System Logs
|
||||
|
||||
```bash
|
||||
# View system messages
|
||||
dmesg | less
|
||||
|
||||
# View recent errors
|
||||
dmesg | grep -i error | tail -20
|
||||
|
||||
# View kernel ring buffer
|
||||
journalctl -k # If using systemd-journald
|
||||
|
||||
# Check OpenRC logs
|
||||
ls -la /var/log/rc.log
|
||||
```
|
||||
|
||||
### Package Management (Gentoo)
|
||||
|
||||
```bash
|
||||
# Search for package
|
||||
emerge --search <package>
|
||||
|
||||
# Check package info
|
||||
emerge --info <package>
|
||||
|
||||
# List installed packages
|
||||
qlist -I
|
||||
|
||||
# Check for config file updates
|
||||
dispatch-conf
|
||||
|
||||
# Rebuild @world
|
||||
emerge -avuDN @world
|
||||
```
|
||||
|
||||
### Performance Monitoring
|
||||
|
||||
```bash
|
||||
# CPU usage
|
||||
top
|
||||
htop
|
||||
|
||||
# Memory usage
|
||||
free -h
|
||||
|
||||
# Disk usage
|
||||
df -h
|
||||
du -sh /*
|
||||
|
||||
# I/O statistics
|
||||
iostat -x 2
|
||||
|
||||
# Network statistics
|
||||
iftop
|
||||
nethogs
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Documentation Files
|
||||
|
||||
- `USER-GUIDE.md` - Quick reference for everyday tasks
|
||||
- `System-Overview.md` - Hardware specs and software stack
|
||||
- `Feature-Status.md` - Current state and working features
|
||||
- `Backup-Setup.md` - Complete backup guide
|
||||
- `Security-Hardening.md` - Complete security guide
|
||||
- `Power-Management-Setup.md` - Power management guide
|
||||
- `Bluetooth-Setup.md` - Bluetooth setup and troubleshooting
|
||||
- `Dotfiles-Management.md` - Complete chezmoi guide
|
||||
|
||||
### Script Documentation
|
||||
|
||||
- `scripts/wifi-setup/README.md` - WiFi setup tool
|
||||
- `scripts/bluetooth-setup/README.md` - Bluetooth setup tool
|
||||
- `scripts/audio-setup/README.md` - Audio setup tool
|
||||
- `scripts/monitor-setup/README.md` - Monitor setup tool
|
||||
- `scripts/battery-setup/README.md` - Battery conservation tool
|
||||
|
||||
### Emergency Recovery
|
||||
|
||||
If the system becomes unbootable:
|
||||
|
||||
1. Boot from Gentoo LiveCD/USB
|
||||
2. Mount root filesystem: `mount /dev/sdXY /mnt/gentoo`
|
||||
3. Chroot: `chroot /mnt/gentoo /bin/bash`
|
||||
4. Source profile: `source /etc/profile`
|
||||
5. Fix issue (kernel, config, etc.)
|
||||
6. Exit chroot and reboot
|
||||
|
||||
### Backup Restoration
|
||||
|
||||
If you need to restore from backup:
|
||||
|
||||
```bash
|
||||
# List available backups on NAS
|
||||
ssh alexander@192.168.2.171 "ls -la /mnt/ssd-pool-a/backups/lenovo-gentoo/"
|
||||
|
||||
# Restore specific backup
|
||||
rsync -avz --progress \
|
||||
alexander@192.168.2.171:/mnt/ssd-pool-a/backups/lenovo-gentoo/YYYY-MM-DD/ \
|
||||
/restore-location/
|
||||
```
|
||||
|
||||
See `Backup-Setup.md` for complete restoration procedures.
|
||||
Reference in New Issue
Block a user