From 5a20023c54f708b67806804e762e0a1e873a9dac Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Fri, 13 Nov 2026 22:21:58 +0100 Subject: [PATCH 1/2] feat(config): list, read and revert the firewall's config revisions OPNsense has no API that takes an uploaded config.xml: the backup API lists the history in /conf/backup, hands out a revision and reverts to one that is already on the firewall. A full replace exists only on the legacy page diag_backup.php. So an application restores a configuration by reverting to the revision that holds it (NetOrk/netork#2511). get_config_revisions() lists the history newest first: id, time in UTC (time_iso is in the firewall's zone), description, user and size. get_config_revision(id) returns one revision's config.xml. revert_config_revision(id) calls revert_backup and refuses an id that is not in the history now; an id that is no file name of the history never reaches a request path. A revert only saves config.xml as a new newest revision: no service is reloaded and the firewall does not reboot. load_replace_candidate is None instead of NAPALM's stub that raised, so a capability check sees that the driver replaces nothing. The helper that finds the newest backup for rollback() moves to the new module, which keeps opnsense.py under its recorded size. Refs NetOrk/netork#2511 --- CHANGELOG.md | 10 + README.md | 46 ++- napalm_opnsense/config_revisions.py | 205 ++++++++++++ napalm_opnsense/opnsense.py | 17 +- tests/quality_baseline.json | 2 +- .../fixtures/core_backup_backups_this.json | 36 ++ tests/unit/test_config_revisions.py | 316 ++++++++++++++++++ 7 files changed, 615 insertions(+), 17 deletions(-) create mode 100644 napalm_opnsense/config_revisions.py create mode 100644 tests/unit/fixtures/core_backup_backups_this.json create mode 100644 tests/unit/test_config_revisions.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a8e0c8..8bd8432 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ 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` and refuses an id that + is not in the history (`UnknownConfigRevision`). 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 (``, in their order) and the zone (``, an IANA name; none is the `Etc/UTC` OPNsense runs @@ -19,6 +26,9 @@ All notable changes to this driver. The format follows ### Changed - Requires napalm-device-types 4.35.0, which declares the time-sync 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 diff --git a/README.md b/README.md index 2bfb827..6625e0f 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,9 @@ arguments. | `get_ntp_servers` | ✅ ⁵ | `GET /api/core/backup/download/this`: `` 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/` (XML) | +| `revert_config_revision(revision_id)` | ✅ ⁶ | `POST /api/core/backup/revert_backup/` | | `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,44 @@ 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*), `` 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 + }, +] +``` + +`get_config_revision(revision_id)` returns that revision's config.xml as text. +`revert_config_revision(revision_id)` makes it the configuration again; it refuses an +id that is not in the history now (`UnknownConfigRevision`, a `ValueError`) and raises +`RuntimeError` when the firewall refuses, e.g. for a user with `user-config-readonly`. + +**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/ 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 +289,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 diff --git a/napalm_opnsense/config_revisions.py b/napalm_opnsense/config_revisions.py new file mode 100644 index 0000000..67a7005 --- /dev/null +++ b/napalm_opnsense/config_revisions.py @@ -0,0 +1,205 @@ +"""The firewall's own configuration history (NetOrk/netork#2511). + +OPNsense keeps a copy of config.xml for every save, as ``/conf/backup/config-.xml`` -- *System → Configuration → History*. It keeps ```` +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/ 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 +from datetime import UTC, datetime +from typing import TYPE_CHECKING, Any, TypedDict + +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" +#: A revision's file name in /conf/backup: its unix time, and ``_`` 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") + + +class ConfigRevisionDict(TypedDict): + """One revision of the firewall's configuration (``get_config_revisions``).""" + + id: str # what get_config_revision and revert_config_revision take + time: str | None # when it was saved, UTC ISO 8601; None when the firewall does not say + description: str | None # what made the change, as the firewall records it; None: none + user: str | None # who saved it ("root@192.0.2.20"); None when the firewall names nobody + size: int | None # the file's size in bytes; None when not given + + +class UnknownConfigRevision(ValueError): + """The firewall's configuration history has no revision of that id.""" + + def __init__(self, revision_id: object) -> None: + super().__init__(f"no configuration revision {revision_id!r} in the firewall's history") + + +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: + """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. + + Example:: + + [ + { + "id": "config-1794603885.1239.xml", + "time": "2026-11-13T21:04:45+00:00", + "description": "/api/firewall/filter/apply made changes", + "user": "apiuser@192.0.2.10", + "size": 58213, + }, + ] + + :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 revert_config_revision(self, revision_id: str) -> None: + """Make revision *revision_id* the firewall's configuration (``revert_backup``). + + The revision is saved as config.xml and as the history's new newest entry; + no service is reloaded and the firewall does not reboot (see the module). + + :raises UnknownConfigRevision: for an id that is not in the history now. + :raises RuntimeError: when the firewall refuses the revert, e.g. for a key + that may not change the configuration. + :raises Exception: when the firewall cannot be reached. + """ + checked = _checked_id(revision_id) + if checked not in {r["id"] for r in self.get_config_revisions()}: + raise UnknownConfigRevision(checked) + 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 RuntimeError(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 diff --git a/napalm_opnsense/opnsense.py b/napalm_opnsense/opnsense.py index c061705..fd3a1df 100644 --- a/napalm_opnsense/opnsense.py +++ b/napalm_opnsense/opnsense.py @@ -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. diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index f794000..99918ad 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -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" diff --git a/tests/unit/fixtures/core_backup_backups_this.json b/tests/unit/fixtures/core_backup_backups_this.json new file mode 100644 index 0000000..4c72086 --- /dev/null +++ b/tests/unit/fixtures/core_backup_backups_this.json @@ -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" + } + ] +} diff --git a/tests/unit/test_config_revisions.py b/tests/unit/test_config_revisions.py new file mode 100644 index 0000000..1686b44 --- /dev/null +++ b/tests/unit/test_config_revisions.py @@ -0,0 +1,316 @@ +"""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 json +from pathlib import Path +from unittest.mock import MagicMock, patch + +import pytest +import requests + +from napalm_opnsense.config_revisions import 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" + + +class Firewall: + """Answers as the firewall's backup API would; every request is recorded.""" + + def __init__(self, history=HISTORY, files=None, revert_answer=None): + self.history = history + self.files = files if files is not None else {OLDEST: CONFIG_XML} + self.revert_answer = revert_answer or {"status": "reverted"} + 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 + response.json.return_value = self.revert_answer + return response + + @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) == CONFIG_XML + 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(self, driver): + firewall = _on(driver, Firewall()) + + driver.revert_config_revision(OLDEST) + + assert firewall.requests == [ + ("GET", HISTORY_PATH), + ("POST", f"/api/core/backup/revert_backup/{OLDEST}"), + ] + + 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_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_is_refused_before_any_request(self, driver, revision_id): + firewall = _on(driver, Firewall()) + + with pytest.raises(UnknownConfigRevision): + driver.revert_config_revision(revision_id) + + assert firewall.requests == [] + + 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(RuntimeError, 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(RuntimeError, 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 TestWhatTheDriverOffers: + 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 -- 2.54.0 From a65a3ed6e3904221fc9c2e3f4fec96e65f0b9978 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Fri, 13 Nov 2026 22:33:58 +0100 Subject: [PATCH 2/2] refactor(config): take the revision contract from napalm-device-types 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 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 --- CHANGELOG.md | 10 ++- README.md | 18 ++-- napalm_opnsense/config_revisions.py | 83 ++++++++++--------- pyproject.toml | 2 +- tests/unit/test_config_revisions.py | 123 +++++++++++++++++++++++++--- 5 files changed, 174 insertions(+), 62 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bd8432..4004bb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,8 +11,12 @@ All notable changes to this driver. The format follows 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` and refuses an id that - is not in the history (`UnknownConfigRevision`). A revert saves config.xml and + 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 `` 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 (``, in their order) and @@ -26,6 +30,8 @@ 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. diff --git a/README.md b/README.md index 6625e0f..678a701 100644 --- a/README.md +++ b/README.md @@ -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 @@ -208,10 +208,18 @@ first being the configuration in place now: ] ``` -`get_config_revision(revision_id)` returns that revision's config.xml as text. -`revert_config_revision(revision_id)` makes it the configuration again; it refuses an -id that is not in the history now (`UnknownConfigRevision`, a `ValueError`) and raises -`RuntimeError` when the firewall refuses, e.g. for a user with `user-config-readonly`. +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 `` 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 diff --git a/napalm_opnsense/config_revisions.py b/napalm_opnsense/config_revisions.py index 67a7005..b925344 100644 --- a/napalm_opnsense/config_revisions.py +++ b/napalm_opnsense/config_revisions.py @@ -1,5 +1,11 @@ """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 ```` block every save writes into config.xml. + OPNsense keeps a copy of config.xml for every save, as ``/conf/backup/config-.xml`` -- *System → Configuration → History*. It keeps ```` of them (100 when unset) and drops the oldest on the next save. The newest is the @@ -26,8 +32,19 @@ 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, TypedDict +from typing import TYPE_CHECKING, Any + +from napalm_device_types import ( + ConfigRevertFailed, + ConfigRevisionDict, + ConfigRevisionsMixin, + UnknownConfigRevision, +) logger = logging.getLogger(__name__) @@ -40,28 +57,13 @@ 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 ``_`` 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") -class ConfigRevisionDict(TypedDict): - """One revision of the firewall's configuration (``get_config_revisions``).""" - - id: str # what get_config_revision and revert_config_revision take - time: str | None # when it was saved, UTC ISO 8601; None when the firewall does not say - description: str | None # what made the change, as the firewall records it; None: none - user: str | None # who saved it ("root@192.0.2.20"); None when the firewall names nobody - size: int | None # the file's size in bytes; None when not given - - -class UnknownConfigRevision(ValueError): - """The firewall's configuration history has no revision of that id.""" - - def __init__(self, revision_id: object) -> None: - super().__init__(f"no configuration revision {revision_id!r} in the firewall's history") - - def _checked_id(revision_id: object) -> str: if not isinstance(revision_id, str) or not _REVISION_ID.fullmatch(revision_id): raise UnknownConfigRevision(revision_id) @@ -121,7 +123,7 @@ def config_revisions(answer: Any) -> list[ConfigRevisionDict]: return revisions -class OPNsenseConfigRevisionsMixin: +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). @@ -138,18 +140,6 @@ class OPNsenseConfigRevisionsMixin: def get_config_revisions(self) -> list[ConfigRevisionDict]: """The firewall's configuration history, newest first; the first is in place now. - Example:: - - [ - { - "id": "config-1794603885.1239.xml", - "time": "2026-11-13T21:04:45+00:00", - "description": "/api/firewall/filter/apply made changes", - "user": "apiuser@192.0.2.10", - "size": 58213, - }, - ] - :raises Exception: when the history cannot be read, e.g. by a key without the backup privilege. """ @@ -167,27 +157,36 @@ class OPNsenseConfigRevisionsMixin: raise UnknownConfigRevision(checked) return text - def revert_config_revision(self, revision_id: str) -> None: - """Make revision *revision_id* the firewall's configuration (``revert_backup``). + def config_revision_content(self, text: str) -> str: + """config.xml without the root's ```` block, canonical (XML C14N). - The revision is saved as config.xml and as the history's new newest entry; - no service is reloaded and the firewall does not reboot (see the module). + The indentation between elements does not count; a value's own blanks do. - :raises UnknownConfigRevision: for an id that is not in the history now. - :raises RuntimeError: when the firewall refuses the revert, e.g. for a key - that may not change the configuration. - :raises Exception: when the firewall cannot be reached. + :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) - if checked not in {r["id"] for r in self.get_config_revisions()}: - raise UnknownConfigRevision(checked) 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 RuntimeError(f"The firewall did not revert to {checked}: {reason or status}") + 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``. diff --git a/pyproject.toml b/pyproject.toml index 5e9d87b..f671c45 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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", ] diff --git a/tests/unit/test_config_revisions.py b/tests/unit/test_config_revisions.py index 1686b44..3ae55f2 100644 --- a/tests/unit/test_config_revisions.py +++ b/tests/unit/test_config_revisions.py @@ -14,14 +14,16 @@ 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.config_revisions import UnknownConfigRevision from napalm_opnsense.opnsense import OPNsenseDriver FIXTURES = Path(__file__).parent / "fixtures" @@ -32,15 +34,50 @@ 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 block every save writes into config.xml.""" + block = ( + f" \n {user}\n \n" + " /api/core/backup/revert_backup made changes\n" + " \n" + ) + return config.replace("", block + "") + + +#: 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("OPNsense", "gw"), + "root@192.0.2.20", + "1794603482.87", + ), + NEWEST: _stamped( + CONFIG_XML.replace("OPNsense", "gw1"), + "apiuser@192.0.2.10", + "1794603885.12", + ), +} class Firewall: - """Answers as the firewall's backup API would; every request is recorded.""" + """Answers as the firewall's backup API would; every request is recorded. - def __init__(self, history=HISTORY, files=None, revert_answer=None): - self.history = history - self.files = files if files is not None else {OLDEST: CONFIG_XML} + 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): @@ -68,9 +105,17 @@ class Firewall: 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(" ")[0] + "\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"] @@ -205,7 +250,7 @@ class TestGetConfigRevision: def test_the_revisions_config_xml(self, driver): firewall = _on(driver, Firewall()) - assert driver.get_config_revision(OLDEST) == CONFIG_XML + 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): @@ -237,14 +282,18 @@ class TestGetConfigRevision: class TestRevertConfigRevision: - def test_reverts_through_the_backup_api(self, driver): + def test_reverts_through_the_backup_api_and_checks_the_result(self, driver): firewall = _on(driver, Firewall()) - driver.revert_config_revision(OLDEST) + 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): @@ -254,6 +303,13 @@ class TestRevertConfigRevision: 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()) @@ -263,13 +319,13 @@ class TestRevertConfigRevision: assert firewall.posts == [] @pytest.mark.parametrize("revision_id", ["", "../config.xml", "config-1.xml/x", None]) - def test_an_id_that_names_no_revision_is_refused_before_any_request(self, driver, revision_id): + 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 == [] + 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"))) @@ -290,13 +346,13 @@ class TestRevertConfigRevision: reason = "User apiuser denied for write access (user-config-readonly set)" _on(driver, Firewall(revert_answer={"errorMessage": reason, "errorTitle": "Error"})) - with pytest.raises(RuntimeError, match="user-config-readonly"): + 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(RuntimeError, match="failed"): + with pytest.raises(ConfigRevertFailed, match="failed"): driver.revert_config_revision(OLDEST) def test_an_http_error_raises(self, driver): @@ -306,7 +362,50 @@ class TestRevertConfigRevision: 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 is the save's stamp. + deeper = CONFIG_XML.replace("", "7", 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 = '\n' + b = "" + + 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("opnsense", "opnsense ") + + 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("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 -- 2.54.0