appa-net/pfsense.home.arpa/README.md

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:

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:

# 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

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:

   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
• pfSense Firewall Rules
• RFC 2644 — VLAN tagging
• RFC 5735 — Special Use IPv4 Addresses

---

Last Updated: 2026-04-22
Configuration Version: 1.0