feat(scheduled-jobs): scheduled jobs on Proxmox VE and Backup Server (#56) #59

Merged
christianmanivong merged 3 commits from feature/scheduled-jobs into main 2026-11-03 15:05:16 +00:00
7 changed files with 221 additions and 1 deletions

No files matched your search

+18
View File
@@ -7,6 +7,24 @@ 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 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.
### Changed
- Requires napalm-device-types 4.26.0.
## [0.10.0] - 2026-11-03
### Added
+4
View File
@@ -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
+4
View File
@@ -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),
]
+6
View File
@@ -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`` (pmxcfs); its lines are only run.
RUN_ONLY_SOURCES = ("/etc/cron.d/vzdump",)
PORT_SPECS = [
PortSpec("https", 8006, weight=8.0),
]
+51
View File
@@ -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``, 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:
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
+1 -1
View File
@@ -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.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",
+137
View File
@@ -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 pmxcfs (``/etc/pve``), where no switch writes."""
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