lenovo-gentoo/Backup-Setup.md

Backup Setup Guide

Complete guide for the automated backup system on Gentoo workstation.

Overview

This backup system provides automated, network-triggered backups to a NAS via SSH/rsync with multiple safeguards against backup spam and comprehensive logging.

Table of Contents

• Features
• Architecture
• Installation
• Configuration
• Usage
• Backup Types
• Network Trigger
• Troubleshooting
• Advanced Configuration

Features

✅ Four backup types: Full system, home directory, incremental, configs ✅ Network-triggered backups: Auto-backup when NAS detected ✅ Multiple safeguards: Rate limiting, cooldown, lock files ✅ Interactive management: Easy-to-use CLI interface ✅ Comprehensive logging: Track all backup operations ✅ ZSH completion: Tab completion for all commands ✅ User-space operation: No sudo required for backups

Architecture

Components

/usr/local/bin/
├── backup-setup          # Interactive management script
├── backup-full           # Full system backup
├── backup-home           # Home directory backup
├── backup-incremental    # Incremental backup
├── backup-configs        # Configuration files backup
└── backup-trigger        # Network trigger daemon

/etc/
├── backup.conf           # Configuration file
└── init.d/
    └── backup-monitor    # OpenRC service

~/.local/var/
├── log/
│   ├── backup.log        # Backup operations log
│   └── backup-monitor.log # Monitor daemon log
└── backup/
    ├── last-backup       # Last backup timestamp
    ├── last-check        # Last NAS check timestamp
    └── backup-in-progress # Active backup marker

Backup Flow

1. Network trigger detects NAS
   ↓
2. Check safeguards (cooldown, rate limit, lock files)
   ↓
3. Trigger backup in background
   ↓
4. Backup runs (rsync to NAS)
   ↓
5. Update timestamps and markers
   ↓
6. Wait for next check (5 minutes)

Installation

Prerequisites

# Required packages
emerge -av net-misc/rsync net-misc/openssh

# Verify NAS is accessible
ping 192.168.2.171
ssh alexander@192.168.2.171

Install Scripts

cd ~/repository/git.hinrichs.dev/alexander/claude/lenovo-gentoo/scripts/backup-setup
sudo ./INSTALL.sh

This will:

1. Copy all backup scripts to /usr/local/bin/
2. Set execute permissions
3. Create log and state directories
4. Show next steps

Configure Backup

# Copy example config
sudo cp /usr/local/share/backup-setup/backup.conf.example /etc/backup.conf

# Edit configuration
sudo nvim /etc/backup.conf

Install Network Trigger (Optional)

# Install ZSH completion
sudo cp _backup-setup /usr/local/share/zsh/site-functions/

# Install network trigger service
sudo cp backup-trigger /usr/local/bin/
sudo chmod +x /usr/local/bin/backup-trigger
sudo cp backup-monitor /etc/init.d/
sudo chmod +x /etc/init.d/backup-monitor

# Enable at boot
sudo rc-update add backup-monitor default

# Start service
sudo rc-service backup-monitor start

Configuration

Basic Settings

Edit /etc/backup.conf:

# NAS Connection
NAS_HOST="192.168.2.171"
NAS_PORT="22"
NAS_USER="alexander"
NAS_PATH="/DATA/Backup/lenovo-gentoo-machine"

# Backup Settings
RETENTION_DAYS="30"
RETENTION_COUNT="10"
BACKUP_COOLDOWN="3600"  # 1 hour between backups

Exclusion Patterns

Add paths to exclude from backups:

EXCLUDE_PATTERNS=(
  "/dev/*"
  "/proc/*"
  "/sys/*"
  "/tmp/*"
  "/run/*"
  "/mnt/*"
  "/media/*"
  "/var/tmp/portage/*"
  "/var/cache/*"
  "/.cache/*"
  "/home/*/.cache/*"
  "/home/*/Downloads/*.iso"
)

Usage

Interactive Management

# 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

Examples

# Check backup status
$ backup-setup
========================================
Backup Status
========================================

Configuration:
  NAS: alexander@192.168.2.171:22
  Path: /DATA/Backup/lenovo-gentoo-machine

