38f2aefecd
- Add backup-pfsense-config.sh script for automated config backups via SSH - Auto-commits backups to git with timestamped filenames - Includes validation, error handling, and troubleshooting guides - Add scripts/README.md with detailed usage and crontab examples - Add BACKUP-QUICKSTART.md for quick reference commands - Update README.md to reference automated backup workflow - Create backups/ directory structure The script tests SSH connectivity successfully to pfSense.
227 lines
6.7 KiB
Markdown
227 lines
6.7 KiB
Markdown
# 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):**
|
|
```bash
|
|
cd pfsense.home.arpa
|
|
./scripts/backup-pfsense-config.sh
|
|
```
|
|
|
|
**Specify custom host:**
|
|
```bash
|
|
./scripts/backup-pfsense-config.sh 192.168.1.1
|
|
./scripts/backup-pfsense-config.sh pfsense.home.arpa
|
|
```
|
|
|
|
**Download without auto-committing to git:**
|
|
```bash
|
|
./scripts/backup-pfsense-config.sh --no-commit
|
|
# or
|
|
./scripts/backup-pfsense-config.sh -n
|
|
```
|
|
|
|
**Test SSH connectivity (dry-run):**
|
|
```bash
|
|
./scripts/backup-pfsense-config.sh --dry-run
|
|
```
|
|
|
|
**Show help:**
|
|
```bash
|
|
./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:**
|
|
```bash
|
|
crontab -e
|
|
```
|
|
|
|
2. **Add this line:**
|
|
```cron
|
|
0 2 * * * cd /Users/kenjim/workspace/src/personal/appa-net/pfsense.home.arpa && ./scripts/backup-pfsense-config.sh
|
|
```
|
|
|
|
3. **Verify the entry:**
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|