OPNsense Firewalls
The OPNsense module manages your firewall infrastructure. It provides real-time monitoring, update management, and configuration backups for all OPNsense installations.
Overview
Host Table
| Column | Description |
|---|---|
| Customer | Assigned customer |
| Name | Display name of the firewall (editable in the detail panel) |
| Site | Site of the customer (since v3.38.0, free text before), hidden by default |
| Hostname | Hostname of the firewall |
| OPNsense Version | Installed OPNsense version |
| Edition | Community (versions YY.1 / YY.7) or Business (YY.4 / YY.10), derived from the version; also shown in the detail panel under Information (since v3.31.3) |
| Agent Version | DATAZONE Agent version |
| WAN IP | Public WAN address |
| Uptime | Time since last reboot |
| CPU / RAM / Disk | Current utilization as progress bars |
| Last Response | Timestamp of the last agent heartbeat |
| Last Config Change | Timestamp of the last configuration change |
| Gateways | Status of configured gateways (color-coded) |
| WebUI | Direct link to the OPNsense web interface |
Status Detection
A firewall is considered offline if no heartbeat is received within twice the heartbeat interval. The heartbeat interval is reported by the agent (heartbeat_interval) and the offline detection is calculated as heartbeat_interval x 2. Default: 2x 30s = 60s.
Dynamic Detection
Unlike the other modules (fixed 120s timeout), the OPNsense offline detection dynamically adapts to the actual heartbeat interval of the agent.
Adding a Host
Via Agent (recommended)
- Install the agent on the OPNsense appliance (see Agent Installation)
- The agent automatically detects that the system is FreeBSD/OPNsense
- The firewall appears in the OPNsense module
Manual (API-based)
- Click Add Firewall
- Enter the following details:
- Customer - Assign to a customer
- Hostname - Display name
- Host - IP address or FQDN
- API Key and API Secret - OPNsense API credentials
Setting Up API Access
In the OPNsense web interface under System > Access > Users, you can create API keys. The user requires read permissions for the desired areas.
Detail Panel
Click on a firewall in the table to open the detail panel.
The detail panel contains 9 main tabs at the top. The Overview tab additionally contains 7 sub-tabs for detailed system information.
Main Tabs
| Tab | Icon | Description |
|---|---|---|
| Overview | Monitor | System information with sub-tabs (see below) |
| Checks | ClipboardCheck | Health check results and status |
| Jobs | ListTodo | Running and completed tasks |
| Shell | Terminal | Remote terminal to the OPNsense shell |
| Log | FileText | Execution logs for all actions |
| Groups | Tags | Manage group membership |
| Updates | RefreshCw | Update history and schedules |
| Agent | Cpu | Agent status, logs, and management |
| Delete | Trash2 | Remove firewall from DATAZONE Control |
Tab: Overview
The overview shows the most important metrics (CPU, RAM, Disk, Uptime) as cards at the top. Below are editable fields (Name, Customer, Description) and the sub-tab navigation.
Sub-tab: Hardware
- CPU model, cores, clock speed
- RAM size and utilization
- Disks with size and usage
- BIOS information
Sub-tab: Interfaces
- All network interfaces with status (UP/DOWN)
- Interface name (WAN, LAN, OPT1, etc.)
- IP addresses (IPv4 and IPv6)
- Throughput and packet statistics
- VLAN configurations
Sub-tab: VPN
Overview of all VPN connections, divided into three sections:
OpenVPN:
- Server and client instances with status (up/down)
- Connected clients per server
- Throughput and connection duration
- Descriptions from the OPNsense config.xml
IPsec:
- Phase 1 and Phase 2 tunnels
- Connection status and uptime
- Remote gateway and local/remote subnets
WireGuard:
- Peers with status and last handshake
- Allowed IPs and endpoint information
- Transferred data per peer
Sub-tab: Routes (since v1.3.0)
- Complete routing table of the firewall
- Destination network, gateway, interface
- Metric and flags
- Static and dynamic routes
Sub-tab: Certificates (since v1.3.0)
- ACME certificates (Let's Encrypt) and self-signed SSL certificates
- Expiration date with color highlighting (red when expiring soon)
- Certificate details: Common Name, issuer, serial number
- Cache interval: 6 hours
Sub-tab: Services (since v1.3.0)
Two sections:
OPNsense Services:
- All configured OPNsense services with status (Running/Stopped); services with several instances (e.g. OpenVPN) show the instance number
- From 3.37.0: Start, Stop, Restart per service with confirmation (admins or permission Manage services in the OPNsense module only - enforced by the backend, firewall online). The agent uses the OPNsense API
/api/core/service/<action>/<name>[/<id>](orconfigctl service ...), not systemctl - before, this always failed on OPNsense. After the action the agent checks that the service runs or is stopped and reports an error otherwise - Locked core services (lock icon) can only be restarted;
configdcan never be stopped
Nginx Virtual Hosts (if Nginx plugin is installed):
- Configured Nginx server entries
- Server name, port, SSL status
- Upstream configurations
- Cache interval: 1 hour
Sub-tab: Backups
Since v3.42.0 Control keeps a history of each firewall's config.xml (config versions).
What is stored: the complete /conf/config.xml. A new version is only created when the file changed (SHA-256 compared with the newest version). If nothing changed, the agent only reports the hash and the file is not transferred at all. If the reported hash does not match the newest stored version, Control requests the backup with content exactly once more; if that attempt again only reports a mismatching hash, the task fails (no further automatic retry, since v3.48.13).
When a backup is taken (reason in the list):
| Reason | When |
|---|---|
| Nightly | Every night at opn_backup_nightly_time (default 02:30, same time zone as notifications) for every firewall that is online |
| Before update | Before an update run touches the node for the first time. If the backup fails, the update still continues (note in the log) |
| Before change | Before every change made from Control: rules, NAT, aliases, categories, WireGuard |
| Manual | Button Back up now |
| Before / After restore | State right before a restore and about six minutes after it (after the reboot) |
Encryption: the file contains password hashes, private keys and PSKs. Control only stores it encrypted (Fernet, key derived from SCRIPT_VAULT_KEY in .env, the same key as for script secrets). Without the key nothing is stored and the tab shows a notice. If SCRIPT_VAULT_KEY changes, older versions can no longer be read. Task results and logs never contain the content, only size and hash.
Retention: opn_backup_retention_days (default 90 days). The newest version of each firewall is always kept, as is a version that was restored within the last 7 days.
List: time, reason, size, OPNsense version, by whom. Per row:
- Changes shows what changed compared with the previous version (unified diff, green = added, red = removed). Passwords, keys, PSKs, API secrets and OpenVPN keys are hidden on both sides (
[maskiert 1a2b3c4d]). When such a value changes, the short code changes – you see that e.g. a PSK changed, but not the value. - Download returns the real, complete
config.xml(with all secrets) – keep it safe. - Restore puts the version back on the firewall (see below).
Permissions:
| What | Permission |
|---|---|
| See the list | OPNsense View (sub-tab Backups) |
| Back up now | Write permission in the module (tasks/edit) |
| Changes + Download | Read config backups (opnsense.config_backup) |
| Restore | Restore config (opnsense.config_restore) plus write permission in the module |
The two new permissions are not part of "all sub-tabs" and not part of the Operator, Support or Viewer roles – admins have them, everyone else only when explicitly granted. Customer-bound users only see firewalls of their customer. Download, diff and restore are written to the audit log. The Files tab does not hand out /conf (config.xml and /conf/backup) without Read config backups either – since v3.48.14 for no file action at all, i.e. also not via rename, upload or listing.
Restore – procedure:
- Click Restore in the row and type the firewall name.
- Control first creates a backup of the current state (reason Before restore), then the restore. The agent runs both one after the other, the backup first.
- The agent checks the version (checksum, well-formed XML with
<opnsense>), additionally saves the previous file as/conf/backup/config-<time>-datazone.xmlon the firewall, writes the new file atomically and schedules a reboot in one minute. It reports the result before the reboot. - After the reboot Control backs up the new state (reason After restore).
Requirements: agent 3.42.0 or newer, firewall online. Nothing else may be running on the firewall or its HA partner (update run, reboot, agent update, another restore – including one that finished less than 10 minutes ago, because that node is rebooting). Conversely, an update run does not touch the pair during these 10 minutes. If the version comes from another major version (e.g. 25.7 instead of 26.1), the dialog shows a warning and requires its own checkbox. The restore is only executed if the agent fetches it within 30 minutes; if it reports no result for 10 minutes it counts as failed (check the firewall). From agent 3.48.3 on the agent applies it only within 5 minutes after fetching it (e.g. when it is still busy with a long task) - after that it refuses without changing anything, so a restore reported as failed never triggers a reboot later. While swapping the file the agent holds the same file lock OPNsense uses; when backing up it reads the file under that lock and only stores complete XML. Once the result has reached Control it reboots right away (the reboot scheduled in one minute remains as fallback). The content is only inserted when the agent fetches the task and never stored in the task parameters.
HA pair
If the firewall is part of an HA pair, the dialog shows a warning and requires an extra checkbox. With config sync active, the partner may take over the restored state or overwrite it with its own state on the next sync. Preferably restore on the node that syncs to the other one and check both firewalls afterwards.
The old field change descriptions does not exist; Changes shows what changed.
Comparison (from v3.47.0)
Compare with another firewall (at the top of the Backups sub-tab) puts two firewalls side by side – or two versions of the same firewall if you pick the same firewall on both sides with different versions. The default is the newest config version on each side. In the HA box on the Updates tab, Compare pair opens the same dialog with both nodes (see Checking HA synchronisation).
Unlike Changes (line diff), Control compares structured per section and matches objects by properties that are the same on both firewalls – never by UUID, which differs on every firewall:
| Section | Matched by | Notes |
|---|---|---|
| Aliases | name | content compared without order |
| Filter rules | interface + action + description (without description: protocol/source/destination/port) | legacy and MVC rules; sequence, creator and timestamps do not count |
| NAT | kind (port forward, outbound, 1:1, NPT) + interface + description | plus outbound mode |
| Interfaces | key (wan, lan, opt1 …) | description, device, addresses, gateway, MTU … |
| System | general / DNS / NTP | hostname excluded |
| Unbound DNS | overrides by host + domain or name | legacy and MVC settings |
| WireGuard, IPsec | name or description | keys and PSKs only masked |
| Users and groups | name | names only, no hashes, keys or API keys |
| Certificates | description | name and expiry date only, never key material |
Per section Control shows only left, only right, different (table object · field · left · right) and how many objects are the same. Use the chips at the top to hide sections. References to other objects (e.g. categories of a rule) and interface keys are shown as names so they can be compared across firewalls. Passwords, keys and PSKs are masked like in Changes – the same short code means the same value.
Permission: Read config backups (opnsense.config_backup); customer-bound users only see firewalls of their customer (both sides). Every comparison is in the audit log (opn_config_compare). API: GET /api/opnsense/compare?a=<id>&b=<id>[&va=<version>][&vb=<version>][§ions=aliases,rules].
Templates (from 3.46.0) keep reporting their own drift under OPNsense › Templates.
Sub-tab: Files (since v3.30.0)
Browser file manager like on Windows and Linux (agent 3.19.0 or newer, firewall online). Browse folders and download files (permission Files), upload, rename, delete and create folders (permission Manage files). Since v3.42.0, downloads from /conf (config.xml and /conf/backup, also /cf/conf and ZIPs of parent folders) additionally need the permission Read config backups (opnsense.config_backup), because these files contain password hashes and keys. Since v3.48.14 this applies to every file action, not only downloads: without the permission you can neither list /conf and /cf/conf nor create folders, delete, upload or move files into or out of them there (rename checks source and destination). When listing a parent folder conf is hidden, also a symlink pointing to /conf. The same applies to /var/log/filter* (permission Search firewall log) and /tmp/dz-capture-* (permission Packet capture). Control rejects paths containing ... Control always checks this; agents 3.48.14 or newer additionally check it on the firewall on the real path (symlinks resolved).
- Role Support may only read and download, Operator and administrators may also change.
- Protected against delete and rename: among others
/conf,/conf/config.xml,/usr/local,/usr/local/etc,/usr/local/opnsense,/var/db,/var/log,/etc/rc.confand the agent files (from agent 3.30.0; older agents protect the generic Unix folders). - Changes to configuration files only take effect after the service is reloaded, or are overwritten by OPNsense the next time it saves. Change the configuration itself only in the OPNsense web interface.
Unbound DNS Statistics (since v1.3.0)
In the overview, Unbound DNS statistics are displayed as cards (if Unbound is active):
- Total number of queries
- Cache hit rate
- Top queried domains
Tab: Checks
Shows all health checks assigned to this firewall with their current status:
- OK (green), Warning (yellow), Critical (red), Unknown (gray)
- Last check result and timestamp
- Direct link to check configuration
See Health Checks for details.
Tab: Jobs
All jobs affecting this firewall (directly, via group, customer or "all"). Run, pause, edit and delete directly in the list.
Since v3.31.3 New job opens the same form as the module's Jobs page, with this firewall as target: major upgrade to latest version or a specific version, HA options, checks and playbooks. The target can be changed in the form.
Tab: Shell
Remote terminal to the OPNsense shell directly in the browser. Uses the agent for a secure WebSocket connection.
- Full interactive terminal
- FreeBSD shell (csh/sh)
- Root access
Tab: Log
Chronological execution logs of all actions on this firewall:
- Timestamp, action, user
- Result (success/failure)
- Expandable detail output
Tab: Groups
Manage group membership for this firewall:
- Current groups with colored badges
- Add/remove groups
See Groups.
Tab: Updates
- HA box (on CARP nodes): role, partner, reboot pending; actions HA pair: update, HA pair: update + reboot (rolling), Enable/leave CARP maintenance
- Single-node buttons: System Update (no reboot), Update + Reboot, Major Upgrade (starts a run, target Latest or a release, step by step)
- Version info: OPNsense, agent, kernel, available update, next major release
Tab: Agent
- Agent status (Online/Offline) and version
- View agent configuration
- View agent logs
- Restart agent
Tab: Delete
Permanently remove the firewall from DATAZONE Control.
Warning
This action cannot be undone. The agent on the firewall will not be uninstalled.
VPN Management (since v2.2.3)
The OPNsense module provides a centralized management interface for WireGuard VPN directly in DATAZONE Control. Accessible via the VPN tab in the OPNsense module view (next to the host table).
VPN Overview
The VPN table shows all VPN instances across all firewalls. The view aggregates WireGuard, OpenVPN, and IPsec tunnels centrally in one table.
| Column | Description |
|---|---|
| Customer | Assigned customer |
| Firewall | Name of the firewall |
| Instance | Name of the VPN instance |
| Type | WG RW (Road Warrior), WG S2S (Site-to-Site), OpenVPN, IPsec |
| Interface | WireGuard interface (wg0, wg1, etc.) |
| Port | Listening port |
| Tunnel Network | IP range of the tunnel |
| Peers | Number of configured peers |
| Active Peers | Number of currently connected peers |
| Status | Online/Offline |
Type Filter: Filter by VPN type (All, WireGuard, OpenVPN, IPsec) with counter badges.
WireGuard Instances
Create New Instance
Click New Instance to create a WireGuard instance on a firewall:
| Field | Description |
|---|---|
| Firewall | Target firewall (online + API-ready only) |
| Name | Name of the WireGuard instance |
| Port | Listening port (default: 51820) |
| Tunnel Network | IP address and subnet (e.g., 10.10.10.1/24) |
| DNS for Clients | DNS server for client configurations |
| Create WAN Rule | Creates a UDP firewall rule on the WAN interface |
| Allow-All on WireGuard Interface | Allows all traffic through the tunnel |
Separate Firewall Rules
The WAN rule (open port) and the Allow-All rule (allow traffic) can be controlled independently. This lets you open the port but manually restrict traffic on the WireGuard interface in OPNsense.
Add Peer
Click on an instance and select Add Peer:
| Field | Description |
|---|---|
| Name | Name of the peer (e.g., employee name) |
| Tunnel IP | IP address of the peer in the tunnel network |
| DNS | DNS server for the peer |
| MTU | Only if different from 1420 |
| Split Tunnel | Route only specific networks through the tunnel (LAN subnets auto-detected) |
After creation, a client configuration with QR code is displayed that can be imported directly into WireGuard apps.
Private Key
The peer's private key is only displayed once after creation. It cannot be retrieved again. Save the configuration or scan the QR code immediately.
Tunnel Mode
| Mode | Description |
|---|---|
| Full Tunnel | All traffic is routed through the VPN tunnel (0.0.0.0/0, ::/0) |
| Split Tunnel | Only specific networks are routed. LAN subnets of the firewall are automatically suggested and can be added with a click. |
Instance Detail
Click on a VPN instance to open the detail panel.
WireGuard Instances:
- Instance name, interface, type badge, and status
- Associated firewall with direct link
- Peer table with status, name, allowed IPs, endpoint, last handshake, and traffic (RX/TX)
- Enable/disable instance
- View settings (name, interface, port, tunnel network, UUIDs)
IPsec Instances:
- Phase 2/Child-SA table with local and remote networks
- Encryption and hash details
- Remote gateway, IKE version, DH group, lifetime, NAT-T status
Peer Actions
The following actions are available for each WireGuard peer:
| Action | Description |
|---|---|
| Enable/Disable | Temporarily disable the peer without deleting it |
| Edit Allowed IPs | Change the allowed IP ranges for the peer |
| Configuration/QR Code | Show client configuration (only available immediately after creation) |
| Delete | Permanently remove the peer |
Edit Allowed IPs:
- Chip-based management with add/remove
- Quick buttons for common ranges:
0.0.0.0/0,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 - Free-text input for any IP range
Site-to-Site Wizard (since v2.2.3)
The Site-to-Site Wizard automatically creates a WireGuard tunnel between two OPNsense firewalls in three steps:
Step 1: Select Firewalls
- Choose two online firewalls with API readiness
- Detected LAN subnets are displayed automatically
Step 2: Configuration
| Field | Description |
|---|---|
| Tunnel Subnet | Point-to-point network. Suggestion: the next free /30 from 10.0.80.0/22 |
| Port | WireGuard port on both sides. Suggestion: the next free one from 51830, allowed range 1024–65535 |
| Connection Mode | Equal, A=Primary, or B=Primary |
| Endpoints | IP or DNS name without port (depends on connection mode). Prefilled with the firewall's external IP |
| Networks A → B / B → A | Which local subnets to route through the tunnel. Detected LANs are shown as clickable chips above the field, the LAN interface is preselected. Add more networks separated by commas |
| WAN rule | Open the UDP port - from 3.33.0 only on the side that accepts connections (with A/B = primary only there) |
| Allow-All | Allow all tunnel traffic. From 3.33.0 the choice is respected (before, the rule was always created) |
Since v3.66.4 you can only continue once the input is valid: tunnel subnet and networks with prefix (e.g. 192.168.1.0/24), a port in the allowed range, and an endpoint for every firewall that accepts connections. Networks must not overlap the tunnel subnet. The server runs the same checks before it creates anything on the firewalls.
Step 3: Summary and Execution
The wizard automatically performs:
- Key generation on both firewalls
- Create WireGuard instances with generated keys
- Add peers on both sides with PSK (Pre-Shared Key)
- Create firewall rules (if enabled)
Connection Mode (since v2.2.10)
| Mode | Description |
|---|---|
| Equal | Both firewalls have static IPs. Either side can initiate the connection. Both get endpoint + keepalive configured. |
| A = Primary | Firewall A has a static IP (headquarters). Firewall B (branch office, dynamic IP) connects to A. Only A needs an endpoint. B gets PersistentKeepalive=25. |
| B = Primary | Reversed: B has a static IP, A connects to B. |
Dynamic IP
Use the Primary mode when one site doesn't have a static IP. The secondary site always connects to the primary and keeps the tunnel alive with PersistentKeepalive.
Deleting a Site-to-Site Connection
In the instance detail panel of an S2S connection, the entire Site-to-Site link can be deleted. This automatically:
- Removes associated firewall rules (WAN + Allow-All) - from 3.37.0 first, while the instance still exists (before, the allow-all rule stayed because its WG interface could no longer be found)
- Deletes peers on both sides
- Removes WireGuard instances on both firewalls
If provisioning an S2S connection fails, Control clears the temporarily stored private keys and the PSK right away from 3.37.0 (before only after a successful setup).
Since 3.48.3:
- Deleting during provisioning: provisioning steps not fetched yet expire at once (they never run), everything already created is removed via the stored IDs. If the agent is executing a provisioning step right now, Control refuses the deletion for that moment (HTTP 409, delete again in a minute) - otherwise an instance without owner would remain on the firewall. A step hanging without result for 15 minutes does not block.
- If one side of the provisioning fails, the still open step of the other side expires too.
- Private keys and PSK are removed from task result and parameters before anything is stored, also for expired or cancelled provisioning tasks (old entries once at start-up).
WireGuard: honest results (from 3.37.0)
OPNsense reports input errors with HTTP 200 and result: failed. The agent now evaluates this for all WireGuard tasks (instance, peer, assignment to the instance, reconfigure, firewall rules) and marks the task as failed. A half-created peer or instance is removed again. Enabling/disabling a peer and changing allowed IPs keeps the assignment to the instance (OPNsense removed it on partial updates otherwise). The pre-shared key of a new road-warrior peer is generated in the browser and sent along, so it is never missing from the client configuration. Enable/disable follows the state enabled, not connected: a peer that is not connected can be disabled.
Permissions and update lock (from 3.33.0)
Changing rules, NAT, aliases, categories and WireGuard requires Edit or Tasks in the OPNsense module (view is not enough) and the firewall must be in the user's customer scope. While an update run is active on the firewall, changes are rejected with a notice so no filter reload hits the reboot. Invalid rule or peer IDs are rejected. The separate choice "Allow-All only, no WAN rule" needs agent 3.33.0 or later; older agents would open the port anyway, so Control creates no rule then.
Firewall Rules (since v2.3.0)
The OPNsense module provides centralized management for firewall rules, aliases, categories, and NAT rules directly in DATAZONE Control. Accessible via the Rules tab in the OPNsense module view.
Overview
The Rules overview shows all firewalls with their rule count, broken down by type (Pass, Block, Reject).
Click on a firewall to open the rule editor. It contains 5 tabs:
| Tab | Description |
|---|---|
| Rules | Filter rules (main rules) |
| Aliases | Manage aliases |
| Categories | Manage categories |
| NAT Source | Outbound NAT rules (Source NAT) |
| NAT Port Forward | Port forwarding rules |
Commit Workflow
All changes to rules, aliases, and NAT rules are saved locally first. Only by clicking Commit are the changes applied to the firewall. Use Discard to discard uncommitted changes.
Applying: safeguards and feedback (from 3.37.0)
Automatic rollback for rules and source NAT. Before the first change the agent creates a savepoint (/api/firewall/filter/savepoint or /api/firewall/source_nat/savepoint) and applies with that revision (.../apply/<revision>). OPNsense reverts the rules itself after 60 seconds unless the rollback is cancelled. After applying, the agent opens a new connection to Control; only if that works it cancels the rollback (.../cancelRollback/<revision>) and checks on the firewall that the rollback timer really ended. If Control is unreachable, the task ends with Connection lost after applying - OPNsense reverts the change automatically after 60 s.
| Area | Automatic rollback | Connectivity check |
|---|---|---|
| Filter rules | yes (OPNsense 25.7 / 26.1) | yes |
| Source NAT | yes (OPNsense 25.7 / 26.1) | yes |
| Port forwards (API from OPNsense 26.1) | no - separate OPNsense model (DNat) not covered by the rollback | yes, clear notice on loss |
| Aliases, categories | no | no |
OPNsense 26.7
From OPNsense 26.7 savepoint and rollback are no longer part of the API. The agent detects this and applies without automatic rollback; the connectivity check still runs and reports a loss as an error.
If the rollback timer of a previous change (60 s) is still running, the agent refuses: Rollback of a previous change still running - please wait 60 s (OPNsense would not start a new timer otherwise). Right after applying it checks that its own timer really runs; otherwise it reports honestly that no rollback is active. Only a real answer from Control counts as reachable (not e.g. an error page of a proxy).
Port forwards are only available through the API from OPNsense 26.1; older versions report this clearly.
Position of new entries. New rules and NAT entries go to the end (highest existing sequence + 100), as the list shows them - older OPNsense versions would otherwise have put them at the top with sequence 1. Editing never sends the position; only moving changes it. If the agent could not read the categories of an entry, editing does not overwrite them.
Honest result. Every change is evaluated on its own (OPNsense reports input errors with HTTP 200 and result: failed). If applying fails, the task fails. After applying, the tab shows a notice listing all failed changes; only successful changes are taken over into the list, new entries get their real ID right away. Without an answer within 2.5 minutes (e.g. agent offline) it says Result unknown - reload after the next heartbeat. A newly added entry that has not been applied yet can be enabled/disabled; the state goes along with the creation.
Order. Control sends the desired order only when rules were moved. The agent then changes only the sequence of rules whose position really changed (before, every apply renumbered all rules - one configuration revision per rule).
Interface networks. OPNsense stores LAN net as lan and LAN address as lanip. Control shows the plain names and converts them correctly when applying (before, lannet was sent, which OPNsense rejects). From 3.37.0 interface names only come from the direct entries below <interfaces> in config.xml.
Filter Rules (Rules)
The Rules tab shows all firewall rules of the selected firewall with visual status indicators.
Filtering and Searching
- Action filter: All, Pass, Block, Reject
- Interface filter: Dropdown with all available interfaces
- Category filter: Dropdown with all configured categories
- Free-text search: Searches all visible columns
Rule Display
Each rule shows the following information:
| Field | Description |
|---|---|
| # | Sequence number (order) |
| Active | Enabled/Disabled (toggle) |
| Action | Pass (green), Block (red), or Reject (orange) |
| Direction | In or Out |
| Interface | Network interface (WAN, LAN, etc.) |
| Protocol | TCP, UDP, ICMP, etc. |
| Source | Source address or alias (with NOT indicator) |
| Destination | Destination address or alias (with NOT indicator) |
| Gateway | Assigned gateway |
| Log | Whether the rule is logged |
| Categories | Assigned categories as colored chips |
| Description | Free-text description |
Creating Rules
Click Add Rule to create a new rule. Optionally select a template:
| Template | Description |
|---|---|
| Empty | Empty rule for manual configuration |
| Allow HTTP/HTTPS | Allow web traffic (port 80/443) |
| Allow SSH | Allow SSH access (port 22) |
| Allow DNS | Allow DNS queries (port 53) |
| Allow ICMP | Allow ping |
| Allow SMTP | Allow email sending (port 25/587) |
| Allow WireGuard | Allow WireGuard VPN |
| Allow OpenVPN | Allow OpenVPN |
| Allow IPsec | Allow IPsec VPN |
| Block All | Block all traffic |
Editing Rules
The edit form is divided into sections:
Organization:
- Enabled/Disabled
- Assign categories
- Description
Interface:
- Interface selection (including "Floating (all)" for all interfaces)
- Invert interface (NOT)
Filter:
- Quick rule (optimized processing)
- Action: Pass, Block, Reject
- Direction: In, Out
- IP Version: IPv4, IPv6, IPv4+IPv6
- Protocol: Any, TCP, UDP, TCP/UDP, ICMP, ESP, AH, GRE, IGMP, PIM, OSPF
Source:
- Source address via network selector (see below)
- Invert source (NOT)
- Source port
Destination:
- Destination address via network selector
- Invert destination (NOT)
- Destination port
Advanced:
- Gateway selection
- Enable logging
Network Selector
The network selector is an intelligent dropdown that groups different address types:
| Group | Options |
|---|---|
| General | any (any address), (self) (firewall itself) |
| Interface Addresses | IP address of each interface (e.g., LAN address, WAN address) |
| Interface Networks | Subnet of each interface (e.g., LAN net, WAN net) |
| Aliases | All configured aliases |
| Single Host or Network | Manual input of an IP/subnet |
Reordering Rules
The order of rules determines processing priority. Use the arrow buttons (up/down) to reorder rules.
Protected Rules
Rules with DATAZONE-PROTECT in the description are protected and cannot be edited, disabled or deleted.
From 3.37.0 Control no longer creates DATAZONE-PROTECT rules (before, the first apply created an all-ports rule from the Control server). Existing rules stay unchanged and protected. Protection against locking yourself out is now savepoint/rollback and the connectivity check after applying (see above) - the agent's connection to Control is outbound.
If the rule list of the firewall cannot be read, the agent applies nothing and reports why (safe abort instead of deleting without a check).
Aliases
Aliases are named groups of IP addresses, networks, or URLs that can be used in firewall rules. They greatly simplify rule management.
Alias Types
| Type | Description | Example |
|---|---|---|
| Host(s) | Individual IP addresses or hostnames | 192.168.1.100, server.example.com |
| Network(s) | IP subnets in CIDR notation | 192.168.1.0/24, 10.0.0.0/8 |
| URL Table (IPs) | URL providing an IP list | Blocklist URLs |
| URL Table | URL providing a mixed list | External filter lists |
| GeoIP | Country-based IP ranges | Country codes |
| External | Externally managed aliases | External sources |
Creating/Editing Aliases
| Field | Description |
|---|---|
| Name | Unique name (letters, numbers, underscore only) |
| Type | Alias type (see above) |
| Description | Optional description |
| Content | IP addresses, networks, or URLs (one per line) |
| Categories | Selection from the existing categories (from 3.37.0 multi-select instead of free text) |
| Protocol Filter | Any, IPv4, or IPv6 (for URL types) |
| Update Interval | Refresh frequency for URL-based aliases |
Using Aliases in Rules
Created aliases automatically appear in the network selector of firewall rules under the "Aliases" group.
Categories
Categories are used to organize firewall rules and aliases. They can be color-coded.
- Create: Set name and color
- Edit: Change name and color
- Delete: Remove category (assignments are resolved)
Categories are displayed as colored chips in the rule and alias overview.
From 3.37.0 the rule and alias editors offer the existing categories as chips to select. Create new categories in the Categories tab and apply them first. OPNsense stores categories as IDs; the agent converts the names into IDs when applying, unknown names lead to a clear error (before, names were sent and rejected by OPNsense).
The Aliases page and the Aliases tab of the firewall rules behave the same after applying (notice with errors, only successful changes are taken over).
NAT Source (Outbound NAT)
Outbound NAT rules control source address translation for outgoing traffic.
Templates
| Template | Description |
|---|---|
| Empty | Empty rule |
| Outbound LAN | Standard NAT for LAN traffic |
| Outbound All Interfaces | NAT for all interfaces |
Rule Fields
| Field | Description |
|---|---|
| Enabled | Enable/disable rule |
| Interface | Outgoing interface |
| IP Version | IPv4, IPv6, or both |
| Protocol | Network protocol |
| Source | Source network (with NOT and network selector) |
| Destination | Destination network (with NOT and network selector) |
| Destination Port | Destination port |
| Target IP (Translation) | Translated source address |
| Target Port (Translation) | Translated source port |
| Log | Enable logging |
| Description | Free-text description |
NAT Port Forward
Port forward rules redirect incoming traffic to internal servers.
Templates
| Template | Description |
|---|---|
| Empty | Empty rule |
| Port Forward HTTP | HTTP forwarding (port 80) |
| Port Forward HTTPS | HTTPS forwarding (port 443) |
| Port Forward RDP | RDP forwarding (port 3389) |
| Port Forward SSH | SSH forwarding (port 22) |
Rule Fields
| Field | Description |
|---|---|
| Enabled | Enable/disable rule |
| Interface | Incoming interface (typically: WAN) |
| IP Version | IPv4, IPv6, or both |
| Protocol | Network protocol |
| Source | Source address (with NOT and network selector) |
| Source Port | Source port |
| Destination | External destination address (with NOT and network selector) |
| External Port | Port on the interface (public port) |
| Target IP (Redirect) | Internal server (IP address) |
| Internal Port | Port on the internal server |
| Log | Enable logging |
| Description | Free-text description |
Example: Forward a Web Server
To make an internal web server (192.168.1.100:443) publicly accessible, create a port forward rule on the WAN interface with external port 443 and target IP 192.168.1.100, internal port 443.
IPsec MSS Clamping (since v3.6.0)
Large TCP packets over IPsec tunnels often need MSS clamping. The reason is the IPsec overhead of 50 to 80 bytes, plus a smaller WAN MTU on PPPoE or DS-Lite lines, even when a router such as a Fritzbox sits in front. Without clamping, SMB, RDP or HTTPS over the tunnel typically hang while ping works. The standard is a rule under Firewall > Settings > Normalization on the IPsec (enc0) interface. It covers all tunnels and future networks.
Two system scripts and a predefined check handle this:
| Component | Effect |
|---|---|
| OPNsense IPsec MSS-Clamping Check | Read-only. Checks existing rules and their coverage per tunnel remote network, measures the WAN path MTU with DF pings to the peer or to the internet, counts fragmentation and tests the path MTU through every active tunnel |
| OPNsense IPsec MSS-Clamping aktivieren | Creates the enc0 rule with max-mss and reloads the filter. Since v3.11.0 it uses each firewall's SUGGESTED_MSS from the latest check result, 1350 without a result. An existing enc0 rule is only adjusted, LAN-side rules stay untouched, and a config.xml backup is made first |
| Check "IPsec MSS-Clamping" | Predefined health check with the check script and the enable script as remediation. Auto-remediation is off by default |
Check results:
| Result | Exit code | Meaning |
|---|---|---|
CLAMPING_OK | 0 | enc0 rule exists and is active |
NO_IPSEC | 0 | IPsec is not active |
CLAMPING_NONSTANDARD | 1 | All remote networks are clamped only by LAN-side rules. Works, but must be maintained per network and only applies to that interface |
CLAMPING_TOO_HIGH | 1 | max-mss on enc0 is higher than the recommended value |
CLAMPING_RECOMMENDED | 1 | No rule, but no measured evidence. Clamping is still recommended |
CLAMPING_PARTIAL | 2 | Only some remote networks are covered by LAN-side rules |
CLAMPING_NEEDED | 2 | No rule and WAN or tunnel MTU below 1500, or ICMP "fragmentation needed" received |
For custom fields the check prints FIELD:MSS_STATUS, FIELD:MSS_CLAMP, FIELD:WAN_PMTU and FIELD:SUGGESTED_MSS. If the peer does not answer pings, the check measures the own uplink via 1.1.1.1, 8.8.8.8 or 9.9.9.9. The enable script takes SUGGESTED_MSS automatically per firewall (see Passing Check Values to Scripts) and logs the value it used. After a successful run the check runs again on the firewall automatically. For a fixed value, copy the enable script, remove the # DZ-CHECK-VAR line and set MSS. Route-based tunnels (VTI, ipsecX) are not covered by the enc0 rule; set the MSS on the interface itself there.
Legacy Migration for IPsec and Firewall Rules (since v3.6.3)
Newer OPNsense versions move the old pages for IPsec tunnels (phase 1/2) and firewall rules into legacy plugins. Before updates, both should be switched to the new areas VPN > IPsec > Connections and Firewall > Rules. Each has a dry-run and an execute variant:
| Script | Effect |
|---|---|
| OPNsense IPsec Legacy-Migration (Probelauf) | Read-only. Shows the planned connection for every active legacy tunnel with IDs, proposals, children, PSK and WAN rules, and what stays manual |
| OPNsense IPsec Legacy-Migration (ausfuehren) | Creates connections, PSK and WAN rules, disables the legacy phase 1 entries and reloads IPsec and the filter |
| OPNsense Regel-Migration Legacy -> Rules (Probelauf) | Read-only, OPNsense 26.1 or later. Simulates importing all legacy rules and lists rules that cannot be converted |
| OPNsense Regel-Migration Legacy -> Rules (ausfuehren) | Creates all legacy rules as new rules, disables the legacy rules and reloads the filter |
IPsec: The mapping follows OPNsense's own legacy rendering. Crypto, IDs, lifetimes and reqids stay the same; under IKEv2 several phase 2 entries are merged into one child as before. Because OPNsense only creates the automatic WAN rules for IKE (UDP 500/4500) and ESP for legacy tunnels, the migration adds these rules as new firewall rules. Mobile/road-warrior, EAP and XAuth, route-based tunnels (VTI), transport mode and phase 2 with NAT are not migrated automatically. If a tunnel was up before the migration and does not come back within 90 seconds, the script restores the old configuration automatically.
Rules: The migration uses OPNsense's built-in converter and keeps the UUID of every rule, so a second run updates instead of duplicating. Migrated rules are placed after already existing new rules to keep the current evaluation order. All rules are migrated together; if one rule cannot be converted, the script stops without changes. After reloading it checks that every previously active rule is back in the ruleset and that Control is still reachable, otherwise it rolls back automatically.
In both cases the legacy entries stay in the configuration as disabled entries, and a backup is written to /conf/backup/ first. The dry runs are available as predefined checks OPNsense Legacy-IPsec and OPNsense Legacy-Firewall-Regeln to see the state across all firewalls. Since v3.12.0 the check OPNsense Legacy-IPsec is only critical when active legacy tunnels exist but the plugin os-strongswan-legacy is missing, because OPNsense then does not bring these tunnels up. Migratable tunnels and tunnels with manual items are a warning. After the migration the check reports OK, because disabled legacy rules no longer count. Running it again then changes nothing and does not reload the filter. Already migrated rules are never overwritten by their disabled legacy copy.
Security baseline and vulnerable packages (since v3.40.0)
Two predefined checks, both read-only. They only run once you distribute them with a job (Automation → Jobs, type check). There is no auto-remediation.
OPNsense Sicherheits-Grundcheck (security baseline) only rates what can be read reliably from /conf/config.xml. Aliases in rules are not resolved (then no rating).
| Check | Result |
|---|---|
| Web GUI reachable from WAN: active pass rule on WAN (also floating with WAN), source any, destination (self), WAN address or any, port empty or GUI port, protocol TCP/any – and the GUI listens on all interfaces or on WAN. Legacy rules and rules from 26.1 (Firewall: Rules) | critical |
| SSH enabled with root login and password authentication | warning |
| Web GUI over http instead of https | warning |
GUI TLS minimum below TLS 1.2 (only when readable from the generated lighttpd configuration, otherwise unknown) | warning |
| 2FA (TOTP server in the GUI authentication), users with a shell, users with API keys | info only (FIELD) |
Whether root still has the default password is not checked – this cannot be determined reliably from the stored hash. The age of API keys is not stored in config.xml either. FIELD output: GUI_WAN_EXPOSED, GUI_PROTOCOL, SSH_ENABLED, SSH_ROOT_PASSWORD, TLS_MIN, GUI_2FA, SHELL_USERS, API_KEY_USERS. Exit 0 = OK, 1 = warning, 2 = critical, 3 = no OPNsense / not evaluable.
OPNsense verwundbare Pakete (pkg audit) runs pkg audit -F -q (fetches the vulnerability database). If the download fails, the check uses the existing database (FIELD:VULN_DB=cached). Exit 0 = no vulnerable packages, 2 = vulnerable packages installed (list in the log and in FIELD:PACKAGES, truncated), 3 = check not possible. The fix is usually an OPNsense update; if packages stay listed, there is no fix yet.
Alerts for certificates, gateways and VPN (since v3.40.0)
Control reports expiring ACME certificates, degraded gateways and – opt-in only – IPsec tunnels and WireGuard sites that are down. In the VPN tab and in the VPN overview you enable monitoring per tunnel with Monitor; the pill monitored shows the state. The tab Overview → Gateways shows the history of the last 30 days. Details: Notifications.
Templates (since 3.46.0)
Under OPNsense > Templates you create an alias, a filter rule or an outbound NAT rule (source NAT) once and roll it out to many firewalls. Control then manages the template: it regularly checks whether it is still correct on every firewall and reports differences. Nothing is ever overwritten automatically - aligning only happens when you trigger it.
Target
A template applies to one or more firewalls, an OPNsense group, a customer or all firewalls (including ones added later). Customer-bound users only see the templates of their customer and can only target their customer or single firewalls of their own. Creating, changing and rolling out need OPNsense edit or tasks like any change on a firewall; viewing only needs the read right.
Marker
Every object rolled out gets the marker [DZT:<no>] (template number) at the start of its description, e.g. [DZT:12] DATAZONE admins. Control finds the object again by it - even if it was renamed or moved on the firewall. If someone removes the marker, Control still recognises the object by its remembered UUID and shows it as different.
Alias names are unique on a firewall. If an alias with the template's name already exists there without the marker, the firewall shows conflict: Control does not touch it. Adopt marks the existing alias and aligns it to the template content.
Interface placeholders
In rules and outbound NAT you write interfaces as WAN, LAN or by the interface description (e.g. GUEST). Networks are LAN net, WAN address and so on; any, (self), aliases and networks like 10.0.0.0/8 work as well. Control inserts the matching interface per firewall (description from config.xml; if the WAN interface is called e.g. "Internet", WAN resolves to it as long as the agent reports the key). If an interface does not exist on a firewall, that firewall shows failed with the reason - nothing is rolled out there.
Status per firewall
| Status | Meaning |
|---|---|
| current | Object present and equal to the template |
| different | Object present but fields differ (listed in the note) |
| missing | Object not on the firewall |
| conflict | Alias with the same name without marker (or owned by another template) |
| running | Rollout/removal in progress |
| failed | Placeholder not resolvable or last rollout failed (reason in the note) |
| agent too old | Agent below 3.37.0 - templates are not rolled out there |
| orphaned | Template deleted or firewall no longer in the target, but the object is still there |
| no data | The firewall has not reported rule/alias data yet |
Only the fields the template defines are compared; lists such as alias content regardless of order. The check runs when the page is opened, with Check now and hourly in the background. It is based on the data the agent sends with its heartbeat (up to 5 minutes old).
Rolling out and aligning
Roll out (to all targets or per firewall) first shows a preview: per firewall Create, Align, Nothing to do or why it is not possible (offline, agent too old, update run active, conflict). Only after confirming (typed confirmation from 5 firewalls) Control creates one task per firewall - the same way as the firewall rules: write right and customer scope are checked, the firewall is locked during an update run, and config.xml is backed up first. Filter rules and outbound NAT use the automatic rollback from 3.37.0.
New rules are added at the end of the firewall's rule list. Change the order in the firewall rules if needed; aligning keeps the position. Agent 3.37.0 or newer is required.
Removal only on request
Control never deletes anything on a firewall by itself. If a template is deleted or a firewall leaves the target, the object stays there and shows orphaned. Then you choose per firewall:
- Remove from firewall - the object is deleted by its UUID (after confirmation). If an alias is still used by rules, OPNsense refuses.
- Stop managing - the object stays unchanged, Control no longer checks it.
A deleted template disappears from the list as soon as no firewall is orphaned any more.
Diagnostics (since 3.48.0)
In the detail panel of a firewall, the Network group has the Diagnostics tab. Everything is fetched live from the agent (agent RPC) when you open it or press a button - Control stores none of it and changes nothing on the firewall. If the firewall runs an agent older than 3.48.0, the tab shows Agent update required; trigger an update in the Agent tab.
Interfaces
Packets, bytes, errors and drops per direction plus collisions for every interface (netstat -i -b -d -n --libxo json, the text output without libxo). The names from the configuration (WAN, LAN, Guests ...) are shown above the device name (igb0, vlan0.10). Errors, drops and collisions above 0 are red. The counters run since the last reboot of the firewall - use Refresh to see whether they are rising right now.
ARP/NDP
The ARP table (IPv4, arp -an) and the NDP table (IPv6, ndp -an) in one list with IP, MAC, interface, expiry and type. Hostnames come from the DHCP leases where known. The search field filters by IP, MAC, name and interface; at the top you switch between all, ARP and NDP.
DHCP leases
All leases of the DHCP servers running on the firewall in one list - with IP, MAC, hostname, interface, start, end, type (dynamic/static) and server:
| Server | Source |
|---|---|
| ISC DHCP | configctl dhcpd list leases 4, reservations from the configuration (also without a current lease, as "reserviert") |
| Kea (OPNsense 24.1+) | configctl kea list leases4, otherwise the lease file /var/db/kea/dhcp4.leases; reservations are "static" |
| Dnsmasq (OPNsense 25.1+) | /var/db/dnsmasq.leases; leases without expiry are "static" |
The count per server is shown at the top. If a server cannot be read, a yellow note gives the reason. The DHCP tab of the overview keeps showing the state of the last heartbeat (ISC only).
Firewall log
Searches the pf firewall log of the firewall (/var/log/filter/filter_*.log, newest file first, same field layout as the OPNsense GUI). Filters:
- Time range 15 minutes, 1 hour or 24 hours
- Action all, passed (pass) or blocked (block)
- Interface and protocol
- Source/destination IP - a full address matches exactly that one, with a prefix a network (
10.0.0.0/24), otherwise part of the address is enough (e.g.192.168.10.) - Source/destination port - must match exactly
- Rows - default 500, at most 2000
Each row shows time, interface, action, direction, protocol (TCP with flags), source and destination with port and the name of the rule (from the running rule set, otherwise the rule ID). Only one search runs per firewall at a time, and per search the agent reads at most 96 MB of log; if that is not enough, Control says so - then shorten the time range or add filters. Only rules with logging enabled appear in the log.
Packet capture
Starts tcpdump on an interface of the firewall and offers the result as .pcap for download (open it e.g. with Wireshark).
- Limits: at most 120 seconds, 10000 packets and 20 MB - whichever comes first ends the capture. The first 1600 bytes of each packet are stored. Only one capture runs per firewall at a time; a running one can be stopped. At most 3 captures or 60 MB are kept on the firewall, and
/tmpneeds at least 100 MB free - otherwise the agent refuses to start with a note. - Agent restart: tcpdump runs under
timeoutand ends at the latest 5 seconds after the limit, even if the agent restarts in the middle. At startup the agent ends leftover captures and lists existing files again (status "done (agent restart)") so you can download or delete them. - Filter: only a fixed vocabulary is allowed -
host,net,port,portrange,src,dst,proto,less,greater,ether host,vlan, protocols such astcp,udp,icmp,icmp6,ip,ip6,arp,esp,gre,carp, plusand,or,notand parentheses, with IP addresses, networks, MAC addresses and numbers as values. Example:host 10.0.0.5 and tcp port 443. Anything else (special characters, options like-w, file names, host names) is rejected by the agent; the filter is never run through a shell. - Promiscuous is off by default - you see traffic from and to the firewall and the traffic it routes.
- Deletion: after the download Control deletes the file from the firewall immediately. At the latest one hour after the end the agent deletes it itself, also after an agent restart. Delete removes it right away.
- On the firewall the files are stored as
/tmp/dz-capture-<ID>.pcap.
Permissions
| Permission | Area | Default |
|---|---|---|
Diagnostics (opnsense.diagnostics) | Interfaces, ARP/NDP, DHCP leases | Operator and Support, not Viewer |
Search firewall log (opnsense.firewall_log) | Firewall log | admins only or granted explicitly |
Packet capture (opnsense.capture) | Start, stop, download, delete | admins only or granted explicitly |
The firewall log and captures contain connection data and contents of customer traffic. These permissions are therefore never granted through "all sub-tabs" (*.subtabs) and are part of no default role except Administrator. The Files tab follows this too: without the respective permission /var/log/filter* and /tmp/dz-capture-* are blocked there (download, ZIP of the parent folder, rename, delete, upload) and hidden in listings. Customer-bound users only see firewalls of their customer. The audit log records every log search (with its filters), every start, stop and deletion and every download of a capture. The Diagnostics tab appears as soon as one of the three permissions is present; the areas inside follow the respective permission.
Context Menu
Right-clicking on a firewall in the table provides quick actions:
- Open Details - Show the detail panel
- Open WebUI - Open the OPNsense web interface in a new tab
- Open Shell - Start a remote terminal
- Start Tunnel - Quick access to tunnel templates
- Start Update - Trigger a firmware update
- Run Script - Execute a script from the library
Tunnel Templates
| Template | Target Port | Description |
|---|---|---|
| OPNsense WebUI | 443 | Access to the web interface |
| Agent SSH | 22 | SSH via the agent |
| SSH | 22 | Direct SSH access |
| VNC | 5900 | VNC remote access |
| HTTP | 80 | HTTP forwarding |
| Custom | Any | Any port |
Update Schedules and Update Runs
Since v3.7.0 OPNsense updates execute as update runs with real verification - HA pairs (CARP) are updated rolling: BACKUP first, health check, settle time, then the MASTER with CARP maintenance (planned failover). Details, failure behaviour and options: OPNsense HA Updates.
| Type | Description | Reboot |
|---|---|---|
| System Update | Packages only; base/kernel stays open as reboot pending | never |
| Update + Reboot | Packages + base/kernel, reboot only when OPNsense requires it; HA rolling | when required |
| Major Upgrade | Step by step up to the target or Latest (e.g. 23.7 → 26.7) | two reboots per step |
The HA column of the firewall table shows the CARP role (MASTER / BACKUP / MAINT / INIT) with the HA partner in the tooltip. The result of every run is shown in the Jobs tab (banner, status dot, last runs per schedule, run details with resume/abort).
Schedules can be configured as one-time or recurring (daily, weekly, monthly, cron). See Update Schedules.
Additional Actions
| Action | Description |
|---|---|
| Backup | Create a configuration backup (config.xml) |
| Config Sync | Synchronize configuration between HA firewalls |