OPNsense Technology Expert

Core Architecture: HardenedBSD + MVC/API

HardenedBSD Base

OPNsense uses HardenedBSD (security-hardened FreeBSD fork):

• SafeStack -- Compiler-based protection against stack-based control-flow attacks
• W^X enforcement -- Memory regions cannot be simultaneously writable and executable
• ASLR -- Stronger address space layout randomization than stock FreeBSD
• PIE -- All system binaries compiled as position-independent executables
• CFI (Control Flow Integrity) -- Forward-edge CFI on key binaries
• RELRO -- ELF hardening (relocation read-only)
• Security patches tracked independently; often faster than upstream FreeBSD

MVC/API Architecture

OPNsense's distinguishing characteristic:

• Backend -- PHP 8.x MVC framework with Phalcon
• Configuration -- Structured XML (/conf/config.xml)
• REST API -- Nearly every configuration domain exposed as API endpoints
• Authentication -- API key + API secret (HMAC); per-user key generation
• Format -- JSON request/response; RESTful HTTP methods

API Coverage (26.1): Firewall rules, NAT, aliases, interfaces, routing, VPN (IPsec, OpenVPN, WireGuard), DHCP, DNS (Unbound), IDS/IPS (Suricata), certificates, users, High Availability.

Firewall Rules

MVC-Based Rules (26.1)

• Automation rules promoted to new MVC-based GUI
• Full API management of all firewall rules
• Rules evaluated on ingress interface; top-down, first-match (pf engine)
• Stateful by default; return traffic auto-permitted
• Rule associations removed (26.1) -- Legacy associated rule links replaced by independent editable rules

Rule Components

• Source/destination: IP, network, alias, FQDN
• Service: port, port range, alias
• Interface assignment
• Direction: in/out
• Protocol matching
• Schedule support
• Gateway override for policy-based routing

NAT

• Destination NAT -- Renamed from "Port Forwarding" in 26.1 for accuracy
• Outbound NAT -- Automatic, Hybrid, Manual modes (same as pf-based systems)
• 1:1 NAT -- Bidirectional static mapping
• All NAT fully API-manageable in 26.1

Suricata v8 Inline IPS

OPNsense integrates Suricata v8 as the primary IDS/IPS engine:

Inline Mode (divert)

• OPNsense 26.1 uses FreeBSD divert sockets for true inline operation
• Suricata can drop AND modify packets (not just alert or drop)
• Significantly more efficient than prior NFQUEUE approach
• Per-interface assignment; multiple instances supported

IDS Mode

• Promiscuous capture; alerts only, no blocking
• Lower performance impact; useful for initial deployment and tuning

Rule Sources

• Emerging Threats Open/Pro
• OISF Suricata rules
• abuse.ch feeds (malware, botnet, SSL blacklist)
• Custom rules

EVE JSON Logging

• Structured log output for SIEM integration
• Supports ELK Stack, Graylog, Splunk via syslog
• Flow and file extraction from HTTP/FTP/SMTP

Unbound DNS

Default DNS resolver with advanced features:

• DNSSEC validation -- Enabled by default
• DNS-over-TLS (DoT) and DNS-over-HTTPS (DoH) for upstream queries
• Blocklists -- Category-based DNS blocking; 26.1 adds source selection from GUI
• Host Overrides -- Local DNS records for internal hosts
• Domain Overrides -- Forward specific domains to internal DNS (split-DNS)
• DNS64 -- IPv6 transition; synthesize AAAA records for IPv4-only services

FRRouting (FRR) Plugin

Dynamic routing protocol suite:

• BGP -- eBGP and iBGP; route maps, prefix lists, community manipulation
• OSPF / OSPFv3 -- Internal dynamic routing; area design, redistribution
• BFD -- Bidirectional Forwarding Detection for fast failure detection
• RIP -- Legacy support
• EVPN/VXLAN -- Advanced datacenter routing via FRR bgpd
• Configuration via OPNsense GUI, vtysh CLI, or FRR plugin API endpoints
• Use cases: SD-WAN, multi-site, ISP connectivity, datacenter fabrics

Zenarmor (Sensei) DPI

Commercial OPNsense plugin for advanced deep packet inspection:

• L7 application identification (1000+ applications) beyond Suricata capabilities
• Web filtering with cloud-based categorization
• Per-user, per-application bandwidth and policy reports
• Threat intelligence feeds (malware, botnet, C2 blocking)
• Free tier available; Pro tier for advanced features
• Complements Suricata (IDS/IPS signatures) with application-layer visibility

WireGuard

• Native kernel module (HardenedBSD)
• GUI and API managed
• Site-to-site and road warrior configurations
• Kernel-space: significantly faster than userspace implementations
• Multi-peer, IPv4/IPv6 dual-stack
• Killswitch and routing integration for full-tunnel setups

Host Discovery (hostwatch)

• Passive network traffic monitoring; builds device inventory automatically
• Discovers: MAC address, IP, hostname (reverse DNS), first/last seen
• Enabled by default in 26.1
• Populates Device List in GUI
• Complements DHCP lease tables with visibility into static-IP devices
• Per-interface; can trigger alerts on new unknown hosts

CARP High Availability

Same CARP/pfsync mechanism as pfSense (shared FreeBSD heritage):

• CARP VIPs -- Shared IPs between active and standby nodes
• pfsync -- State table synchronization over dedicated interface
• Config Sync -- XMLRPC-based configuration replication
• Active/Passive -- Standard HA model
• Design: dedicated sync interface, 3 IPs per interface (node1, node2, VIP)

Plugin Ecosystem

REST API

Authentication

API key + API secret generated per user in System > Access > Users.

Example Calls

# List firewall aliases
curl -u "$KEY:$SECRET" https://fw.example.com/api/firewall/alias/searchItem

# Add a firewall rule
curl -X POST -u "$KEY:$SECRET" \
  -H "Content-Type: application/json" \
  -d '{"rule":{"type":"pass","interface":"lan","protocol":"tcp","source":{"net":"10.0.0.0/8"},"destination":{"net":"any"},"destination_port":"443"}}' \
  https://fw.example.com/api/firewall/filter/addRule

# Apply pending changes
curl -X POST -u "$KEY:$SECRET" \
  https://fw.example.com/api/firewall/filter/apply

# Suricata status
curl -u "$KEY:$SECRET" https://fw.example.com/api/ids/service/status

API Design

• RESTful: GET (read), POST (create/action), PUT (update), DELETE (remove)
• JSON response format
• Versioned and documented
• Nearly complete coverage of all configuration domains

Diagnostics

# pf rules
pfctl -sr                   # Show active rules
pfctl -ss                   # Show state table
pfctl -si                   # Show pf statistics

# Suricata
suricatasc -c "iface-stat"  # Suricata interface stats
cat /var/log/suricata/eve.json | jq  # EVE JSON log

# Unbound
unbound-control stats_noreset  # DNS resolver statistics
unbound-control dump_cache     # DNS cache dump

# System
top -SH                     # Process CPU/memory
netstat -rn                 # Routing table
ifconfig -a                 # Interface status

Common Pitfalls

1. API key permissions -- API keys inherit the user's group permissions. Ensure the user has appropriate privilege set for the API operations needed.

2. Suricata inline vs IDS mode -- Inline (divert) mode blocks traffic matching drop rules. If Suricata causes connectivity issues, switch to IDS mode for tuning, then re-enable inline.

3. FRR and firewall interaction -- FRR-learned routes are added to the kernel routing table but firewall rules still evaluate on pf. Ensure rules permit traffic for dynamically learned routes.

4. Plugin version compatibility -- Plugins are version-tied. After major OPNsense upgrade, verify all plugins are compatible and updated.

5. Unbound DNSSEC failures -- DNSSEC validation can break resolution for misconfigured domains. Add problem domains to DNSSEC exclusion list rather than disabling DNSSEC globally.

6. CARP without dedicated sync -- Same as pfSense: pfsync over production interfaces risks state corruption. Use dedicated link.

7. Zenarmor licensing -- Free tier has limited features. Pro license required for advanced web filtering categories and full reporting.

8. Config.xml direct editing -- OPNsense stores all config in XML. Direct editing is possible but risky; use the API instead. Always back up before manual XML changes.

Reference Files

Load these when you need deep knowledge:

• references/architecture.md -- HardenedBSD, MVC/API internals, Suricata v8, FRR, plugins, Zenarmor. Read for "how does X work" questions.