How to install Zenarmor on OPNsense: the complete step-by-step guide

You install Zenarmor on OPNsense in five main steps: disable hardware offloading, install the repository plugin os-sunnyvalley and then os-sensei under System > Firmware > Plugins, run the setup wizard from Zenarmor > Dashboard, activate a trial or licence, and configure your first policies. On suitable hardware, a basic installation is done within an hour. The real quality lies in the choices that follow: reporting database, deployment mode, interfaces and policies.

As an official Zenarmor partner in the Netherlands, we checked every step against Zenarmor's current installation documentation (release 2.7, September 2026) and the OPNsense manual, and added the pitfalls we run into on real projects. Note that the OPNsense page sometimes lags behind Zenarmor's own documentation; where they differ, we follow Zenarmor. Would you rather not do it yourself? At the end you will find how Secrotec can do it for you.

Before you start: what you need

• An up-to-date OPNsense installation. Zenarmor lists OPNsense 24.7 and later as supported, and the release notes show that the current 26.7 series is actively supported. Fully update OPNsense first.
• Administrator access to the web interface (for example root), and ideally console or SSH access in case something goes wrong.
• Adequate hardware: RAM, CPU and disk in line with the table below.
• Suitable network cards for netmap, the subsystem Zenarmor uses to read packets.
• A licensing decision: a 15-day free trial, an existing subscription key or the Free Edition. According to Zenarmor, the Free and Home editions are intended for non-commercial use only.
• A fallback: a configuration backup and, for a virtual firewall, a snapshot.

This guide covers OPNsense, the platform Zenarmor itself recommends. Zenarmor also runs on pfSense CE 2.7 and 2.8, FreeBSD and several Linux distributions. pfSense Plus is no longer supported.

Hardware requirements and sizing

Zenarmor publishes the following guidance based on the number of active devices and WAN bandwidth (source: hardware requirements):

Active devices	Max. bandwidth	Min. RAM	Min. CPU
0–50	300 Mbps	1 GB	Dual-core x86_64 (PassMark 200+)
50–100	500 Mbps	4 GB	Intel i3 dual-core 2.0 GHz
100–250	1 Gbps	8 GB	Intel i5 dual-core 2.2 GHz
250–1,000	1–2 Gbps	16 GB	Intel i5 dual-core 3.2 GHz
1,000–2,000	1–2 Gbps	32 GB	Intel i7 quad-core 3.4 GHz
2,000+	2–4.5 Gbps	64 GB	Intel i9 quad-core 3.0 GHz

Four points from the documentation that are often missed:

• Elasticsearch needs at least 8 GB of RAM. With less memory, the wizard classifies your system as low-end and does not offer local Elasticsearch, so you fall back to SQLite.
• Single-core performance matters more than the number of cores. A fast quad-core beats a slow many-core processor.
• Disk space: allow roughly 5 MB per hour per Mbit/s of throughput. Zenarmor's own example for an active 100 Mbps link is about 6 GB per day and 168 GB per month. Use an SSD.
• Virtualisation: with more than 500 active devices and more than 500 Mbps of sustained WAN traffic, Zenarmor advises against running as a virtual guest, because resources are shared.

If you are buying new hardware, you can choose your own x86 hardware, a virtual machine on Proxmox, Hyper-V or VMware, or an appliance from Deciso, the company behind OPNsense, via the OPNsense shop. Always check an appliance's RAM against the table.

Network cards and netmap

Zenarmor reads packets through netmap, a FreeBSD subsystem for fast access to raw Ethernet frames. The documentation names Intel cards using the em(4) and igb(4) drivers as stable and fast. If native netmap support on your card is unreliable, the emulated netmap driver mode is the safe choice, and it is the default on OPNsense. In virtual machines, start with that default mode and only then test whether native netmap runs reliably.

Step 1: back up and disable hardware offloading

1. Create a configuration backup under System > Configuration > Backups and download the file. For a virtual firewall, take a snapshot as well.
2. Go to Interfaces > Settings.
3. Make sure hardware checksum offloading, TCP segmentation offloading (TSO) and large receive offloading (LRO) are disabled, and disable VLAN hardware filtering.
4. Save and reboot the firewall so the settings are definitely active on every interface.

