wiretastix

Backup and Recovery

How to backup and restore Wiretastix data, configuration, and state.

Regular backups are essential for any production system. This guide covers what to backup in Wiretastix, how to perform backups, and how to restore from them.

What to Backup

Wiretastix has several critical components that should be backed up regularly:

1. Database (Critical)

The database contains all your Wiretastix configuration and state:

  • Users and groups: User accounts, group memberships, OIDC mappings
  • Peers: All WireGuard peer configurations, keys, IP assignments
  • Rules: Network firewall rules and policies
  • API tokens: Authentication tokens for CLI/API access
  • Configuration values: Runtime configuration parameters
  • Audit logs: Historical data about changes and events

Database file locations:

  • SQLite: /var/lib/wiretastix/wiretastix.db (or configured path)
  • PostgreSQL: Managed by PostgreSQL, backup using pg_dump

Priority: CRITICAL - Loss means complete reconfiguration required

2. Configuration Files (Critical)

The main configuration file defines how Wiretastix operates:

  • Main config: /etc/wiretastix/wiretastix.yaml
    • Contains: Database connection, OIDC settings, network configuration
    • Sensitive: Contains client secrets, cookie secrets, private keys

Priority: CRITICAL - Loss requires manual reconfiguration

3. WireGuard Private Key (Critical)

The server’s WireGuard private key:

  • Embedded in config: If wireguard.pvtkey is in wiretastix.yaml
  • Separate file: If stored in a separate file (e.g., /etc/wiretastix/wg-private.key)

Priority: CRITICAL - Loss breaks all existing client configurations

4. TLS Certificates (Important)

If using custom TLS certificates:

  • Certificate files: /etc/wiretastix/certs/ (or configured path)
  • ACME/Let’s Encrypt: Certificates in cert-dir from config

Priority: IMPORTANT - Can be regenerated but causes temporary downtime

5. NFTables Configuration (Important)

Base firewall rules:

  • File: /etc/nftables.conf or configured path
  • Custom rules: Any additional nftables configuration

Priority: IMPORTANT - Can be recreated from documentation

6. Environment Files (Optional)

System service configuration:

  • Systemd environment: /etc/default/wiretastix
  • Docker environment: Environment variables in docker-compose.yml

Priority: OPTIONAL - Easy to recreate

Backup Strategies

Full Backup vs Incremental

Full Backup (Recommended):

  • Backs up entire database and all configuration files
  • Simple to restore
  • Larger storage requirements
  • Recommended frequency: Daily for production

Incremental Backup (Advanced):

  • Only backs up changes since last backup
  • More complex to restore
  • Efficient storage use
  • Recommended for large deployments with frequent changes

Backup Schedule Recommendations

Production environments:

  • Daily: Full database backup (automated)
  • Weekly: Full system backup including all files
  • Before changes: Manual backup before major updates
  • After changes: Verify backup after configuration changes

Development/testing:

  • Weekly: Full backup
  • Before major changes: Manual backup

Backup Procedures

SQLite Database Backup

SQLite databases are single files, making them simple to backup.

Method 1: Offline Backup (Safest)

Stop the service, copy the file, restart:

# Stop Wiretastix
sudo systemctl stop wiretastix

# Create backup directory
sudo mkdir -p /backup/wiretastix

# Backup database with timestamp
sudo cp /var/lib/wiretastix/wiretastix.db \
  /backup/wiretastix/wiretastix-$(date +%Y%m%d-%H%M%S).db

# Restart Wiretastix
sudo systemctl start wiretastix

# Verify backup
ls -lh /backup/wiretastix/

Method 2: Online Backup (For Running Systems)

Using SQLite’s backup API:

# Create backup while service is running
sqlite3 /var/lib/wiretastix/wiretastix.db \
  ".backup /backup/wiretastix/wiretastix-$(date +%Y%m%d-%H%M%S).db"

# Verify backup integrity
sqlite3 /backup/wiretastix/wiretastix-20250115-120000.db "PRAGMA integrity_check;"

If using Write-Ahead Logging (WAL mode, default in Wiretastix):

# Checkpoint WAL to consolidate
sqlite3 /var/lib/wiretastix/wiretastix.db "PRAGMA wal_checkpoint(FULL);"

# Then backup
sudo cp /var/lib/wiretastix/wiretastix.db \
  /backup/wiretastix/wiretastix-$(date +%Y%m%d-%H%M%S).db

PostgreSQL Database Backup

Method 1: Using pg_dump (Standard)

Full database backup:

# Create backup directory
sudo mkdir -p /backup/wiretastix

# Backup database
sudo -u postgres pg_dump wiretastix > \
  /backup/wiretastix/wiretastix-$(date +%Y%m%d-%H%M%S).sql

# Verify backup
ls -lh /backup/wiretastix/
head -20 /backup/wiretastix/wiretastix-20250115-120000.sql

