← Full reference

cron and crontab

Running commands on a schedule — crontab format, crontab -e/-l, system files and environment traps

cron is a daemon that wakes up once a minute, reads the schedules and runs the commands whose time has come. A user's schedule is their crontab, edited with the crontab command. There are also system schedules in /etc/crontab and /etc/cron.d/.

Syntax

crontab -e            # edit your schedule
crontab -l            # show it
crontab file          # replace the schedule with the file's contents

A schedule line:

# min  hour day   month  weekday      command
  30   2    *     *      1-5          /usr/local/bin/report.sh

Fields

FieldValues
minute0–59
hour0–23
day of month1–31
month1–12 or jan–dec
day of week0–7 (0 and 7 are Sunday) or sun–sat
commandeverything to the end of the line; run via /bin/sh
Field valueMeaning
*any value
5exactly 5
1,15list: 1 and 15
1-5range: 1 through 5 inclusive
*/10every tenth: 0, 10, 20…
9-18/3step within a range: 9, 12, 15, 18

Special strings

StringEquivalent
@rebootonce, when the cron daemon starts
@hourly0 * * * *
@daily / @midnight0 0 * * *
@weekly0 0 * * 0
@monthly0 0 1 * *
@yearly / @annually0 0 1 1 *

The crontab command

OptionWhat it does
-eopen the schedule in an editor ($VISUAL / $EDITOR); the syntax is checked after saving
-lprint the schedule; if there is none — "no crontab for …" and exit code 1
-rdelete the whole schedule without asking; -ri — with confirmation
file / -install the schedule from a file / from stdin (the old one is replaced entirely)
-n fileonly check the syntax, don't install
-u userwork with another user's schedule (requires root)

User schedules are stored in /var/spool/cron/crontabs/<name>, but you should edit them only through crontab.

Variables in crontab

Lines like NAME=value set the environment for the jobs below that line.

VariableWhat it sets
PATHwhere to look for commands; by default only /usr/bin:/bin
SHELLwhat runs the command; default /bin/sh (that's dash, not bash)
MAILTOwho gets the jobs' output by mail; MAILTO="" — nobody
HOMEhome directory; jobs start in it

The rest of the environment is minimal: a job sees HOME, LOGNAME, PATH, SHELL, PWD, LANG and whatever you set yourself.

System schedules

WhereSpecifics
/etc/crontabhas a sixth field — the user: 17 * * * * root command
/etc/cron.d/<file>the same format with a user; the file is picked up without crontab
/etc/cron.hourly/, daily/, weekly/, monthly/executable scripts run by run-parts from /etc/crontab

Examples

# install a schedule from a file and check it
crontab jobs.txt
crontab -l

# check the syntax without changing anything
crontab -n jobs.txt

# append a line to the existing schedule
(crontab -l 2>/dev/null; echo '0 3 * * * /usr/local/bin/backup.sh') | crontab -

# another user's schedule
crontab -u www-data -l

# cron must be running, otherwise nothing gets executed
service cron start
pgrep -x cron

Sample schedule lines:

SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
MAILTO=""

# every 5 minutes, output and errors to a log
*/5 * * * * /usr/local/bin/check.sh >> /var/log/check.log 2>&1

# at 02:30 on weekdays
30 2 * * 1-5 /usr/local/bin/report.sh

# on the 1st and 15th at midnight
0 0 1,15 * * /usr/local/bin/invoice.sh

# a percent sign in the command must be escaped
0 0 * * * tar czf /backup/etc-$(date +\%F).tgz /etc

# when cron starts
@reboot /usr/local/bin/warmup.sh

Pitfalls

  • PATH in cron is only /usr/bin:/bin. A command from /usr/sbin or /usr/local/bin that works in your terminal gives "command not found" in cron. Use full paths or set PATH at the top of the crontab.
  • % in a command is a newline. Everything after the first unescaped % is fed to the command on stdin. date +%F in a crontab breaks — write date +\%F.
  • Variables apply only to the lines below. A PATH=… written after a job doesn't affect that job.
  • The last line must end with a newline. crontab rejects a file without one, and in /etc/cron.d a last line without \n is silently ignored.
  • Day of month and day of week are combined with "OR". 0 0 13 * 5 means "every 13th and every Friday", not "Friday the 13th".
  • The command runs in sh, not bash. [[ ]], {1..5}, &> don't work unless SHELL=/bin/bash is set.
  • Job output goes nowhere: cron tries to mail it, and mail isn't configured in the container. Redirect to a file: >> /var/log/job.log 2>&1.
  • /etc/cron.d and /etc/crontab need the user field. Without it cron takes the first word of the command as the user name, and the job doesn't run.
  • Files in /etc/cron.d with a dot in the name (backup.cron) are ignored, as are files writable by the group or by everyone. Names — only letters, digits, - and _; permissions — 644.
  • In a container cron isn't started automatically. Until there's a cron process, the schedule doesn't work: service cron start. The daemon picks up crontab changes on its once-a-minute check.
  • Times follow the system time zone. In the sandbox it's UTC; check with date.

See also

date · service · redirection · logrotate