Why? According to Zenarmor, hardware offloading is incompatible with netmap. Recent OPNsense versions disable checksum, TSO and LRO offloading by default, but always check, especially after a migration or earlier performance tuning.

Step 2: install the os-sunnyvalley repository plugin

1. Log in to the OPNsense web interface with an administrator account.
2. Go to System > Firmware > Plugins.
3. Search for os-sunnyvalley, the vendor repository of Sunny Valley, the company behind Zenarmor.
4. Click the + icon. OPNsense switches to the update screen and installs the plugin.
5. Return to the Plugins tab and refresh the page (F5) if the list has not updated yet.

Step 3: install the os-sensei Zenarmor plugin

1. On the same tab, search for os-sensei. Sensei was Zenarmor's original product name.
2. Click +. A third-party software notice appears; confirm with Install.
3. Wait for the installation to finish. A Zenarmor menu appears in the left-hand navigation; refresh the page if needed.

Prefer the console? Choose option 8 (Shell) in the OPNsense console menu and run pkg install os-sunnyvalley followed by pkg install os-sensei. You still complete the wizard in the web interface afterwards. See Zenarmor's OPNsense installation guide.

Step 4: run the initial configuration wizard

Open Zenarmor > Dashboard and the wizard starts automatically. Zenarmor is not operational until the wizard has been completed. The steps follow the official description of the initial configuration.

4a. Welcome

Accept the Terms of Service and Privacy Policy by ticking the checkbox, then click I Agree.

4b. Hardware Check & Reporting Database

The wizard analyses your hardware and reports compatible, low-end or incompatible. With incompatible hardware the setup stops. Next, you choose the reporting database:

Database	Best for	Points to note
Local Elasticsearch	Business networks that need rich reporting and longer history	At least 8 GB RAM and an SSD; not offered on low-end systems
SQLite	Small networks, labs, appliances with little RAM	Lightweight; less suited to large data volumes
Remote Elasticsearch	Larger environments, central logging, SIEM integration	Compatible with Elasticsearch 8.9.x to 8.17.1; Zenarmor needs full access; cannot be changed after the wizard

MongoDB has not been supported for new installations since September 2025. Click Install Database (local) or Next (remote). Our advice: local Elasticsearch from 8 GB of RAM; below that, SQLite, optionally combined with streaming to a syslog server or SIEM.

4c. Deployment Mode & Interface Selection

• Deployment mode. "Routed mode with emulated netmap driver" is selected by default. The native netmap driver is faster, but only with well-supported network cards. Depending on platform and version, the wizard offers other modes too; stick with the default unless you have a clear reason not to.
• CPU pinning. By default, Zenarmor pins its packet engine to dedicated CPU cores. You can turn this off with "Do not pin engine packet processors to dedicated CPU cores", for instance if you have few cores and other services are starved.
• Interfaces. Protect the LAN side. Select the physical parent interface (for example igb0) rather than individual VLAN interfaces, so Zenarmor inspects every sub-interface. Never select a parent and its VLANs at the same time.
• Security zones. Tag each interface with a zone: lan, dmz, guest, wifi, wan or a custom zone via Custom. A wrong tag, such as WAN labelled as LAN, causes filtering and reporting errors.

Click Next.

4d. Activate Subscription

You have three options: a 15-day free trial of the business subscription (email address only, no credit card), "I already have my subscription key" for an existing licence, or the Free Edition. For a business environment, choose the trial or a licence. Since 2.7, licence activation is also built into the Zenconsole registration flow.

Plan	List price	Suitable for
Free	$0	Evaluation and home labs; non-commercial, no TLS inspection
Home	$9.99 per month	Personal use; not for businesses
Unified Secure	$5.00 per user per month (10–49 users), lower for more users	Businesses: IPS, application and web control, gateway HA; TLS inspection as an add-on
Unified Secure Plus	$9.00 per user per month (10–49 users), lower for more users	Businesses needing full TLS inspection, mesh VPN and more agents
SSE, ZTNA, SASE	On request	Enterprises, MSPs, longer retention