Method 2: Custom Format (Compressed)

Smaller backup files:

sudo -u postgres pg_dump -Fc wiretastix > \
  /backup/wiretastix/wiretastix-$(date +%Y%m%d-%H%M%S).dump

Method 3: Docker PostgreSQL Backup

If running PostgreSQL in Docker:

docker compose exec -T postgres pg_dump -U wiretastix wiretastix > \
  /backup/wiretastix/wiretastix-$(date +%Y%m%d-%H%M%S).sql

Configuration Files Backup

Backup all configuration files together:

# Create backup with timestamp
sudo tar czf /backup/wiretastix/config-$(date +%Y%m%d-%H%M%S).tar.gz \
  /etc/wiretastix/ \
  /etc/nftables.conf \
  /etc/default/wiretastix

# For Docker setups
tar czf /backup/wiretastix/config-$(date +%Y%m%d-%H%M%S).tar.gz \
  config/ \
  docker-compose.yml

# Verify backup
tar tzf /backup/wiretastix/config-20250115-120000.tar.gz

Complete System Backup

Backup everything in one command:

#!/bin/bash
# complete-backup.sh

BACKUP_DIR="/backup/wiretastix"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
BACKUP_NAME="wiretastix-full-${TIMESTAMP}"

mkdir -p "${BACKUP_DIR}"

# Stop service for consistency (optional)
# systemctl stop wiretastix

# Backup database
if [ -f /var/lib/wiretastix/wiretastix.db ]; then
    # SQLite
    sqlite3 /var/lib/wiretastix/wiretastix.db \
      ".backup ${BACKUP_DIR}/${BACKUP_NAME}.db"
else
    # PostgreSQL
    sudo -u postgres pg_dump wiretastix > \
      "${BACKUP_DIR}/${BACKUP_NAME}.sql"
fi

# Backup configuration
tar czf "${BACKUP_DIR}/${BACKUP_NAME}-config.tar.gz" \
  /etc/wiretastix/ \
  /etc/nftables.conf \
  /etc/default/wiretastix \
  2>/dev/null

# Restart service if stopped
# systemctl start wiretastix

# Create checksum
cd "${BACKUP_DIR}"
sha256sum ${BACKUP_NAME}* > ${BACKUP_NAME}.sha256

echo "Backup completed: ${BACKUP_DIR}/${BACKUP_NAME}*"
ls -lh "${BACKUP_DIR}/${BACKUP_NAME}"*

Make it executable and run:

sudo chmod +x complete-backup.sh
sudo ./complete-backup.sh

Automated Backup Scripts

Daily Backup with Cron

Create a backup script:

sudo nano /usr/local/bin/wiretastix-backup.sh

Add content:

#!/bin/bash
set -e

BACKUP_DIR="/backup/wiretastix"
RETENTION_DAYS=30
TIMESTAMP=$(date +%Y%m%d-%H%M%S)

mkdir -p "${BACKUP_DIR}"

# Backup database
if [ -f /var/lib/wiretastix/wiretastix.db ]; then
    sqlite3 /var/lib/wiretastix/wiretastix.db \
      ".backup ${BACKUP_DIR}/wiretastix-${TIMESTAMP}.db"
else
    sudo -u postgres pg_dump wiretastix > \
      "${BACKUP_DIR}/wiretastix-${TIMESTAMP}.sql"
fi

# Backup config (weekly only - check day of week)
if [ $(date +%u) -eq 7 ]; then
    tar czf "${BACKUP_DIR}/config-${TIMESTAMP}.tar.gz" \
      /etc/wiretastix/ /etc/nftables.conf /etc/default/wiretastix 2>/dev/null
fi

# Remove old backups
find "${BACKUP_DIR}" -name "wiretastix-*.db" -mtime +${RETENTION_DAYS} -delete
find "${BACKUP_DIR}" -name "wiretastix-*.sql" -mtime +${RETENTION_DAYS} -delete
find "${BACKUP_DIR}" -name "config-*.tar.gz" -mtime +${RETENTION_DAYS} -delete

# Log completion
echo "$(date): Backup completed successfully" >> /var/log/wiretastix-backup.log

Make executable:

sudo chmod +x /usr/local/bin/wiretastix-backup.sh

Schedule with cron:

sudo crontab -e

Add line:

# Wiretastix daily backup at 2 AM
0 2 * * * /usr/local/bin/wiretastix-backup.sh

Docker Automated Backup

For Docker deployments:

#!/bin/bash
# docker-backup.sh

BACKUP_DIR="./backups"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)

mkdir -p "${BACKUP_DIR}"

# Backup PostgreSQL (if using)
docker compose exec -T postgres pg_dump -U wiretastix wiretastix > \
  "${BACKUP_DIR}/db-${TIMESTAMP}.sql"

