feat(lldp): one lldpctl keyvalue parser and the LLDP projections #78

Merged
christianmanivong merged 3 commits from feat/lldpctl-keyvalue-parser into main 2026-11-02 09:38:07 +00:00
7 changed files with 773 additions and 0 deletions

No files matched your search

+14
View File
@@ -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
+10
View File
@@ -179,6 +179,16 @@ without `ss` is read with `netstat -lntup` (OpenWrt's busybox, old net-tools); o
cgroup names the procd service (`/services/<name>/<instance>`). 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`.
+13
View File
@@ -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",
+97
View File
@@ -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"]
+204
View File
@@ -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.<type>=`` and ``port.<type>=``,
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.<Symbol>.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"]
+127
View File
@@ -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"]
+308
View File
@@ -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.<Capability>.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.<Symbol>.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=$?")