# 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