# Backup SQLite (if using)
docker compose exec -T wiretastix sqlite3 /data/wiretastix.db \
  ".backup /tmp/backup.db" 2>/dev/null || true
docker compose cp wiretastix:/tmp/backup.db \
  "${BACKUP_DIR}/db-${TIMESTAMP}.db" 2>/dev/null || true

# Backup configuration
tar czf "${BACKUP_DIR}/config-${TIMESTAMP}.tar.gz" \
  config/ docker-compose.yml

# Cleanup old backups (30 days)
find "${BACKUP_DIR}" -name "*.sql" -mtime +30 -delete
find "${BACKUP_DIR}" -name "*.db" -mtime +30 -delete
find "${BACKUP_DIR}" -name "*.tar.gz" -mtime +30 -delete

echo "Backup completed: ${BACKUP_DIR}/*-${TIMESTAMP}*"

Backup Verification

Always verify your backups!

Verify SQLite Backup

# Check integrity
sqlite3 /backup/wiretastix/wiretastix-20250115-120000.db \
  "PRAGMA integrity_check;"

# Should output: ok

# Check tables exist
sqlite3 /backup/wiretastix/wiretastix-20250115-120000.db \
  ".tables"

# Check row counts
sqlite3 /backup/wiretastix/wiretastix-20250115-120000.db \
  "SELECT COUNT(*) FROM users; SELECT COUNT(*) FROM peers;"

Verify PostgreSQL Backup

# Check file is valid SQL
head -50 /backup/wiretastix/wiretastix-20250115-120000.sql

# Verify it's not corrupted
grep -q "PostgreSQL database dump complete" \
  /backup/wiretastix/wiretastix-20250115-120000.sql && \
  echo "Backup appears complete" || echo "Backup may be incomplete"

Periodically test restore in a non-production environment:

# Create test directory
mkdir -p /tmp/wiretastix-restore-test

# Restore to test location
cp /backup/wiretastix/wiretastix-20250115-120000.db \
  /tmp/wiretastix-restore-test/wiretastix.db

# Test database access
sqlite3 /tmp/wiretastix-restore-test/wiretastix.db \
  "SELECT COUNT(*) FROM users;"

# Cleanup
rm -rf /tmp/wiretastix-restore-test

Restore Procedures

Prerequisites for Restore

Before restoring:

  1. Stop Wiretastix service
  2. Backup current state (even if corrupted, for forensics)
  3. Verify backup file integrity
  4. Ensure sufficient disk space
  5. Have alternative access (don’t lock yourself out)

Restore SQLite Database

# Stop service
sudo systemctl stop wiretastix

# Backup current (corrupted) database
sudo mv /var/lib/wiretastix/wiretastix.db \
  /var/lib/wiretastix/wiretastix.db.broken

# Restore from backup
sudo cp /backup/wiretastix/wiretastix-20250115-120000.db \
  /var/lib/wiretastix/wiretastix.db

# Fix permissions
sudo chown wiretastix:wiretastix /var/lib/wiretastix/wiretastix.db
sudo chmod 644 /var/lib/wiretastix/wiretastix.db

# Verify restored database
sqlite3 /var/lib/wiretastix/wiretastix.db "PRAGMA integrity_check;"

# Start service
sudo systemctl start wiretastix

# Verify service started
sudo systemctl status wiretastix

Restore PostgreSQL Database

# Stop Wiretastix
sudo systemctl stop wiretastix

# Drop existing database (CAREFUL!)
sudo -u postgres psql -c "DROP DATABASE IF EXISTS wiretastix;"

# Recreate database
sudo -u postgres psql -c "CREATE DATABASE wiretastix OWNER wiretastix;"

# Restore from backup
sudo -u postgres psql wiretastix < \
  /backup/wiretastix/wiretastix-20250115-120000.sql

# Or for custom format:
sudo -u postgres pg_restore -d wiretastix \
  /backup/wiretastix/wiretastix-20250115-120000.dump

# Verify restore
sudo -u postgres psql -d wiretastix -c "\dt"

# Start Wiretastix
sudo systemctl start wiretastix

# Verify service
sudo systemctl status wiretastix

Restore Configuration Files

# Stop service
sudo systemctl stop wiretastix

# Backup current config
sudo mv /etc/wiretastix /etc/wiretastix.old

# Extract backup
sudo tar xzf /backup/wiretastix/config-20250115-120000.tar.gz -C /

# Fix permissions
sudo chown -R root:root /etc/wiretastix
sudo chmod 755 /etc/wiretastix
sudo chmod 644 /etc/wiretastix/wiretastix.yaml

# Restart service
sudo systemctl start wiretastix

# Verify
sudo systemctl status wiretastix

Docker Restore

For Docker deployments:

# Stop containers
docker compose down

