DevOps OPNsense
Agent Workflow (MANDATORY)
Before ANY change, spawn in parallel, one spawn_agent call each:
- explore-codebase - find existing OPNsense IaC (Terraform/OpenTofu, Ansible), exported
config.xml and runbooks
- 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 sniper.
Versions (checked 2026-11-10)
See the pinned versions map below 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.
Pinned versions:
opnsense-community: "26.7 series, latest listed 26.7.8 (2026-10-30), FreeBSD 15.1 base"
opnsense-business: "26.10 series listed"
release-cadence: "two majors per year, minors about every two weeks"
dhcp: "Dnsmasq default, Kea for large HA, ISC DHCP end of life"
ansible-collection: "oxlorg.opnsense (third party, 26.1.11 tag shown in README)"
terraform-provider: "browningluke/opnsense ~> 0.16 (third party, pre-1.0)"
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,
GET API calls, pfctl -s ...; never pfctl -d or 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.xml into chat or Git
Related skills
- devops-networking
- devops-proxmox
- devops-virtualization
- devops-ansible
- devops-iac
- devops-secrets
- devops-storage-backup
- devops-observability
- devops-sre-ops
- devops-linux
1---2name: devops-opnsense-23description: Use when operating an OPNsense firewall/router - interfaces, VLANs and bridges, firewall rules and NAT, DNS (Unbound) and DHCP (Dnsmasq, Kea), WireGuard/OpenVPN/IPsec, multi-WAN gateway groups, high availability (CARP, pfsync, config sync), reverse proxy and IDS plugins, firmware updates, major upgrades, snapshots and rollback, config.xml backup and restore, the REST API and automation (Ansible, OpenTofu), running OPNsense as a VM, and troubleshooting. Not for Linux host nftables or generic networking (devops-networking), Proxmox itself (devops-proxmox), or security audit (security-expert).4metadata:5 source: https://skillmd.com/skills/fusengine/devops-opnsense-26---78<objective>9Covers day-to-day and risky operations on an OPNsense firewall: network objects, rules and NAT, DNS/DHCP, VPN, multi-WAN, HA, plugins, upgrades and rollback, backup, API and automation, VM deployment and troubleshooting, with a lock-out-proof way to apply every risky change. Does not cover Linux host firewalls and generic networking (devops-networking), Proxmox administration (devops-proxmox), or security audits (security-expert).10</objective>1112# DevOps OPNsense1314## Agent Workflow (MANDATORY)1516Before ANY change, spawn in parallel, one `spawn_agent` call each:17181. **explore-codebase** - find existing OPNsense IaC (Terraform/OpenTofu, Ansible), exported `config.xml` and runbooks192. **research-expert** - verify menu paths, API endpoints and plugin names against docs.opnsense.org for the installed release203. **mcp__context7__query-docs** - library docs if the automation uses a provider or collection2122Then inspect read-only (GUI views, `GET` API calls) and confirm the installed version first. After file changes (templates, IaC), run **sniper**.2324## Versions (checked 2026-11-10)2526See the pinned `versions` map below 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.2728Pinned versions:2930```yaml31opnsense-community: "26.7 series, latest listed 26.7.8 (2026-10-30), FreeBSD 15.1 base"32opnsense-business: "26.10 series listed"33release-cadence: "two majors per year, minors about every two weeks"34dhcp: "Dnsmasq default, Kea for large HA, ISC DHCP end of life"35ansible-collection: "oxlorg.opnsense (third party, 26.1.11 tag shown in README)"36terraform-provider: "browningluke/opnsense ~> 0.16 (third party, pre-1.0)"37```3839## Overview4041| Area | Decision in one line |42|------|----------------------|43| **Rules** | MVC rules are the default; order is Floating > group > interface; `quick` is first-match; NAT is evaluated before filter rules |44| **DHCP** | Dnsmasq for small/medium, Kea for large HA, ISC is end of life |45| **VPN** | WireGuard for simple tunnels, IPsec connections (swanctl) for interop, OpenVPN 2.7 shipped in 26.7 |46| **Multi-WAN** | Monitor IPs + gateway group tiers + policy rule on the traffic that should fail over |47| **HA** | CARP VIPs + pfsync on a dedicated link + XMLRPC sync from master only; same version on both nodes |48| **Upgrade** | Major upgrades are offline: console, snapshot (ZFS) or VM snapshot, config backup first |49| **API** | Basic auth with key/secret, read first, then write, then apply step, then read back |50| **Automation** | Third-party Ansible collection and Terraform provider, pre-production grade |5152## Critical Rules53541. **Lock-out is the main danger.** Every operation in the table of [safe-opnsense-changes.md](references/safe-opnsense-changes.md) is proposed as ACTION / EFFECT / PROOF / ROLLBACK, console path and rollback stated first, then WAIT-FOR-GO552. **Out-of-band access before any change** to interfaces, rules on the management path, restores, upgrades or HA actions563. **Backup before change**: download `config.xml`, snapshot (ZFS) or VM snapshot; keep copies off-box and encrypted574. **Read-only first**: GUI views, `GET` API calls, `pfctl -s ...`; never `pfctl -d` or a state flush on a remote box without the format585. **One change at a time**, verified from a NEW session before the next596. **Never invent a menu path, endpoint, command or flag**: unknown = "not verified" (every reference ends with that list)607. **Secrets stay out of output and Git**: API key/secret and WireGuard keys only through environment variables or a secret store (`devops-secrets`)618. **HA**: change the master, sync to the backup; a backup node never holds sync settings6263## Reference Guide6465### Concepts6667| Topic | Reference | When to Consult |68|-------|-----------|-----------------|69| **Safe changes** | [safe-opnsense-changes.md](references/safe-opnsense-changes.md) | Before ANY change that can cut access or lose state |70| **Upgrades** | [upgrade-rollback.md](references/upgrade-rollback.md) | Release line, minor/major upgrades, snapshots, rollback |71| **Rules and NAT** | [firewall-nat-interfaces.md](references/firewall-nat-interfaces.md) | Interfaces, rule order, aliases, NAT modes |72| **DNS/DHCP** | [dns-dhcp.md](references/dns-dhcp.md) | Unbound, Dnsmasq, Kea, relay |73| **VPN** | [vpn.md](references/vpn.md) | WireGuard, IPsec, OpenVPN |74| **Multi-WAN** | [multiwan.md](references/multiwan.md) | Gateways, groups, failover |75| **HA** | [ha-carp.md](references/ha-carp.md) | CARP, pfsync, config sync |76| **Plugins** | [plugins-proxy-ids.md](references/plugins-proxy-ids.md) | Caddy/HAProxy/nginx, ACME, Suricata, CrowdSec |77| **Backup and API** | [backup-restore-api.md](references/backup-restore-api.md) | Backups, REST API, Ansible, OpenTofu |78| **Console, VM, pfSense** | [console-vm-pfsense.md](references/console-vm-pfsense.md) | Console menu, VM install, migrating from pfSense |79| **Troubleshooting** | [troubleshooting-order.md](references/troubleshooting-order.md) | Any "cannot connect" |8081### Templates8283| Template | When to Use |84|----------|-------------|85| [api-calls.sh](references/templates/api-calls.sh) | Read-only API calls with key/secret from environment |86| [config-backup.sh](references/templates/config-backup.sh) | Pull and encrypt the config off-box |87| [opentofu-opnsense.tf](references/templates/opentofu-opnsense.tf) | OpenTofu/Terraform provider example (pre-1.0) |88| [requirements.yml](references/templates/requirements.yml) | Install the Ansible collection |89| [wireguard-checklist.md](references/templates/wireguard-checklist.md) | WireGuard instance and peer checklist |90| [carp-ha-checklist.md](references/templates/carp-ha-checklist.md) | HA cluster setup and failover checklist |91| [pre-upgrade-checklist.md](references/templates/pre-upgrade-checklist.md) | Before a firmware upgrade |92| [rollback-checklist.md](references/templates/rollback-checklist.md) | Recovering from a failed change or upgrade |9394## Quick Reference9596```bash97pfctl -s nat # NAT/reflection rules (read-only, on the firewall)98less /tmp/rules.debug # generated ruleset (on the firewall)99curl -sS -u "$OPNSENSE_API_KEY:$OPNSENSE_API_SECRET" "https://$OPNSENSE_HOST/api/firewall/alias/get"100```101Boot loader menu (press Space during boot): option 8 = Boot Environments (ZFS snapshots). Console menu: option 12 = update / major upgrade.102103## Best Practices104105### DO106- Keep the web GUI and SSH on all interfaces unless a loopback alias design is proven107- Use a dedicated least-privilege API user and rotate its key108- Keep both HA nodes on the same version and the same interface assignments109- Prefer explicit manual NAT over automatic reflection helpers110111### DON'T112- Deploy ISC DHCP, or leave a plugin owning ports 80/443 while the GUI uses them113- Run `pfctl -d`, reset states, restore a config or start a major upgrade without the ACTION/EFFECT/PROOF/ROLLBACK format and the user's go114- Treat the third-party Ansible collection or Terraform provider as production-stable115- Paste API secrets, WireGuard private keys or `config.xml` into chat or Git116117---118119## Related skills120121- devops-networking122- devops-proxmox123- devops-virtualization124- devops-ansible125- devops-iac126- devops-secrets127- devops-storage-backup128- devops-observability129- devops-sre-ops130- devops-linux