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
296
pfsense.home.arpa/README.md
Normal file
296
pfsense.home.arpa/README.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# pfSense Router Configuration
|
||||
|
||||
Central hub for your home network. Manages DHCP, DNS, routing, firewalling, and network segmentation via VLANs.
|
||||
|
||||
## Overview
|
||||
|
||||
**Device**: pfSense Router
|
||||
**Primary IP**: 172.27.0.1 (LAN default gateway)
|
||||
**Role**: Router, Firewall, DHCP server, DNS resolver, VLAN orchestration
|
||||
|
||||
## Network Architecture
|
||||
|
||||
Your home network is segmented into security zones using VLANs. Each VLAN has:
|
||||
- Isolated broadcast domain
|
||||
- Separate IP subnet
|
||||
- Controlled routing and firewall rules between VLANs
|
||||
- Dedicated DHCP scope (if needed)
|
||||
|
||||
### VLAN Structure
|
||||
|
||||
| VLAN ID | Name | Purpose | Subnet | Gateway | Notes |
|
||||
|---------|------|---------|--------|---------|-------|
|
||||
| 1 | `LAN_SECURE` | Trusted personal devices | 172.27.0.0/24 | 172.27.0.1 | Primary network (default) |
|
||||
| 2 | `VLAN_AIWORKLOAD` | AI/ML dangerous workloads (openclaw) | 172.27.2.0/24 | 172.27.2.1 | Isolated, minimal internet access |
|
||||
| 3 | `VLAN_IOT` | IoT devices (cameras, smart home) | 172.27.3.0/24 | 172.27.3.1 | Limited trust, blocked from LAN_SECURE |
|
||||
|
||||
## Configuration Steps
|
||||
|
||||
### Prerequisites
|
||||
- Access to pfSense WebUI or SSH
|
||||
- Understanding of your network hardware (which ports support VLANs)
|
||||
|
||||
### Step 1: Create VLANs on Physical Interface
|
||||
|
||||
1. Navigate: **Interfaces → VLANs**
|
||||
2. Click **+ Add**
|
||||
3. Create `VLAN_AIWORKLOAD`:
|
||||
- **Parent Interface**: `em0` (or your LAN NIC)
|
||||
- **VLAN Tag**: `2`
|
||||
- **VLAN Priority**: `0` (default)
|
||||
- **Description**: `VLAN_AIWORKLOAD`
|
||||
- Click **Save**
|
||||
|
||||
4. Create `VLAN_IOT`:
|
||||
- **Parent Interface**: `em0`
|
||||
- **VLAN Tag**: `3`
|
||||
- **VLAN Priority**: `0`
|
||||
- **Description**: `VLAN_IOT`
|
||||
- Click **Save**
|
||||
|
||||
5. Click **Apply Changes**
|
||||
|
||||
### Step 2: Create Virtual Interfaces
|
||||
|
||||
1. Navigate: **Interfaces → Assignments**
|
||||
2. Click **+ Add** next to `VLAN_AIWORKLOAD_2`:
|
||||
- A new interface (e.g., `OPT1`) is created automatically
|
||||
- Click the pencil icon to configure it
|
||||
|
||||
3. Configure `OPT1` (VLAN_AIWORKLOAD):
|
||||
- **Enable Interface**: ✓ Checked
|
||||
- **Description**: `VLAN_AIWORKLOAD`
|
||||
- **IPv4 Configuration Type**: `Static IPv4`
|
||||
- **IPv4 Address**: `172.27.2.1`
|
||||
- **IPv4 Subnet Mask**: `255.255.255.0` (/24)
|
||||
- Click **Save**
|
||||
|
||||
4. Repeat for `VLAN_IOT_3`:
|
||||
- Configure as `OPT2`
|
||||
- **Description**: `VLAN_IOT`
|
||||
- **IPv4 Address**: `172.27.3.1`
|
||||
- **IPv4 Subnet Mask**: `255.255.255.0` (/24)
|
||||
- Click **Save**
|
||||
|
||||
5. Click **Apply Changes**
|
||||
|
||||
### Step 3: Configure DHCP for Each VLAN
|
||||
|
||||
#### VLAN_AIWORKLOAD DHCP
|
||||
1. Navigate: **Services → DHCP Server**
|
||||
2. Click the **VLAN_AIWORKLOAD** tab
|
||||
3. **Enable DHCP server on VLAN_AIWORKLOAD interface**: ✓ Checked
|
||||
4. **Range**: `172.27.2.100` to `172.27.2.200`
|
||||
5. **Gateway**: `172.27.2.1`
|
||||
6. **Servers**:
|
||||
- DNS 1: `172.27.0.1` (pfSense resolver)
|
||||
- DNS 2: `8.8.8.8` (optional fallback)
|
||||
7. Click **Save**
|
||||
|
||||
#### VLAN_IOT DHCP
|
||||
1. Click the **VLAN_IOT** tab
|
||||
2. **Enable DHCP server on VLAN_IOT interface**: ✓ Checked
|
||||
3. **Range**: `172.27.3.100` to `172.27.3.200`
|
||||
4. **Gateway**: `172.27.3.1`
|
||||
5. **Servers**:
|
||||
- DNS 1: `172.27.0.1`
|
||||
- DNS 2: `8.8.8.8`
|
||||
6. Click **Save**
|
||||
|
||||
### Step 4: Configure Firewall Rules
|
||||
|
||||
#### Allow WAN → All VLANs
|
||||
Navigate: **Firewall → Rules → WAN**
|
||||
- Default rule should allow established connections
|
||||
|
||||
#### Default LAN → VLAN Rules
|
||||
Navigate: **Firewall → Rules → LAN_SECURE**
|
||||
|
||||
1. **Allow LAN_SECURE → VLAN_AIWORKLOAD** (if needed):
|
||||
- Action: `Pass`
|
||||
- Interface: `LAN`
|
||||
- Direction: `in`
|
||||
- Source: `LAN_SECURE subnet`
|
||||
- Destination: `VLAN_AIWORKLOAD subnet`
|
||||
- Click **Save**
|
||||
|
||||
2. **Block LAN_SECURE ↔ VLAN_IOT** (by default, implicit deny):
|
||||
- *No rule needed* — VLANs are isolated by default
|
||||
- Optionally add explicit block rule for security
|
||||
|
||||
#### VLAN_AIWORKLOAD Rules
|
||||
Navigate: **Firewall → Rules → VLAN_AIWORKLOAD**
|
||||
|
||||
1. **Allow VLAN_AIWORKLOAD → WAN** (for outbound internet):
|
||||
- Action: `Pass`
|
||||
- Source: `VLAN_AIWORKLOAD subnet`
|
||||
- Destination: `any`
|
||||
- Protocol: `TCP/UDP`
|
||||
- Click **Save**
|
||||
|
||||
2. **Block VLAN_AIWORKLOAD → LAN_SECURE**:
|
||||
- Action: `Block`
|
||||
- Source: `VLAN_AIWORKLOAD subnet`
|
||||
- Destination: `LAN_SECURE subnet`
|
||||
- Click **Save**
|
||||
|
||||
#### VLAN_IOT Rules
|
||||
Navigate: **Firewall → Rules → VLAN_IOT**
|
||||
|
||||
1. **Allow VLAN_IOT → WAN** (for NTP, updates, cloud APIs):
|
||||
- Action: `Pass`
|
||||
- Source: `VLAN_IOT subnet`
|
||||
- Destination: `any`
|
||||
- Protocol: `TCP/UDP`
|
||||
- Click **Save**
|
||||
|
||||
2. **Block VLAN_IOT → LAN_SECURE**:
|
||||
- Action: `Block`
|
||||
- Source: `VLAN_IOT subnet`
|
||||
- Destination: `LAN_SECURE subnet`
|
||||
- Click **Save**
|
||||
|
||||
3. **Block VLAN_IOT → VLAN_AIWORKLOAD** (optional):
|
||||
- Action: `Block`
|
||||
- Source: `VLAN_IOT subnet`
|
||||
- Destination: `VLAN_AIWORKLOAD subnet`
|
||||
- Click **Save**
|
||||
|
||||
### Step 5: Configure Port Assignments (If Hardware Supports)
|
||||
|
||||
If your switch/NIC supports physical VLAN tagging:
|
||||
|
||||
Navigate: **Interfaces → Physical Ports** (varies by pfSense version)
|
||||
|
||||
Example configuration:
|
||||
- **Port 1**: LAN_SECURE (VLAN 1, untagged)
|
||||
- **Port 2**: VLAN_AIWORKLOAD (VLAN 2, tagged)
|
||||
- **Port 3**: VLAN_IOT (VLAN 3, tagged)
|
||||
- **Port 4**: WAN
|
||||
|
||||
*This step depends on your hardware. If using a managed switch, configure VLAN tagging there instead.*
|
||||
|
||||
## Network Access Matrix
|
||||
|
||||
Shows which VLANs can reach which destinations:
|
||||
|
||||
```
|
||||
FROM TO_LAN_SECURE TO_AIWORKLOAD TO_IOT TO_WAN
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
LAN_SECURE ✓ (same) ✗ BLOCK ✗ BLOCK ✓
|
||||
VLAN_AIWORKLOAD ✗ BLOCK ✓ (same) ✗ BLOCK ✓
|
||||
VLAN_IOT ✗ BLOCK ✗ BLOCK ✓ (same) ✓
|
||||
```
|
||||
|
||||
## Device Assignment
|
||||
|
||||
Assign devices to VLANs via:
|
||||
|
||||
1. **DHCP reservations** (Recommended):
|
||||
- Navigate: **Services → DHCP Server**
|
||||
- Tab: Desired VLAN
|
||||
- Scroll to **DHCP Static Mappings**
|
||||
- Add device MAC → static IP in that VLAN
|
||||
- Example: Openclaw server → `172.27.2.50` (VLAN_AIWORKLOAD)
|
||||
|
||||
2. **Manual static configuration**:
|
||||
- Configure device IP in the target VLAN subnet
|
||||
- Set gateway to VLAN gateway (172.27.2.1, 172.27.3.1, etc.)
|
||||
|
||||
3. **Switch port assignment** (if hardware supports):
|
||||
- Assign physical switch ports to VLANs
|
||||
- Devices connected to those ports get VLAN membership
|
||||
|
||||
## DNS Configuration
|
||||
|
||||
Navigate: **Services → DNS Resolver**
|
||||
|
||||
1. **Enable DNS Resolver**: ✓ Checked
|
||||
2. **Network Interfaces**: Select all interfaces (LAN, VLAN_AIWORKLOAD, VLAN_IOT)
|
||||
3. **Forward Mode**: Check if needed for external DNS
|
||||
4. **Access Lists**:
|
||||
- Ensure all VLANs can query DNS on their gateways
|
||||
|
||||
This allows devices in each VLAN to resolve hostnames locally.
|
||||
|
||||
## Backup & Recovery
|
||||
|
||||
### Automated Backup (Recommended)
|
||||
|
||||
Use the included backup utility script for automated, versioned backups:
|
||||
|
||||
```bash
|
||||
cd pfsense.home.arpa
|
||||
./scripts/backup-pfsense-config.sh
|
||||
```
|
||||
|
||||
This script:
|
||||
- Connects to pfSense via SSH (using your public key)
|
||||
- Downloads the current configuration XML
|
||||
- Validates it's a valid pfSense config
|
||||
- Stores it in `backups/` with a timestamped filename
|
||||
- Automatically commits to git with configuration details
|
||||
|
||||
**Schedule automated daily backups:**
|
||||
```bash
|
||||
# Add to crontab (backups every day at 2 AM)
|
||||
0 2 * * * cd /path/to/appa-net/pfsense.home.arpa && ./scripts/backup-pfsense-config.sh
|
||||
```
|
||||
|
||||
For more details, see: [scripts/README.md](scripts/README.md)
|
||||
|
||||
### Manual Backup
|
||||
|
||||
If you prefer manual backups or SSH isn't available:
|
||||
|
||||
1. Navigate: **Diagnostics → Backup & Restore**
|
||||
2. Click **Download configuration as XML**
|
||||
3. Save to: `pfsense.home.arpa/backups/pfsense-config-YYYY-MM-DD.xml`
|
||||
4. Commit manually:
|
||||
```bash
|
||||
git add backups/pfsense-config-2026-04-22.xml
|
||||
git commit -m "pfSense: Backup configuration (manual)"
|
||||
git push
|
||||
```
|
||||
|
||||
### Restoring Configuration
|
||||
|
||||
1. Navigate: **Diagnostics → Backup & Restore**
|
||||
2. Click **Choose File** and select XML backup
|
||||
3. Click **Restore Configuration**
|
||||
4. Reboot when prompted
|
||||
|
||||
## Maintenance Tasks
|
||||
|
||||
- **Monthly**: Export and backup pfSense configuration
|
||||
- **Quarterly**: Review firewall rules and DHCP assignments
|
||||
- **As needed**: Adjust rules based on new devices or requirements
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### VLANs not working:
|
||||
- Verify VLAN tags are correct in Interfaces → VLANs
|
||||
- Ensure virtual interfaces are enabled (Interfaces → Assignments)
|
||||
- Check physical switch VLAN configuration if using managed switch
|
||||
|
||||
### Devices can't get DHCP:
|
||||
- Verify DHCP is enabled for the VLAN
|
||||
- Check DHCP range is correct
|
||||
- Inspect DHCP leases: **Status → DHCP Leases**
|
||||
|
||||
### Can't ping between VLANs (expected):
|
||||
- Verify firewall rules are allowing or blocking as desired
|
||||
- Check rule order (first match wins)
|
||||
- Use **Diagnostics → Packet Capture** to debug
|
||||
|
||||
## References
|
||||
|
||||
- [pfSense VLAN Documentation](https://docs.netgate.com/pfsense/en/latest/vlan/index.html)
|
||||
- [pfSense Firewall Rules](https://docs.netgate.com/pfsense/en/latest/firewall/index.html)
|
||||
- RFC 2644 — VLAN tagging
|
||||
- RFC 5735 — Special Use IPv4 Addresses
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-04-22
|
||||
**Configuration Version:** 1.0
|
||||
Reference in New Issue
Block a user