diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d72002..5b0bfdf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,7 +15,8 @@ recorded here; their history is the git log. to do on every poll (#8). Needs napalm-device-types with `LldpAgentMixin`. ### Changed -- The floor on napalm-device-types is 4.23.0, the first release with what this driver uses. +- The floor on napalm-device-types is 4.24.0, the first release with what this driver + uses (its shared `lldpctl` parser). - Python 3.12 is the floor (`requires-python = ">=3.12"`): netOrk runs every driver on 3.12, so 3.10 and 3.11 are no longer tested (NAPALM/driver-standard#6). - The floor on napalm is 5.1: older releases import `pkg_resources`, which a Python @@ -27,6 +28,22 @@ recorded here; their history is the git log. `manage_service("lldpd", "enable")` and `manage_service("lldpd", "start")` (#8). ### Fixed +- `get_lldp_neighbors()` and `get_lldp_neighbors_detail()` keep an interface name with + a dot whole: the neighbours of a VLAN interface such as `eth0.1` used to come back + under `eth0` with every field empty (#26). A neighbour that names its port by MAC + address or a local id is reported with that port instead of an empty one, and a + chassis named by a local id or an address with that id. The detail now also + carries the neighbour's system description and capabilities, which were always + empty. lldpd's output is parsed by napalm-device-types' shared parser. +- `get_lldp_neighbors()` reports a neighbour's chassis MAC as `mac` (lower case) when + the neighbour names its chassis by one, as napalm-linux does, so netOrk can match the + neighbour by MAC rather than by name only (#31). +- `get_lldp_neighbors()` and `get_lldp_neighbors_detail()` raise when lldpctl fails + (not installed, lldpd not running or unreachable), with lldpctl's message; they used + to return no neighbours, the same answer as a device without any (#27). An empty + result now means lldpctl ran and listed none. `get_environment()` raises when + `/proc/stat` or `/proc/meminfo` cannot be read or parsed, instead of reporting 0 % + CPU and 0 bytes of memory. - `get_arp_table()` reports an unknown age as `-1.0` (napalm-device-types' `ARP_AGE_UNKNOWN`) instead of `0.0`, which means "confirmed just now": neither `ip neigh` nor `/proc/net/arp` has an age (NetOrk/netork#1327). diff --git a/README.md b/README.md index 90a8098..c871e66 100644 --- a/README.md +++ b/README.md @@ -61,9 +61,9 @@ device.close() | `get_arp_table` | ✅ | Uses `ip neigh show` | | `get_mac_address_table` | ✅ | Uses `bridge fdb show` | | `get_config` | ✅ | Uses `uci export` | -| `get_environment` | ✅ | CPU from `/proc/stat`, memory from `/proc/meminfo` | -| `get_lldp_neighbors` | ✅ | Requires `lldpd` installed and running; reads only, never starts or configures it | -| `get_lldp_neighbors_detail` | ✅ | Requires `lldpd` installed and running; reads only, never starts or configures it | +| `get_environment` | ✅ | CPU from `/proc/stat`, memory from `/proc/meminfo`; raises when either cannot be read | +| `get_lldp_neighbors` | ✅ | Requires `lldpd` installed and running (raises otherwise); reads only, never starts or configures it | +| `get_lldp_neighbors_detail` | ✅ | Requires `lldpd` installed and running (raises otherwise); reads only, never starts or configures it | | `get_listening_sockets` | ✅ | busybox `netstat -lntup`, procd service from the process's cgroup (napalm-device-types `ListeningSocketsMixin`); over an SSH exec channel | ## Configuration management diff --git a/napalm_openwrt/lldp_mixin.py b/napalm_openwrt/lldp_mixin.py index 86da3f1..a04af1d 100644 --- a/napalm_openwrt/lldp_mixin.py +++ b/napalm_openwrt/lldp_mixin.py @@ -12,96 +12,52 @@ from __future__ import annotations -from typing import Any +from typing import TYPE_CHECKING -#: The keys a neighbour opens with in ``lldpctl -f keyvalue``: an optional -#: ``alias``, then ``via`` (lldpd's ``display_interface``). -_NEIGHBOUR_START = ("alias", "via") - - -def _keyvalue_neighbours(output: str) -> list[tuple[str, dict[str, str]]]: - """``lldpctl -f keyvalue`` as ``(local interface, {subkey: value})``, one per neighbour. - - Every neighbour on a port prints the same keys, so a port is no key: a - neighbour ends where the next one opens. A key may repeat inside one - neighbour (``chassis.mgmt-ip``, one per address); the last value stays. - """ - neighbours: list[tuple[str, dict[str, str]]] = [] - for line in output.splitlines(): - key, sep, value = line.strip().partition("=") - parts = key.split(".") - # parts: ['lldp', '', , , ...] - if not sep or len(parts) < 3 or parts[0] != "lldp": - continue - iface, subkey = parts[1], ".".join(parts[2:]) - current = neighbours[-1][1] if neighbours and neighbours[-1][0] == iface else None - if current is None or (subkey in _NEIGHBOUR_START and set(current) - {"alias"}): - current = {} - neighbours.append((iface, current)) - current[subkey] = value - return neighbours +from napalm.base.models import LLDPNeighborDetailDict +from napalm_device_types import ( + LLDPCTL_KEYVALUE_COMMAND, + LldpNeighborDict, + LldpNeighborRow, + lldp_neighbors, + lldp_neighbors_detail, + parse_lldpctl_keyvalue, +) class OpenWrtLLDPMixin: """Mixin providing LLDP NAPALM getters.""" - def get_lldp_neighbors(self) -> dict[str, list[dict[str, Any]]]: + def get_lldp_neighbors(self) -> dict[str, list[LldpNeighborDict]]: """Return LLDP neighbors (requires ``lldpd`` installed and running on the device). + A neighbour that names its chassis by a MAC address carries it as ``mac``. + Uses ``lldpctl -f keyvalue`` output:: lldp.eth0.port.ifname=eth1 lldp.eth0.chassis.name=router-core """ - neighbors: dict[str, list[dict[str, Any]]] = {} - for row in self._get_lldp_table(): - neighbors.setdefault(row["local_port"], []).append( - {"hostname": row["system_name"], "port": row["port_id"]} - ) - return neighbors + return lldp_neighbors(self._get_lldp_table()) - def _get_lldp_table(self) -> list[dict[str, Any]]: - """Parse ``lldpctl -f keyvalue`` into a list of row dicts. + def _get_lldp_table(self) -> list[LldpNeighborRow]: + """``lldpctl -f keyvalue`` as one row per neighbour. Reads only: lldpd is neither started nor reconfigured here. Installing, starting and configuring it are the caller's (``ensure_package``, ``manage_service``). + + :raises ValueError: when lldpctl failed (not installed, lldpd not + running): that is no answer, not a port without neighbours. """ - output = self._send_command("lldpctl -f keyvalue") - rows: list[dict[str, Any]] = [] + return parse_lldpctl_keyvalue(self._send_command(LLDPCTL_KEYVALUE_COMMAND)) - for iface, data in _keyvalue_neighbours(output): - rows.append( - { - "local_port": iface, - "remote_chassis_id": data.get("chassis.mac", data.get("chassis.id.value", "")), - "port_id": data.get("port.ifname", data.get("port.id.value", "")), - "mgmt_address": data.get("chassis.mgmt-ip", ""), - "port_description": data.get("port.descr", ""), - "system_name": data.get("chassis.name", ""), - } - ) - - return rows - - def get_lldp_neighbors_detail(self, interface: str = "") -> dict[str, list[dict[str, Any]]]: + def get_lldp_neighbors_detail( + self, interface: str = "" + ) -> dict[str, list[LLDPNeighborDetailDict]]: """Return detailed LLDP neighbor info.""" - details: dict[str, list[dict[str, Any]]] = {} + return lldp_neighbors_detail(self._get_lldp_table(), interface) - for row in self._get_lldp_table(): - if interface and row["local_port"] != interface: - continue - details.setdefault(row["local_port"], []).append( - { - "parent_interface": "", - "remote_port": row["port_id"], - "remote_port_description": row["port_description"], - "remote_chassis_id": row["remote_chassis_id"], - "remote_system_name": row["system_name"], - "remote_system_description": "", - "remote_system_capab": [], - "remote_system_enable_capab": [], - } - ) + if TYPE_CHECKING: # pragma: no cover - the driver's - return details + def _send_command(self, command: str | list[str]) -> str: ... diff --git a/napalm_openwrt/system_mixin.py b/napalm_openwrt/system_mixin.py index 7b48943..95f7179 100644 --- a/napalm_openwrt/system_mixin.py +++ b/napalm_openwrt/system_mixin.py @@ -25,6 +25,8 @@ _RC_RE = re.compile(rf"^{_RC_MARKER}(\d+)\s*$", re.MULTILINE) _APK_INDEX_MISSING = re.compile(r"opening from cache .*No such file or directory") #: The aggregate CPU line of ``/proc/stat``, read twice one second apart. _CPU_SAMPLES = "grep '^cpu ' /proc/stat; sleep 1; grep '^cpu ' /proc/stat" +#: ``MemTotal: 124608 kB`` and ``MemAvailable:`` of ``/proc/meminfo``. +_MEMINFO_RE = re.compile(r"^(MemTotal|MemAvailable):\s+(\d+)\s+kB\s*$", re.MULTILINE) def _split_status(raw: str) -> tuple[str, int | None]: @@ -61,22 +63,33 @@ def _cpu_counters(line: str) -> tuple[int, int]: def _cpu_usage_percent(output: str) -> float: """Busy share of the time between the two ``cpu`` lines of :data:`_CPU_SAMPLES`. - 0.0 when there are not two readable lines or the counters did not move. + 0.0 when the counters did not move. + + :raises ValueError: when the output does not hold two readable ``cpu`` lines. """ lines = [line for line in output.splitlines() if line.startswith("cpu ")] if len(lines) < 2: - return 0.0 - try: - idle1, total1 = _cpu_counters(lines[0]) - idle2, total2 = _cpu_counters(lines[1]) - except ValueError: - return 0.0 + raise ValueError(f"/proc/stat gave no two cpu readings: {output[:200]!r}") + idle1, total1 = _cpu_counters(lines[0]) + idle2, total2 = _cpu_counters(lines[1]) elapsed = total2 - total1 if elapsed <= 0: return 0.0 return (1 - (idle2 - idle1) / elapsed) * 100 +def _meminfo_kib(output: str) -> tuple[int, int]: + """``(MemTotal, MemAvailable)`` in KiB from ``/proc/meminfo``. + + :raises ValueError: when either is missing or not a number. + """ + values = dict(_MEMINFO_RE.findall(output)) + missing = [key for key in ("MemTotal", "MemAvailable") if key not in values] + if missing: + raise ValueError(f"/proc/meminfo has no {', '.join(missing)}: {output[:200]!r}") + return int(values["MemTotal"]), int(values["MemAvailable"]) + + class OpenWrtSystemMixin: """Mixin providing system-level NAPALM getters. @@ -89,23 +102,12 @@ class OpenWrtSystemMixin: CPU usage from ``/proc/stat``: the difference of two reads one second apart, so it is the last second, not the average since boot. Memory from ``/proc/meminfo``. + + :raises ValueError: when either file could not be read or parsed; a + failed read is no 0 % CPU and no 0 bytes of memory. """ cpu_pct = _cpu_usage_percent(self._send_command(_CPU_SAMPLES)) - mem_out = self._send_command("cat /proc/meminfo") - - mem_total = 0 - mem_available = 0 - for line in mem_out.splitlines(): - if line.startswith("MemTotal:"): - try: - mem_total = int(line.split()[1]) - except (IndexError, ValueError): - pass - elif line.startswith("MemAvailable:"): - try: - mem_available = int(line.split()[1]) - except (IndexError, ValueError): - pass + mem_total, mem_available = _meminfo_kib(self._send_command("cat /proc/meminfo")) return { "fans": {}, diff --git a/pyproject.toml b/pyproject.toml index 70ad6df..c9e6c5a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,7 +21,7 @@ classifiers = [ ] dependencies = [ "napalm>=5.1", # older releases import pkg_resources, which a 3.12 venv lacks - "napalm_device_types>=4.23.0", + "napalm_device_types>=4.24.0", "netmiko>=4.0.0", "paramiko>=5.0.0", # CVE-2026-44405 "netaddr>=0.7.19", # IPAddress; below it the package has none (CI lowest job) @@ -71,7 +71,6 @@ ignore_missing_imports = true module = [ "napalm_openwrt.config_mixin", "napalm_openwrt.interfaces_mixin", - "napalm_openwrt.lldp_mixin", "napalm_openwrt.openwrt", "napalm_openwrt.packages_mixin", "napalm_openwrt.routing_mixin", diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 0cbab18..fc2dcf8 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -40,7 +40,6 @@ "mypy_relaxed": [ "napalm_openwrt.config_mixin", "napalm_openwrt.interfaces_mixin", - "napalm_openwrt.lldp_mixin", "napalm_openwrt.openwrt", "napalm_openwrt.packages_mixin", "napalm_openwrt.routing_mixin", diff --git a/tests/unit/test_driver.py b/tests/unit/test_driver.py index 8b694c6..abdc083 100644 --- a/tests/unit/test_driver.py +++ b/tests/unit/test_driver.py @@ -3,6 +3,7 @@ from unittest.mock import MagicMock, patch import pytest +from napalm_device_types import LLDPCTL_KEYVALUE_COMMAND from napalm_openwrt.openwrt import OpenWrtDriver @@ -335,6 +336,17 @@ class TestGetLldpNeighbors: assert result["eth0"][0]["hostname"] == "core-router" assert result["eth0"][0]["port"] == "ether1" + def test_the_chassis_mac_is_reported(self, driver): + # netOrk matches a neighbour by this MAC first (#31). + driver._send_command = lambda cmd, **kw: LLDPCTL_KV + + assert driver.get_lldp_neighbors()["eth0"][0]["mac"] == "00:aa:bb:cc:dd:ee" + + def test_a_chassis_named_by_a_local_id_has_no_mac(self, driver): + driver._send_command = lambda cmd, **kw: LLDPCTL_KV_DOTTED_AND_ID_TYPES + + assert driver.get_lldp_neighbors()["eth1"] == [{"hostname": "access-sw", "port": "gi1/0/7"}] + # Two neighbours on one port, laid out the way lldpd's keyvalue writer prints them # (src/client/display.c, kv_writer.c): every neighbour opens with an optional @@ -390,7 +402,7 @@ class TestLldpGettersOnlyRead: getattr(driver, getter)() - assert sent == ["lldpctl -f keyvalue"] + assert sent == [LLDPCTL_KEYVALUE_COMMAND] class TestLldpSeveralNeighboursOnOnePort: @@ -401,11 +413,11 @@ class TestLldpSeveralNeighboursOnOnePort: result = driver.get_lldp_neighbors() - assert result["lan1"] == [ - {"hostname": "desk-phone", "port": "lan"}, - {"hostname": "desk-pc", "port": "eno1"}, + assert [(n["hostname"], n["port"]) for n in result["lan1"]] == [ + ("desk-phone", "lan"), + ("desk-pc", "eno1"), ] - assert result["eth0"] == [{"hostname": "core-router", "port": "ether1"}] + assert [(n["hostname"], n["port"]) for n in result["eth0"]] == [("core-router", "ether1")] def test_a_neighbour_keeps_only_its_own_fields(self, driver): driver._send_command = lambda cmd, **kw: LLDPCTL_KV_TWO_ON_ONE_PORT @@ -421,6 +433,105 @@ class TestLldpSeveralNeighboursOnOnePort: assert len(driver.get_lldp_neighbors_detail("lan1")["lan1"]) == 2 +class TestLldpFailedRead: + """A failed lldpctl raises; no neighbours only when it ran and listed none (#27).""" + + @pytest.mark.parametrize("getter", ["get_lldp_neighbors", "get_lldp_neighbors_detail"]) + def test_a_missing_lldpctl_raises(self, driver, getter): + driver._send_command = lambda cmd, **kw: "ash: lldpctl: not found\n__LLDPCTL_RC=127" + + with pytest.raises(ValueError, match="lldpctl: not found"): + getattr(driver, getter)() + + def test_an_unreachable_lldpd_raises(self, driver): + driver._send_command = lambda cmd, **kw: ( + "[WARN/control] unable to connect to socket /var/run/lldpd.socket: " + "No such file or directory\n__LLDPCTL_RC=1" + ) + + with pytest.raises(ValueError, match="unable to connect"): + driver.get_lldp_neighbors() + + def test_lldpctl_without_neighbours_lists_none(self, driver): + driver._send_command = lambda cmd, **kw: "__LLDPCTL_RC=0" + + assert driver.get_lldp_neighbors() == {} + assert driver.get_lldp_neighbors_detail() == {} + + def test_the_exit_status_comes_back_with_the_output(self, driver): + sent: list = [] + + def send(cmd, **kw): + sent.append(cmd) + return LLDPCTL_KV + "__LLDPCTL_RC=0" + + driver._send_command = send + + assert driver.get_lldp_neighbors()["eth0"][0]["hostname"] == "core-router" + assert sent == [LLDPCTL_KEYVALUE_COMMAND] + + +# A swconfig VLAN interface (``eth0.1``) with a neighbour that names its port by +# MAC, and a switch on ``eth1`` that names itself and its port by local ids. +# Laid out the way lldpd's keyvalue writer prints them (src/client/display.c): +# an id is printed under its type, never as ``id.value``. Not recorded from a device. +LLDPCTL_KV_DOTTED_AND_ID_TYPES = """\ +lldp.eth0.1.via=LLDP +lldp.eth0.1.rid=1 +lldp.eth0.1.chassis.mac=00:11:22:33:44:01 +lldp.eth0.1.chassis.name=desk-phone +lldp.eth0.1.chassis.descr=SIP phone +lldp.eth0.1.chassis.Tel.enabled=on +lldp.eth0.1.port.mac=00:11:22:33:44:01 +lldp.eth0.1.port.descr=WAN +lldp.eth1.via=LLDP +lldp.eth1.rid=2 +lldp.eth1.chassis.local=access-sw-01 +lldp.eth1.chassis.name=access-sw +lldp.eth1.chassis.Bridge.enabled=on +lldp.eth1.chassis.Router.enabled=off +lldp.eth1.port.local=gi1/0/7 +""" + + +class TestLldpDottedInterfaceAndPortIds: + """``eth0.1`` keeps its name, and a port id given as MAC or local id is read (#26).""" + + def test_a_dotted_interface_keeps_its_name(self, driver): + driver._send_command = lambda cmd, **kw: LLDPCTL_KV_DOTTED_AND_ID_TYPES + + result = driver.get_lldp_neighbors() + + assert sorted(result) == ["eth0.1", "eth1"] + assert result["eth0.1"][0]["hostname"] == "desk-phone" + + def test_a_port_given_by_mac_or_local_id_is_read(self, driver): + driver._send_command = lambda cmd, **kw: LLDPCTL_KV_DOTTED_AND_ID_TYPES + + result = driver.get_lldp_neighbors() + + assert result["eth0.1"][0]["port"] == "00:11:22:33:44:01" + assert result["eth1"][0]["port"] == "gi1/0/7" + + def test_a_chassis_given_by_a_local_id_is_read(self, driver): + driver._send_command = lambda cmd, **kw: LLDPCTL_KV_DOTTED_AND_ID_TYPES + + switch = driver.get_lldp_neighbors_detail("eth1")["eth1"][0] + + assert switch["remote_chassis_id"] == "access-sw-01" + + def test_the_detail_carries_description_and_capabilities(self, driver): + driver._send_command = lambda cmd, **kw: LLDPCTL_KV_DOTTED_AND_ID_TYPES + + detail = driver.get_lldp_neighbors_detail() + + phone = detail["eth0.1"][0] + assert phone["remote_port_description"] == "WAN" + assert phone["remote_system_description"] == "SIP phone" + assert phone["remote_system_enable_capab"] == ["telephone"] + assert detail["eth1"][0]["remote_system_capab"] == ["bridge", "router"] + + BRIDGE_VLAN_SHOW = """\ port vlan-id eth0 1 PVID Egress Untagged @@ -2137,10 +2248,41 @@ class TestGetEnvironmentCpu: assert driver.get_environment()["cpu"][0]["%usage"] == 0.0 - def test_a_single_read_is_not_taken_for_usage(self, driver): + def test_a_single_read_raises(self, driver): + # Not taken for the usage (#10), and not reported as 0 % either (#27). self._answer(driver, "cpu 1000 0 500 8500 0 0 0\n") - assert driver.get_environment()["cpu"][0]["%usage"] == 0.0 + with pytest.raises(ValueError, match="/proc/stat"): + driver.get_environment() + + def test_an_unreadable_proc_stat_raises(self, driver): + self._answer(driver, "grep: /proc/stat: No such file or directory\n") + + with pytest.raises(ValueError, match="/proc/stat"): + driver.get_environment() + + def test_a_garbled_cpu_line_raises(self, driver): + self._answer(driver, "cpu 1000 0 500 x 0 0 0\ncpu 1090 0 500 8510 0 0 0\n") + + with pytest.raises(ValueError): + driver.get_environment() + + @pytest.mark.parametrize( + "meminfo", + [ + "cat: can't open '/proc/meminfo': No such file or directory", + "MemTotal: 124608 kB\nMemFree: 43204 kB\n", + "MemTotal: 124608 kB\nMemAvailable:\n", + ], + ) + def test_an_unreadable_meminfo_raises(self, driver, meminfo): + def send(cmd, **kw): + return meminfo if "meminfo" in cmd else PROC_STAT_CPU_TWICE + + driver._send_command = send + + with pytest.raises(ValueError, match="/proc/meminfo"): + driver.get_environment() def test_memory_is_still_read(self, driver): self._answer(driver, PROC_STAT_CPU_TWICE)