feat(scheduled-jobs): the cron jobs of config.xml over the REST API (#43) #44

Merged
christianmanivong merged 2 commits from feature/scheduled-jobs into main 2026-11-03 08:20:27 +00:00
Owner

Summary

Scheduled jobs on OPNsense through the cron API: every cron job of config.xml is read with who owns it, any job can be enabled and disabled, and an application's own jobs can be written and deleted. A job's command is a configd action, validated against what configd offers.

Changes

  • New napalm_opnsense/scheduled_jobs.py with OPNsenseScheduledJobsMixin, mixed into OPNsenseDriver.
  • get_scheduled_jobs(): one GET /api/cron/settings/get (it carries the selected configd action; search_jobs shows its display text). key=opnsense:<uuid>, kind=cron, source=config.xml, run_as=root, schedule_kind=cron. Origin other than cron is platform; a description starting with napalm-scheduled-job: <name> is application (name and the rest as description); everything else admin. An answer without its jobs raises ValueError. time_zone is None (the driver does not read the system settings).
  • manage_scheduled_job(): enable/disable via toggle_job/<uuid>/1|0 + cron/service/reconfigure. run is in no job's actions and is refused: the API cannot run a configd action now.
  • put_scheduled_job(): command is a configd action (longest one configd offers that the command starts with), the words after it its parameters; unknown actions, @reboot, run_as other than root, multi-line commands and parameters with blanks, quotes or backslashes are refused (ScheduledJobRefused). The schedule is written as its five fields, aliases expanded, month/weekday names as numbers (OPNsense's field masks take no names). OPNsense validation errors become ScheduledJobRefused.
  • delete_scheduled_job(): only application jobs, via del_job/<uuid> + reconfigure.
  • get_scheduled_job_commands(): the configd actions a job can run (GET /api/cron/settings/get_job, blank job), [{"command", "description"}]; an empty list raises (configd did not answer).
  • Every write reads the job again and raises ScheduledJobChanged when its digest differs.
  • napalm-device-types>=4.26.0; README method table and a short section; CHANGELOG.
  • opnsense.py stays at its recorded size: the redundant import re as _re in manage_service goes.

Related Issue

Closes #43
Part of NetOrk/netork#1933

Testing

  • tests/unit/test_scheduled_jobs.py: 61 tests over synthetic API answers in the shape of OPNsense 26.7 (admin, IDS-registered, application, with parameters, invalid marker); new module at 100% coverage, suite 549 passed, 85% total.
  • ruff format/check, mypy (strict for the new module), napalm-standard check and ratchet, bandit: clean.
  • Not tried on a firewall yet.
## Summary Scheduled jobs on OPNsense through the cron API: every cron job of config.xml is read with who owns it, any job can be enabled and disabled, and an application's own jobs can be written and deleted. A job's command is a configd action, validated against what configd offers. ## Changes - New `napalm_opnsense/scheduled_jobs.py` with `OPNsenseScheduledJobsMixin`, mixed into `OPNsenseDriver`. - `get_scheduled_jobs()`: one `GET /api/cron/settings/get` (it carries the selected configd action; `search_jobs` shows its display text). `key=opnsense:<uuid>`, `kind=cron`, `source=config.xml`, `run_as=root`, `schedule_kind=cron`. Origin other than `cron` is `platform`; a description starting with `napalm-scheduled-job: <name>` is `application` (name and the rest as description); everything else `admin`. An answer without its jobs raises `ValueError`. `time_zone` is `None` (the driver does not read the system settings). - `manage_scheduled_job()`: enable/disable via `toggle_job/<uuid>/1|0` + `cron/service/reconfigure`. `run` is in no job's `actions` and is refused: the API cannot run a configd action now. - `put_scheduled_job()`: `command` is a configd action (longest one configd offers that the command starts with), the words after it its parameters; unknown actions, `@reboot`, `run_as` other than root, multi-line commands and parameters with blanks, quotes or backslashes are refused (`ScheduledJobRefused`). The schedule is written as its five fields, aliases expanded, month/weekday names as numbers (OPNsense's field masks take no names). OPNsense validation errors become `ScheduledJobRefused`. - `delete_scheduled_job()`: only `application` jobs, via `del_job/<uuid>` + `reconfigure`. - `get_scheduled_job_commands()`: the configd actions a job can run (`GET /api/cron/settings/get_job`, blank job), `[{"command", "description"}]`; an empty list raises (configd did not answer). - Every write reads the job again and raises `ScheduledJobChanged` when its digest differs. - `napalm-device-types>=4.26.0`; README method table and a short section; CHANGELOG. - `opnsense.py` stays at its recorded size: the redundant `import re as _re` in `manage_service` goes. ## Related Issue Closes #43 Part of NetOrk/netork#1933 ## Testing - `tests/unit/test_scheduled_jobs.py`: 61 tests over synthetic API answers in the shape of OPNsense 26.7 (admin, IDS-registered, application, with parameters, invalid marker); new module at 100% coverage, suite 549 passed, 85% total. - ruff format/check, mypy (strict for the new module), `napalm-standard check` and `ratchet`, bandit: clean. - Not tried on a firewall yet.
christianmanivong added 1 commit 2026-11-03 04:44:42 +00:00
feat(scheduled-jobs): the cron jobs of config.xml over the REST API (#43)
driver / standard (pull_request) Successful in 25s
driver / lint (pull_request) Successful in 26s
driver / types (pull_request) Failing after 35s
driver / test (3.13) (pull_request) Failing after 18s
driver / test (3.12) (pull_request) Failing after 21s
driver / lowest (pull_request) Failing after 17s
driver / build (pull_request) Successful in 30s
driver / security (pull_request) Failing after 40s
CI / driver (pull_request) Failing after 1m25s
driver / publish (pull_request) Skipped
c4ff19ac20
OPNsense keeps its cron jobs in its configuration and runs each as a
configd action, so the POSIX implementation does not fit: the driver has
no shell, and a job's command is not a shell line. The cron API reads and
writes them instead.

get_scheduled_jobs reads every job in one request (/api/cron/settings/get,
which carries the selected action rather than its display text). A job
another component registered is platform, one written by
put_scheduled_job carries the napalm-scheduled-job marker in its
description and is application, the rest admin. Every job can be enabled
and disabled; only an application's job is edited or deleted.
put_scheduled_job takes a configd action as command and refuses one
configd does not offer; get_scheduled_job_commands lists them. Running a
job now is refused: the API cannot run a configd action. Every write
reads the job again and refuses one whose digest changed.

Parameters are written one per line and only without blanks, quotes or
backslashes: OPNsense up to 26.1 splits them as a shell would, 26.7 takes
a line per argument, and only such arguments mean the same to both.

Requires napalm-device-types 4.26.0.

Closes #43
christianmanivong added 1 commit 2026-11-03 07:35:59 +00:00
chore(scheduled-jobs): require napalm-device-types 4.27.0
driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Successful in 14s
driver / types (pull_request) Successful in 56s
driver / test (3.12) (pull_request) Successful in 1m7s
driver / test (3.13) (pull_request) Successful in 1m1s
driver / lowest (pull_request) Successful in 32s
driver / build (pull_request) Successful in 27s
driver / security (pull_request) Successful in 55s
CI / driver (pull_request) Successful in 2m30s
driver / publish (pull_request) Skipped
f75d1c8334
4.26.0 went out with the sshd drop-in change; the scheduled-jobs
contract is in 4.27.0.
christianmanivong merged commit 0289963af8 into main 2026-11-03 08:20:27 +00:00
Sign in to join this conversation.
No Reviewers
1 Participants
Notifications
Due Date
No due date set.
Blocks
You do not have permission to read 1 dependency
Reference: NAPALM/napalm-opnsense#44