crontab.1

.TH CRONTAB 1 "1 May 2011"
.SH NAME
.PP
crontab - manipulate per-user crontabs (dillon's lightweight cron
daemon)
.SH SYNOPSIS
.PP
\f[B]crontab file [-u user]\f[] - replace crontab from file
.PP
\f[B]crontab - [-u user]\f[] - replace crontab from stdin
.PP
\f[B]crontab -l [-u user]\f[] - list crontab for user
.PP
\f[B]crontab -e [-u user]\f[] - edit crontab for user
.PP
\f[B]crontab -d [-u user]\f[] - delete crontab for user
.PP
\f[B]crontab -c dir\f[] - specify crontab directory
.SH DESCRIPTION
.PP
\f[B]crontab\f[] manipulates the per-user crontabs.
.PP
Generally the -e option is used to edit your crontab.
\f[B]crontab\f[] will use the editor specified by your EDITOR or
VISUAL environment variable (or /usr/bin/vi) to edit the crontab.
.PP
\f[B]crontab\f[] doesn't provide the kinds of protections that
programs like \f[B]visudo\f[] do against syntax errors and
simultaneous edits.
Errors won't be detected until \f[B]crond\f[] reads the crontab
file.
What \f[B]crontab\f[] does is provide a mechanism for users who may
not themselves have write privileges to the crontab folder to
nonetheless install or edit their crontabs.
It also notifies a running crond daemon of any changes to these
files.
.PP
Only users who belong to the same group as the \f[B]crontab\f[]
binary will be able to install or edit crontabs.
However it'll be possible for the superuser to install crontabs
even for users who don't have the privileges to install them
themselves.
(Even for users who don't have a login shell.)
Only the superuser may use the -u or -c switches to specify a
different user and/or crontab directory.
.PP
The superuser also has his or her own per-user crontab, saved as
/var/spool/cron/crontabs/root.
.PP
Unlike other cron daemons, this crond/crontab package doesn't try
to do everything under the sun.
It doesn't try to keep track of user's preferred shells; that would
require special-casing users with no login shell.
Instead, it just runs all commands using \f[C]/bin/sh\f[].
(Commands can of course be script files written in any shell you
like.)
.PP
Nor does it do any special environment handling.
A shell script is better-suited to doing that than a cron daemon.
This cron daemon sets up only four environment variables: USER,
LOGNAME, HOME, and SHELL.
.PP
Our crontab format is roughly similar to that used by vixiecron.
Individual fields may contain a time, a time range, a time range
with a skip factor, a symbolic range for the day of week and month
in year, and additional subranges delimited with commas.
Blank lines in the crontab or lines that begin with a hash (#) are
ignored.
If you specify both a day in the month and a day of week, it will
be interpreted as the Nth such day in the month.
.PP
Some examples:
.IP
.nf
\f[C]
#\ MIN\ HOUR\ DAY\ MONTH\ DAYOFWEEK\ \ COMMAND
#\ run\ `date`\ at\ 6:10\ am\ every\ day
10\ 6\ *\ *\ *\ date

#\ run\ every\ two\ hours\ at\ the\ top\ of\ the\ hour
0\ */2\ *\ *\ *\ date

#\ run\ every\ two\ hours\ between\ 11\ pm\ and\ 7\ am,\ and\ again\ at\ 8\ am
0\ 23-7/2,8\ *\ *\ *\ date

#\ run\ at\ 4:00\ am\ on\ January\ 1st
0\ 4\ 1\ jan\ *\ date

#\ run\ every\ day\ at\ 11\ am,\ appending\ all\ output\ to\ a\ file
0\ 11\ *\ *\ *\ date\ >>\ /var/log/date-output\ 2>&1
\f[]
.fi
.PP
To request the last Monday, etc.
in a month, ask for the \[lq]5th\[rq] one.
This will always match the last Monday, etc., even if there are
only four Mondays in the month:
.IP
.nf
\f[C]
#\ run\ at\ 11\ am\ on\ the\ first\ and\ last\ Mon,\ Tue,\ Wed\ of\ each\ month
0\ 11\ 1,5\ *\ mon-wed\ date
\f[]
.fi
.PP
When the fourth Monday in a month is the last, it will match
against both the \[lq]4th\[rq] and the \[lq]5th\[rq] (it will only
run once if both are specified).
.PP
The following formats are also recognized:
.IP
.nf
\f[C]
#\ schedule\ this\ job\ only\ once,\ when\ crond\ starts\ up
\@reboot\ date

#\ schedule\ this\ job\ whenever\ crond\ is\ running,\ and\ sees\ that\ at\ least\ one
#\ hour\ has\ elapsed\ since\ it\ last\ ran
\@hourly\ ID=job1\ date
\f[]
.fi
.PP
The formats \@hourly, \@daily, \@weekly, \@monthly, and \@yearly
need to update timestamp files when their jobs have been run.
The timestamp files are saved as
/var/spool/cron/cronstamps/user.jobname.
So for all of these formats, the cron command needs a jobname,
given by prefixing the command with \f[C]ID=jobname\f[].
(This syntax was chosen to maximize the chance that our crontab
files will be readable by other cron daemons as well.
They might just interpret the ID=jobname as a command-line
environment variable assignment.)
.PP
There's also this esoteric option, whose usefulness will be
explained later:
.IP
.nf
\f[C]
#\ don\[aq]t\ ever\ schedule\ this\ job\ on\ its\ own;\ only\ run\ it\ when\ it\[aq]s\ triggered
#\ as\ a\ "dependency"\ of\ another\ job\ (see\ below),\ or\ when\ the\ user\ explicitly
#\ requests\ it\ through\ the\ "cron.update"\ file\ (see\ crond(8))
\@noauto\ ID=namedjob\ date
\f[]
.fi
.PP
There's also a format available for finer-grained control of
frequencies:
.IP
.nf
\f[C]
#\ run\ whenever\ it\[aq]s\ between\ 2-4\ am,\ and\ at\ least\ one\ day\ (1d)
#\ has\ elapsed\ since\ this\ job\ ran
*\ 2-4\ *\ *\ *\ ID=job2\ FREQ=1d\ date

#\ as\ before,\ but\ re-try\ every\ 10\ minutes\ (10m)\ if\ my_command
#\ exits\ with\ code\ 11\ (EAGAIN)
*\ 2-4\ *\ *\ *\ ID=job3\ FREQ=1d/10m\ my_command
\f[]
.fi
.PP
These formats also update timestamp files, and so also require
their jobs to be assigned IDs.
.PP
Notice the technique used in the second example: jobs can exit with
code 11 to indicate they lacked the resources to run (for example,
no network was available), and so should be tried again after a
brief delay.
This works for jobs using either \@freq or FREQ=\&... formats; but
the FREQ=\&.../10m syntax is the only way to customize the length
of the delay before re-trying.
.PP
Jobs can be made to \[lq]depend\[rq] on, or wait until AFTER other
jobs have successfully completed.
Consider the following crontab:
.IP
.nf
\f[C]
*\ *\ *\ *\ *\ ID=job4\ FREQ=1d\ first_command
*\ *\ *\ *\ *\ ID=job5\ FREQ=1h\ AFTER=job4/30m\ second_command
\f[]
.fi
.PP
Here, whenever job5 is up to be run, if job4 is scheduled to run
within the next 30 minutes (30m), job5 will first wait for it to
successfully complete.
.PP
(What if job4 doesn't successfully complete? If job4 returns with
exit code EAGAIN, job5 will continue to wait until job4 is
retried\[em]even if that won't be within the hour.
If job4 returns with any other non-zero exit code, job5 will be
removed from the queue without running.)
.PP
Jobs can be told to wait for multiple other jobs, as follows:
.IP
.nf
\f[C]
10\ *\ *\ *\ *\ ID=job6\ AFTER=job4/1h,job7\ third_command
\f[]
.fi
.PP
The waiting job6 doesn't care what order job4 and job7 complete in.
If job6 comes up to be re-scheduled (an hour later) while an
earlier instance is still waiting, only a single instance of job6
will remain in the queue.
It will have all of its \[lq]waiting flags\[rq] reset: so each of
job7 and job4 (supposing again that job4 would run within the next
1h) will again have to complete before job6 will run.
.PP
If a job waits on a \@reboot or \@noauto job, the target job being
waited on will also be scheduled to run.
This technique can be used to have a common job scheduled as
\@noauto that several other jobs depend on (and so call as a
subroutine).
.PP
The command portion of a cron job is run with
\f[C]/bin/sh\ -c\ ...\f[] and may therefore contain any valid
Bourne shell command.
A common practice is to prefix your command with \f[B]exec\f[] to
keep the process table uncluttered.
It is also common to redirect job output to a file or to /dev/null.
If you do not, and the command generates output on stdout or
stderr, that output will be mailed to the local user whose crontab
the job comes from.
If you have crontabs for special users, such as uucp, who can't
receive local mail, you may want to create mail aliases for them or
adjust this behavior.
(See crond(8) for details how to adjust it.)
.PP
Whenever jobs return an exit code that's neither 0 nor 11 (EAGAIN),
that event will be logged, regardless of whether any stdout or
stderr is generated.
The job's timestamp will also be updated, and it won't be run again
until it would next be normally scheduled.
Any jobs waiting on the failed job will be canceled; they won't be
run until they're next scheduled.
.SH TODO
.PP
Ought to be able to have several crontab files for any given user,
as an organizational tool.
.SH SEE ALSO
.PP
\f[B]crond\f[](8)
.SH AUTHORS
.PP
Matthew Dillon (dillon\@apollo.backplane.com): original
developer
.PD 0
.P
.PD
Jim Pryor (profjim\@jimpryor.net): current
developer