safe-crontab: the guarded crontab installer we wish we'd had

We are releasing a small tool called safe-crontab, a guarded, drop-in replacement for crontab <file>. It is open source under the MIT licence, written by Zak Fielding, and the code is now up at github.com/zaktrue/safe-crontab.

Plain crontab <file> has no guard rails at all. It replaces the entire schedule in one shot, takes no backup, and gives no warning if the new file happens to be far smaller than the one it is about to overwrite. We know that because it happened to us.

An automated agent needed to add a couple of lines to a crontab. It wrote a small file containing just those new lines and ran crontab on it, without first pulling the existing schedule down with crontab -l and adding to that. Since plain crontab does not add, it replaces, the result was not two extra lines, it was every previously scheduled job gone at once: 363 lines, deleted in a single command, with no confirmation prompt and no backup taken by crontab itself. We recovered everything from an independent backup that happened to exist for unrelated reasons, so nothing was actually lost. But that recovery was luck, not anything the tooling had actually guaranteed, and the incident should never have been possible in the first place.

safe-crontab is what we built the next day, with one aim: make that specific mistake, and the general shape of mistake it belongs to, get refused before it happens rather than tidied up after. Running safe-crontab <file> performs five steps in order. It locks the whole operation with flock so two installs cannot race each other. It backs up the current live crontab to a timestamped file before anything else happens. It checks the new file against a shrink guard: if it has far fewer lines than a configurable share of the current crontab, the install is refused outright, unless --force-shrink is passed for a genuinely deliberate large removal. Where the local crontab supports a dry-run flag, it checks the new file’s syntax before installing anything. Finally it installs the file and reads it back for a best-effort comparison against the source.

That last step is worth being honest about, because it is easy to oversell. The readback comparison is advisory, not a guarantee. Some crontab implementations quietly rewrite whitespace, blank lines or comments when they store a schedule, so a correct install can still produce a hash that does not quite match the source file, and treating that as a failure would just produce false alarms. A mismatch is logged as a warning; a match is never treated as proof either. Anyone who needs real certainty should run crontab -l themselves once safe-crontab finishes. We would rather say that plainly than claim a level of assurance the tool cannot actually back up.

The tool is Linux-first, built and tested against a GNU userland: it needs bash, flock, sha256sum and GNU xargs. It has not been tested on macOS or the BSDs, which lack some of those by default, so treat it as untested there rather than assume it will just work.

safe-crontab is for anyone letting automation, a script, or an agent touch crontab unattended, which is exactly the situation that caused our incident: a human can be careful once and distracted the next time, but a script has no notion of caution beyond whatever is actually enforced in the code path it calls. It is just as useful for a person editing a crontab by hand who would rather have a backup taken automatically than remember to take one. We are not claiming it will stop every possible mistake. We are saying it refuses the one specific shape of mistake that nearly cost us a working schedule, and we would rather ship something honest about its limits than something that overpromises. It is free, it is MIT licensed, and we would be glad to see it get some use.

← Back to Blog