feat(scheduled-jobs): ScheduledJobsMixin and its POSIX implementation (#86)
driver / standard (pull_request) Successful in 20s
driver / lint (pull_request) Successful in 23s
driver / types (pull_request) Successful in 1m16s
driver / test (3.13) (pull_request) Successful in 1m18s
driver / test (3.12) (pull_request) Successful in 1m27s
driver / lowest (pull_request) Successful in 46s
driver / build (pull_request) Successful in 43s
driver / security (pull_request) Successful in 1m27s
CI / driver (pull_request) Successful in 3m11s
driver / publish (pull_request) Skipped

What a host runs on its own schedule as one shape: cron lines, run-parts
scripts, anacron, systemd timers, periodic, a platform's own jobs, Windows
tasks. Every job says who owns its definition and what the driver can do
to it; every write names the digest the caller saw and is refused when the
host's definition changed since.

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

get_cron_jobs and CronJobDict go: nothing called them.

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

Closes #86
This commit is contained in:
christianmanivong committed 2026-11-03 05:29:27 +01:00
1 parent fdf2f89115
commit f573fa53d2
16 files changed
+2440 -44

No files matched your search

+1 -1
View File
@@ -32,7 +32,7 @@
},
"mypy_relaxed": [],
"python_file_lines": {
"napalm_device_types/models.py": 1463
"napalm_device_types/models.py": 1454
},
"untyped_public": []
}
+141
View File
@@ -0,0 +1,141 @@
"""Cron expressions: what they mean, when they fire next, and as systemd ``OnCalendar``.
One module answers all three, because a job netOrk writes as a timer must fire
exactly when the cron expression the user gave says, and the preview must show
the same runs the host will make (NetOrk/netork#1933).
"""
from __future__ import annotations
from datetime import UTC, datetime
from zoneinfo import ZoneInfo
import pytest
from napalm_device_types.cron import is_reboot, next_runs, parse_cron, to_on_calendar
BERLIN = ZoneInfo("Europe/Berlin")
class TestParse:
def test_every_field_is_expanded_to_its_values(self):
s = parse_cron("*/15 6-8 1,15 * *")
assert s.minutes == frozenset({0, 15, 30, 45})
assert s.hours == frozenset({6, 7, 8})
assert s.days == frozenset({1, 15})
assert s.months == frozenset(range(1, 13))
assert s.weekdays == frozenset(range(7))
def test_a_range_takes_a_step(self):
assert parse_cron("1-30/10 * * * *").minutes == frozenset({1, 11, 21})
def test_names_are_months_and_weekdays_in_any_case(self):
s = parse_cron("0 0 * Jan,MAR mon-Fri")
assert s.months == frozenset({1, 3})
assert s.weekdays == frozenset({1, 2, 3, 4, 5})
def test_seven_is_sunday_too(self):
assert parse_cron("0 0 * * 7").weekdays == frozenset({0})
@pytest.mark.parametrize(
("alias", "expanded"),
[
("@hourly", "0 * * * *"),
("@daily", "0 0 * * *"),
("@midnight", "0 0 * * *"),
("@weekly", "0 0 * * 0"),
("@monthly", "0 0 1 * *"),
("@yearly", "0 0 1 1 *"),
("@annually", "0 0 1 1 *"),
],
)
def test_an_alias_is_its_expression(self, alias, expanded):
assert parse_cron(alias) == parse_cron(expanded)
def test_reboot_is_no_calendar(self):
assert is_reboot("@reboot")
assert not is_reboot("0 0 * * *")
with pytest.raises(ValueError, match="reboot"):
parse_cron("@reboot")
@pytest.mark.parametrize(
"bad",
[
"",
"* * * *",
"* * * * * *",
"60 * * * *",
"* 24 * * *",
"* * 0 * *",
"* * * 13 *",
"* * * * 8",
"*/0 * * * *",
"5-1 * * * *",
"a * * * *",
"@often",
"1,,2 * * * *",
],
)
def test_what_cron_would_not_take_is_refused(self, bad):
with pytest.raises(ValueError):
parse_cron(bad)
def test_day_of_month_and_weekday_are_or_only_when_both_are_restricted(self):
assert parse_cron("0 0 1 * 1").either_day
assert not parse_cron("0 0 */2 * 1").either_day
assert not parse_cron("0 0 1 * *").either_day
class TestNextRuns:
def test_runs_after_the_instant_in_the_hosts_time(self):
after = datetime(2026, 11, 3, 5, 50, tzinfo=UTC) # 06:50 in Berlin
runs = next_runs("0 7 * * *", after, BERLIN, count=2)
assert runs == [
datetime(2026, 11, 3, 7, 0, tzinfo=BERLIN),
datetime(2026, 11, 4, 7, 0, tzinfo=BERLIN),
]
def test_the_instant_itself_is_not_a_next_run(self):
after = datetime(2026, 11, 3, 6, 0, tzinfo=UTC)
assert next_runs("0 6 * * *", after, ZoneInfo("UTC"), count=1)[0].day == 4
def test_either_day_fires_on_both(self):
after = datetime(2026, 11, 30, 12, 0, tzinfo=UTC) # a Monday
runs = next_runs("0 0 1 * 1", after, ZoneInfo("UTC"), count=3)
assert [r.day for r in runs] == [1, 7, 14]
def test_a_day_that_never_comes_gives_no_runs(self):
assert next_runs("0 0 31 2 *", datetime(2026, 1, 1, tzinfo=UTC), BERLIN) == []
def test_a_time_the_clock_skips_is_left_out(self):
# 2026-03-29 02:30 does not exist in Berlin.
after = datetime(2026, 3, 28, 12, 0, tzinfo=UTC)
runs = next_runs("30 2 * * *", after, BERLIN, count=2)
assert [r.day for r in runs] == [30, 31]
def test_reboot_has_no_next_run(self):
assert next_runs("@reboot", datetime(2026, 1, 1, tzinfo=UTC), BERLIN) == []
class TestOnCalendar:
def test_every_field_as_its_values(self):
assert to_on_calendar("*/15 6 * * *") == ["*-*-* 06:00,15,30,45:00"]
def test_a_restricted_weekday_leads(self):
assert to_on_calendar("30 4 * * 1-5") == ["Mon,Tue,Wed,Thu,Fri *-*-* 04:30:00"]
def test_months_and_days(self):
assert to_on_calendar("0 0 1,15 1,7 *") == ["*-01,07-01,15 00:00:00"]
def test_either_day_is_two_lines(self):
assert to_on_calendar("0 0 1 * 0") == ["*-*-01 00:00:00", "Sun *-*-* 00:00:00"]
def test_both_days_with_a_star_are_one_line(self):
assert to_on_calendar("0 0 */10 * 6") == ["Sat *-*-01,11,21,31 00:00:00"]
def test_an_alias(self):
assert to_on_calendar("@daily") == ["*-*-* 00:00:00"]
def test_reboot_is_refused(self):
with pytest.raises(ValueError, match="reboot"):
to_on_calendar("@reboot")
+145
View File
@@ -0,0 +1,145 @@
"""Crontabs as text: the jobs in them, and changing one line (NetOrk/netork#1933)."""
from __future__ import annotations
import subprocess
import pytest
from napalm_device_types._crontab import (
DISABLED_MARKER,
marked_lines,
parse_anacrontab,
parse_crontab,
run_script,
switched,
with_job,
without_job,
)
SYSTEM = """\
# /etc/crontab: system-wide crontab
SHELL=/bin/sh
PATH="/usr/local/sbin:/usr/bin:/bin"
17 * * * * root cd / && run-parts --report /etc/cron.hourly
@reboot root /usr/local/bin/warm-cache # keeps the # in the command
#napalm-disabled: 0 4 * * * backup /usr/local/bin/backup
garbage line
0 4 * * * backup /usr/local/bin/backup
"""
USER = """\
MAILTO=ops@example.org
*/5 * * * * /usr/bin/php /var/www/cron.php
# napalm-scheduled-job: netork-cleanup tidy the cache
0 3 * * * find /tmp -mtime +7 -delete
"""
class TestParse:
def test_a_system_crontab_names_the_user(self):
jobs = parse_crontab("/etc/crontab", SYSTEM, system=True)
first = jobs[0]
assert (first.schedule, first.run_as) == ("17 * * * *", "root")
assert first.command == "cd / && run-parts --report /etc/cron.hourly"
assert first.env == {"SHELL": "/bin/sh", "PATH": "/usr/local/sbin:/usr/bin:/bin"}
assert first.key.startswith("cron:/etc/crontab:")
def test_an_alias_and_a_hash_inside_the_command(self):
reboot = parse_crontab("/etc/crontab", SYSTEM, system=True)[1]
assert reboot.schedule == "@reboot"
assert reboot.command == "/usr/local/bin/warm-cache # keeps the # in the command"
def test_a_line_switched_off_is_a_job_that_is_off(self):
jobs = parse_crontab("/etc/crontab", SYSTEM, system=True)
off = jobs[2]
assert not off.enabled
assert off.run_as == "backup"
def test_equal_lines_get_their_own_keys_and_switching_off_keeps_the_key(self):
jobs = parse_crontab("/etc/crontab", SYSTEM, system=True)
assert jobs[3].key == jobs[2].key + ":2"
assert len(jobs) == 4 # the garbage line is left out
def test_a_user_crontab_runs_as_its_user(self):
jobs = parse_crontab("/var/spool/cron/crontabs/www", USER, system=False, user="www-data")
assert jobs[0].run_as == "www-data"
assert jobs[0].env == {"MAILTO": "ops@example.org"}
def test_an_applications_job_is_keyed_by_its_name(self):
job = parse_crontab("/x", USER, system=False, user="root")[1]
assert (job.key, job.name, job.description) == (
"job:netork-cleanup",
"netork-cleanup",
"tidy the cache",
)
def test_an_anacrontab(self):
text = "SHELL=/bin/sh\n1\t5\tcron.daily\trun-parts --report /etc/cron.daily\n@monthly 15 cron.monthly run-parts /etc/cron.monthly\nbad line here\n"
jobs = parse_anacrontab(text)
assert [(j.key, j.schedule, j.run_as) for j in jobs] == [
("anacron:cron.daily", "1", "root"),
("anacron:cron.monthly", "@monthly", "root"),
]
assert jobs[0].command == "run-parts --report /etc/cron.daily"
class TestEdit:
def test_switching_off_and_on_again_gives_the_text_back(self):
jobs = parse_crontab("/etc/crontab", SYSTEM, system=True)
off = switched(SYSTEM, jobs[0], enabled=False)
assert DISABLED_MARKER + "17 *\t* * *\troot" in off
again = parse_crontab("/etc/crontab", off, system=True)
assert again[0].key == jobs[0].key and not again[0].enabled
assert switched(off, again[0], enabled=True) == SYSTEM.replace(
"17 *\t* * *\troot\tcd", "17 *\t* * *\troot\tcd"
)
def test_an_applications_job_is_added_replaced_and_removed(self):
lines = marked_lines("netork-x", "a job", "0 1 * * * /bin/true", enabled=True)
added = with_job("A=1\n", [], "netork-x", lines)
assert added == "A=1\n# napalm-scheduled-job: netork-x a job\n0 1 * * * /bin/true\n"
jobs = parse_crontab("/x", added, system=False, user="root")
changed = with_job(
added,
jobs,
"netork-x",
marked_lines("netork-x", "", "0 2 * * * /bin/true", enabled=False),
)
assert (
changed
== "A=1\n# napalm-scheduled-job: netork-x\n#napalm-disabled: 0 2 * * * /bin/true\n"
)
jobs = parse_crontab("/x", changed, system=False, user="root")
assert without_job(changed, jobs, "netork-x") == "A=1\n"
def test_adding_to_a_text_without_a_last_newline(self):
assert with_job("A=1", [], "n", ["# m", "x"]) == "A=1\n# m\nx\n"
def test_removing_the_only_job_leaves_nothing(self):
text = "# napalm-scheduled-job: n\n0 1 * * * x\n"
jobs = parse_crontab("/x", text, system=False, user="root")
assert without_job(text, jobs, "n") == ""
class TestRunScript:
def _run(self, script: str) -> str:
return subprocess.run(
["sh", "-c", script], capture_output=True, text=True, check=True
).stdout
def test_the_crontabs_variables_are_set(self):
assert (
self._run(run_script('echo "$GREETING"', {"GREETING": "hi there", "MAILTO": "x"}))
== "hi there\n"
)
def test_a_percent_starts_stdin_and_further_ones_are_newlines(self):
assert self._run(run_script("cat%one%two", {})) == "one\ntwo\n"
def test_an_escaped_percent_is_a_percent(self):
assert self._run(run_script("date -d @0 -u +\\%Y", {})) == "1970\n"
@pytest.mark.parametrize("command", ["echo plain", "echo 'quoted'"])
def test_without_percent_the_command_is_as_it_is(self, command):
assert run_script(command, {}) == command
+108
View File
@@ -0,0 +1,108 @@
"""The scheduled-jobs contract: its digest, the names and specs it takes (NetOrk/netork#1933)."""
from __future__ import annotations
import pytest
from napalm_device_types import ScheduledJobsMixin
from napalm_device_types.scheduled_jobs import (
ACTIONS,
ScheduledJobChanged,
ScheduledJobRefused,
check_job_name,
check_spec,
job_digest,
)
JOB = {
"kind": "cron",
"source": "/etc/crontab",
"run_as": "root",
"schedule": "*/5 * * * *",
"command": "/usr/local/bin/backup",
"enabled": True,
}
class TestDigest:
def test_sixteen_hex_characters(self):
digest = job_digest(JOB)
assert len(digest) == 16
int(digest, 16)
def test_the_same_definition_has_the_same_digest(self):
assert job_digest(JOB) == job_digest(dict(JOB))
@pytest.mark.parametrize(
"field, value",
[
("schedule", "0 * * * *"),
("command", "/usr/local/bin/other"),
("run_as", "nobody"),
("enabled", False),
("source", "/etc/cron.d/backup"),
("kind", "anacron"),
],
)
def test_every_part_of_the_definition_changes_it(self, field, value):
assert job_digest({**JOB, field: value}) != job_digest(JOB)
def test_content_the_definition_points_at_changes_it(self):
assert job_digest(JOB, content="12345 678") != job_digest(JOB)
def test_what_the_host_says_of_its_runs_does_not(self):
assert job_digest({**JOB, "last_run": "2026-11-03T06:00:00Z"}) == job_digest(JOB)
class TestNames:
@pytest.mark.parametrize("name", ["backup", "netork-backup-db", "a", "x1"])
def test_a_good_name(self, name):
check_job_name(name)
@pytest.mark.parametrize("name", ["", "-x", "Backup", "a b", "a/b", "a.timer", "a" * 64])
def test_a_name_a_file_or_unit_could_not_carry_safely(self, name):
with pytest.raises(ScheduledJobRefused):
check_job_name(name)
class TestSpec:
SPEC = {
"name": "backup",
"schedule": "0 3 * * *",
"run_as": "root",
"command": "/usr/local/bin/backup",
"enabled": True,
}
def test_a_good_spec(self):
check_spec(self.SPEC)
check_spec({**self.SPEC, "schedule": "@reboot"})
@pytest.mark.parametrize(
"field, value",
[
("schedule", "every day"),
("run_as", "root; rm"),
("run_as", ""),
("command", ""),
("command", " "),
("description", "two\nlines"),
],
)
def test_a_spec_that_cannot_be_written(self, field, value):
with pytest.raises(ScheduledJobRefused):
check_spec({**self.SPEC, field: value})
class TestContract:
def test_the_mixin_declares_nothing_at_runtime(self):
driver = ScheduledJobsMixin()
for method in ("get_scheduled_jobs", "manage_scheduled_job", "put_scheduled_job"):
assert not hasattr(driver, method)
def test_the_actions(self):
assert ACTIONS == ("enable", "disable", "run")
def test_a_refusal_is_a_value_error_and_a_change_is_not(self):
assert issubclass(ScheduledJobRefused, ValueError)
assert not issubclass(ScheduledJobChanged, ValueError)
+499
View File
@@ -0,0 +1,499 @@
"""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={ OnUnitActiveSec=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_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 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_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_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)