Add pfSense backup utility and documentation
- 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.
This commit is contained in:
Kenji Morishige
226
pfsense.home.arpa/scripts/README.md
Normal file
226
pfsense.home.arpa/scripts/README.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user