Skip to content

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 ​

ColumnDescription
CustomerAssigned customer
NameDisplay name of the firewall (editable in the detail panel)
SiteSite of the customer (since v3.38.0, free text before), hidden by default
HostnameHostname of the firewall
OPNsense VersionInstalled OPNsense version
EditionCommunity (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 VersionDATAZONE Agent version
WAN IPPublic WAN address
UptimeTime since last reboot
CPU / RAM / DiskCurrent utilization as progress bars
Last ResponseTimestamp of the last agent heartbeat
Last Config ChangeTimestamp of the last configuration change
GatewaysStatus of configured gateways (color-coded)
WebUIDirect 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 ​

  1. Install the agent on the OPNsense appliance (see Agent Installation)
  2. The agent automatically detects that the system is FreeBSD/OPNsense
  3. The firewall appears in the OPNsense module

Manual (API-based) ​

  1. Click Add Firewall
  2. 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 ​

TabIconDescription
OverviewMonitorSystem information with sub-tabs (see below)
ChecksClipboardCheckHealth check results and status
JobsListTodoRunning and completed tasks
ShellTerminalRemote terminal to the OPNsense shell
LogFileTextExecution logs for all actions
GroupsTagsManage group membership
UpdatesRefreshCwUpdate history and schedules
AgentCpuAgent status, logs, and management
DeleteTrash2Remove 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>] (or configctl 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; configd can 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):

ReasonWhen
NightlyEvery night at opn_backup_nightly_time (default 02:30, same time zone as notifications) for every firewall that is online
Before updateBefore an update run touches the node for the first time. If the backup fails, the update still continues (note in the log)
Before changeBefore every change made from Control: rules, NAT, aliases, categories, WireGuard
ManualButton Back up now
Before / After restoreState 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:

WhatPermission
See the listOPNsense View (sub-tab Backups)
Back up nowWrite permission in the module (tasks/edit)
Changes + DownloadRead config backups (opnsense.config_backup)
RestoreRestore 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:

  1. Click Restore in the row and type the firewall name.
  2. 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.
  3. The agent checks the version (checksum, well-formed XML with <opnsense>), additionally saves the previous file as /conf/backup/config-<time>-datazone.xml on the firewall, writes the new file atomically and schedules a reboot in one minute. It reports the result before the reboot.
  4. 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:

SectionMatched byNotes
Aliasesnamecontent compared without order
Filter rulesinterface + action + description (without description: protocol/source/destination/port)legacy and MVC rules; sequence, creator and timestamps do not count
NATkind (port forward, outbound, 1:1, NPT) + interface + descriptionplus outbound mode
Interfaceskey (wan, lan, opt1 …)description, device, addresses, gateway, MTU …
Systemgeneral / DNS / NTPhostname excluded
Unbound DNSoverrides by host + domain or namelegacy and MVC settings
WireGuard, IPsecname or descriptionkeys and PSKs only masked
Users and groupsnamenames only, no hashes, keys or API keys
Certificatesdescriptionname 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>][&sections=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.conf and 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.

ColumnDescription
CustomerAssigned customer
FirewallName of the firewall
InstanceName of the VPN instance
TypeWG RW (Road Warrior), WG S2S (Site-to-Site), OpenVPN, IPsec
InterfaceWireGuard interface (wg0, wg1, etc.)
PortListening port
Tunnel NetworkIP range of the tunnel
PeersNumber of configured peers
Active PeersNumber of currently connected peers
StatusOnline/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:

FieldDescription
FirewallTarget firewall (online + API-ready only)
NameName of the WireGuard instance
PortListening port (default: 51820)
Tunnel NetworkIP address and subnet (e.g., 10.10.10.1/24)
DNS for ClientsDNS server for client configurations
Create WAN RuleCreates a UDP firewall rule on the WAN interface
Allow-All on WireGuard InterfaceAllows 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:

FieldDescription
NameName of the peer (e.g., employee name)
Tunnel IPIP address of the peer in the tunnel network
DNSDNS server for the peer
MTUOnly if different from 1420
Split TunnelRoute 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 ​

ModeDescription
Full TunnelAll traffic is routed through the VPN tunnel (0.0.0.0/0, ::/0)
Split TunnelOnly 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:

ActionDescription
Enable/DisableTemporarily disable the peer without deleting it
Edit Allowed IPsChange the allowed IP ranges for the peer
Configuration/QR CodeShow client configuration (only available immediately after creation)
DeletePermanently 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

FieldDescription
Tunnel SubnetPoint-to-point network. Suggestion: the next free /30 from 10.0.80.0/22
PortWireGuard port on both sides. Suggestion: the next free one from 51830, allowed range 1024–65535
Connection ModeEqual, A=Primary, or B=Primary
EndpointsIP or DNS name without port (depends on connection mode). Prefilled with the firewall's external IP
Networks A → B / B → AWhich 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 ruleOpen the UDP port - from 3.33.0 only on the side that accepts connections (with A/B = primary only there)
Allow-AllAllow 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:

  1. Key generation on both firewalls
  2. Create WireGuard instances with generated keys
  3. Add peers on both sides with PSK (Pre-Shared Key)
  4. Create firewall rules (if enabled)

Connection Mode (since v2.2.10) ​

ModeDescription
EqualBoth firewalls have static IPs. Either side can initiate the connection. Both get endpoint + keepalive configured.
A = PrimaryFirewall 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 = PrimaryReversed: 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:

TabDescription
RulesFilter rules (main rules)
AliasesManage aliases
CategoriesManage categories
NAT SourceOutbound NAT rules (Source NAT)
NAT Port ForwardPort 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.

AreaAutomatic rollbackConnectivity check
Filter rulesyes (OPNsense 25.7 / 26.1)yes
Source NATyes (OPNsense 25.7 / 26.1)yes
Port forwards (API from OPNsense 26.1)no - separate OPNsense model (DNat) not covered by the rollbackyes, clear notice on loss
Aliases, categoriesnono

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:

FieldDescription
#Sequence number (order)
ActiveEnabled/Disabled (toggle)
ActionPass (green), Block (red), or Reject (orange)
DirectionIn or Out
InterfaceNetwork interface (WAN, LAN, etc.)
ProtocolTCP, UDP, ICMP, etc.
SourceSource address or alias (with NOT indicator)
DestinationDestination address or alias (with NOT indicator)
GatewayAssigned gateway
LogWhether the rule is logged
CategoriesAssigned categories as colored chips
DescriptionFree-text description

Creating Rules ​

Click Add Rule to create a new rule. Optionally select a template:

TemplateDescription
EmptyEmpty rule for manual configuration
Allow HTTP/HTTPSAllow web traffic (port 80/443)
Allow SSHAllow SSH access (port 22)
Allow DNSAllow DNS queries (port 53)
Allow ICMPAllow ping
Allow SMTPAllow email sending (port 25/587)
Allow WireGuardAllow WireGuard VPN
Allow OpenVPNAllow OpenVPN
Allow IPsecAllow IPsec VPN
Block AllBlock 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:

GroupOptions
Generalany (any address), (self) (firewall itself)
Interface AddressesIP address of each interface (e.g., LAN address, WAN address)
Interface NetworksSubnet of each interface (e.g., LAN net, WAN net)
AliasesAll configured aliases
Single Host or NetworkManual 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 ​

TypeDescriptionExample
Host(s)Individual IP addresses or hostnames192.168.1.100, server.example.com
Network(s)IP subnets in CIDR notation192.168.1.0/24, 10.0.0.0/8
URL Table (IPs)URL providing an IP listBlocklist URLs
URL TableURL providing a mixed listExternal filter lists
GeoIPCountry-based IP rangesCountry codes
ExternalExternally managed aliasesExternal sources

Creating/Editing Aliases ​

FieldDescription
NameUnique name (letters, numbers, underscore only)
TypeAlias type (see above)
DescriptionOptional description
ContentIP addresses, networks, or URLs (one per line)
CategoriesSelection from the existing categories (from 3.37.0 multi-select instead of free text)
Protocol FilterAny, IPv4, or IPv6 (for URL types)
Update IntervalRefresh 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 ​

TemplateDescription
EmptyEmpty rule
Outbound LANStandard NAT for LAN traffic
Outbound All InterfacesNAT for all interfaces

Rule Fields ​

FieldDescription
EnabledEnable/disable rule
InterfaceOutgoing interface
IP VersionIPv4, IPv6, or both
ProtocolNetwork protocol
SourceSource network (with NOT and network selector)
DestinationDestination network (with NOT and network selector)
Destination PortDestination port
Target IP (Translation)Translated source address
Target Port (Translation)Translated source port
LogEnable logging
DescriptionFree-text description

NAT Port Forward ​

Port forward rules redirect incoming traffic to internal servers.

Templates ​

TemplateDescription
EmptyEmpty rule
Port Forward HTTPHTTP forwarding (port 80)
Port Forward HTTPSHTTPS forwarding (port 443)
Port Forward RDPRDP forwarding (port 3389)
Port Forward SSHSSH forwarding (port 22)

Rule Fields ​

FieldDescription
EnabledEnable/disable rule
InterfaceIncoming interface (typically: WAN)
IP VersionIPv4, IPv6, or both
ProtocolNetwork protocol
SourceSource address (with NOT and network selector)
Source PortSource port
DestinationExternal destination address (with NOT and network selector)
External PortPort on the interface (public port)
Target IP (Redirect)Internal server (IP address)
Internal PortPort on the internal server
LogEnable logging
DescriptionFree-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:

ComponentEffect
OPNsense IPsec MSS-Clamping CheckRead-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 aktivierenCreates 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:

ResultExit codeMeaning
CLAMPING_OK0enc0 rule exists and is active
NO_IPSEC0IPsec is not active
CLAMPING_NONSTANDARD1All remote networks are clamped only by LAN-side rules. Works, but must be maintained per network and only applies to that interface
CLAMPING_TOO_HIGH1max-mss on enc0 is higher than the recommended value
CLAMPING_RECOMMENDED1No rule, but no measured evidence. Clamping is still recommended
CLAMPING_PARTIAL2Only some remote networks are covered by LAN-side rules
CLAMPING_NEEDED2No 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:

ScriptEffect
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).

