feat(config): list, read and revert the firewall's config revisions #48

Merged
christianmanivong merged 2 commits from feat/config-revisions into main 2026-11-13 22:10:02 +00:00
8 changed files with 729 additions and 19 deletions

No files matched your search

+16
View File
@@ -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
+54 -2
View File
@@ -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
+204
View File
@@ -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
+2 -15
View File
@@ -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
View File
@@ -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",
]
+1 -1
View File
@@ -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"
}
]
}
+415
View File
@@ -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