diff --git a/CHANGELOG.md b/CHANGELOG.md index 9164633..51e3b44 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,11 +19,29 @@ recorded here; their history is the git log. 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 3.12 venv no longer has. +- `get_lldp_neighbors()` and `get_lldp_neighbors_detail()` only read. They no longer + enable and start a stopped lldpd, and no longer rewrite lldpd's interface list + and restart it, which could happen on every poll. A device whose lldpd is stopped + now reports no neighbours until lldpd is started, for example with + `manage_service("lldpd", "enable")` and `manage_service("lldpd", "start")` (#8). ### Fixed - `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). +- The driver no longer removes `port` from the `optional_args` dict it is given: + the caller's dict stays as it was (#19). +- `manage_service()` reports a failed action or a missing init script as failed: + only the init script's exit status decides, where any action used to come back + as a success (#3). +- `apply_updates()` reports a failed upgrade as failed, with the package manager's + exit status in `error`; it used to report every upgrade as done (#11). +- `get_environment()` reports the CPU usage of the last second, from two reads of + `/proc/stat` one second apart; it used to report the average since boot, so a box + busy for the last minute could show a low figure (#10). +- `get_lldp_neighbors()` and `get_lldp_neighbors_detail()` report every neighbour + on a port (a phone with a PC behind it, a switch without LLDP of its own); only + the last one came back, mixed with fields of the others (#9). ## [0.7.0] - 2026-10-23 diff --git a/README.md b/README.md index e7aa87f..90a8098 100644 --- a/README.md +++ b/README.md @@ -62,8 +62,8 @@ device.close() | `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` package installed on device | -| `get_lldp_neighbors_detail` | ✅ | Requires `lldpd` package installed on device | +| `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_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 168677e..86da3f1 100644 --- a/napalm_openwrt/lldp_mixin.py +++ b/napalm_openwrt/lldp_mixin.py @@ -14,12 +14,39 @@ from __future__ import annotations from typing import Any +#: 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 + class OpenWrtLLDPMixin: """Mixin providing LLDP NAPALM getters.""" def get_lldp_neighbors(self) -> dict[str, list[dict[str, Any]]]: - """Return LLDP neighbors (requires ``lldpd`` to be installed on the device). + """Return LLDP neighbors (requires ``lldpd`` installed and running on the device). Uses ``lldpctl -f keyvalue`` output:: @@ -33,67 +60,17 @@ class OpenWrtLLDPMixin: ) return neighbors - def _lldpd_fix_interface(self) -> None: - """Ensure lldpd UCI config uses the actual management interface. - - Detects the interface carrying the default route (e.g. br-lan.10 on a - VLAN trunk) and replaces any stale/wrong interface entry in the lldpd - UCI config. Idempotent — only writes if the config needs updating. - """ - mgmt_iface = self._send_command( - "ip route show default 2>/dev/null | head -1 | grep -oE 'dev [^ ]+' | awk '{print $2}'" - ).strip() - if not mgmt_iface: - mgmt_iface = "br-lan" - # LLDP is a L2 protocol — it must run on the bridge, not a VLAN subinterface. - # Strip .VID suffix so br-ap.10 → br-ap. - if "." in mgmt_iface: - mgmt_iface = mgmt_iface.rsplit(".", 1)[0] - - current = self._send_command("uci get lldpd.config.interface 2>/dev/null").strip() - if mgmt_iface in current: - return # already correct - - # Reset the interface list to just the management interface - self._send_command( - "uci delete lldpd.config.interface 2>/dev/null; " - f"uci add_list lldpd.config.interface='{mgmt_iface}' 2>/dev/null; " - "uci commit lldpd 2>/dev/null; " - "/etc/init.d/lldpd restart 2>/dev/null" - ) - def _get_lldp_table(self) -> list[dict[str, Any]]: """Parse ``lldpctl -f keyvalue`` into a list of row dicts. - Ensures ``lldpd`` is enabled and running before querying; if it was - not already running the daemon needs time to discover neighbors so - the first call after a fresh install will return an empty list. + Reads only: lldpd is neither started nor reconfigured here. Installing, + starting and configuring it are the caller's (``ensure_package``, + ``manage_service``). """ - # Ensure lldpd is running on the correct management interface - self._send_command( - "pgrep lldpd >/dev/null 2>&1 || " - "(/etc/init.d/lldpd enable 2>/dev/null; /etc/init.d/lldpd start 2>/dev/null)" - ) - self._lldpd_fix_interface() output = self._send_command("lldpctl -f keyvalue") rows: list[dict[str, Any]] = [] - # Group by local interface prefix: lldp..* - entries: dict[str, dict[str, str]] = {} - for line in output.splitlines(): - line_s = line.strip() - if "=" not in line_s: - continue - key, _, value = line_s.partition("=") - parts = key.split(".") - # parts: ['lldp', '', , , ...] - if len(parts) < 3 or parts[0] != "lldp": - continue - iface = parts[1] - subkey = ".".join(parts[2:]) - entries.setdefault(iface, {})[subkey] = value - - for iface, data in entries.items(): + for iface, data in _keyvalue_neighbours(output): rows.append( { "local_port": iface, diff --git a/napalm_openwrt/openwrt.py b/napalm_openwrt/openwrt.py index e08864d..f489e76 100644 --- a/napalm_openwrt/openwrt.py +++ b/napalm_openwrt/openwrt.py @@ -111,8 +111,8 @@ class OpenWrtDriver( self.timeout = timeout self.device: ConnectHandler | None = None - if optional_args is None: - optional_args = {} + # A copy: the caller's dict stays as it was. + optional_args = dict(optional_args or {}) self.port = optional_args.pop("port", 22) self.netmiko_optional_args = netmiko_args(optional_args) diff --git a/napalm_openwrt/system_mixin.py b/napalm_openwrt/system_mixin.py index 63b0b9b..7b48943 100644 --- a/napalm_openwrt/system_mixin.py +++ b/napalm_openwrt/system_mixin.py @@ -23,6 +23,8 @@ _RC_MARKER = "__OWRT_RC=" _RC_RE = re.compile(rf"^{_RC_MARKER}(\d+)\s*$", re.MULTILINE) #: What apk prints when its index is not in RAM (after a reboot). _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" def _split_status(raw: str) -> tuple[str, int | None]: @@ -32,6 +34,49 @@ def _split_status(raw: str) -> tuple[str, int | None]: return output, int(statuses[-1]) if statuses else None +def _status_result(raw: str, command: str) -> dict[str, Any]: + """``{"success", "output"}`` from what a command marked with ``_RC_MARKER`` printed. + + Only the exit status decides; output without a status is no success. + """ + output, status = _split_status(raw) + if status is None: + return {"success": False, "output": output or "No exit status came back from the device."} + if status: + return {"success": False, "output": output or f"{command} exited with status {status}."} + return {"success": True, "output": output} + + +def _cpu_counters(line: str) -> tuple[int, int]: + """``(idle, total)`` jiffies of a ``cpu`` line. + + The total counts user, nice, system, idle, iowait, irq and softirq. + """ + fields = [int(x) for x in line.split()[1:8]] + if len(fields) < 7: + raise ValueError(f"not a cpu line: {line!r}") + return fields[3], sum(fields) + + +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. + """ + 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 + elapsed = total2 - total1 + if elapsed <= 0: + return 0.0 + return (1 - (idle2 - idle1) / elapsed) * 100 + + class OpenWrtSystemMixin: """Mixin providing system-level NAPALM getters. @@ -41,21 +86,13 @@ class OpenWrtSystemMixin: def get_environment(self) -> dict[str, Any]: """Return device environment data (CPU, memory). - CPU usage from ``/proc/stat`` (two samples 1 second apart via ``awk``). + 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``. """ - cpu_out = self._send_command( - "awk '/^cpu /{idle1=$5; total1=$2+$3+$4+$5+$6+$7+$8} " - "END{print (1-(idle1/total1))*100}' /proc/stat" - ) + cpu_pct = _cpu_usage_percent(self._send_command(_CPU_SAMPLES)) mem_out = self._send_command("cat /proc/meminfo") - cpu_pct = 0.0 - try: - cpu_pct = float(cpu_out.strip()) - except (ValueError, AttributeError): - pass - mem_total = 0 mem_available = 0 for line in mem_out.splitlines(): @@ -389,15 +426,19 @@ class OpenWrtSystemMixin: return result def manage_service(self, name: str, action: str) -> dict[str, Any]: - """Execute a lifecycle action (start/stop/restart/enable/disable) on a service.""" + """Execute a lifecycle action (start/stop/restart/enable/disable) on a service. + + Only the init script's exit status decides ``success``; a missing script + or a failed action comes back with what the device printed. + """ import re as _re if not _re.match(r"^[a-zA-Z0-9_\-]+$", name): raise ValueError(f"Invalid service name: {name!r}") if action not in ("start", "stop", "restart", "enable", "disable"): raise ValueError(f"Invalid action: {action!r}") - output = self._send_command(f"/etc/init.d/{name} {action} 2>&1") - return {"success": True, "output": output} + command = f"/etc/init.d/{name} {action}" + return _status_result(self._send_command(f"{command} 2>&1; echo {_RC_MARKER}$?"), command) def get_available_updates(self) -> list[dict[str, Any]]: """Return list of upgradable packages from the local package manager cache. @@ -463,7 +504,10 @@ class OpenWrtSystemMixin: return {"success": status == 0, "output": output} def apply_updates(self, packages: list[str]) -> dict[str, Any]: - """Upgrade the given packages using the device's package manager.""" + """Upgrade the given packages using the device's package manager. + + Only the package manager's exit status decides ``success``. + """ import re as _re for pkg in packages: @@ -472,11 +516,18 @@ class OpenWrtSystemMixin: pm = self._pm_type() pkg_args = " ".join(packages) if pm == "apk": - cmd = f"apk upgrade {pkg_args} 2>&1" + cmd = f"apk upgrade {pkg_args}" else: - cmd = f"opkg upgrade {pkg_args} 2>&1" - output = self._send_command(cmd) - return {"success": True, "output": output} + cmd = f"opkg upgrade {pkg_args}" + output, status = _split_status(self._send_command(f"{cmd} 2>&1; echo {_RC_MARKER}$?")) + if status == 0: + return {"success": True, "output": output} + error = ( + f"{cmd.strip()} exited with status {status}" + if status is not None + else "No exit status came back from the device." + ) + return {"success": False, "output": output, "error": error} # ------------------------------------------------------------------ # NTP diff --git a/tests/unit/test_driver.py b/tests/unit/test_driver.py index 20fa1f4..8b694c6 100644 --- a/tests/unit/test_driver.py +++ b/tests/unit/test_driver.py @@ -336,6 +336,91 @@ class TestGetLldpNeighbors: assert result["eth0"][0]["port"] == "ether1" +# 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 +# ``alias`` and then ``via``, and the same key may repeat inside one neighbour +# (one ``chassis.mgmt-ip`` per address). Not recorded from a device. +LLDPCTL_KV_TWO_ON_ONE_PORT = """\ +lldp.lan1.via=LLDP +lldp.lan1.rid=1 +lldp.lan1.age=0 day, 00:10:00 +lldp.lan1.chassis.mac=00:11:22:33:44:01 +lldp.lan1.chassis.name=desk-phone +lldp.lan1.chassis.mgmt-ip=10.0.0.21 +lldp.lan1.chassis.mgmt-ip=fe80::211:22ff:fe33:4401 +lldp.lan1.port.ifname=lan +lldp.lan1.port.descr=phone uplink +lldp.lan1.alias=desk +lldp.lan1.via=LLDP +lldp.lan1.rid=2 +lldp.lan1.age=0 day, 00:09:00 +lldp.lan1.chassis.mac=00:11:22:33:44:02 +lldp.lan1.chassis.name=desk-pc +lldp.lan1.port.ifname=eno1 +lldp.eth0.via=LLDP +lldp.eth0.rid=3 +lldp.eth0.chassis.mac=00:aa:bb:cc:dd:ee +lldp.eth0.chassis.name=core-router +lldp.eth0.port.ifname=ether1 +""" + + +class TestLldpGettersOnlyRead: + """Reading the neighbours neither starts lldpd nor rewrites its configuration (#8).""" + + def _answer(self, driver) -> list: + sent: list = [] + + def send(cmd, **kw): + sent.append(cmd) + # A default route on a VLAN of another bridge: the old code rewrote + # lldpd's interface list for it and restarted the daemon. + if "ip route" in cmd: + return "br-ap" + if "uci get lldpd" in cmd: + return "br-lan" + return LLDPCTL_KV + + driver._send_command = send + return sent + + @pytest.mark.parametrize("getter", ["get_lldp_neighbors", "get_lldp_neighbors_detail"]) + def test_only_lldpctl_is_asked(self, driver, getter): + sent = self._answer(driver) + + getattr(driver, getter)() + + assert sent == ["lldpctl -f keyvalue"] + + +class TestLldpSeveralNeighboursOnOnePort: + """Each neighbour on a port is its own entry; none is lost (#9).""" + + def test_both_neighbours_on_the_port_are_reported(self, driver): + driver._send_command = lambda cmd, **kw: LLDPCTL_KV_TWO_ON_ONE_PORT + + result = driver.get_lldp_neighbors() + + assert result["lan1"] == [ + {"hostname": "desk-phone", "port": "lan"}, + {"hostname": "desk-pc", "port": "eno1"}, + ] + assert result["eth0"] == [{"hostname": "core-router", "port": "ether1"}] + + def test_a_neighbour_keeps_only_its_own_fields(self, driver): + driver._send_command = lambda cmd, **kw: LLDPCTL_KV_TWO_ON_ONE_PORT + + pc = driver.get_lldp_neighbors_detail("lan1")["lan1"][1] + + assert pc["remote_chassis_id"] == "00:11:22:33:44:02" + assert pc["remote_port_description"] == "" + + def test_a_repeated_key_inside_one_neighbour_is_no_new_neighbour(self, driver): + driver._send_command = lambda cmd, **kw: LLDPCTL_KV_TWO_ON_ONE_PORT + + assert len(driver.get_lldp_neighbors_detail("lan1")["lan1"]) == 2 + + BRIDGE_VLAN_SHOW = """\ port vlan-id eth0 1 PVID Egress Untagged @@ -1940,3 +2025,126 @@ class TestGetSystemConfigBridgeStp: # Nothing to have an opinion about — distinct from "STP is off". driver._send_command = _system_send(network_out="network.lan=interface\n") assert driver.get_system_config()["bridge_stp"] is None + + +class TestOptionalArgs: + def test_the_callers_optional_args_are_left_as_they_were(self): + optional_args = {"port": 2222, "conn_timeout": 15} + + drv = OpenWrtDriver("192.168.1.1", "root", "", optional_args=optional_args) + + assert drv.port == 2222 + assert optional_args == {"port": 2222, "conn_timeout": 15} + + +class TestManageService: + """Only the init script's exit status decides whether an action succeeded (#3).""" + + def _answer(self, driver, reply: str) -> list: + sent: list = [] + + def send(cmd, **kw): + sent.append(cmd) + return reply + + driver._send_command = send + return sent + + def test_a_clean_exit_is_a_success(self, driver): + sent = self._answer(driver, "__OWRT_RC=0\n") + + assert driver.manage_service("dnsmasq", "restart") == {"success": True, "output": ""} + assert sent[0].startswith("/etc/init.d/dnsmasq restart 2>&1") + + def test_a_failed_action_is_no_success(self, driver): + self._answer(driver, "Command failed: Not found\n__OWRT_RC=1\n") + + result = driver.manage_service("dnsmasq", "start") + + assert result == {"success": False, "output": "Command failed: Not found"} + + def test_a_missing_init_script_is_no_success(self, driver): + self._answer(driver, "ash: /etc/init.d/nope: not found\n__OWRT_RC=127\n") + + result = driver.manage_service("nope", "start") + + assert result["success"] is False + assert "not found" in result["output"] + + def test_a_silent_failure_names_the_status(self, driver): + self._answer(driver, "__OWRT_RC=1\n") + + result = driver.manage_service("lldpd", "enable") + + assert result["success"] is False + assert "status 1" in result["output"] + + def test_output_without_a_status_is_no_success(self, driver): + self._answer(driver, "") + + assert driver.manage_service("dnsmasq", "stop")["success"] is False + + def test_an_invalid_name_is_refused_before_anything_is_sent(self, driver): + sent = self._answer(driver, "__OWRT_RC=0\n") + + with pytest.raises(ValueError): + driver.manage_service("x; reboot", "start") + assert sent == [] + + +# Busy 15 % on average since boot, 90 % in the second between the two reads. +PROC_STAT_CPU_TWICE = """\ +cpu 1000 0 500 8500 0 0 0 0 0 0 +cpu 1090 0 500 8510 0 0 0 0 0 0 +""" + +MEMINFO = """\ +MemTotal: 124608 kB +MemFree: 43204 kB +MemAvailable: 62000 kB +""" + + +class TestGetEnvironmentCpu: + """CPU usage is the second between two reads, not the average since boot (#10).""" + + def _answer(self, driver, cpu: str) -> list: + sent: list = [] + + def send(cmd, **kw): + sent.append(cmd) + return MEMINFO if "meminfo" in cmd else cpu + + driver._send_command = send + return sent + + def test_usage_is_the_difference_of_two_reads(self, driver): + self._answer(driver, PROC_STAT_CPU_TWICE) + + assert driver.get_environment()["cpu"] == {0: {"%usage": 90.0}} + + def test_the_two_reads_are_a_second_apart(self, driver): + sent = self._answer(driver, PROC_STAT_CPU_TWICE) + + driver.get_environment() + + command = next(cmd for cmd in sent if "/proc/stat" in cmd) + assert command.count("/proc/stat") == 2 + assert "sleep 1" in command + + def test_counters_that_did_not_move_are_zero(self, driver): + self._answer(driver, "cpu 1000 0 500 8500 0 0 0\ncpu 1000 0 500 8500 0 0 0\n") + + assert driver.get_environment()["cpu"][0]["%usage"] == 0.0 + + def test_a_single_read_is_not_taken_for_usage(self, driver): + self._answer(driver, "cpu 1000 0 500 8500 0 0 0\n") + + assert driver.get_environment()["cpu"][0]["%usage"] == 0.0 + + def test_memory_is_still_read(self, driver): + self._answer(driver, PROC_STAT_CPU_TWICE) + + memory = driver.get_environment()["memory"] + + assert memory == {"available_ram": 62000 * 1024, "used_ram": (124608 - 62000) * 1024} diff --git a/tests/unit/test_updates.py b/tests/unit/test_updates.py index b86b3fb..98d3558 100644 --- a/tests/unit/test_updates.py +++ b/tests/unit/test_updates.py @@ -111,3 +111,54 @@ class TestRefresh: result = driver.refresh_available_updates() assert result == {"success": False, "output": "ERROR: network unreachable"} + + +class TestApplyUpdates: + """Only the package manager's exit status decides whether an upgrade succeeded (#11).""" + + def test_apk_upgrade_that_worked(self, driver): + sent = _answer( + driver, "apk", "(1/1) Upgrading dnsmasq (2.90-r4 -> 2.90-r5)\nOK\n__OWRT_RC=0\n" + ) + + result = driver.apply_updates(["dnsmasq"]) + + assert result == { + "success": True, + "output": "(1/1) Upgrading dnsmasq (2.90-r4 -> 2.90-r5)\nOK", + } + assert sent[-1].startswith("apk upgrade dnsmasq 2>&1") + + def test_apk_upgrade_that_failed_is_no_success(self, driver): + _answer( + driver, + "apk", + "ERROR: unable to select packages:\n nope (no such package)\n__OWRT_RC=1\n", + ) + + result = driver.apply_updates(["nope"]) + + assert result["success"] is False + assert "unable to select packages" in result["output"] + assert "status 1" in result["error"] + + def test_opkg_upgrade_that_failed_is_no_success(self, driver): + sent = _answer( + driver, + "opkg", + " * opkg_download: Failed to download\nCollected errors:\n__OWRT_RC=255\n", + ) + + result = driver.apply_updates(["dnsmasq"]) + + assert result["success"] is False + assert "status 255" in result["error"] + assert sent[-1].startswith("opkg upgrade dnsmasq 2>&1") + + def test_output_without_a_status_is_no_success(self, driver): + _answer(driver, "opkg", "") + + result = driver.apply_updates(["dnsmasq"]) + + assert result["success"] is False + assert result["error"]