feat(config): list, read and revert the firewall's config revisions #48
No files matched your search
@@ -7,6 +7,17 @@ All notable changes to this driver. The format follows
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- The firewall's configuration history (NetOrk/netork#2511): `get_config_revisions()`
|
||||
lists the revisions OPNsense keeps of config.xml, newest first, each with its id, its
|
||||
time in UTC, its description, its user and its size; `get_config_revision(id)`
|
||||
returns one revision's config.xml; `revert_config_revision(id)` makes it the
|
||||
configuration again through `/api/core/backup/revert_backup`, refuses an id that is
|
||||
not in the history (`UnknownConfigRevision`), and raises `ConfigRevertFailed` when the
|
||||
newest revision afterwards does not hold the revision's configuration -- OPNsense
|
||||
answers "reverted" even when it kept the previous file. `config_revision_content()`
|
||||
compares config.xml without the `<revision>` block every save writes. The contract is
|
||||
napalm-device-types 4.38.0's `ConfigRevisionsMixin`. A revert saves config.xml and
|
||||
nothing else: no service is reloaded and the firewall does not reboot.
|
||||
- Time sync (NetOrk/netork#2363): `get_time_sync()` from napalm-device-types 4.35.0's
|
||||
`TimeSyncMixin` reads the time servers (`<system><timeservers>`, in their order) and
|
||||
the zone (`<system><timezone>`, an IANA name; none is the `Etc/UTC` OPNsense runs
|
||||
@@ -19,6 +30,11 @@ All notable changes to this driver. The format follows
|
||||
|
||||
### Changed
|
||||
- Requires napalm-device-types 4.35.0, which declares the time-sync contract.
|
||||
- Requires napalm-device-types 4.38.0, which declares the configuration-history
|
||||
contract.
|
||||
- `load_replace_candidate` is `None` instead of NAPALM's stub that raised, so a caller
|
||||
can tell that the driver replaces no configuration: OPNsense has no API that takes an
|
||||
uploaded config.xml.
|
||||
|
||||
### Fixed
|
||||
- `get_ntp_servers()` lists the configured servers of config.xml, the same list as
|
||||
|
||||
@@ -16,7 +16,7 @@ NAPALM community driver for **OPNsense** firewalls (read-only, via REST API).
|
||||
|---|---|
|
||||
| Python | 3.12 |
|
||||
| NAPALM | 4.0 |
|
||||
| napalm-device-types | 4.35.0 |
|
||||
| napalm-device-types | 4.38.0 |
|
||||
| requests | 2.28 |
|
||||
|
||||
## Installation
|
||||
@@ -85,6 +85,9 @@ arguments.
|
||||
| `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` |
|
||||
@@ -103,6 +106,7 @@ arguments.
|
||||
> ³ 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
|
||||
|
||||
@@ -185,6 +189,52 @@ person where to set them. Which interfaces ntpd serves time on is not touched. I
|
||||
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
|
||||
@@ -247,7 +297,9 @@ d.close()
|
||||
|
||||
### Limitations
|
||||
|
||||
- `load_replace_candidate` is not supported (no XML upload endpoint in the JSON API).
|
||||
- `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
|
||||
|
||||
@@ -0,0 +1,204 @@
|
||||
"""The firewall's own configuration history (NetOrk/netork#2511).
|
||||
|
||||
napalm-device-types' ``ConfigRevisionsMixin`` is the contract: it declares the listing
|
||||
and the reading and runs the revert as a template -- refuse an id that is not in the
|
||||
history, read the revision, revert, check that the newest revision holds it. This
|
||||
module talks to the firewall: the three API calls, and ``config_revision_content``,
|
||||
which leaves out the ``<revision>`` block every save writes into config.xml.
|
||||
|
||||
OPNsense keeps a copy of config.xml for every save, as ``/conf/backup/config-<unix
|
||||
time>.xml`` -- *System → Configuration → History*. It keeps ``<system><backupcount>``
|
||||
of them (100 when unset) and drops the oldest on the next save. The newest is the
|
||||
copy of the configuration in place now.
|
||||
|
||||
No API takes an uploaded config.xml: the backup API (``/api/core/backup/``) lists the
|
||||
history, hands out a revision and reverts to one, but only to a revision that is
|
||||
already on the firewall; a full replace exists only on the legacy page
|
||||
``diag_backup.php``. So the driver has no ``load_replace_candidate``, and an
|
||||
application restores a configuration by reverting to the revision that holds it.
|
||||
|
||||
A revert (``revert_backup``) 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`` and by the API key's user, and
|
||||
the oldest entry may drop out. That is all, and it is done when the request returns:
|
||||
OPNsense reloads no service and does not reboot, so the running firewall keeps the
|
||||
state it had until a subsystem's settings are applied or it restarts. The ``config``
|
||||
system hooks run afterwards (``/usr/local/etc/rc.syshook.d/config``, from syslog);
|
||||
core installs none, a plugin such as git-backup does. The revert starts no HA
|
||||
configuration sync.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import re
|
||||
|
||||
# config.xml as the firewall's own API hands it over; ElementTree resolves no external
|
||||
# entities, and expat limits entity expansion since 2.4.1.
|
||||
import xml.etree.ElementTree as ET # nosec B405
|
||||
from datetime import UTC, datetime
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from napalm_device_types import (
|
||||
ConfigRevertFailed,
|
||||
ConfigRevisionDict,
|
||||
ConfigRevisionsMixin,
|
||||
UnknownConfigRevision,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
#: The history of this firewall, newest first.
|
||||
HISTORY_PATH = "/api/core/backup/backups/this"
|
||||
#: One revision's config.xml; the answer is empty for a name with no file.
|
||||
DOWNLOAD_PATH = "/api/core/backup/download/this/{revision_id}"
|
||||
#: Copy a revision over config.xml and save it.
|
||||
REVERT_PATH = "/api/core/backup/revert_backup/{revision_id}"
|
||||
#: What ``revert_backup`` answers for a revision it has no file for.
|
||||
_NOT_FOUND = "not_found"
|
||||
_REVERTED = "reverted"
|
||||
#: What every save writes into config.xml anew: who saved it, when, from where.
|
||||
_STAMP = "revision"
|
||||
#: A revision's file name in /conf/backup: its unix time, and ``_<ns>`` after a save
|
||||
#: within the same microsecond. Nothing else may reach a request path.
|
||||
_REVISION_ID = re.compile(r"config-([0-9]+(?:\.[0-9]+)?)(?:_[0-9]+)?\.xml")
|
||||
|
||||
|
||||
def _checked_id(revision_id: object) -> str:
|
||||
if not isinstance(revision_id, str) or not _REVISION_ID.fullmatch(revision_id):
|
||||
raise UnknownConfigRevision(revision_id)
|
||||
return revision_id
|
||||
|
||||
|
||||
def _utc(value: Any) -> str | None:
|
||||
try:
|
||||
seconds = float(value)
|
||||
except (TypeError, ValueError):
|
||||
return None
|
||||
return datetime.fromtimestamp(seconds, UTC).isoformat(timespec="seconds")
|
||||
|
||||
|
||||
def _text(value: Any) -> str | None:
|
||||
return value.strip() or None if isinstance(value, str) else None
|
||||
|
||||
|
||||
def _stamp(revision: ConfigRevisionDict) -> float:
|
||||
found = _REVISION_ID.fullmatch(revision["id"])
|
||||
return float(found.group(1)) if found else 0.0
|
||||
|
||||
|
||||
def _revision(item: Any) -> ConfigRevisionDict | None:
|
||||
if not isinstance(item, dict):
|
||||
return None
|
||||
revision_id = item.get("id")
|
||||
if not isinstance(revision_id, str):
|
||||
return None
|
||||
found = _REVISION_ID.fullmatch(revision_id)
|
||||
if found is None:
|
||||
return None
|
||||
size = item.get("filesize")
|
||||
return {
|
||||
"id": revision_id,
|
||||
# The revision's own time; the file name's when it has none.
|
||||
"time": _utc(item.get("time")) or _utc(found.group(1)),
|
||||
"description": _text(item.get("description")),
|
||||
"user": _text(item.get("username")),
|
||||
"size": size if isinstance(size, int) and not isinstance(size, bool) else None,
|
||||
}
|
||||
|
||||
|
||||
def config_revisions(answer: Any) -> list[ConfigRevisionDict]:
|
||||
"""The revisions of a ``backups/this`` *answer*, newest first.
|
||||
|
||||
An entry without a usable id is left out: nothing could read or revert it.
|
||||
|
||||
:raises ValueError: for an answer that is no history, which is not "no revisions".
|
||||
"""
|
||||
items = answer.get("items") if isinstance(answer, dict) else None
|
||||
if not isinstance(items, list):
|
||||
raise ValueError("the firewall answered with no configuration history")
|
||||
revisions = [r for r in map(_revision, items) if r is not None]
|
||||
# By the file name's time, as OPNsense itself orders them.
|
||||
revisions.sort(key=_stamp, reverse=True)
|
||||
return revisions
|
||||
|
||||
|
||||
class OPNsenseConfigRevisionsMixin(ConfigRevisionsMixin):
|
||||
"""List, read and revert to the firewall's configuration revisions; see the module."""
|
||||
|
||||
#: No API takes an uploaded config.xml (NAPALM's base stub would only raise).
|
||||
load_replace_candidate = None
|
||||
|
||||
if TYPE_CHECKING: # pragma: no cover - the driver's REST helpers
|
||||
|
||||
def _get(self, path: str) -> dict[str, Any]: ...
|
||||
|
||||
def _get_text(self, path: str) -> str: ...
|
||||
|
||||
def _post(self, path: str, data: dict[str, Any] | None = None) -> dict[str, Any]: ...
|
||||
|
||||
def get_config_revisions(self) -> list[ConfigRevisionDict]:
|
||||
"""The firewall's configuration history, newest first; the first is in place now.
|
||||
|
||||
:raises Exception: when the history cannot be read, e.g. by a key without the
|
||||
backup privilege.
|
||||
"""
|
||||
return config_revisions(self._get(HISTORY_PATH))
|
||||
|
||||
def get_config_revision(self, revision_id: str) -> str:
|
||||
"""The config.xml of revision *revision_id*, as the firewall keeps it.
|
||||
|
||||
:raises UnknownConfigRevision: for an id that is not in the history.
|
||||
:raises Exception: when the firewall cannot be read.
|
||||
"""
|
||||
checked = _checked_id(revision_id)
|
||||
text = self._get_text(DOWNLOAD_PATH.format(revision_id=checked))
|
||||
if not text.strip():
|
||||
raise UnknownConfigRevision(checked)
|
||||
return text
|
||||
|
||||
def config_revision_content(self, text: str) -> str:
|
||||
"""config.xml without the root's ``<revision>`` block, canonical (XML C14N).
|
||||
|
||||
The indentation between elements does not count; a value's own blanks do.
|
||||
|
||||
:raises xml.etree.ElementTree.ParseError: for a text that is no XML.
|
||||
"""
|
||||
# The firewall's own config.xml: see the import.
|
||||
root = ET.fromstring(text) # nosec B314
|
||||
for stamp in root.findall(_STAMP):
|
||||
root.remove(stamp)
|
||||
for element in root.iter():
|
||||
if element.text is not None and not element.text.strip():
|
||||
element.text = None
|
||||
if element.tail is not None and not element.tail.strip():
|
||||
element.tail = None
|
||||
return ET.canonicalize(ET.tostring(root, encoding="unicode"))
|
||||
|
||||
def _revert_to_config_revision(self, revision_id: str) -> None:
|
||||
"""``revert_backup``: config.xml becomes the revision, saved as the newest one."""
|
||||
checked = _checked_id(revision_id)
|
||||
answer = self._post(REVERT_PATH.format(revision_id=checked))
|
||||
status = answer.get("status") if isinstance(answer, dict) else None
|
||||
if status == _NOT_FOUND:
|
||||
raise UnknownConfigRevision(checked)
|
||||
if status != _REVERTED:
|
||||
reason = answer.get("errorMessage") if isinstance(answer, dict) else None
|
||||
raise ConfigRevertFailed(
|
||||
f"The firewall did not revert to {checked}: {reason or status}"
|
||||
)
|
||||
|
||||
def _get_latest_backup_id(self) -> str | None:
|
||||
"""Return the ID of the most recent server-side config backup, or ``None``.
|
||||
|
||||
Calls ``GET /api/core/backup/backups/this``. The response is sorted
|
||||
newest-first by OPNsense. Returns ``None`` when no backups exist or
|
||||
the request fails.
|
||||
"""
|
||||
try:
|
||||
data = self._get(HISTORY_PATH)
|
||||
items = data.get("items", [])
|
||||
return items[0]["id"] if items else None
|
||||
except Exception as exc:
|
||||
logger.debug("No backup snapshots found: %s", exc)
|
||||
return None
|
||||
@@ -62,6 +62,7 @@ from napalm_device_types.models import (
|
||||
from requests.exceptions import RequestException
|
||||
|
||||
from napalm_opnsense.api_endpoint import ALIVE_TIMEOUT, api_endpoint
|
||||
from napalm_opnsense.config_revisions import OPNsenseConfigRevisionsMixin
|
||||
from napalm_opnsense.ha import config_sync, dhcp_ha
|
||||
from napalm_opnsense.kea_reservations import (
|
||||
lease_held,
|
||||
@@ -99,6 +100,7 @@ def _opnsense_version(versions: Any) -> str:
|
||||
|
||||
|
||||
class OPNsenseDriver(
|
||||
OPNsenseConfigRevisionsMixin,
|
||||
OPNsenseTimeSyncMixin,
|
||||
OPNsenseScheduledJobsMixin,
|
||||
OPNsenseSshSettingsMixin,
|
||||
@@ -1091,21 +1093,6 @@ class OPNsenseDriver(
|
||||
# Internal helpers (config management)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _get_latest_backup_id(self) -> str | None:
|
||||
"""Return the ID of the most recent server-side config backup, or ``None``.
|
||||
|
||||
Calls ``GET /api/core/backup/backups/this``. The response is sorted
|
||||
newest-first by OPNsense. Returns ``None`` when no backups exist or
|
||||
the request fails.
|
||||
"""
|
||||
try:
|
||||
data = self._get("/api/core/backup/backups/this")
|
||||
items = data.get("items", [])
|
||||
return items[0]["id"] if items else None
|
||||
except Exception as exc:
|
||||
logger.debug("No backup snapshots found: %s", exc)
|
||||
return None
|
||||
|
||||
def _fetch_current_routes(self) -> list[dict[str, Any]]:
|
||||
"""Return the current static routes from the OPNsense API.
|
||||
|
||||
|
||||
+1
-1
@@ -23,7 +23,7 @@ classifiers = [
|
||||
]
|
||||
dependencies = [
|
||||
"napalm>=5.1", # older releases import pkg_resources, which a 3.12 venv lacks
|
||||
"napalm-device-types>=4.35.0",
|
||||
"napalm-device-types>=4.38.0",
|
||||
"requests>=2.28.0",
|
||||
]
|
||||
|
||||
|
||||
@@ -55,7 +55,7 @@
|
||||
"napalm_opnsense.resolver_mixin"
|
||||
],
|
||||
"python_file_lines": {
|
||||
"napalm_opnsense/opnsense.py": 3035
|
||||
"napalm_opnsense/opnsense.py": 3022
|
||||
},
|
||||
"untyped_public": [
|
||||
"napalm_opnsense/opnsense.py::OPNsenseDriver.get_snmp_config"
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"time": "1794603885.12",
|
||||
"time_iso": "2026-11-13T22:04:45+01:00",
|
||||
"description": "/api/firewall/filter/apply made changes",
|
||||
"username": "apiuser@192.0.2.10",
|
||||
"filesize": 58213,
|
||||
"id": "config-1794603885.1239.xml"
|
||||
},
|
||||
{
|
||||
"time": "1794603482.87",
|
||||
"time_iso": "2026-11-13T21:58:02+01:00",
|
||||
"description": "/system_general.php made changes",
|
||||
"username": "root@192.0.2.20",
|
||||
"filesize": 58190,
|
||||
"id": "config-1794603482.8721.xml"
|
||||
},
|
||||
{
|
||||
"time": "1794475810.05",
|
||||
"time_iso": "2026-11-12T10:30:10+01:00",
|
||||
"description": "/api/core/backup/revert_backup/config-1793516400.0012.xml made changes",
|
||||
"username": "apiuser@192.0.2.10",
|
||||
"filesize": 57944,
|
||||
"id": "config-1794475810.0548_123456789.xml"
|
||||
},
|
||||
{
|
||||
"time": "1793516400.00",
|
||||
"time_iso": "2026-11-01T08:00:00+01:00",
|
||||
"description": "",
|
||||
"username": "",
|
||||
"filesize": 57944,
|
||||
"id": "config-1793516400.0012.xml"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,415 @@
|
||||
"""The firewall's own configuration history: list it, read a revision, revert to one.
|
||||
|
||||
NetOrk/netork#2511: OPNsense has no API that takes an uploaded config.xml, so an
|
||||
application restores a configuration by finding the revision in the firewall's own
|
||||
history whose content it wants and reverting to that one.
|
||||
|
||||
``core_backup_backups_this.json`` has the shape ``/api/core/backup/backups/this`` answers
|
||||
with on 24.7 up to 26.7 and ``master`` (``OPNsense\\Core\\Api\\BackupController``):
|
||||
newest first, ``time`` the revision's unix time with two decimals, ``time_iso`` the same
|
||||
in the firewall's own zone (here +01:00), ``id`` the file name in ``/conf/backup``. The
|
||||
values are made up; the oldest is a revision without description and user, as the
|
||||
first configuration of a new install is.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import json
|
||||
from pathlib import Path
|
||||
from unittest.mock import MagicMock, patch
|
||||
from xml.etree.ElementTree import ParseError
|
||||
|
||||
import pytest
|
||||
import requests
|
||||
from napalm_device_types import ConfigRevertFailed, ConfigRevisionsMixin, UnknownConfigRevision
|
||||
|
||||
from napalm_opnsense.opnsense import OPNsenseDriver
|
||||
|
||||
FIXTURES = Path(__file__).parent / "fixtures"
|
||||
HISTORY = json.loads((FIXTURES / "core_backup_backups_this.json").read_text())
|
||||
CONFIG_XML = (FIXTURES / "config_xml_sample.xml").read_text()
|
||||
|
||||
HISTORY_PATH = "/api/core/backup/backups/this"
|
||||
NEWEST = "config-1794603885.1239.xml"
|
||||
OLDEST = "config-1793516400.0012.xml"
|
||||
WITH_SUFFIX = "config-1794475810.0548_123456789.xml"
|
||||
#: The id of the revision a revert saves, as the fake firewall names it.
|
||||
REVERTED = "config-1794700000.0001.xml"
|
||||
|
||||
|
||||
def _stamped(config: str, user: str, time: str) -> str:
|
||||
"""*config* with the <revision> block every save writes into config.xml."""
|
||||
block = (
|
||||
f" <revision>\n <username>{user}</username>\n <time>{time}</time>\n"
|
||||
" <description>/api/core/backup/revert_backup made changes</description>\n"
|
||||
" </revision>\n"
|
||||
)
|
||||
return config.replace("</opnsense>", block + "</opnsense>")
|
||||
|
||||
|
||||
#: The oldest revision is the sample; every later one names the host otherwise.
|
||||
FILES = {
|
||||
OLDEST: _stamped(CONFIG_XML, "root@192.0.2.20", "1793516400.00"),
|
||||
WITH_SUFFIX: _stamped(CONFIG_XML, "apiuser@192.0.2.10", "1794475810.05"),
|
||||
"config-1794603482.8721.xml": _stamped(
|
||||
CONFIG_XML.replace("<hostname>OPNsense</hostname>", "<hostname>gw</hostname>"),
|
||||
"root@192.0.2.20",
|
||||
"1794603482.87",
|
||||
),
|
||||
NEWEST: _stamped(
|
||||
CONFIG_XML.replace("<hostname>OPNsense</hostname>", "<hostname>gw1</hostname>"),
|
||||
"apiuser@192.0.2.10",
|
||||
"1794603885.12",
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
class Firewall:
|
||||
"""Answers as the firewall's backup API would; every request is recorded.
|
||||
|
||||
A revert it takes saves the revision as a new newest one, restamped; one it does
|
||||
not take (``takes=False``) still answers "reverted", as OPNsense does when it falls
|
||||
back to the previous file.
|
||||
"""
|
||||
|
||||
def __init__(self, history=HISTORY, files=None, revert_answer=None, takes=True):
|
||||
self.history = copy.deepcopy(history)
|
||||
self.files = dict(FILES if files is None else files)
|
||||
self.revert_answer = revert_answer or {"status": "reverted"}
|
||||
self.takes = takes
|
||||
self.requests: list[tuple[str, str]] = []
|
||||
|
||||
def get(self, url, timeout=None):
|
||||
path = url.removeprefix("https://fw")
|
||||
self.requests.append(("GET", path))
|
||||
response = MagicMock()
|
||||
response.raise_for_status.return_value = None
|
||||
if path == HISTORY_PATH:
|
||||
if isinstance(self.history, Exception):
|
||||
response.raise_for_status.side_effect = self.history
|
||||
response.json.return_value = self.history
|
||||
return response
|
||||
prefix = "/api/core/backup/download/this/"
|
||||
if path.startswith(prefix):
|
||||
# BackupController::downloadAction sends nothing for a name it has no file for.
|
||||
response.text = self.files.get(path.removeprefix(prefix), "")
|
||||
response.json.side_effect = json.JSONDecodeError("Expecting value", "<", 0)
|
||||
return response
|
||||
raise AssertionError(f"unexpected GET {path}")
|
||||
|
||||
def post(self, url, json=None, timeout=None):
|
||||
path = url.removeprefix("https://fw")
|
||||
self.requests.append(("POST", path))
|
||||
response = MagicMock()
|
||||
response.raise_for_status.return_value = None
|
||||
if isinstance(self.revert_answer, Exception):
|
||||
response.raise_for_status.side_effect = self.revert_answer
|
||||
elif self.revert_answer.get("status") == "reverted" and self.takes:
|
||||
self._save(path.rsplit("/", 1)[1])
|
||||
response.json.return_value = self.revert_answer
|
||||
return response
|
||||
|
||||
def _save(self, revision_id):
|
||||
body = self.files[revision_id].split(" <revision>")[0] + "</opnsense>\n"
|
||||
self.files[REVERTED] = _stamped(body, "apiuser@192.0.2.10", "1794700000.00")
|
||||
item = {"time": "1794700000.00", "description": "", "username": "", "id": REVERTED}
|
||||
self.history["items"].insert(0, item)
|
||||
|
||||
@property
|
||||
def posts(self) -> list[str]:
|
||||
return [path for method, path in self.requests if method == "POST"]
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def driver():
|
||||
with patch("napalm_opnsense.opnsense.requests.Session"):
|
||||
drv = OPNsenseDriver(
|
||||
hostname="fw", username="k", password="s", optional_args={"verify": False}
|
||||
)
|
||||
drv.session = MagicMock()
|
||||
yield drv
|
||||
|
||||
|
||||
def _on(driver, firewall: Firewall) -> Firewall:
|
||||
driver.session.get.side_effect = firewall.get
|
||||
driver.session.post.side_effect = firewall.post
|
||||
return firewall
|
||||
|
||||
|
||||
class TestGetConfigRevisions:
|
||||
def test_every_revision_newest_first(self, driver):
|
||||
_on(driver, Firewall())
|
||||
|
||||
revisions = driver.get_config_revisions()
|
||||
|
||||
assert [r["id"] for r in revisions] == [
|
||||
NEWEST,
|
||||
"config-1794603482.8721.xml",
|
||||
WITH_SUFFIX,
|
||||
OLDEST,
|
||||
]
|
||||
|
||||
def test_a_revision_as_the_firewall_describes_it(self, driver):
|
||||
_on(driver, Firewall())
|
||||
|
||||
assert driver.get_config_revisions()[0] == {
|
||||
"id": NEWEST,
|
||||
"time": "2026-11-13T21:04:45+00:00",
|
||||
"description": "/api/firewall/filter/apply made changes",
|
||||
"user": "apiuser@192.0.2.10",
|
||||
"size": 58213,
|
||||
}
|
||||
|
||||
def test_the_time_is_utc_whatever_zone_the_firewall_runs_in(self, driver):
|
||||
# time_iso is in the firewall's zone (+01:00 here); time is unix seconds.
|
||||
_on(driver, Firewall())
|
||||
|
||||
times = [r["time"] for r in driver.get_config_revisions()]
|
||||
|
||||
assert times == [
|
||||
"2026-11-13T21:04:45+00:00",
|
||||
"2026-11-13T20:58:02+00:00",
|
||||
"2026-11-12T09:30:10+00:00",
|
||||
"2026-11-01T07:00:00+00:00",
|
||||
]
|
||||
|
||||
def test_no_description_and_no_user_are_none(self, driver):
|
||||
_on(driver, Firewall())
|
||||
|
||||
oldest = driver.get_config_revisions()[-1]
|
||||
|
||||
assert (oldest["description"], oldest["user"]) == (None, None)
|
||||
|
||||
def test_newest_first_even_when_the_answer_is_not_sorted(self, driver):
|
||||
items = list(reversed(HISTORY["items"]))
|
||||
_on(driver, Firewall(history={"items": items}))
|
||||
|
||||
assert driver.get_config_revisions()[0]["id"] == NEWEST
|
||||
|
||||
def test_without_a_time_the_file_name_tells_it(self, driver):
|
||||
item = {"id": OLDEST, "description": "", "username": "", "filesize": 1}
|
||||
_on(driver, Firewall(history={"items": [item]}))
|
||||
|
||||
assert driver.get_config_revisions()[0]["time"] == "2026-11-01T07:00:00+00:00"
|
||||
|
||||
def test_a_time_and_size_of_another_shape_are_none(self, driver):
|
||||
item = {"id": "config-1.xml", "time": "soon", "filesize": "big", "description": 7}
|
||||
_on(driver, Firewall(history={"items": [item, "noise"]}))
|
||||
|
||||
assert driver.get_config_revisions() == [
|
||||
{
|
||||
"id": "config-1.xml",
|
||||
"time": "1970-01-01T00:00:01+00:00",
|
||||
"description": None,
|
||||
"user": None,
|
||||
"size": None,
|
||||
}
|
||||
]
|
||||
|
||||
def test_an_entry_without_a_usable_id_is_left_out(self, driver):
|
||||
# Nothing could read or revert it: the id goes into the request path.
|
||||
items = [
|
||||
{"id": "../config.xml", "time": "1"},
|
||||
{"id": "config-1/../../x.xml", "time": "1"},
|
||||
{"time": "1"},
|
||||
HISTORY["items"][0],
|
||||
]
|
||||
_on(driver, Firewall(history={"items": items}))
|
||||
|
||||
assert [r["id"] for r in driver.get_config_revisions()] == [NEWEST]
|
||||
|
||||
def test_no_history_is_an_empty_list(self, driver):
|
||||
_on(driver, Firewall(history={"items": []}))
|
||||
|
||||
assert driver.get_config_revisions() == []
|
||||
|
||||
def test_a_failed_read_raises(self, driver):
|
||||
_on(driver, Firewall(history=requests.HTTPError("403 Forbidden")))
|
||||
|
||||
with pytest.raises(requests.HTTPError, match="403"):
|
||||
driver.get_config_revisions()
|
||||
|
||||
@pytest.mark.parametrize("answer", [[], {"items": "x"}, {}], ids=["list", "items", "empty"])
|
||||
def test_an_answer_of_another_shape_raises(self, driver, answer):
|
||||
# "No history" would be a reading; this is none.
|
||||
_on(driver, Firewall(history=answer))
|
||||
|
||||
with pytest.raises(ValueError, match="history"):
|
||||
driver.get_config_revisions()
|
||||
|
||||
def test_a_reading_only_reads(self, driver):
|
||||
firewall = _on(driver, Firewall())
|
||||
|
||||
driver.get_config_revisions()
|
||||
|
||||
assert firewall.requests == [("GET", HISTORY_PATH)]
|
||||
|
||||
|
||||
class TestGetConfigRevision:
|
||||
def test_the_revisions_config_xml(self, driver):
|
||||
firewall = _on(driver, Firewall())
|
||||
|
||||
assert driver.get_config_revision(OLDEST) == FILES[OLDEST]
|
||||
assert firewall.requests == [("GET", f"/api/core/backup/download/this/{OLDEST}")]
|
||||
|
||||
def test_a_revision_the_firewall_has_no_file_for_raises(self, driver):
|
||||
# Rotated out of the history: the download answers with nothing.
|
||||
_on(driver, Firewall(files={}))
|
||||
|
||||
with pytest.raises(UnknownConfigRevision, match=OLDEST):
|
||||
driver.get_config_revision(OLDEST)
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"revision_id",
|
||||
["", "config.xml", "../config.xml", "config-1/../../x.xml", "config-1.xml?x=1", None],
|
||||
)
|
||||
def test_an_id_that_names_no_revision_is_refused_before_any_request(self, driver, revision_id):
|
||||
firewall = _on(driver, Firewall())
|
||||
|
||||
with pytest.raises(UnknownConfigRevision):
|
||||
driver.get_config_revision(revision_id)
|
||||
|
||||
assert firewall.requests == []
|
||||
|
||||
def test_a_failed_read_raises(self, driver):
|
||||
resp = MagicMock()
|
||||
resp.raise_for_status.side_effect = requests.HTTPError("403 Forbidden")
|
||||
driver.session.get.return_value = resp
|
||||
|
||||
with pytest.raises(requests.HTTPError, match="403"):
|
||||
driver.get_config_revision(OLDEST)
|
||||
|
||||
|
||||
class TestRevertConfigRevision:
|
||||
def test_reverts_through_the_backup_api_and_checks_the_result(self, driver):
|
||||
firewall = _on(driver, Firewall())
|
||||
|
||||
now = driver.revert_config_revision(OLDEST)
|
||||
|
||||
assert now["id"] == REVERTED
|
||||
assert firewall.requests == [
|
||||
("GET", HISTORY_PATH),
|
||||
("GET", f"/api/core/backup/download/this/{OLDEST}"),
|
||||
("POST", f"/api/core/backup/revert_backup/{OLDEST}"),
|
||||
("GET", HISTORY_PATH),
|
||||
("GET", f"/api/core/backup/download/this/{REVERTED}"),
|
||||
]
|
||||
|
||||
def test_an_id_with_the_suffix_of_a_fast_save(self, driver):
|
||||
firewall = _on(driver, Firewall())
|
||||
|
||||
driver.revert_config_revision(WITH_SUFFIX)
|
||||
|
||||
assert firewall.posts == [f"/api/core/backup/revert_backup/{WITH_SUFFIX}"]
|
||||
|
||||
def test_a_revert_the_firewall_did_not_take_fails(self, driver):
|
||||
# restoreBackup() falls back to the previous file and the answer is "reverted".
|
||||
_on(driver, Firewall(takes=False))
|
||||
|
||||
with pytest.raises(ConfigRevertFailed, match=OLDEST):
|
||||
driver.revert_config_revision(OLDEST)
|
||||
|
||||
def test_a_revision_not_in_the_history_is_refused(self, driver):
|
||||
firewall = _on(driver, Firewall())
|
||||
|
||||
with pytest.raises(UnknownConfigRevision, match="config-1000000000.5.xml"):
|
||||
driver.revert_config_revision("config-1000000000.5.xml")
|
||||
|
||||
assert firewall.posts == []
|
||||
|
||||
@pytest.mark.parametrize("revision_id", ["", "../config.xml", "config-1.xml/x", None])
|
||||
def test_an_id_that_names_no_revision_never_reaches_a_request_path(self, driver, revision_id):
|
||||
firewall = _on(driver, Firewall())
|
||||
|
||||
with pytest.raises(UnknownConfigRevision):
|
||||
driver.revert_config_revision(revision_id)
|
||||
|
||||
assert firewall.requests == [("GET", HISTORY_PATH)]
|
||||
|
||||
def test_a_history_that_cannot_be_read_reverts_nothing(self, driver):
|
||||
firewall = _on(driver, Firewall(history=requests.HTTPError("403 Forbidden")))
|
||||
|
||||
with pytest.raises(requests.HTTPError):
|
||||
driver.revert_config_revision(OLDEST)
|
||||
|
||||
assert firewall.posts == []
|
||||
|
||||
def test_a_revision_gone_by_the_time_of_the_revert_is_unknown(self, driver):
|
||||
_on(driver, Firewall(revert_answer={"status": "not_found"}))
|
||||
|
||||
with pytest.raises(UnknownConfigRevision, match=OLDEST):
|
||||
driver.revert_config_revision(OLDEST)
|
||||
|
||||
def test_a_key_that_may_not_write_is_refused_with_the_firewalls_reason(self, driver):
|
||||
# user-config-readonly: throwReadOnly() answers with an errorMessage.
|
||||
reason = "User apiuser denied for write access (user-config-readonly set)"
|
||||
_on(driver, Firewall(revert_answer={"errorMessage": reason, "errorTitle": "Error"}))
|
||||
|
||||
with pytest.raises(ConfigRevertFailed, match="user-config-readonly"):
|
||||
driver.revert_config_revision(OLDEST)
|
||||
|
||||
def test_any_other_answer_is_a_failed_revert(self, driver):
|
||||
_on(driver, Firewall(revert_answer={"status": "failed"}))
|
||||
|
||||
with pytest.raises(ConfigRevertFailed, match="failed"):
|
||||
driver.revert_config_revision(OLDEST)
|
||||
|
||||
def test_an_http_error_raises(self, driver):
|
||||
_on(driver, Firewall(revert_answer=requests.HTTPError("500 Server Error")))
|
||||
|
||||
with pytest.raises(requests.HTTPError, match="500"):
|
||||
driver.revert_config_revision(OLDEST)
|
||||
|
||||
|
||||
class TestConfigRevisionContent:
|
||||
def test_the_revision_block_does_not_count(self, driver):
|
||||
# Same configuration, saved by someone else at another time.
|
||||
assert driver.config_revision_content(FILES[OLDEST]) == driver.config_revision_content(
|
||||
FILES[WITH_SUFFIX]
|
||||
)
|
||||
|
||||
def test_a_changed_setting_counts(self, driver):
|
||||
assert driver.config_revision_content(FILES[OLDEST]) != driver.config_revision_content(
|
||||
FILES[NEWEST]
|
||||
)
|
||||
|
||||
def test_a_configuration_without_a_revision_block(self, driver):
|
||||
stamped = driver.config_revision_content(FILES[OLDEST])
|
||||
|
||||
assert driver.config_revision_content(CONFIG_XML) == stamped
|
||||
|
||||
def test_a_revision_element_deeper_down_counts(self, driver):
|
||||
# Only the root's <revision> is the save's stamp.
|
||||
deeper = CONFIG_XML.replace("<theme>", "<theme><revision>7</revision>", 1)
|
||||
|
||||
assert driver.config_revision_content(deeper) != driver.config_revision_content(CONFIG_XML)
|
||||
|
||||
def test_how_the_xml_is_written_does_not_count(self, driver):
|
||||
# Attribute order, quotes and empty elements are no difference of the configuration.
|
||||
a = '<?xml version="1.0"?>\n<opnsense><x a="1" b="2"></x></opnsense>'
|
||||
b = "<opnsense><x b='2' a='1'/></opnsense>"
|
||||
|
||||
assert driver.config_revision_content(a) == driver.config_revision_content(b)
|
||||
|
||||
def test_the_blanks_of_a_value_count(self, driver):
|
||||
padded = CONFIG_XML.replace("<theme>opnsense</theme>", "<theme>opnsense </theme>")
|
||||
|
||||
assert driver.config_revision_content(padded) != driver.config_revision_content(CONFIG_XML)
|
||||
|
||||
def test_text_that_is_no_xml_raises(self, driver):
|
||||
with pytest.raises(ParseError):
|
||||
driver.config_revision_content("<html><body>Login")
|
||||
|
||||
|
||||
class TestWhatTheDriverOffers:
|
||||
def test_it_keeps_the_contract_of_device_types(self):
|
||||
assert issubclass(OPNsenseDriver, ConfigRevisionsMixin)
|
||||
|
||||
def test_it_reads_and_reverts_revisions(self):
|
||||
for name in ("get_config_revisions", "get_config_revision", "revert_config_revision"):
|
||||
assert callable(getattr(OPNsenseDriver, name, None)), name
|
||||
|
||||
def test_it_replaces_no_configuration(self):
|
||||
# No API takes an uploaded config.xml: an application asks for this and gets no.
|
||||
assert getattr(OPNsenseDriver, "load_replace_candidate", None) is None
|
||||
Reference in new issue
Block a user