Compare commits

...
14 Commits
Author SHA1 Message Date
christianmanivong a0901e3277 Merge pull request 'chore(release): 4.24.0' (#81) from chore/release-4.24.0 into main
driver / standard (push) Successful in 19s
driver / lint (push) Successful in 17s
driver / types (push) Successful in 1m14s
driver / test (3.12) (push) Successful in 1m15s
driver / test (3.13) (push) Successful in 1m8s
driver / lowest (push) Successful in 36s
driver / build (push) Successful in 31s
driver / security (push) Successful in 1m16s
driver / publish (push) Successful in 32s
CI / driver (push) Successful in 4m45s
2026-11-02 09:45:41 +00:00
christianmanivong 060e210130 chore(release): 4.24.0
driver / standard (pull_request) Successful in 19s
driver / lint (pull_request) Successful in 22s
driver / types (pull_request) Successful in 1m12s
driver / test (3.12) (pull_request) Successful in 1m16s
driver / lowest (pull_request) Successful in 35s
driver / test (3.13) (pull_request) Successful in 1m18s
driver / build (pull_request) Successful in 34s
driver / security (pull_request) Successful in 1m20s
CI / driver (pull_request) Successful in 3m17s
driver / publish (pull_request) Skipped
2026-11-02 10:38:38 +01:00
christianmanivong 31973d2d5f Merge pull request 'feat(lldp): one lldpctl keyvalue parser and the LLDP projections' (#78) from feat/lldpctl-keyvalue-parser into main
driver / standard (push) Successful in 18s
driver / lint (push) Successful in 17s
driver / types (push) Successful in 1m24s
driver / test (3.12) (push) Successful in 1m26s
driver / test (3.13) (push) Successful in 1m13s
driver / lowest (push) Successful in 36s
driver / build (push) Successful in 39s
driver / security (push) Successful in 1m28s
CI / driver (push) Successful in 3m30s
driver / publish (push) Skipped
2026-11-02 09:38:06 +00:00
christianmanivong abda0973e7 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
2026-11-02 10:24:03 +01:00
christianmanivong 4eeaaef236 Merge pull request 'docs(structure): format the code examples as current ruff does' (#80) from fix/ruff-markdown-format into main
driver / standard (push) Successful in 20s
driver / lint (push) Successful in 17s
driver / types (push) Successful in 1m15s
driver / test (3.12) (push) Successful in 1m20s
driver / test (3.13) (push) Successful in 1m7s
driver / lowest (push) Successful in 44s
driver / build (push) Successful in 36s
driver / security (push) Successful in 1m22s
CI / driver (push) Successful in 3m2s
driver / publish (push) Skipped
2026-11-02 09:23:57 +00:00
christianmanivong 3490d8b62a docs(structure): format the code examples as current ruff does
driver / standard (pull_request) Successful in 21s
driver / lint (pull_request) Successful in 17s
driver / types (pull_request) Successful in 1m5s
driver / test (3.12) (pull_request) Successful in 1m14s
driver / test (3.13) (pull_request) Successful in 1m7s
driver / lowest (pull_request) Successful in 34s
driver / build (pull_request) Successful in 32s
driver / security (pull_request) Successful in 1m29s
CI / driver (pull_request) Successful in 3m21s
driver / publish (pull_request) Skipped
ruff 0.17 formats Python blocks in Markdown too, and CI installs ruff
unpinned, so the lint job on main failed on docs/STRUCTURE.md.

Closes #79
2026-11-02 09:18:42 +01:00
christianmanivong 2542081c6f 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
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).
2026-11-02 08:50:50 +01:00
christianmanivong 4427be35cc 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
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
2026-11-02 08:42:10 +01:00
christianmanivong ad9ec0fb4d Merge pull request 'docs: a structure that keeps device-types vendor- and product-agnostic' (#37) from docs/structure-plan into main
driver / standard (push) Successful in 14s
driver / lint (push) Failing after 13s
driver / test (3.12) (push) Successful in 1m0s
driver / types (push) Successful in 1m5s
driver / test (3.13) (push) Successful in 1m2s
driver / lowest (push) Successful in 36s
driver / build (push) Successful in 42s
driver / security (push) Successful in 1m19s
CI / driver (push) Failing after 2m48s
driver / publish (push) Skipped
Reviewed-on: #37
2026-11-02 07:19:02 +00:00
christianmanivong 8dd7e8ab9a Merge branch 'main' into docs/structure-plan
driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Failing after 13s
driver / types (pull_request) Successful in 1m0s
driver / test (3.12) (pull_request) Successful in 58s
driver / test (3.13) (pull_request) Successful in 58s
driver / lowest (pull_request) Successful in 30s
driver / build (pull_request) Successful in 27s
driver / security (pull_request) Successful in 58s
CI / driver (pull_request) Failing after 2m22s
driver / publish (pull_request) Skipped
2026-11-02 07:18:47 +00:00
christianmanivong 935fad2a2d Merge pull request 'fix(updates): read dnf's security advisories from the cached metadata (#76)' (#77) from fix/dnf-security-cache-only into main
driver / standard (push) Failing after 2s
driver / lint (push) Successful in 14s
driver / types (push) Successful in 1m1s
driver / test (3.12) (push) Successful in 1m1s
driver / test (3.13) (push) Successful in 55s
driver / lowest (push) Successful in 31s
driver / build (push) Successful in 31s
driver / security (push) Successful in 1m3s
CI / driver (push) Failing after 2m6s
driver / publish (push) Skipped
Reviewed-on: #77
2026-11-02 07:18:33 +00:00
christianmanivong f337ae7fb8 fix(updates): read dnf's security advisories from the cached metadata
driver / standard (pull_request) Successful in 15s
driver / lint (pull_request) Successful in 13s
driver / types (pull_request) Successful in 55s
driver / test (3.12) (pull_request) Successful in 1m2s
driver / lowest (pull_request) Successful in 32s
driver / test (3.13) (pull_request) Successful in 1m4s
driver / build (pull_request) Successful in 25s
driver / security (pull_request) Successful in 57s
CI / driver (pull_request) Successful in 2m27s
driver / publish (pull_request) Skipped
DNF_SECURITY_COMMAND ran `dnf updateinfo list --security`, which downloads
the repositories' metadata first whenever the cached copy has expired. On an
Oracle Linux host on OCI that took longer than netOrk's whole 120 s poll.
It now runs with --cacheonly, as APT_UPGRADABLE_COMMAND reads apt's local
index; refreshing stays `dnf makecache`. Without a cache dnf fails at once,
and the __DNF_RC marker already turns that into "security unknown".

Closes #76
2026-11-02 08:07:48 +01:00
christianmanivong c7ea15dbb4 docs: what the drivers need from the SNMP profile, opt-outs, and how getters behave
CI / test (3.10) (push) Successful in 26s
CI / test (3.11) (push) Successful in 24s
CI / test (3.12) (push) Successful in 26s
CI / test (3.13) (push) Successful in 25s
CI / test (3.10) (pull_request) Successful in 25s
CI / test (3.11) (pull_request) Successful in 24s
CI / test (3.12) (pull_request) Successful in 26s
CI / test (3.13) (pull_request) Successful in 25s
The SNMP profile has to express fallback OIDs, tables folded by first,
average or maximum, numbers inside text values, memory as used, free or
percent, and the uptime source. TX errors counting drops becomes
OPNsense's entry instead of every firewall's.

A driver opts out of an inherited template with None, so callers ask
callable(). USES_SSH, FULL_UPGRADE and platform stay as driver facts.
Getters do not write, a failed read raises, a write reports its real
result, and the application uses public driver methods only.
2026-10-14 10:56:17 +02:00
christianmanivong 01fe680456 docs: a structure that keeps device-types vendor- and product-agnostic
CI / test (3.10) (push) Successful in 28s
CI / test (3.11) (push) Successful in 26s
CI / test (3.12) (push) Successful in 27s
CI / test (3.13) (push) Successful in 25s
CI / test (3.10) (pull_request) Successful in 25s
CI / test (3.11) (pull_request) Successful in 24s
CI / test (3.12) (pull_request) Successful in 25s
CI / test (3.13) (pull_request) Successful in 24s
Roles and capabilities declare, templates run declared steps, reconcilers
stay free of I/O. POSIX host readers, the SSH exec transport and the
privilege layer move to a new package, napalm-unix. SNMP polling, ping
sweeps, discovery scoring, guest profiles, display labels and warnings
belong to the application; drivers declare SNMP OIDs as data and report
facts. Fixes become templates whose values come from the caller.

Says in which order this happens and where the open proposals #8-#14 and
#22 go instead.
2026-10-14 10:20:55 +02:00
11 changed files with 1045 additions and 3 deletions

No files matched your search

+24
View File
@@ -7,6 +7,30 @@ recorded here; their history is the git log.
## [Unreleased]
## [4.24.0] - 2026-11-02
### 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
downloaded the repositories' metadata first, and on an Oracle Linux host on OCI that
outlasted netOrk's whole poll budget. Refreshing the index stays a step of its own
(`dnf makecache`). Without a cache dnf fails at once, which already reads as
"security unknown".
## [4.23.0] - 2026-11-02
### Changed
+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`.
+244
View File
@@ -0,0 +1,244 @@
# Structure
Status: agreed plan. Nothing here is implemented yet; the migration at the end says in
which order it will be.
## Principle
**napalm-device-types is vendor-, OS-, protocol- and product-agnostic.** It holds the
contracts every driver implements and the generic logic that works unchanged for every
driver of a role. It knows no shell, no paramiko, no package manager, no container CLI,
no SNMP OID, no cloud-init and no application that uses the drivers.
That rules out three kinds of code that are here today:
- **How a kind of host is read.** Shell commands and their parsers for POSIX hosts move to
a new package, **napalm-unix**, which napalm-linux and napalm-bsd depend on.
- **What an application does with a device.** Polling a device over SNMP, sweeping a range
with pings, scoring discovery evidence, choosing what a provisioned guest installs, and
deciding what counts as a problem belong to the application, not to the drivers.
- **Product naming.** Files, markers and messages a driver leaves on a device carry the
driver's name or none, never the name of the application that called it.
```
napalm-device-types roles, capabilities, templates, models, reconcilers <- every driver
^
napalm-unix POSIX host readers, SSH exec transport, privilege <- napalm-linux, napalm-bsd
^
napalm-linux, napalm-bsd connection, platform getters, platform steps
application SNMP polling, ping sweeps, discovery scoring, guest
profiles, warnings, and the values every fix is given
```
## What stays in napalm-device-types
| Kind | Rule | Modules |
|---|---|---|
| **Role** | Declares only, under `TYPE_CHECKING`. No runtime method. | `access_point`, `switch`, `firewall`, `hypervisor`, `os`, `storage`, `phone`, `media`, `residential_gateway`, `management_controller` |
| **Capability** | Declares only. | `packages`, `services`, `updates`, `nat_vpn`, `mac_acl`, `config_lifecycle`, `interface_filter`, `host_reboot` |
| **Template** | A concrete method that runs a fixed sequence of abstract steps. A driver implements the steps, or overrides the whole method when its device does it in one go. All values come from the caller. | the fix routines below |
| **Contract types** | Interfaces and data shapes other packages implement or fill. | `CommandChannelMixin`, `CommandResult`, `ByteStream`; the declaration of `ContainerEngineMixin`; the reader mixins' public method declarations; the SNMP profile type; `models` |
| **Reconciler** | Concrete and vendor-neutral, without I/O of its own. | `firewall_rules` and `dhcp` diff/apply, `_matching`, `lag` |
| **Introspection** | Concrete, without I/O. | `roles`; `base` (`FingerprintRule`, `PortSpec`, the fingerprint attributes) |
| **Driver facts** | Class attributes that describe the device or how it is reached, not what an application does with it. | `USES_SSH`, `FULL_UPGRADE`, `platform`, `SNMP_HEALTH_PROFILE` |
### Fix routines are templates
A change the application wants made on a device, for example "run an SNMP agent that
answers us", is one template per purpose. The template fixes the order of the steps; the
driver knows how each step is done on its device; the caller supplies every value.
```python
class SnmpAgentMixin:
def configure_snmp_agent(self, settings: SnmpAgentSettingsDict) -> FixResultDict:
steps = [
self._install_snmp_agent,
self._write_snmp_agent_config,
self._enable_snmp_agent,
self._verify_snmp_agent,
]
... # runs them in order, stops at the first failure
# declared only; napalm-unix implements them for net-snmp
def _install_snmp_agent(self) -> FixStepDict: ...
def _write_snmp_agent_config(self, settings: SnmpAgentSettingsDict) -> FixStepDict: ...
def _enable_snmp_agent(self) -> FixStepDict: ...
def _verify_snmp_agent(self, settings: SnmpAgentSettingsDict) -> FixStepDict: ...
```
napalm-unix implements the four steps for net-snmp, for Linux and the BSDs alike. A REST
driver such as OPNsense overrides `configure_snmp_agent` as a whole, because its device
takes the whole configuration in one call. The community, the allowed sources, contact
and location are the caller's.
The same shape replaces every action in today's `run_device_action`:
| Today | Template |
|---|---|
| `fix_snmp` | `configure_snmp_agent(settings)` |
| `fix_apt_proxy` | `configure_package_proxy(url)` |
| `fix_docker_permissions` | `grant_container_engine_access(user)` |
| `install_lldpd`, `install_auc` | `ensure_package(name)` |
The mixin is mixed in by the driver, or by the platform package, not by a role base. A
driver that inherits a template it cannot run on its device, as a NAS driver built on the
Linux driver inherits the package proxy, opts out by setting the method to `None`. So a
caller asks `callable(getattr(driver, "configure_snmp_agent", None))`, never `hasattr`.
The caller verifies the result from its own side where it can; the SNMP agent is asked
by the application's SNMP client, not by a probe the driver hand-builds.
### SNMP: drivers declare data, the application polls
The drivers do not collect over SNMP. A driver whose device answers the standard UCD-MIB
and IF-MIB declares nothing. A driver whose device publishes the same values under
proprietary OIDs declares them as data, in a class attribute of a type defined here:
```python
class ProcurveDriver(SwitchDriver):
SNMP_HEALTH_PROFILE: ClassVar[SnmpHealthProfile] = {
"uptime": {"oids": ["1.3.6.1.4.1.11.2.14.11.1.2.4.1.5.1"], "format": "ticks"},
"cpu": {"oids": ["1.3.6.1.4.1.11.2.14.11.5.1.9.6.1.0", "1.3.6.1.4.1.11.2.3.7.8.6.1.0"]},
"memory": {"total": "...", "free": "...", "unit": "bytes"},
}
```
One OID per value is not enough for the drivers there are. The profile type has to say:
- **Fallbacks:** an ordered list of OIDs; the first that answers wins (ProCurve's CPU).
- **Tables:** an OID to walk and how to fold its rows: first, average or maximum (TP-Link
reports CPU and memory per stack unit).
- **Text values:** a pattern that takes the number out of a string (Netgear reports CPU
as `"5 Secs ( 3.2%)"`).
- **Memory:** total with used or free, or a percentage only, and the unit.
- **Uptime:** which OID, standard ones included (`sysUpTime` where a device has no
`hrSystemUptime`), and its format.
- **Interfaces:** a pattern of names to skip, and whether the TX-error counter counts
drops. Today the second is `True` on every firewall, because OPNsense counts drops
there; it becomes OPNsense's profile entry.
Polling, the standard OIDs, the counter arithmetic (64-bit counters first, 32-bit as the
fallback) and the defaults are the application's.
### Warnings are facts
A driver reports facts: the proxy a host is configured with, a DSL line's SNR, the
firmware version it runs and the one it is offered. It does not compare them with a
setting of the application or with a threshold, and it does not name a warning.
The same goes for lookups a device does not make itself: what firmware a vendor
currently publishes is the application's catalogue, not a getter.
### Getters read, and say when they cannot
- A getter changes nothing on the device. It does not start a daemon, rewrite its
configuration or install a package on the way to an answer.
- A read that fails raises. An empty list means "there is none", never "could not ask";
a sync that deletes and re-adds on top of an empty answer would otherwise duplicate
everything.
- A write reports failure from the device's answer or exit status, never `success: True`
by default.
### The application uses public methods only
The application never calls a driver's private methods (`_get`, `_post`,
`_send_command`, `_action_*`). What it needs from a device becomes a declared method of
the driver.
## What moves to napalm-unix
| Module | Knows |
|---|---|
| `host_status` | apt, dnf, dpkg, systemd timers, `df` |
| `kernel` | `/proc`, `/lib/modules`, gzip, base64 |
| `listening` | `ss`, `netstat`, `/proc/<pid>/cgroup` |
| `systemd` | `systemctl` |
| `virtual_ips` | vip-manager, keepalived, awk |
| `system_identity` | SMBIOS via sysfs and `dmidecode` |
| `package_updates` | apt and dnf output |
| `ssh_server` | OpenSSH (`sshd -T`, `sshd -t`, `sshd_config`); which algorithms to drop stays the caller's |
| `terminal` | ANSI escape codes in shell output |
| `channel`: `run_on_transport`, `open_stream_on_transport`, `ParamikoExecStream` | paramiko exec channels |
| `container_engine`: `ContainerEngineConnection`, engine probing | the Docker CLI, `system dial-stdio` |
It also takes what napalm-linux and napalm-bsd each carry today:
- **Privilege:** one `sudo -S` / `sudo -n` / root layer, including the rule that a
privileged command never gets stdin while a sudo password is set, and one way to write a
file as root (stage with `mktemp`, then `install`). Two copies of this have already
drifted apart.
- **Parsers:** `/etc/passwd` with `/etc/group`, crontab lines, `ps` with `lstart`.
- **Fix steps:** net-snmp, the package proxy, container engine group membership.
The FreeBSD part of `host_status` (`freebsd-version -k` against `-r`) moves to napalm-bsd.
In napalm-unix every reader follows one pattern:
- **Shape:** `FOO_COMMAND`, `parse_foo(output)`, and `FooMixin.get_foo()`.
- **Reaching the host:** the mixin uses `run_command(command, privileged=...)` from
`CommandChannelMixin`. The six per-reader `_run_*` hooks, with four different signatures,
go away.
- **Framing:** one frame helper writes and parses the `BEGIN`/`END` markers for every reader.
- **Errors:** one exception for "cannot read" and one for "not on this host". A read that
fails or is cut short raises; it never reads as "nothing there".
- **Names on the host:** temporary files, markers and drop-ins carry `napalm` or the
driver's name. A drop-in written under an older name is still recognised and replaced.
Layout: `napalm_unix/{posix,linux,freebsd,openssh,transport}/`.
## What moves to the application
| Today | Why it is not a driver's |
|---|---|
| `health_metrics`, `_ucd_metrics` | Polling over SNMP is something the application does to a device; the driver is not even connected while it runs. |
| `ping_sweep` | Looping over addresses, capping the targets and reporting progress is a scan. A device with a faster batch keeps it as a capability of its own. |
| `rules_max_weight` | Scoring is how one application ranks drivers. The rules themselves stay with the driver. |
| `provisioning` (`QEMU_GUEST_AGENTS`, cloud-init network-config, decompressors) | Which agent a guest gets and how its network is configured is a guest profile. The hypervisor driver is handed the packages and commands. |
| `TYPE_LABEL`, `REBOOT_SETTLE_SECONDS` | A display name and a polling delay. |
| firmware catalogues (napalm-netgear's `netgear_plus`) | What a vendor publishes is not something the device reports. |
| `run_device_action` | Replaced by the templates above. |
`OSDriver.ROLE` stops defaulting to `"linux"`. Each OS driver states its own role.
## Rules, enforced by tests in this package
1. Roles and capabilities own no runtime method; a template runs only declared steps.
2. No module imports `paramiko`, `socket`, `subprocess` or `asyncio`, and none defines a
`*_COMMAND`.
3. No module, string or default names an application.
4. Role methods return TypedDicts, not `Any`.
Each rule is added with the step that makes it pass.
## Migration
This package cannot keep re-exports pointing at napalm-unix: the contract package would
then depend on its implementation. So a moved name is first deprecated here and then
removed, and nothing breaks in between.
| Step | Change |
|---|---|
| 1 | The application moves to 4.9 and the drivers that need it; napalm-bsd stops passing stdin to a privileged command while a sudo password is set. |
| 2 | This document; the application's architecture docs and this README follow it. |
| 3 | `SnmpHealthProfile`. The application polls on its own; the four switch and phone drivers declare their OIDs as data. `HealthMetricsMixin` is deprecated. |
| 4 | The fix templates. napalm-linux and napalm-bsd implement the steps; the application calls the templates with its values. `run_device_action` is deprecated. The other drivers follow, one issue each. |
| 5 | Ping sweep, scoring, provisioning, `TYPE_LABEL` and `REBOOT_SETTLE_SECONDS` move to the application and are deprecated here. Drivers report facts instead of warnings. |
| 6 | napalm-unix, with the moved code and its tests, the unified hooks and the frame helper. napalm-linux and napalm-bsd import from it; the moved names are deprecated here. |
| 7 | 5.0 removes everything deprecated. It also splits `models.py` by area, types the remaining `Dict[str, Any]` role returns, declares what drivers already offer undeclared (`get_networks`, `search_packages`, `first_boot_pending`, the base-system update entry), and makes `install_package` declare the result drivers return. |
| 8 | The README shrinks to the concepts; the reader details move with the readers. |
## Proposals this replaces
Several open issues proposed adding shared driver code here. Under this structure:
| Issue | Goes to |
|---|---|
| #8 netmiko session | not here: a CLI-driver helper package, or left in the drivers |
| #9 config mode for CLI switches | not here: a CLI-driver helper package, or left in the drivers |
| #10 LLDP rows | the projection of rows into NAPALM's two shapes stays here; the `lldpctl` parser goes to napalm-unix |
| #11 CLI text helpers | not here; the natural port sort, which `lag` already has, may become public |
| #12 ping | the reply builder stays here; the BusyBox and iputils parser goes to napalm-unix |
| #13 Linux userland | napalm-unix; the snmpd part becomes the SNMP template's steps |
| #14 `run_device_action` | replaced by the fix templates |
| #22 hooks onto `run_command` | step 6 |
+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"]
+5 -2
View File
@@ -28,9 +28,12 @@ APT_UPGRADABLE_COMMAND = "{ LC_ALL=C apt list --upgradable 2>/dev/null; echo __A
#: Read-only. Lists the packages that a pending security advisory covers. A
#: failed dnf prints nothing, the same as no advisories, so its exit status is
#: printed inside the group, as apt's is.
#: printed inside the group, as apt's is. It reads the cached metadata only, as
#: apt reads its local index: an expired cache otherwise makes dnf download the
#: repositories' metadata first, which can take minutes (#76).
DNF_SECURITY_COMMAND = (
"{ LC_ALL=C dnf updateinfo list --security --quiet 2>/dev/null; echo __DNF_RC=$?; } | cat"
"{ LC_ALL=C dnf --cacheonly updateinfo list --security --quiet 2>/dev/null;"
" echo __DNF_RC=$?; } | cat"
)
# openssl/noble-updates,noble-security 3.0.13-0ubuntu3.6 amd64 [upgradable from: 3.0.13-0ubuntu3.5]
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "napalm-device-types"
version = "4.23.0"
version = "4.24.0"
description = "Abstract device-type base classes for NAPALM drivers"
readme = "README.md"
requires-python = ">=3.12"
+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=$?")
+12
View File
@@ -176,6 +176,18 @@ __DNF_RC=0
with pytest.raises(ValueError, match="exit status 1"):
parse_dnf_security(out)
def test_the_command_reads_only_the_cached_metadata(self, tmp_path):
"""An expired cache made dnf download the repositories' metadata inside the
poll, which outlasted its whole budget (#76)."""
args = tmp_path / "args"
dnf = tmp_path / "dnf"
dnf.write_text(f"#!/bin/sh\nprintf '%s\\n' \"$@\" > {args}\n")
dnf.chmod(0o755)
env = {"PATH": f"{tmp_path}:{os.environ.get('PATH', '/usr/bin:/bin')}"}
subprocess.run(["sh", "-c", DNF_SECURITY_COMMAND], capture_output=True, env=env)
assert "--cacheonly" in args.read_text().split()
@pytest.mark.parametrize(
("nevra", "name"),
[