Skip to content
agit8or1Public

About

Self-hosted OPNsense fleet management for MSPs and IT teams. Monitor firewall and connectivity health, review configuration backups and drift, and roll out updates through canary/pilot/production rings — with firewalls grouped by customer and site.

Topics

Resources

Security policy

Stars

31 stars

Watchers

1 watching

Forks

Latest commit

 

History

287 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

OPNManager

Self-hosted OPNsense fleet management for MSPs and IT teams.

CI License: MIT v3.81.3

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.

Fleet dashboard showing eleven managed firewalls across five customers, with roll-up tiles for offline devices, pending updates, gateways down, configuration drift and expiring certificates above a per-firewall health table

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.


What it helps you do

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.


Watch the walkthrough

Play the OPNManager walkthrough — fleet dashboard, incident triage, configuration diff, ringed update rollout and the customer and site model, in both light and dark themes

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.


See it in action

Know exactly what changed, and when

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.

Configuration diff in dark theme showing two firewall rules added since the baseline, each labelled "added" with the rule description, interface and type

Diagnose one firewall without leaving the page

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.

Per-firewall health in light theme showing a gateway flagged high latency at 148.70 ms with 2.40% loss, a WireGuard tunnel, six services with one stopped, and a certificate expiring in six days

Roll updates out without taking a customer down

Canary, then pilot, then production, with manual progression — and never both members of a CARP pair at once.

Fleet updates in dark theme with a running OPNsense 26.7.3 campaign showing canary completed cleanly, pilot in progress and production holding, above a fleet table with each firewall's ring, versions and HA partner

Work one list instead of an inbox

An incident opens when a condition becomes true and closes when it actually clears. Acknowledging stops the notifications without closing it.

Incident list in light theme with two critical and four warning incidents showing severity, affected firewall, customer, how long each has been open and acknowledge controls

See the trend, not just the current value

Per-firewall WAN throughput, CPU load, memory and disk, collected on each agent check-in.

Firewall statistics in dark theme showing four populated twenty-four-hour charts: WAN traffic, CPU load average, memory usage and disk usage, each with average, peak and low figures

Ask what is actually exposed

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.

AI security report in dark theme for a demo firewall graded D at 62 out of 100, risk level high, with an executive summary and a critical finding that the web GUI is reachable from any internet source, each finding carrying its recommendation and the rules it was found in

A firewall whose administration is already restricted scores accordingly, and the findings that remain are named as preferences rather than problems.

AI security report in light theme for a demo firewall graded A at 94 out of 100, risk level low, with two low-severity hardening notes and one informational finding confirming SSH is restricted to management addresses

Organised the way you actually support them

Customers group sites, sites group firewalls, each with a code, timezone, contacts and a default maintenance window.

Customer management in light theme listing five customer organisations with code, contact, timezone, default maintenance window, their sites and firewall counts

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.


Quick Start

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+.

1. Server

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 apache2

2. Agent package

Stage 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.

3. First firewall

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> sh

The 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.


Compatibility and feature availability

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.

Known limitations

  • 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, and scripts/stage_agent_package.php puts 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 — keep compatibility until every firewall runs a signing agent, then move to prefer_signed once SELECT hostname, api_key_confirmed FROM firewalls shows 1 everywhere.
  • 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.)

Upgrading

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.

Releases

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.


Documentation

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.

Security

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.php fails 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.sql seeds them and records every migration it contains, so the first migrate.php changes 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.php generates 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.

Contributing

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.

Support

OPNManager itself stays free, MIT-licensed and self-hosted. Nothing in the project requires an engagement, and everything documented here works without one.


More tools from MSPReboot

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.

License

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.

About

Self-hosted OPNsense fleet management for MSPs and IT teams. Monitor firewall and connectivity health, review configuration backups and drift, and roll out updates through canary/pilot/production rings — with firewalls grouped by customer and site.

Topics

Resources

Security policy

Stars

31 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages