get_local_accounts(names) reads a person's account back: groups, lock,
sudo, key files. add_local_account() creates or reopens one with the
person's key, optional password hash and optional sudo rule;
lock_local_account() takes the keys and sudo away and refuses every
login, keeping the home.
Every command root runs is one fixed command, so a sudoers allowlist can
name it. The key files are read and written as the person (sudo -n -u),
never as root, since a link in a home the person owns may point anywhere.
The sudo rule is a drop-in of its own, checked with visudo before and
sudo -l after; a rule elsewhere (cloud-init's) is reported, not edited.
The login user's own account and system accounts are refused.
A driver supplies creating, opening, locking, reading the lock and
leaving a group.
A driver that typed `echo '<password>' | sudo -S -p "" <command>` into an
interactive shell left that line, password and all, in the login user's
shell history once per command, and where only the part before the first
`&&` ran as root, files root should own were left to the login user.
get_history_sudo_lines() counts the lines per history file with grep -c,
as the login user, without reading any back. remove_history_sudo_lines()
deletes exactly those lines with sed -i, overwrites the backup with
shred -u, and as root gives the driver's SUDO_ROOT_FILES back to root:root
where each is a regular file, not a link, owned by the login user. It
reports each file's lines before and after. Nothing goes to stdin.
The driver names the marker and the files and supplies run_command.
A VM on a VLAN-aware bridge without a VLAN tag only gets an address when
the switch port behind the bridge carries an untagged network. To find
that port, the caller needs the bridge's physical NICs: their LLDP
neighbours name the switch and the port.
uplinks lists them in groups, one per way out of the bridge: a bond's
slaves together, a single NIC alone. A bond is one link, so a caller can
let one slave's neighbour speak for the others when lldpd sees only one.
Internal, VLAN and virtual ports are no uplinks. A missing key means the
driver cannot tell; an empty list is a bridge without uplink.
NAPALM requires an age on every entry of get_arp_table and
get_ipv6_neighbors_table. Many devices do not report one, and drivers
filled in 0.0, which means "confirmed just now". ARP_AGE_UNKNOWN (-1.0, as
NAPALM's IOS driver reports) is the value for "not reported"; the README
states the contract.
NetOrk/netork#1327
netOrk runs every driver in its own containers on Python 3.12, so 3.10
and 3.11 are no longer supported or tested. requires-python, mypy and
ruff move to 3.12, along with what ruff's pyupgrade rules then rewrite.
HostShutdownMixin.shutdown_host(), on DeviceTypeDriver: a device shuts
itself down cleanly through its own means; declared, so hasattr says
whether a driver can. There is no forced variant.
VmStopRequestMixin.begin_stop_vm(name): ask for a VM's clean shutdown
and return at once, for a caller that waits on a timer and reads
get_vm_status instead of blocking in stop_vm. No role demands it.
For netOrk's graph workflows, which switch a hypervisor off when CI has
nothing for it (NetOrk/netork#1636).
The NAPALM driver standard landed on main (#52, 4.21.1). apt_proxy follows
it: builtin generics, strict mypy, complexity 10 at most (parse_apt_proxy,
same_proxy_url and the comment-out step split into helpers), 100 % covered.
Its TypedDicts live in apt_proxy.py, since models.py is over 1000 lines and
may not grow. Version 4.22.0 with its CHANGELOG section.
apt reads apt.conf.d in order and apt.conf last; the last value wins. The
Debian installer writes its proxy into apt.conf, Ubuntu's into
90curtin-aptproxy: reading 00proxy alone missed both, and a fix that wrote
00proxy and read it back reported success while apt fetched elsewhere.
- get_package_proxy_report(): apt-config dump's proxy, per-host overrides,
auto-detect, every line of apt's files that sets it (in reading order,
editable or inside a block), the http and https sources.
- check_package_proxy(url, expect): a fetch with apt-helper, past any proxy;
an HTTP error counts as an answer.
- configure_package_proxy(url): write 00proxy, comment out other proxy
lines, read apt's proxy back, fetch one InRelease through it.
- same_proxy_url(): scheme, host and port, a trailing slash aside.
A driver supplies _run_apt_command, _run_apt_root_command and
_write_apt_file. Version 4.22.0.
- CI moves to .gitea/workflows/ci.yml and calls the shared driver workflow
of NAPALM/driver-standard: conformance, ruff, strict mypy, tests on
3.10-3.13 and at the lowest declared versions, bandit, pip-audit, build,
and on a release tag the upload to PyPI.
- tests/quality_baseline.json records today's long and complex functions
and the one file over 1000 lines; they may shrink, not grow.
- Coverage floor 95 % (measured 95.15 %).
- CHANGELOG.md starts here; project links point at git.netork.io; the
license is the SPDX string PEP 639 wants.
- Long docstring and command lines are wrapped; recorded device output in
tests/ keeps its lines (E501 is off there).
- host_firewall: the negation token is the named constant _NEGATION. bandit
read token == "!" as a hardcoded password.
- ssh_host_keys: _known_hosts_file takes the expected key as an argument
instead of asserting it; both callers had already returned when it is None.
- ssh_server: the staged path is on the device, not a local temp file
(nosec B108).
- tests: raise ... from exc, zip(strict=True).
Mechanical: ruff format, and ruff check --fix with the rule set every NAPALM
driver uses (E, F, I, UP, B at line length 100). typing.List/Dict/Optional
become builtin generics and X | None, imports are sorted, the coding cookies
are gone. Two tests that read the source text follow the new spelling.
What ruff cannot fix comes in the next commit.
get_host_firewall() reads `nft -j list ruleset` as root and returns every
chain with its family, table, hook, priority and policy, and every rule as
matches and a verdict. Rules iptables-nft wrote show their extensions in nft's
JSON only as an opaque `xt`, so the tables iptables manages are taken from
iptables-save instead; a legacy iptables is kept beside nft's tables, since
both apply. A condition the parse does not model is an `unknown` match with
its text, never left out. Without root neither tool can be read, and
HostFirewallUnavailable is raised rather than a host without rules.
A driver supplies only _run_host_firewall_command(command, privileged=).
Version 4.21.0.
get_service_packages() returns, per systemd service, the installed packages
it is made of: the one shipping its unit file and the one shipping the
binary its ExecStart runs -- not the libraries that binary links against.
One read-only command: systemctl show for every loaded service unit, then
one dpkg -S for all paths (each also across the /usr merge), or rpm -qf per
path. The report is framed; one cut short raises. A driver supplies
_run_service_packages_command, as for KernelFactsMixin.
Version 4.20.0.
Drivers get the host keys to expect in optional_args["ssh_host_keys"] (by port)
and report what they saw through optional_args["ssh_host_key_observer"].
With a known key, any other key is refused before authentication
(SshHostKeyMismatch); without one, the first key is accepted. One
implementation for paramiko (HostKeyCheck.connect) and netmiko
(HostKeyCheck.netmiko + observe). A caller or driver that ignores both keys
keeps working as before.
Version 4.19.0.
feat/service-clusters (#47) and feat/opnsense-public-contracts (#46) both
called themselves 4.17.0 and were merged one after the other: two trees
under one version. 4.17.0 stays the public contracts (83cd7db, pinned by
netOrk for #1113); the service clusters on top of it are 4.18.0.
ServiceClustersMixin.get_service_clusters() -> ServiceClustersDict
{patroni, adguardhome_sync, bunkerweb}: per mechanism the clusters the
host's configuration says it belongs to, each with its members (address,
port, name, role as the mechanism words it, this_host, config_from) and the
unit or container it was read from (source).
- Patroni: scope, name and restapi.connect_address from its YAML, then the
members and roles /cluster lists from the DCS.
- adguardhome-sync: ORIGIN_URL and REPLICA*_URL; the origin pushes to each
replica.
- BunkerWeb: a worker's API_WHITELIST_IP names the manager it admits, a
manager's BUNKERWEB_INSTANCES its workers.
Two hosts answering at one virtual IP prove nothing; this is the evidence
that they run one service (NetOrk/netork#1125). One generic command for
every Linux host, filtered on the host like the virtual IPs' one:
allowlisted fields only, URLs without user:password@, DCS endpoints stay
there. Root first, then without it; None per mechanism is "did not look".
An application followed a firewall's upgrade, edited its resolver's
forwards and read its OSPF state through the driver's private REST
helpers (NetOrk/netork#1113). Declared contracts, neutral shapes:
- UpdateMixin.get_update_progress() -> UpdateProgressDict {state, log}
for an update apply_updates only starts.
- DnsForwardMixin: get_dns_forwards(), set_dns_forward(domain, server,
port), remove_dns_forward(domain); the driver applies.
- OspfMixin.get_ospf() -> OspfDict {router_id, areas, interfaces}; the
routing daemon's format is the driver's to translate.
All declared only.
FirmwareOfferMixin.get_firmware_offer() -> FirmwareOfferDict
{current_version, latest_version, newer, download_url?}: what runs and
the newest firmware the vendor offers, from its download catalogue or
the device's own update check. Comparing vendor version strings stays
with the driver, so it says whether the offer is newer; whether that is a
warning is the application's call (NetOrk/netork#1111). Declared only.
LicenseDict gets withholds: NotRequired[List[str]]: what a device keeps back
for want of a license while the rest of it answers. A Supermicro X10 with
only SFT-OOB-LIC answers Redfish but withholds its drives and firmware
inventory until DCMS is activated. That makes it partly licensed, not
unlicensed, and the caller can tell the two apart (NetOrk/netork#1111).
Drivers report facts and the application decides what is a warning
(docs/STRUCTURE.md, NetOrk/netork#1111). Three facts drivers so far
only reported as warning codes get contracts:
- LicenseMixin.get_licenses(): licenses and subscriptions with their
status (a Proxmox subscription, a VMware edition, a BMC license a
feature needs).
- HypervisorDriver.get_hypervisor_hosts(): each host connected, in
maintenance, with configuration issues, under a central manager.
- PackageProxyMixin.get_package_proxy(): the proxy apt fetches through.
All declared only.
run_device_action was a string dispatch drivers filled with an
application's remediations, values hard-coded inside (community
"public", the caller's address, a /24 firewall rule).
napalm_device_types.fixes declares them as templates instead. A
template runs declared steps in order and stops at the first failure
(run_fix_steps); the driver implements the steps, or overrides the
whole method where its device takes the change in one call; every
value comes from the caller.
- SnmpAgentMixin.configure_snmp_agent(settings): install, configure,
firewall, start. The caller verifies with its own SNMP client.
get_management_peer() (optional) says the address the device sees the
management connection come from, for choosing allowed_sources.
- EnsurePackageMixin.ensure_package(name): install only what is missing.
- PackageProxyMixin.configure_package_proxy(url): declared.
- ContainerEngineMixin.grant_container_engine_access(user): declared.
None is mixed into a role base, so a capability check stays truthful.
Closes#33
Drivers no longer collect over SNMP (docs/STRUCTURE.md). A driver whose
device publishes its health values under OIDs of its own declares them
as SNMP_HEALTH_PROFILE: per value either scalars asked in order or a
table folded by first, average or max, optionally with a pattern for
text answers; memory as total with used or free, or a percentage, in
KiB or bytes; and how to read the interfaces. The application polls
and computes.
HealthMetricsMixin.get_health_metrics now warns that it is deprecated;
it goes in 5.0.
Closes#32
get_dhcp_ha (declared on DhcpServerMixin, optional) is what a DHCP
server's own HA configuration says: on or off, this server's peer name,
each peer's name, role as the server words it, and HA URL.
ConfigSyncMixin.get_config_sync is where a host pushes its configuration
and for which services, by the names get_services reports; sync items
without a service name stay visible under `unmapped`. A driver mixes it
in, no role promises it. Both raise when they could not read.
What the facts mean for a pair -- hot standby, which side to write to --
is the caller's (NetOrk/netork#1125).
carp_virtual_ip() and its state table are CARP protocol knowledge; under the
agreed structure (PR #37, docs/STRUCTURE.md) the base package carries only
contracts, data shapes and I/O-free reconcilers. They move to the driver that
speaks CARP (napalm-opnsense). The contract stays: VirtualIpsDict.carp and
VirtualIpDict.holds.
Nothing used the helper yet; it was released in 4.10.0 an hour ago.
netOrk #1121.