fix(lldp): shared lldpctl parser; raise on failed LLDP and environment reads #30

Merged
christianmanivong merged 4 commits from fix/lldp-keyvalue into main 2026-11-02 11:04:12 +00:00
7 changed files with 221 additions and 106 deletions

No files matched your search

+18 -1
View File
@@ -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).
+3 -3
View File
@@ -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
+26 -70
View File
@@ -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', '<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
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: ...
+24 -22
View File
@@ -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": {},
+1 -2
View File
@@ -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",
-1
View File
@@ -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",
+149 -7
View File
@@ -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)