From Cron to systemd Timers

To migrate a job from cron to a systemd timer is to rewrite a five-field cron line as a .timer unit whose OnCalendar expression says when a matching .service unit should run — and then to prove the two schedules agree before the cron line is deleted. The conversion looks mechanical: minutes and hours map directly, months map directly, and most simple schedules translate cleanly. The catch is that the two schedulers do not mean the same thing by the same-looking schedule, and the places where they differ are exactly the places a glance will not catch: a day-of-month combined with a day-of-week, a firing inside the spring-forward gap, a monthly job on the 31st. You can convert and prove both sides in the Cron ⇄ systemd Timer Converter, which computes the next 100 firings of each and flags where they disagree — entirely in your browser.

Why teams move off cron — and why cron is still fine for simple jobs

Cron is the oldest scheduler on Unix, and its limits are the reasons teams leave it. A cron job cannot wait for another service to be ready: if the job needs the database up, it runs anyway and fails, because cron has no dependency ordering. Its output goes to local mail or nowhere, so a job that fails quietly stays failed quietly — there is no journal to query and no status to check. Its calendar is five fields wide, so there is no way to say "the first Monday of the month" or "the last day of February", and a machine that was asleep or off at the scheduled minute simply misses the run. A systemd timer fixes each of those: dependencies with After= and Requires=, every firing logged in the journal like any other unit, a Persistent= catch-up for missed runs, and an OnCalendar expression with weekday names, date ranges, and last-day-of-month syntax.

None of that means cron is obsolete, and migrating a working job just because timers are newer is a mistake. Cron is still the right tool for a simple per-user job, for a schedule that has run unchanged for a decade, and for any system without systemd — containers, minimal images, BSD and macOS hosts. The test is not which scheduler is newer, it is what the job needs: if the job needs ordering, logging, catch-up after downtime, or a calendar cron cannot express, migrate it. If it is a one-line schedule that has never failed and nobody has ever had to debug, leave it alone. A migration that buys nothing is risk with no return, and this article is about the migrations that do buy something — done in a way that cannot silently change when the job runs.

The DOM+DOW trap: the one migration bug that silently doubles firings

The single most dangerous line in a cron migration is one that restricts both the day-of-month and the day-of-week, and the classic example is 0 0 15 * 5. Most people read it as "midnight on Friday the 15th". That is not what it means. The crontab(5) man page states the rule plainly: if both day fields are restricted — neither contains "*" — the command runs when either field matches. So 0 0 15 * 5 fires at midnight on the 15th of every month and on every Friday, roughly five times a month instead of once, and it has been doing so for as long as the line has existed. Anyone who converts it to a single OnCalendar line has just changed the schedule without knowing it.

OnCalendar means the opposite. The systemd.time(7) man page gives the example Thu,Fri 2012-*-1,5 and says it refers to the first or fifth day of the month, "but only if that day is a Thursday or Friday" — date and weekday must both match. So the naive conversion Fri *-*-15 00:00 fires only when the 15th actually is a Friday, a few times a year, and the Friday runs and most of the 15th runs quietly disappear. The correct conversion is two OnCalendar lines in one .timer unit — *-*-15 00:00 and Fri *-*-* 00:00 — because the systemd.timer(5) man page allows OnCalendar to be specified more than once, and the unit triggers whenever any of its expressions elapses. That union is the whole point of the converter: it emits both lines and flags the entry as a union, instead of emitting one line that silently changes the schedule.

DST and month-end: where the two schedulers genuinely disagree

Daylight saving time is where the two schedulers stop agreeing even in principle, and the man pages are honest about the asymmetry. For cron, crontab(5) states the rule explicitly: non-existent times, such as the "missing hours" during the spring-forward change, will never match, so a job scheduled at 02:30 on that day simply does not run — and times that occur more than once, during the fall-back change, cause matching jobs to run twice. For timers, the systemd man pages state no equivalent rule: systemd.time(7) and systemd.timer(5) describe the calendar syntax in detail, but neither page says what an OnCalendar firing does inside the missing hour. That silence is a fact, not an oversight to fill in by guessing, and this article will not invent a rule the man pages do not state.

Month-end is the same story in miniature. A cron line for the 31st simply skips every month that has no 31st, and OnCalendar does the same by default — but OnCalendar also offers syntax cron cannot express at all, such as the "~" last-day form: *-02~01 means the last day of February, and Mon *-05~07/1 means the last Monday in May. The practical consequence is simple: keep time-critical jobs out of 02:00–03:00 if you can, and if you cannot, generate the next-100-runs table across a DST boundary and a month-end and read it instead of guessing. Where the man pages are silent, the table is the only honest answer — run it, do not assume. The same goes for AccuracySec: timers do not necessarily fire at the precise configured second, so a schedule that depends on exact seconds needs a different design, not a tighter expression.

The proof workflow: compare the next 100 firings before you switch