Last backup: 2025-11-07 20:48:32 (1h ago)

✓ NAS is reachable at alexander@192.168.2.171:22
✓ Available space on NAS: 2.1T

# Run config backup
$ backup-setup backup configs
ℹ Starting configs backup...
✓ Config backup completed successfully
  Backup size: 26MB
  Duration: 3s

# View logs
$ backup-setup logs
[2025-11-07 20:48:29] Starting config backup...
[2025-11-07 20:48:32] Backup completed: 26MB in 3s

Backup Types

1. Full System Backup

What it backs up: Entire system excluding caches and temporary files

Size: Large (depends on system, typically 20-50GB)

Duration: Long (20-60 minutes)

Use case: Complete system restore, major changes

backup-setup backup full

Exclusions:

• /dev, /proc, /sys, /tmp, /run
• /mnt, /media
• /var/tmp/portage/* (Portage build directory)
• /var/cache/*
• All .cache directories

2. Home Directory Backup

What it backs up: /home/alexander only

Size: Medium (depends on data, typically 10-50GB)

Duration: Medium (10-30 minutes)

Use case: Personal files, documents, projects

backup-setup backup home

Exclusions:

• .cache directories
• Browser caches
• Downloads/*.iso, Downloads/*.mp4, Downloads/*.mkv

3. Incremental Backup

What it backs up: Only changed files since last backup

Size: Small (only changes)

Duration: Fast (1-10 minutes)

Use case: Daily backups, minimal bandwidth

backup-setup backup incremental

How it works: Uses rsync's --link-dest to hardlink unchanged files, saving space and time.

4. Configuration Backup

What it backs up: System configs, dotfiles, scripts

Size: Tiny (typically <100MB)

Duration: Very fast (<1 minute)

Use case: Quick config snapshots, testing changes

backup-setup backup configs

Includes:

• /etc (system configuration)
• /home/alexander/.config (user configs)
• /home/alexander/.local (local data)
• /etc/portage (Gentoo package config)
• /usr/local/bin (custom scripts)
• /home/alexander/.zshrc, .bashrc, etc.

Network Trigger

How It Works

The network trigger monitors for NAS availability and automatically triggers backups when the NAS is detected. It has multiple safeguards to prevent backup spam:

1. Rate Limiting: Checks for NAS only every 5 minutes
2. Cooldown Period: Enforces minimum 1 hour between backups
3. Lock File Detection: Skips if another backup is running
4. In-Progress Marker: Tracks active backups
5. Stale Marker Cleanup: Removes markers older than 6 hours

Monitor Status

# Check service 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

Example Log Output

[2025-11-07 21:01:43] ==========================================
[2025-11-07 21:01:43] Backup monitor started
[2025-11-07 21:01:43] Monitoring for NAS: 192.168.2.171
[2025-11-07 21:01:43] Check interval: 5 minutes
[2025-11-07 21:01:43] Backup cooldown: 3600s (1h)
[2025-11-07 21:01:43] ==========================================
[2025-11-07 21:06:00] NAS is available at 192.168.2.171
[2025-11-07 21:06:00] Cooldown passed, backup allowed
[2025-11-07 21:06:00] NAS detected, triggering incremental backup...
[2025-11-07 21:06:00] Backup started in background (PID: 12345)

Service Management

# Start monitor
sudo rc-service backup-monitor start

# Stop monitor
sudo rc-service backup-monitor stop

# Restart monitor
sudo rc-service backup-monitor restart

# Enable at boot
sudo rc-update add backup-monitor default

# Disable at boot
sudo rc-update del backup-monitor default

Troubleshooting

Backup Fails with Permission Denied

Problem: Cannot write to log files or state files

Solution: Ensure directories exist and are writable:

mkdir -p ~/.local/var/log
mkdir -p ~/.local/var/backup
chmod 755 ~/.local/var/log
chmod 755 ~/.local/var/backup

Lock File Prevents Backup

Problem: Backup shows "already running" but no backup is active

Solution: Remove stale lock file:

rm /tmp/backup-*.lock

NAS Not Detected

Problem: Network trigger doesn't detect NAS

Check connection:

# Test ping
ping -c 3 192.168.2.171

# Test SSH
ssh alexander@192.168.2.171 "echo test"

# Check monitor logs
tail -20 ~/.local/var/log/backup-monitor.log

Verify config:

cat /etc/backup.conf

Backup Too Slow

Problem: Backup takes too long

Solutions:

1. Use incremental backup instead of full:

   backup-setup backup incremental
   

2. Add more exclusions to /etc/backup.conf:

   EXCLUDE_PATTERNS+=(
     "/home/*/Videos/*"
     "/home/*/Music/*"
     "/home/*/.local/share/Steam/*"
   )
   

3. Check network speed:

   # Test transfer speed
   dd if=/dev/zero bs=1M count=100 | \
     ssh alexander@192.168.2.171 "cat > /dev/null"
   

Cooldown Too Short/Long

Problem: Backups happen too frequently or not frequently enough

Solution: Adjust BACKUP_COOLDOWN in /etc/backup.conf:

# 30 minutes
BACKUP_COOLDOWN="1800"

# 2 hours
BACKUP_COOLDOWN="7200"

# 6 hours
BACKUP_COOLDOWN="21600"

Then restart the monitor:

sudo rc-service backup-monitor restart

Advanced Configuration

Custom Backup Schedules

Instead of using the network trigger, use cron for scheduled backups:

# Edit crontab
crontab -e

# Daily incremental at 2 AM
0 2 * * * /usr/local/bin/backup-incremental

# Weekly full backup on Sunday at 3 AM
0 3 * * 0 /usr/local/bin/backup-full

# Hourly config backup
0 * * * * /usr/local/bin/backup-configs

Multiple NAS Destinations

Create separate configs for different NAS hosts:

# Create configs
sudo cp /etc/backup.conf /etc/backup-nas1.conf
sudo cp /etc/backup.conf /etc/backup-nas2.conf

# Edit each config with different NAS_HOST and NAS_PATH

# Create wrapper scripts
cat > ~/.local/bin/backup-nas1 <<'EOF'
#!/bin/sh
CONFIG_FILE="/etc/backup-nas1.conf" /usr/local/bin/backup-incremental "$@"
EOF

cat > ~/.local/bin/backup-nas2 <<'EOF'
#!/bin/sh
CONFIG_FILE="/etc/backup-nas2.conf" /usr/local/bin/backup-incremental "$@"
EOF

chmod +x ~/.local/bin/backup-nas*

Backup Verification

Add verification to backup scripts by editing them:

# After rsync in any backup script, add:

# Verify backup
info "Verifying backup..."
if ssh -p "$NAS_PORT" "${NAS_USER}@${NAS_HOST}" \
  "test -d '$BACKUP_DEST' && du -sh '$BACKUP_DEST'"; then
  success "Backup verified"
else
  error "Backup verification failed"
  exit 1
fi

Email Notifications

Install and configure email notifications:

# Install mail client
emerge -av mail-client/mailx

# Add to backup scripts after completion:
echo "Backup completed at $(date)" | \
  mail -s "Backup: $HOSTNAME" your.email@example.com

Encryption

Encrypt backups using gpg before sending to NAS:

# Install gpg
emerge -av app-crypt/gnupg

# Generate key
gpg --gen-key

# Modify backup scripts to encrypt:
# Replace rsync command with:
tar czf - / --exclude-from=<(printf '%s\n' "${EXCLUDE_PATTERNS[@]}") | \
  gpg --encrypt --recipient your@email.com | \
  ssh -p "$NAS_PORT" "${NAS_USER}@${NAS_HOST}" \
    "cat > '$BACKUP_DEST/backup.tar.gz.gpg'"

Best Practices

1. Test Restores: Regularly test restoring from backups
2. Monitor Logs: Check backup logs weekly
3. Verify Space: Ensure NAS has adequate free space
4. Update Exclusions: Review and update exclusion patterns
5. Document Changes: Keep notes on backup configuration changes
6. 3-2-1 Rule: Keep 3 copies, on 2 media types, 1 offsite

See Also

• USER-GUIDE.md - Quick reference guide
• CLAUDE.md - System overview
• /etc/backup.conf - Backup configuration
• ~/.local/var/log/backup.log - Backup logs