Pfsense

---
name: pfsense
description: "Expert coverage of pfSense (Plus and CE) across all versions: FreeBSD pf packet filter, CARP high availability, OpenVPN/WireGuard/IPsec, pfBlockerNG, Suricata/Snort IDS/IPS, ALTQ/limiters traffic shaping, Netgate hardware, package system, and WebGUI administration. Use for \"pfSense\", \"Netgate\", \"pfBlockerNG\", \"CARP HA\", \"pfsync\", \"ALTQ\", \"pfSense Plus\", \"pfSense CE\", \"Netgate 4100\", \"Netgate 6100\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `firewall` skill."
license: MIT
---

# pfSense

This skill covers pfSense (Plus and CE) across all supported versions (CE 2.7.x/2.8.x, Plus 24.x/25.x). Areas of expertise include:

- FreeBSD base OS and pf (packet filter) firewall engine
- WebGUI administration, dashboard customization, diagnostics
- Per-interface firewall rules with first-match evaluation
- Aliases (IP, network, port, URL table) for scalable rule design
- Floating rules for cross-interface policy
- NAT (port forward, outbound, 1:1, reflection)
- CARP high availability with pfsync state synchronization
- VPN (OpenVPN, WireGuard, IPsec with strongSwan)
- Package ecosystem (pfBlockerNG, Suricata, Snort, HAProxy, Squid)
- Traffic shaping (ALTQ, limiters/dummynet)
- VLAN trunking and inter-VLAN routing
- Netgate hardware platforms

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Use diagnostics (packet capture, states, logs, routing table)
   - **Policy design** -- Apply per-interface rules, aliases, floating rules
   - **Architecture** -- Load `references/architecture.md` for FreeBSD, pf, CARP, packages, hardware
   - **VPN** -- OpenVPN, WireGuard, or IPsec configuration
   - **Package configuration** -- pfBlockerNG, Suricata, Snort, HAProxy

2. **Identify edition and version** -- pfSense Plus vs CE matters. Plus gets features first, runs on Netgate hardware, has commercial support. CE is community-supported.

3. **Load context** -- Read the reference file for deep knowledge.

4. **Analyze** -- Apply pfSense-specific reasoning. The pf firewall engine behaves differently from commercial NGFWs (per-interface, first-match, stateful by default).

5. **Recommend** -- Provide guidance with WebGUI paths and pf rule logic.

6. **Verify** -- Suggest validation via packet capture, state table, pfTop, logs.

## Core Architecture: FreeBSD + pf

pfSense builds on FreeBSD, using **pf (packet filter)** as the underlying firewall engine:

- **pf** processes all firewall rules and NAT; pfSense wraps it with a PHP/HTML WebGUI
- Stateful inspection by default; connection state tracked for TCP/UDP/ICMP
- ZFS support for root filesystem (recommended)
- All configuration stored in `/conf/config.xml` (XML); versioned config history

## Firewall Rules

### Per-Interface Rules
- Rules defined **per interface** (LAN, WAN, OPT1, etc.)
- Evaluated **top-down, first-match wins**
- Stateful by default; return traffic automatically permitted
- Each interface tab shows only rules for that interface

### Rule Components
- **Source/Destination** -- Single host, alias (group), network, FQDN (resolved at rule load)
- **Aliases** -- Named groups of IPs, networks, or ports; single alias reference in rules; updated via WebGUI, API, or URL table import
- **Service/Port** -- Individual port, port range, or alias
- **Schedule** -- Apply rules during defined time windows
- **Advanced options** -- TCP flags, OS fingerprinting, max connections, gateway override

### Floating Rules
- Applied across all interfaces or selected interfaces
- Support bidirectional match and `quick` keyword for early exit
- Processed before per-interface rules
- Use cases: global policies, traffic tagging for QoS

### Anti-Lockout Rule
- Built-in rule preventing admin lockout from WebGUI
- Active on LAN by default; disable only with console access available

## NAT

### Port Forward (Destination NAT)
- Maps external port to internal host:port for inbound services
- Auto-creates associated firewall rule (can be manually managed instead)
- Supports port/IP ranges and 1:many mappings

### Outbound NAT
Four modes:
1. **Automatic** -- pfSense generates outbound NAT rules for all internal subnets (default)
2. **Hybrid** -- Auto rules + manual additions (recommended for customization)
3. **Manual** -- Full admin control; no auto-generated rules
4. **Disabled** -- No outbound NAT

### 1:1 NAT
- Bidirectional static mapping of external IP to internal IP
- All ports translated; no port restriction

### NAT Reflection
- Allows internal hosts to reach port forwards using the external IP/FQDN
- Modes: NAT+proxy, Pure NAT (pf), Disabled
- NAT+proxy is most compatible; Pure NAT is more efficient

## VPN

### OpenVPN
- SSL/TLS-based; client-to-site and site-to-site modes
- Full PKI via pfSense's integrated Certificate Manager
- Multiple concurrent servers/clients
- **OpenVPN Client Export** package generates platform-specific configs
- IPv4/IPv6 dual-stack tunnels

### WireGuard
- Built into pfSense Plus; modern crypto (Curve25519, ChaCha20-Poly1305, BLAKE2s)
- Site-to-site and road warrior modes
- Lower CPU overhead and faster handshake than OpenVPN
- GUI and API managed; peers treated as firewall aliases

### IPsec (strongSwan)
- IKEv1 (aggressive/main mode) and IKEv2
- PSK or certificate (EAP, RSA) authentication
- Phase 1 / Phase 2 fully configurable from WebGUI
- Mobile IPsec for iOS/Android/Windows native clients
- Route-based (VTI) and policy-based modes

