christianmanivong 6c1aaf1690
driver / standard (push) Failing after 15s
driver / lint (push) Successful in 14s
driver / types (push) Successful in 56s
driver / test (3.12) (push) Successful in 1m3s
driver / test (3.13) (push) Successful in 55s
driver / lowest (push) Successful in 34s
driver / build (push) Successful in 30s
driver / security (push) Successful in 1m30s
CI / driver (push) Failing after 3m2s
driver / publish (push) Skipped
Merge pull request 'fix(radius): the getters raise when the firewall does not answer (#49)' (#50) from fix/radius-read-errors into main
2026-11-15 19:24:02 +00:00
2026-05-29 09:22:10 +02:00
2026-05-29 09:22:10 +02:00

napalm-opnsense

NAPALM community driver for OPNsense firewalls (read-only, via REST API).

Tested devices

Model OPNsense Version Tested
OPNsense (virtual/bare metal) 24.7 ✅

Additional OPNsense versions should work — contributions welcome.

Requirements

Dependency Minimum version
Python 3.12
NAPALM 4.0
napalm-device-types 4.38.0
requests 2.28

Installation

pip install napalm-opnsense

Or from source:

git clone https://git.netork.io/NAPALM/napalm-opnsense
cd napalm-opnsense
pip install -e .

Quick start

from napalm import get_network_driver

driver = get_network_driver("opnsense")
with driver(
    "192.168.1.1",
    "my_api_key",
    "my_api_secret",
    optional_args={"verify": False},
) as device:
    facts = device.get_facts()
    print(facts)

Authentication

OPNsense uses API key/secret pairs instead of username/password. Generate a key pair in the OPNsense GUI under System → Access → Users → edit user → API keys.

Pass the credentials via optional_args:

optional_args = {
    "api_key": "your-api-key",
    "api_secret": "your-api-secret",
    "verify": False,  # set to a CA bundle path or True in production
}

Alternatively, pass the key/secret as the positional username/password arguments.

Implemented getters

Getter Status OPNsense API Endpoint
get_facts ✅ GET /api/diagnostics/system/system_information (name, version) + GET /api/core/system/status (fallback on older versions)
get_interfaces ✅ GET /api/interfaces/overview/export
get_interfaces_ip ✅ GET /api/interfaces/overview/export; a CARP address only on the node that is MASTER for it
get_interfaces_counters ✅ GET /api/diagnostics/interface/get_interface_statistics
get_arp_table ✅ GET /api/diagnostics/interface/get_arp
get_ipv6_neighbors_table ✅ GET /api/diagnostics/interface/get_ndp
get_route_to ✅ GET /api/diagnostics/interface/get_routes
get_environment ✅ GET /api/diagnostics/system/system_resources + system_temperature
get_lldp_neighbors ✅ ¹ GET /api/lldpd/service/neighbor
get_lldp_neighbors_detail ✅ ¹ GET /api/lldpd/service/neighbor
get_ntp_servers ✅ ⁵ GET /api/core/backup/download/this: <system><timeservers> of config.xml
get_time_sync ✅ ⁵ GET /api/core/backup/download/this (servers, zone) + GET /api/ntpd/service/status (system peer)
get_config ✅ GET /api/core/backup/download/this (XML)
get_config_revisions() ✅ ⁶ GET /api/core/backup/backups/this
get_config_revision(revision_id) ✅ ⁶ GET /api/core/backup/download/this/<id> (XML)
revert_config_revision(revision_id) ✅ ⁶ POST /api/core/backup/revert_backup/<id>
is_alive ✅ TCP socket check
get_bgp_neighbors ✅ ² GET /api/quagga/bgp/get + GET /api/quagga/diagnostics/bgpneighbors
get_vlans ✅ GET /api/interfaces/vlan_settings/search_item
get_mac_address_table ❌ Not applicable (firewall, no L2 switching)
ping ✅ POST /api/diagnostics/ping/set + start + search_jobs + stop/remove
get_listening_sockets ✅ GET /api/diagnostics/interface/get_socket_statistics + /api/core/service/search + /api/wireguard/service/show (WireGuard's kernel sockets by listen port)
get_virtual_ips ✅ GET /api/interfaces/overview/export: every address bound to a CARP VHID (CARP address and IP aliases on it), with this node's CARP state. interfaces/vip_settings is not read: it carries the CARP passwords
ping_sweep ✅ ³ same endpoints, one batch of parallel jobs at a time
get_scheduled_jobs() ✅ ⁴ GET /api/cron/settings/get: every cron job of config.xml
manage_scheduled_job(key, action, digest=) ✅ ⁴ enable, disable: POST /api/cron/settings/toggle_job/<uuid>/1 (or /0) + /api/cron/service/reconfigure; run now is refused
put_scheduled_job(spec) / delete_scheduled_job(key, digest=) ✅ ⁴ an application's own job: add_job, set_job/<uuid>, del_job/<uuid> + reconfigure
get_scheduled_job_commands() ✅ ⁴ GET /api/cron/settings/get_job: the configd actions a job can run

¹ Requires the os-lldpd plugin. Returns empty dict if the plugin is not installed. ² Requires the os-frr (FRR/Quagga) plugin. Returns empty dict if the plugin is not installed or FRR is not running. ³ Overrides the generic per-host loop from napalm-device-types. ⁴ See Scheduled jobs. ⁵ See Time sync. ⁶ See Configuration history.

Ping

OPNsense has no synchronous ping endpoint: /api/diagnostics/ping is a job API — create, start, read statistics, stop, remove. A single ping therefore costs five requests and about a second of waiting, which makes the generic sequential sweep from napalm-device-types unusable for a whole subnet.

ping_sweep exploits what the job API does offer instead: jobs are independent and run on the firewall in parallel, and search_jobs reports all of them in one response. It creates and starts a batch (PING_SWEEP_BATCH_SIZE, default 32), waits once, reads every result with a single request, then cleans the batch up — waiting time per batch is constant rather than linear in hosts. PING_SWEEP_MAX_TARGETS (default 512) bounds the sweep as a whole; both are deliberately conservative, since this runs on production firewalls.

Results are polled rather than read once: search_jobs signals the running ping with SIGINFO and parses whatever it has written so far, so the statistics line lands in the log slightly after the request that triggered it.

ttl and vrf are accepted for NAPALM compatibility and ignored — the API has no equivalent.

Scheduled jobs

OPNsense keeps its cron jobs in config.xml (System → Settings → Cron), and each runs a configd action, not a shell line. key is opnsense:<uuid>, kind cron, source config.xml, run_as root. A job another component registered (its origin is not cron, such as the intrusion detection's rule update) is platform; one whose description starts with napalm-scheduled-job: <name> was written by put_scheduled_job and is the only kind that can be edited or deleted; every other job is admin. Every job can be enabled and disabled.

put_scheduled_job takes a configd action as command, with its parameters as the words after it: the actions are what get_scheduled_job_commands() lists, anything else is refused (ScheduledJobRefused), and so is @reboot and a parameter with blanks, quotes or backslashes, which OPNsense releases before and after 26.7 would split differently. The schedule is written as its five fields, month and weekday names as numbers.

Not covered: the API cannot run a configd action now, so no job takes run; what OPNsense writes into the crontab beyond config.xml (periodic, the plugins' system jobs) cannot be read over the API; the time zone is not read (None).

SSH server settings

OPNsense writes sshd_config from config.xml (<system><ssh>: kex, ciphers, macs, keys, keysig), set on the legacy page System → Settings → Administration → Secure Shell (system_advanced_admin.php). No API controller reads or writes that section, up to OPNsense 26.7 and on master, so the driver does not offer harden_ssh_server. It says, as data, where a person sets the algorithm lists instead: SSH_SETTINGS_MENU is the page's menu path and SSH_SETTINGS_FIELDS names each list's field by its algorithm class (napalm-device-types' SSH_ALGORITHM_CLASSES). A field left empty means OpenSSH's defaults. In an HA pair the configuration sync carries the section to the backup when its "OpenSSH" item (ssh) is ticked.

Time sync

OPNsense keeps the time servers and the zone in config.xml: <system><timeservers>, space-separated in the order of Services → Network Time → General (services_ntpd.php), and <system><timezone>, an IANA name set on System → Settings → General (system_general.php). get_time_sync() reads both from the configuration download get_config uses, and get_ntp_servers() returns the same servers. An empty or missing zone reads as Etc/UTC, the zone OPNsense runs in then. synchronized is whether /api/ntpd/service/status (ntpq -pnw as rows) has a system peer (*): False without servers, since OPNsense does not run ntpd then, and None when the status cannot be read. daemon is ntpd. The API key needs the privilege to download the configuration, as for get_config.

Both pages are legacy PHP, and no API controller reads or writes either value, up to OPNsense 26.7 and on master; the initial setup wizard writes the zone only together with the hostname, the interfaces and the root password. So the driver writes neither: time_sync_writes is empty and configure_time_sync is None. TIME_SERVERS_MENU and TIME_ZONE_MENU are the pages' menu paths, for telling a person where to set them. Which interfaces ntpd serves time on is not touched. In an HA pair the configuration sync carries the servers to the backup when its "Network Time" item (ntpd) is ticked; the zone is not synchronised.

Configuration history

OPNsense keeps a copy of config.xml for every save in /conf/backup (System → Configuration → History), <system><backupcount> of them (100 when unset); the next save drops the oldest. get_config_revisions() lists them newest first, the first being the configuration in place now:

[
    {
        "id": "config-1794603885.1239.xml",  # what the two methods below take
        "time": "2026-11-13T21:04:45+00:00",  # UTC, whatever zone the firewall runs in
        "description": "/api/firewall/filter/apply made changes",  # None when empty
        "user": "apiuser@192.0.2.10",  # None when empty
        "size": 58213,  # bytes
    },
]

The contract is napalm-device-types' ConfigRevisionsMixin; this driver does the API calls. get_config_revision(revision_id) returns that revision's config.xml as text. revert_config_revision(revision_id) makes it the configuration again and returns the revision in place afterwards. It refuses an id that is not in the history now (UnknownConfigRevision, a ValueError) before anything changes, reads the revision, calls revert_backup, and then checks that the newest revision holds the revision's configuration: OPNsense answers reverted even when it could not load the file and kept the previous one. A refusal of the firewall (for a user with user-config-readonly) or a failed check raises ConfigRevertFailed, a RuntimeError. That is five requests. config_revision_content(text) is config.xml without the <revision> block every save writes (who, when, from where), in canonical XML, with the indentation between elements left out: two revisions with the same configuration compare equal through it.

What a revert does. OPNsense copies the revision over config.xml and saves it. The history gets a new newest entry with the revision's content, described as /api/core/backup/revert_backup/<id> made changes by the API key's user, and the oldest entry may drop out. That is all, and it is done when the request returns: no service is reloaded and the firewall does not reboot, so it keeps running with the settings it had until a subsystem's settings are applied or it restarts. The config system hooks run afterwards; core installs none, a plugin such as git-backup does. The revert starts no HA configuration sync.

There is no API that takes an uploaded config.xml (the full restore exists only on the legacy page diag_backup.php, behind a GUI login), so the driver offers no load_replace_candidate: it is None. A configuration that is no longer in the history cannot be put back through the API. The API key needs the backup privilege.

Config management

OPNsense does not expose a single generic "push config" endpoint. Config is managed per-module via separate API controllers. This driver implements config management for static routes via /api/routes/routes/.

Why routes? Routes are the most common network-automation target on a firewall, and the OPNsense routes API provides full CRUD operations.

Supported methods

Method OPNsense API
load_merge_candidate(config=...) stages routes in memory
compare_config() diffs against GET /api/routes/routes/searchroute
commit_config() snapshots backup → POST /api/routes/routes/addroute × n → reconfigure
discard_config() clears staged candidate
rollback() POST /api/core/backup/revert_backup/{id} — restores the config.xml snapshot taken before the last commit

Config format

The load_merge_candidate config parameter must be a JSON array of route objects, each with network and gateway keys. gateway must be the name of an existing OPNsense gateway (as configured under System → Gateways → Configuration), not an IP address.

[
  {
    "network": "10.0.0.0/8",
    "gateway": "WAN_GW",
    "descr": "Corporate internal",
    "disabled": "0"
  },
  {
    "network": "0.0.0.0/0",
    "gateway": "WAN_GW",
    "descr": "Default route"
  }
]

Example

import json

driver = get_network_driver("opnsense")
d = driver("192.168.1.1", "user", "pass", optional_args={"api_key": "k", "api_secret": "s"})
d.open()

routes = json.dumps([{"network": "10.0.0.0/8", "gateway": "WAN_GW"}])
d.load_merge_candidate(config=routes)

print(d.compare_config())  # unified diff
d.commit_config()  # applies routes and calls reconfigure
d.rollback()  # removes the routes just added
d.close()

Limitations

  • load_replace_candidate is None (no XML upload endpoint in the JSON API); a revision of the firewall's own history can be reverted to instead, see Configuration history.
  • Non-route config (firewall rules, DHCP, DNS, interfaces, …) must be managed via OPNsense module-specific controllers — outside the scope of this driver.
  • rollback() reverts the entire config.xml to the pre-commit state (not just the routes). OPNsense's backup API has no partial-restore capability.
  • Rollback uses the backup snapshot taken at commit_config() time. If no commit was made in the current session, the most recent available backup is used as a fallback.

Optional arguments

Argument Default Description
api_key username OPNsense API key
api_secret password OPNsense API secret
base_url https://<hostname> Override the base URL
verify True TLS certificate verification (path or bool)

Development

The rules are in STANDARDS.md.

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest --cov

CI

.gitea/workflows/ci.yml calls the shared workflow of the driver standard: ruff, mypy, the tests on Python 3.12 and 3.13 and at the lowest declared versions, bandit, pip-audit and a build check. A release tag publishes to PyPI.

License

Apache 2.0 — see LICENSE.

S
Description
No description provided
Readme
2.2 MiB
0 Stars 1 Watchers 0 Forks
2026-11-07 19:11:02 +00:00
Languages
Python 100%