DevOps OPNsense
Agent Workflow (MANDATORY)
Before ANY change, spawn in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - find existing OPNsense IaC (Terraform/OpenTofu, Ansible), exported
config.xmland runbooks - fuse-ai-pilot:research-expert - verify menu paths, API endpoints and plugin names against docs.opnsense.org for the installed release
- mcp__context7__query-docs - library docs if the automation uses a provider or collection
Then inspect read-only (GUI views, GET API calls) and confirm the installed version first. After file changes (templates, IaC), run fuse-ai-pilot:sniper.
Versions (checked 2026-11-10)
See the frontmatter versions map and the "Sources" of each reference. Community Edition 26.7 series on FreeBSD 15.1; Business Edition series 26.10 is listed. Menu paths and API endpoints change between series: check the release page of the installed version before quoting a path.
Overview
| Area | Decision in one line |
|---|---|
| Rules | MVC rules are the default; order is Floating > group > interface; quick is first-match; NAT is evaluated before filter rules |
| DHCP | Dnsmasq for small/medium, Kea for large HA, ISC is end of life |
| VPN | WireGuard for simple tunnels, IPsec connections (swanctl) for interop, OpenVPN 2.7 shipped in 26.7 |
| Multi-WAN | Monitor IPs + gateway group tiers + policy rule on the traffic that should fail over |
| HA | CARP VIPs + pfsync on a dedicated link + XMLRPC sync from master only; same version on both nodes |
| Upgrade | Major upgrades are offline: console, snapshot (ZFS) or VM snapshot, config backup first |
| API | Basic auth with key/secret, read first, then write, then apply step, then read back |
| Automation | Third-party Ansible collection and Terraform provider, pre-production grade |
Critical Rules
- Lock-out is the main danger. Every operation in the table of safe-opnsense-changes.md is proposed as ACTION / EFFECT / PROOF / ROLLBACK, console path and rollback stated first, then WAIT-FOR-GO
- Out-of-band access before any change to interfaces, rules on the management path, restores, upgrades or HA actions
- Backup before change: download
config.xml, snapshot (ZFS) or VM snapshot; keep copies off-box and encrypted - Read-only first: GUI views,
GETAPI calls,pfctl -s ...; neverpfctl -dor a state flush on a remote box without the format - One change at a time, verified from a NEW session before the next
- Never invent a menu path, endpoint, command or flag: unknown = "not verified" (every reference ends with that list)
- Secrets stay out of output and Git: API key/secret and WireGuard keys only through environment variables or a secret store (
devops-secrets) - HA: change the master, sync to the backup; a backup node never holds sync settings
Reference Guide
Concepts
| Topic | Reference | When to Consult |
|---|---|---|
| Safe changes | safe-opnsense-changes.md | Before ANY change that can cut access or lose state |
| Upgrades | upgrade-rollback.md | Release line, minor/major upgrades, snapshots, rollback |
| Rules and NAT | firewall-nat-interfaces.md | Interfaces, rule order, aliases, NAT modes |
| DNS/DHCP | dns-dhcp.md | Unbound, Dnsmasq, Kea, relay |
| VPN | vpn.md | WireGuard, IPsec, OpenVPN |
| Multi-WAN | multiwan.md | Gateways, groups, failover |
| HA | ha-carp.md | CARP, pfsync, config sync |
| Plugins | plugins-proxy-ids.md | Caddy/HAProxy/nginx, ACME, Suricata, CrowdSec |
| Backup and API | backup-restore-api.md | Backups, REST API, Ansible, OpenTofu |
| Console, VM, pfSense | console-vm-pfsense.md | Console menu, VM install, migrating from pfSense |
| Troubleshooting | troubleshooting-order.md | Any "cannot connect" |
Templates
| Template | When to Use |
|---|---|
| api-calls.sh | Read-only API calls with key/secret from environment |
| config-backup.sh | Pull and encrypt the config off-box |
| opentofu-opnsense.tf | OpenTofu/Terraform provider example (pre-1.0) |
| requirements.yml | Install the Ansible collection |
| wireguard-checklist.md | WireGuard instance and peer checklist |
| carp-ha-checklist.md | HA cluster setup and failover checklist |
| pre-upgrade-checklist.md | Before a firmware upgrade |
| rollback-checklist.md | Recovering from a failed change or upgrade |
Quick Reference
pfctl -s nat # NAT/reflection rules (read-only, on the firewall)
less /tmp/rules.debug # generated ruleset (on the firewall)
curl -sS -u "$OPNSENSE_API_KEY:$OPNSENSE_API_SECRET" "https://$OPNSENSE_HOST/api/firewall/alias/get"
Boot loader menu (press Space during boot): option 8 = Boot Environments (ZFS snapshots). Console menu: option 12 = update / major upgrade.
Best Practices
DO
- Keep the web GUI and SSH on all interfaces unless a loopback alias design is proven
- Use a dedicated least-privilege API user and rotate its key
- Keep both HA nodes on the same version and the same interface assignments
- Prefer explicit manual NAT over automatic reflection helpers
DON'T
- Deploy ISC DHCP, or leave a plugin owning ports 80/443 while the GUI uses them
- Run
pfctl -d, reset states, restore a config or start a major upgrade without the ACTION/EFFECT/PROOF/ROLLBACK format and the user's go - Treat the third-party Ansible collection or Terraform provider as production-stable
- Paste API secrets, WireGuard private keys or
config.xmlinto chat or Git
