Add system cron discovery and management; bump to 0.2.0
This commit is contained in:
19 files changed
+1129
-55
No files matched your search
@@ -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
@@ -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
@@ -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
@@ -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.
|
||||
Reference in new issue
Block a user