The proof workflow is short, and skipping it is how a migration bug reaches production. Convert the cron line, then compute the next 100 firings of both sides from the same start time in the same timezone, side by side, and read the verdict over all 100 — not the first few. A monthly divergence may not appear in the first ten rows, and a DST divergence will not appear at all unless the window crosses a clock change, which is why the table runs to 100 firings rather than 10. The converter computes both tables in your browser and highlights the first rows where they differ; systemd-analyze calendar validates one OnCalendar expression at a time, which is useful for checking the timer half, but it cannot compare the two halves for you.

The second half of the workflow is a breadcrumb for the next person. Keep the original cron line commented in the .timer or .service file, next to the OnCalendar lines that replaced it, so anyone reading the unit can see what it replaced and why there are two lines instead of one. A conversion without its source line is a schedule nobody can audit: six months later, nobody will remember whether the second OnCalendar line was deliberate or a leftover, and the temptation will be to "clean it up" — which is how the Friday runs disappear a second time. The commented cron line costs one line and answers the question before it is asked.

The safe migration path: drop-ins, Persistent, and the @reboot gap

Never hand-edit a packaged unit file in /usr/lib/systemd/system: the next package update overwrites it, and the migration silently disappears along with the hardening. The supported route is a drop-in override — run systemctl edit myjob.timer and your changes land in /etc/systemd/system/myjob.timer.d/override.conf, where they take precedence over the shipped file, survive upgrades, and can be removed by deleting one file. Then reload, enable the timer, and confirm it is actually armed with systemctl list-timers, which shows the next elapse time — the one number that tells you whether the conversion produced the schedule you meant.

Two settings deserve a deliberate decision rather than a default. Persistent=true is the right choice for laptops and desktops that sleep: if the machine was off when a firing was due, the service runs once at the next opportunity instead of the run silently never happening — note that it is a single catch-up, not a replay of every missed firing, and it only applies to OnCalendar timers. And @reboot has no true timer equivalent: OnBootSec=, which fires a set time after boot, is the closest analogue, and it is not identical — it is relative to boot rather than "run once at startup", and in containers it maps to OnStartupSec=. If the job must run exactly once per boot, OnBootSec= is the answer, but document the difference in the unit; do not pretend the conversion is exact when the man page says otherwise.

The audit-first habit: convert, prove, run in parallel, then cut over

The safest cutover is boring on purpose. Convert, prove with the next-100 table, and then — where the job is idempotent — run both the cron line and the timer in parallel for a week and compare the outcomes: the logs, the outputs, the side effects. A week covers a full weekly cycle and usually a DST boundary or a month-end if one is near, and any firing the proof table predicted will show up in the journal next to the cron run it duplicates. Only when the two agree for a full week do you delete the cron line, and you keep the commented copy in the unit as the breadcrumb from the previous section.

Where the job is not idempotent — it sends mail, charges a customer, mutates a database — do not run both, because the duplicate is the bug you are trying to avoid. Prove harder instead: run the 100-firing table across a DST boundary and a month-end, check the first differing rows by hand, and cut over in one step with the old line commented in the unit. Then audit the finished unit the same way you would audit any other: score it with the systemd Unit Auditor and read the companion article How to Harden systemd Services, because a migrated timer inherits the same sandbox questions as any other unit. Keep the timer, the service, and the proof in version control — a schedule that lives only on one machine is one rebuild away from being forgotten.

Sources

Frequently asked questions

Is OnCalendar just cron with a different syntax?

No — the syntax overlaps, but the semantics differ in the places that matter. Cron ORs day-of-month with day-of-week when both are restricted; OnCalendar ANDs them. OnCalendar supports seconds, date ranges such as 01..07, weekday ranges, timezones, and last-day-of-month syntax with "~" — none of which a five-field cron line can express. It also supports multiple OnCalendar lines in one unit and monotonic timers such as OnBootSec=. Most simple schedules translate cleanly; the trap cases are DOM+DOW combinations, seconds, @reboot, and date ranges, and those are exactly the cases the converter flags instead of guessing.

What happens to a timer firing inside the spring-forward gap?

The man pages do not say. crontab(5) is explicit for cron: a job scheduled in the missing hour never runs, and a job scheduled in the repeated hour runs twice. systemd.time(7) and systemd.timer(5) state no equivalent rule for OnCalendar, so do not assume a timer behaves like cron at 02:30 on the spring-forward day. The honest check is the proof table: generate the next 100 firings across the DST boundary in the converter and read what actually happens. If the job is time-critical, the safest choice is to schedule it outside 02:00–03:00 entirely.

Can I run cron and the timer side by side during migration?

Yes, if the job is idempotent — safe to run twice with the same result. Run both for a week, compare the logs and outputs, and delete the cron line only when the two agree. If the job is not idempotent — it sends mail, takes payment, or mutates state — do not run both, because the duplicate run is itself the failure. In that case, prove the schedule with the 100-firing table instead, cut over in one step, and keep the old cron line commented in the unit so the conversion stays auditable.