Self-hosted OPNsense fleet management for MSPs and IT teams.
Quick Start · Screenshots · Watch the walkthrough · Documentation · Security · MSPReboot
OPNManager runs on your own server and gives your staff one place to watch, back up and update every OPNsense firewall you look after, grouped by customer and site. Customers and sites are organisational groupings inside your installation — they are not tenant logins, and nobody outside your own team signs in.
All screenshots show the real interface populated with simulated data from an isolated demo fixture. Addresses are reserved documentation ranges and every organisation and hostname is fictitious.
Find firewall and connectivity problems. Agents report check-ins, gateway latency and loss, VPN tunnel state, CARP status, service state and certificate expiry. Problems become incidents — one entry per ongoing condition, opened when it starts and closed when it actually clears, rather than one email per poll.
Review configuration backups and changes. Configurations are backed up on a schedule and kept per firewall. Mark one as the approved baseline and every firewall is compared against it, ignoring serialisation noise and the fields OPNsense rewrites on every save. Nothing is ever restored automatically.
Coordinate maintenance and updates. Updates run as campaigns through canary, pilot and production rings with manual progression. Members of a CARP pair are never updated at the same time. Maintenance windows withhold notification while collection and health display continue.
A recorded tour of the running application — the fleet dashboard, finding a connectivity problem, reviewing what changed against an approved baseline, planning a ringed update, and the customer and site model, with a theme switch part way through.
▶ Watch the walkthrough — 3m42s, 1080p MP4 (11 MB). Prefer the short version? 40-second highlight.
These are pinned to the v3.25.0 release, which is where the media lives. They
were previously pointed at releases/latest, which broke the moment a later release
was published without the video attached.
Captions: docs/walkthrough.vtt ·
Transcript: docs/walkthrough-script.md.
The video is caption-led; no narration audio was produced.
Each firewall's newest backup is compared against the baseline you approved, and the diff names every change by its description rather than by line number.
Gateways with latency and loss, VPN tunnels with handshake age, service state and certificate expiry — here a degraded LTE gateway and a stopped IDS service.
Canary, then pilot, then production, with manual progression — and never both members of a CARP pair at once.
An incident opens when a condition becomes true and closes when it actually clears. Acknowledging stops the notifications without closing it.
Per-firewall WAN throughput, CPU load, memory and disk, collected on each agent check-in.
Optional, off by default, and never the only opinion in the room. Secrets are redacted before anything leaves your server, and severity is graded by what an attacker can reach rather than by how tidy a setting is: a management interface published to the internet is critical, a resolver without DNSSEC is not.
A firewall whose administration is already restricted scores accordingly, and the findings that remain are named as preferences rather than problems.
Customers group sites, sites group firewalls, each with a code, timezone, contacts and a default maintenance window.
See all 28 screenshots → — fleet health, config search, backups, bulk operations, maintenance windows, staff roles, tags, approved commands, audit history and more, in both themes.
Requires Ubuntu 22.04 LTS or newer, PHP 8.0+ (CI builds against 8.3), MySQL 8.0+ or MariaDB 10.6+, and Apache 2.4+ or Nginx 1.18+.
cd /var/www
git clone https://github.com/agit8or1/OPNMGR.git opnsense
cd /var/www/opnsense
composer install --no-dev
# Creates the opnsense_fw database, every table, the reference data and the
# default settings, and records every migration it includes as applied.
# Safe to re-import: every statement is idempotent and never overwrites a value.
mysql -u root -p < database/schema.sql
mysql -u root -p -e "
CREATE USER 'opnsense_user'@'localhost' IDENTIFIED BY 'your-secure-password';
GRANT ALL PRIVILEGES ON opnsense_fw.* TO 'opnsense_user'@'localhost';
FLUSH PRIVILEGES;"
cp .env.example .env
# Set at minimum DB_HOST, DB_NAME, DB_USER, DB_PASS and APP_URL.
chmod 640 .env
# Required: secrets are only ever stored encrypted. (create_admin.php also
# generates the key if it is missing, and stops if it is not usable.)
php scripts/generate_master_key.php
php scripts/create_admin.php
chown -R www-data:www-data /var/www/opnsense
a2ensite opnmanager && systemctl reload apache2Stage the agent package before you enroll a firewall. The package is not in git. This command downloads the one for your version from the GitHub release and verifies its signature, checksum and contents:
php scripts/stage_agent_package.php # prints READY: agent 1.8.2 staged (signed-release)If the manager cannot reach GitHub, copy os-opnmanager-agent-<version>.tar.gz and its
.release.json from the release, then run
php scripts/stage_agent_package.php --import <directory>, or upload both files on
Add Firewall. If no release exists for your commit, --build-local builds the
package from the tracked source. Until a package is staged, Settings and Add Firewall
show the reason instead of an install command.
Open Add Firewall and click Create & Get Key. Then copy the install one-liner shown there. It is built from your own server's URL and includes the checksum of the package you staged:
# On the OPNsense firewall, as root:
fetch -o - https://<your-opnmgr-server>/downloads/plugins/install_opnmanager_agent.sh \
| env OPNMGR_BASE_URL=https://<your-opnmgr-server> OPNMGR_AGENT_SHA256=<shown> shThe installer verifies the package before it changes anything on the firewall.
Then paste the key into Services → OPNManager Agent → Quick Enrollment in the
OPNsense GUI. The agent installs as a native plugin, checks in every two minutes by default, logs to
/var/log/opnmanager_agent.log, and is managed with
service opnmanager_agent start|stop|restart.
| Version | Notes | |
|---|---|---|
| Application | 3.81.3 | Install from main. |
| Agent | v1.8.2 | Newest published OPNsense package (held behind the rollout gate). Built and signed by the release workflow; stage it with scripts/stage_agent_package.php. |
| pfSense agent | v1.0.0 | Built from agent/pfsense/ with scripts/build_pfsense_agent_package.sh. |
| Minimum supported agent | 1.3.0 | Not enforced at check-in: older agents still report in, but lose health score and version-gated features. |
| Database schema | 1.4.0 | database/schema.sql, regenerated by scripts/generate_schema.sh. |
CI enforces these against VERSION and the published artifact — application 3.81.3,
Agent: v1.8.2 — so no reference in the tree can drift out of step.
Feature availability depends on the agent version a firewall is actually running:
| Feature | Requires | Status |
|---|---|---|
| Check-ins, system stats, traffic, latency | agent 1.3.0+ | Released |
| Configuration backup, restore, drift | agent 1.3.0+ | Released |
| Fleet updates, rings, HA-safe ordering | agent 1.3.0+ | Released |
| Customer path checks on rollouts (DNS, VPN service, internet) | server + probe (tools/opnmgr-probe), opt-in per campaign | Released in 3.81.0; fixture- and local-manager-tested |
| Incidents and maintenance windows | server only | Released |
| Web GUI access restriction, outbound lockdown | agent 1.3.0+ | Released. Queued as a policy the agent applies; see the note below. |
| Health telemetry — gateways, VPN, CARP, services, certificates | agent 1.6.2+ | Released. 1.6.0 reported no gateways and 1.6.1 miscounted services; use 1.6.2. |
| AI configuration review | server only, opt-in | Released, off by default. Secrets are redacted before anything leaves your server and redaction cannot be disabled. |
Firewalls below the health minimum are shown as not reporting rather than as failures. Anything present in this repository but not listed above should be treated as source-only until it appears in CHANGELOG.md.
Platforms. OPNsense, pfSense CE and pfSense Plus can be managed side by side (3.79+). Only OPNsense has been live-validated; pfSense support is implemented and tested against fixtures and stubs, shows as untested per capability, and runs write operations only on firewalls you designate as lab devices. The full matrix, detection rules, agent packaging and enrollment are in docs/PLATFORMS.md. New modules: policy templates, VPN topology, customer reports, integrations.
Validated on OPNsense 26.7 (FreeBSD 14), which is what the maintainer's own fleet
runs. Earlier releases may work — the agent needs only a POSIX shell, fetch and
configctl — but are not tested. Firewalls need outbound HTTPS to the manager; no
inbound port is required.
- The agent package is not in this repository. The release workflow builds it from
plugin/os-opnmanager-agent/and attaches it, signed, to each GitHub release, andscripts/stage_agent_package.phpputs it on your manager (Quick Start step 2). The installer fetches the package from your manager, never from a third party. - Customer checks see only what a probe can reach. The probe tests DNS, a TCP connection and one HTTPS request from wherever you run it. It does not prove an application works end to end. Clean-install enrollment and customer checks are tested against fixtures and a local manager, not yet against a live OPNsense firewall: see CHANGELOG.md for 3.81.0.
- Agent request signing is in every released agent since 1.6.5 (OPNMGR 3.46.0) and
in the pfSense agent: each adopts its api_key/secret and signs every POST, and the
manager verifies HMAC-SHA256. Clean installs start at
agent_auth_mode = prefer_signed(since 3.80.3). On an older installation the only limit is upgrade order — keepcompatibilityuntil every firewall runs a signing agent, then move toprefer_signedonceSELECT hostname, api_key_confirmed FROM firewallsshows1everywhere. - The two firewall lockdown policies have not been exercised against a live
OPNsense firewall by the maintainer of this change. They edit
/conf/config.xml, back it up first, validate the result before installing it, and restore the backup if the filter reload fails — and the generator is tested by running the real scripts against a sample configuration. But the effect on a production firewall is untested. Apply to one firewall you can reach out-of-band before using them across a fleet. - The project itself carries no LTS line or published release cadence. Treat it as actively developed software and read the changelog before upgrading. (Commercial hosting and support are available separately — see Support.)
git pull is usually enough. Since 3.26.0 the two-factor enrolment QR is rendered
on your own server, which added one Composer dependency — run
composer install --no-dev after pulling, or the two-factor setup page will fail to
load.
Each version is tagged from main, so the
latest release matches this tree.
Tagging was intermittent before 3.22 — v3.11.1 was the previous tag, and 3.12 through
3.21 shipped on main and are recorded only in the changelog — so
CHANGELOG.md remains the authoritative history.
| docs/SCREENSHOTS.md | Full screenshot gallery — 28 captures in both themes. |
| CHANGELOG.md | Full release-by-release history. |
| FEATURES.md | Feature reference. |
| docs/UPGRADING.md | Upgrading the server and the agent fleet. |
| SECURITY.md | Security architecture and how to report a vulnerability. |
| docs/walkthrough-script.md | Walkthrough transcript and narration script. |
Agents authenticate with a per-firewall API key and HMAC signing secret. Secrets, SSH
private keys and MFA recovery codes are encrypted at rest with XChaCha20-Poly1305
keyed from .env. Agent updates are Ed25519-signed and verified before installation,
with automatic rollback. Remote operations go through a validated action catalogue;
raw shell is a separate, audited, administrator-only path that is off unless enabled.
Certificate metadata is collected, never private key material.
Since 3.80.1 (GHSA-r7xj-q84q-rpwc):
- Every action checks the caller's role, not only their login. Each page or endpoint
that writes, queues or executes requires its capability from
inc/permissions.php;tests/role_gate_test.phpfails CI when one does not. - A firewall's first check-in is tied to its enrolment token. An unbound firewall can
be claimed only within
agent_claim_window_hours(default 24) of a single-use token being redeemed for it, not by anyone who knows its id. - Secure defaults. Raw shell is off and administrator two-factor is required unless
an installation has stored otherwise; both are on Settings > Security Policy.
Since 3.80.3 a clean install stores these values (
schema.sqlseeds them and records every migration it contains, so the firstmigrate.phpchanges nothing). - No plaintext fallback. Without a usable
OPNMGR_MASTER_KEY(unset, malformed, or no sodium extension) new secrets are refused rather than stored in plaintext, and administrators see a banner naming the cause.scripts/create_admin.phpgenerates the key at install and stops if it is not usable.
Read SECURITY.md before exposing an installation, and report vulnerabilities through the process described there rather than in a public issue.
Issues and pull requests are welcome — there are
templates for bugs, features
and questions. CI lints every PHP and shell file, validates Composer dependencies,
runs the security regression suite, and enforces that VERSION and every version
reference derived from it agree.
- Issues for bugs and questions
- Managed hosting and paid support are available — see mspreboot.com or get in touch
OPNManager itself stays free, MIT-licensed and self-hosted. Nothing in the project requires an engagement, and everything documented here works without one.
OPNManager is one of six free, self-hosted tools published at mspreboot.com/free-projects — alongside Client St0r (IT documentation and asset management), Depl0y, St0r, Rem0te and Net Agit8or. They are free to use and self-hosted, with no per-seat billing and no licence server.
mspreboot.com is the MSP consulting practice of the same author, who ran an MSP for 24 years. If you would rather not run OPNManager yourself, hosting and support for it are offered there, as is consulting on the operation around it. Use of the software never depends on any of that — the project is free and self-hosted either way.
MIT — see LICENSE.
OPNManager is an independent project. It is not affiliated with, endorsed by, or sponsored by Deciso B.V. or the OPNsense project. "OPNsense" is a registered trademark of Deciso B.V.









