diff --git a/CHANGELOG.md b/CHANGELOG.md index aa6e349..9dc337e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,20 @@ 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. 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 `APT_UPGRADABLE_COMMAND` reads apt's local index (#76). With an expired cache dnf diff --git a/README.md b/README.md index ea8ba97..6cbf721 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 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`) +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..9c7de80 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -135,6 +135,13 @@ from napalm_device_types.listening import ( ListeningSocketsUnavailable, parse_listening_sockets, ) +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, LocalAccountDict, @@ -348,6 +355,12 @@ __all__ = [ "ListeningSocketsMixin", "ListeningSocketsUnavailable", "parse_listening_sockets", + "LLDPCTL_KEYVALUE_COMMAND", + "LldpNeighborDict", + "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..44b0e26 --- /dev/null +++ b/napalm_device_types/lldp.py @@ -0,0 +1,97 @@ +"""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 + +import re +from collections.abc import Iterable +from typing import NotRequired, TypedDict + +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): + """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] + + +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: + 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 + + +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__ = ["LldpNeighborDict", "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..49ce11d --- /dev/null +++ b/tests/test_lldp_rows.py @@ -0,0 +1,127 @@ +"""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:AB", + 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", "mac": "00:11:22:33:44:ab"}, + {"hostname": "desk-pc", "port": "eno1"}, + ], + "eth1": [{"hostname": "access-sw", "port": "gi1/0/7"}], + } + + 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): + 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:AB", + "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=$?")