# 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