From dce794644c9d269c7c71ac15d184db880fabf31d Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Tue, 3 Nov 2026 05:39:04 +0100 Subject: [PATCH 1/3] feat(scheduled-jobs): scheduled jobs on Proxmox VE and Backup Server (#56) Both drivers mix in napalm-device-types' PosixScheduledJobsMixin over the node's root SSH session: get_scheduled_jobs reads cron, run-parts, anacron and every systemd timer in one round trip; manage_scheduled_job enables, disables or runs one now; put_ and delete_scheduled_job write and remove an application's own job. What Proxmox ships is platform, so it is only switched and run: pve-* units, pvesr.timer and /etc/cron.d/vzdump on Proxmox VE, proxmox-backup* units on a backup server. A vzdump cron line is only run, because the file is a link into /etc/pve and rewriting it would replace the link with a plain file. Backup jobs (/cluster/backup), replication and a backup server's verify, prune, sync and GC jobs run in Proxmox's own daemons and stay with the backup features. Requires napalm-device-types 4.26.0. Closes #56 --- CHANGELOG.md | 17 ++++ README.md | 4 + napalm_proxmox/backup_driver.py | 4 + napalm_proxmox/driver.py | 6 ++ napalm_proxmox/scheduled_jobs.py | 51 ++++++++++++ pyproject.toml | 2 +- tests/test_scheduled_jobs.py | 137 +++++++++++++++++++++++++++++++ 7 files changed, 220 insertions(+), 1 deletion(-) create mode 100644 napalm_proxmox/scheduled_jobs.py create mode 100644 tests/test_scheduled_jobs.py diff --git a/CHANGELOG.md b/CHANGELOG.md index ec6402e..2746734 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added +- Scheduled jobs on both drivers (NetOrk/netork#1933, #56), through napalm-device-types' + `PosixScheduledJobsMixin`: `get_scheduled_jobs()` reads `/etc/crontab`, `/etc/cron.d`, + the user crontabs, the run-parts directories, `/etc/anacrontab` and every systemd timer + in one round trip as root; `manage_scheduled_job()` enables, disables or runs one now; + `put_scheduled_job()` and `delete_scheduled_job()` write and remove an application's own. + What Proxmox ships is `platform`: on Proxmox VE `pve-*` units (`pve-daily-update.timer`), + `pvesr.timer` and `/etc/cron.d/vzdump`; on a backup server `proxmox-backup*` units + (`proxmox-backup-daily-update.timer`). A line in `/etc/cron.d/vzdump` is only run, never + switched: the file is a link into `/etc/pve`, and rewriting it would replace the link. + Not scheduled jobs here: Proxmox VE's backup jobs (`/cluster/backup`) and replication, + and a backup server's verify, prune, sync and garbage collection jobs. Proxmox runs them + in its own daemons; `get_clusters()` and `get_backup_jobs()` keep them. + +### Changed +- Requires napalm-device-types 4.26.0. + ## [0.10.0] - 2026-11-03 ### Added diff --git a/README.md b/README.md index 9d6fa22..a7ca064 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,9 @@ device = driver( | `traceroute` | `traceroute -n` over SSH | | `cli` | Arbitrary commands over SSH (stdout) | | `get_route_to` | `ip route show` over SSH | +| `get_scheduled_jobs` | cron, `/etc/cron.d`, user crontabs, run-parts, anacron, systemd timers, as root over SSH (napalm-device-types' `PosixScheduledJobsMixin`); `pve-*` units, `pvesr.timer` and `/etc/cron.d/vzdump` are `platform` | +| `manage_scheduled_job(key, action, digest=)` | enable, disable, run now; a `/etc/cron.d/vzdump` line only runs | +| `put_scheduled_job(spec)` / `delete_scheduled_job(key, digest=)` | an application's own job, as a systemd timer | **Not implemented** (raise `NotImplementedError`): `get_bgp_config`, `get_bgp_neighbors`, `get_bgp_neighbors_detail`, @@ -184,6 +187,7 @@ the disks and ZFS pools the server manages itself. | `get_disks`, `get_disk_pools` | `/nodes/localhost/disks/{list,zfs}` | | `get_licenses` | `pbs-subscription` | | packages, updates, services, kernel, listening sockets, sshd hardening, `reboot_host`, `shutdown_host` | as on Proxmox VE | +| scheduled jobs | as on Proxmox VE; `proxmox-backup*` units are `platform`. Verify, prune, sync and GC jobs are `get_backup_jobs`, not scheduled jobs | **API token rights.** Reading needs the role `Audit` on `/` (`Sys.Audit`, `Datastore.Audit`); the remotes need `Remote.Audit` on `/remote` as well, which diff --git a/napalm_proxmox/backup_driver.py b/napalm_proxmox/backup_driver.py index 04db286..ec496d9 100644 --- a/napalm_proxmox/backup_driver.py +++ b/napalm_proxmox/backup_driver.py @@ -40,6 +40,7 @@ from napalm_proxmox._base import ProxmoxBase from napalm_proxmox.host_mixin import ProxmoxHostMixin from napalm_proxmox.pbs_backups import ProxmoxBackupServerMixin from napalm_proxmox.pbs_host import ProxmoxPbsHostMixin +from napalm_proxmox.scheduled_jobs import PBS_PLATFORM_SOURCES, ProxmoxScheduledJobsMixin logger = logging.getLogger(__name__) @@ -59,6 +60,7 @@ class ProxmoxBackupDriver( ListeningSocketsMixin, SystemIdentityMixin, SystemdServicesMixin, + ProxmoxScheduledJobsMixin, HostStatusMixin, LicenseMixin, EnsurePackageMixin, @@ -76,6 +78,8 @@ class ProxmoxBackupDriver( #: A PBS upgrades like a PVE node: a plain ``apt-get upgrade`` holds back #: what needs new or removed packages. FULL_UPGRADE = True + #: The backup server's own timer is ``platform``. + PLATFORM_SOURCES = PBS_PLATFORM_SOURCES PORT_SPECS = [ PortSpec("https", 8007, weight=8.0), ] diff --git a/napalm_proxmox/driver.py b/napalm_proxmox/driver.py index 52f4a2f..4241bc5 100644 --- a/napalm_proxmox/driver.py +++ b/napalm_proxmox/driver.py @@ -54,6 +54,7 @@ from napalm_proxmox.host_mixin import ProxmoxHostMixin from napalm_proxmox.interfaces_mixin import ProxmoxInterfaceMixin from napalm_proxmox.lldp_mixin import ProxmoxLLDPMixin from napalm_proxmox.routing_mixin import ProxmoxRoutingMixin +from napalm_proxmox.scheduled_jobs import PVE_PLATFORM_SOURCES, ProxmoxScheduledJobsMixin from napalm_proxmox.sdn_mixin import ProxmoxSDNMixin from napalm_proxmox.system_mixin import ProxmoxSystemMixin from napalm_proxmox.vm_contract_mixin import ProxmoxVMContractMixin @@ -94,6 +95,7 @@ class ProxmoxDriver( ListeningSocketsMixin, SystemIdentityMixin, SystemdServicesMixin, + ProxmoxScheduledJobsMixin, HostStatusMixin, LicenseMixin, SnmpAgentMixin, @@ -115,6 +117,10 @@ class ProxmoxDriver( #: ``apt-get upgrade`` holds back what needs new or removed packages and can #: leave the node half updated. netOrk reads this when it upgrades the host. FULL_UPGRADE = True + #: Proxmox VE's own timers and cron file are ``platform``. + PLATFORM_SOURCES = PVE_PLATFORM_SOURCES + #: ``/etc/cron.d/vzdump`` links into ``/etc/pve``; its lines are only run. + RUN_ONLY_SOURCES = ("/etc/cron.d/vzdump",) PORT_SPECS = [ PortSpec("https", 8006, weight=8.0), ] diff --git a/napalm_proxmox/scheduled_jobs.py b/napalm_proxmox/scheduled_jobs.py new file mode 100644 index 0000000..d38c340 --- /dev/null +++ b/napalm_proxmox/scheduled_jobs.py @@ -0,0 +1,51 @@ +"""Scheduled jobs of a Proxmox VE node or a Proxmox Backup Server (#56). + +Both are Debian hosts: napalm-device-types' ``PosixScheduledJobsMixin`` reads +cron, run-parts, anacron and systemd timers over ``run_command`` as root, and +switches, runs and writes them. What this module adds is which of them Proxmox +itself ships -- ``platform`` -- and that a line in a file the cluster file +system holds is only run. + +Not here: Proxmox VE's backup jobs (``/cluster/backup``) and replication, and a +backup server's verify, prune, sync and garbage collection jobs. Proxmox runs +those in its own daemons, not from cron or a timer, and the backup features +(``get_clusters``, ``get_backup_jobs``) keep them. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, ClassVar + +from napalm_device_types import PosixScheduledJobsMixin + +if TYPE_CHECKING: + from napalm_device_types._scheduled_reading import Reading + +_UNITS = ("/usr/lib/systemd/system", "/lib/systemd/system") + +#: What Proxmox VE ships: ``pve-daily-update.timer`` (pve-manager), ``pvesr.timer`` +#: (replication before Proxmox VE 7) and ``/etc/cron.d/vzdump``, the backup schedule of +#: releases before ``pvescheduler``, a link to ``/etc/pve/vzdump.cron``. +PVE_PLATFORM_SOURCES = ( + *(f"{d}/pve-*" for d in _UNITS), + *(f"{d}/pvesr.timer" for d in _UNITS), + "/etc/cron.d/vzdump", +) + +#: What a Proxmox Backup Server ships: ``proxmox-backup-daily-update.timer``. +PBS_PLATFORM_SOURCES = tuple(f"{d}/proxmox-backup*" for d in _UNITS) + + +class ProxmoxScheduledJobsMixin(PosixScheduledJobsMixin): + """Scheduled jobs of a Proxmox host; a driver sets ``PLATFORM_SOURCES``.""" + + #: Sources a job is only run from: links into ``/etc/pve``, which a rewrite + #: (``install`` over the path) would replace with a file of its own. + RUN_ONLY_SOURCES: ClassVar[tuple[str, ...]] = () + + def _sj_read(self) -> Reading: + reading = super()._sj_read() + for job in reading.jobs: + if job["source"] in self.RUN_ONLY_SOURCES: + job["actions"] = [a for a in job["actions"] if a == "run"] # type: ignore[attr-defined] + return reading diff --git a/pyproject.toml b/pyproject.toml index 059e8b0..828f347 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,7 +21,7 @@ classifiers = [ requires-python = ">=3.12" dependencies = [ "napalm>=5.0.0", - "napalm_device_types>=4.25.0", # BackupServerDriver + "napalm_device_types>=4.26.0", # PosixScheduledJobsMixin "paramiko>=5.0.0", # CVE-2026-44405; imported directly for the node's SSH session (_base.py) "proxmoxer>=2.0.0", "netaddr>=0.9.0", diff --git a/tests/test_scheduled_jobs.py b/tests/test_scheduled_jobs.py new file mode 100644 index 0000000..9f93aea --- /dev/null +++ b/tests/test_scheduled_jobs.py @@ -0,0 +1,137 @@ +"""Scheduled jobs on a Proxmox VE node and a Proxmox Backup Server (#56). + +The report, its parse and every write are napalm-device-types' +``PosixScheduledJobsMixin``'s; the drivers carry the command across +``run_command`` as root in one round trip and say which jobs Proxmox itself +ships (``platform``). +""" + +from __future__ import annotations + +from unittest.mock import MagicMock + +import pytest +from napalm_device_types import CommandResult, PosixScheduledJobsMixin, ScheduledJobRefused + +from napalm_proxmox import ProxmoxBackupDriver, ProxmoxDriver + +_TIMER = """|Id={name}.timer +|Unit={name}.service +|Description={name} +|TimersCalendar={{ OnCalendar=*-*-* 06:00:00 ; next_elapse=n/a }} +|NextElapseUSecRealtime=@1762236000 +|LastTriggerUSec=@1762149600 +|UnitFileState=enabled +|ActiveState=active +|FragmentPath={path} +|""" + +_UNIT = """|Id={name}.service +|ExecStart={{ path=/usr/bin/{name} ; argv[]=/usr/bin/{name} ; }} +|Result=success +|FragmentPath={path} +|""" + + +def _report(*timers: tuple[str, str]) -> str: + return "\n".join( + [ + "SJ_BEGIN", + "[system /etc/cron.d/vzdump]", + "|0 1 * * 6 root vzdump 100 --mode snapshot --quiet 1", + "[system /etc/cron.d/zfsutils-linux]", + "|0 0 * * 0 root /usr/lib/zfs-linux/scrub", + "[user /var/spool/cron/crontabs/root]", + "|*/5 * * * * /root/check.sh", + "[systemd]", + "[timers]", + *(_TIMER.format(name=n, path=p) for n, p in timers), + "[units]", + *(_UNIT.format(name=n, path=p.replace(".timer", ".service")) for n, p in timers), + "[tz]", + "/usr/share/zoneinfo/Europe/Berlin", + "[owners]", + "zfsutils-linux: /etc/cron.d/zfsutils-linux", + *(f"{n.split('-')[0]}: {p}" for n, p in timers), + "SJ_END", + "", + ] + ) + + +PVE_REPORT = _report( + ("pve-daily-update", "/lib/systemd/system/pve-daily-update.timer"), + ("pvesr", "/usr/lib/systemd/system/pvesr.timer"), + ("apt-daily", "/usr/lib/systemd/system/apt-daily.timer"), +) +PBS_REPORT = _report( + ("proxmox-backup-daily-update", "/usr/lib/systemd/system/proxmox-backup-daily-update.timer"), + ("pve-daily-update", "/lib/systemd/system/pve-daily-update.timer"), + ("apt-daily", "/usr/lib/systemd/system/apt-daily.timer"), +) +VERBS = ("get_scheduled_jobs", "manage_scheduled_job", "put_scheduled_job", "delete_scheduled_job") + + +def _driver(cls: type, report: str) -> MagicMock: + driver = cls("host", "root@pam", "pw") + driver.run_command = MagicMock(return_value=CommandResult(report, "", 0)) + return driver + + +def _by_source(driver: MagicMock) -> dict[str, dict[str, object]]: + return {str(j["source"]): dict(j) for j in driver.get_scheduled_jobs()["jobs"]} + + +@pytest.mark.parametrize( + ("cls", "report"), + [(ProxmoxDriver, PVE_REPORT), (ProxmoxBackupDriver, PBS_REPORT)], + ids=["pve", "pbs"], +) +def test_each_driver_offers_every_verb_and_reads_as_root_once(cls: type, report: str) -> None: + assert issubclass(cls, PosixScheduledJobsMixin) + for verb in VERBS: + assert callable(getattr(cls, verb)) + driver = _driver(cls, report) + reading = driver.get_scheduled_jobs() + assert reading["time_zone"] == "Europe/Berlin" + assert len(reading["jobs"]) == 6 + driver.run_command.assert_called_once() + assert driver.run_command.call_args.kwargs["privileged"] is True + + +def test_what_proxmox_ve_ships_is_platform() -> None: + jobs = _by_source(_driver(ProxmoxDriver, PVE_REPORT)) + managed = {source: job["managed_by"] for source, job in jobs.items()} + assert managed == { + "/lib/systemd/system/pve-daily-update.timer": "platform", + "/usr/lib/systemd/system/pvesr.timer": "platform", + "/etc/cron.d/vzdump": "platform", + "/usr/lib/systemd/system/apt-daily.timer": "package", + "/etc/cron.d/zfsutils-linux": "package", + "/var/spool/cron/crontabs/root": "admin", + } + assert jobs["/lib/systemd/system/pve-daily-update.timer"]["actions"] == [ + "enable", + "disable", + "run", + ] + + +def test_what_a_backup_server_ships_is_platform() -> None: + jobs = _by_source(_driver(ProxmoxBackupDriver, PBS_REPORT)) + managed = {source: job["managed_by"] for source, job in jobs.items()} + assert managed["/usr/lib/systemd/system/proxmox-backup-daily-update.timer"] == "platform" + # Proxmox VE's names mean nothing on a backup server. + assert managed["/lib/systemd/system/pve-daily-update.timer"] == "package" + assert managed["/etc/cron.d/vzdump"] == "admin" + assert managed["/usr/lib/systemd/system/apt-daily.timer"] == "package" + + +def test_a_vzdump_cron_line_only_runs() -> None: + """``/etc/cron.d/vzdump`` links into ``/etc/pve``; switching it would replace the link.""" + driver = _driver(ProxmoxDriver, PVE_REPORT) + job = _by_source(driver)["/etc/cron.d/vzdump"] + assert job["actions"] == ["run"] + with pytest.raises(ScheduledJobRefused): + driver.manage_scheduled_job(str(job["key"]), "disable", digest=str(job["digest"])) + assert driver.run_command.call_count == 2 # two readings, nothing written From 4e7e29b598a638a7f2e66f3c81d3a580c428367c Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Tue, 3 Nov 2026 05:40:27 +0100 Subject: [PATCH 2/3] docs(scheduled-jobs): a vzdump line only runs because of pmxcfs (#56) The guard is not about the link: napalm-device-types now writes the file a link names. /etc/cron.d/vzdump points into /etc/pve, the cluster file system, where installing a file with a mode and owner is not safe. Refs #56 --- CHANGELOG.md | 3 ++- napalm_proxmox/driver.py | 2 +- napalm_proxmox/scheduled_jobs.py | 4 ++-- tests/test_scheduled_jobs.py | 2 +- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2746734..5dcff46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 What Proxmox ships is `platform`: on Proxmox VE `pve-*` units (`pve-daily-update.timer`), `pvesr.timer` and `/etc/cron.d/vzdump`; on a backup server `proxmox-backup*` units (`proxmox-backup-daily-update.timer`). A line in `/etc/cron.d/vzdump` is only run, never - switched: the file is a link into `/etc/pve`, and rewriting it would replace the link. + switched: the file is a link to `/etc/pve/vzdump.cron` on the cluster file system + (pmxcfs), where installing a file with a mode and owner is not safe. Not scheduled jobs here: Proxmox VE's backup jobs (`/cluster/backup`) and replication, and a backup server's verify, prune, sync and garbage collection jobs. Proxmox runs them in its own daemons; `get_clusters()` and `get_backup_jobs()` keep them. diff --git a/napalm_proxmox/driver.py b/napalm_proxmox/driver.py index 4241bc5..137b5c0 100644 --- a/napalm_proxmox/driver.py +++ b/napalm_proxmox/driver.py @@ -119,7 +119,7 @@ class ProxmoxDriver( FULL_UPGRADE = True #: Proxmox VE's own timers and cron file are ``platform``. PLATFORM_SOURCES = PVE_PLATFORM_SOURCES - #: ``/etc/cron.d/vzdump`` links into ``/etc/pve``; its lines are only run. + #: ``/etc/cron.d/vzdump`` links into ``/etc/pve`` (pmxcfs); its lines are only run. RUN_ONLY_SOURCES = ("/etc/cron.d/vzdump",) PORT_SPECS = [ PortSpec("https", 8006, weight=8.0), diff --git a/napalm_proxmox/scheduled_jobs.py b/napalm_proxmox/scheduled_jobs.py index d38c340..0aa3b4c 100644 --- a/napalm_proxmox/scheduled_jobs.py +++ b/napalm_proxmox/scheduled_jobs.py @@ -39,8 +39,8 @@ PBS_PLATFORM_SOURCES = tuple(f"{d}/proxmox-backup*" for d in _UNITS) class ProxmoxScheduledJobsMixin(PosixScheduledJobsMixin): """Scheduled jobs of a Proxmox host; a driver sets ``PLATFORM_SOURCES``.""" - #: Sources a job is only run from: links into ``/etc/pve``, which a rewrite - #: (``install`` over the path) would replace with a file of its own. + #: Sources a job is only run from: links into ``/etc/pve``, the cluster file system + #: (pmxcfs), where a switch's ``install`` with a mode and owner is not safe. RUN_ONLY_SOURCES: ClassVar[tuple[str, ...]] = () def _sj_read(self) -> Reading: diff --git a/tests/test_scheduled_jobs.py b/tests/test_scheduled_jobs.py index 9f93aea..4a274a4 100644 --- a/tests/test_scheduled_jobs.py +++ b/tests/test_scheduled_jobs.py @@ -128,7 +128,7 @@ def test_what_a_backup_server_ships_is_platform() -> None: def test_a_vzdump_cron_line_only_runs() -> None: - """``/etc/cron.d/vzdump`` links into ``/etc/pve``; switching it would replace the link.""" + """``/etc/cron.d/vzdump`` links into pmxcfs (``/etc/pve``), where no switch writes.""" driver = _driver(ProxmoxDriver, PVE_REPORT) job = _by_source(driver)["/etc/cron.d/vzdump"] assert job["actions"] == ["run"] From 25363ac7b0ab8c7255d9d367aa3f0e31431cc223 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Tue, 3 Nov 2026 08:35:41 +0100 Subject: [PATCH 3/3] chore(scheduled-jobs): require napalm-device-types 4.27.0 4.26.0 went out with the sshd drop-in change; the scheduled-jobs contract is in 4.27.0. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 828f347..c942197 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,7 +21,7 @@ classifiers = [ requires-python = ">=3.12" dependencies = [ "napalm>=5.0.0", - "napalm_device_types>=4.26.0", # PosixScheduledJobsMixin + "napalm_device_types>=4.27.0", # PosixScheduledJobsMixin "paramiko>=5.0.0", # CVE-2026-44405; imported directly for the node's SSH session (_base.py) "proxmoxer>=2.0.0", "netaddr>=0.9.0",