The crontab Command And File Syntax

 

©2002 by Wayne Pollock, Tampa Florida USA.  All rights reserved.

Command Use:

The crontab command is used to schedule jobs to be run in the future, usually on some regular schedule (such as every week).  The command is run with one of three command line arguments:

 
crontab -l  View crontab file, if any
crontab -r  Remove crontab file, if any
crontab -e  Edit (or create) user's crontab file (starts the editor automatically)
crontab file  Replace existing crontab file (if any) with file

crontab File Syntax:

The file allows blank lines and comment lines (lines whose first non-blank character is #).  Other lines describe jobs to run and when to run them.  You have one line for each job you wish to run.  The first five fields on a line are called the time-spec.  This says when to run the job.  The rest of the line is some command to run.  Note if you try to put a comment on the end of a command, it will be passed to the command and may not be taken as a comment (it depends on your system's standard shell).

While the command may contain spaces, the first five fields must not contain any white space.  Space is used to separate the fields.  In some versions of crontab other lines may appear in the file.  These are described in the crontab file man page (man crontab) for your system.

The command (and the time-spec fields) must all be on a single line. 

Everything from the start of the command to the first unescaped percent (or a newline if there are no unescaped percent symbols) is the command.  It is run by a plain old shell (and not necessarily your default shell).

crontab will interpret any text on the line following an un-escaped percent symbol (%) as input to be passed into the command's standard input.  (This is similar to the shell's here document feature.)  Each un-escaped percent sign in this text is treated as a new-line. 

If your command uses percent symbols (such as the date) be sure to escape them with a backslash.  This escape of a percent symbol is independent of the shell's quoting rules.  (So to use a backslash percent in the command string you must use ...\\\%..., which is confusing to say the least.)

Operation:

Each minute the cron daemon wakes up and compares the crontab file entries against the current time.  If the five fields match the current minute then the command is executed.  The command runs with the user's permissions.  It is important to note that the command will run with a simplified /bin/sh environment (your login scripts are not run), and further no interactive commands can be used since the command does not run with its input or output connected to any screen or keyboard.

Neither cron nor at have any concept of seconds.  They wake up each minute, on the minute.  However, lengthly commands may take a long time to run.  In addition, many systems will delay the start of crontab jobs by a fixed (but random) amount of seconds.  This prevents 1,000 hosts in an organization from attempting to download updates from the Internet, all at the same time, even when they all have identical crontab files.

Should you forget to redirect standard output or standard error of your command, crontab will send any output to the user as email.

Field Descriptions:

minute  hour  dayOfMonth  month  dayOfWeek  command

where:
minute values range from 0 to 59,
hour values range from 0 to 23,
dayOfMonth values range from 1 to 31,
month values range from 1 to 12,
dayOfWeek values range from 0 to 6, with 0 meaning Sunday

Field Values:

 
NUMA single value
NUM-NUMA range of values
NUM,NUM-NUM,...A comma separated list of values or ranges (remember no spaces after commas!)
* wildcard, meaning match all possible values
(Note: Don't use a wildcard for the minute field, and rarely for the hour!)

Examples:

# Example 1:  0,30 8-17 * * 1-5 cmd
Show/Hide Answer (+/-)

Run cmd on the half-hour from 8:00 AM to 5:30 PM, Monday thru Friday

# Example 2:  0 12 1,15 * 5 cmd
Show/Hide Answer (+/-)

Run cmd at noon each Friday AND the first and fifteenth of every month

# Example 3:  17 3 * * 1 cmd
Show/Hide Answer (+/-)

Run cmd at 3:17 AM Monday (a backup program perhaps)

# Example 4:

# This command sends a "popup" message to the user's screen,
# at 3:00 PM Fridays, if they are logged in:
0 15 * * 5 echo "Time for staff meeting" | write $LOGNAME >/dev/null 2>&1
# Example 5:

# This command sends a multi-line "popup" message to the user's screen,
# at 3:00 PM Fridays, if they are logged in:
0 15 * * 5 write $LOGNAME >/dev/null 2>&1 %Time for the%staff meeting.

Additional Information:

In addition to the per-user crontab files, there may be one or more system-wide crontab files in /etc.  (Use ls -ld /etc/*cron* to find them.)  These files generally have an additional field between the time-spec and the command, which lists with which user account name the command should be run.

See the man page for the crontab command, the man page for the crontab file format (man 5 crontab On Linux and BSD), and also the man page for the anacron or the periodic command (most systems have one or ther other) which is related to crontab.

crontab jobs run detached from the current session, which means that such jobs can't receive input and the output has no place to go.  If you don't make arrangements to redirect the output, it will be collected (standard output and standard error) and sent as email back to the user.

If the computer is off when the job is supposed to run, it will be skipped.  The anacron or periodic command can be used in this situation, if available on your system.

Time changes when the clock gets adjusted, as for daylight savings time changes, may cause some cron jobs to be skipped or run twice.  Although many versions of the cron daemon handle time changes of less then a few hours correctly (by not skipping or repeating cron and at jobs), this behavior is not specified by POSIX.

These jobs run with a very minimal environment.  POSIX only requires these four environment variables set: HOME, LOGNAME, PATH (which should be set to find all standard utilities), and SHELL.  It may be better to write a bash shell script that sources the login scripts (and the ~/.bashrc file).

Linux (Vixie) and BSD cron allow a contab file to contain lines to set environment variables.  Such lines have the form:

name = "value"

Cron (for most systems) will also allow you to control where output goes, by setting the special environment variable (in the crontab file) MAILTO="who", where who is either the name of a user to send the email to, or an empty (null) string to tell crontab to discard any output.

Linux (Vixie) and BSD crontab files allow a convenient short-hand for any field in the time-spec that is either a * or a single range.  In these cases the asterisk or range can be followed with /number, where number indicates a step value.  For example an hour field of 8-17/2 means the same as the hour field of 8,10,12,14,16.  A day-of-month field of */2 means every odd day, and so on.

Access Control:

This is controlled by a pair of files called cron.allow and cron.deny.  The location and even the exact use of these files vary from system to system.  For Linux these file exists in /etc.  On Linux:

In addition cron jobs (and at jobs) may not be run if a user's account is locked (Solaris and FreeBSD do this) or expired/unavailable as per PAM (Linux and FREEBSD do this).

With Vixie cron a number of additional security measures are used: no crontab files may be symbolic (or soft) links, and no crontab files may be executable or be writable by any user other than their owner.  The crontab files in /etc/cron* must be owned by root.