appa-net/pfsense.home.arpa/scripts

pfSense Backup Scripts

Automation utilities for backing up and managing pfSense configuration.

Scripts

backup-pfsense-config.sh

Automated backup utility that:

• Connects to your pfSense router via SSH (using public key authentication)
• Downloads the current configuration XML
• Validates the backup is a valid pfSense config
• Stores it in backups/ folder with a timestamped filename
• Automatically commits to git with a detailed message

Usage

Basic usage (default host):

cd pfsense.home.arpa
./scripts/backup-pfsense-config.sh

Specify custom host:

./scripts/backup-pfsense-config.sh 192.168.1.1
./scripts/backup-pfsense-config.sh pfsense.home.arpa

Download without auto-committing to git:

./scripts/backup-pfsense-config.sh --no-commit
# or
./scripts/backup-pfsense-config.sh -n

Test SSH connectivity (dry-run):

./scripts/backup-pfsense-config.sh --dry-run

Show help:

./scripts/backup-pfsense-config.sh --help
# or
./scripts/backup-pfsense-config.sh -h

Prerequisites

1. SSH Public Key Authentication

   • Your public key must be installed on pfSense
   • Run on pfSense: cat ~/.ssh/authorized_keys to verify
   • If not installed, manually copy your key: ssh-copy-id root@pfsense

2. SSH Host Configuration (recommended)

   • Add to your ~/.ssh/config:

     Host pfsense
       HostName 172.27.0.1  # or your pfSense IP
       User root
       IdentityFile ~/.ssh/id_rsa  # or your key path
     

   • This allows ssh pfsense to work directly

3. Git Repository

   • Must be run from within a git repository
   • The script auto-commits backups to git

4. Dependencies

   • bash (4.0+)
   • ssh and scp
   • git
   • du, shasum, grep (standard Unix utilities)

Features

• ✅ Automatic validation — Confirms backup is valid XML and contains pfSense markers
• ✅ Timestamped files — Format: pfsense-config-YYYY-MM-DD_HHMMSS.xml
• ✅ Rich git commits — Includes VLAN count, firewall rule count, SHA256 hash
• ✅ Error handling — Clear error messages and troubleshooting tips
• ✅ Dry-run mode — Test SSH connectivity without downloading
• ✅ Human-readable output — Color-coded info/warning/error messages
• ✅ Configurable — Via environment variables or command-line arguments

Example Output

╔════════════════════════════════════════════════════════════════╗
║       pfSense Configuration Backup Utility                    ║
╚════════════════════════════════════════════════════════════════╝

[INFO] Configuration:
  Host:        pfsense
  User:        root
  Remote path: /conf/config.xml
  Backup dir:  ./backups
  Auto-commit: true

[INFO] Checking prerequisites...
[✓] SSH is available
[✓] Git is available
[✓] Backup directory exists
[✓] Git repository found

[INFO] Testing SSH connection to pfsense...
[✓] SSH connection to pfsense successful

[INFO] Fetching pfSense configuration from pfsense...
[✓] Configuration downloaded to ./backups/pfsense-config-2026-04-22_143022.xml
[INFO] Backup size: 68K

[INFO] Validating backup file...
[✓] Backup file is valid XML with pfSense markers

[INFO] Committing backup to git repository...
[✓] Added backup to git staging area
[✓] Configuration committed to git

════════════════════════════════════════════════════════════════
[✓] pfSense configuration backup completed successfully!
════════════════════════════════════════════════════════════════

Backup Details:
  Location:     ./backups/pfsense-config-2026-04-22_143022.xml
  Size:         68K
  Timestamp:    2026-04-22_143022
  From:         root@pfsense:/conf/config.xml

Next Steps:
  1. Review the changes: git show HEAD
  2. Push to remote:    git push origin main
  3. Schedule automated backups in crontab

Scheduling Automated Backups

To backup your pfSense config automatically every day at 2 AM:

1. Edit your crontab:

   crontab -e
   

2. Add this line:

   0 2 * * * cd /Users/kenjim/workspace/src/personal/appa-net/pfsense.home.arpa && ./scripts/backup-pfsense-config.sh
   

3. Verify the entry:

   crontab -l | grep backup-pfsense
   

Now your config will be backed up automatically every day!

Troubleshooting

Problem	Solution
Permission denied (publickey)	Install public key: ssh-copy-id root@pfsense
Connection refused	Check pfSense IP/hostname is correct
No such file or directory: /conf/config.xml	Not running on pfSense; check SSH host
XML validation failed	Config may be corrupted; try manual backup via WebUI
Git commit fails	Ensure you're in the git repository root

Environment Variables

Control script behavior with environment variables:

# Use different SSH user
PFSENSE_USER=admin ./scripts/backup-pfsense-config.sh

# Disable auto-commit
AUTO_COMMIT=false ./scripts/backup-pfsense-config.sh

# Combine both
PFSENSE_USER=admin AUTO_COMMIT=false ./scripts/backup-pfsense-config.sh pfsense.home.arpa

Backup Files Location

All backups are stored in the backups/ directory:

backups/
├── pfsense-config-2026-04-22_143022.xml
├── pfsense-config-2026-04-21_023001.xml
└── pfsense-config-2026-04-20_023000.xml

Viewing Differences Between Backups

Compare two configurations:

# Show what changed between two backups
diff backups/pfsense-config-2026-04-22_143022.xml backups/pfsense-config-2026-04-21_023001.xml

# Or use git to see changes across commits
git log --oneline backups/
git diff HEAD~1..HEAD -- backups/pfsense-config-*.xml

Restoring from a Backup

To restore a previous configuration on pfSense:

1. Download the backup file from this repository
2. Log into pfSense WebUI
3. Go: Diagnostics → Backup & Restore
4. Choose the backup file and click Restore Configuration
5. Reboot when prompted

Future Enhancements

• Compress old backups to save space
• Upload to cloud storage (S3, etc.)
• Encrypt sensitive configs before storing
• Notify on significant changes (email alert)
• Generate change reports showing diffs

---

Last Updated: 2026-04-22