kenjim/appa-net
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
38f2aefecd92968f3ba3addc3bf791b30c9a76a8
appa-net/pfsense.home.arpa/README.md
Kenji Morishige 38f2aefecd 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

297 lines
9.0 KiB
Markdown
Raw Blame History

# 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 View Git Blame Copy Permalink