Files
napalm-bsd/napalm_bsd/periodic.py
T
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

283 lines
11 KiB
Python

"""FreeBSD's ``periodic``: every script it runs is a scheduled job (#27).
``periodic daily`` (and weekly, monthly; ``security`` from the daily run) runs
each executable file in ``/etc/periodic/<period>`` and
``/usr/local/etc/periodic/<period>``. A script does its work only when its knob
in ``periodic.conf`` says ``YES``: defaults in ``/etc/defaults/periodic.conf``,
overrides in ``/etc/periodic.conf`` and the files after it. So a script is a job
of ``kind="periodic"``, enabled by its knob; enabling and disabling it writes
``/etc/periodic.conf`` with ``sysrc``; running it runs the script, as periodic does.
**The knob** is ``<period>_<name>_enable`` (``security_status_<name>_enable`` for
the security scripts), the name without its number and with ``_`` for ``-``. A
script that names none of these but exactly one ``<period>_…_enable`` has that one
(``480.leapfile-ntpd``: ``daily_ntpd_leapfile_enable``). A script whose knob is not
known this way is only run. A script whose knob is off does nothing when it runs,
so it does not offer ``run`` until it is enabled.
The scan runs after the cron report in the same round trip, as root; the knobs
are read the way periodic reads them, by sourcing its configuration in a subshell.
"""
from __future__ import annotations
import re
from dataclasses import dataclass, field
from shlex import quote
from typing import ClassVar
from napalm_device_types.channel import CommandResult
from napalm_device_types.scheduled_jobs import (
ACTIONS,
RUN_TIMEOUT,
ScheduledJobRefused,
ScheduledJobResultDict,
job_digest,
)
from napalm_device_types.terminal import strip_terminal_codes
from napalm_bsd.scheduled_jobs import BsdScheduledJobsMixin
PERIODS = ("daily", "weekly", "monthly", "security")
PERIODIC_DIRS = tuple((p, f"/etc/periodic/{p}") for p in PERIODS) + tuple(
(p, f"/usr/local/etc/periodic/{p}") for p in PERIODS
)
PERIODIC_DEFAULTS = "/etc/defaults/periodic.conf"
PERIODIC_CONF = "/etc/periodic.conf"
_BEGIN = "PERIODIC_BEGIN"
_END = "PERIODIC_END"
#: A knob as a script names it, with the default it gives it (``${x:-YES}``).
_REF = "(daily|weekly|monthly|security)_[A-Za-z0-9_]+_enable(:?-[A-Za-z]+)?"
_REF_PARTS = re.compile(r"^([A-Za-z0-9_]+_enable)(?::?-([A-Za-z]+))?$")
_KNOB = re.compile(r"(daily|weekly|monthly|security)_[A-Za-z0-9_]+_enable")
_SECTION = re.compile(r"^\[(script|conf|read|owners)(?: (.*))?\]$")
_SWITCH = ["enable", "disable", "run"]
def _scan(period: str, directory: str) -> str:
return (
f'for f in {quote(directory)}/*; do [ -f "$f" ] && [ -x "$f" ] || continue; '
'c=$(cksum < "$f" | cut -d" " -f1); '
f'printf \'[script %s %s %s]\\n\' {period} "$c" "$f"; '
f"k=$(grep -oE '{_REF}' \"$f\" | sort -u); "
"for r in $k; do printf '|%s\\n' \"$r\"; done; "
'K="$K $k"; Q="$Q\n$f"; done; '
)
def _source(defaults: str) -> str:
"""``sh`` that reads periodic's configuration as periodic does; prints nothing."""
d = quote(defaults)
return f"if [ -r {d} ]; then . {d}; source_periodic_confs; fi >/dev/null 2>&1 </dev/null"
def reading_command(dirs: tuple[tuple[str, str], ...], defaults: str, owners_sh: str) -> str:
"""``sh`` that prints every periodic script, the knobs it names and their values."""
parts = ["printf '%s%s\\n' PERIODIC_ BEGIN; K=''; Q=''; "]
parts += [_scan(period, directory) for period, directory in dirs]
parts.append(
f"echo '[conf]'; ( {_source(defaults)}; "
'for r in $K; do k=${r%%[:-]*}; eval "s=\\${$k+x} v=\\${$k-}"; '
'[ -n "$s" ] && printf \'|%s=%s\\n\' "$k" "$v"; done; echo \'[read]\' ); '
f"echo '[owners]'; printf '%s\\n' \"$Q\" | sed '/^$/d' | {{ {owners_sh}; }}; "
"printf '%s%s\\n' PERIODIC_ END"
)
return "".join(parts)
def knob_of(period: str, path: str, refs: list[str]) -> tuple[str | None, bool]:
"""The knob that switches the script *path*, and whether it is on when unset."""
defaults: dict[str, bool] = {}
for ref in refs:
parts = _REF_PARTS.match(ref)
if parts:
on = (parts[2] or "").lower() == "yes"
defaults[parts[1]] = defaults.get(parts[1], False) or on
name = re.sub(r"^\d+\.", "", path.rsplit("/", 1)[-1]).replace("-", "_")
for knob in (f"{period}_{name}_enable", f"{period}_status_{name}_enable"):
if knob in defaults:
return knob, defaults[knob]
own = [k for k in defaults if k.startswith(f"{period}_")]
if len(own) == 1:
return own[0], defaults[own[0]]
return None, False
@dataclass
class _Raw:
period: str
checksum: str
path: str
refs: list[str] = field(default_factory=list)
@dataclass(frozen=True)
class PeriodicScript:
"""A periodic script as a job, and what switching and running it need."""
job: dict[str, object]
knob: str | None
period: str
@dataclass
class _Report:
scripts: list[_Raw] = field(default_factory=list)
conf: dict[str, str] = field(default_factory=dict)
owned: set[str] = field(default_factory=set)
read: bool = False
def _take(report: _Report, section: str, value: str) -> None:
if section == "script" and value:
report.scripts[-1].refs.append(value)
elif section == "conf":
knob, sep, setting = value.partition("=")
if sep:
report.conf[knob] = setting
elif section == "owners":
_package, sep, path = value.partition(": ")
if sep and path.startswith("/"):
report.owned.add(path.strip())
def _open(report: _Report, header: re.Match[str]) -> str:
"""The section *header* begins; a script's header names the script."""
if header[1] == "script":
period, checksum, path = (header[2] or "").split(" ", 2)
report.scripts.append(_Raw(period, checksum, path))
report.read = report.read or header[1] == "read"
return header[1]
def _report(output: str) -> _Report:
text = strip_terminal_codes(output)
begin, end = text.rfind(_BEGIN), text.rfind(_END)
if begin < 0 or end < begin:
raise ValueError("the periodic report is cut short (no end marker)")
report, section = _Report(), ""
for line in text[begin + len(_BEGIN) : end].splitlines():
header = _SECTION.match(line)
if header is not None:
section = _open(report, header)
elif section:
_take(report, section, line[1:] if line.startswith("|") else line)
if not report.read:
raise ValueError("periodic.conf could not be read")
return report
def _job(raw: _Raw, report: _Report) -> PeriodicScript:
knob, default_on = knob_of(raw.period, raw.path, raw.refs)
enabled, actions = True, ["run"]
if knob is not None:
value = report.conf.get(knob, "")
enabled = value.lower() == "yes" if value else default_on
actions = _SWITCH if enabled else ["enable", "disable"]
job: dict[str, object] = {
"key": f"periodic:{raw.path}",
"kind": "periodic",
"source": raw.path,
"run_as": "root",
"schedule": raw.period,
"schedule_kind": "period",
"command": raw.path,
"enabled": enabled,
"managed_by": "package" if raw.path in report.owned else "admin",
"actions": actions,
}
job["digest"] = job_digest(job, content=raw.checksum)
return PeriodicScript(job, knob, raw.period)
def parse_periodic(output: str) -> list[PeriodicScript]:
"""The periodic scripts of a report from :func:`reading_command`.
:raises ValueError: when the report is cut short or periodic.conf could not be read.
"""
report = _report(output)
return [_job(raw, report) for raw in report.scripts]
def _said(result: CommandResult) -> str:
return "\n".join(p for p in (result.stdout.strip(), result.stderr.strip()) if p)
class PeriodicJobsMixin(BsdScheduledJobsMixin):
"""Cron and FreeBSD's periodic scripts; see the module's docstring."""
PERIODIC_DIRS: ClassVar[tuple[tuple[str, str], ...]] = PERIODIC_DIRS
PERIODIC_DEFAULTS: ClassVar[str] = PERIODIC_DEFAULTS
#: Where enabling and disabling a script writes its knob.
PERIODIC_CONF: ClassVar[str] = PERIODIC_CONF
def _sj_extra_command(self) -> str:
return reading_command(self.PERIODIC_DIRS, self.PERIODIC_DEFAULTS, self.OWNERS_SH)
def _sj_extra_jobs(self, output: str) -> list[dict[str, object]]:
return [script.job for script in parse_periodic(output)]
def manage_scheduled_job(self, key: str, action: str, *, digest: str) -> ScheduledJobResultDict:
"""Enable, disable or run *key* now: a periodic script here, anything else as cron."""
if not key.startswith("periodic:"):
return super().manage_scheduled_job(key, action, digest=digest)
if action not in ACTIONS:
raise ScheduledJobRefused(f"unknown action {action!r}; allowed: {list(ACTIONS)}")
reading, output = self._sj_report()
job = self._sj_job(reading, key, digest)
if action not in job["actions"]: # type: ignore[operator]
raise ScheduledJobRefused(f"{key} cannot be told to {action} on this host")
script = next(s for s in parse_periodic(output) if s.job["key"] == key)
if action == "run":
return self._periodic_run(script)
return self._periodic_switch(script, action == "enable")
def _periodic_run(self, script: PeriodicScript) -> ScheduledJobResultDict:
# periodic exports what it runs for; ``security`` is spawned by the daily run.
runs_for = "security daily" if script.period == "security" else script.period
argv = [
"timeout",
str(RUN_TIMEOUT),
"env",
f"PERIODIC={runs_for}",
str(script.job["source"]),
]
result = self._sj_root(argv, timeout=RUN_TIMEOUT + 30)
said = _said(result)
if result.exit_code != 0:
return {"success": False, "output": said or f"exit {result.exit_code}"}
return {"success": True, "output": said or "ran"}
def _periodic_switch(self, script: PeriodicScript, enabled: bool) -> ScheduledJobResultDict:
knob = script.knob or ""
if not _KNOB.fullmatch(knob): # pragma: no cover - parse_periodic only takes these
raise ScheduledJobRefused(f"not a periodic knob: {knob!r}")
value = "YES" if enabled else "NO"
command = (
f"sysrc -f {quote(self.PERIODIC_CONF)} {knob}={value} || exit $?; "
f"( {_source(self.PERIODIC_DEFAULTS)}; printf 'now=%s\\n' \"${{{knob}-}}\" )"
)
return _switched(
self.run_command(command, privileged=True, timeout=60),
knob,
enabled,
self.PERIODIC_CONF,
)
def _switched(result: CommandResult, knob: str, enabled: bool, conf: str) -> ScheduledJobResultDict:
"""What writing *knob* did: sysrc's word, and whether periodic now reads it so."""
lines = result.stdout.strip().splitlines()
if result.exit_code != 0 or not lines or not lines[-1].startswith("now="):
return {"success": False, "output": _said(result) or f"exit {result.exit_code}"}
said = "\n".join(lines[:-1]).strip()
now = lines[-1].removeprefix("now=")
if (now.lower() == "yes") != enabled:
return {
"success": False,
"output": f"{said}\n{knob} is still {now or 'unset'}: "
f"a periodic.conf read after {conf} sets it".strip(),
}
return {"success": True, "output": said or f"{knob}={'YES' if enabled else 'NO'}"}