# 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