Merge remote-tracking branch 'origin/main' into feat/lldp-agent-setup

This commit is contained in:
Christian Manivong committed 2026-11-02 00:31:35 +01:00
commit 1e988c87f4
7 files changed
+383 -78

No files matched your search

+18
View File
@@ -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
+2 -2
View File
@@ -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
+32 -55
View File
@@ -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', '<iface>', <category>, <field>, ...]
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.<iface>.*
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', '<iface>', <category>, <field>, ...]
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,
+2 -2
View File
@@ -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)
+70 -19
View File
@@ -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
+208
View File
@@ -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}
+51
View File
@@ -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"]