get_port_forwards was declared on ResidentialGatewayDriver alone, as if a
port forward were a home-router feature. A firewall forwards ports just the
same (OPNsense calls it destination NAT), and netOrk asks both: is this host
reachable from the internet, which CVEs are exposed. The declaration moves to
NatVpnMixin, where the two roles already overlap, and PortForwardDict next to
NATTranslationDict.
The contract now says what counts. Destination NAT between internal networks
and rules that only exempt traffic are not port forwards: callers read every
entry as "reachable from outside". "ANY" forwards every protocol and an
external port of 0 every port -- a whole host forwarded is the most exposed
case and must not fall out for lack of a port number.
Declaration only, under TYPE_CHECKING: nothing changes at runtime.
Some switches list only their member ports, each tagged with the trunk
it belongs to, and never the trunk itself. procurve over CLI is one:
`show interfaces brief` has `3-Trk3` and `4-Trk3` but no `Trk3`. Its
REST path already built the trunk row itself, in code no other driver
could reach.
Grouping members by `trunk_group` into one entry per group is the same
for every vendor, so it lives here once. The entry is up/enabled if any
member is, its speed is the members' sum, and `lag_members` is in port
order. A LAG the driver already reported is left alone.
`lag_mode` is set only when the driver passes it. netOrk shows a missing
mode as "static trunk", but a guessed "trunk" would label an LACP group
wrongly, and a label that looks sure when nothing is known is worse.
A free function, not a SwitchDriver method: role bases are declarations
only (test_role_contracts), like normalize_cidr beside DhcpServerMixin.
HostRebootMixin declares reboot_host(), mixed into DeviceTypeDriver so
any device may be restartable. netOrk restarted hosts by sending
/sbin/reboot through a driver's private _send_command; a driver talking
to an API had no such method and the reboot was silently skipped.
HypervisorDriver gains GUEST_AGENT_PACKAGES / GUEST_AGENT_RUNCMD, the
agent cloud-init installs so the hypervisor can read a new VM's IP.
The default stays qemu-guest-agent; VMware declares open-vm-tools.
NetworkTargetDict.kind may be "portgroup": a VMware port group fixes its
VLAN like an SDN vnet does, without being one.
VMDict.vmid and VMConfigDict.vmid were int. Proxmox numbers its guests,
but VMware identifies a VM by UUID, which an int cannot hold. The
provisioning dicts already carried vmid as a string; the read side now
matches. Proxmox reports "100".
VMConfigDict gains optional hardware details -- os_name, cpu_type,
sockets, cores_per_socket, firmware, machine and passthrough (PCI/USB,
as VMPassthroughDict) -- so netOrk's VM hardware view can be filled by
any hypervisor instead of reading Proxmox's raw config through the
driver's private API.
Also fixes the README's hypervisor example, which still named the
pre-contract snapshot_create.
BREAKING CHANGE: VMDict.vmid and VMConfigDict.vmid are str.
Two endpoint device types had nowhere to go and were filed under
AccessPointDriver for want of anywhere better — a Yealink desk phone and a Sonos
speaker. netOrk reads the access-point role to decide what appears in its
wireless page, its AP profile pickers and its SSID drift view, so both showed up
in all three. PhoneDriver and MediaDriver give them an honest home; each
declares the surface its one existing driver actually implements, so the
contract is real rather than aspirational.
DeviceTypeDriver also gains two class attributes for facts netOrk kept as
hardcoded driver-name sets on its own side (netork#113):
USES_SSH whether netOrk reaches the device over SSH or a REST
API — transport, which is why it is not a role
REBOOT_SETTLE_SECONDS how long a reboot takes before polling is worth
attempting again
Both are driver facts and belong with the driver. A new driver is handled
correctly without anyone remembering to extend a list in netOrk.
A role base used to fill its methods with `raise NotImplementedError`. That is
not neutral under multiple inheritance: the placeholder wins the MRO against a
sibling base's working implementation and silently replaces it. Adding one stub
to a base was therefore a breaking change for every driver mixing that base with
another, and it broke three of them — OpenWrt grew seven forwarding methods,
QNAP one, and OpenMediaVault avoided inheriting StorageDriver at all.
Role bases now declare their surface under `if TYPE_CHECKING` and implement
nothing. There is no longer anything to shadow, so a device can finally say what
it is:
class QnapQtsDriver(StorageDriver, HypervisorDriver, LinuxDriver):
The order of those bases is the ranking, read back by roles_of(),
role_keys_of() and primary_role_of() in the new roles module. Nothing restates
it: no precedence table, no attribute to override.
Two consequences, both wanted. `hasattr` is a truthful capability probe again,
because a method exists exactly when a driver provided it. And a method that was
never implemented now raises AttributeError rather than NotImplementedError, so
callers should ask before calling.
Shared behaviour moves out of the roles and into function classes, each holding
it once: PackageManagementMixin (was five byte-identical copies),
HealthMetricsMixin (five), ServiceControlMixin, UpdateMixin, NatVpnMixin,
MacAclMixin, FirewallRuleMixin, InterfaceFilterMixin.
BREAKING CHANGE: methods whose contract genuinely differed were renamed apart —
StorageDriver.get_services -> get_storage_services, the storage and hypervisor
snapshot writers -> create/delete/rollback_{volume,vm}_snapshot,
HypervisorDriver.get_storage -> get_vm_storage_pools, get_snapshots ->
get_vm_snapshots, SwitchDriver.get_dot1x_config -> get_dot1x_ports. Two
duplicate names collapsed onto the one already in use: get_pending_updates ->
get_available_updates and remove_package -> uninstall_package.
Also fixes __doc__ being None on all seven role bases: TYPE_LABEL was assigned
above the triple-quoted string, which made it a bare expression rather than a
docstring.
A driver whose send_wake_on_lan() interface is not the name get_interfaces()
is keyed by leaves callers with no way to offer a valid choice. OPNsense keys
by the physical device ("em0") but wakes by the assigned name ("lan"), and
rejects the former — so the assigned name has to travel with the interface
data as an "identifier" key.
Part of netork#85. Reservations were the only DHCP desired state the mixin
knew about; this adds the layer above them — the ranges a device serves and
the options it publishes with them.
The identity is the CIDR, matched rather than compared, the way `mac` is for
a reservation. normalize_cidr deliberately does not rewrite the network
address: turning 10.10.20.5/24 into 10.10.20.0/24 would make a typo silently
match a real subnet and then apply that caller's pools and options to it.
option_data is compared per option, and only over the options the caller
named. An absent key means "not managed", not "should be empty" — without
that rule a caller managing only domain_search would diff against every
option the server autocollects (routers, domain_name_servers, ntp_servers)
and reconfigure the DHCP daemon on every single run.
Neither diff deletes. For subnets that is not merely conservative: removing
one takes DHCP down for a whole VLAN, and the diff cannot tell "no longer
wanted" from "was never this caller's to describe".
commit_dhcp_subnets is separate from commit_dhcp_reservations even where a
driver implements both with the same call — the two desired-state sets are
applied independently, and a caller that changed only subnets should not
have to know which reload the vendor happens to share.
19 new tests against an in-memory fake; no vendor driver needed.
Adds the generic half of DHCP reservation management: diff_dhcp_reservations
matches desired against live reservations by normalised MAC, and
apply_dhcp_reservationset walks the diff and commits once at the end.
Both are concrete here because neither is vendor-specific — only
get_dhcp_reservations/apply_dhcp_reservation/commit_dhcp_reservations touch
the device (Kea REST on OPNsense, dnsmasq/odhcpd UCI on OpenWrt).
Two deliberate choices:
- The MAC is the matching key, not a description as with firewall rules. A
reservation has a natural identity and this is it. That also means a host
moving to another VLAN is an update of the existing entry rather than a
second one for the same MAC.
- An empty diff skips the commit. Committing reloads the DHCP daemon and
drops in-flight requests, which is too high a price for a no-op run. This
differs from apply_firewall_ruleset, which always commits.
Live reservations with no desired counterpart are never reported for
deletion — a DHCP server routinely carries hand-created entries the caller's
desired set was never meant to describe.
Mixed into FirewallDriver and ResidentialGatewayDriver: both device types
commonly run the DHCP server for their networks.
Sweeping a range is orchestration, not device mechanics: the only
vendor-specific part is executing a single ping, and NAPALM already
standardises that. PingSweepMixin therefore owns the loop, the reply parsing,
the target cap and the progress reporting, and is mixed into DeviceTypeDriver
so any driver implementing ping() becomes a usable sweep source without
writing sweep code of its own.
driver_supports_ping() answers "can this driver ping?" by introspection
instead of a hand-maintained list, with SUPPORTS_PING = False as the opt-out
for a driver that inherits a ping it cannot actually use.
The generic implementation is deliberately sequential — a NAPALM connection is
a single session and not safe to drive from several threads at once. A driver
whose device offers something faster overrides ping_sweep and keeps the return
shape; see napalm-opnsense's batched job API version.
FirewallRuleDict/FirewallRuleDiffDict (models.py) plus three abstract
methods (get_firewall_rules/apply_firewall_rule/commit_firewall_rules)
concrete drivers implement, and two concrete methods every driver gets
for free: diff_firewall_rules() matches desired vs. live rules by
description and reports add/update (never delete -- a firewall may carry
manually-created rules a caller's desired set was never meant to
describe); apply_firewall_ruleset() orchestrates applying the diff and
yields progress lines, meant for streaming to a caller.
This is the generic reconciliation engine NetOrk's Firewall Profile
feature needs against OPNsense -- kept here instead of in
napalm-opnsense since the matching/comparison/orchestration logic is
identical for any firewall vendor that implements the three abstract
methods.
Makes explicit a rule that's been applied ad hoc: matching/comparison/
orchestration logic that's identical across every driver of a device-type
belongs as a concrete method on the abstract base class; only actual
device communication (REST/CLI/payload format) belongs in the concrete
vendor driver as an implementation of an abstract method. Uses the
upcoming FirewallDriver diff/apply mechanism as the worked example.
Abstract method for sending a Wake-on-LAN magic packet through a
firewall's driver connection, following the same contract style as
get_nat_translations/get_security_zones. Raises NotImplementedError
by default; concrete drivers implement it per their own API.
Replaces template-clone semantics (template: str, existing Proxmox template
VMID) with image_url: str — the driver now downloads the cloud image itself
and imports it as the VM's root disk, rather than requiring an admin to have
pre-built a template. Adds image_checksum for optional verification and a
separate download_timeout since image downloads can take much longer than
the rest of provisioning.
Returns selectable bridge/vnet targets for a new VM's NIC, distinguishing
real bridges (Linux, OVS) from SDN vnets, and exposing whether a NIC on that
target may additionally carry a vlan_tag (Linux bridge vlan_aware flag, OVS
always, SDN vnet never — the VLAN is already fixed by the vnet's zone/tag).
Add three new methods to HypervisorDriver:
- create_vm_from_cloud_init(): provision VM from template with dual-NIC config
- destroy_vm(): stop and remove VM with optional disk cleanup
- get_vm_status(): poll runtime status, optionally wait for IP via guest-agent
New TypedDicts VMProvisionResultDict and VMStatusDict in models.py
document the provisioning API contract.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
The comment said AccessPointDriver sits BEFORE mixins, which was wrong after
the mixin refactor. NetworkDriver (parent) raises NotImplementedError for
standard NAPALM methods, so AccessPointDriver must come LAST in the MRO to
avoid shadowing mixin implementations.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
These three methods were defined with `raise NotImplementedError` in
AccessPointDriver. Because AccessPointDriver appears before the mixin
classes in the MRO of concrete drivers (e.g. OpenWrtDriver), this caused
the abstract body to be called instead of the mixin implementation.
Symptoms:
- get_radio_status() → NotImplementedError, silently caught in poll →
radio_snapshot never updated after the initial snap
- get_ssids() / get_wireless_clients() → same silent failure
Fix: remove the method bodies from AccessPointDriver entirely. Python then
continues the MRO search and finds the correct mixin implementation.
The comment documents the invariant so it is not accidentally re-introduced.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Neue Zwischenschicht zwischen NetworkDriver und den typ-spezifischen
Basisklassen (FirewallDriver, SwitchDriver, …). Definiert das
Fingerprinting-Interface für den Discovery-Subsystem:
- FingerprintRule (NamedTuple): pattern, weight, mandatory, negative
- PortSpec (NamedTuple): scheme, port, paths, weight, mandatory
- DeviceTypeDriver: VENDOR, DRIVER_NAME, PORT_SPECS, SNMP_OBJECT_ID_PREFIX,
SNMP_FINGERPRINT, SSH_FINGERPRINT, HTTP_FINGERPRINT
Alle *Driver-Klassen erben jetzt von DeviceTypeDriver statt NetworkDriver.
Transitiv ist NetworkDriver weiterhin in der MRO (keine Breaking Change).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Each abstract base class now carries a TYPE_LABEL: str attribute that
describes the device category in human-readable form:
AccessPointDriver → "Access Point"
FirewallDriver → "Firewall"
HypervisorDriver → "Hypervisor"
OSDriver → "OS"
ResidentialGatewayDriver → "Gateway"
StorageDriver → "Storage"
SwitchDriver → "Switch"
Concrete drivers can override TYPE_LABEL to express a more specific
category (e.g. LinuxDriver sets "Linux"). The backend reads this
attribute to expose a type_label in the DriverInfo API response,
replacing the hardcoded DRIVER_TYPE map in the frontend.
23 tests covering presence, value, inheritance, and override.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds the abstract set_lag_members() method (with docstring) implemented
by the ProCurve, NetGear and TP-Link Jetstream drivers for managing
LAG/trunk port membership.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Defines the driver-level health metrics interface across all base classes.
OSDriver/FirewallDriver/HypervisorDriver/AccessPointDriver get a default
UCD-MIB + IF-MIB implementation via shared _ucd_metrics.py; SwitchDriver
raises NotImplementedError (vendor-proprietary OIDs). Adds HealthMetricsDict
and HealthMetricsIfaceDict TypedDicts to models.py.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Introduce OSDriver abstract base class (os.py) for general-purpose OS
drivers (Linux, BSD, macOS) — registers package management, service
management, users, processes, cron job and the two new OS-specific
extension points
- Add get_docker_info() contract: returns DockerInfoDict covering
containers, images, volumes, networks and outdated image detection
- Add run_device_action() contract: generic extensibility point for
driver-specific one-off administrative actions
- Fix duplicate TypedDicts in models.py: remove early shadow definitions
of UserDict, ProcessDict, CronJobDict, ApplyUpdatesResultDict from the
Common section; keep the more complete definitions in the OS section
- Add Docker TypedDicts: DockerContainerDict, DockerImageDict,
DockerVolumeDict, DockerNetworkDict, DockerInfoDict
- Add DeviceActionResultDict
- Export OSDriver from package __init__; bump version to 0.3.0
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add ServiceDict and UpdateDict TypedDicts to models
- Add get_services() / manage_service() abstract methods for init-system interaction
- Add get_available_updates() / apply_updates() for package upgrade workflows
- Add _filter_interfaces() helper to exclude lo and phy* interfaces from interface dicts
- Extend WirelessClientDict with optional ip, hostname, and lease_end fields
- Add optional description field to VPNTunnelDict
- Bump version 0.1.0 → 0.2.0