CheckResult
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 authenticationwarning
Web GUI over http instead of httpswarning
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 keysinfo 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 ​

StatusMeaning
currentObject present and equal to the template
differentObject present but fields differ (listed in the note)
missingObject not on the firewall
conflictAlias with the same name without marker (or owned by another template)
runningRollout/removal in progress
failedPlaceholder not resolvable or last rollout failed (reason in the note)
agent too oldAgent below 3.37.0 - templates are not rolled out there
orphanedTemplate deleted or firewall no longer in the target, but the object is still there
no dataThe 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:

ServerSource
ISC DHCPconfigctl 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 /tmp needs at least 100 MB free - otherwise the agent refuses to start with a note.
  • Agent restart: tcpdump runs under timeout and 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 as tcp, udp, icmp, icmp6, ip, ip6, arp, esp, gre, carp, plus and, or, not and 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 ​

PermissionAreaDefault
Diagnostics (opnsense.diagnostics)Interfaces, ARP/NDP, DHCP leasesOperator and Support, not Viewer
Search firewall log (opnsense.firewall_log)Firewall logadmins only or granted explicitly
Packet capture (opnsense.capture)Start, stop, download, deleteadmins 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 ​

TemplateTarget PortDescription
OPNsense WebUI443Access to the web interface
Agent SSH22SSH via the agent
SSH22Direct SSH access
VNC5900VNC remote access
HTTP80HTTP forwarding
CustomAnyAny 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.

TypeDescriptionReboot
System UpdatePackages only; base/kernel stays open as reboot pendingnever
Update + RebootPackages + base/kernel, reboot only when OPNsense requires it; HA rollingwhen required
Major UpgradeStep 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 ​

ActionDescription
BackupCreate a configuration backup (config.xml)
Config SyncSynchronize configuration between HA firewalls

DATAZONE Control Documentation