diff --git a/CHANGELOG.md b/CHANGELOG.md index 938a7c6..68f49a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,31 @@ 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 diff --git a/README.md b/README.md index efb6af7..b21b930 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 822d958..1f3c912 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -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", diff --git a/napalm_device_types/_crontab.py b/napalm_device_types/_crontab.py new file mode 100644 index 0000000..7337959 --- /dev/null +++ b/napalm_device_types/_crontab.py @@ -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: `` +and is keyed ``job:``, 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"(?: `` 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/``. +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 ``@`` (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} diff --git a/napalm_device_types/cron.py b/napalm_device_types/cron.py new file mode 100644 index 0000000..8955313 --- /dev/null +++ b/napalm_device_types/cron.py @@ -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}"] diff --git a/napalm_device_types/models.py b/napalm_device_types/models.py index b791092..b2d4302 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -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.""" diff --git a/napalm_device_types/os.py b/napalm_device_types/os.py index 8c62e09..a9a7b6a 100644 --- a/napalm_device_types/os.py +++ b/napalm_device_types/os.py @@ -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 # ------------------------------------------------------------------ diff --git a/napalm_device_types/scheduled_jobs.py b/napalm_device_types/scheduled_jobs.py new file mode 100644 index 0000000..7ea907c --- /dev/null +++ b/napalm_device_types/scheduled_jobs.py @@ -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*. + """ + ... diff --git a/napalm_device_types/scheduled_jobs_posix.py b/napalm_device_types/scheduled_jobs_posix.py new file mode 100644 index 0000000..8fee6c9 --- /dev/null +++ b/napalm_device_types/scheduled_jobs_posix.py @@ -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 `` 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 -- ``.timer`` and ``.service`` in :attr:`UNIT_DIR`, the command +in :attr:`JOB_SCRIPT_DIR` ``/`` 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 " " 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 ``: ``. + OWNERS_SH: ClassVar[str] = OWNERS_SH + #: ``sh`` that prints the time zone: an IANA name, or a path ending in ``zoneinfo/``. + 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"} diff --git a/pyproject.toml b/pyproject.toml index 9c7a9ce..8c81a76 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "napalm-device-types" -version = "4.26.0" +version = "4.27.0" description = "Abstract device-type base classes for NAPALM drivers" readme = "README.md" requires-python = ">=3.12" diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 3b89766..d75b3d2 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -32,7 +32,7 @@ }, "mypy_relaxed": [], "python_file_lines": { - "napalm_device_types/models.py": 1463 + "napalm_device_types/models.py": 1454 }, "untyped_public": [] } diff --git a/tests/test_cron.py b/tests/test_cron.py new file mode 100644 index 0000000..ae5d780 --- /dev/null +++ b/tests/test_cron.py @@ -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") diff --git a/tests/test_crontab_text.py b/tests/test_crontab_text.py new file mode 100644 index 0000000..8a0a015 --- /dev/null +++ b/tests/test_crontab_text.py @@ -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 diff --git a/tests/test_scheduled_jobs.py b/tests/test_scheduled_jobs.py new file mode 100644 index 0000000..e3623e5 --- /dev/null +++ b/tests/test_scheduled_jobs.py @@ -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) diff --git a/tests/test_scheduled_jobs_posix.py b/tests/test_scheduled_jobs_posix.py new file mode 100644 index 0000000..3029746 --- /dev/null +++ b/tests/test_scheduled_jobs_posix.py @@ -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)