## CARP High Availability

**CARP (Common Address Redundancy Protocol)** provides pfSense HA:

### Architecture
- **Virtual IPs (VIPs)** -- Shared IPs floated between active and standby nodes
- **Master/Backup election** -- Based on advertisement skew; lowest skew = master
- **pfsync** -- Synchronizes firewall state tables over dedicated sync interface
- **Config Sync (XMLRPC)** -- Primary pushes full config to secondary

### Design Rules
- Dedicated physical link for pfsync (never share with production)
- Each node needs its own IP on every interface plus the shared CARP VIP
- Three IPs per interface minimum: node1, node2, CARP VIP
- Firewall rules reference CARP VIPs, not individual node IPs

### Failover
- CARP advertisement timeout triggers failover
- Configurable preempt and demotion counters
- pfsync ensures stateful failover (established connections survive)
- Active/passive only; no built-in active/active (use HAProxy for L7 load balancing)

## Packages

### pfBlockerNG
- DNS-based (DNSBL) and IP-based blocking
- Integrates with Unbound DNS Resolver for DNS sinkhole
- GeoIP blocking via MaxMind database
- Ad/tracking/malware domain blocking
- Customizable block page; Python-based v3 with performance improvements

### Suricata
- Full IDS/IPS; inline mode (blocks) or IDS mode (alerts)
- Rules: Emerging Threats, Snort Community, custom
- EVE JSON logging for SIEM integration
- Per-interface assignment; multiple instances

### Snort
- Alternative IDS/IPS; NFQUEUE inline or promiscuous mode
- Older but widely supported rule ecosystem

### HAProxy
- L7 load balancer and reverse proxy
- SSL termination, ACL-based routing, health checks, sticky sessions
- Common for publishing internal services with TLS

### Squid
- HTTP/HTTPS caching proxy
- SSL inspection (bump) for HTTPS visibility
- SquidGuard for URL categorization
- WCCP for transparent proxy

## Traffic Shaping

### ALTQ (Legacy)
- BSD-native queuing: HFSC, PRIQ, CBQ, FAIRQ
- Per-interface; flow classification via firewall rules with assigned queues
- **Limitation**: Does not work with multi-queue NICs or LAGG
- Best for simple QoS on single-queue interfaces

### Limiters (dummynet)
- Per-connection or per-IP bandwidth caps
- Download and upload limits set separately
- Applied via firewall rule advanced options
- More compatible with modern NICs; simpler than ALTQ
- Use case: fair bandwidth sharing, guest network throttling

## VLAN

- 802.1Q VLAN tagging on any physical interface
- Each VLAN assigned as a pfSense interface with its own firewall rules, DHCP, DNS
- Inter-VLAN routing through pfSense (L3 gateway)
- VLAN filtering tested and supported on Netgate hardware

## Netgate Hardware

| Model | Target | Key Specs |
|---|---|---|
| 1100 / 2100 | SOHO/Branch | ARM-based; fanless |
| 4100 | SMB | Intel; 2.5 GbE ports |
| 6100 | Mid-range | Intel; 10 GbE SFP+ |
| 7100 / 8200 | Enterprise | Multi-core x86; SFP+ |
| 1537 / 1541 | DC edge | Dual PSU; up to 25 GbE |

All ship pre-loaded with pfSense Plus; Netgate Global Support available.

## Diagnostics

### Packet Capture
- WebGUI: Diagnostics > Packet Capture (tcpdump wrapper)
- Filter by interface, protocol, host, port
- Download pcap for Wireshark analysis

### States
- WebGUI: Diagnostics > States
- Filter by source/destination; view active connections
- `pfctl -s state` from CLI

### Firewall Logs
- WebGUI: Status > System Logs > Firewall
- Filter by interface, action (pass/block), source, destination
- Real-time log view available

### pfTop
- Real-time connection monitoring
- Sort by bytes, packets, age, source, destination
- `pftop` from SSH/console

### Other Tools
- `pfctl -sr` -- Show active pf rules
- `pfctl -ss` -- Show state table
- `pfctl -si` -- Show pf statistics
- `netstat -rn` -- Routing table
- Diagnostics > Traceroute, Ping, DNS Lookup from WebGUI

## Common Pitfalls

1. **Rules on wrong interface** -- pf evaluates rules on the interface where traffic enters. Inbound internet traffic matches WAN rules, not LAN rules.

2. **Alias not updating** -- FQDN aliases resolve at rule load time. URL table aliases update on schedule. If IP changed, force alias update or use URL table.

3. **NAT reflection not working** -- Must be enabled per port forward AND system-wide (System > Advanced > Firewall & NAT). Use NAT+proxy mode for broadest compatibility.

4. **CARP without dedicated sync interface** -- pfsync over production interfaces causes state corruption risk. Always use a dedicated crossover cable or VLAN.

5. **ALTQ on multi-queue NIC** -- ALTQ does not work with multi-queue NICs. Use limiters (dummynet) instead, or disable multi-queue in NIC settings.

6. **Package conflicts** -- Running both Suricata and Snort on the same interface causes conflicts. Choose one IDS/IPS per interface.

7. **Outbound NAT mode confusion** -- Switching from Automatic to Manual without recreating rules breaks outbound connectivity. Use Hybrid mode to add rules without losing auto-generated ones.

8. **pfBlockerNG DNSBL with non-Unbound DNS** -- DNSBL requires Unbound as the DNS resolver. If using DNS Forwarder (dnsmasq), DNSBL will not function.

## Reference Files

Load these when you need deep knowledge:

- `references/architecture.md` -- FreeBSD, pf internals, packages, CARP HA, ALTQ, Netgate hardware. Read for "how does X work" questions.