Add system cron discovery and management; bump to 0.2.0
CI / test (3.11) (pull_request) Successful in 48s
CI / test (3.13) (pull_request) Successful in 54s

This commit is contained in:
mdaleo404 committed 2026-09-26 08:43:00 +01:00
1 parent 62d505a17e
commit 58d8d0f378
19 files changed
+1129 -55

No files matched your search

+7 -4
View File
@@ -82,9 +82,9 @@ Plan
```
The caller previews the plan, obtains confirmation, then calls `apply`. Plans
snapshot existing content so a failed step can be rolled back. Cron plans also
record the previous crontab text and re-check it at apply time to detect
concurrent edits.
snapshot existing content so a failed step can be rolled back. Cron plans
record the previous crontab text or drop-in content and re-check it at apply
time to detect concurrent edits.
## Exit codes
@@ -124,4 +124,7 @@ The schema version is `1`.
```
Rules: no ANSI sequences; ISO 8601 timestamps with explicit offsets; stable
field names; missing data is `null`, never invented.
field names; missing data is `null`, never invented. Jobs whose `backend` is
`cron` additionally carry a `cron` object (`expression`, `shell`, `mailto`,
`line`, `user`, `environment`), where `user` is the run-as account for system
entries and `null` for the current user's crontab.
+13
View File
@@ -63,12 +63,20 @@ systemd extras (persistent, jitter, accuracy, working directory, environment).
```console
$ schedls new backup --timer --daily 02:00 --persistent -- /usr/local/bin/backup /srv/data
$ schedls new cleanup --cron --cron-expr '0 4 * * 0' -- /usr/local/bin/cleanup
$ sudo schedls new updates --cron --system --daily 03:00 -- /usr/local/bin/updates
$ sudo schedls new report --cron --system --daily 04:00 --run-as www-data -- /usr/local/bin/report
$ schedls new backup -i
```
Creates a scheduled job. `NAME` and a backend (`--timer` or `--cron`) are
required unless `--interactive` is used.
Cron jobs are created for the current user's crontab. With `--system` (root
only) the job is created as an `/etc/cron.d/schedls-NAME` drop-in and runs as
`root` unless `--run-as USER` is given. System cron names may contain letters,
digits, `_` and `-` only, because cron ignores `cron.d` file names containing a
period. `--run-as` is valid only together with `--cron --system`.
The command to run is everything after `--`:
```console
@@ -112,6 +120,8 @@ $ schedls rm backup --dry-run
```
Removes a schedls-managed job and its files. Unmanaged jobs cannot be removed.
For a system cron job this removes the `/etc/cron.d/schedls-NAME` drop-in and
refuses to touch anything whose markers no longer match.
### `enable NAME` / `disable NAME`
@@ -257,6 +267,9 @@ $ schedls edit backup -i
```
- Prompts use stdin only; no external editor or pager is ever launched.
- `new` asks for the scope (user or system) unless `--user`/`--system` was
given. Choosing system for a cron job also asks which user it should run as
(`--run-as`, default `root`).
- A terminal is required. With piped or redirected input, `schedls` exits `3`
and asks you to pass flags instead.
- Interactive mode cannot be combined with `--json` (exit `2`).
+59 -8
View File
@@ -1,11 +1,25 @@
# cron backend
`schedls` reads and edits the **current user's crontab** through the `crontab`
utility. It never writes to `/var/spool/cron*` directly.
`schedls` reads every cron source visible to it:
- the **current user's crontab**, through the `crontab` utility;
- **system crontabs**: `/etc/crontab`, `/etc/cron.d/*`;
- **periodic directories**: `/etc/cron.{hourly,daily,weekly,monthly}/*`;
- **other users' crontabs** (`/var/spool/cron/crontabs/*` on Debian-style
systems, `/var/spool/cron/*` elsewhere) when running as root.
Cron jobs are named after where they live: system entries are `<file>:<line>`,
periodic scripts are named after the script, spool entries are `<user>:<line>`,
and the current user's crontab entries are `cron-<line>`. Jobs created by
`schedls` are listed under their schedule name instead.
`schedls` writes either through the `crontab` utility (current user) or as an
`/etc/cron.d/schedls-<name>` drop-in (system, root only). It never writes to
`/var/spool/cron*` directly.
## Reading
The crontab is read with `crontab -l` and parsed losslessly into lines:
The user crontab is read with `crontab -l` and parsed losslessly into lines:
- blank lines;
- comments;
@@ -13,12 +27,18 @@ The crontab is read with `crontab -l` and parsed losslessly into lines:
- five-field entries and `@` nicknames;
- `schedls:begin` / `schedls:end` managed-block markers.
System crontabs add a user field between the schedule and the command
(`min hour dom mon dow USER command`). Files in `/etc/cron.d` whose names
contain a period, and hidden files, are ignored because cron ignores them too.
Periodic directories only contribute executable, run-parts-style file names.
Every unrelated line is preserved exactly. `schedls` does not reformat, sort,
normalize, or rewrite crontab content it did not create.
## Managed blocks
Jobs created by `schedls` live in a delimited block:
Jobs created by `schedls` in the current user's crontab live in a delimited
block:
```cron
# schedls:begin name=backup
@@ -29,6 +49,30 @@ Jobs created by `schedls` live in a delimited block:
If markers are malformed or a `begin` has no matching `end`, mutations refuse
to proceed rather than guess.
## System drop-ins
A system cron job is a file named after the schedule:
```cron
# Managed by schedls
# schedls:begin name=backup
0 2 * * * root /usr/local/bin/backup /srv/data
# schedls:end name=backup
```
Only `/etc/cron.d/schedls-<name>` files carrying a matching managed block are
treated as managed. A `schedls-` prefixed file whose markers are missing or
malformed is listed as unmanaged (`schedls-<name>:<line>`) and cannot be
removed. Creating system jobs requires root and a trusted `/etc/cron.d`
directory: not a symlink, owned by root, and not group- or other-writable.
Removal deletes only the drop-in file, after re-checking that it still matches
the snapshot and markers. Cron picks up `/etc/cron.d` changes by itself, so no
daemon reload is issued.
Use `--run-as USER` to run a system job as another account (default `root`).
The interactive wizard (`schedls new -i`) asks for the scope, and choosing the
system scope for a cron job then prompts for the run-as user.
## Command rendering
Cron executes command text through a shell. `schedls` keeps an argv internally
@@ -56,11 +100,16 @@ shell mode from characters such as `|`, `>`, `&&` or `$()`.
## Installation and validation
When the local `crontab` supports syntax testing (`crontab -T`), the new
When the local `crontab` supports syntax testing (`crontab -T`), a new user
crontab is validated before installation. The native `crontab` install remains
authoritative. The previous crontab text is retained and restored if
installation fails or the crontab changed since the plan was prepared.
System drop-ins are validated when they are rendered and written atomically;
`crontab -T` only understands user-format crontabs, so it is not used for them.
A file written by `schedls` is re-read and its managed block verified before
the command reports success.
Capabilities are feature-detected, never assumed:
```python
@@ -85,6 +134,8 @@ command-line compatibility but have no effect on cron jobs; see
## Not yet supported
- system cron (`/etc/crontab`, `/etc/cron.d`, periodic directories);
- editing existing cron jobs;
- cross-user crontabs.
- editing cron jobs (user or system);
- token-level updates of `/etc/crontab` (read-only, shared file);
- anacron (`/etc/anacrontab`);
- removing or editing periodic directory scripts;
- modifying other users' spool crontabs (read-only, root only).
+12 -4
View File
@@ -58,7 +58,11 @@ never uses it to build a filesystem path: unit names are always derived from
the validated job name (`schedls-<name>.timer` / `.service`). Generated unit
names are re-validated before they are written to a temporary directory, so a
crafted unit cannot redirect writes or removals outside the trusted unit
directory.
directory. System cron drop-ins follow the same rule: the path is always
`/etc/cron.d/schedls-<name>` from the validated schedule name, with letters,
digits, `_` and `-` only, and removal refuses any path that is not exactly the
expected one. System names never contain a period, because cron ignores
`cron.d` files with dots.
### Untrusted output
@@ -89,14 +93,18 @@ Configuration is treated as opaque data. Malformed `schedls` cron markers cause
mutation to fail closed rather than guess. Unknown crontab lines are preserved
byte-for-byte. A systemd unit whose name starts with `schedls-` is only treated
as managed when its file carries the `# Managed by schedls` and `# Name:`
markers, so a same-named foreign unit is not modified.
markers, so a same-named foreign unit is not modified. Likewise a
`/etc/cron.d/schedls-<name>` drop-in is only managed when its begin/end markers
match the file name; otherwise it is listed as unmanaged and left alone.
### Partial operations
systemd creation writes both units, reloads the manager, and enables the timer;
if a later step fails, or the operation is interrupted, the previous state is
restored and a partially enabled timer is disabled again. Cron installs are
validated first and restored from the previous crontab text on failure.
validated first and restored from the previous crontab text on failure. System
cron drop-ins are written atomically and a failed multi-file apply restores or
removes whatever it had already written.
### Supply chain
@@ -105,6 +113,6 @@ in CI.
## Availability, privacy
`0.1.0` requires `systemd-analyze` to create or validate calendar expressions
`0.2.0` requires `systemd-analyze` to create or validate calendar expressions
and refuses the operation if it is unavailable. `schedls` makes no network
requests and collects no telemetry.