Cron

Cron runs commands on a schedule. This sheet covers crontab syntax, the Debian/Ubuntu layout, the gotchas that make a job work in a terminal but fail under cron, overlap protection with flock, and how the same schedules look in systemd timers, Kubernetes CronJobs and GitHub Actions. Related: Linux, Kubernetes, Regex.

Documentation: man 5 crontab, systemd.time(7), Kubernetes CronJob, GitHub Actions schedule

Syntax #

# ┌───────── minute        (0-59)
# │ ┌─────── hour          (0-23)
# │ │ ┌───── day of month  (1-31)
# │ │ │ ┌─── month         (1-12 or jan-dec)
# │ │ │ │ ┌─ day of week   (0-7 or sun-sat; 0 and 7 are Sunday)
# │ │ │ │ │
  * * * * *  <COMMAND>

Rules that catch people out:

• If both day-of-month and day-of-week are restricted (neither is *), the job runs when either matches (OR, not AND). 0 0 1 * 1 is midnight on the 1st and every Monday.
• */N steps restart at the start of the range, so */7 in the minute field runs at 0, 7, 14 … 56, then 0 again (a 4 minute gap).
• No seconds field. For sub-minute work use a systemd timer or a loop with sleep.
• Times use the system local timezone. Jobs in a daylight-saving gap may be skipped or run twice, so avoid 01:00 to 03:00 local for important jobs, or run the host in UTC.

Special Strings #

crontab Command #

Back up before editing in bulk: crontab -l > crontab.bak.

System Cron #

# /etc/cron.d/backup: schedule, USER, command
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
MAILTO=""
30 2 * * *  root  /usr/local/bin/backup.sh >> /var/log/backup.log 2>&1

• Files in /etc/cron.d must be owned by root and not writable by group or others.
• On Debian/Ubuntu, run-parts and /etc/cron.d skip file names containing a dot (such as backup.sh or job.conf) and the file name must be letters, digits, _ or -. A silently ignored job is almost always this. Check with run-parts --test /etc/cron.daily.
• Scripts in cron.daily and friends need the executable bit and no extension.
• The daily/weekly/monthly times are set in /etc/crontab (or by anacron, see below), commonly 06:25 for daily on Debian.

Environment Gotchas #

Logging and Debugging #

The syslog line shows that a job started, not whether it succeeded. Capture the output yourself and use set -euo pipefail in scripts. For monitoring, ping a dead-man-switch service (Healthchecks.io, Uptime Kuma push monitors) at the end of a successful run:

0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 https://hc-ping.com/<UUID> >/dev/null

Preventing Overlap with flock #

flock holds a lock file for the life of the command, so a slow run does not collide with the next one.

*/5 * * * * flock -n /var/lock/sync.lock /usr/local/bin/sync.sh >> /var/log/sync.log 2>&1

Use a lock path writable by the job user (/var/lock is root-only on some systems; /run/user/<UID>/ or /tmp works for users). Also consider timeout 10m <CMD> to kill hung jobs.

anacron #

Cron skips jobs when the machine is off. anacron runs them later: it records the last run date per job in /var/spool/anacron/ and only handles daily or longer periods. It is what runs cron.daily on laptops and VMs that are not always on.

# /etc/anacrontab: period(days) delay(min) job-id command
1    5   daily-backup   /usr/local/bin/backup.sh
7    10  weekly-report  /usr/local/bin/report.sh
@monthly 15 monthly-clean /usr/local/bin/clean.sh

systemd timers do this natively with Persistent=true.

systemd Timers #

A timer unit starts a service unit of the same name (backup.timer starts backup.service). Benefits over cron: journal logging, dependencies, resource limits, Persistent= catch-up, jitter.

# /etc/systemd/system/backup.service
[Unit]
Description=Nightly backup

[Service]
Type=oneshot
ExecStart=/usr/local/bin/backup.sh

# /etc/systemd/system/backup.timer
[Unit]
Description=Nightly backup timer

[Timer]
OnCalendar=*-*-* 02:30:00
Persistent=true
RandomizedDelaySec=5m

[Install]
WantedBy=timers.target

OnCalendar format is DayOfWeek Year-Month-Day Hour:Minute:Second, every part optional:

Timers are accurate to within AccuracySec= (default 1 minute) to batch wake-ups; set AccuracySec=1s if that matters.

Kubernetes CronJob #

Uses the standard five-field syntax (plus the @ macros). See Kubernetes and Kubectl.

apiVersion: batch/v1
kind: CronJob
metadata:
  name: backup
spec:
  schedule: "30 2 * * *"
  timeZone: "Europe/London"
  concurrencyPolicy: Forbid
  startingDeadlineSeconds: 300
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 1
  jobTemplate:
    spec:
      backoffLimit: 2
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: backup
              image: <IMAGE>
              command: ["/backup.sh"]

• Without spec.timeZone (stable since Kubernetes 1.27) the schedule uses the timezone of the kube-controller-manager, usually UTC.
• concurrencyPolicy: Allow (default), Forbid (skip if previous still running), Replace.
• A job missed for longer than startingDeadlineSeconds is counted as failed and skipped.
• Do not set CRON_TZ= or TZ= inside schedule; use timeZone.

GitHub Actions schedule #

on:
  schedule:
    - cron: "17 5 * * 1-5"
  workflow_dispatch:

• Always UTC. There is no timezone setting, so convert (and remember DST shifts your local time).
• Five fields only, no seconds, and no @daily style macros.
• Runs from the default branch only.
• Can be delayed under load, particularly at the top of the hour. Pick an odd minute (17, not 0).
• In public repos, scheduled workflows are disabled after 60 days without repository activity. Add workflow_dispatch to run by hand.
• The shortest supported interval is every 5 minutes.

Common Schedules #

Cron has no “last day of month” field, so use the date test shown. Sanity check any expression with crontab.guru or systemd-analyze calendar.