driver / standard (pull_request) Successful in 17s
driver / lint (pull_request) Successful in 15s
driver / types (pull_request) Successful in 1m0s
driver / test (3.12) (pull_request) Successful in 1m11s
driver / test (3.13) (pull_request) Successful in 1m3s
driver / lowest (pull_request) Successful in 35s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 1m1s
CI / driver (pull_request) Successful in 2m44s
driver / publish (pull_request) Skipped
napalm-device-types 4.38.0 declares ConfigRevisionsMixin: the listing, the reading, ConfigRevisionDict and the exceptions, and the revert as a template. The driver keeps the device communication: the three backup API calls, the revert step, and config_revision_content(), which leaves out the <revision> block every save writes into config.xml and the indentation between elements. The template reads the newest revision after the revert and checks that it holds the revision's configuration. OPNsense answers "reverted" even when restoreBackup() could not load the file and kept the previous one; that now raises ConfigRevertFailed instead of passing. A refusal of the firewall raises ConfigRevertFailed too. An id the history does not list still never reaches a request path. Refs NetOrk/netork#2511
339 lines
15 KiB
Markdown
339 lines
15 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
pip install napalm-opnsense
|
||
```
|
||
|
||
Or from source:
|
||
|
||
```bash
|
||
git clone https://git.netork.io/NAPALM/napalm-opnsense
|
||
cd napalm-opnsense
|
||
pip install -e .
|
||
```
|
||
|
||
## Quick start
|
||
|
||
```python
|
||
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`:
|
||
|
||
```python
|
||
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](#scheduled-jobs).
|
||
> ⁵ See [Time sync](#time-sync).
|
||
> ⁶ See [Configuration history](#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:
|
||
|
||
```python
|
||
[
|
||
{
|
||
"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.
|
||
|
||
```json
|
||
[
|
||
{
|
||
"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
|
||
|
||
```python
|
||
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](#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](https://git.netork.io/NAPALM/driver-standard/src/branch/main/STANDARDS.md).
|
||
|
||
```bash
|
||
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
|
||
.venv/bin/pytest --cov
|
||
```
|
||
|
||
## CI
|
||
|
||
[.gitea/workflows/ci.yml](.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](LICENSE).
|
||
|