From 4427be35ccc5643b995ab3aa67d227a18c0f4199 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Mon, 2 Nov 2026 08:42:10 +0100 Subject: [PATCH 1/2] feat(lldp): parse lldpctl keyvalue into one row per neighbour napalm-linux, napalm-openwrt and napalm-proxmox each parsed lldpd's neighbours on their own, and the copies grouped lines by interface (two neighbours on one port merged), cut the interface name at its first dot and looked for chassis.id.value, a key lldpd never prints. The parse lives here once now: neighbours are split at their via line, the interface name runs up to the neighbour's first field, ids are read under the type lldpd prints them with, and a failed lldpctl raises. The rows project into NAPALM's two LLDP shapes with lldp_neighbors and lldp_neighbors_detail, the projection part of #10. Refs #10 --- CHANGELOG.md | 12 ++ README.md | 10 ++ napalm_device_types/__init__.py | 7 + napalm_device_types/lldp.py | 79 ++++++++ napalm_device_types/lldpctl.py | 204 +++++++++++++++++++++ tests/test_lldp_rows.py | 113 ++++++++++++ tests/test_lldpctl.py | 308 ++++++++++++++++++++++++++++++++ 7 files changed, 733 insertions(+) create mode 100644 napalm_device_types/lldp.py create mode 100644 napalm_device_types/lldpctl.py create mode 100644 tests/test_lldp_rows.py create mode 100644 tests/test_lldpctl.py diff --git a/CHANGELOG.md b/CHANGELOG.md index aa6e349..22258d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,18 @@ recorded here; their history is the git log. ## [Unreleased] +### Added +- `parse_lldpctl_keyvalue(output)` and `LLDPCTL_KEYVALUE_COMMAND`: lldpd's neighbours + (`lldpctl -f keyvalue`) as one `LldpNeighborRow` per neighbour, for every driver of a + host that runs lldpd. Several neighbours on one port (a phone and the PC behind it, an + unmanaged switch) stay apart, an interface name with dots (`eth0.1`) stays whole, the + chassis and port ids are read whatever their type (MAC, address, interface name, local + id), with management addresses and capabilities. A failed lldpctl (lldpd not running, + lldpctl missing) raises instead of reading as no neighbours. +- `lldp_neighbors(rows)` and `lldp_neighbors_detail(rows, interface="")`: NAPALM's + `get_lldp_neighbors` and `get_lldp_neighbors_detail` from those rows, so a driver no + longer builds the two shapes itself. + ### Fixed - `DNF_SECURITY_COMMAND` reads the cached metadata only (`dnf --cacheonly`), as `APT_UPGRADABLE_COMMAND` reads apt's local index (#76). With an expired cache dnf diff --git a/README.md b/README.md index ea8ba97..09e5158 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,16 @@ without `ss` is read with `netstat -lntup` (OpenWrt's busybox, old net-tools); o cgroup names the procd service (`/services//`). A host with neither raises `ListeningSocketsUnavailable`. +LLDP neighbours are rows: `LldpNeighborRow` is one neighbour as its local port heard it +(chassis and port id with their type, name, description, management addresses, +capabilities in NAPALM's names), and `lldp_neighbors(rows)` / `lldp_neighbors_detail(rows, +interface)` are NAPALM's two getters projected from them, a port with two neighbours +keeping both. A driver for a host that runs lldpd sends `LLDPCTL_KEYVALUE_COMMAND` and +hands its output to `parse_lldpctl_keyvalue`: one row per neighbour block, an interface +name with dots (`eth0.1`) kept whole, ids read under the type lldpd prints them with +(`chassis.mac`, `port.local`, ...). When lldpctl fails (lldpd not running, no `lldpctl`) +the parse raises instead of reading as no neighbours. + `HostFirewallMixin` (`get_host_firewall`) reads a Linux host's own netfilter rules the same way: `nft -j list ruleset`, with the tables iptables-nft manages taken from `iptables-save` instead, because nft shows their extensions (`-m conntrack`, `-m set`) only as an opaque `xt`. diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 68f28d1..c4afbb5 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -135,6 +135,8 @@ from napalm_device_types.listening import ( ListeningSocketsUnavailable, parse_listening_sockets, ) +from napalm_device_types.lldp import LldpNeighborRow, lldp_neighbors, lldp_neighbors_detail +from napalm_device_types.lldpctl import LLDPCTL_KEYVALUE_COMMAND, parse_lldpctl_keyvalue from napalm_device_types.local_accounts import ( LocalAccountChangeDict, LocalAccountDict, @@ -348,6 +350,11 @@ __all__ = [ "ListeningSocketsMixin", "ListeningSocketsUnavailable", "parse_listening_sockets", + "LLDPCTL_KEYVALUE_COMMAND", + "LldpNeighborRow", + "lldp_neighbors", + "lldp_neighbors_detail", + "parse_lldpctl_keyvalue", "LocalAccountsMixin", "LocalAccountDict", "LocalAccountChangeDict", diff --git a/napalm_device_types/lldp.py b/napalm_device_types/lldp.py new file mode 100644 index 0000000..e796bf4 --- /dev/null +++ b/napalm_device_types/lldp.py @@ -0,0 +1,79 @@ +"""LLDP neighbours as rows, and the two shapes NAPALM asks for. + +A driver reads its neighbours one row per neighbour -- from ``lldpctl`` +(:func:`~napalm_device_types.lldpctl.parse_lldpctl_keyvalue`), an API or a CLI +-- and ``get_lldp_neighbors`` and ``get_lldp_neighbors_detail`` are the same +projection of those rows for every driver. A port with several neighbours (a +phone and the PC behind it, an unmanaged switch) is several rows, and stays +several entries in both shapes. +""" + +from __future__ import annotations + +from collections.abc import Iterable +from typing import TypedDict + +from napalm.base.models import LLDPNeighborDetailDict, LLDPNeighborDict + + +class LldpNeighborRow(TypedDict): + """One LLDP neighbour, as the local port heard it. + + ``chassis_id_type`` and ``port_id_type`` name what the id is: ``mac``, + ``ip``, ``ifname``, ``ifalias``, ``local`` or ``unhandled`` (an id type + lldpd does not decode), ``""`` when the neighbour sent no id. + ``capabilities`` and ``enabled_capabilities`` use NAPALM's names + (``bridge``, ``router``, ``wlan-access-point``, ``telephone``, ...). + """ + + local_port: str + chassis_id: str + chassis_id_type: str + port_id: str + port_id_type: str + port_description: str + system_name: str + system_description: str + management_addresses: list[str] + capabilities: list[str] + enabled_capabilities: list[str] + + +def lldp_neighbors(rows: Iterable[LldpNeighborRow]) -> dict[str, list[LLDPNeighborDict]]: + """``get_lldp_neighbors``: per local port, every neighbour's name and port.""" + neighbors: dict[str, list[LLDPNeighborDict]] = {} + for row in rows: + neighbors.setdefault(row["local_port"], []).append( + {"hostname": row["system_name"], "port": row["port_id"]} + ) + return neighbors + + +def lldp_neighbors_detail( + rows: Iterable[LldpNeighborRow], interface: str = "" +) -> dict[str, list[LLDPNeighborDetailDict]]: + """``get_lldp_neighbors_detail``: per local port, every neighbour in full. + + With ``interface``, that port only. ``parent_interface`` stays empty: a row + does not know which aggregate its port belongs to. + """ + details: dict[str, list[LLDPNeighborDetailDict]] = {} + for row in rows: + 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["chassis_id"], + "remote_system_name": row["system_name"], + "remote_system_description": row["system_description"], + "remote_system_capab": list(row["capabilities"]), + "remote_system_enable_capab": list(row["enabled_capabilities"]), + } + ) + return details + + +__all__ = ["LldpNeighborRow", "lldp_neighbors", "lldp_neighbors_detail"] diff --git a/napalm_device_types/lldpctl.py b/napalm_device_types/lldpctl.py new file mode 100644 index 0000000..09b644e --- /dev/null +++ b/napalm_device_types/lldpctl.py @@ -0,0 +1,204 @@ +"""``lldpctl -f keyvalue``: lldpd's neighbours, one row each. + +Every driver for a host that runs lldpd reads its neighbours the same way, so +the command and its parse live here once and a driver only carries the command +across. lldpd's keyvalue writer (``src/client/kv_writer.c``) prints one +``key=value`` line per field, the key being the field's path joined by dots +(a newline inside a value becomes a space):: + + lldp.eth0.1.via=LLDP + lldp.eth0.1.chassis.mac=00:11:22:33:44:01 + lldp.eth0.1.chassis.Tel.enabled=on + lldp.eth0.1.port.local=gi1/0/7 + +**A neighbour is a block, not a port.** Every neighbour on a port prints the +same keys, so grouping the lines by interface merges them. A neighbour opens +with ``via`` (after the local interface's ``alias``, when it has one); the next +``via`` on the same port is the next neighbour. + +**An interface name may hold dots** (``eth0.1``, ``br-lan.10``). It is +everything between ``lldp.`` and the neighbour's first field, never the second +dotted part of the key. + +**An id is printed under its type**, ``chassis.=`` and ``port.=``, +with lldpd's names for the type (``mac``, ``ip``, ``ifname``, ``ifalias``, +``local``, ``unhandled``); there is no ``chassis.id`` key. + +**A failed read raises.** lldpctl exits non-zero when it cannot reach lldpd; +:data:`LLDPCTL_KEYVALUE_COMMAND` brings that status and lldpctl's message back, +and the parse raises on it instead of reading it as no neighbours. Output that +carries no exit status (a driver that runs plain ``lldpctl -f keyvalue``) raises +when it holds text but not a single neighbour line, as a shell's ``lldpctl: not +found`` does. +""" + +from __future__ import annotations + +import re + +from napalm_device_types.lldp import LldpNeighborRow + +_RC = "__LLDPCTL_RC" + +#: One line, POSIX ``sh``, read-only. Without arguments lldpctl shows the +#: neighbours in detail; its error text and exit status come back with them. +LLDPCTL_KEYVALUE_COMMAND = f"lldpctl -f keyvalue 2>&1; echo {_RC}=$?" + +_RC_RE = re.compile(rf"^{_RC}=(\d+)$") +_PREFIX = "lldp." +#: The fields a neighbour opens with: the local interface's alias, then ``via``. +_OPENERS = frozenset({"alias", "via"}) +#: The first part after the interface name of every key lldpd prints for a +#: neighbour (``src/client/display.c``, ``display_interface``). +_CATEGORIES = _OPENERS | { + "rid", + "age", + "status", + "chassis", + "port", + "ttl", + "vlan", + "ppvid", + "pi", + "lldp-med", + "unknown-tlvs", +} +#: lldpd's id types (``src/lib/atoms/chassis.c``, ``port.c``), in the order read. +_CHASSIS_ID_TYPES = ("mac", "local", "ip", "ifname", "ifalias", "unhandled") +_PORT_ID_TYPES = ("ifname", "mac", "local", "ip", "ifalias", "unhandled") +#: lldpd's capability symbols in NAPALM's names; one NAPALM lacks is lowercased. +_CAPABILITIES = { + "Other": "other", + "Repeater": "repeater", + "Bridge": "bridge", + "Router": "router", + "Wlan": "wlan-access-point", + "Tel": "telephone", + "Docsis": "docsis-cable-device", + "Station": "station", +} +_SWITCH = {"on": True, "off": False} + +_Fields = dict[str, list[str]] + + +def parse_lldpctl_keyvalue(output: str) -> list[LldpNeighborRow]: + """One row per neighbour, in the order lldpctl listed them. + + :raises ValueError: when lldpctl failed -- a non-zero exit status, or text + without a single neighbour line and no status at all. + """ + return [_row(port, fields) for port, fields in _neighbours(_pairs(output))] + + +def _pairs(output: str) -> list[tuple[str, str]]: + """``(key without "lldp.", value)`` of every neighbour line; raises on a failed run.""" + pairs: list[tuple[str, str]] = [] + other: list[str] = [] + status: int | None = None + for line in output.splitlines(): + line = line.strip() + key, sep, value = line.partition("=") + if _RC_RE.match(line): + status = int(value) + elif sep and key.startswith(_PREFIX): + pairs.append((key[len(_PREFIX) :], value)) + elif line: + other.append(line) + _raise_on_failure(status, other, bool(pairs)) + return pairs + + +def _raise_on_failure(status: int | None, other: list[str], listed: bool) -> None: + """A non-zero status, or text without a status and without a neighbour line.""" + if status or (status is None and other and not listed): + said = " ".join(other)[:200] or f"exit status {status}" + raise ValueError(f"lldpctl did not list the neighbours: {said}") + + +def _neighbours(pairs: list[tuple[str, str]]) -> list[tuple[str, _Fields]]: + """Split the lines into neighbours: ``(local interface, {field: [values]})``.""" + neighbours: list[tuple[str, _Fields]] = [] + port: str | None = None + fields: _Fields = {} + for key, value in pairs: + split = _split(key, port) + if split is None: + continue + name, field = split + if name != port or field == "alias" or (field == "via" and "via" in fields): + port, fields = name, {} + neighbours.append((port, fields)) + fields.setdefault(field, []).append(value) + return neighbours + + +def _split(key: str, port: str | None) -> tuple[str, str] | None: + """``(interface, field)`` of a key, or None when it is no neighbour field. + + ``via`` and ``alias`` end their key, so they name the interface exactly; + the keys after them continue that interface. Only a key that does neither + ends its interface name at the first known field. + """ + head, _, last = key.rpartition(".") + if head and last in _OPENERS: + return head, last + if port is not None and key.startswith(port + "."): + field = key[len(port) + 1 :] + if field.split(".", 1)[0] in _CATEGORIES: + return port, field + parts = key.split(".") + for i in range(1, len(parts)): + if parts[i] in _CATEGORIES: + return ".".join(parts[:i]), ".".join(parts[i:]) + return None + + +def _row(port: str, fields: _Fields) -> LldpNeighborRow: + chassis_type, chassis_id = _id(fields, "chassis", _CHASSIS_ID_TYPES) + port_type, port_id = _id(fields, "port", _PORT_ID_TYPES) + capabilities, enabled = _capabilities(fields) + return { + "local_port": port, + "chassis_id": chassis_id, + "chassis_id_type": chassis_type, + "port_id": port_id, + "port_id_type": port_type, + "port_description": _first(fields, "port.descr"), + "system_name": _first(fields, "chassis.name"), + "system_description": _first(fields, "chassis.descr"), + "management_addresses": list(fields.get("chassis.mgmt-ip", [])), + "capabilities": capabilities, + "enabled_capabilities": enabled, + } + + +def _first(fields: _Fields, field: str) -> str: + return fields.get(field, [""])[0] + + +def _id(fields: _Fields, category: str, types: tuple[str, ...]) -> tuple[str, str]: + """``(type, id)`` of the chassis or the port; ``("", "")`` when none was sent.""" + for kind in types: + if f"{category}.{kind}" in fields: + return kind, _first(fields, f"{category}.{kind}") + return "", "" + + +def _capabilities(fields: _Fields) -> tuple[list[str], list[str]]: + """``chassis..enabled=on|off``: the capabilities offered, and those enabled.""" + offered: list[str] = [] + enabled: list[str] = [] + for field, values in fields.items(): + parts = field.split(".") + switch = _SWITCH.get(values[0]) + if len(parts) != 3 or parts[0] != "chassis" or parts[2] != "enabled" or switch is None: + continue + name = _CAPABILITIES.get(parts[1], parts[1].lower()) + offered.append(name) + if switch: + enabled.append(name) + return offered, enabled + + +__all__ = ["LLDPCTL_KEYVALUE_COMMAND", "parse_lldpctl_keyvalue"] diff --git a/tests/test_lldp_rows.py b/tests/test_lldp_rows.py new file mode 100644 index 0000000..5fe25c2 --- /dev/null +++ b/tests/test_lldp_rows.py @@ -0,0 +1,113 @@ +"""LLDP rows projected into NAPALM's ``get_lldp_neighbors`` and ``get_lldp_neighbors_detail``. + +A driver reads its neighbours into :class:`LldpNeighborRow` (from ``lldpctl``, +an API, a CLI) and the two NAPALM shapes come from those rows the same way for +every driver (NAPALM/napalm-device-types#10). +""" + +from __future__ import annotations + +from typing import get_type_hints + +from napalm_device_types import LldpNeighborRow, lldp_neighbors, lldp_neighbors_detail + + +def _row(local_port: str, name: str, **fields: object) -> LldpNeighborRow: + row: LldpNeighborRow = { + "local_port": local_port, + "chassis_id": "", + "chassis_id_type": "", + "port_id": "", + "port_id_type": "", + "port_description": "", + "system_name": name, + "system_description": "", + "management_addresses": [], + "capabilities": [], + "enabled_capabilities": [], + } + row.update(fields) # type: ignore[typeddict-item] + return row + + +PHONE = _row( + "eth0.1", + "desk-phone", + chassis_id="00:11:22:33:44:01", + chassis_id_type="mac", + port_id="00:11:22:33:44:01", + port_id_type="mac", + port_description="WAN", + system_description="SIP phone", + capabilities=["bridge", "telephone"], + enabled_capabilities=["telephone"], +) +PC = _row("eth0.1", "desk-pc", port_id="eno1", port_id_type="ifname") +SWITCH = _row("eth1", "access-sw", port_id="gi1/0/7", port_id_type="local") + + +def test_a_row_names_its_fields(): + assert set(get_type_hints(LldpNeighborRow)) == { + "local_port", + "chassis_id", + "chassis_id_type", + "port_id", + "port_id_type", + "port_description", + "system_name", + "system_description", + "management_addresses", + "capabilities", + "enabled_capabilities", + } + + +class TestNeighbors: + def test_every_neighbour_of_a_port_is_listed(self): + assert lldp_neighbors([PHONE, PC, SWITCH]) == { + "eth0.1": [ + {"hostname": "desk-phone", "port": "00:11:22:33:44:01"}, + {"hostname": "desk-pc", "port": "eno1"}, + ], + "eth1": [{"hostname": "access-sw", "port": "gi1/0/7"}], + } + + def test_no_rows_is_no_neighbour(self): + assert lldp_neighbors([]) == {} + + +class TestNeighborsDetail: + def test_every_field_napalm_names(self): + assert lldp_neighbors_detail([PHONE]) == { + "eth0.1": [ + { + "parent_interface": "", + "remote_port": "00:11:22:33:44:01", + "remote_port_description": "WAN", + "remote_chassis_id": "00:11:22:33:44:01", + "remote_system_name": "desk-phone", + "remote_system_description": "SIP phone", + "remote_system_capab": ["bridge", "telephone"], + "remote_system_enable_capab": ["telephone"], + } + ] + } + + def test_every_neighbour_of_a_port_is_listed(self): + detail = lldp_neighbors_detail([PHONE, PC, SWITCH]) + + assert [n["remote_system_name"] for n in detail["eth0.1"]] == ["desk-phone", "desk-pc"] + assert [n["remote_system_name"] for n in detail["eth1"]] == ["access-sw"] + + def test_one_interface_only(self): + assert list(lldp_neighbors_detail([PHONE, PC, SWITCH], "eth1")) == ["eth1"] + + def test_an_interface_without_neighbours_is_empty(self): + assert lldp_neighbors_detail([PHONE], "eth9") == {} + + def test_the_lists_are_the_rows_own_copies(self): + detail = lldp_neighbors_detail([PHONE]) + + detail["eth0.1"][0]["remote_system_capab"].append("router") + + assert PHONE["capabilities"] == ["bridge", "telephone"] diff --git a/tests/test_lldpctl.py b/tests/test_lldpctl.py new file mode 100644 index 0000000..8620b3e --- /dev/null +++ b/tests/test_lldpctl.py @@ -0,0 +1,308 @@ +"""``lldpctl -f keyvalue``: one row per LLDP neighbour, for every driver that reads lldpd. + +napalm-linux, napalm-openwrt and napalm-proxmox each parsed this output on their +own, and each copy grouped the lines by interface, so two neighbours on one port +merged (NAPALM/napalm-openwrt#9, NAPALM/napalm-linux#58), split ``eth0.1`` at its +dot (NAPALM/napalm-openwrt#26) and looked for ``chassis.id.value``, a key lldpd +never prints. The parse lives here once now. +""" + +from __future__ import annotations + +import pytest + +from napalm_device_types import LLDPCTL_KEYVALUE_COMMAND, parse_lldpctl_keyvalue + +# The recording napalm-openwrt's tests have used since the driver was written +# (tests/unit/test_driver.py, ``LLDPCTL_KV``): one neighbour on eth0. Its two +# ``chassis.cap.*`` lines are not lldpd's format (lldpd prints one +# ``chassis..enabled=on|off`` line per capability), so they yield none. +OPENWRT_ONE_NEIGHBOUR = """\ +lldp.eth0.via=LLDP +lldp.eth0.rid=1 +lldp.eth0.age=0 day, 01:23:45 +lldp.eth0.chassis.mac=00:aa:bb:cc:dd:ee +lldp.eth0.chassis.name=core-router +lldp.eth0.chassis.descr=RouterOS 7.x +lldp.eth0.chassis.mgmt-ip=10.0.0.1 +lldp.eth0.chassis.cap.available=Router, Bridge +lldp.eth0.chassis.cap.enabled=Router +lldp.eth0.port.ifname=ether1 +lldp.eth0.port.descr=uplink +""" + +# Laid out the way lldpd 1.0's keyvalue writer prints ``show neighbors details`` +# (src/client/display.c ``display_interface``, ``display_chassis``, +# ``display_port``, ``display_vlans``, ``display_med``; src/client/kv_writer.c): +# a neighbour opens with the local interface's optional ``alias`` and ``via``, +# an id is printed under its type (``chassis.mac``, ``port.local``), a +# capability as ``chassis..enabled``, a management address once per +# address. Not recorded from a device. +# +# On ``eth0.1`` (a VLAN interface, its name holds a dot) a phone and a PC behind +# an unmanaged switch; on ``eth1`` a switch that names its port by a local id and +# itself by an address. +TWO_ON_ONE_DOTTED_PORT = """\ +lldp.eth0.1.alias=desk +lldp.eth0.1.via=LLDP +lldp.eth0.1.rid=1 +lldp.eth0.1.age=0 day, 00:10:00 +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, firmware a=1 +lldp.eth0.1.chassis.mgmt-ip=10.0.0.21 +lldp.eth0.1.chassis.mgmt-iface=2 +lldp.eth0.1.chassis.mgmt-ip=fe80::211:22ff:fe33:4401 +lldp.eth0.1.chassis.mgmt-iface=2 +lldp.eth0.1.chassis.Bridge.enabled=off +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.eth0.1.port.ttl=120 +lldp.eth0.1.port.auto-negotiation.supported=yes +lldp.eth0.1.port.auto-negotiation.enabled=yes +lldp.eth0.1.port.auto-negotiation.100Base-TX.hd=yes +lldp.eth0.1.port.auto-negotiation.100Base-TX.fd=yes +lldp.eth0.1.port.auto-negotiation.current=100BaseTXFD - 2 pair category 5 UTP, full duplex mode +lldp.eth0.1.vlan.vlan-id=10 +lldp.eth0.1.vlan.pvid=yes +lldp.eth0.1.vlan=voice +lldp.eth0.1.lldp-med.device-type=Communication Device Endpoint (Class III) +lldp.eth0.1.lldp-med.Capabilities.available=yes +lldp.eth0.1.lldp-med.inventory.software=2.1.4 +lldp.eth0.1.alias=desk +lldp.eth0.1.via=LLDP +lldp.eth0.1.rid=2 +lldp.eth0.1.age=0 day, 00:09:00 +lldp.eth0.1.chassis.mac=00:11:22:33:44:02 +lldp.eth0.1.chassis.name=desk-pc +lldp.eth0.1.chassis.descr=Debian GNU/Linux 12 (bookworm) Linux 6.1.0-25-amd64 +lldp.eth0.1.chassis.Bridge.enabled=off +lldp.eth0.1.chassis.Router.enabled=off +lldp.eth0.1.chassis.Wlan.enabled=off +lldp.eth0.1.chassis.Station.enabled=on +lldp.eth0.1.port.ifname=eno1 +lldp.eth0.1.port.ttl=120 +lldp.eth0.1.unknown-tlvs.unknown-tlv.oui=00,80,C2 +lldp.eth0.1.unknown-tlvs.unknown-tlv.subtype=9 +lldp.eth0.1.unknown-tlvs.unknown-tlv.len=1 +lldp.eth0.1.unknown-tlvs.unknown-tlv=01 +lldp.eth1.via=LLDP +lldp.eth1.rid=3 +lldp.eth1.age=1 day, 02:00:00 +lldp.eth1.chassis.ip=192.0.2.7 +lldp.eth1.chassis.name=access-sw +lldp.eth1.chassis.Bridge.enabled=on +lldp.eth1.chassis.Router.enabled=off +lldp.eth1.chassis.CVLAN.enabled=on +lldp.eth1.port.local=gi1/0/7 +lldp.eth1.port.descr=GigabitEthernet1/0/7 +lldp.eth1.ppvid.supported=no +lldp.eth1.ppvid.enabled=no +lldp.eth1.pi=88cc +""" + + +def _rows(output: str = TWO_ON_ONE_DOTTED_PORT) -> list[dict[str, object]]: + return [dict(row) for row in parse_lldpctl_keyvalue(output)] + + +class TestOneRowPerNeighbour: + def test_the_openwrt_recording_is_one_neighbour_with_its_fields(self): + assert _rows(OPENWRT_ONE_NEIGHBOUR) == [ + { + "local_port": "eth0", + "chassis_id": "00:aa:bb:cc:dd:ee", + "chassis_id_type": "mac", + "port_id": "ether1", + "port_id_type": "ifname", + "port_description": "uplink", + "system_name": "core-router", + "system_description": "RouterOS 7.x", + "management_addresses": ["10.0.0.1"], + "capabilities": [], + "enabled_capabilities": [], + } + ] + + def test_two_neighbours_on_one_port_stay_apart(self): + rows = _rows() + + assert [(r["local_port"], r["system_name"]) for r in rows] == [ + ("eth0.1", "desk-phone"), + ("eth0.1", "desk-pc"), + ("eth1", "access-sw"), + ] + + def test_a_neighbour_keeps_only_its_own_fields(self): + pc = _rows()[1] + + assert pc["chassis_id"] == "00:11:22:33:44:02" + assert pc["port_description"] == "" + assert pc["management_addresses"] == [] + + def test_neighbours_without_alias_are_split_at_via(self): + output = OPENWRT_ONE_NEIGHBOUR + OPENWRT_ONE_NEIGHBOUR.replace("core-router", "edge") + + assert [r["system_name"] for r in _rows(output)] == ["core-router", "edge"] + + +class TestInterfaceName: + def test_a_dotted_interface_name_survives(self): + assert {r["local_port"] for r in _rows()} == {"eth0.1", "eth1"} + + def test_an_interface_named_like_a_field_survives(self): + output = ( + "lldp.vlan.100.via=LLDP\n" + "lldp.vlan.100.chassis.mac=00:aa:bb:cc:dd:01\n" + "lldp.vlan.100.port.ifname=port1\n" + ) + + (row,) = _rows(output) + + assert (row["local_port"], row["chassis_id"], row["port_id"]) == ( + "vlan.100", + "00:aa:bb:cc:dd:01", + "port1", + ) + + def test_without_via_the_name_ends_at_the_first_field(self): + output = "lldp.br-lan.10.chassis.name=sw\nlldp.br-lan.10.port.ifname=1\n" + + (row,) = _rows(output) + + assert (row["local_port"], row["system_name"], row["port_id"]) == ("br-lan.10", "sw", "1") + + +class TestIds: + def test_a_port_given_by_its_mac_is_read(self): + phone = _rows()[0] + + assert (phone["port_id"], phone["port_id_type"]) == ("00:11:22:33:44:01", "mac") + + def test_a_port_given_by_a_local_id_is_read(self): + switch = _rows()[2] + + assert (switch["port_id"], switch["port_id_type"]) == ("gi1/0/7", "local") + + def test_a_chassis_given_by_its_address_is_read(self): + switch = _rows()[2] + + assert (switch["chassis_id"], switch["chassis_id_type"]) == ("192.0.2.7", "ip") + + @pytest.mark.parametrize("kind", ["local", "ifname", "ifalias", "unhandled"]) + def test_every_id_type_lldpd_names_is_read(self, kind): + output = f"lldp.eth0.via=LLDP\nlldp.eth0.chassis.{kind}=c1\nlldp.eth0.port.{kind}=p1\n" + + (row,) = _rows(output) + + assert (row["chassis_id"], row["chassis_id_type"]) == ("c1", kind) + assert (row["port_id"], row["port_id_type"]) == ("p1", kind) + + def test_a_neighbour_without_ids_has_empty_ones(self): + (row,) = _rows("lldp.eth0.via=CDPv2\nlldp.eth0.chassis.name=sw\n") + + assert (row["chassis_id"], row["chassis_id_type"]) == ("", "") + assert (row["port_id"], row["port_id_type"]) == ("", "") + + +class TestOtherFields: + def test_every_management_address_is_kept(self): + phone = _rows()[0] + + assert phone["management_addresses"] == ["10.0.0.21", "fe80::211:22ff:fe33:4401"] + + def test_a_value_may_hold_an_equals_sign(self): + assert _rows()[0]["system_description"] == "SIP phone, firmware a=1" + + def test_capabilities_in_napalm_names_and_which_are_enabled(self): + phone, pc, switch = _rows() + + assert phone["capabilities"] == ["bridge", "telephone"] + assert phone["enabled_capabilities"] == ["telephone"] + assert pc["capabilities"] == ["bridge", "router", "wlan-access-point", "station"] + assert pc["enabled_capabilities"] == ["station"] + assert switch["capabilities"] == ["bridge", "router", "cvlan"] + assert switch["enabled_capabilities"] == ["bridge", "cvlan"] + + def test_every_napalm_capability_name(self): + symbols = ["Other", "Repeater", "Bridge", "Router", "Wlan", "Tel", "Docsis", "Station"] + output = "lldp.eth0.via=LLDP\n" + "".join( + f"lldp.eth0.chassis.{s}.enabled=on\n" for s in symbols + ) + + (row,) = _rows(output) + + assert row["capabilities"] == [ + "other", + "repeater", + "bridge", + "router", + "wlan-access-point", + "telephone", + "docsis-cable-device", + "station", + ] + assert row["enabled_capabilities"] == row["capabilities"] + + def test_a_capability_line_needs_on_or_off(self): + (row,) = _rows(OPENWRT_ONE_NEIGHBOUR) + + assert row["capabilities"] == [] + + +class TestReadOrFailure: + """A failed read raises; ``[]`` only when lldpctl ran and listed nobody.""" + + def test_no_output_is_no_neighbour(self): + assert parse_lldpctl_keyvalue("") == [] + + def test_a_zero_exit_status_without_neighbours_is_no_neighbour(self): + assert parse_lldpctl_keyvalue("__LLDPCTL_RC=0\n") == [] + + def test_a_missing_lldpctl_raises(self): + with pytest.raises(ValueError, match="lldpctl: not found"): + parse_lldpctl_keyvalue("sh: lldpctl: not found\n") + + def test_a_non_zero_exit_status_raises_with_what_lldpctl_said(self): + output = ( + "[WARN/control] unable to connect to socket /var/run/lldpd.socket: " + "No such file or directory\n" + "__LLDPCTL_RC=1\n" + ) + + with pytest.raises(ValueError, match="unable to connect to socket"): + parse_lldpctl_keyvalue(output) + + def test_a_non_zero_exit_status_without_a_message_names_the_status(self): + with pytest.raises(ValueError, match="exit status 127"): + parse_lldpctl_keyvalue("__LLDPCTL_RC=127\n") + + def test_with_status_zero_a_warning_beside_the_neighbours_is_ignored(self): + output = ( + "lldpctl -f keyvalue 2>&1; echo __LLDPCTL_RC=$?\n" + "[WARN/lldpctl] something lldpd wants to say\n" + + OPENWRT_ONE_NEIGHBOUR + + "__LLDPCTL_RC=0\n" + ) + + assert [r["system_name"] for r in _rows(output)] == ["core-router"] + + def test_a_line_outside_lldp_is_no_neighbour(self): + output = "lldpd.config.tx-delay=30\n" + OPENWRT_ONE_NEIGHBOUR + + assert len(_rows(output)) == 1 + + def test_a_key_without_a_known_field_is_skipped(self): + output = "lldp.summary=1\nlldp.eth9.future-field=x\n" + OPENWRT_ONE_NEIGHBOUR + + assert [r["local_port"] for r in _rows(output)] == ["eth0"] + + +class TestCommand: + def test_the_command_reads_the_neighbours_in_keyvalue_form(self): + assert LLDPCTL_KEYVALUE_COMMAND.startswith("lldpctl -f keyvalue ") + + def test_the_command_brings_back_the_error_text_and_the_exit_status(self): + assert "2>&1" in LLDPCTL_KEYVALUE_COMMAND + assert LLDPCTL_KEYVALUE_COMMAND.endswith("echo __LLDPCTL_RC=$?") -- 2.54.0 From 2542081c6f9f28eb8c57499a1f1119f0056001d5 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Mon, 2 Nov 2026 08:50:50 +0100 Subject: [PATCH 2/2] feat(lldp): report the neighbour's chassis MAC in lldp_neighbors An application matches an LLDP neighbour by its chassis MAC first, and napalm-linux and napalm-netgear report it as mac; the projection did not, so every driver built on it would have reported neighbours by name only (NAPALM/napalm-openwrt#31). lldp_neighbors now carries mac, lower case, when the chassis id is a MAC address (LldpNeighborDict). --- CHANGELOG.md | 4 +++- README.md | 2 +- napalm_device_types/__init__.py | 8 +++++++- napalm_device_types/lldp.py | 36 ++++++++++++++++++++++++--------- tests/test_lldp_rows.py | 20 +++++++++++++++--- 5 files changed, 55 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 22258d8..9dc337e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,9 @@ recorded here; their history is the git log. lldpctl missing) raises instead of reading as no neighbours. - `lldp_neighbors(rows)` and `lldp_neighbors_detail(rows, interface="")`: NAPALM's `get_lldp_neighbors` and `get_lldp_neighbors_detail` from those rows, so a driver no - longer builds the two shapes itself. + longer builds the two shapes itself. A neighbour that names its chassis by a MAC + address carries it in `get_lldp_neighbors` as `mac`, in lower case + (`LldpNeighborDict`), so an application can match it by MAC. ### Fixed - `DNF_SECURITY_COMMAND` reads the cached metadata only (`dnf --cacheonly`), as diff --git a/README.md b/README.md index 09e5158..6cbf721 100644 --- a/README.md +++ b/README.md @@ -183,7 +183,7 @@ LLDP neighbours are rows: `LldpNeighborRow` is one neighbour as its local port h (chassis and port id with their type, name, description, management addresses, capabilities in NAPALM's names), and `lldp_neighbors(rows)` / `lldp_neighbors_detail(rows, interface)` are NAPALM's two getters projected from them, a port with two neighbours -keeping both. A driver for a host that runs lldpd sends `LLDPCTL_KEYVALUE_COMMAND` and +keeping both; a neighbour named by its chassis MAC carries it as `mac` (lower case). A driver for a host that runs lldpd sends `LLDPCTL_KEYVALUE_COMMAND` and hands its output to `parse_lldpctl_keyvalue`: one row per neighbour block, an interface name with dots (`eth0.1`) kept whole, ids read under the type lldpd prints them with (`chassis.mac`, `port.local`, ...). When lldpctl fails (lldpd not running, no `lldpctl`) diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index c4afbb5..9c7de80 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -135,7 +135,12 @@ from napalm_device_types.listening import ( ListeningSocketsUnavailable, parse_listening_sockets, ) -from napalm_device_types.lldp import LldpNeighborRow, lldp_neighbors, lldp_neighbors_detail +from napalm_device_types.lldp import ( + LldpNeighborDict, + LldpNeighborRow, + lldp_neighbors, + lldp_neighbors_detail, +) from napalm_device_types.lldpctl import LLDPCTL_KEYVALUE_COMMAND, parse_lldpctl_keyvalue from napalm_device_types.local_accounts import ( LocalAccountChangeDict, @@ -351,6 +356,7 @@ __all__ = [ "ListeningSocketsUnavailable", "parse_listening_sockets", "LLDPCTL_KEYVALUE_COMMAND", + "LldpNeighborDict", "LldpNeighborRow", "lldp_neighbors", "lldp_neighbors_detail", diff --git a/napalm_device_types/lldp.py b/napalm_device_types/lldp.py index e796bf4..44b0e26 100644 --- a/napalm_device_types/lldp.py +++ b/napalm_device_types/lldp.py @@ -10,10 +10,14 @@ several entries in both shapes. from __future__ import annotations +import re from collections.abc import Iterable -from typing import TypedDict +from typing import NotRequired, TypedDict -from napalm.base.models import LLDPNeighborDetailDict, LLDPNeighborDict +from napalm.base.models import LLDPNeighborDetailDict + +#: A chassis id of type ``mac`` that really is a MAC address. +_MAC_RE = re.compile(r"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$") class LldpNeighborRow(TypedDict): @@ -39,13 +43,27 @@ class LldpNeighborRow(TypedDict): enabled_capabilities: list[str] -def lldp_neighbors(rows: Iterable[LldpNeighborRow]) -> dict[str, list[LLDPNeighborDict]]: - """``get_lldp_neighbors``: per local port, every neighbour's name and port.""" - neighbors: dict[str, list[LLDPNeighborDict]] = {} +class LldpNeighborDict(TypedDict): + """NAPALM's ``get_lldp_neighbors`` entry (``hostname``, ``port``), plus the chassis MAC. + + ``mac`` (lower case) is there only when the neighbour names its chassis by a + MAC address; an application can match the neighbour by it, where a name + may be ambiguous. + """ + + hostname: str + port: str + mac: NotRequired[str] + + +def lldp_neighbors(rows: Iterable[LldpNeighborRow]) -> dict[str, list[LldpNeighborDict]]: + """``get_lldp_neighbors``: per local port, every neighbour's name, port and chassis MAC.""" + neighbors: dict[str, list[LldpNeighborDict]] = {} for row in rows: - neighbors.setdefault(row["local_port"], []).append( - {"hostname": row["system_name"], "port": row["port_id"]} - ) + entry: LldpNeighborDict = {"hostname": row["system_name"], "port": row["port_id"]} + if row["chassis_id_type"] == "mac" and _MAC_RE.match(row["chassis_id"]): + entry["mac"] = row["chassis_id"].lower() + neighbors.setdefault(row["local_port"], []).append(entry) return neighbors @@ -76,4 +94,4 @@ def lldp_neighbors_detail( return details -__all__ = ["LldpNeighborRow", "lldp_neighbors", "lldp_neighbors_detail"] +__all__ = ["LldpNeighborDict", "LldpNeighborRow", "lldp_neighbors", "lldp_neighbors_detail"] diff --git a/tests/test_lldp_rows.py b/tests/test_lldp_rows.py index 5fe25c2..49ce11d 100644 --- a/tests/test_lldp_rows.py +++ b/tests/test_lldp_rows.py @@ -33,7 +33,7 @@ def _row(local_port: str, name: str, **fields: object) -> LldpNeighborRow: PHONE = _row( "eth0.1", "desk-phone", - chassis_id="00:11:22:33:44:01", + chassis_id="00:11:22:33:44:AB", chassis_id_type="mac", port_id="00:11:22:33:44:01", port_id_type="mac", @@ -66,7 +66,7 @@ class TestNeighbors: def test_every_neighbour_of_a_port_is_listed(self): assert lldp_neighbors([PHONE, PC, SWITCH]) == { "eth0.1": [ - {"hostname": "desk-phone", "port": "00:11:22:33:44:01"}, + {"hostname": "desk-phone", "port": "00:11:22:33:44:01", "mac": "00:11:22:33:44:ab"}, {"hostname": "desk-pc", "port": "eno1"}, ], "eth1": [{"hostname": "access-sw", "port": "gi1/0/7"}], @@ -75,6 +75,20 @@ class TestNeighbors: def test_no_rows_is_no_neighbour(self): assert lldp_neighbors([]) == {} + def test_a_chassis_mac_is_reported_in_lower_case(self): + # netOrk matches a neighbour by this MAC first (NAPALM/napalm-openwrt#31). + assert lldp_neighbors([PHONE])["eth0.1"][0]["mac"] == "00:11:22:33:44:ab" + + def test_a_chassis_named_otherwise_has_no_mac(self): + switch = _row("eth1", "sw", chassis_id="00:11:22:33:44:55", chassis_id_type="local") + + assert "mac" not in lldp_neighbors([switch])["eth1"][0] + + def test_a_mac_id_that_is_no_mac_address_is_left_out(self): + odd = _row("eth1", "sw", chassis_id="00:11", chassis_id_type="mac") + + assert "mac" not in lldp_neighbors([odd])["eth1"][0] + class TestNeighborsDetail: def test_every_field_napalm_names(self): @@ -84,7 +98,7 @@ class TestNeighborsDetail: "parent_interface": "", "remote_port": "00:11:22:33:44:01", "remote_port_description": "WAN", - "remote_chassis_id": "00:11:22:33:44:01", + "remote_chassis_id": "00:11:22:33:44:AB", "remote_system_name": "desk-phone", "remote_system_description": "SIP phone", "remote_system_capab": ["bridge", "telephone"], -- 2.54.0