Compare commits

...
12 Commits
Author SHA1 Message Date
christianmanivong 4e40f95bc1 Merge pull request 'feat(scheduled-jobs): ScheduledJobsMixin and its POSIX implementation (#86), release 4.27.0' (#87) from feature/scheduled-jobs into main
driver / types (push) Successful in 59s
driver / standard (push) Successful in 15s
driver / lint (push) Successful in 14s
driver / test (3.12) (push) Successful in 1m6s
driver / test (3.13) (push) Successful in 1m0s
driver / lowest (push) Successful in 35s
driver / build (push) Successful in 30s
driver / security (push) Successful in 54s
driver / publish (push) Successful in 41s
CI / driver (push) Successful in 3m7s
2026-11-03 07:37:25 +00:00
christianmanivong 70e1c9b218 chore(release): 4.27.0
driver / lint (pull_request) Successful in 14s
driver / standard (pull_request) Successful in 17s
driver / types (pull_request) Successful in 1m0s
driver / test (3.13) (pull_request) Successful in 1m11s
driver / test (3.12) (pull_request) Successful in 1m20s
driver / lowest (pull_request) Successful in 40s
driver / build (pull_request) Successful in 34s
driver / security (pull_request) Successful in 1m5s
CI / driver (pull_request) Successful in 2m33s
driver / publish (pull_request) Skipped
Scheduled jobs (NetOrk/netork#1933): ScheduledJobsMixin, its POSIX
implementation and napalm_device_types.cron. 4.26.0 went out meanwhile
with the sshd drop-in change, so this is 4.27.0.
2026-11-03 08:34:14 +01:00
christianmanivong a70501ff60 Merge remote-tracking branch 'origin/main' into feature/scheduled-jobs
# Conflicts:
#	CHANGELOG.md
2026-11-03 08:33:52 +01:00
christianmanivong c6d119eb83 fix(scheduled-jobs): a monotonic timer as its unit file says it, OnUnitActiveSec
driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Successful in 13s
driver / types (pull_request) Successful in 57s
driver / test (3.12) (pull_request) Successful in 1m12s
driver / lowest (pull_request) Successful in 43s
driver / test (3.13) (pull_request) Successful in 1m14s
driver / build (pull_request) Successful in 27s
driver / security (pull_request) Successful in 1m8s
CI / driver (pull_request) Successful in 2m47s
driver / publish (pull_request) Skipped
systemctl show names a timer's monotonic settings by their properties,
OnUnitActiveUSec=3h; the schedule now reads as the unit file writes it.
Found on a live Ubuntu host.

Refs #86
2026-11-03 08:11:48 +01:00
christianmanivong 8e9d21c368 Merge pull request 'feat(ssh): SSHD_CONFIG_GENERATED keeps the hardening to the drop-in (#88), release 4.26.0' (#89) from fix/ssh-hardening-generated-config into main
driver / test (3.12) (push) Successful in 1m35s
driver / standard (push) Successful in 17s
driver / lint (push) Successful in 23s
driver / types (push) Successful in 2m7s
driver / test (3.13) (push) Successful in 1m41s
driver / lowest (push) Successful in 1m30s
driver / build (push) Successful in 1m5s
driver / security (push) Successful in 1m41s
driver / publish (push) Successful in 1m11s
CI / driver (push) Successful in 8m25s
2026-11-03 07:00:40 +00:00
christianmanivong 25f28297e4 chore(release): 4.26.0
driver / lint (pull_request) Successful in 13s
driver / standard (pull_request) Successful in 17s
driver / types (pull_request) Successful in 2m9s
driver / test (3.13) (pull_request) Successful in 2m2s
driver / test (3.12) (pull_request) Successful in 2m10s
driver / lowest (pull_request) Successful in 36s
driver / build (pull_request) Successful in 35s
driver / security (pull_request) Successful in 1m9s
CI / driver (pull_request) Successful in 3m28s
driver / publish (pull_request) Skipped
2026-11-03 07:56:46 +01:00
christianmanivong 847c902193 feat(ssh): SSHD_CONFIG_GENERATED keeps the hardening to the drop-in (#88)
A platform that writes sshd_config from its own database (OpenMediaVault)
had to opt out of harden_ssh_server altogether. Where that generated file
includes /etc/ssh/sshd_config.d, the drop-in is safe; only the fallback
that rewrites sshd_config itself would be undone on the next apply. With
SSHD_CONFIG_GENERATED set, a sshd_config without the include is left alone
and the result says why.
2026-11-03 07:56:46 +01:00
christianmanivong ffbb194300 fix(scheduled-jobs): a file without a last newline no longer swallows the next header
driver / standard (pull_request) Successful in 15s
driver / lint (pull_request) Successful in 14s
driver / types (pull_request) Successful in 1m4s
driver / test (3.12) (pull_request) Successful in 1m6s
driver / test (3.13) (pull_request) Successful in 1m4s
driver / build (pull_request) Successful in 32s
driver / lowest (pull_request) Successful in 41s
driver / security (pull_request) Successful in 1m13s
CI / driver (pull_request) Successful in 2m43s
driver / publish (pull_request) Skipped
GNU sed keeps a missing final newline, so the next section's header ran
on into the file's last line and its jobs were lost. The report ends
every such file with a newline of its own.

Refs #86
2026-11-03 05:50:44 +01:00
christianmanivong edef6cf07c fix(scheduled-jobs): write a linked crontab through its link, with the target's mode
driver / standard (pull_request) Successful in 16s
driver / lint (pull_request) Successful in 20s
driver / types (pull_request) Successful in 1m11s
driver / test (3.12) (pull_request) Successful in 1m25s
driver / test (3.13) (pull_request) Successful in 1m18s
driver / lowest (pull_request) Successful in 40s
driver / build (pull_request) Successful in 36s
driver / security (pull_request) Successful in 1m8s
CI / driver (pull_request) Successful in 2m54s
driver / publish (pull_request) Skipped
stat without -L gave the link's own mode, 777, and install replaced the
link with a plain file of that mode: cron ignores a file anyone may write,
so every job in it stopped (/etc/cron.d/vzdump on older PVE links to
/etc/pve/vzdump.cron). The file the link names is written instead.

Refs #86
2026-11-03 05:39:57 +01:00
christianmanivong df476a12f2 feat(scheduled-jobs): the install command, time zone, owners and platform sources are the driver's
driver / standard (pull_request) Successful in 17s
driver / lint (pull_request) Successful in 13s
driver / types (pull_request) Successful in 1m7s
driver / test (3.13) (pull_request) Successful in 1m4s
driver / test (3.12) (pull_request) Successful in 1m12s
driver / lowest (pull_request) Successful in 39s
driver / build (pull_request) Successful in 30s
driver / security (pull_request) Successful in 1m6s
CI / driver (pull_request) Successful in 2m48s
driver / publish (pull_request) Skipped
A BSD install takes -D as a destdir, OpenWrt keeps its time zone in uci
and its package database in opkg, and a platform's generated files are its
own; each is a class attribute a driver sets.

Refs #86
2026-11-03 05:33:14 +01:00
christianmanivong 834cb2e0ea fix(scheduled-jobs): an own job goes to /etc/cron.d only where the host has it
driver / standard (pull_request) Successful in 19s
driver / lint (pull_request) Successful in 15s
driver / types (pull_request) Successful in 1m12s
driver / test (3.12) (pull_request) Successful in 1m21s
driver / lowest (pull_request) Successful in 39s
driver / test (3.13) (pull_request) Successful in 1m21s
driver / build (pull_request) Successful in 32s
driver / security (pull_request) Successful in 1m7s
CI / driver (pull_request) Successful in 3m3s
driver / publish (pull_request) Skipped
BusyBox crond reads no /etc/cron.d, so an Alpine host without systemd
takes the job in the user's crontab instead of a file it would never run.

Refs #86
2026-11-03 05:30:19 +01:00
christianmanivong f573fa53d2 feat(scheduled-jobs): ScheduledJobsMixin and its POSIX implementation (#86)
driver / standard (pull_request) Successful in 20s
driver / lint (pull_request) Successful in 23s
driver / types (pull_request) Successful in 1m16s
driver / test (3.13) (pull_request) Successful in 1m18s
driver / test (3.12) (pull_request) Successful in 1m27s
driver / lowest (pull_request) Successful in 46s
driver / build (pull_request) Successful in 43s
driver / security (pull_request) Successful in 1m27s
CI / driver (pull_request) Successful in 3m11s
driver / publish (pull_request) Skipped
What a host runs on its own schedule as one shape: cron lines, run-parts
scripts, anacron, systemd timers, periodic, a platform's own jobs, Windows
tasks. Every job says who owns its definition and what the driver can do
to it; every write names the digest the caller saw and is refused when the
host's definition changed since.

PosixScheduledJobsMixin reads everything in one framed report as root,
switches a cron line behind #napalm-disabled:, a timer by systemctl and a
run-parts script by its execute bit, runs a job now bounded by timeout, and
writes an application's job as a timer where systemd runs, else in
/etc/cron.d or the user's crontab. napalm_device_types.cron parses cron
expressions, gives their next runs and writes them as OnCalendar lines.

get_cron_jobs and CronJobDict go: nothing called them.

Version 4.26.0, so drivers can require it before the release is tagged.

Closes #86
2026-11-03 05:29:27 +01:00
18 changed files with 2582 additions and 46 deletions

No files matched your search

+34
View File
@@ -7,6 +7,40 @@ recorded here; their history is the git log.
## [Unreleased]
## [4.27.0] - 2026-11-03
### Added
- `ScheduledJobsMixin`: what a host runs on its own schedule as one shape,
`ScheduledJobDict` — cron lines, run-parts scripts, anacron, systemd timers, `periodic`,
a platform's own jobs, Windows tasks — with who owns each definition (`managed_by`) and
what the driver can do to it (`actions`). `get_scheduled_jobs` reads them with the host's
time zone; `manage_scheduled_job` enables, disables or runs one now; `put_scheduled_job`
and `delete_scheduled_job` create, change and delete a job an application writes. Every
write names the `digest` the caller saw (`job_digest`) and raises `ScheduledJobChanged`
when the host's definition differs; `ScheduledJobRefused` for a job that cannot take a
verb (NetOrk/netork#1933, #86).
- `PosixScheduledJobsMixin`: the implementation over the command channel. One framed report
as root reads `/etc/crontab`, `/etc/cron.d`, the user crontabs, the run-parts directories,
`/etc/anacrontab` and every systemd timer with the unit it starts, and which package owns
each definition. A cron line is switched off behind `#napalm-disabled: `; an
application's job is a timer where systemd runs, else a file in `/etc/cron.d` or marked
lines in the user's crontab.
- `napalm_device_types.cron`: cron expressions as Vixie cron reads them, their next runs in
a time zone, and as systemd `OnCalendar` lines that fire on exactly the same minutes.
### Removed
- `OSDriver.get_cron_jobs` and `CronJobDict`. No application called them; the readers in
napalm-linux and napalm-bsd go with them. `get_scheduled_jobs` replaces them.
## [4.26.0] - 2026-11-03
### Added
- `OpenSshServerMixin.SSHD_CONFIG_GENERATED`: a driver whose platform writes sshd_config
from its own database, but includes `/etc/ssh/sshd_config.d` (OpenMediaVault), sets it
and keeps `harden_ssh_server`. The hardening then goes only into the drop-in; a
sshd_config without that include is left alone and the result says why, since the
platform would write over a change to it on its next apply (#88, NetOrk/netork#1950).
## [4.25.0] - 2026-11-02
### Added
+14 -4
View File
@@ -301,6 +301,20 @@ trip (`list-unit-files` plus one `systemctl show` over every loaded unit) instea
`is-enabled` and a `show` per unit. A host without systemd raises `SystemdUnavailable`,
a `NotImplementedError`, so a driver can fall back to another init system.
`ScheduledJobsMixin` (`get_scheduled_jobs`, `manage_scheduled_job`, `put_scheduled_job`,
`delete_scheduled_job`) is what a host runs on its own schedule — cron lines, run-parts
scripts, anacron, systemd timers, `periodic`, a platform's own jobs, Windows tasks — as one
shape, `ScheduledJobDict`. Every job says who owns its definition (`managed_by`: package,
admin, platform, application) and what the driver can do to it (`actions`): every job a
driver can switch takes `enable`, `disable` and `run`; only a job an application wrote
through `put_scheduled_job` takes `edit` and `delete`. Every write names the `digest` the
caller saw and raises `ScheduledJobChanged` when the host's definition is no longer that.
`PosixScheduledJobsMixin` implements it over `run_command`: one framed report as root,
a cron line switched off behind `#napalm-disabled: `, a timer by `systemctl`, an
application's job as a timer where systemd runs, else in `/etc/cron.d` or the user's
crontab. A driver sets the paths its host keeps jobs in. `napalm_device_types.cron` parses
cron expressions, gives their next runs and writes them as `OnCalendar` lines.
### Access channels: why there is no container model here
`CommandChannelMixin` declares a driver's public channel to its host:
@@ -621,10 +635,6 @@ class LinuxDriver(OSDriver):
def get_processes(self):
# return List[ProcessDict]
...
def get_cron_jobs(self):
# return List[CronJobDict]
...
```
### Storage / NAS
+22
View File
@@ -58,6 +58,8 @@ instead of being restated on every role that happens to need it:
* :class:`~napalm_device_types.service_clusters.ServiceClustersMixin`
* :class:`~napalm_device_types.service_packages.ServicePackagesMixin`
* :class:`~napalm_device_types.sudo_history.SudoHistoryMixin`
* :class:`~napalm_device_types.scheduled_jobs.ScheduledJobsMixin`
* :class:`~napalm_device_types.scheduled_jobs_posix.PosixScheduledJobsMixin`
* :class:`~napalm_device_types.services.ServiceControlMixin`
* :class:`~napalm_device_types.systemd.SystemdServicesMixin`
* :class:`~napalm_device_types.updates.UpdateMixin`
@@ -205,6 +207,17 @@ from napalm_device_types.ping_sweep import PingSweepMixin, driver_supports_ping
from napalm_device_types.provisioning import VMProvisionIncomplete
from napalm_device_types.residential_gateway import ResidentialGatewayDriver
from napalm_device_types.roles import primary_role_of, role_keys_of, roles_of
from napalm_device_types.scheduled_jobs import (
ScheduledJobChanged,
ScheduledJobDict,
ScheduledJobRefused,
ScheduledJobResultDict,
ScheduledJobsMixin,
ScheduledJobSpecDict,
ScheduledJobsReadingDict,
job_digest,
)
from napalm_device_types.scheduled_jobs_posix import PosixScheduledJobsMixin
from napalm_device_types.service_clusters import (
SERVICE_CLUSTERS_COMMAND,
ServiceClustersMixin,
@@ -400,6 +413,15 @@ __all__ = [
"PortSpec",
"ResidentialGatewayDriver",
"ServiceControlMixin",
"PosixScheduledJobsMixin",
"ScheduledJobChanged",
"ScheduledJobDict",
"ScheduledJobRefused",
"ScheduledJobResultDict",
"ScheduledJobSpecDict",
"ScheduledJobsMixin",
"ScheduledJobsReadingDict",
"job_digest",
"StorageDriver",
"SwitchDriver",
"SYSTEMD_SERVICES_COMMAND",
+222
View File
@@ -0,0 +1,222 @@
"""Crontabs and anacrontabs as text: the jobs in them, and changing one line of them.
Pure: no I/O. :mod:`napalm_device_types.scheduled_jobs_posix` reads the files and
writes them back; this module says what is in them and what the new text is.
**A line's key survives switching it off.** A job switched off is the same line
behind the marker :data:`DISABLED_MARKER`; the key is built from the line without
it, so the job keeps its key and the marker is all that changes. Two equal lines
in one file get ``:2``, ``:3`` after the first.
**A job an application wrote** is the line after ``# napalm-scheduled-job: <name>``
and is keyed ``job:<name>``, whatever its schedule.
**Everything else is left as it was**: comments, blank lines, variables, lines
cron would not take.
"""
from __future__ import annotations
import hashlib
import re
from dataclasses import dataclass, field
from shlex import quote
DISABLED_MARKER = "#napalm-disabled: "
JOB_MARKER = "# napalm-scheduled-job: "
_VARIABLE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$")
_ANACRON_PERIOD = re.compile(r"^(\d+|@(daily|weekly|monthly|yearly|annually))$")
@dataclass(frozen=True)
class CronLine:
"""One job in a crontab: where it is, what it says, and what was set before it."""
index: int # the line's number in the text, from 0
key: str
schedule: str
run_as: str
command: str
enabled: bool
env: dict[str, str] = field(default_factory=dict)
name: str = "" # the name an application gave it
description: str = ""
def _unquote(value: str) -> str:
value = value.strip()
if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
return value[1:-1]
return value
def _digest(text: str) -> str:
return hashlib.sha256(" ".join(text.split()).encode()).hexdigest()[:8]
def _split(content: str, *, system: bool, user: str) -> tuple[str, str, str] | None:
"""(schedule, run_as, command) of a cron line; None for one cron would not take."""
fields = 1 if content.startswith("@") else 5
owner = 1 if system else 0
parts = content.split(None, fields + owner)
if len(parts) < fields + owner + 1:
return None
schedule = " ".join(parts[:fields])
run_as = parts[fields] if system else user
return schedule, run_as, parts[-1]
def _anacron_split(content: str) -> tuple[str, str, str] | None:
"""(period, job identifier, command) of an anacrontab line."""
parts = content.split(None, 3)
if len(parts) < 4 or not _ANACRON_PERIOD.match(parts[0]) or not parts[1].isdigit():
return None
return parts[0], parts[2], parts[3]
@dataclass
class _Scan:
"""What is set while a text is read line by line."""
env: dict[str, str] = field(default_factory=dict)
seen: dict[str, int] = field(default_factory=dict)
name: str = ""
description: str = ""
def key(self, base: str) -> str:
n = self.seen.get(base, 0) + 1
self.seen[base] = n
return base if n == 1 else f"{base}:{n}"
def take_name(self) -> tuple[str, str]:
named = self.name, self.description
self.name, self.description = "", ""
return named
def _content(raw: str) -> tuple[str, bool] | None:
"""The job text of *raw* and whether it is on; None for a comment or a blank."""
line = raw.strip()
if line.startswith(DISABLED_MARKER.strip()):
return line[len(DISABLED_MARKER.strip()) :].strip(), False
if not line or line.startswith("#"):
return None
return line, True
def _remember(scan: _Scan, raw: str) -> bool:
"""Take a variable or an application's marker from *raw*; whether it was one."""
line = raw.strip()
if line.startswith(JOB_MARKER.strip()):
name, _, description = line[len(JOB_MARKER.strip()) :].strip().partition(" ")
scan.name, scan.description = name, description.strip()
return True
variable = _VARIABLE.match(line)
if variable:
scan.env[variable[1]] = _unquote(variable[2])
return True
return False
def parse_crontab(path: str, text: str, *, system: bool, user: str = "") -> list[CronLine]:
"""The jobs of the crontab *text* at *path*.
*system*: a sixth field names the user (``/etc/crontab``, ``/etc/cron.d``);
otherwise every job runs as *user*.
"""
scan, jobs = _Scan(), []
for index, raw in enumerate(text.splitlines()):
if _remember(scan, raw):
continue
found = _content(raw)
split = _split(found[0], system=system, user=user) if found else None
if found is None or split is None:
continue
content, enabled = found
name, description = scan.take_name()
key = f"job:{name}" if name else scan.key(f"cron:{path}:{_digest(content)}")
schedule, run_as, command = split
jobs.append(
CronLine(
index, key, schedule, run_as, command, enabled, dict(scan.env), name, description
)
)
return jobs
def parse_anacrontab(text: str) -> list[CronLine]:
"""The jobs of an anacrontab: period, delay, identifier, command; all run as root."""
scan, jobs = _Scan(), []
for index, raw in enumerate(text.splitlines()):
if _remember(scan, raw):
continue
found = _content(raw)
split = _anacron_split(found[0]) if found else None
if found is None or split is None:
continue
period, identifier, command = split
key = scan.key(f"anacron:{identifier}")
jobs.append(CronLine(index, key, period, "root", command, found[1], dict(scan.env)))
return jobs
def _replace(text: str, index: int, lines: list[str]) -> str:
rows = text.splitlines()
rows[index : index + 1] = lines
return "\n".join(rows) + "\n"
def switched(text: str, line: CronLine, *, enabled: bool) -> str:
"""*text* with *line* switched on or off: the marker added or taken away, nothing else."""
raw = text.splitlines()[line.index]
found = _content(raw)
if found is None: # pragma: no cover - a CronLine always points at a job
raise ValueError(f"line {line.index} is no job")
content = found[0]
return _replace(text, line.index, [content if enabled else DISABLED_MARKER + content])
def marked_lines(name: str, description: str, line: str, *, enabled: bool) -> list[str]:
"""An application's job as crontab lines: its marker, then the job, maybe switched off."""
marker = f"{JOB_MARKER}{name} {description}".rstrip()
return [marker, line if enabled else DISABLED_MARKER + line]
def with_job(text: str, jobs: list[CronLine], name: str, lines: list[str]) -> str:
"""*text* with the application's job *name* as *lines*: replaced, or added at the end."""
current = next((j for j in jobs if j.name == name), None)
if current is None:
body = text if not text or text.endswith("\n") else text + "\n"
return body + "\n".join(lines) + "\n"
rows = text.splitlines()
rows[current.index - 1 : current.index + 1] = lines
return "\n".join(rows) + "\n"
def without_job(text: str, jobs: list[CronLine], name: str) -> str:
"""*text* without the application's job *name* and its marker."""
current = next(j for j in jobs if j.name == name)
rows = text.splitlines()
del rows[current.index - 1 : current.index + 1]
return "\n".join(rows) + ("\n" if rows else "")
def _unescape(part: str) -> str:
return part.replace("\\%", "%")
def run_script(command: str, env: dict[str, str]) -> str:
"""*command* as ``sh -c`` takes it, the way cron would run it.
The crontab's variables are exported first. The first ``%`` that is not
escaped ends the command; what follows is its stdin, with every further
``%`` a newline, and ``\\%`` is a ``%``.
"""
parts = re.split(r"(?<!\\)%", command)
exports = "".join(f"export {k}={quote(v)}; " for k, v in env.items() if k != "MAILTO")
head = _unescape(parts[0])
if len(parts) == 1:
return exports + head
stdin = "\n".join(_unescape(p) for p in parts[1:])
return f"{exports}printf '%s\\n' {quote(stdin)} | {{ {head}\n}}"
+417
View File
@@ -0,0 +1,417 @@
"""The scheduled-jobs report of a POSIX host: the command that prints it, and its parse.
:mod:`napalm_device_types.scheduled_jobs_posix` sends :func:`reading_command` and
hands what came back to :func:`parse_reading`. Pure: no I/O.
**One framed report, as root.** Every crontab, cron.d file, anacrontab and job
script is printed behind a header line and with ``|`` before each of its lines,
so no line of a file can pass for a header; run-parts scripts by their execute
bit and checksum; systemd's timers and the units they start by ``systemctl show``;
then the time zone and which package owns each definition file. A report whose
end marker is missing raises: a list cut short must never read as jobs that went
away.
"""
from __future__ import annotations
import re
from dataclasses import dataclass, field
from datetime import UTC, datetime
from shlex import quote
from napalm_device_types._crontab import JOB_MARKER, CronLine, parse_anacrontab, parse_crontab
from napalm_device_types.scheduled_jobs import DELETE, EDIT, job_digest
from napalm_device_types.terminal import strip_terminal_codes
_BEGIN = "SJ_BEGIN"
_END = "SJ_END"
SCHEDULE_HEADER = "# schedule: "
TIMER_PROPERTIES = (
"Id,Unit,Description,TimersCalendar,TimersMonotonic,NextElapseUSecRealtime,"
"LastTriggerUSec,UnitFileState,ActiveState,FragmentPath"
)
UNIT_PROPERTIES = "Id,ExecStart,User,Result,FragmentPath"
#: The names run-parts runs (Debian's ``--lsbsysinit``-less default).
_RUN_PARTS_NAME = re.compile(r"^[A-Za-z0-9_-]+$")
_SECTION = re.compile(r"^\[([a-z-]+)(?: (.*))?\]$")
#: Reads definition paths on stdin, prints ``<package>: <path>`` for each a package owns.
OWNERS_SH = (
"if command -v dpkg >/dev/null 2>&1; then xargs dpkg -S 2>/dev/null; "
"elif command -v rpm >/dev/null 2>&1; then while read -r p; do "
'o=$(rpm -qf --qf \'%{NAME}\' -- "$p" 2>/dev/null) && printf \'%s: %s\\n\' "$o" "$p"; done; '
"elif command -v apk >/dev/null 2>&1; then while read -r p; do "
'o=$(apk info -qW -- "$p" 2>/dev/null) && [ -n "$o" ] && printf \'%s: %s\\n\' "$o" "$p"; done; '
"else cat >/dev/null; fi"
)
#: Prints the host's time zone: an IANA name, or a path ending in ``zoneinfo/<name>``.
TIME_ZONE_SH = "cat /etc/timezone 2>/dev/null || readlink /etc/localtime 2>/dev/null"
@dataclass(frozen=True)
class Paths:
"""Where a host keeps its scheduled jobs."""
system_files: tuple[str, ...]
cron_d_dirs: tuple[str, ...]
spool_dirs: tuple[str, ...]
run_parts: tuple[tuple[str, str], ...] # (period, directory)
anacrontab: str
script_dir: str
systemd_marker: str = "/run/systemd/system"
owners_sh: str = OWNERS_SH
time_zone_sh: str = TIME_ZONE_SH
@dataclass
class Reading:
"""What one report said, beyond the jobs: what writes need to know."""
jobs: list[dict[str, object]] = field(default_factory=list)
time_zone: str | None = None
systemd: bool = False
#: per key: the unit a timer starts, the crontab line a cron job is
units: dict[str, str] = field(default_factory=dict)
lines: dict[str, CronLine] = field(default_factory=dict)
def _q(path: str) -> str:
return quote(path)
def _files(section: str, pattern: str) -> str:
return (
f'for f in {pattern}; do [ -f "$f" ] || continue; printf \'[%s %s]\\n\' {section} "$f"; '
# GNU sed keeps a missing last newline; without one of its own the next
# header would run on into the file's last line.
'sed \'s/^/|/\' "$f"; [ -n "$(tail -c 1 "$f")" ] && echo; P="$P\n$f"; done; '
)
def _run_parts(period: str, directory: str) -> str:
return (
f'for f in {_q(directory)}/*; do [ -f "$f" ] || continue; '
'[ -x "$f" ] && x=1 || x=0; c=$(cksum < "$f" | cut -d" " -f1); '
f'printf \'[run-parts %s %s %s %s]\\n\' {period} "$x" "$c" "$f"; P="$P\n$f"; done; '
)
def _timers(paths: Paths) -> str:
show = f"systemctl show --no-pager -p {TIMER_PROPERTIES}"
units = f"systemctl show --no-pager -p {UNIT_PROPERTIES}"
return (
f"if [ -d {_q(paths.systemd_marker)} ]; then echo '[systemd]'; "
"t=$(systemctl list-unit-files --type=timer --no-legend --no-pager 2>/dev/null "
"| awk '$1 !~ /@\\./ {print $1}'); "
'if [ -n "$t" ]; then '
f"s=$({show} --timestamp=unix $t 2>/dev/null || {show} $t 2>/dev/null); "
"echo '[timers]'; printf '%s\\n' \"$s\" | sed 's/^/|/'; "
"u=$(printf '%s\\n' \"$s\" | sed -n 's/^Unit=//p'); "
f"echo '[units]'; {units} $u 2>/dev/null | sed 's/^/|/'; "
"P=\"$P\n$(printf '%s\\n' \"$s\" | sed -n 's/^FragmentPath=//p')\"; fi; fi; "
)
def reading_command(paths: Paths) -> str:
"""One POSIX ``sh`` script that prints every scheduled job of the host; run it as root."""
parts = ["printf '%s%s\\n' SJ_ BEGIN; P=''; "]
parts += [_files("system", _q(f)) for f in paths.system_files]
parts += [_files("system", f"{_q(d)}/*") for d in paths.cron_d_dirs]
parts += [_files("user", f"{_q(d)}/*") for d in paths.spool_dirs]
parts.append(_files("anacron", _q(paths.anacrontab)))
parts += [_run_parts(period, d) for period, d in paths.run_parts]
parts.append(_files("script", f"{_q(paths.script_dir)}/*"))
parts.append(_timers(paths))
parts.append(
f"echo '[tz]'; {{ {paths.time_zone_sh}; }}; "
f"echo '[owners]'; printf '%s\\n' \"$P\" | sed '/^$/d' | {{ {paths.owners_sh}; }}; "
"printf '%s%s\\n' SJ_ END"
)
return "".join(parts)
# -- parse ------------------------------------------------------------------------------------
@dataclass
class _Section:
name: str
args: str
lines: list[str] = field(default_factory=list)
def _sections(output: str) -> list[_Section]:
text = strip_terminal_codes(output)
begin, end = text.rfind(_BEGIN), text.rfind(_END)
if begin < 0 or end < begin:
raise ValueError("the scheduled-jobs report is cut short (no end marker)")
sections: list[_Section] = []
for line in text[begin + len(_BEGIN) : end].splitlines():
header = _SECTION.match(line)
if header:
sections.append(_Section(header[1], header[2] or ""))
elif sections:
sections[-1].lines.append(line[1:] if line.startswith("|") else line)
return sections
def _owned(lines: list[str]) -> set[str]:
owned: set[str] = set()
for line in lines:
package, sep, path = line.partition(": ")
if sep and path.startswith("/") and not package.startswith("diversion"):
owned.add(path.strip())
return owned
def _time_zone(lines: list[str]) -> str | None:
value = next((ln.strip() for ln in lines if ln.strip()), "")
if "zoneinfo/" in value:
value = value.split("zoneinfo/", 1)[1]
return value or None
def _blocks(lines: list[str]) -> list[dict[str, list[str]]]:
blocks: list[dict[str, list[str]]] = [{}]
for line in lines:
if not line.strip():
blocks.append({})
continue
key, sep, value = line.partition("=")
if sep:
blocks[-1].setdefault(key, []).append(value)
return [b for b in blocks if b.get("Id")]
def _one(block: dict[str, list[str]], key: str) -> str:
return (block.get(key) or [""])[0].strip()
def _timestamp(value: str) -> str | None:
"""systemd's ``@<seconds>`` (or a UTC time) as ISO 8601; None when it never was."""
value = value.strip()
if value.startswith("@") and value[1:].isdigit() and int(value[1:]) > 0:
return datetime.fromtimestamp(int(value[1:]), UTC).isoformat()
match = re.search(r"(\d{4}-\d\d-\d\d \d\d:\d\d:\d\d) UTC$", value)
if match:
return datetime.strptime(match[1], "%Y-%m-%d %H:%M:%S").replace(tzinfo=UTC).isoformat()
return None
def _timer_entries(block: dict[str, list[str]], key: str) -> list[str]:
"""``{ OnCalendar=daily ; next_elapse=… }`` → ``OnCalendar=daily``, one per entry.
``systemctl show`` names a monotonic setting by its property (``OnUnitActiveUSec``);
it is given as the unit file says it (``OnUnitActiveSec``).
"""
entries = (v.strip(" {}").split(" ; ")[0].strip() for v in block.get(key, []) if v.strip())
return [re.sub(r"^(On\w+)USec=", r"\1Sec=", e) for e in entries]
def _argv(exec_start: list[str]) -> str:
commands = []
for value in exec_start:
match = re.search(r"argv\[\]=(.*?) ; ", value)
if match:
commands.append(match[1].strip())
return "; ".join(commands)
@dataclass
class _Script:
name: str
description: str
schedule: str
command: str
def _script(path: str, lines: list[str]) -> _Script | None:
"""An application's job script: its marker, schedule and command; None for any other file."""
marker = next((ln for ln in lines if ln.startswith(JOB_MARKER)), None)
schedule = next((ln for ln in lines if ln.startswith(SCHEDULE_HEADER)), None)
if marker is None or schedule is None:
return None
name, _, description = marker[len(JOB_MARKER) :].partition(" ")
body = [ln for ln in lines if ln not in (marker, schedule) and not ln.startswith("#!")]
return _Script(
name, description.strip(), schedule[len(SCHEDULE_HEADER) :], "\n".join(body).strip()
)
def _job(
*,
key: str,
kind: str,
source: str,
run_as: str,
schedule: str,
schedule_kind: str,
command: str,
enabled: bool,
managed_by: str,
actions: list[str],
content: str = "",
**extra: object,
) -> dict[str, object]:
job: dict[str, object] = {
"key": key,
"kind": kind,
"source": source,
"run_as": run_as,
"schedule": schedule,
"schedule_kind": schedule_kind,
"command": command,
"enabled": enabled,
"managed_by": managed_by,
"actions": actions,
}
job["digest"] = job_digest(job, content=content)
job.update({k: v for k, v in extra.items() if v not in (None, "")})
return job
_SWITCH = ["enable", "disable", "run"]
_OWN = [*_SWITCH, EDIT, DELETE]
def _cron_jobs(section: _Section, owned: set[str], reading: Reading) -> None:
path = section.args
text = "\n".join(section.lines)
if section.name == "anacron":
found = parse_anacrontab(text)
else:
user = path.rsplit("/", 1)[-1]
found = parse_crontab(path, text, system=section.name == "system", user=user)
kind = "anacron" if section.name == "anacron" else "cron"
for line in found:
own = bool(line.name)
reading.lines[line.key] = line
reading.jobs.append(
_job(
key=line.key,
kind=kind,
source=path,
run_as=line.run_as,
schedule=line.schedule,
schedule_kind="period" if kind == "anacron" else "cron",
command=line.command,
enabled=line.enabled,
managed_by="application" if own else ("package" if path in owned else "admin"),
actions=_OWN if own else _SWITCH,
name=line.name,
description=line.description,
)
)
def _run_parts_job(section: _Section, owned: set[str], reading: Reading) -> None:
period, executable, checksum, path = section.args.split(" ", 3)
if not _RUN_PARTS_NAME.match(path.rsplit("/", 1)[-1]):
return
reading.jobs.append(
_job(
key=f"run-parts:{path}",
kind="run_parts",
source=path,
run_as="root",
schedule=period,
schedule_kind="period",
command=path,
enabled=executable == "1",
managed_by="package" if path in owned else "admin",
actions=_SWITCH,
content=checksum,
)
)
def _timer_job(
timer: dict[str, list[str]],
unit: dict[str, list[str]],
scripts: dict[str, _Script],
owned: set[str],
) -> dict[str, object]:
fragment = _one(timer, "FragmentPath")
calendar = _timer_entries(timer, "TimersCalendar")
schedule = "; ".join(calendar + _timer_entries(timer, "TimersMonotonic"))
command = _argv(unit.get("ExecStart", []))
script = scripts.get(command.split(" ", 1)[0])
last_run = _timestamp(_one(timer, "LastTriggerUSec"))
switchable = _one(timer, "UnitFileState") not in ("static", "generated", "transient")
common = {
"kind": "systemd_timer",
"source": fragment,
"run_as": _one(unit, "User") or "root",
"enabled": _one(timer, "ActiveState") == "active",
"last_run": last_run,
"last_result": _one(unit, "Result") or None if last_run else None,
"next_run": _timestamp(_one(timer, "NextElapseUSecRealtime")),
}
if script is not None:
return _job(
key=f"job:{script.name}",
schedule=script.schedule,
schedule_kind="cron",
command=script.command,
managed_by="application",
actions=_OWN,
name=script.name,
description=script.description,
**common, # type: ignore[arg-type]
)
packaged = fragment in owned or fragment.startswith(("/usr/lib/", "/lib/"))
return _job(
key=f"timer:{_one(timer, 'Id')}",
schedule=schedule,
schedule_kind="calendar" if calendar else "monotonic",
command=command,
managed_by="package" if packaged else "admin",
actions=_SWITCH if switchable else ["run"],
description=_one(timer, "Description"),
**common, # type: ignore[arg-type]
)
def _timer_jobs(
sections: dict[str, _Section], scripts: dict[str, _Script], owned: set[str], reading: Reading
) -> None:
timers = _blocks(sections["timers"].lines) if "timers" in sections else []
units = (
{_one(b, "Id"): b for b in _blocks(sections["units"].lines)} if "units" in sections else {}
)
for timer in timers:
unit = units.get(_one(timer, "Unit"), {})
job = _timer_job(timer, unit, scripts, owned)
reading.units[str(job["key"])] = _one(timer, "Unit")
reading.jobs.append(job)
def parse_reading(output: str) -> Reading:
"""The jobs, time zone and write context of a report from :func:`reading_command`.
:raises ValueError: when the report is cut short.
"""
sections = _sections(output)
named = {s.name: s for s in sections if s.name in ("timers", "units", "tz", "owners")}
owned = _owned(named["owners"].lines) if "owners" in named else set()
reading = Reading(
time_zone=_time_zone(named["tz"].lines) if "tz" in named else None,
systemd=any(s.name == "systemd" for s in sections),
)
for section in sections:
if section.name in ("system", "user", "anacron"):
_cron_jobs(section, owned, reading)
elif section.name == "run-parts":
_run_parts_job(section, owned, reading)
_timer_jobs(named, _scripts(sections), owned, reading)
return reading
def _scripts(sections: list[_Section]) -> dict[str, _Script]:
"""An application's job scripts, by path."""
scripts = ((s.args, _script(s.args, s.lines)) for s in sections if s.name == "script")
return {path: script for path, script in scripts if script is not None}
+203
View File
@@ -0,0 +1,203 @@
"""Cron expressions: what they mean, when they fire next, and as systemd ``OnCalendar``.
A scheduled job is given as a cron expression on every host, and a host with
systemd runs it as a timer. So the expression has to mean the same in three
places -- on the host's cron, in a preview of the next runs, and in the
``OnCalendar`` lines a timer is written with -- and the meaning lives here once.
**What cron means is Vixie cron's.** Five fields (minute, hour, day of month,
month, day of week), each ``*``, a value, a range ``a-b``, a step ``*/n`` or
``a-b/n``, or a list of those; month and weekday names in any case; ``7`` is
Sunday as well as ``0``; the ``@hourly`` … ``@yearly`` aliases. When both day
fields are restricted -- neither starts with ``*`` -- a day matches if *either*
does; otherwise both must (``*/2`` counts as starting with ``*``).
**``OnCalendar`` by expansion.** Every field is written as its values, so a range
with a step needs no systemd syntax of its own, and a timer fires on exactly the
minutes cron would. The *either* rule is two ``OnCalendar`` lines, which systemd
ORs. ``@reboot`` has no calendar; a timer takes it as ``OnBootSec``.
**Next runs are in the host's time zone.** A local time the clock skips when
summer time starts is left out; cron implementations disagree on it, and a
preview that promised it would promise too much.
"""
from __future__ import annotations
from datetime import date, datetime, timedelta
from typing import NamedTuple
from zoneinfo import ZoneInfo
REBOOT = "@reboot"
ALIASES = {
"@yearly": "0 0 1 1 *",
"@annually": "0 0 1 1 *",
"@monthly": "0 0 1 * *",
"@weekly": "0 0 * * 0",
"@daily": "0 0 * * *",
"@midnight": "0 0 * * *",
"@hourly": "0 * * * *",
}
_MONTHS = ("jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec")
_WEEKDAYS = ("sun", "mon", "tue", "wed", "thu", "fri", "sat")
_SYSTEMD_WEEKDAYS = ("Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat")
#: (lowest, highest, names) per field; a name stands for its index plus the lowest.
_FIELDS = (
(0, 59, ()),
(0, 23, ()),
(1, 31, ()),
(1, 12, _MONTHS),
(0, 7, _WEEKDAYS),
)
#: How far ahead a next run is looked for: a 29 February comes within eight years.
_HORIZON_DAYS = 8 * 366
class CronSchedule(NamedTuple):
"""An expression's values per field, and whether a day matches on either day field."""
minutes: frozenset[int]
hours: frozenset[int]
days: frozenset[int]
months: frozenset[int]
weekdays: frozenset[int] # 0 = Sunday
either_day: bool
def is_reboot(expr: str) -> bool:
"""Whether *expr* is ``@reboot``: once at boot, no calendar."""
return expr.strip().lower() == REBOOT
def _value(token: str, low: int, names: tuple[str, ...]) -> int:
if token.isdigit():
return int(token)
if token.lower() in names:
return names.index(token.lower()) + low
raise ValueError(f"not a value: {token!r}")
def _part(part: str, low: int, high: int, names: tuple[str, ...]) -> set[int]:
span, _, step_text = part.partition("/")
step = 1
if step_text:
if not step_text.isdigit() or int(step_text) == 0:
raise ValueError(f"not a step: {part!r}")
step = int(step_text)
if span == "*":
first, last = low, high
elif "-" in span:
a, _, b = span.partition("-")
first, last = _value(a, low, names), _value(b, low, names)
else:
first = _value(span, low, names)
last = high if step_text else first
if not low <= first <= last <= high:
raise ValueError(f"out of range {low}-{high}: {part!r}")
return set(range(first, last + 1, step))
def _field(text: str, low: int, high: int, names: tuple[str, ...]) -> frozenset[int]:
values: set[int] = set()
for part in text.split(","):
if not part:
raise ValueError(f"empty list item in {text!r}")
values |= _part(part, low, high, names)
return frozenset(values)
def parse_cron(expr: str) -> CronSchedule:
"""The values *expr* stands for.
:raises ValueError: for anything Vixie cron would not take, and for
``@reboot``, which names no time.
"""
text = expr.strip()
if is_reboot(text):
raise ValueError("@reboot names no time; it runs once at boot")
if text.startswith("@"):
if text.lower() not in ALIASES:
raise ValueError(f"unknown alias {text!r}")
text = ALIASES[text.lower()]
fields = text.split()
if len(fields) != len(_FIELDS):
raise ValueError(f"a cron expression has five fields, not {len(fields)}: {expr!r}")
minutes, hours, days, months, weekdays = (
_field(f, low, high, names) for f, (low, high, names) in zip(fields, _FIELDS, strict=True)
)
if 7 in weekdays:
weekdays = (weekdays - {7}) | {0}
either = not fields[2].startswith("*") and not fields[4].startswith("*")
return CronSchedule(minutes, hours, days, months, frozenset(weekdays), either)
def _day_matches(s: CronSchedule, day: date) -> bool:
if day.month not in s.months:
return False
on_day = day.day in s.days
on_weekday = (day.isoweekday() % 7) in s.weekdays
return (on_day or on_weekday) if s.either_day else (on_day and on_weekday)
def _local(day: date, hour: int, minute: int, tz: ZoneInfo) -> datetime | None:
"""*day* at *hour*:*minute* in *tz*; None when the clock skips that time."""
naive = datetime(day.year, day.month, day.day, hour, minute)
aware = naive.replace(tzinfo=tz)
if aware.astimezone(ZoneInfo("UTC")).astimezone(tz).replace(tzinfo=None) != naive:
return None
return aware
def next_runs(expr: str, after: datetime, tz: ZoneInfo, count: int = 5) -> list[datetime]:
"""The next *count* times *expr* fires after *after*, in *tz*.
``@reboot`` and a day that never comes (31 February) give none.
:raises ValueError: for an expression :func:`parse_cron` refuses.
"""
if is_reboot(expr):
return []
s = parse_cron(expr)
start = after.astimezone(tz)
runs: list[datetime] = []
for offset in range(_HORIZON_DAYS):
day = start.date() + timedelta(days=offset)
if not _day_matches(s, day):
continue
for hour in sorted(s.hours):
for minute in sorted(s.minutes):
at = _local(day, hour, minute, tz)
if at is None or at <= after:
continue
runs.append(at)
if len(runs) == count:
return runs
return runs
def _values(values: frozenset[int], low: int, high: int) -> str:
if values == frozenset(range(low, high + 1)):
return "*"
return ",".join(f"{v:02d}" for v in sorted(values))
def to_on_calendar(expr: str) -> list[str]:
"""``OnCalendar`` lines that fire exactly when *expr* does.
:raises ValueError: for an expression :func:`parse_cron` refuses, ``@reboot``
among them -- a timer takes that as ``OnBootSec``.
"""
s = parse_cron(expr)
time = f"{_values(s.hours, 0, 23)}:{_values(s.minutes, 0, 59)}:00"
months = _values(s.months, 1, 12)
days = _values(s.days, 1, 31)
weekdays = ",".join(_SYSTEMD_WEEKDAYS[d] for d in (1, 2, 3, 4, 5, 6, 0) if d in s.weekdays)
every_weekday = s.weekdays == frozenset(range(7))
if s.either_day:
return [f"*-{months}-{days} {time}", f"{weekdays} *-{months}-* {time}"]
prefix = "" if every_weekday else f"{weekdays} "
return [f"{prefix}*-{months}-{days} {time}"]
-9
View File
@@ -1038,15 +1038,6 @@ class ProcessDict(TypedDict):
command: str # full command line
class CronJobDict(TypedDict):
"""A scheduled cron task."""
user: str # owner of the crontab entry
schedule: str # five-field cron expression, e.g. "0 * * * *"
command: str # shell command to execute
description: NotRequired[str] # optional inline comment
class ApplyUpdatesResultDict(TypedDict):
"""Result of an ``apply_updates()`` call."""
-29
View File
@@ -15,7 +15,6 @@ from typing import TYPE_CHECKING
from napalm_device_types.base import DeviceTypeDriver
from napalm_device_types.health_metrics import HealthMetricsMixin
from napalm_device_types.models import (
CronJobDict,
DeviceActionResultDict,
ProcessDict,
SNMPConfigDict,
@@ -131,34 +130,6 @@ class OSDriver(
"""
...
# ------------------------------------------------------------------
# Cron jobs
# ------------------------------------------------------------------
def get_cron_jobs(self) -> list[CronJobDict]:
"""
Returns scheduled cron tasks from all user crontabs and ``/etc/cron.d``.
Each entry contains:
* user (string) - owner of the crontab entry
* schedule (string) - five-field cron expression (e.g. ``"0 * * * *"``)
* command (string) - shell command to execute
* description (string, optional) - inline comment text if present
Example::
[
{
"user": "root",
"schedule": "0 4 * * *",
"command": "/usr/local/bin/backup.sh",
"description": "nightly backup",
},
]
"""
...
# ------------------------------------------------------------------
# SNMP
# ------------------------------------------------------------------
+196
View File
@@ -0,0 +1,196 @@
"""Scheduled jobs: what a host runs on its own schedule, and switching it on, off and now.
A host runs work on its own: cron lines, run-parts scripts, anacron, systemd
timers, FreeBSD's ``periodic``, a firewall's or a NAS's own scheduled jobs, the
Windows Task Scheduler. :class:`ScheduledJobsMixin` reads all of them as one
shape, :class:`~napalm_device_types.models.ScheduledJobDict`, and acts on them.
Declared under ``if TYPE_CHECKING`` like a role: nothing exists at runtime until
a driver implements it. :class:`~napalm_device_types.scheduled_jobs_posix.PosixScheduledJobsMixin`
is the implementation for a host reached through the command channel.
**Who owns a definition** is on every job (``managed_by``): ``package`` (installed
by one), ``admin`` (written on the host), ``platform`` (generated by the device's
own configuration -- OPNsense, OpenMediaVault, QTS, Windows), ``application`` (written
through :meth:`put_scheduled_job`, under the ``name`` the application gave it).
What the application makes of that is the application's.
**What may be done is on every job too** (``actions``): every job a driver can
switch takes ``enable``, ``disable`` and ``run``; only an ``application`` job takes
``edit`` and ``delete``. A driver never edits or removes a job it did not write.
**Never over a change it did not see.** Every write names the ``digest`` the caller
saw. The driver reads the job again right before it writes and raises
:class:`ScheduledJobChanged` when the definition differs.
"""
from __future__ import annotations
import hashlib
import json
import re
from typing import TYPE_CHECKING, Any, NotRequired, TypedDict
from napalm_device_types.cron import is_reboot, parse_cron
#: What :meth:`ScheduledJobsMixin.manage_scheduled_job` takes.
ACTIONS = ("enable", "disable", "run")
#: What a job's ``actions`` may list beyond :data:`ACTIONS`.
EDIT = "edit"
DELETE = "delete"
KINDS = ("cron", "run_parts", "anacron", "systemd_timer", "periodic", "task")
MANAGED_BY = ("package", "admin", "platform", "application")
#: Seconds a run now may take on the host before ``timeout`` stops it.
RUN_TIMEOUT = 300
#: A job's name becomes a file and a unit name: lower case, digits, dashes.
_NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,62}")
#: A user name as useradd and the BSDs take it.
_USER = re.compile(r"[A-Za-z_][A-Za-z0-9_.-]{0,31}\$?")
#: The parts of a job that are its definition; what the host says of its runs is not.
_DEFINITION = ("kind", "source", "run_as", "schedule", "command", "enabled")
class ScheduledJobDict(TypedDict):
"""A job the host runs on its own schedule (``get_scheduled_jobs``).
A cron line, a run-parts script, an anacron job, a systemd timer, a FreeBSD
``periodic`` script, a platform's own job, a Windows task -- one shape for all
of them (``napalm_device_types.scheduled_jobs``).
"""
key: str # stable name on this host: "timer:apt-daily.timer", "cron:/etc/crontab:1a2b3c4d"
kind: str # cron | run_parts | anacron | systemd_timer | periodic | task
source: str # the file, unit file or configuration it is defined in
run_as: str # the user it runs as
schedule: str # as the host has it: "*/5 * * * *", "OnCalendar=daily", "daily"
schedule_kind: str # cron | calendar | monotonic | period | triggers
command: str # as the host has it
enabled: bool
managed_by: str # package | admin | platform | application
digest: str # job_digest(): the definition as it is now
actions: list[str] # what the driver can do to this job: enable, disable, run, edit, delete
name: NotRequired[str] # the name an application gave a job it wrote (put_scheduled_job)
description: NotRequired[str]
last_run: NotRequired[str | None] # ISO 8601, UTC; where the host knows it
last_result: NotRequired[str | None] # "success", or what the host says went wrong
next_run: NotRequired[str | None] # ISO 8601, UTC; where the host knows it
class ScheduledJobsReadingDict(TypedDict):
"""Every scheduled job of a host, and the time zone its schedules are in."""
jobs: list[ScheduledJobDict]
time_zone: str | None # IANA name ("Europe/Berlin"); None when the host does not say
class ScheduledJobSpecDict(TypedDict):
"""A job an application wants on the host (``put_scheduled_job``)."""
name: str # the job's name on the host, chosen by the application: [a-z0-9][a-z0-9-]*
schedule: str # a cron expression (napalm_device_types.cron), "@reboot" included
run_as: str
command: str # one or more lines of POSIX sh; a platform may take its own (OPNsense: configd)
enabled: bool
description: NotRequired[str]
class ScheduledJobResultDict(TypedDict):
"""What an action on a scheduled job did."""
success: bool
output: str # what the host said; for a run, what the job printed
class ScheduledJobChanged(Exception): # noqa: N818 - a state, as the callers word it
"""The job's definition differs from the digest the caller saw: nothing was written."""
class ScheduledJobRefused(ValueError):
"""The job cannot take what was asked of it, or the request itself is not valid."""
def job_digest(job: dict[str, Any], *, content: str = "") -> str:
"""The definition of *job* in 16 hex characters.
Over kind, source, run_as, schedule, command and enabled -- so enabling a job
changes it -- and *content*: what the definition points at that the job's
fields do not show, such as a run-parts script's checksum.
"""
parts = [job.get(field) for field in _DEFINITION] + [content]
return hashlib.sha256(json.dumps(parts).encode()).hexdigest()[:16]
def check_job_name(name: str) -> None:
""":raises ScheduledJobRefused: for a name a file or a unit could not carry safely."""
if not _NAME.fullmatch(name or ""):
raise ScheduledJobRefused(f"not a job name: {name!r} (a-z, 0-9 and -, at most 63)")
def check_spec(spec: ScheduledJobSpecDict) -> None:
""":raises ScheduledJobRefused: for a spec no host could be given as it is."""
check_job_name(spec["name"])
if not _USER.fullmatch(spec.get("run_as") or ""):
raise ScheduledJobRefused(f"not a user name: {spec.get('run_as')!r}")
if not (spec.get("command") or "").strip():
raise ScheduledJobRefused("a job needs a command")
if "\n" in (spec.get("description") or ""):
raise ScheduledJobRefused("a description is one line")
if not is_reboot(spec["schedule"]):
try:
parse_cron(spec["schedule"])
except ValueError as exc:
raise ScheduledJobRefused(str(exc)) from exc
class ScheduledJobsMixin:
"""Declares the scheduled-jobs contract; a driver that can implements it.
A verb a driver cannot do at all is ``None`` on the driver, as ``manage_service``
is; a verb one job cannot take is missing from that job's ``actions``.
"""
if TYPE_CHECKING: # pragma: no cover - declared for type checkers only
def get_scheduled_jobs(self) -> ScheduledJobsReadingDict:
"""Every scheduled job of the host.
:raises ValueError: when the reading came back cut short -- never a
shorter list.
"""
...
def manage_scheduled_job(
self, key: str, action: str, *, digest: str
) -> ScheduledJobResultDict:
"""Enable, disable or run the job *key* now.
:raises ScheduledJobChanged: when the job is no longer as *digest* says.
:raises ScheduledJobRefused: when the job does not take *action*.
:raises LookupError: when the host has no job *key*.
"""
...
def put_scheduled_job(
self, spec: ScheduledJobSpecDict, *, digest: str | None = None
) -> ScheduledJobResultDict:
"""Create the job ``spec["name"]`` (*digest* None) or change it.
:raises ScheduledJobChanged: when the job is no longer as *digest*
says, or when a job of that name is there although *digest* is None.
:raises ScheduledJobRefused: for a spec :func:`check_spec` refuses, or
one the host cannot take.
"""
...
def delete_scheduled_job(self, key: str, *, digest: str) -> ScheduledJobResultDict:
"""Delete the job *key*, which an application wrote.
:raises ScheduledJobChanged: when the job is no longer as *digest* says.
:raises ScheduledJobRefused: when the job is not one an application wrote.
:raises LookupError: when the host has no job *key*.
"""
...
+493
View File
@@ -0,0 +1,493 @@
"""Scheduled jobs on a POSIX host, over the command channel: cron and systemd timers.
:class:`PosixScheduledJobsMixin` implements
:class:`~napalm_device_types.scheduled_jobs.ScheduledJobsMixin` for a driver that has
:meth:`~napalm_device_types.channel.CommandChannelMixin.run_command`. The driver
mixes it in and sets the paths its host keeps jobs in; the defaults are Debian's.
**Reading** is one framed report as root (:mod:`napalm_device_types._scheduled_reading`).
**Switching** a cron or anacron line comments it out behind ``#napalm-disabled: ``
and takes exactly that marker away again; a run-parts script loses or gets its
execute bit; a timer is ``systemctl disable --now`` / ``enable --now``. A timer that
cannot be switched (``static``) only runs.
**Writing** stages the new text as the login user and installs it as root with one
fixed command: ``crontab -u <user> <file>`` for a user's crontab, ``install`` with
the file's own mode and owner for a system file. Root never reads stdin. Before any
write the job is read again and compared with the digest the caller saw.
**An application's own job** (:meth:`put_scheduled_job`) is a timer on a host with
systemd -- ``<name>.timer`` and ``<name>.service`` in :attr:`UNIT_DIR`, the command
in :attr:`JOB_SCRIPT_DIR` ``/<name>`` behind a marker and its cron expression --
else a file in :attr:`OWN_CRON_D_DIR`, else marked lines in the user's crontab.
**Running now** is bounded by :data:`~napalm_device_types.scheduled_jobs.RUN_TIMEOUT`:
a timer's unit by ``systemctl start`` and its journal since then, a cron line's
command as its user the way cron runs it (``_crontab.run_script``).
"""
from __future__ import annotations
import fnmatch
import shlex
from collections.abc import Sequence
from typing import TYPE_CHECKING, ClassVar
from napalm_device_types._crontab import (
JOB_MARKER,
CronLine,
marked_lines,
parse_anacrontab,
parse_crontab,
run_script,
switched,
with_job,
without_job,
)
from napalm_device_types._scheduled_reading import (
OWNERS_SH,
SCHEDULE_HEADER,
TIME_ZONE_SH,
Paths,
Reading,
parse_reading,
reading_command,
)
from napalm_device_types.cron import is_reboot, to_on_calendar
from napalm_device_types.scheduled_jobs import (
ACTIONS,
RUN_TIMEOUT,
ScheduledJobChanged,
ScheduledJobRefused,
ScheduledJobResultDict,
ScheduledJobsMixin,
ScheduledJobSpecDict,
ScheduledJobsReadingDict,
check_spec,
)
if TYPE_CHECKING:
from napalm_device_types.channel import CommandResult
_STAGE = 't=$(mktemp) && chmod 644 "$t" && cat > "$t" && printf %s "$t"'
#: What a run keeps of the job's output.
_OUTPUT_LIMIT = 64 * 1024
_READ_TIMEOUT = 120
def _command(argv: Sequence[str]) -> str:
return shlex.join(argv)
def _said(result: CommandResult) -> str:
return "\n".join(p for p in (result.stdout.strip(), result.stderr.strip()) if p)[
-_OUTPUT_LIMIT:
]
def _result(result: CommandResult, done: str) -> ScheduledJobResultDict:
if result.exit_code != 0:
return {"success": False, "output": _said(result) or f"exit {result.exit_code}"}
return {"success": True, "output": _said(result) or done}
class PosixScheduledJobsMixin(ScheduledJobsMixin):
"""Scheduled jobs of a host reached through ``run_command``; the paths are the driver's."""
CRON_SYSTEM_FILES: ClassVar[tuple[str, ...]] = ("/etc/crontab",)
CRON_D_DIRS: ClassVar[tuple[str, ...]] = ("/etc/cron.d",)
CRON_SPOOL_DIRS: ClassVar[tuple[str, ...]] = (
"/var/spool/cron/crontabs",
"/var/spool/cron",
"/etc/crontabs",
)
RUN_PARTS_DIRS: ClassVar[tuple[tuple[str, str], ...]] = (
("hourly", "/etc/cron.hourly"),
("daily", "/etc/cron.daily"),
("weekly", "/etc/cron.weekly"),
("monthly", "/etc/cron.monthly"),
)
ANACRONTAB: ClassVar[str] = "/etc/anacrontab"
JOB_SCRIPT_DIR: ClassVar[str] = "/usr/local/libexec/scheduled-jobs"
UNIT_DIR: ClassVar[str] = "/etc/systemd/system"
#: Where a host without systemd takes an application's job as a file, if the directory
#: is there; else, or None, the user's crontab.
OWN_CRON_D_DIR: ClassVar[str | None] = "/etc/cron.d"
ROOT_GROUP: ClassVar[str] = "root"
#: Prints "<octal mode> <owner> <group>" of the path appended.
STAT_ARGV: ClassVar[tuple[str, ...]] = ("stat", "-c", "%a %U %G", "--")
#: ``install`` and how it makes missing directories (FreeBSD's ``-D`` is a destdir).
INSTALL: ClassVar[tuple[str, ...]] = ("install", "-D")
#: ``sh`` that reads definition paths on stdin and prints ``<package>: <path>``.
OWNERS_SH: ClassVar[str] = OWNERS_SH
#: ``sh`` that prints the time zone: an IANA name, or a path ending in ``zoneinfo/<name>``.
TIME_ZONE_SH: ClassVar[str] = TIME_ZONE_SH
#: ``fnmatch`` patterns on a job's ``source``: what the platform generates is ``platform``.
PLATFORM_SOURCES: ClassVar[tuple[str, ...]] = ()
#: Run as root after a user's crontab was written; for a host that keeps it elsewhere too.
CRONTAB_AFTER_WRITE: ClassVar[tuple[str, ...] | None] = None
if TYPE_CHECKING: # pragma: no cover - declared for type checkers only
def run_command(
self,
command: str,
*,
privileged: bool = False,
timeout: float = 60,
stdin: bytes | None = None,
) -> CommandResult: ...
# -- reading ---------------------------------------------------------------------------------
def _sj_paths(self) -> Paths:
return Paths(
system_files=self.CRON_SYSTEM_FILES,
cron_d_dirs=self.CRON_D_DIRS,
spool_dirs=self.CRON_SPOOL_DIRS,
run_parts=self.RUN_PARTS_DIRS,
anacrontab=self.ANACRONTAB,
script_dir=self.JOB_SCRIPT_DIR,
owners_sh=self.OWNERS_SH,
time_zone_sh=self.TIME_ZONE_SH,
)
def _sj_read(self) -> Reading:
result = self.run_command(
reading_command(self._sj_paths()), privileged=True, timeout=_READ_TIMEOUT
)
reading = parse_reading(result.stdout)
for job in reading.jobs:
source = str(job["source"])
if job["managed_by"] != "application" and any(
fnmatch.fnmatchcase(source, p) for p in self.PLATFORM_SOURCES
):
job["managed_by"] = "platform"
return reading
def get_scheduled_jobs(self) -> ScheduledJobsReadingDict:
"""Every scheduled job of the host, in one round trip.
:raises ValueError: when the report came back cut short.
"""
reading = self._sj_read()
return {"jobs": reading.jobs, "time_zone": reading.time_zone} # type: ignore[typeddict-item]
def _sj_job(self, reading: Reading, key: str, digest: str) -> dict[str, object]:
job = next((j for j in reading.jobs if j["key"] == key), None)
if job is None:
raise LookupError(f"no scheduled job {key}")
if job["digest"] != digest:
raise ScheduledJobChanged(f"{key} changed on the host since it was read")
return job
# -- commands --------------------------------------------------------------------------------
def _sj_root(self, argv: Sequence[str], timeout: float = 60) -> CommandResult:
return self.run_command(_command(argv), privileged=True, timeout=timeout)
def _sj_checked(self, argv: Sequence[str]) -> CommandResult:
result = self._sj_root(argv)
if result.exit_code != 0:
raise RuntimeError(f"{_command(argv)}: {_said(result) or result.exit_code}")
return result
def _sj_stage(self, content: str) -> str:
result = self.run_command(_STAGE, timeout=30, stdin=content.encode())
path = result.stdout.strip().splitlines()[-1:] or [""]
if result.exit_code != 0 or not path[0].startswith("/"):
raise RuntimeError(f"cannot stage a file: {_said(result)}")
return path[0]
def _sj_install(self, content: str, path: str, mode: str, owner: str, group: str) -> None:
staged = self._sj_stage(content)
try:
self._sj_checked(
[*self.INSTALL, "-m", mode, "-o", owner, "-g", group, "--", staged, path]
)
finally:
self.run_command(_command(["rm", "-f", "--", staged]), timeout=30)
# -- crontab files ---------------------------------------------------------------------------
def _sj_spool_user(self, path: str) -> str | None:
"""The user whose crontab *path* is; None for a system file."""
directory, _, user = path.rpartition("/")
return user if directory in self.CRON_SPOOL_DIRS else None
def _sj_crontab(self, user: str) -> str:
result = self._sj_root(["crontab", "-u", user, "-l"])
if result.exit_code != 0:
if "no crontab" in (result.stderr + result.stdout).lower():
return ""
raise RuntimeError(f"cannot read the crontab of {user}: {_said(result)}")
return result.stdout
def _sj_text(self, path: str) -> str:
user = self._sj_spool_user(path)
if user is not None:
return self._sj_crontab(user)
return self._sj_checked(["cat", "--", path]).stdout
def _sj_write_crontab(self, user: str, text: str) -> None:
staged = self._sj_stage(text)
try:
self._sj_checked(["crontab", "-u", user, staged])
finally:
self.run_command(_command(["rm", "-f", "--", staged]), timeout=30)
if self.CRONTAB_AFTER_WRITE:
self._sj_checked(self.CRONTAB_AFTER_WRITE)
def _sj_write(self, path: str, text: str) -> None:
user = self._sj_spool_user(path)
if user is not None:
self._sj_write_crontab(user, text)
return
# Through a symbolic link to the file it names, with that file's mode: the
# link's own mode is 777, and cron ignores a file anyone may write.
real = self._sj_checked(["readlink", "-f", "--", path]).stdout.strip() or path
mode, owner, group = self._sj_checked([*self.STAT_ARGV, real]).stdout.split()[:3]
self._sj_install(text, real, mode, owner, group)
def _sj_line(self, job: dict[str, object], text: str) -> CronLine:
"""The job's line in *text* as it is now, read again for the write."""
path = str(job["source"])
if job["kind"] == "anacron":
found = parse_anacrontab(text)
else:
user = self._sj_spool_user(path)
found = parse_crontab(path, text, system=user is None, user=user or "")
line = next((ln for ln in found if ln.key == job["key"]), None)
if line is None:
raise ScheduledJobChanged(f"{job['key']} is no longer in {path}")
return line
# -- switching and running -------------------------------------------------------------------
def _sj_timer_unit(self, job: dict[str, object]) -> str:
key = str(job["key"])
return f"{job['name']}.timer" if key.startswith("job:") else key.removeprefix("timer:")
def _sj_switch(self, job: dict[str, object], enabled: bool) -> ScheduledJobResultDict:
word = "enabled" if enabled else "disabled"
if job["kind"] == "systemd_timer":
verb = "enable" if enabled else "disable"
return _result(
self._sj_root(["systemctl", verb, "--now", "--", self._sj_timer_unit(job)]), word
)
if job["kind"] == "run_parts":
return _result(
self._sj_root(["chmod", "+x" if enabled else "-x", "--", str(job["source"])]), word
)
path = str(job["source"])
text = self._sj_text(path)
self._sj_write(path, switched(text, self._sj_line(job, text), enabled=enabled))
return {"success": True, "output": f"{job['key']} {word}"}
def _sj_as(self, user: str, script: str) -> list[str]:
"""*script* run by ``sh`` as *user*, from root."""
if user == "root":
return ["sh", "-c", script]
return ["su", "-s", "/bin/sh", user, "-c", script]
def _sj_run(self, job: dict[str, object], reading: Reading) -> ScheduledJobResultDict:
bound = ["timeout", str(RUN_TIMEOUT)]
wait = RUN_TIMEOUT + 30
if job["kind"] == "systemd_timer":
unit = reading.units[str(job["key"])]
since = self.run_command("date +%s", timeout=30).stdout.strip()
started = self._sj_root([*bound, "systemctl", "start", "--", unit], timeout=wait)
journal = self._sj_root(
[
"journalctl",
"-u",
unit,
"--since",
f"@{since}",
"--no-pager",
"-o",
"cat",
"-n",
"200",
]
)
output = "\n".join(p for p in (_said(started), journal.stdout.strip()) if p)
return {"success": started.exit_code == 0, "output": output or f"{unit} ran"}
if job["kind"] == "run_parts":
return _result(self._sj_root([*bound, str(job["source"])], timeout=wait), "ran")
path = str(job["source"])
line = self._sj_line(job, self._sj_text(path))
script = run_script(line.command, line.env)
return _result(
self._sj_root([*bound, *self._sj_as(line.run_as, script)], timeout=wait), "ran"
)
def manage_scheduled_job(self, key: str, action: str, *, digest: str) -> ScheduledJobResultDict:
"""Enable, disable or run the job *key* now; see :class:`ScheduledJobsMixin`."""
if action not in ACTIONS:
raise ScheduledJobRefused(f"unknown action {action!r}; allowed: {list(ACTIONS)}")
reading = self._sj_read()
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")
if action == "run":
return self._sj_run(job, reading)
return self._sj_switch(job, action == "enable")
# -- an application's own jobs ---------------------------------------------------------------
def _sj_own(
self, reading: Reading, spec: ScheduledJobSpecDict, digest: str | None
) -> dict[str, object] | None:
current = next((j for j in reading.jobs if j["key"] == f"job:{spec['name']}"), None)
if digest is None:
if current is not None:
raise ScheduledJobChanged(f"a job {spec['name']} is there already")
return None
if current is None:
raise LookupError(f"no scheduled job job:{spec['name']}")
if current["digest"] != digest:
raise ScheduledJobChanged(f"job:{spec['name']} changed on the host since it was read")
return current
def _sj_group(self, user: str) -> str:
result = self.run_command(_command(["id", "-gn", "--", user]), timeout=30)
if result.exit_code != 0:
raise ScheduledJobRefused(f"the host has no user {user}")
return result.stdout.strip()
def _sj_calendar(self, schedule: str) -> list[str]:
if is_reboot(schedule):
return ["OnBootSec=1min"]
lines = to_on_calendar(schedule)
for line in lines:
checked = self.run_command(
_command(["systemd-analyze", "calendar", "--", line]), timeout=30
)
if checked.exit_code != 0:
raise ScheduledJobRefused(f"systemd does not take {line!r}: {_said(checked)}")
return [f"OnCalendar={line}" for line in lines]
def _sj_put_timer(self, spec: ScheduledJobSpecDict) -> None:
name, description = spec["name"], spec.get("description") or spec["name"]
script = f"{self.JOB_SCRIPT_DIR}/{name}"
unit_description = description.replace("%", "%%")
timer = "\n".join(
[
"[Unit]",
f"Description={unit_description}",
"",
"[Timer]",
*self._sj_calendar(spec["schedule"]),
f"Unit={name}.service",
"",
"[Install]",
"WantedBy=timers.target",
"",
]
)
service = "\n".join(
[
"[Unit]",
f"Description={unit_description}",
"",
"[Service]",
"Type=oneshot",
f"User={spec['run_as']}",
f"ExecStart={script}",
"",
]
)
body = f"#!/bin/sh\n{JOB_MARKER}{name} {spec.get('description') or ''}".rstrip()
body += f"\n{SCHEDULE_HEADER}{spec['schedule']}\n{spec['command'].strip()}\n"
self._sj_install(body, script, "750", "root", self._sj_group(spec["run_as"]))
self._sj_install(service, f"{self.UNIT_DIR}/{name}.service", "644", "root", self.ROOT_GROUP)
self._sj_install(timer, f"{self.UNIT_DIR}/{name}.timer", "644", "root", self.ROOT_GROUP)
self._sj_checked(["systemctl", "daemon-reload"])
verb = "enable" if spec["enabled"] else "disable"
self._sj_checked(["systemctl", verb, "--now", "--", f"{name}.timer"])
def _sj_cron_text(self, spec: ScheduledJobSpecDict, *, system: bool) -> list[str]:
if "\n" in spec["command"].strip():
raise ScheduledJobRefused("a cron line holds one line of command")
owner = f" {spec['run_as']}" if system else ""
line = f"{spec['schedule']}{owner} {spec['command'].strip()}"
return marked_lines(
spec["name"], spec.get("description") or "", line, enabled=spec["enabled"]
)
def _sj_cron_d(self) -> str | None:
""":attr:`OWN_CRON_D_DIR` where the host has it; BusyBox crond reads none."""
directory = self.OWN_CRON_D_DIR
if directory is None:
return None
found = self.run_command(_command(["test", "-d", directory]), timeout=30)
return directory if found.exit_code == 0 else None
def _sj_put_cron(self, spec: ScheduledJobSpecDict, current: dict[str, object] | None) -> None:
if self._sj_cron_d() is not None:
self._sj_group(spec["run_as"])
text = "\n".join(self._sj_cron_text(spec, system=True)) + "\n"
self._sj_install(
text, f"{self.OWN_CRON_D_DIR}/{spec['name']}", "644", "root", self.ROOT_GROUP
)
return
if current is not None and current["run_as"] != spec["run_as"]:
self._sj_delete_cron(current)
user = spec["run_as"]
text = self._sj_crontab(user)
jobs = parse_crontab("", text, system=False, user=user)
self._sj_write_crontab(
user, with_job(text, jobs, spec["name"], self._sj_cron_text(spec, system=False))
)
def put_scheduled_job(
self, spec: ScheduledJobSpecDict, *, digest: str | None = None
) -> ScheduledJobResultDict:
"""Create or change the application's own job; see :class:`ScheduledJobsMixin`."""
check_spec(spec)
reading = self._sj_read()
current = self._sj_own(reading, spec, digest)
if reading.systemd:
self._sj_put_timer(spec)
else:
self._sj_put_cron(spec, current)
return {
"success": True,
"output": f"job:{spec['name']} {'changed' if current else 'created'}",
}
def _sj_delete_cron(self, job: dict[str, object]) -> None:
path = str(job["source"])
if self._sj_spool_user(path) is None:
self._sj_checked(["rm", "-f", "--", path])
return
text = self._sj_text(path)
jobs = parse_crontab(path, text, system=False, user=str(job["run_as"]))
self._sj_write(path, without_job(text, jobs, str(job["name"])))
def delete_scheduled_job(self, key: str, *, digest: str) -> ScheduledJobResultDict:
"""Delete the application's job *key*; see :class:`ScheduledJobsMixin`."""
job = self._sj_job(self._sj_read(), key, digest)
if job["managed_by"] != "application":
raise ScheduledJobRefused(
f"{key} was not written by an application; it is only switched"
)
name = str(job["name"])
if job["kind"] != "systemd_timer":
self._sj_delete_cron(job)
return {"success": True, "output": f"{key} deleted"}
self._sj_root(["systemctl", "disable", "--now", "--", f"{name}.timer"])
self._sj_checked(
[
"rm",
"-f",
"--",
f"{self.UNIT_DIR}/{name}.timer",
f"{self.UNIT_DIR}/{name}.service",
f"{self.JOB_SCRIPT_DIR}/{name}",
]
)
self._sj_checked(["systemctl", "daemon-reload"])
return {"success": True, "output": f"{key} deleted"}
+18 -2
View File
@@ -15,7 +15,9 @@ accident.
``/etc/ssh/sshd_config.d/*.conf`` -- Debian and Ubuntu do, at the top -- the
lists go to :data:`DROPIN_PATH`, which sorts first and so wins. sshd_config
stays as the distribution shipped it, and removing the file undoes the change.
Only without such an ``Include`` is sshd_config itself rewritten, after a copy.
Only without such an ``Include`` is sshd_config itself rewritten, after a copy --
and not at all on a platform that generates it
(:attr:`OpenSshServerMixin.SSHD_CONFIG_GENERATED`).
**Nobody is locked out, by three checks.**
@@ -426,9 +428,16 @@ class OpenSshServerMixin:
whose platform writes sshd_config itself (an appliance that regenerates it
from its own database) must not inherit this, or must opt out with
``harden_ssh_server = None``: its file would be overwritten on the next
apply.
apply. Where that generated file still includes the drop-in directory, the
driver sets :attr:`SSHD_CONFIG_GENERATED` instead and keeps the hardening.
"""
#: True where the platform writes sshd_config from its own database
#: (OpenMediaVault): only the drop-in directory is written, and a
#: sshd_config that does not include it is left alone, since the platform
#: would write over a change to it on its next apply.
SSHD_CONFIG_GENERATED: bool = False
if TYPE_CHECKING: # pragma: no cover - declared for type checkers only
def run_command(
@@ -565,6 +574,13 @@ class OpenSshServerMixin:
main = self._ssh_read(MAIN_CONFIG)
if main is None:
raise RuntimeError(f"cannot read {MAIN_CONFIG}")
if self.SSHD_CONFIG_GENERATED and not has_dropin_include(main):
result.message = (
f"Not changed: {MAIN_CONFIG} does not include {DROPIN_DIR}, and this"
" platform writes it from its own settings."
)
say(result.message)
return result
restore = self._write_change(plan, main, result, say)
return self._apply_or_restore(
result,
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "napalm-device-types"
version = "4.25.0"
version = "4.27.0"
description = "Abstract device-type base classes for NAPALM drivers"
readme = "README.md"
requires-python = ">=3.12"
+1 -1
View File
@@ -32,7 +32,7 @@
},
"mypy_relaxed": [],
"python_file_lines": {
"napalm_device_types/models.py": 1463
"napalm_device_types/models.py": 1454
},
"untyped_public": []
}
+141
View File
@@ -0,0 +1,141 @@
"""Cron expressions: what they mean, when they fire next, and as systemd ``OnCalendar``.
One module answers all three, because a job netOrk writes as a timer must fire
exactly when the cron expression the user gave says, and the preview must show
the same runs the host will make (NetOrk/netork#1933).
"""
from __future__ import annotations
from datetime import UTC, datetime
from zoneinfo import ZoneInfo
import pytest
from napalm_device_types.cron import is_reboot, next_runs, parse_cron, to_on_calendar
BERLIN = ZoneInfo("Europe/Berlin")
class TestParse:
def test_every_field_is_expanded_to_its_values(self):
s = parse_cron("*/15 6-8 1,15 * *")
assert s.minutes == frozenset({0, 15, 30, 45})
assert s.hours == frozenset({6, 7, 8})
assert s.days == frozenset({1, 15})
assert s.months == frozenset(range(1, 13))
assert s.weekdays == frozenset(range(7))
def test_a_range_takes_a_step(self):
assert parse_cron("1-30/10 * * * *").minutes == frozenset({1, 11, 21})
def test_names_are_months_and_weekdays_in_any_case(self):
s = parse_cron("0 0 * Jan,MAR mon-Fri")
assert s.months == frozenset({1, 3})
assert s.weekdays == frozenset({1, 2, 3, 4, 5})
def test_seven_is_sunday_too(self):
assert parse_cron("0 0 * * 7").weekdays == frozenset({0})
@pytest.mark.parametrize(
("alias", "expanded"),
[
("@hourly", "0 * * * *"),
("@daily", "0 0 * * *"),
("@midnight", "0 0 * * *"),
("@weekly", "0 0 * * 0"),
("@monthly", "0 0 1 * *"),
("@yearly", "0 0 1 1 *"),
("@annually", "0 0 1 1 *"),
],
)
def test_an_alias_is_its_expression(self, alias, expanded):
assert parse_cron(alias) == parse_cron(expanded)
def test_reboot_is_no_calendar(self):
assert is_reboot("@reboot")
assert not is_reboot("0 0 * * *")
with pytest.raises(ValueError, match="reboot"):
parse_cron("@reboot")
@pytest.mark.parametrize(
"bad",
[
"",
"* * * *",
"* * * * * *",
"60 * * * *",
"* 24 * * *",
"* * 0 * *",
"* * * 13 *",
"* * * * 8",
"*/0 * * * *",
"5-1 * * * *",
"a * * * *",
"@often",
"1,,2 * * * *",
],
)
def test_what_cron_would_not_take_is_refused(self, bad):
with pytest.raises(ValueError):
parse_cron(bad)
def test_day_of_month_and_weekday_are_or_only_when_both_are_restricted(self):
assert parse_cron("0 0 1 * 1").either_day
assert not parse_cron("0 0 */2 * 1").either_day
assert not parse_cron("0 0 1 * *").either_day
class TestNextRuns:
def test_runs_after_the_instant_in_the_hosts_time(self):
after = datetime(2026, 11, 3, 5, 50, tzinfo=UTC) # 06:50 in Berlin
runs = next_runs("0 7 * * *", after, BERLIN, count=2)
assert runs == [
datetime(2026, 11, 3, 7, 0, tzinfo=BERLIN),
datetime(2026, 11, 4, 7, 0, tzinfo=BERLIN),
]
def test_the_instant_itself_is_not_a_next_run(self):
after = datetime(2026, 11, 3, 6, 0, tzinfo=UTC)
assert next_runs("0 6 * * *", after, ZoneInfo("UTC"), count=1)[0].day == 4
def test_either_day_fires_on_both(self):
after = datetime(2026, 11, 30, 12, 0, tzinfo=UTC) # a Monday
runs = next_runs("0 0 1 * 1", after, ZoneInfo("UTC"), count=3)
assert [r.day for r in runs] == [1, 7, 14]
def test_a_day_that_never_comes_gives_no_runs(self):
assert next_runs("0 0 31 2 *", datetime(2026, 1, 1, tzinfo=UTC), BERLIN) == []
def test_a_time_the_clock_skips_is_left_out(self):
# 2026-03-29 02:30 does not exist in Berlin.
after = datetime(2026, 3, 28, 12, 0, tzinfo=UTC)
runs = next_runs("30 2 * * *", after, BERLIN, count=2)
assert [r.day for r in runs] == [30, 31]
def test_reboot_has_no_next_run(self):
assert next_runs("@reboot", datetime(2026, 1, 1, tzinfo=UTC), BERLIN) == []
class TestOnCalendar:
def test_every_field_as_its_values(self):
assert to_on_calendar("*/15 6 * * *") == ["*-*-* 06:00,15,30,45:00"]
def test_a_restricted_weekday_leads(self):
assert to_on_calendar("30 4 * * 1-5") == ["Mon,Tue,Wed,Thu,Fri *-*-* 04:30:00"]
def test_months_and_days(self):
assert to_on_calendar("0 0 1,15 1,7 *") == ["*-01,07-01,15 00:00:00"]
def test_either_day_is_two_lines(self):
assert to_on_calendar("0 0 1 * 0") == ["*-*-01 00:00:00", "Sun *-*-* 00:00:00"]
def test_both_days_with_a_star_are_one_line(self):
assert to_on_calendar("0 0 */10 * 6") == ["Sat *-*-01,11,21,31 00:00:00"]
def test_an_alias(self):
assert to_on_calendar("@daily") == ["*-*-* 00:00:00"]
def test_reboot_is_refused(self):
with pytest.raises(ValueError, match="reboot"):
to_on_calendar("@reboot")
+145
View File
@@ -0,0 +1,145 @@
"""Crontabs as text: the jobs in them, and changing one line (NetOrk/netork#1933)."""
from __future__ import annotations
import subprocess
import pytest
from napalm_device_types._crontab import (
DISABLED_MARKER,
marked_lines,
parse_anacrontab,
parse_crontab,
run_script,
switched,
with_job,
without_job,
)
SYSTEM = """\
# /etc/crontab: system-wide crontab
SHELL=/bin/sh
PATH="/usr/local/sbin:/usr/bin:/bin"
17 * * * * root cd / && run-parts --report /etc/cron.hourly
@reboot root /usr/local/bin/warm-cache # keeps the # in the command
#napalm-disabled: 0 4 * * * backup /usr/local/bin/backup
garbage line
0 4 * * * backup /usr/local/bin/backup
"""
USER = """\
MAILTO=ops@example.org
*/5 * * * * /usr/bin/php /var/www/cron.php
# napalm-scheduled-job: netork-cleanup tidy the cache
0 3 * * * find /tmp -mtime +7 -delete
"""
class TestParse:
def test_a_system_crontab_names_the_user(self):
jobs = parse_crontab("/etc/crontab", SYSTEM, system=True)
first = jobs[0]
assert (first.schedule, first.run_as) == ("17 * * * *", "root")
assert first.command == "cd / && run-parts --report /etc/cron.hourly"
assert first.env == {"SHELL": "/bin/sh", "PATH": "/usr/local/sbin:/usr/bin:/bin"}
assert first.key.startswith("cron:/etc/crontab:")
def test_an_alias_and_a_hash_inside_the_command(self):
reboot = parse_crontab("/etc/crontab", SYSTEM, system=True)[1]
assert reboot.schedule == "@reboot"
assert reboot.command == "/usr/local/bin/warm-cache # keeps the # in the command"
def test_a_line_switched_off_is_a_job_that_is_off(self):
jobs = parse_crontab("/etc/crontab", SYSTEM, system=True)
off = jobs[2]
assert not off.enabled
assert off.run_as == "backup"
def test_equal_lines_get_their_own_keys_and_switching_off_keeps_the_key(self):
jobs = parse_crontab("/etc/crontab", SYSTEM, system=True)
assert jobs[3].key == jobs[2].key + ":2"
assert len(jobs) == 4 # the garbage line is left out
def test_a_user_crontab_runs_as_its_user(self):
jobs = parse_crontab("/var/spool/cron/crontabs/www", USER, system=False, user="www-data")
assert jobs[0].run_as == "www-data"
assert jobs[0].env == {"MAILTO": "ops@example.org"}
def test_an_applications_job_is_keyed_by_its_name(self):
job = parse_crontab("/x", USER, system=False, user="root")[1]
assert (job.key, job.name, job.description) == (
"job:netork-cleanup",
"netork-cleanup",
"tidy the cache",
)
def test_an_anacrontab(self):
text = "SHELL=/bin/sh\n1\t5\tcron.daily\trun-parts --report /etc/cron.daily\n@monthly 15 cron.monthly run-parts /etc/cron.monthly\nbad line here\n"
jobs = parse_anacrontab(text)
assert [(j.key, j.schedule, j.run_as) for j in jobs] == [
("anacron:cron.daily", "1", "root"),
("anacron:cron.monthly", "@monthly", "root"),
]
assert jobs[0].command == "run-parts --report /etc/cron.daily"
class TestEdit:
def test_switching_off_and_on_again_gives_the_text_back(self):
jobs = parse_crontab("/etc/crontab", SYSTEM, system=True)
off = switched(SYSTEM, jobs[0], enabled=False)
assert DISABLED_MARKER + "17 *\t* * *\troot" in off
again = parse_crontab("/etc/crontab", off, system=True)
assert again[0].key == jobs[0].key and not again[0].enabled
assert switched(off, again[0], enabled=True) == SYSTEM.replace(
"17 *\t* * *\troot\tcd", "17 *\t* * *\troot\tcd"
)
def test_an_applications_job_is_added_replaced_and_removed(self):
lines = marked_lines("netork-x", "a job", "0 1 * * * /bin/true", enabled=True)
added = with_job("A=1\n", [], "netork-x", lines)
assert added == "A=1\n# napalm-scheduled-job: netork-x a job\n0 1 * * * /bin/true\n"
jobs = parse_crontab("/x", added, system=False, user="root")
changed = with_job(
added,
jobs,
"netork-x",
marked_lines("netork-x", "", "0 2 * * * /bin/true", enabled=False),
)
assert (
changed
== "A=1\n# napalm-scheduled-job: netork-x\n#napalm-disabled: 0 2 * * * /bin/true\n"
)
jobs = parse_crontab("/x", changed, system=False, user="root")
assert without_job(changed, jobs, "netork-x") == "A=1\n"
def test_adding_to_a_text_without_a_last_newline(self):
assert with_job("A=1", [], "n", ["# m", "x"]) == "A=1\n# m\nx\n"
def test_removing_the_only_job_leaves_nothing(self):
text = "# napalm-scheduled-job: n\n0 1 * * * x\n"
jobs = parse_crontab("/x", text, system=False, user="root")
assert without_job(text, jobs, "n") == ""
class TestRunScript:
def _run(self, script: str) -> str:
return subprocess.run(
["sh", "-c", script], capture_output=True, text=True, check=True
).stdout
def test_the_crontabs_variables_are_set(self):
assert (
self._run(run_script('echo "$GREETING"', {"GREETING": "hi there", "MAILTO": "x"}))
== "hi there\n"
)
def test_a_percent_starts_stdin_and_further_ones_are_newlines(self):
assert self._run(run_script("cat%one%two", {})) == "one\ntwo\n"
def test_an_escaped_percent_is_a_percent(self):
assert self._run(run_script("date -d @0 -u +\\%Y", {})) == "1970\n"
@pytest.mark.parametrize("command", ["echo plain", "echo 'quoted'"])
def test_without_percent_the_command_is_as_it_is(self, command):
assert run_script(command, {}) == command
+108
View File
@@ -0,0 +1,108 @@
"""The scheduled-jobs contract: its digest, the names and specs it takes (NetOrk/netork#1933)."""
from __future__ import annotations
import pytest
from napalm_device_types import ScheduledJobsMixin
from napalm_device_types.scheduled_jobs import (
ACTIONS,
ScheduledJobChanged,
ScheduledJobRefused,
check_job_name,
check_spec,
job_digest,
)
JOB = {
"kind": "cron",
"source": "/etc/crontab",
"run_as": "root",
"schedule": "*/5 * * * *",
"command": "/usr/local/bin/backup",
"enabled": True,
}
class TestDigest:
def test_sixteen_hex_characters(self):
digest = job_digest(JOB)
assert len(digest) == 16
int(digest, 16)
def test_the_same_definition_has_the_same_digest(self):
assert job_digest(JOB) == job_digest(dict(JOB))
@pytest.mark.parametrize(
"field, value",
[
("schedule", "0 * * * *"),
("command", "/usr/local/bin/other"),
("run_as", "nobody"),
("enabled", False),
("source", "/etc/cron.d/backup"),
("kind", "anacron"),
],
)
def test_every_part_of_the_definition_changes_it(self, field, value):
assert job_digest({**JOB, field: value}) != job_digest(JOB)
def test_content_the_definition_points_at_changes_it(self):
assert job_digest(JOB, content="12345 678") != job_digest(JOB)
def test_what_the_host_says_of_its_runs_does_not(self):
assert job_digest({**JOB, "last_run": "2026-11-03T06:00:00Z"}) == job_digest(JOB)
class TestNames:
@pytest.mark.parametrize("name", ["backup", "netork-backup-db", "a", "x1"])
def test_a_good_name(self, name):
check_job_name(name)
@pytest.mark.parametrize("name", ["", "-x", "Backup", "a b", "a/b", "a.timer", "a" * 64])
def test_a_name_a_file_or_unit_could_not_carry_safely(self, name):
with pytest.raises(ScheduledJobRefused):
check_job_name(name)
class TestSpec:
SPEC = {
"name": "backup",
"schedule": "0 3 * * *",
"run_as": "root",
"command": "/usr/local/bin/backup",
"enabled": True,
}
def test_a_good_spec(self):
check_spec(self.SPEC)
check_spec({**self.SPEC, "schedule": "@reboot"})
@pytest.mark.parametrize(
"field, value",
[
("schedule", "every day"),
("run_as", "root; rm"),
("run_as", ""),
("command", ""),
("command", " "),
("description", "two\nlines"),
],
)
def test_a_spec_that_cannot_be_written(self, field, value):
with pytest.raises(ScheduledJobRefused):
check_spec({**self.SPEC, field: value})
class TestContract:
def test_the_mixin_declares_nothing_at_runtime(self):
driver = ScheduledJobsMixin()
for method in ("get_scheduled_jobs", "manage_scheduled_job", "put_scheduled_job"):
assert not hasattr(driver, method)
def test_the_actions(self):
assert ACTIONS == ("enable", "disable", "run")
def test_a_refusal_is_a_value_error_and_a_change_is_not(self):
assert issubclass(ScheduledJobRefused, ValueError)
assert not issubclass(ScheduledJobChanged, ValueError)
+540
View File
@@ -0,0 +1,540 @@
"""Scheduled jobs on a POSIX host: the report as root, switching, running, an application's jobs.
The reading command is run by a real ``sh`` over a directory tree that stands in
for the host, with ``systemctl``, ``crontab``, ``dpkg``, ``install`` and
``journalctl`` replaced by scripts that keep a log -- so the shell itself is what
is tested, not a hand-written copy of its output (NetOrk/netork#1933).
"""
from __future__ import annotations
import os
import subprocess
from pathlib import Path
import pytest
from napalm_device_types import PosixScheduledJobsMixin
from napalm_device_types._scheduled_reading import parse_reading
from napalm_device_types.channel import CommandResult
from napalm_device_types.scheduled_jobs import ScheduledJobChanged, ScheduledJobRefused
TIMERS = """\
Id=apt-daily.timer
Unit=apt-daily.service
Description=Daily apt download activities
TimersCalendar={ OnCalendar=*-*-* 06,18:00:00 ; next_elapse=@1762192800 }
NextElapseUSecRealtime=@1762192800
LastTriggerUSec=@1762149600
UnitFileState=enabled
ActiveState=active
FragmentPath=/usr/lib/systemd/system/apt-daily.timer
Id=fstrim.timer
Unit=fstrim.service
Description=Discard unused blocks once a week
TimersMonotonic={ OnUnitActiveUSec=1w ; next_elapse=n/a }
NextElapseUSecRealtime=n/a
LastTriggerUSec=n/a
UnitFileState=static
ActiveState=inactive
FragmentPath=/etc/systemd/system/fstrim.timer
Id=backup.timer
Unit=backup.service
Description=netork backup
TimersCalendar={ OnCalendar=*-*-* 03:00:00 ; next_elapse=n/a }
NextElapseUSecRealtime=Tue 2026-11-04 03:00:00 UTC
LastTriggerUSec=n/a
UnitFileState=enabled
ActiveState=active
FragmentPath=/etc/systemd/system/backup.timer
"""
UNITS = """\
Id=apt-daily.service
ExecStart={ path=/usr/lib/apt/apt.systemd.daily ; argv[]=/usr/lib/apt/apt.systemd.daily update ; ignore_errors=no ; start_time=[n/a] ; stop_time=[n/a] ; pid=0 ; code=(null) ; status=0/0 }
User=
Result=success
FragmentPath=/usr/lib/systemd/system/apt-daily.service
Id=fstrim.service
ExecStart={ path=/sbin/fstrim ; argv[]=/sbin/fstrim --listed-in /etc/fstab ; ignore_errors=no }
Result=success
FragmentPath=/usr/lib/systemd/system/fstrim.service
Id=backup.service
ExecStart={ path=SCRIPTS/backup ; argv[]=SCRIPTS/backup ; ignore_errors=no }
User=backup
Result=exit-code
FragmentPath=/etc/systemd/system/backup.service
"""
SYSTEMCTL = """#!/bin/sh
echo "systemctl $*" >> "$LOG"
case "$1" in
list-unit-files) printf 'apt-daily.timer enabled enabled\\nfstrim.timer static -\\nbackup.timer enabled enabled\\ngetty@.timer static -\\n' ;;
show) case "$*" in *Unit,Description*) sed "s#SCRIPTS#$SCRIPTS#g" "$FIX/timers" ;; *) sed "s#SCRIPTS#$SCRIPTS#g" "$FIX/units" ;; esac ;;
esac
"""
CRONTAB = """#!/bin/sh
echo "crontab $*" >> "$LOG"
[ "$1" = -u ] || exit 2
if [ "$3" = -l ]; then
[ -f "$SPOOL/$2" ] || { echo "no crontab for $2" >&2; exit 1; }
cat "$SPOOL/$2"
else
cp "$3" "$SPOOL/$2"
fi
"""
DPKG = """#!/bin/sh
for p in "$@"; do case " $OWNED " in *" $p "*) echo "cron: $p" ;; esac; done
"""
INSTALL = """#!/bin/sh
echo "install $*" >> "$LOG"
args=""
while [ $# -gt 0 ]; do case "$1" in -o|-g) shift 2 ;; *) args="$args '$1'"; shift ;; esac; done
eval "/usr/bin/install $args"
"""
ECHO_LOG = """#!/bin/sh
echo "$(basename "$0") $*" >> "$LOG"
[ "$(basename "$0")" = journalctl ] && echo "backup ran fine"
exit 0
"""
class Host(PosixScheduledJobsMixin):
"""A host in a directory; every command is run by sh, root or not."""
def __init__(self, root: Path, *, systemd: bool = True, own_cron_d: bool = True) -> None:
self.root = root
etc = root / "etc"
self.CRON_SYSTEM_FILES = (str(etc / "crontab"),) # type: ignore[misc]
self.CRON_D_DIRS = (str(etc / "cron.d"),) # type: ignore[misc]
self.CRON_SPOOL_DIRS = (str(root / "spool"),) # type: ignore[misc]
self.RUN_PARTS_DIRS = (("daily", str(etc / "cron.daily")),) # type: ignore[misc]
self.ANACRONTAB = str(etc / "anacrontab") # type: ignore[misc]
self.JOB_SCRIPT_DIR = str(root / "scripts") # type: ignore[misc]
self.UNIT_DIR = str(root / "units") # type: ignore[misc]
self.OWN_CRON_D_DIR = str(etc / "cron.d") if own_cron_d else None # type: ignore[misc]
self.ROOT_GROUP = subprocess.run(
["id", "-gn"], capture_output=True, text=True
).stdout.strip() # type: ignore[misc]
self.systemd_dir = root / ("run-systemd" if systemd else "no-systemd")
self.commands: list[str] = []
def _sj_paths(self): # type: ignore[no-untyped-def]
paths = super()._sj_paths()
from dataclasses import replace
return replace(paths, systemd_marker=str(self.systemd_dir))
def run_command(self, command, *, privileged=False, timeout=60, stdin=None): # type: ignore[no-untyped-def]
self.commands.append(command)
env = {
**os.environ,
"PATH": f"{self.root / 'bin'}:{os.environ['PATH']}",
"LOG": str(self.root / "log"),
"SPOOL": str(self.root / "spool"),
"FIX": str(self.root / "fix"),
"SCRIPTS": str(self.root / "scripts"),
"OWNED": str(self.root / "etc" / "crontab"),
}
done = subprocess.run(
["sh", "-c", command], input=stdin, capture_output=True, env=env, timeout=30
)
return CommandResult(done.stdout.decode(), done.stderr.decode(), done.returncode)
def log(self) -> str:
log = self.root / "log"
return log.read_text() if log.exists() else ""
def _tool(root: Path, name: str, body: str) -> None:
path = root / "bin" / name
path.write_text(body)
path.chmod(0o755)
@pytest.fixture
def root(tmp_path: Path) -> Path:
for d in (
"etc/cron.d",
"etc/cron.daily",
"spool",
"scripts",
"units",
"bin",
"fix",
"run-systemd",
):
(tmp_path / d).mkdir(parents=True)
(tmp_path / "etc/crontab").write_text(
"SHELL=/bin/sh\nOUT="
+ str(tmp_path / "out")
+ "\n17 * * * * root cd / && run-parts /etc/cron.hourly\n"
'*/5 * * * * root echo "$OUT" > ' + str(tmp_path / "ran") + "\n"
)
(tmp_path / "etc/cron.d/certbot").write_text("0 */12 * * * root certbot -q renew\n")
(tmp_path / "etc/anacrontab").write_text("1 5 cron.daily run-parts /etc/cron.daily\n")
(tmp_path / "spool/www-data").write_text("*/5 * * * * php /var/www/cron.php\n")
for name, mode in (("logrotate", 0o755), ("off", 0o644), ("x.dpkg-old", 0o755)):
script = tmp_path / "etc/cron.daily" / name
script.write_text("#!/bin/sh\necho rotated\n")
script.chmod(mode)
(tmp_path / "scripts/backup").write_text(
"#!/bin/sh\n# napalm-scheduled-job: backup nightly backup\n# schedule: 0 3 * * *\n/usr/local/bin/backup --all\n"
)
(tmp_path / "fix/timers").write_text(TIMERS)
(tmp_path / "fix/units").write_text(UNITS)
for name, body in (
("systemctl", SYSTEMCTL),
("crontab", CRONTAB),
("dpkg", DPKG),
("install", INSTALL),
("journalctl", ECHO_LOG),
("systemd-analyze", ECHO_LOG),
):
_tool(tmp_path, name, body)
return tmp_path
def _jobs(host: Host) -> dict[str, dict]:
return {j["key"]: j for j in host.get_scheduled_jobs()["jobs"]}
class TestReading:
def test_every_source_is_read(self, root: Path):
jobs = _jobs(Host(root))
kinds = sorted({j["kind"] for j in jobs.values()})
assert kinds == ["anacron", "cron", "run_parts", "systemd_timer"]
users = {j["run_as"] for j in jobs.values() if j["kind"] == "cron"}
assert users == {"root", "www-data"}
def test_a_package_owns_what_it_installed(self, root: Path):
jobs = _jobs(Host(root))
crontab = [j for j in jobs.values() if j["source"] == str(root / "etc/crontab")]
assert {j["managed_by"] for j in crontab} == {"package"}
certbot = next(j for j in jobs.values() if j["source"].endswith("certbot"))
assert certbot["managed_by"] == "admin"
def test_run_parts_by_execute_bit_and_the_names_run_parts_runs(self, root: Path):
jobs = _jobs(Host(root))
daily = root / "etc/cron.daily"
assert jobs[f"run-parts:{daily}/logrotate"]["enabled"]
assert not jobs[f"run-parts:{daily}/off"]["enabled"]
assert f"run-parts:{daily}/x.dpkg-old" not in jobs
def test_a_changed_script_changes_its_digest(self, root: Path):
host = Host(root)
key = f"run-parts:{root}/etc/cron.daily/logrotate"
before = _jobs(host)[key]["digest"]
(root / "etc/cron.daily/logrotate").write_text("#!/bin/sh\necho something else\n")
assert _jobs(host)[key]["digest"] != before
def test_timers_with_their_unit_and_runs(self, root: Path):
apt = _jobs(Host(root))["timer:apt-daily.timer"]
assert apt["schedule"] == "OnCalendar=*-*-* 06,18:00:00"
assert apt["schedule_kind"] == "calendar"
assert apt["command"] == "/usr/lib/apt/apt.systemd.daily update"
assert (apt["run_as"], apt["managed_by"], apt["enabled"]) == ("root", "package", True)
assert apt["last_run"] == "2025-11-03T06:00:00+00:00"
assert apt["next_run"] == "2025-11-03T18:00:00+00:00"
assert apt["last_result"] == "success"
assert apt["actions"] == ["enable", "disable", "run"]
def test_a_static_timer_only_runs(self, root: Path):
fstrim = _jobs(Host(root))["timer:fstrim.timer"]
assert fstrim["schedule"] == "OnUnitActiveSec=1w"
assert fstrim["schedule_kind"] == "monotonic"
assert fstrim["actions"] == ["run"]
assert fstrim.get("last_run") is None
assert fstrim["managed_by"] == "admin"
def test_an_applications_timer_by_its_script(self, root: Path):
backup = _jobs(Host(root))["job:backup"]
assert backup["managed_by"] == "application"
assert (backup["name"], backup["description"]) == ("backup", "nightly backup")
assert (backup["schedule"], backup["schedule_kind"]) == ("0 3 * * *", "cron")
assert backup["command"] == "/usr/local/bin/backup --all"
assert backup["run_as"] == "backup"
assert "edit" in backup["actions"] and "delete" in backup["actions"]
assert backup["next_run"] == "2026-11-04T03:00:00+00:00"
assert "last_result" not in backup
def test_a_file_without_a_last_newline_does_not_swallow_the_next(self, root: Path):
(root / "etc/cron.d/certbot").write_text("0 */12 * * * root certbot -q renew")
jobs = _jobs(Host(root))
assert any(j["source"].endswith("certbot") for j in jobs.values())
assert any(j["source"].endswith("spool/www-data") for j in jobs.values())
def test_without_systemd_no_timers(self, root: Path):
jobs = _jobs(Host(root, systemd=False))
assert not [j for j in jobs.values() if j["kind"] == "systemd_timer"]
def test_a_report_cut_short_raises(self, root: Path):
host = Host(root)
full = host.run_command
host.run_command = lambda c, **kw: full(c, **kw)._replace(
stdout=full(c, **kw).stdout.split("SJ_END")[0][:-3]
) # type: ignore[method-assign]
with pytest.raises(ValueError, match="cut short"):
host.get_scheduled_jobs()
class TestDriverSettings:
def test_what_the_platform_generates(self, root: Path):
host = Host(root)
host.PLATFORM_SOURCES = ("*/cron.d/cert*",) # type: ignore[misc]
certbot = next(j for j in _jobs(host).values() if j["source"].endswith("certbot"))
assert certbot["managed_by"] == "platform"
def test_the_time_zone_and_owners_commands_are_the_drivers(self, root: Path):
host = Host(root)
host.TIME_ZONE_SH = "echo America/New_York" # type: ignore[misc]
host.OWNERS_SH = "cat >/dev/null" # type: ignore[misc]
reading = host.get_scheduled_jobs()
assert reading["time_zone"] == "America/New_York"
assert {j["managed_by"] for j in reading["jobs"] if j["kind"] == "cron"} == {"admin"}
class TestParseReading:
def test_the_time_zone_from_either_file(self):
out = "SJ_BEGIN\n[tz]\n/usr/share/zoneinfo/Europe/Berlin\nSJ_END\n"
assert parse_reading(out).time_zone == "Europe/Berlin"
assert parse_reading("SJ_BEGIN\n[tz]\nEtc/UTC\nSJ_END").time_zone == "Etc/UTC"
assert parse_reading("SJ_BEGIN\n[tz]\nSJ_END").time_zone is None
def test_owners_skip_diversions(self):
out = "SJ_BEGIN\n[owners]\ndiversion by x from: /etc/crontab\ncron, cron-daemon: /etc/cron.d/x\nSJ_END"
reading = parse_reading(out + "")
assert reading.jobs == []
def test_a_time_not_in_utc_is_left_unknown(self):
from napalm_device_types._scheduled_reading import _timestamp
assert _timestamp("Tue 2026-11-04 03:00:00 CET") is None
assert _timestamp("@0") is None
class TestSwitching:
def _cron(self, host: Host, path: str) -> dict:
return next(j for j in _jobs(host).values() if j["source"] == path and j["kind"] == "cron")
def test_a_system_line_switched_off_and_on(self, root: Path):
host = Host(root)
path = str(root / "etc/cron.d/certbot")
job = self._cron(host, path)
mode = os.stat(path).st_mode
assert host.manage_scheduled_job(job["key"], "disable", digest=job["digest"])["success"]
assert (
root / "etc/cron.d/certbot"
).read_text() == "#napalm-disabled: 0 */12 * * * root certbot -q renew\n"
off = _jobs(host)[job["key"]]
assert not off["enabled"]
host.manage_scheduled_job(job["key"], "enable", digest=off["digest"])
assert (root / "etc/cron.d/certbot").read_text() == "0 */12 * * * root certbot -q renew\n"
assert f"install -D -m {mode & 0o777:o}" in host.log()
assert os.stat(path).st_mode == mode
def test_a_linked_file_is_written_through_its_link(self, root: Path):
real = root / "etc/vzdump.cron"
real.write_text("0 1 * * * root vzdump --all\n")
real.chmod(0o640)
link = root / "etc/cron.d/vzdump"
link.symlink_to(real)
host = Host(root)
job = self._cron(host, str(link))
host.manage_scheduled_job(job["key"], "disable", digest=job["digest"])
assert link.is_symlink()
assert real.read_text() == "#napalm-disabled: 0 1 * * * root vzdump --all\n"
assert real.stat().st_mode & 0o777 == 0o640
def test_a_users_line_goes_through_crontab(self, root: Path):
host = Host(root)
job = self._cron(host, str(root / "spool/www-data"))
host.manage_scheduled_job(job["key"], "disable", digest=job["digest"])
assert (root / "spool/www-data").read_text().startswith("#napalm-disabled: */5")
assert "crontab -u www-data /" in host.log()
def test_a_change_it_did_not_see_is_refused(self, root: Path):
host = Host(root)
job = self._cron(host, str(root / "etc/cron.d/certbot"))
with pytest.raises(ScheduledJobChanged):
host.manage_scheduled_job(job["key"], "disable", digest="0" * 16)
def test_an_unknown_job_and_an_unknown_action(self, root: Path):
host = Host(root)
with pytest.raises(LookupError):
host.manage_scheduled_job("cron:/nowhere:1", "disable", digest="x")
with pytest.raises(ScheduledJobRefused):
host.manage_scheduled_job("cron:/nowhere:1", "explode", digest="x")
def test_a_static_timer_is_not_disabled(self, root: Path):
host = Host(root)
fstrim = _jobs(host)["timer:fstrim.timer"]
with pytest.raises(ScheduledJobRefused):
host.manage_scheduled_job("timer:fstrim.timer", "disable", digest=fstrim["digest"])
def test_a_timer_and_a_run_parts_script(self, root: Path):
host = Host(root)
jobs = _jobs(host)
apt = jobs["timer:apt-daily.timer"]
host.manage_scheduled_job(apt["key"], "disable", digest=apt["digest"])
assert "systemctl disable --now -- apt-daily.timer" in host.log()
key = f"run-parts:{root}/etc/cron.daily/off"
host.manage_scheduled_job(key, "enable", digest=jobs[key]["digest"])
assert os.access(root / "etc/cron.daily/off", os.X_OK)
def test_an_applications_timer_is_switched_by_its_name(self, root: Path):
host = Host(root)
backup = _jobs(host)["job:backup"]
host.manage_scheduled_job("job:backup", "disable", digest=backup["digest"])
assert "systemctl disable --now -- backup.timer" in host.log()
class TestRunning:
def test_a_cron_line_runs_as_cron_would(self, root: Path):
host = Host(root)
job = next(j for j in _jobs(host).values() if "ran" in j["command"])
result = host.manage_scheduled_job(job["key"], "run", digest=job["digest"])
assert result["success"]
assert (root / "ran").read_text() == f"{root / 'out'}\n"
assert "timeout 300 sh -c" in host.commands[-1]
def test_a_timer_runs_its_unit_and_says_what_its_journal_said(self, root: Path):
host = Host(root)
backup = _jobs(host)["job:backup"]
result = host.manage_scheduled_job("job:backup", "run", digest=backup["digest"])
assert result == {"success": True, "output": "backup ran fine"}
assert "systemctl start -- backup.service" in host.log()
def test_a_run_parts_script_runs(self, root: Path):
host = Host(root)
key = f"run-parts:{root}/etc/cron.daily/logrotate"
result = host.manage_scheduled_job(key, "run", digest=_jobs(host)[key]["digest"])
assert result == {"success": True, "output": "rotated"}
def test_another_user_runs_through_su(self):
assert Host(Path("/x"))._sj_as("www-data", "true") == [
"su",
"-s",
"/bin/sh",
"www-data",
"-c",
"true",
]
SPEC = {
"name": "netork-tidy",
"schedule": "*/30 1-2 * * *",
"run_as": "root",
"command": "find /tmp -mtime +7 -delete",
"enabled": True,
"description": "tidy %tmp",
}
class TestApplicationJobs:
def test_a_timer_on_a_host_with_systemd(self, root: Path):
host = Host(root)
assert host.put_scheduled_job(SPEC)["output"] == "job:netork-tidy created"
timer = (root / "units/netork-tidy.timer").read_text()
assert "OnCalendar=*-*-* 01,02:00,30:00" in timer
assert "Description=tidy %%tmp" in timer
service = (root / "units/netork-tidy.service").read_text()
assert f"ExecStart={root}/scripts/netork-tidy" in service and "User=root" in service
script = (root / "scripts/netork-tidy").read_text()
assert script.splitlines()[1:] == [
"# napalm-scheduled-job: netork-tidy tidy %tmp",
"# schedule: */30 1-2 * * *",
"find /tmp -mtime +7 -delete",
]
assert "systemctl daemon-reload" in host.log()
assert "systemctl enable --now -- netork-tidy.timer" in host.log()
def test_reboot_is_a_boot_timer(self, root: Path):
Host(root).put_scheduled_job({**SPEC, "schedule": "@reboot", "enabled": False})
assert "OnBootSec=1min" in (root / "units/netork-tidy.timer").read_text()
def test_creating_one_that_is_there_and_changing_one_that_is_not(self, root: Path):
host = Host(root)
with pytest.raises(ScheduledJobChanged):
host.put_scheduled_job({**SPEC, "name": "backup"})
with pytest.raises(LookupError):
host.put_scheduled_job(SPEC, digest="x")
with pytest.raises(ScheduledJobChanged):
host.put_scheduled_job({**SPEC, "name": "backup"}, digest="x")
def test_an_unknown_user_is_refused(self, root: Path):
with pytest.raises(ScheduledJobRefused, match="no user"):
Host(root).put_scheduled_job({**SPEC, "run_as": "no-such-user-here"})
def test_a_timer_deleted(self, root: Path):
host = Host(root)
backup = _jobs(host)["job:backup"]
host.delete_scheduled_job("job:backup", digest=backup["digest"])
assert not (root / "scripts/backup").exists()
assert "systemctl disable --now -- backup.timer" in host.log()
def test_only_an_applications_job_is_deleted(self, root: Path):
host = Host(root)
apt = _jobs(host)["timer:apt-daily.timer"]
with pytest.raises(ScheduledJobRefused):
host.delete_scheduled_job(apt["key"], digest=apt["digest"])
def test_a_cron_d_file_without_systemd(self, root: Path):
host = Host(root, systemd=False)
host.put_scheduled_job(SPEC)
assert (root / "etc/cron.d/netork-tidy").read_text() == (
"# napalm-scheduled-job: netork-tidy tidy %tmp\n*/30 1-2 * * * root find /tmp -mtime +7 -delete\n"
)
job = _jobs(host)["job:netork-tidy"]
assert job["managed_by"] == "application" and job["kind"] == "cron"
host.delete_scheduled_job("job:netork-tidy", digest=job["digest"])
assert not (root / "etc/cron.d/netork-tidy").exists()
def test_marked_lines_in_the_users_crontab_on_a_busybox_host(self, root: Path):
host = Host(root, systemd=False, own_cron_d=False)
host.put_scheduled_job({**SPEC, "run_as": "www-data"})
text = (root / "spool/www-data").read_text()
assert text.endswith(
"# napalm-scheduled-job: netork-tidy tidy %tmp\n*/30 1-2 * * * find /tmp -mtime +7 -delete\n"
)
job = _jobs(host)["job:netork-tidy"]
host.put_scheduled_job(
{**SPEC, "run_as": "www-data", "enabled": False}, digest=job["digest"]
)
assert "#napalm-disabled: */30" in (root / "spool/www-data").read_text()
job = _jobs(host)["job:netork-tidy"]
host.put_scheduled_job({**SPEC, "run_as": "nobody"}, digest=job["digest"])
assert "netork-tidy" not in (root / "spool/www-data").read_text()
assert "netork-tidy" in (root / "spool/nobody").read_text()
job = _jobs(host)["job:netork-tidy"]
host.delete_scheduled_job("job:netork-tidy", digest=job["digest"])
assert (root / "spool/nobody").read_text() == ""
def test_a_cron_d_that_is_not_there_is_the_crontab(self, root: Path):
host = Host(root, systemd=False)
host.OWN_CRON_D_DIR = str(root / "etc/no-cron.d") # type: ignore[misc]
host.put_scheduled_job(SPEC)
assert "netork-tidy" in (root / "spool/root").read_text()
def test_a_cron_line_holds_one_line(self, root: Path):
with pytest.raises(ScheduledJobRefused, match="one line"):
Host(root, systemd=False).put_scheduled_job({**SPEC, "command": "a\nb"})
def test_a_calendar_systemd_refuses(self, root: Path):
_tool(root, "systemd-analyze", "#!/bin/sh\necho 'Failed to parse' >&2\nexit 1\n")
with pytest.raises(ScheduledJobRefused, match="systemd does not take"):
Host(root).put_scheduled_job(SPEC)
def test_a_failed_install_says_so(self, root: Path):
_tool(root, "install", "#!/bin/sh\necho 'read-only file system' >&2\nexit 1\n")
with pytest.raises(RuntimeError, match="read-only"):
Host(root).put_scheduled_job(SPEC)
+27
View File
@@ -14,6 +14,7 @@ import pytest
from napalm_device_types.channel import CommandResult
from napalm_device_types.ssh_server import (
DROPIN_DIR,
DROPIN_PATH,
MAIN_CONFIG,
OpenSshServerMixin,
@@ -401,6 +402,32 @@ def test_mixin_falls_back_to_sshd_config_without_an_include():
assert host._effective()["mac"] == ["hmac-sha2-256"]
class GeneratedConfigHost(FakeHost):
"""A platform that writes sshd_config from its own database (OpenMediaVault)."""
SSHD_CONFIG_GENERATED = True
def test_generated_sshd_config_still_gets_the_dropin():
host = GeneratedConfigHost()
result = host.harden_ssh_server({"mac": ["hmac-sha1"]})
assert result.applied
assert result.path == DROPIN_PATH
assert host.files[MAIN_CONFIG] == "Include /etc/ssh/sshd_config.d/*.conf\nPort 22\n"
def test_generated_sshd_config_without_an_include_is_left_alone():
"""The platform would write its own file over the change on its next apply."""
host = GeneratedConfigHost(main="Port 22\nMACs hmac-sha1,hmac-sha2-256\n")
result = host.harden_ssh_server({"mac": ["hmac-sha1"]})
assert not result.applied and not result.rolled_back
assert result.path is None
assert host.files[MAIN_CONFIG] == "Port 22\nMACs hmac-sha1,hmac-sha2-256\n"
assert list(host.files) == [MAIN_CONFIG]
assert host.reloads == 0
assert DROPIN_DIR in result.message
def test_mixin_restores_when_sshd_rejects_the_config():
host = FakeHost()
host.syntax_ok = False