Christian Manivong 991e07043f
driver / standard (pull_request) Successful in 15s
driver / lint (pull_request) Successful in 13s
driver / test (3.12) (pull_request) Failing after 15s
driver / test (3.13) (pull_request) Failing after 13s
driver / types (pull_request) Failing after 25s
driver / lowest (pull_request) Failing after 19s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Failing after 36s
CI / driver (pull_request) Failing after 1m10s
driver / publish (pull_request) Skipped
feat(scheduled-jobs): FreeBSD and OpenBSD through PosixScheduledJobsMixin (#27)
get_scheduled_jobs reads /etc/crontab and the user crontabs in
/var/cron/tabs, on FreeBSD also both cron.d directories and every
periodic script, in one round trip as root; manage_scheduled_job
enables, disables or runs one now; put_ and delete_scheduled_job write
and remove an application's own job (/etc/cron.d on FreeBSD, marked
lines in the user's crontab on OpenBSD).

A periodic script is what FreeBSD runs daily, weekly, monthly and for
the security run; it does its work only when its periodic.conf knob
says YES, so that knob is its enabled state, written with sysrc to
/etc/periodic.conf. A later periodic.conf that still overrides it is
reported instead of claimed as done. A script whose knob is not known
only runs; one whose knob is off does nothing when run and offers no run.

BSD su takes no shell (FreeBSD's -s is a MAC label) and -m starts
root's own shell, csh on many FreeBSD hosts, so another user's job goes
to /bin/sh on stdin. OpenBSD cron's -n/-q/-s flags are left off when a
line runs now. What the base system ships is platform: FreeBSD's
/etc/crontab and /etc/periodic, OpenBSD's newsyslog and
/etc/daily|weekly|monthly lines, which stay one job each.

get_cron_jobs goes: it read without root and missed cron.d, every other
user and periodic.

Requires napalm-device-types 4.26.0.

Closes #27
2026-11-03 05:53:01 +01:00

napalm-bsd

NAPALM drivers for FreeBSD (freebsd) and OpenBSD (openbsd) hosts, over SSH, built on napalm-device-types' OSDriver, in the role bsd (one for both systems). Written for netOrk, which provisions and manages BSD VMs (NetOrk/netork#792).

Design

  • One shared BsdDriver (napalm_bsd/base.py) holds the SSH layer and every reader whose tools agree between the BSDs. FreeBSDDriver and OpenBSDDriver name only the commands that differ (hostname, release, kernel, hardware, netstat -rnW vs -rn).
  • Every command runs on its own SSH exec channel (run_on_transport from napalm-device-types): no PTY to parse a prompt from, stdout and stderr apart, a real exit status. run_command() / open_stream() are public (CommandChannelMixin).
  • Root comes from sudo -S with the sudo password on stdin (never on a command line), or sudo -n without one, as in napalm-linux. netOrk provisions sudo on BSD VMs for that reason; doas cannot read a password from stdin.
  • Parsing is in napalm_bsd/parse.py, pure functions tested on output recorded from real systems (tests/fixtures/, each directory's COMMANDS.txt lists what produced it).

Supported getters

Getter FreeBSD OpenBSD Source
get_facts ✓ ✓ kern.hostname/hostname, freebsd-version/uname, kenv smbios.*/hw.*, kern.boottime
get_interfaces, get_interfaces_ip ✓ ✓ ifconfig -a
get_route_to ✓ ✓ netstat -rnW / netstat -rn
get_arp_table ✓ ✓ arp -an
get_lldp_neighbors {} {} no LLDP daemon in either base system
get_os_users, get_processes ✓ ✓ /etc/passwd+/etc/group, ps … lstart
get_scheduled_jobs ✓ ✓ /etc/crontab, /var/cron/tabs/*; FreeBSD also /etc/cron.d, /usr/local/etc/cron.d and every periodic script with its periodic.conf knob (napalm-device-types' PosixScheduledJobsMixin)
manage_scheduled_job(key, action, digest=) ✓ ✓ enable, disable, run now; a periodic script by sysrc -f /etc/periodic.conf
put_scheduled_job(spec) / delete_scheduled_job(key, digest=) ✓ ✓ an application's own job: a file in /etc/cron.d (FreeBSD), marked lines in the user's crontab (OpenBSD)
get_listening_sockets ✓ ✓ sockstat -46lq / fstat -n as root, netstat -an without
get_packages, install_package, uninstall_package ✓ ✓ pkg query / pkg install, pkg delete; pkg_info / pkg_add -I, pkg_delete
get_available_updates ✓ ✓ pkg upgrade -n + pkg audit (VuXML); pkg_add -u -n -v + syspatch -c
get_services, manage_service ✓ ✓ service -e + service … status / service … <action>; rcctl ls on + rcctl check / rcctl <action>
run_device_action("fix_snmp"), get_snmp_config ✓ ✓ net-snmp from packages: /usr/local/etc/snmp/snmpd.conf + service snmpd; /etc/snmp/snmpd.conf + rcctl … netsnmpd
get_host_status ✓ unknown napalm-device-types' host status: on FreeBSD freebsd-version -k vs -r (4.1+)
first_boot_pending ✓ always False whether /firstboot still exists

get_listening_sockets has the shape of napalm-device-types' ListeningSocketsMixin (whose ss/cgroup reading is Linux's) and its rule: read as root first, without root when that brings nothing back (attributed: False). FreeBSD's sockstat sees every socket either way; OpenBSD's fstat shows a user only their own processes, so without root the sockets come from netstat -an, unnamed.

There is deliberately no get_kernel_facts: KernelFactsMixin reports a Linux kernel's modules and CONFIG_* options, which a BSD kernel does not have, and hasattr(driver, "get_kernel_facts") has to stay truthful.

Updates. security on FreeBSD comes from VuXML (pkg audit): True for a package it lists as vulnerable, False for one it does not, None when the audit could not run. OpenBSD's tools do not say, so it is None there. Base-system patches are one entry, base-system (NetOrk/netork#799): OpenBSD's syspatch applies its patches together and in order; a classic FreeBSD base reports what freebsd-update has fetched (updatesready). On FreeBSD with pkgbase the base system is packages from the FreeBSD-base repository and needs no extra entry.

A reader that cannot read raises rather than return an empty list: netOrk takes [] as "no updates" and would close every patch clock on the host. That covers a refused sudo, a failing pkg, syspatch or freebsd-update, and a pkg database pkg cannot read (only pkg's "not installed" means no packages).

Reboot. get_host_status reports a FreeBSD host whose installed kernel (freebsd-version -k) differs from the running one (-r) as needing a reboot. OpenBSD has no such reading yet, so it stays unknown there.

First boot. A FreeBSD cloud image upgrades its base system on its first boot, starts sshd only after that and restarts right away. /etc/rc removes /firstboot just before the restart, so first_boot_pending() is true until then; netOrk waits for it before it sets up a new VM. OpenBSD has no such marker to ask yet.

Scheduled jobs are read in one round trip as root. A job the application did not write may be enabled, disabled and run, never edited or deleted. What the base system ships is platform: FreeBSD's /etc/crontab and /etc/periodic/*, and the newsyslog, /etc/daily, weekly and monthly lines of OpenBSD's root crontab (which run the .local files themselves, so those are not jobs of their own). On FreeBSD a periodic script is a job of its own, switched by its <period>_<name>_enable knob (security_status_<name>_enable for the security scripts, or the one knob the script names); a script whose knob is not known only runs, and one whose knob is off does nothing when run, so it does not offer run. A job of another user runs through su -m <user> with its script on /bin/sh's stdin: neither BSD's su takes a shell, and -m starts root's own (csh on many FreeBSD hosts). OpenBSD cron's -n, -q and -s flags are left off when a line runs now. timeout(1) bounds a run on both (OpenBSD 7.0 and later).

Services are the enabled ones. FreeBSD reads their status as root, as root-only pidfiles hide a daemon from anyone else, and without root when sudo refuses; OpenBSD's rcctl check needs no root. Actions run as root.

SNMP is net-snmp from packages (NetOrk/netork#800), configured as netOrk does on Linux (v2c, community public, every address), so the agent answers UCD-SNMP-MIB for netOrk's health metrics. Memory, swap and load are right on both systems. CPU: FreeBSD reports ssCpuIdle about a minute after the agent starts; on OpenBSD net-snmp's CPU figures are wrong (0 % idle on an idle machine, also in hrProcessorLoad), so OpenBSDDriver's SNMP_HEALTH_PROFILE marks the CPU unknown and the application reports none.

Connection arguments

optional_args: port (22), key_file, sudo_password, allow_agent, look_for_keys (both off by default).

Development

pip install -e ".[dev]"
pytest
S
Description
NAPALM drivers for FreeBSD and OpenBSD hosts via SSH
Readme
647 KiB
0 Stars 1 Watchers 0 Forks
2026-10-23 12:52:46 +00:00
Languages
Python 100%