netOrk aligns every device with one list of time servers and a zone per site (NetOrk/netork#2360) through napalm-device-types 4.35.0's TimeSyncMixin. OPNsense keeps both in config.xml, <system><timeservers> and <system><timezone>, set on the legacy pages services_ntpd.php and system_general.php. No API controller reads or writes them, on 26.7 and on master, so get_time_sync() reads them from the configuration download get_config already uses and asks /api/ntpd/service/status whether ntpd follows a system peer. The driver writes neither value: time_sync_writes is empty and configure_time_sync is None. Restoring an edited config.xml or running the initial setup wizard would rewrite far more than the clock, on a box that is often the gateway and its LAN's time server. TIME_SERVERS_MENU and TIME_ZONE_MENU say where a person sets them, as SSH_SETTINGS_MENU does for the SSH algorithms. get_ntp_servers() now returns the same configured list. It read a "peers" field the status endpoint does not have (it answers with ntpq's associations as "rows") and so never found a server.
12 KiB
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.35.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) |
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-lldpdplugin. Returns empty dict if the plugin is not installed. ² Requires theos-frr(FRR/Quagga) plugin. Returns empty dict if the plugin is not installed or FRR is not running. ³ Overrides the generic per-host loop fromnapalm-device-types. ⁴ See Scheduled jobs. ⁵ See Time sync.
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.
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_candidateis not supported (no XML upload endpoint in the JSON API).- 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 entireconfig.xmlto 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.