# Restore database (PostgreSQL)
docker compose up -d postgres
docker compose exec -T postgres psql -U wiretastix wiretastix < \
  backups/db-20250115-120000.sql

# Restore SQLite
cp backups/db-20250115-120000.db data/wiretastix.db

# Restore configuration
tar xzf backups/config-20250115-120000.tar.gz

# Start all services
docker compose up -d

# Verify
docker compose ps
docker compose logs wiretastix

Disaster Recovery Scenarios

Scenario 1: Database Corruption

Symptoms: Service fails to start, database errors in logs

Recovery:

  1. Stop service
  2. Attempt SQLite recovery: sqlite3 wiretastix.db ".recover" | sqlite3 recovered.db
  3. If recovery fails, restore from backup
  4. Restart service

Scenario 2: Lost Configuration File

Symptoms: Service won’t start, missing configuration file

Recovery:

  1. Restore configuration from backup
  2. If no backup, recreate from documentation
  3. Regenerate secrets (OIDC cookie-secret, WireGuard key)
  4. Update OIDC provider with new settings
  5. Restart service

Scenario 3: Lost WireGuard Private Key

Symptoms: All clients can’t connect

Recovery:

  1. Generate new WireGuard private key
  2. Update configuration with new key
  3. Restart Wiretastix (new public key generated)
  4. All client configurations must be regenerated
  5. Distribute new configs to all users

Prevention: This is why backing up the private key is critical!

Scenario 4: Complete Server Loss

Symptoms: Server hardware failure, total data loss

Recovery:

  1. Install fresh operating system
  2. Install Wiretastix using preferred method
  3. Restore configuration files from backup
  4. Restore database from backup
  5. Verify WireGuard interface comes up
  6. Test client connectivity
  7. Verify Web UI access
  8. Check API functionality

Off-Site Backup Strategies

Cloud Storage

AWS S3 Example:

# Install AWS CLI
sudo apt-get install awscli

# Configure AWS credentials
aws configure

# Sync backups to S3
aws s3 sync /backup/wiretastix/ s3://my-bucket/wiretastix-backups/

# Or add to backup script
aws s3 cp /backup/wiretastix/wiretastix-${TIMESTAMP}.db \
  s3://my-bucket/wiretastix-backups/

Google Cloud Storage:

# Install gsutil
curl https://sdk.cloud.google.com | bash

# Upload backup
gsutil cp /backup/wiretastix/wiretastix-${TIMESTAMP}.db \
  gs://my-bucket/wiretastix-backups/

Remote Server (rsync)

# Sync backups to remote server
rsync -avz --delete \
  /backup/wiretastix/ \
  backup-server:/backups/wiretastix/

# Or over SSH
rsync -avz -e ssh \
  /backup/wiretastix/ \
  user@backup-server:/backups/wiretastix/

Encrypted Backups

For sensitive data, encrypt before uploading:

# Encrypt backup
gpg --symmetric --cipher-algo AES256 \
  /backup/wiretastix/wiretastix-${TIMESTAMP}.db

# Upload encrypted file
aws s3 cp /backup/wiretastix/wiretastix-${TIMESTAMP}.db.gpg \
  s3://my-bucket/wiretastix-backups/

# Decrypt when needed
gpg --decrypt wiretastix-${TIMESTAMP}.db.gpg > wiretastix.db

Backup Retention Policy

Recommended retention:

  • Daily backups: Keep for 7 days
  • Weekly backups: Keep for 4 weeks
  • Monthly backups: Keep for 12 months
  • Yearly backups: Keep for 3-5 years (compliance-dependent)

Implement in script:

# Remove daily backups older than 7 days
find /backup/wiretastix -name "wiretastix-*.db" -mtime +7 -delete

# Keep weekly backups (Sundays)
# ... (implement logic to keep Sundays for 4 weeks)

# Keep monthly backups (1st of month)
# ... (implement logic to keep 1st for 12 months)

Backup Checklist

Use this checklist for regular backup verification:

  • Database backup completed
  • Configuration files backed up
  • Backup file integrity verified
  • Backup file size is reasonable (not 0 bytes)
  • Backup stored in safe location
  • Off-site backup completed (if applicable)
  • Backup retention policy applied
  • Test restore performed (monthly)
  • Backup script logs checked
  • Backup storage capacity sufficient

Security Considerations

  1. Protect backup files: Backups contain sensitive data (secrets, keys, user data)
  2. Restrict access: Only authorized personnel should access backups
  3. Encrypt backups: Especially for off-site storage
  4. Secure transfer: Use encrypted channels (SSH, HTTPS)
  5. Test restores: Verify you can actually restore when needed
  6. Document procedures: Ensure team knows how to restore
  7. Audit access: Log who accesses backup files
  8. Compliance: Follow data retention regulations in your jurisdiction