List prices from Zenarmor's plans page: status October 2026, in USD, excluding VAT, subject to change. Minimum 10 users; the first site is included.

4e. Finish

Review the summary and click Complete. Zenarmor recommends reading the Best Practices for Zenarmor Deployment before you configure policies, and we fully agree.

Step 5: connect to Zenconsole (optional)

On OPNsense, registering with Zenconsole is optional: you can manage everything locally in the web interface. Connecting pays off if you run several firewalls, want central reporting or plan to use endpoint agents and ZTNA.

1. Go to Zenarmor > Settings > Cloud Management Portal.
2. Click Install & Configure. The agent plugin os-sensei-agent is installed in the background.
3. If necessary, create an account at dash.zenarmor.com.
4. Click Register to Cloud Management Portal and sign in. Disable your browser's pop-up blocker, otherwise registration fails (documentation).

If you later want to add the firewall to a Zenconsole organisation for central policy, back up your local policies first, because they are removed when the firewall joins. More in Zenconsole: central multi-site management.

Step 6: configure your first policies

After the wizard, there is a single Default policy. Open Zenarmor > Policies and work through the tabs:

• Security: enable the essential categories, such as malware, phishing, hacking, spam, potentially dangerous and parked domains, and firstly seen sites. A paid subscription adds advanced categories such as botnet C&C, recent outbreaks, compromised websites and newly registered domains.
• App Controls: block or restrict application categories and specific apps, for example P2P, anonymisers or remote access tools you do not use. See our article on application control.
• Web Controls: choose a profile (Permissive, Moderate or High Control) or build your own, and enforce Safe Search where needed. See the Zenarmor web filter.
• Exclusions: record exceptions for business-critical domains or systems, and document why.

Create additional policies for groups with different needs, based on interface, VLAN, network, device, user or time schedule: a stricter policy for the guest network, for example, and a separate one for IoT and OT. Note that all criteria in a policy must match at the same time (AND logic). Our rule of thumb: start with Moderate plus essential security, review the reports for a week, then tighten. That way an overly strict first policy will not block business processes. For segmentation by VLAN, read Network segmentation for NIS2 and ISO 27001.

Step 7: prepare TLS inspection

Without TLS inspection, Zenarmor mainly sees domain names and certificate details in HTTPS traffic. That is enough for much web and application control. For deeper inspection, Zenarmor offers a lightweight, certificate-based mode and full TLS inspection (decrypt and re-encrypt).

1. Check your licence. In the new plans, TLS inspection is an add-on for Unified Secure and included in Unified Secure Plus.
2. Generate or import a CA certificate in the Zenarmor settings (CA Management). Zenarmor recommends an intermediate CA so that your root CA never sits on the firewall.
3. Distribute the certificate to clients as a trusted certificate, for example through Group Policy, Intune or your MDM platform.
4. Enable it gradually per policy: start with a pilot group and use the bypass list for banking, healthcare portals and apps that use certificate pinning, among others.
5. Document what you inspect and why (GDPR; in the Netherlands a works council has a consent right under Article 27 of the Works Councils Act, and in Germany co-determination under §87 BetrVG applies).

All legal and technical details are in our article TLS inspection with Zenarmor.

Step 8: test and verify

• Live Sessions: do you see traffic from every protected interface and VLAN?
• Dashboard and Reports: do applications, web categories and threats appear?
• Test a block: visit a site in a blocked category. For HTTPS sites, the block page only displays correctly if the Zenarmor CA certificate is trusted on the client; otherwise you see a connection error.
• Look up a category: if you are unsure about a domain, check it in Zenarmor's site classification lookup.
• Load: keep an eye on CPU, RAM and disk usage in the OPNsense dashboard, particularly in the first few days.
• Business-critical services: test VPN, VoIP, video calls, backups and updates.
• Document: record the configuration and create a backup under Zenarmor > Settings > Backup and Restore.

Updates and maintenance

Keep both OPNsense and Zenarmor up to date and read the release notes with every update. Zenarmor itself advises you to:

• take a snapshot before every upgrade in virtual environments;
• test upgrades in a staging environment first;
• ensure a reliable connection and schedule updates outside office hours;
• get management approval and document the whole process;
• use the Zenarmor interface for controlled updates.

Before a major OPNsense upgrade, such as from 26.1 to 26.7, check Zenarmor's release notes for known issues; Zenarmor 2.6.2, for example, fixed a crash report on OPNsense 26.7. A fixed update process also provides evidence for ISO 27001 A.8.8 (management of technical vulnerabilities) and A.8.32 (change management).

High availability (HA)

If you run OPNsense as an HA cluster with CARP, install Zenarmor on every node. Under Zenarmor > Settings > High Availability you can see the status of the backup node: Zenarmor version, engine status, database and synchronisation. Settings and policies are synchronised from the primary firewall; after a change, a notification with a Sync button appears. HA requires a business subscription: the HA documentation refers to the Business Edition, while the new plans list "gateway HA with configuration synchronization" from Unified Secure upwards. Since 2.7, Business and higher subscriptions on OPNsense also benefit from multi-core support for 10G links.

Common pitfalls and how to fix them

Problem	Cause	Fix
Wizard does not offer local Elasticsearch	Too little RAM, system classed as low-end	Upgrade to 8 GB RAM or more, or choose SQLite or remote Elasticsearch
Instability, packet loss, interfaces dropping	Hardware offloading enabled or NIC with weak netmap support	Disable offloading, use emulated mode, choose Intel em/igb cards
Conflict with Suricata (IDS/IPS)	Both use netmap on the same interface	Run them on different interfaces, e.g. Suricata on WAN and Zenarmor on LAN
Duplicate or missing reporting for VLANs	Parent and VLAN interface both selected, or only a VLAN	Select only the parent interface, e.g. igb0
VPN traffic not visible	The OpenVPN tun interface does not support netmap	Use WireGuard (netmap-compatible) or deploy endpoint agents
Odd filtering or reporting	Wrong security zone, e.g. WAN tagged as LAN	Correct the zones in the Zenarmor configuration
Zenconsole registration fails	Browser pop-up blocker	Allow pop-ups temporarily
Disk filling up	Reporting data grows faster than expected	Set a retention period, use a larger SSD or stream data externally

If you use OPNsense as a transparent bridge, test that set-up in a lab first: bridge scenarios need extra care when choosing interfaces and the deployment mode.

Rolling back or uninstalling

• Quick fallback: put the engine into bypass mode or stop the packet engine. OPNsense keeps handling traffic as a regular firewall, without Zenarmor inspection.
• Restore the configuration: via Zenarmor > Settings > Backup and Restore.
• Full removal: follow the uninstall procedure in Zenarmor's documentation (from the shell with zenarmorctl uninstall), which asks whether you want to keep the reporting data. Then remove os-sensei and, if you wish, os-sunnyvalley under System > Firmware > Plugins.
• Last resort: restore the OPNsense configuration backup or the VM snapshot from step 1.

Prefer us to do it? Secrotec installs Zenarmor for you

Doing it yourself works well in a lab or a small office. In production environments with multiple VLANs, HA, TLS inspection or compliance requirements, it pays to get it right first time. As an official Zenarmor partner in the Netherlands, delivering projects throughout Europe, Secrotec provides:

• sizing and hardware advice: reuse existing hardware, a VM or a Deciso appliance;
• installation and configuration following Zenarmor's best practices, including HA and VLAN design;
• policies aligned with ISO 27001 Annex A, NIS2 and, in healthcare, NEN 7510;
• TLS inspection with CA roll-out and privacy documentation;
• reporting and logging that stand up as audit evidence;
• licences with a partner discount, with the price always negotiable in Zenarmor projects.

Our edge: we are ISO 27001 Lead Auditors too. We know what evidence an auditor wants to see and configure Zenarmor accordingly. Zenarmor supports compliance, but it does not make you compliant on its own. See Zenarmor licences and implementation through Secrotec, compare costs with your current firewall in the Zenarmor price comparison, read how to use reporting for NIS2 and ISO 27001, or browse our Firewall & Networks overview.