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.
2026-04-22 14:42:43 -05:00
commit 38f2aefecd
12 changed files with 2122 additions and 0 deletions
--- a/pfsense.home.arpa/INDEX.md
+++ b/pfsense.home.arpa/INDEX.md
@@ -0,0 +1,150 @@
+# pfsense.home.arpa Documentation Index
+
+Quick reference to all configuration files and guides in this folder.
+
+## Files in This Directory
+
+### 📘 **README.md** (Main Configuration Guide)
+Comprehensive reference for managing your pfSense router. Covers:
+- VLAN structure and definitions
+- Step-by-step configuration instructions
+- DHCP setup
+- Firewall rules and access control
+- Troubleshooting guide
+
+**When to read**: When you want detailed explanations or reference material  
+**Length**: ~400 lines (detailed)
+
+### ⚡ **VLAN-QUICKSTART.md** (Implementation Checklist)
+Step-by-step checklist to implement VLANs. Use this for hands-on setup.
+- Pre-implementation checklist
+- 6 phases with checkbox items
+- Testing procedures
+- Backup & documentation steps
+
+**When to read**: When actively configuring your pfSense  
+**Length**: ~300 lines (action-oriented)
+
+### 📊 **VLAN-CONFIG.md** (Configuration Reference)
+YAML-formatted configuration definitions and quick lookup.
+- VLAN definitions (IDs, subnets, purposes)
+- Firewall rule summary (matrix view)
+- DHCP configuration
+- Device assignments
+- Implementation checklist
+- Design rationale
+
+**When to read**: For quick lookup of VLAN IDs, subnet ranges, firewall rules  
+**Length**: ~150 lines (reference)
+
+### 🗺️ **VLAN-TOPOLOGY.md** (Visual Architecture)
+Network diagrams and traffic flow visualization.
+- High-level topology ASCII diagrams
+- Detailed dataflow examples
+- Firewall rule chain visualization
+- Port connectivity diagrams
+- Traffic examples (allowed and blocked)
+- Isolation guarantees
+
+**When to read**: To understand network architecture or debug traffic issues  
+**Length**: ~250 lines (visual/conceptual)
+
+## Quick Navigation
+
+**I want to...**
+
+| Task | File | Section |
+|------|------|---------|
+| Set up VLANs for the first time | VLAN-QUICKSTART.md | Phase 1-6 |
+| Understand VLAN architecture | VLAN-TOPOLOGY.md | High-Level Topology |
+| Look up a VLAN subnet | VLAN-CONFIG.md | VLAN Definitions |
+| Configure firewall rules | README.md | Step 4: Configure Firewall Rules |
+| Set up DHCP | README.md | Step 3: Configure DHCP |
+| Troubleshoot a problem | README.md | Troubleshooting section |
+| Debug traffic | VLAN-TOPOLOGY.md | Traffic Examples |
+| Backup my config | README.md | Backup & Recovery |
+| Add a new device to a VLAN | VLAN-CONFIG.md | Device Assignments |
+
+## File Relationships
+
+```
+README.md
+  ├─ Detailed explanation of all features
+  ├─ References: VLAN-CONFIG.md, VLAN-TOPOLOGY.md
+  └─ Use with: VLAN-QUICKSTART.md for hands-on setup
+
+VLAN-QUICKSTART.md
+  ├─ Step-by-step checklist
+  ├─ References: VLAN-CONFIG.md
+  └─ Use with: README.md for details
+
+VLAN-CONFIG.md
+  ├─ Quick reference data
+  ├─ Subnet/VLAN ID lookup
+  └─ Use with: README.md, VLAN-TOPOLOGY.md for context
+
+VLAN-TOPOLOGY.md
+  ├─ Visual architecture
+  ├─ Traffic flow examples
+  └─ Use with: README.md for firewall rule explanations
+```
+
+## Setup Workflow Recommended
+
+1. **Read** VLAN-TOPOLOGY.md (understand the architecture)
+2. **Review** VLAN-CONFIG.md (familiarize yourself with IDs and subnets)
+3. **Follow** VLAN-QUICKSTART.md (step-by-step implementation)
+4. **Reference** README.md (for detailed explanations during setup)
+5. **Store** backups/ folder (save pfSense XML configs here)
+
+## Directory Structure
+
+```
+pfsense.home.arpa/
+├── README.md                      # Main configuration guide
+├── VLAN-QUICKSTART.md            # Hands-on setup checklist
+├── VLAN-CONFIG.md                # VLAN reference data
+├── VLAN-TOPOLOGY.md              # Network diagrams
+├── INDEX.md                       # This file
+├── backups/                       # Store pfSense backups here
+│   └── pfsense-config-YYYY-MM-DD.xml
+└── scripts/                       # Optional: Automation scripts
+    └── (future: Ansible, Terraform, etc.)
+```
+
+## Backup Location
+
+All pfSense configuration exports should be saved to `backups/` folder:
+
+```bash
+# After exporting from pfSense WebUI:
+mv ~/Downloads/config.xml backups/pfsense-config-2026-04-22.xml
+git add backups/
+git commit -m "pfSense: Backup after VLAN configuration"
+```
+
+## Future Additions
+
+As your network grows, consider adding:
+
+- `FIREWALL-RULES.md` — Detailed firewall rule documentation
+- `DHCP-RESERVATIONS.md` — Static IP assignments for devices
+- `DNS-CONFIG.md` — DNS resolver and record configuration
+- `SCRIPTS/` — Ansible playbooks, Terraform configs, or backup scripts
+- `MIGRATION-GUIDE.md` — How to restore from backup or migrate to new pfSense instance
+
+## Version History
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2026-04-22 | 1.0 | Initial VLAN configuration (3 VLANs: Secure, AIWorkload, IoT) |
+
+## Related Documents
+
+- [Root README.md](../README.md) — Project overview
+- [zet.home.arpa/PROXY-SETUP.md](../zet.home.arpa/PROXY-SETUP.md) — Squid proxy on VLAN (future: will reference this VLAN config)
+
+---
+
+**Last Updated**: 2026-04-22  
+**Current Configuration Version**: 1.0