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
Owner

What

One parser for lldpd's lldpctl -f keyvalue output, for every driver of a host that runs lldpd, plus NAPALM's two LLDP shapes projected from its rows:

  • napalm_device_types/lldpctl.py: LLDPCTL_KEYVALUE_COMMAND (lldpctl -f keyvalue 2>&1; echo __LLDPCTL_RC=$?) and parse_lldpctl_keyvalue(output) -> list[LldpNeighborRow].
  • napalm_device_types/lldp.py: LldpNeighborRow and lldp_neighbors(rows) / lldp_neighbors_detail(rows, interface=""). lldp_neighbors returns LldpNeighborDict: NAPALM's hostname and port, plus mac (lower case) when the chassis id is a MAC address. napalm-linux and napalm-netgear already report it, and netOrk matches neighbours by it first (second commit, for NAPALM/napalm-openwrt#31).

Why

napalm-linux, napalm-openwrt and napalm-proxmox (the last with lldpcli's text format) each parsed lldpd themselves, and the copies share the same bugs: neighbours grouped by port so a second neighbour overwrites the first (NAPALM/napalm-linux#58, NAPALM/napalm-openwrt#9), the interface name cut at its first dot (eth0.1 -> eth0, NAPALM/napalm-openwrt#26), ids looked up as chassis.id.value / port.id.value, keys lldpd never prints, and a failed lldpctl read as "no neighbours" (NAPALM/napalm-openwrt#27).

How the parse handles lldpd's format (src/client/kv_writer.c, display.c):

  • A neighbour opens with via (after the local interface's optional alias); the next via on the same port is the next neighbour.
  • via/alias end their key, so they give the interface name exactly, dots and all; the following keys continue it. A key without such an opener ends the name at the first known field (chassis, port, vlan, lldp-med, ...).
  • Ids are read under the type lldpd prints them with (mac, ip, ifname, ifalias, local, unhandled), and the type is kept in the row.
  • Capabilities (chassis.<Symbol>.enabled=on|off) in NAPALM's names; all management addresses.
  • A non-zero exit status raises ValueError with lldpctl's message; without a status, text that holds not a single neighbour line (sh: lldpctl: not found) raises too. [] only when lldpctl ran and listed nobody.

This is the parse and the projection part of #10 (see #10); the LldpTableMixin it proposes is not part of this. docs/STRUCTURE.md has the lldpctl parser move to napalm-unix later (see #35); lldpctl.py is kept apart from lldp.py so it can move on its own.

Tests

Fixtures only: the recording napalm-openwrt's tests use, and output laid out per lldpd's source (two neighbours on dotted eth0.1, port ids by MAC and local id, chassis by address, MED/VLAN/unknown-TLV lines), plus failure cases. pytest 1146 passed, coverage 100 % on both new modules (96 % total), ruff format --check, ruff check, mypy --strict, napalm-standard ratchet within the baseline.

Release

Feature, minor: CHANGELOG under [Unreleased]. The driver PRs NAPALM/napalm-linux#62, NAPALM/napalm-openwrt#30 and NAPALM/napalm-proxmox#46 raise their floor to 4.24.0 and need this released first.

## What One parser for lldpd's `lldpctl -f keyvalue` output, for every driver of a host that runs lldpd, plus NAPALM's two LLDP shapes projected from its rows: - `napalm_device_types/lldpctl.py`: `LLDPCTL_KEYVALUE_COMMAND` (`lldpctl -f keyvalue 2>&1; echo __LLDPCTL_RC=$?`) and `parse_lldpctl_keyvalue(output) -> list[LldpNeighborRow]`. - `napalm_device_types/lldp.py`: `LldpNeighborRow` and `lldp_neighbors(rows)` / `lldp_neighbors_detail(rows, interface="")`. `lldp_neighbors` returns `LldpNeighborDict`: NAPALM's `hostname` and `port`, plus `mac` (lower case) when the chassis id is a MAC address. napalm-linux and napalm-netgear already report it, and netOrk matches neighbours by it first (second commit, for NAPALM/napalm-openwrt#31). ## Why napalm-linux, napalm-openwrt and napalm-proxmox (the last with lldpcli's text format) each parsed lldpd themselves, and the copies share the same bugs: neighbours grouped by port so a second neighbour overwrites the first (NAPALM/napalm-linux#58, NAPALM/napalm-openwrt#9), the interface name cut at its first dot (`eth0.1` -> `eth0`, NAPALM/napalm-openwrt#26), ids looked up as `chassis.id.value` / `port.id.value`, keys lldpd never prints, and a failed lldpctl read as "no neighbours" (NAPALM/napalm-openwrt#27). How the parse handles lldpd's format (`src/client/kv_writer.c`, `display.c`): - A neighbour opens with `via` (after the local interface's optional `alias`); the next `via` on the same port is the next neighbour. - `via`/`alias` end their key, so they give the interface name exactly, dots and all; the following keys continue it. A key without such an opener ends the name at the first known field (`chassis`, `port`, `vlan`, `lldp-med`, ...). - Ids are read under the type lldpd prints them with (`mac`, `ip`, `ifname`, `ifalias`, `local`, `unhandled`), and the type is kept in the row. - Capabilities (`chassis.<Symbol>.enabled=on|off`) in NAPALM's names; all management addresses. - A non-zero exit status raises `ValueError` with lldpctl's message; without a status, text that holds not a single neighbour line (`sh: lldpctl: not found`) raises too. `[]` only when lldpctl ran and listed nobody. This is the parse and the projection part of #10 (see #10); the `LldpTableMixin` it proposes is not part of this. `docs/STRUCTURE.md` has the lldpctl parser move to napalm-unix later (see #35); `lldpctl.py` is kept apart from `lldp.py` so it can move on its own. ## Tests Fixtures only: the recording napalm-openwrt's tests use, and output laid out per lldpd's source (two neighbours on dotted `eth0.1`, port ids by MAC and local id, chassis by address, MED/VLAN/unknown-TLV lines), plus failure cases. `pytest` 1146 passed, coverage 100 % on both new modules (96 % total), `ruff format --check`, `ruff check`, `mypy --strict`, `napalm-standard ratchet` within the baseline. ## Release Feature, minor: CHANGELOG under [Unreleased]. The driver PRs NAPALM/napalm-linux#62, NAPALM/napalm-openwrt#30 and NAPALM/napalm-proxmox#46 raise their floor to 4.24.0 and need this released first.
christianmanivong added 1 commit 2026-11-02 07:42:29 +00:00
feat(lldp): parse lldpctl keyvalue into one row per neighbour
driver / standard (pull_request) Successful in 16s
driver / lint (pull_request) Failing after 16s
driver / types (pull_request) Successful in 1m8s
driver / test (3.12) (pull_request) Successful in 1m18s
driver / test (3.13) (pull_request) Successful in 1m3s
driver / lowest (pull_request) Successful in 50s
driver / build (pull_request) Successful in 37s
driver / security (pull_request) Successful in 1m18s
CI / driver (pull_request) Failing after 3m7s
driver / publish (pull_request) Skipped
4427be35cc
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
christianmanivong added 1 commit 2026-11-02 07:50:54 +00:00
feat(lldp): report the neighbour's chassis MAC in lldp_neighbors
driver / standard (pull_request) Successful in 20s
driver / lint (pull_request) Failing after 15s
driver / types (pull_request) Successful in 1m13s
driver / test (3.12) (pull_request) Successful in 1m19s
driver / test (3.13) (pull_request) Successful in 1m12s
driver / lowest (pull_request) Successful in 38s
driver / build (pull_request) Successful in 31s
driver / security (pull_request) Successful in 1m13s
CI / driver (pull_request) Failing after 3m1s
driver / publish (pull_request) Skipped
2542081c6f
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).
christianmanivong added 1 commit 2026-11-02 09:24:03 +00:00
Merge remote-tracking branch 'origin/main' into feat/lldpctl-keyvalue-parser
driver / standard (pull_request) Successful in 18s
driver / lint (pull_request) Successful in 17s
driver / types (pull_request) Successful in 1m7s
driver / test (3.12) (pull_request) Successful in 1m14s
driver / test (3.13) (pull_request) Successful in 1m12s
driver / lowest (pull_request) Successful in 38s
driver / build (pull_request) Successful in 35s
driver / security (pull_request) Successful in 1m13s
CI / driver (pull_request) Successful in 2m55s
driver / publish (pull_request) Skipped
abda0973e7
christianmanivong merged commit 31973d2d5f into main 2026-11-02 09:38:07 +00:00
christianmanivong deleted branch feat/lldpctl-keyvalue-parser 2026-11-02 09:38:07 +00:00
Sign in to join this conversation.