From 4e377923db9fb2946362a65b62bfbe242c02d1fb Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 21:42:56 +0100 Subject: [PATCH 1/3] fix(connection): probe the API port from base_url in is_alive is_alive always opened port 443 on the hostname, so a firewall whose API is reached through base_url on another port (https://fw:8443) read as dead. The probe now takes host and port from base_url, falling back to the scheme's default port. Closes #15 --- CHANGELOG.md | 3 +++ napalm_opnsense/api_endpoint.py | 20 ++++++++++++++++++++ napalm_opnsense/opnsense.py | 6 +++--- tests/unit/test_driver.py | 24 ++++++++++++++++++++++++ 4 files changed, 50 insertions(+), 3 deletions(-) create mode 100644 napalm_opnsense/api_endpoint.py diff --git a/CHANGELOG.md b/CHANGELOG.md index aaa2e1f..0ffc10a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ All notable changes to this driver. The format follows 3.12 venv no longer has. ### Fixed +- `is_alive()` checks the host and port named in `base_url` (`https://fw:8443`) instead + of always port 443 on the hostname, so a firewall whose API listens elsewhere no + longer reads as dead (#15). - `configure_snmp_agent()` works on OPNsense 26.x again. The configure step sent fields the os-net-snmp model does not have (`contact`, `location`, `sysobjid`, `bindip`) and `listen` in the shape `get` returns rather than as a string, which diff --git a/napalm_opnsense/api_endpoint.py b/napalm_opnsense/api_endpoint.py new file mode 100644 index 0000000..1904a9a --- /dev/null +++ b/napalm_opnsense/api_endpoint.py @@ -0,0 +1,20 @@ +"""Where the OPNsense REST API listens, read from the driver's ``base_url``.""" + +from __future__ import annotations + +from urllib.parse import urlsplit + +#: The port the API listens on when ``base_url`` names none, per scheme. +DEFAULT_PORTS = {"https": 443, "http": 80} +#: Seconds the driver's reachability probe waits for the API port to accept. +ALIVE_TIMEOUT = 5 + + +def api_endpoint(base_url: str, fallback_host: str) -> tuple[str, int]: + """``https://fw:8443`` -> ``("fw", 8443)``: the host and port of the REST API. + + Without a port the scheme's default applies; without a host, *fallback_host*. + """ + parts = urlsplit(base_url) + port = parts.port or DEFAULT_PORTS.get(parts.scheme.lower(), DEFAULT_PORTS["https"]) + return parts.hostname or fallback_host, port diff --git a/napalm_opnsense/opnsense.py b/napalm_opnsense/opnsense.py index 0ee1c94..6efb55d 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.ha import config_sync, dhcp_ha from napalm_opnsense.listening import parse_socket_statistics, wireguard_listen_ports from napalm_opnsense.ospf_mixin import OPNsenseOspfMixin @@ -190,9 +191,8 @@ class OPNsenseDriver( if self.session is None: return {"is_alive": False} try: - host = self.hostname - port = 443 - with socket.create_connection((host, port), timeout=5): + endpoint = api_endpoint(self.base_url, self.hostname) + with socket.create_connection(endpoint, timeout=ALIVE_TIMEOUT): pass return {"is_alive": True} except OSError: diff --git a/tests/unit/test_driver.py b/tests/unit/test_driver.py index 3bc782d..c6550f8 100644 --- a/tests/unit/test_driver.py +++ b/tests/unit/test_driver.py @@ -164,6 +164,30 @@ class TestIsAlive: result = driver.is_alive() assert result == {"is_alive": False} + @pytest.mark.parametrize( + ("base_url", "expected"), + [ + (None, ("opnsense.example.com", 443)), + ("https://fw.example.com:8443", ("fw.example.com", 8443)), + ("https://fw.example.com:8443/", ("fw.example.com", 8443)), + ("https://fw.example.com", ("fw.example.com", 443)), + ("http://fw.example.com", ("fw.example.com", 80)), + ("https://[2001:db8::1]:4443", ("2001:db8::1", 4443)), + ], + ) + def test_probes_the_host_and_port_of_base_url(self, base_url, expected): + """#15: an API on another port than 443 must not read as dead.""" + args = {"verify": False} + if base_url is not None: + args["base_url"] = base_url + drv = OPNsenseDriver("opnsense.example.com", "u", "p", optional_args=args) + drv.session = MagicMock() + with patch("napalm_opnsense.opnsense.socket.create_connection") as mock_conn: + mock_conn.return_value.__enter__ = MagicMock(return_value=None) + mock_conn.return_value.__exit__ = MagicMock(return_value=False) + assert drv.is_alive() == {"is_alive": True} + assert mock_conn.call_args.args[0] == expected + # --------------------------------------------------------------------------- # _get() -- 2.54.1 From 4fc7b2424e0a359a022c23c58ff26b9399ef1210 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 21:45:12 +0100 Subject: [PATCH 2/3] fix(dns): raise when the host overrides cannot be read The Unbound and Dnsmasq override reads logged any error and returned an empty list. sync_dns_zone took that for "no overrides": it deleted nothing and added every record again, so a transient API error left each record twice on the firewall. The reads now raise, which stops the sync before it writes and lets get_dns_entries callers tell a failed read from an empty one. Closes #14 --- CHANGELOG.md | 3 + napalm_opnsense/opnsense.py | 134 +++++++++++++++++------------------- tests/quality_baseline.json | 5 +- tests/unit/test_driver.py | 38 ++++++++++ 4 files changed, 107 insertions(+), 73 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ffc10a..53a1ec6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,9 @@ All notable changes to this driver. The format follows - `is_alive()` checks the host and port named in `base_url` (`https://fw:8443`) instead of always port 443 on the hostname, so a firewall whose API listens elsewhere no longer reads as dead (#15). +- `sync_dns_zone()` and `get_dns_entries()` raise when the host overrides cannot be + read. A transient API error used to read as "no overrides": the sync then deleted + nothing and added every record a second time (#14). - `configure_snmp_agent()` works on OPNsense 26.x again. The configure step sent fields the os-net-snmp model does not have (`contact`, `location`, `sysobjid`, `bindip`) and `listen` in the shape `get` returns rather than as a string, which diff --git a/napalm_opnsense/opnsense.py b/napalm_opnsense/opnsense.py index 6efb55d..5b312fa 100644 --- a/napalm_opnsense/opnsense.py +++ b/napalm_opnsense/opnsense.py @@ -2823,7 +2823,7 @@ class OPNsenseDriver( Checks whether Unbound (DNS Resolver) or Dnsmasq (DNS Forwarder) is running and returns host overrides from whichever is active. If neither - is running, returns an empty list. + is running, returns an empty list. A failed read of the overrides raises. Each entry:: @@ -2849,81 +2849,75 @@ class OPNsenseDriver( def _get_unbound_host_overrides(self) -> list[dict[str, Any]]: result: list[dict[str, Any]] = [] seen: set[tuple[str, str, str, str]] = set() - try: - data = self._post( - "/api/unbound/settings/searchhostoverride", - {"current": 1, "rowCount": -1, "searchPhrase": ""}, - ) - rows = data.get("rows", []) or [] - # searchhostoverride lists alias records alongside the host override - # they hang off, each under its own UUID. OPNsense flags them, so - # skip them by that flag and report every remaining row as it is — - # including two rows that happen to hold the same name and address. - # Those are duplicates on the device, and sync_dns_zone can only - # clear the copies it is told about. - flagged = any("isAlias" in row for row in rows) - for row in rows: - if flagged and row.get("isAlias"): + data = self._post( + "/api/unbound/settings/searchhostoverride", + {"current": 1, "rowCount": -1, "searchPhrase": ""}, + ) + rows = data.get("rows", []) or [] + # searchhostoverride lists alias records alongside the host override + # they hang off, each under its own UUID. OPNsense flags them, so + # skip them by that flag and report every remaining row as it is — + # including two rows that happen to hold the same name and address. + # Those are duplicates on the device, and sync_dns_zone can only + # clear the copies it is told about. + flagged = any("isAlias" in row for row in rows) + for row in rows: + if flagged and row.get("isAlias"): + continue + host = row.get("hostname", "") or "" + domain = row.get("domain", "") or "" + fqdn = f"{host}.{domain}" if host and domain else host or domain + ip = row.get("server", "") or "" + rr = row.get("rr", "A") or "A" + if not flagged: + # Releases without the flag give nothing to tell an alias + # apart from a copy, so collapsing by content stays the + # safer read there. + key = (host.lower(), domain.lower(), ip, rr) + if key in seen: continue - host = row.get("hostname", "") or "" - domain = row.get("domain", "") or "" - fqdn = f"{host}.{domain}" if host and domain else host or domain - ip = row.get("server", "") or "" - rr = row.get("rr", "A") or "A" - if not flagged: - # Releases without the flag give nothing to tell an alias - # apart from a copy, so collapsing by content stays the - # safer read there. - key = (host.lower(), domain.lower(), ip, rr) - if key in seen: - continue - seen.add(key) - # The auto-PTR flag is "addptr" since 25.x, "ptrrecord" before. - ptr = row.get("addptr", row.get("ptrrecord", "1")) - result.append( - { - "uuid": row.get("uuid", ""), - "hostname": host, - "domain": domain, - "fqdn": fqdn, - "ip": ip, - "record_type": rr, - "description": row.get("description", "") or "", - "enabled": str(row.get("enabled", "1")) == "1", - "ptrrecord": str(ptr) == "1", - "service": "unbound", - } - ) - except Exception as exc: - logger.warning("Failed to fetch Unbound host overrides: %s", exc) + seen.add(key) + # The auto-PTR flag is "addptr" since 25.x, "ptrrecord" before. + ptr = row.get("addptr", row.get("ptrrecord", "1")) + result.append( + { + "uuid": row.get("uuid", ""), + "hostname": host, + "domain": domain, + "fqdn": fqdn, + "ip": ip, + "record_type": rr, + "description": row.get("description", "") or "", + "enabled": str(row.get("enabled", "1")) == "1", + "ptrrecord": str(ptr) == "1", + "service": "unbound", + } + ) return sorted(result, key=lambda e: e["fqdn"].lower()) def _get_dnsmasq_host_overrides(self) -> list[dict[str, Any]]: result: list[dict[str, Any]] = [] - try: - data = self._post( - "/api/dnsmasq/settings/searchhostoverride", - {"current": 1, "rowCount": -1, "searchPhrase": ""}, + data = self._post( + "/api/dnsmasq/settings/searchhostoverride", + {"current": 1, "rowCount": -1, "searchPhrase": ""}, + ) + for row in data.get("rows", []): + host = row.get("host", "") or "" + domain = row.get("domain", "") or "" + fqdn = f"{host}.{domain}" if host and domain else host or domain + result.append( + { + "uuid": row.get("uuid", ""), + "hostname": host, + "domain": domain, + "fqdn": fqdn, + "ip": row.get("ip", "") or "", + "record_type": "A", + "description": row.get("description", "") or "", + "enabled": str(row.get("enabled", "1")) == "1", + "service": "dnsmasq", + } ) - for row in data.get("rows", []): - host = row.get("host", "") or "" - domain = row.get("domain", "") or "" - fqdn = f"{host}.{domain}" if host and domain else host or domain - result.append( - { - "uuid": row.get("uuid", ""), - "hostname": host, - "domain": domain, - "fqdn": fqdn, - "ip": row.get("ip", "") or "", - "record_type": "A", - "description": row.get("description", "") or "", - "enabled": str(row.get("enabled", "1")) == "1", - "service": "dnsmasq", - } - ) - except Exception as exc: - logger.warning("Failed to fetch Dnsmasq host overrides: %s", exc) return sorted(result, key=lambda e: e["fqdn"].lower()) def set_dns_entry(self, uuid: str, service: str, data: dict[str, Any]) -> dict[str, Any]: diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index e1f3188..70c3925 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -6,7 +6,7 @@ "napalm_opnsense/listening.py::_service_of": 12, "napalm_opnsense/listening.py::_socket": 19, "napalm_opnsense/opnsense.py::OPNsenseDriver._allow_snmp_sources": 11, - "napalm_opnsense/opnsense.py::OPNsenseDriver._get_unbound_host_overrides": 17, + "napalm_opnsense/opnsense.py::OPNsenseDriver._get_unbound_host_overrides": 16, "napalm_opnsense/opnsense.py::OPNsenseDriver._kea_read_list": 11, "napalm_opnsense/opnsense.py::OPNsenseDriver.apply_dhcp_subnet": 21, "napalm_opnsense/opnsense.py::OPNsenseDriver.apply_firewall_rule": 11, @@ -31,7 +31,6 @@ "napalm_opnsense/virtual_ips.py::carp_addresses": 14 }, "function_lines": { - "napalm_opnsense/opnsense.py::OPNsenseDriver._get_unbound_host_overrides": 51, "napalm_opnsense/opnsense.py::OPNsenseDriver._regenerate_web_cert": 51, "napalm_opnsense/opnsense.py::OPNsenseDriver.apply_dhcp_subnet": 60, "napalm_opnsense/opnsense.py::OPNsenseDriver.create_dhcp_reservation": 85, @@ -57,7 +56,7 @@ "napalm_opnsense.resolver_mixin" ], "python_file_lines": { - "napalm_opnsense/opnsense.py": 3083 + "napalm_opnsense/opnsense.py": 3077 }, "untyped_public": [ "napalm_opnsense/opnsense.py::OPNsenseDriver.get_snmp_config" diff --git a/tests/unit/test_driver.py b/tests/unit/test_driver.py index c6550f8..a0d6586 100644 --- a/tests/unit/test_driver.py +++ b/tests/unit/test_driver.py @@ -2888,6 +2888,44 @@ class TestSyncDnsZone: assert len([p for p, _ in calls if p.endswith("addhostoverride")]) == 1 + @pytest.mark.parametrize("service", ["unbound", "dnsmasq"]) + def test_a_failed_read_raises_and_changes_nothing(self, driver, service): + """#14: a sync on an inventory it could not read deleted nothing and + added every record a second time.""" + calls = [] + + def _post(path, data=None): + calls.append(path) + if path.endswith("searchhostoverride"): + raise requests.exceptions.ConnectionError("reset by peer") + return {"result": "saved"} + + driver._detect_active_dns = lambda: service + driver._post = _post + + with pytest.raises(requests.exceptions.ConnectionError): + driver.sync_dns_zone( + "office.local", + [{"hostname": "nas", "ip": "172.22.40.8", "record_type": "A", "enabled": True}], + ) + + assert calls == [f"/api/{service}/settings/searchhostoverride"] + + +class TestHostOverrideReadFailure: + """A failed read raises: an empty list would say the firewall has no overrides.""" + + @pytest.mark.parametrize("service", ["unbound", "dnsmasq"]) + def test_get_dns_entries_raises_when_the_search_fails(self, driver, service): + def _post(path, data=None): + raise requests.exceptions.HTTPError("500 Server Error") + + driver._detect_active_dns = lambda: service + driver._post = _post + + with pytest.raises(requests.exceptions.HTTPError): + driver.get_dns_entries() + # --------------------------------------------------------------------------- # uninstall_package – says what it cannot do -- 2.54.1 From ea0a52717ea5c64a536529295c0f93b9292d5189 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 21:50:15 +0100 Subject: [PATCH 3/3] fix(dhcp): match Kea reservations on address and MAC create_dhcp_reservation and delete_dhcp_reservation_and_lease looked a reservation up by its address alone. A reservation another MAC held for the address, made by hand or left from an earlier host, was overwritten on create and removed on delete, together with that host's lease. Create now raises instead of taking it over, and delete leaves another MAC's reservation and lease in place and names that MAC in the new reservation_other_mac field. The matching lives in kea_reservations, a module under strict typing. Closes #26 --- CHANGELOG.md | 5 ++ napalm_opnsense/kea_reservations.py | 59 ++++++++++++++++ napalm_opnsense/opnsense.py | 85 ++++++++++------------- tests/quality_baseline.json | 8 +-- tests/unit/test_driver.py | 100 +++++++++++++++++++++++++--- tests/unit/test_kea_reservations.py | 67 +++++++++++++++++++ 6 files changed, 260 insertions(+), 64 deletions(-) create mode 100644 napalm_opnsense/kea_reservations.py create mode 100644 tests/unit/test_kea_reservations.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 53a1ec6..609136b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,11 @@ All notable changes to this driver. The format follows - `sync_dns_zone()` and `get_dns_entries()` raise when the host overrides cannot be read. A transient API error used to read as "no overrides": the sync then deleted nothing and added every record a second time (#14). +- `create_dhcp_reservation()` no longer takes over a Kea reservation another MAC + holds for the address (made by hand, say): it raises `RuntimeError` and leaves it + as it is. `delete_dhcp_reservation_and_lease()` removes only the reservation and + lease of the given MAC and reports another host's reservation for the address in + the new `reservation_other_mac` field (#26). - `configure_snmp_agent()` works on OPNsense 26.x again. The configure step sent fields the os-net-snmp model does not have (`contact`, `location`, `sysobjid`, `bindip`) and `listen` in the shape `get` returns rather than as a string, which diff --git a/napalm_opnsense/kea_reservations.py b/napalm_opnsense/kea_reservations.py new file mode 100644 index 0000000..dc064a4 --- /dev/null +++ b/napalm_opnsense/kea_reservations.py @@ -0,0 +1,59 @@ +"""Which Kea DHCPv4 reservation or lease is whose, read from the os-kea API rows. + +A reservation is the pair of an address and a MAC. Matching on the address alone +takes over or removes another host's reservation once an address was reused or +edited by hand (#26), so every lookup here checks both. +""" + +from __future__ import annotations + +from typing import Any + +from napalm_device_types.dhcp import normalize_mac + +#: Where a ``leases4/search`` row keeps the client's MAC: os-kea, then plain Kea. +_LEASE_MAC_FIELDS = ("hwaddr", "hw-address") + + +def _mac_of(row: dict[str, Any], *fields: str) -> str: + return normalize_mac(next((str(row[f]) for f in fields if row.get(f)), "")) + + +def split_by_mac(rows: list[dict[str, Any]], mac: str) -> tuple[dict[str, Any] | None, str]: + """``(the row *mac* holds, the MAC of a row another host holds)`` among *rows*. + + *rows* are ``searchReservation`` rows for one address; either part is + ``None`` or ``""`` when there is none. + """ + wanted = normalize_mac(mac) + own = next((row for row in rows if _mac_of(row, "hw_address") == wanted), None) + others = [_mac_of(row, "hw_address") for row in rows] + return own, next((m for m in others if m and m != wanted), "") + + +def lease_held(rows: list[dict[str, Any]], ip: str, mac: str) -> bool: + """Whether a ``leases4/search`` row gives *ip* to *mac*.""" + return any( + (row.get("address") or row.get("ip-address")) == ip + and _mac_of(row, *_LEASE_MAC_FIELDS) == normalize_mac(mac) + for row in rows + ) + + +def reservation_unchanged(row: dict[str, Any], wanted: dict[str, Any], subnet_cidr: str) -> bool: + """Whether a ``searchReservation`` row already holds every field we would write. + + The MAC is compared normalised: Kea keeps it as it was entered, in + either case and with ``:`` or ``-``. The subnet is a model relation that + comes back as the subnet's CIDR or its UUID depending on the OPNsense + version, so either counts. A field the row does not carry counts as a + difference -- writing once too often is the safe side. + """ + if str(row.get("subnet") or "").strip() not in {wanted["subnet"], subnet_cidr}: + return False + if normalize_mac(row.get("hw_address")) != normalize_mac(wanted["hw_address"]): + return False + return all( + str(row.get(field) or "") == str(wanted[field] or "") + for field in ("ip_address", "hostname", "description") + ) diff --git a/napalm_opnsense/opnsense.py b/napalm_opnsense/opnsense.py index 5b312fa..f48ff7d 100644 --- a/napalm_opnsense/opnsense.py +++ b/napalm_opnsense/opnsense.py @@ -64,6 +64,7 @@ from requests.exceptions import RequestException from napalm_opnsense.api_endpoint import ALIVE_TIMEOUT, api_endpoint from napalm_opnsense.ha import config_sync, dhcp_ha +from napalm_opnsense.kea_reservations import lease_held, reservation_unchanged, split_by_mac from napalm_opnsense.listening import parse_socket_statistics, wireguard_listen_ports from napalm_opnsense.ospf_mixin import OPNsenseOspfMixin from napalm_opnsense.ping_mixin import OPNsensePingMixin @@ -1452,7 +1453,8 @@ class OPNsenseDriver( :param hostname: optional hostname to record on the reservation. :raises ValueError: if no Kea subnet contains ``ip``. :raises RuntimeError: if Kea rejects the reservation (validation - errors) or the Kea plugin isn't installed/enabled. + errors), the Kea plugin isn't installed/enabled, or ``ip`` is + already reserved for another MAC (left untouched; the caller decides). """ try: subnets = self._get("/api/kea/dhcpv4/searchSubnet").get("rows") or [] @@ -1473,21 +1475,7 @@ class OPNsenseDriver( if subnet_uuid is None: raise ValueError(f"No Kea-managed subnet contains {ip}") - # Idempotency: reuse an existing reservation for this IP if one - # already exists (e.g. a retried provisioning job), rather than - # creating a duplicate Kea rejects anyway. - existing_row: dict[str, Any] | None = None - try: - existing = self._post( - "/api/kea/dhcpv4/searchReservation", - {"current": 1, "rowCount": -1, "searchPhrase": ip}, - ) - for row in existing.get("rows") or []: - if row.get("ip_address") == ip: - existing_row = row - break - except Exception as exc: - logger.debug("Kea reservation search failed, proceeding to add: %s", exc) + existing_row = self._kea_own_reservation(ip, mac) payload = { "reservation": { @@ -1498,7 +1486,7 @@ class OPNsenseDriver( "description": self._NETORK_TAG, } } - if existing_row is not None and self._kea_reservation_unchanged( + if existing_row is not None and reservation_unchanged( existing_row, payload["reservation"], subnet_cidr ): logger.debug("Kea reservation for %s is already as requested, not touched", ip) @@ -1516,26 +1504,25 @@ class OPNsenseDriver( self._post("/api/kea/service/reconfigure") - @staticmethod - def _kea_reservation_unchanged( - row: dict[str, Any], wanted: dict[str, Any], subnet_cidr: str - ) -> bool: - """Whether a ``searchReservation`` row already holds every field we would write. - - The MAC is compared normalised: Kea keeps it as it was entered, in - either case and with ``:`` or ``-``. The subnet is a model relation that - comes back as the subnet's CIDR or its UUID depending on the OPNsense - version, so either counts. A field the row does not carry counts as a - difference -- writing once too often is the safe side. - """ - if str(row.get("subnet") or "").strip() not in {wanted["subnet"], subnet_cidr}: - return False - if normalize_mac(row.get("hw_address")) != normalize_mac(wanted["hw_address"]): - return False - return all( - str(row.get(field) or "") == str(wanted[field] or "") - for field in ("ip_address", "hostname", "description") + def _kea_reservations_at(self, ip: str) -> list[dict[str, Any]]: + """The ``searchReservation`` rows for *ip* -- the search is a phrase match.""" + found = self._post( + "/api/kea/dhcpv4/searchReservation", + {"current": 1, "rowCount": -1, "searchPhrase": ip}, ) + return [row for row in found.get("rows") or [] if row.get("ip_address") == ip] + + def _kea_own_reservation(self, ip: str, mac: str) -> dict[str, Any] | None: + """*mac*'s reservation for *ip*, updated in place on a retry; raises if another + MAC holds *ip* (#26).""" + try: + own, other = split_by_mac(self._kea_reservations_at(ip), mac) + except Exception as exc: + logger.debug("Kea reservation search failed, proceeding to add: %s", exc) + return None + if own is None and other: + raise RuntimeError(f"Kea already reserves {ip} for {other}, not {normalize_mac(mac)}") + return own def delete_dhcp_reservation_and_lease(self, mac: str, ip: str) -> dict[str, Any]: """Remove a Kea DHCPv4 static reservation and any active lease for (mac, ip). @@ -1565,10 +1552,14 @@ class OPNsenseDriver( returns ``{"status": "error", "message": "Missing lease IP parameter"}``; only ``POST /api/kea/leases4/del_lease/{ip}`` works. + Both match on ``ip`` and ``mac``: another MAC's (an address reused or + edited by hand) is left alone, its reservation reported (#26). + :param mac: NIC MAC address of the reservation to remove. :param ip: IP address of the reservation/lease to remove. :returns: {"reservation_found", "reservation_deleted", "lease_found", - "lease_deleted"} — all bool. + "lease_deleted"} — all bool — and ``reservation_other_mac``, the MAC + another host holds a reservation for ``ip`` under ("" if none). :raises RuntimeError: Kea plugin unavailable, or Kea rejects deletion of a reservation that does exist. """ @@ -1577,26 +1568,22 @@ class OPNsenseDriver( "reservation_deleted": False, "lease_found": False, "lease_deleted": False, + "reservation_other_mac": "", } # --- Reservation --- try: - existing = self._post( - "/api/kea/dhcpv4/searchReservation", - {"current": 1, "rowCount": -1, "searchPhrase": ip}, - ) + rows = self._kea_reservations_at(ip) except Exception as exc: raise RuntimeError(f"Kea DHCPv4 plugin unavailable: {exc}") from exc - reservation_uuid = None - for row in existing.get("rows") or []: - if row.get("ip_address") == ip: - reservation_uuid = row.get("uuid") - break + own, result["reservation_other_mac"] = split_by_mac(rows, mac) + if result["reservation_other_mac"]: + logger.warning("Kea reservation of another MAC for %s left alone", ip) - if reservation_uuid: + if own and own.get("uuid"): result["reservation_found"] = True - del_result = self._post(f"/api/kea/dhcpv4/delReservation/{reservation_uuid}") + del_result = self._post(f"/api/kea/dhcpv4/delReservation/{own['uuid']}") if del_result.get("result") != "deleted": raise RuntimeError(f"Kea rejected reservation delete for {ip}: {del_result}") result["reservation_deleted"] = True @@ -1606,7 +1593,7 @@ class OPNsenseDriver( try: leases = self._get("/api/kea/leases4/search") rows = leases.get("rows") or leases.get("leases") or [] - if any((row.get("address") or row.get("ip-address")) == ip for row in rows): + if lease_held(rows, ip, mac): result["lease_found"] = True del_lease = self._post(f"/api/kea/leases4/del_lease/{ip}") result["lease_deleted"] = bool( diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 70c3925..a0c1215 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -10,8 +10,8 @@ "napalm_opnsense/opnsense.py::OPNsenseDriver._kea_read_list": 11, "napalm_opnsense/opnsense.py::OPNsenseDriver.apply_dhcp_subnet": 21, "napalm_opnsense/opnsense.py::OPNsenseDriver.apply_firewall_rule": 11, - "napalm_opnsense/opnsense.py::OPNsenseDriver.create_dhcp_reservation": 16, - "napalm_opnsense/opnsense.py::OPNsenseDriver.delete_dhcp_reservation_and_lease": 14, + "napalm_opnsense/opnsense.py::OPNsenseDriver.create_dhcp_reservation": 12, + "napalm_opnsense/opnsense.py::OPNsenseDriver.delete_dhcp_reservation_and_lease": 11, "napalm_opnsense/opnsense.py::OPNsenseDriver.get_bgp_neighbors": 16, "napalm_opnsense/opnsense.py::OPNsenseDriver.get_dhcp_leases": 15, "napalm_opnsense/opnsense.py::OPNsenseDriver.get_dhcp_leases._parse_kea": 14, @@ -33,7 +33,7 @@ "function_lines": { "napalm_opnsense/opnsense.py::OPNsenseDriver._regenerate_web_cert": 51, "napalm_opnsense/opnsense.py::OPNsenseDriver.apply_dhcp_subnet": 60, - "napalm_opnsense/opnsense.py::OPNsenseDriver.create_dhcp_reservation": 85, + "napalm_opnsense/opnsense.py::OPNsenseDriver.create_dhcp_reservation": 72, "napalm_opnsense/opnsense.py::OPNsenseDriver.delete_dhcp_reservation_and_lease": 79, "napalm_opnsense/opnsense.py::OPNsenseDriver.get_bgp_neighbors": 86, "napalm_opnsense/opnsense.py::OPNsenseDriver.get_dhcp_leases": 106, @@ -56,7 +56,7 @@ "napalm_opnsense.resolver_mixin" ], "python_file_lines": { - "napalm_opnsense/opnsense.py": 3077 + "napalm_opnsense/opnsense.py": 3064 }, "untyped_public": [ "napalm_opnsense/opnsense.py::OPNsenseDriver.get_snmp_config" diff --git a/tests/unit/test_driver.py b/tests/unit/test_driver.py index a0d6586..abaa5e6 100644 --- a/tests/unit/test_driver.py +++ b/tests/unit/test_driver.py @@ -1846,6 +1846,18 @@ KEA_SUBNETS_RESPONSE = { } +def _reservation_row(mac, ip="172.22.8.253", uuid="existing-uuid-456"): + """A searchReservation row, in the shape the os-kea plugin returns it.""" + return { + "uuid": uuid, + "subnet": "172.22.8.0/24", + "ip_address": ip, + "hw_address": mac, + "hostname": "", + "description": "[netork]", + } + + class TestCreateDhcpReservation: def test_adds_new_reservation_when_none_exists(self, driver): driver.session.get.return_value = _make_json_response(KEA_SUBNETS_RESPONSE) @@ -1876,14 +1888,14 @@ class TestCreateDhcpReservation: def test_updates_existing_reservation_for_same_ip(self, driver): driver.session.get.return_value = _make_json_response(KEA_SUBNETS_RESPONSE) driver.session.post.side_effect = [ - _make_json_response( - {"rows": [{"uuid": "existing-uuid-456", "ip_address": "172.22.8.253"}]} - ), + _make_json_response({"rows": [_reservation_row("02-AA-BB-CC-DD-EE")]}), _make_json_response({"result": "saved", "uuid": "existing-uuid-456"}), _make_json_response({"status": "ok"}), ] - driver.create_dhcp_reservation(mac="02:aa:bb:cc:dd:ee", ip="172.22.8.253") + driver.create_dhcp_reservation( + mac="02:aa:bb:cc:dd:ee", ip="172.22.8.253", hostname="new-vm" + ) set_call = driver.session.post.call_args_list[1] assert ( @@ -1932,7 +1944,6 @@ class TestCreateDhcpReservation: @pytest.mark.parametrize( "field, live_value", [ - ("hw_address", "02:aa:bb:cc:dd:ff"), ("hostname", "old-vm"), ("description", "made by hand"), ("subnet", "172.22.0.0/24"), @@ -1968,6 +1979,23 @@ class TestCreateDhcpReservation: "https://opnsense.example.com/api/kea/service/reconfigure", ] + def test_does_not_take_over_another_macs_reservation(self, driver): + """#26: a reservation for the IP held by another MAC (made by hand, say) + was overwritten with the new MAC and the netOrk tag. It now raises and + leaves the firewall as it is; the caller decides.""" + driver.session.get.return_value = _make_json_response(KEA_SUBNETS_RESPONSE) + driver.session.post.side_effect = [ + _make_json_response({"rows": [_reservation_row("02:11:22:33:44:55")]}), + ] + + with pytest.raises(RuntimeError, match="02:11:22:33:44:55"): + driver.create_dhcp_reservation( + mac="02:aa:bb:cc:dd:ee", ip="172.22.8.253", hostname="new-vm" + ) + + # searchReservation only -- no setReservation, no service/reconfigure. + assert driver.session.post.call_count == 1 + def test_raises_when_ip_not_in_any_kea_subnet(self, driver): driver.session.get.return_value = _make_json_response(KEA_SUBNETS_RESPONSE) @@ -2012,7 +2040,7 @@ class TestDeleteDhcpReservationAndLease: def test_deletes_existing_reservation_and_lease(self, driver): driver.session.post.side_effect = [ _make_json_response( - {"rows": [{"uuid": "existing-uuid-456", "ip_address": "172.22.8.253"}]} + {"rows": [_reservation_row("02:aa:bb:cc:dd:ee")]} ), # searchReservation — match _make_json_response({"result": "deleted"}), # delReservation _make_json_response({"status": "ok"}), # service/reconfigure @@ -2031,6 +2059,7 @@ class TestDeleteDhcpReservationAndLease: "reservation_deleted": True, "lease_found": True, "lease_deleted": True, + "reservation_other_mac": "", } del_res_call = driver.session.post.call_args_list[1] assert ( @@ -2064,15 +2093,66 @@ class TestDeleteDhcpReservationAndLease: "reservation_deleted": False, "lease_found": False, "lease_deleted": False, + "reservation_other_mac": "", } # Only searchReservation was called — no delReservation/reconfigure/delLease. assert driver.session.post.call_count == 1 - def test_reservation_delete_raises_when_kea_rejects(self, driver): + def test_leaves_another_macs_reservation_and_lease_alone(self, driver): + """#26: the IP was matched alone, so after an address was reused or + edited by hand the call removed another host's reservation and lease.""" + driver.session.post.return_value = _make_json_response( + {"rows": [_reservation_row("02:11:22:33:44:55")]} + ) + driver.session.get.return_value = _make_json_response( + {"rows": [{"address": "172.22.8.253", "hwaddr": "02:11:22:33:44:55"}]} + ) + + result = driver.delete_dhcp_reservation_and_lease( + mac="02:aa:bb:cc:dd:ee", ip="172.22.8.253" + ) + + assert result == { + "reservation_found": False, + "reservation_deleted": False, + "lease_found": False, + "lease_deleted": False, + "reservation_other_mac": "02:11:22:33:44:55", + } + # searchReservation only -- no delReservation, reconfigure or del_lease. + assert [c.args[0] for c in driver.session.post.call_args_list] == [ + "https://opnsense.example.com/api/kea/dhcpv4/searchReservation" + ] + + def test_deletes_its_own_reservation_next_to_another_macs(self, driver): + """The search is a phrase match, so it can list another MAC's row too.""" driver.session.post.side_effect = [ _make_json_response( - {"rows": [{"uuid": "existing-uuid-456", "ip_address": "172.22.8.253"}]} + { + "rows": [ + _reservation_row("02:11:22:33:44:55", uuid="foreign-uuid"), + _reservation_row("02:aa:bb:cc:dd:ee", uuid="own-uuid"), + ] + } ), + _make_json_response({"result": "deleted"}), + _make_json_response({"status": "ok"}), + ] + driver.session.get.return_value = _make_json_response({"rows": []}) + + result = driver.delete_dhcp_reservation_and_lease( + mac="02:aa:bb:cc:dd:ee", ip="172.22.8.253" + ) + + assert result["reservation_deleted"] is True + assert result["reservation_other_mac"] == "02:11:22:33:44:55" + assert driver.session.post.call_args_list[1].args[0] == ( + "https://opnsense.example.com/api/kea/dhcpv4/delReservation/own-uuid" + ) + + def test_reservation_delete_raises_when_kea_rejects(self, driver): + driver.session.post.side_effect = [ + _make_json_response({"rows": [_reservation_row("02:AA:BB:CC:DD:EE")]}), _make_json_response({"result": "not found"}), # delReservation rejected ] @@ -2084,9 +2164,7 @@ class TestDeleteDhcpReservationAndLease: def test_lease_delete_failure_is_non_fatal(self, driver): driver.session.post.side_effect = [ - _make_json_response( - {"rows": [{"uuid": "existing-uuid-456", "ip_address": "172.22.8.253"}]} - ), + _make_json_response({"rows": [_reservation_row("02:AA:BB:CC:DD:EE")]}), _make_json_response({"result": "deleted"}), _make_json_response({"status": "ok"}), ] diff --git a/tests/unit/test_kea_reservations.py b/tests/unit/test_kea_reservations.py new file mode 100644 index 0000000..ffbc24e --- /dev/null +++ b/tests/unit/test_kea_reservations.py @@ -0,0 +1,67 @@ +"""Matching Kea reservations and leases on address and MAC (#26).""" + +from napalm_opnsense.kea_reservations import lease_held, reservation_unchanged, split_by_mac + + +def _row(mac, uuid="u-1"): + return {"uuid": uuid, "ip_address": "172.22.8.253", "hw_address": mac} + + +class TestSplitByMac: + def test_no_rows_is_neither_own_nor_other(self): + assert split_by_mac([], "02:aa:bb:cc:dd:ee") == (None, "") + + def test_own_row_matches_whatever_the_mac_spelling(self): + row = _row("02-AA-BB-CC-DD-EE") + assert split_by_mac([row], "02:aa:bb:cc:dd:ee") == (row, "") + + def test_another_hosts_row_is_reported_by_its_mac(self): + assert split_by_mac([_row("02-11-22-33-44-55")], "02:aa:bb:cc:dd:ee") == ( + None, + "02:11:22:33:44:55", + ) + + def test_a_row_without_mac_is_no_ones(self): + """It cannot be shown to be the caller's, so it is never taken as such.""" + row = {"uuid": "u-1", "ip_address": "172.22.8.253"} + assert split_by_mac([row], "02:aa:bb:cc:dd:ee") == (None, "") + + def test_another_hosts_mac_is_found_behind_a_row_without_one(self): + rows = [{"uuid": "u-0", "ip_address": "172.22.8.253"}, _row("02:11:22:33:44:55")] + assert split_by_mac(rows, "02:aa:bb:cc:dd:ee") == (None, "02:11:22:33:44:55") + + +class TestLeaseHeld: + def test_os_kea_lease_of_the_mac(self): + rows = [{"address": "172.22.8.253", "hwaddr": "02:AA:BB:CC:DD:EE"}] + assert lease_held(rows, "172.22.8.253", "02:aa:bb:cc:dd:ee") is True + + def test_plain_kea_lease_of_the_mac(self): + rows = [{"ip-address": "172.22.8.253", "hw-address": "02:aa:bb:cc:dd:ee"}] + assert lease_held(rows, "172.22.8.253", "02:aa:bb:cc:dd:ee") is True + + def test_lease_of_another_mac(self): + rows = [{"address": "172.22.8.253", "hwaddr": "02:11:22:33:44:55"}] + assert lease_held(rows, "172.22.8.253", "02:aa:bb:cc:dd:ee") is False + + def test_lease_of_another_address(self): + rows = [{"address": "172.22.8.254", "hwaddr": "02:aa:bb:cc:dd:ee"}] + assert lease_held(rows, "172.22.8.253", "02:aa:bb:cc:dd:ee") is False + + +class TestReservationUnchanged: + WANTED = { + "subnet": "subnet-uuid", + "ip_address": "172.22.8.253", + "hw_address": "02:aa:bb:cc:dd:ee", + "hostname": "new-vm", + "description": "[netork]", + } + + def test_a_different_mac_is_a_change(self): + row = dict(self.WANTED, hw_address="02:11:22:33:44:55") + assert reservation_unchanged(row, self.WANTED, "172.22.8.0/24") is False + + def test_the_same_reservation_is_unchanged(self): + row = dict(self.WANTED, hw_address="02-AA-BB-CC-DD-EE", subnet="172.22.8.0/24") + assert reservation_unchanged(row, self.WANTED, "172.22.8.0/24") is True -- 2.54.1