Scheduled jobs: ScheduledJobsMixin contract, POSIX cron and systemd timer readers and writers #86

Closed
opened 2026-11-02 23:39:22 +00:00 by christianmanivong · 1 comment
Owner

Part of NetOrk/netork#1933. Priority: P3 — important, not urgent (the NAPALM org has no labels, so it is stated here).

Blocks every driver issue of the epic — the contract has to stand before they run in parallel.

Contract

ScheduledJobsMixin (like ServiceControlMixin), ScheduledJobDict:

Field
key stable per source: timer:<unit>, cron:<path>:<digest of the normalised line>[:n], run-parts:<dir>/<script>, task:<path><name>, opnsense:<uuid>, omv:<uuid> …
kind cron / run_parts / anacron / systemd_timer / periodic / task
source file, unit file, or the platform's configuration
run_as user
schedule, schedule_kind raw expression; cron / calendar (OnCalendar) / monotonic (OnBootSec …) / period (anacron, periodic) / triggers (Windows)
command as the host has it
enabled
managed_by package / admin / platform / netork
last_run, last_result, next_run optional — where the host knows them (timers, Windows, OMV)
description optional

Methods: get_scheduled_jobs(), manage_scheduled_job(key, action, *, expected_hash) with enable / disable / run, and put_scheduled_job(spec, *, expected_hash=None) / delete_scheduled_job(key, *, expected_hash) for netOrk's own. A verb a driver cannot do is refused explicitly (None attribute, as manage_service), never pretended.

Shared implementations (POSIX hosts)

  • Cron reader: /etc/crontab, /etc/cron.d/*, user crontabs (/var/spool/cron/crontabs, /var/spool/cron, /etc/crontabs), run-parts directories, /etc/anacrontab — one framed round trip, root through fixed commands (find … -print0, cat --), a truncated report raises. @ schedules, variables, %, # inside a command handled correctly.
  • systemd timer reader: list-timers --all + one systemctl show over all timers and their units (TimersCalendar, TimersMonotonic, NextElapseUSecRealtime, LastTriggerUSec, Result, UnitFileState, FragmentPath, the unit's ExecStart/User/ExecMainStatus) — one round trip.
  • managed_by: one batched package-database query (dpkg -S / rpm -qf / apk info -W) over all definition files.
  • Writers: stage unprivileged, install as root with a fixed command; foreign cron line disabled with the marker # netork-disabled: ; own job as netork-<slug>.timer/.service or /etc/cron.d/netork-<slug>; systemd-analyze calendar / verify before a timer is installed; the expected hash checked right before the write.
  • Disabling a package's run-parts script: chmod -x is undone by the next package upgrade — dpkg-statoverride keeps it; to be settled here.
  • On Debian many cron.daily scripts exit when systemd runs, because a timer does the work — a job shown twice must be recognisable as such.

Replaces

get_cron_jobs() and CronJobDict are removed, not kept beside the new contract — nothing in netOrk calls them.

Part of NetOrk/netork#1933. **Priority:** P3 — important, not urgent (the NAPALM org has no labels, so it is stated here). **Blocks every driver issue of the epic** — the contract has to stand before they run in parallel. ## Contract `ScheduledJobsMixin` (like `ServiceControlMixin`), `ScheduledJobDict`: | Field | | |---|---| | `key` | stable per source: `timer:<unit>`, `cron:<path>:<digest of the normalised line>[:n]`, `run-parts:<dir>/<script>`, `task:<path><name>`, `opnsense:<uuid>`, `omv:<uuid>` … | | `kind` | `cron` / `run_parts` / `anacron` / `systemd_timer` / `periodic` / `task` | | `source` | file, unit file, or the platform's configuration | | `run_as` | user | | `schedule`, `schedule_kind` | raw expression; `cron` / `calendar` (OnCalendar) / `monotonic` (OnBootSec …) / `period` (anacron, periodic) / `triggers` (Windows) | | `command` | as the host has it | | `enabled` | | | `managed_by` | `package` / `admin` / `platform` / `netork` | | `last_run`, `last_result`, `next_run` | optional — where the host knows them (timers, Windows, OMV) | | `description` | optional | Methods: `get_scheduled_jobs()`, `manage_scheduled_job(key, action, *, expected_hash)` with `enable` / `disable` / `run`, and `put_scheduled_job(spec, *, expected_hash=None)` / `delete_scheduled_job(key, *, expected_hash)` for netOrk's own. A verb a driver cannot do is refused explicitly (`None` attribute, as `manage_service`), never pretended. ## Shared implementations (POSIX hosts) - **Cron reader:** `/etc/crontab`, `/etc/cron.d/*`, user crontabs (`/var/spool/cron/crontabs`, `/var/spool/cron`, `/etc/crontabs`), run-parts directories, `/etc/anacrontab` — one framed round trip, root through fixed commands (`find … -print0`, `cat --`), a truncated report raises. `@` schedules, variables, `%`, `#` inside a command handled correctly. - **systemd timer reader:** `list-timers --all` + one `systemctl show` over all timers and their units (`TimersCalendar`, `TimersMonotonic`, `NextElapseUSecRealtime`, `LastTriggerUSec`, `Result`, `UnitFileState`, `FragmentPath`, the unit's `ExecStart`/`User`/`ExecMainStatus`) — one round trip. - **`managed_by`:** one batched package-database query (`dpkg -S` / `rpm -qf` / `apk info -W`) over all definition files. - **Writers:** stage unprivileged, install as root with a fixed command; foreign cron line disabled with the marker `# netork-disabled: `; own job as `netork-<slug>.timer`/`.service` or `/etc/cron.d/netork-<slug>`; `systemd-analyze calendar` / `verify` before a timer is installed; the expected hash checked right before the write. - Disabling a package's run-parts script: `chmod -x` is undone by the next package upgrade — `dpkg-statoverride` keeps it; to be settled here. - On Debian many `cron.daily` scripts exit when systemd runs, because a timer does the work — a job shown twice must be recognisable as such. ## Replaces `get_cron_jobs()` and `CronJobDict` are removed, not kept beside the new contract — nothing in netOrk calls them.
christianmanivong added a new dependency 2026-11-02 23:39:52 +00:00
christianmanivong added a new dependency 2026-11-02 23:39:52 +00:00
christianmanivong added a new dependency 2026-11-02 23:39:52 +00:00
christianmanivong added a new dependency 2026-11-02 23:39:52 +00:00
christianmanivong added a new dependency 2026-11-02 23:39:52 +00:00
Author
Owner

Merged with #87, v4.27.0.

Merged with #87, v4.27.0.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Blocks
#67 Scheduled jobs: Linux
NAPALM/napalm-linux
#18 Scheduled jobs: OpenMediaVault
NAPALM/napalm-openmediavault
#32 Scheduled jobs: OpenWrt
NAPALM/napalm-openwrt
#43 Scheduled jobs: OPNsense
NAPALM/napalm-opnsense
#17 Scheduled jobs: QNAP QTS
NAPALM/napalm-qnap-qts
#8 Scheduled jobs: Windows
NAPALM/napalm-windows
You do not have permission to read 2 dependencies
Depends on
You do not have permission to read 1 dependency
Reference: NAPALM/napalm-device-types#86