tweak log levels & messages
[yacron.git] / crontab.1
blob05f40df004d80e2de84a84e8ac1f7656c86d272e
1 .\" Copyright 1994 Matthew Dillon (dillon@apollo.backplane.com)
2 .\" Copyright 2009 James Pryor <profjim@jimpryor.net>
3 .\" May be distributed under the GNU General Public License
4 .TH CRONTAB 1 "21 Aug 2009"
5 .SH NAME
6 crontab \- manipulate per-user crontabs (Yet Another Cron)
7 .SH SYNOPSIS
8 .B crontab file [-u user]
9 \- replace crontab from file
11 .B crontab - [-u user]
12 \- replace crontab from stdin
14 .B crontab -l [user]
15 \- list crontab for user
17 .B crontab -e [user]
18 \- edit crontab for user
20 .B crontab -d [user]
21 \- delete crontab for user
23 .B crontab -c dir
24 \- specify crontab directory
25 .SH DESCRIPTION
26 .B crontab
27 manipulates the crontab for a particular user.  Only the superuser may
28 specify a different user and/or crontab directory.  Generally the -e
29 option is used to edit your crontab.
30 .B crontab
31 will use /usr/bin/vi or
32 the editor specified by your EDITOR or VISUAL environment variable to edit the
33 crontab.
34 .PP
35 Unlike other crond/crontabs, this crontab does not try to do everything
36 under the sun.  Frankly, a shell script is much more able to manipulate
37 the environment then cron and I see no particular reason to use the
38 user's shell (from his password entry) to run cron commands when this
39 requires special casing of non-user crontabs, such as those for UUCP.
40 When a crontab command is run, this crontab runs it with /bin/sh and
41 sets up only three environment variables: USER, HOME, and SHELL.
42 .PP
43 .B crond
44 automatically detects changes in the time.  Reverse-indexed
45 time changes less then an hour old will NOT re-run crontab commands
46 already issued in the recovered period. Forward-indexed changes less
47 then an hour
48 into the future will issue missed commands exactly once.  Changes
49 greater then an hour into the past or future cause
50 .B crond
51 to resynchronize
52 and not issue missed commands.
53 Commands are not reissued if the previously
54 issued command is still running.  For example, if you have a crontab
55 command 'sleep 70' that you wish to run once a minute, cron will only be
56 able to issue the command once every two minutes.  If you do not like
57 this feature, you can run your commands in the background with an '&'.
58 .PP
59 The crontab format is roughly similar to that used by vixiecron.
60 Individual fields may contain a time, a
61 time range, a time range with a skip factor, a symbolic range for the
62 day of week and month in year, and additional subranges delimited with
63 commas.  Blank lines in the crontab or lines that begin with a hash (#)
64 are ignored.  If you specify both a day in the month and a day of week,
65 it will be interpreted as the nth such day in the month.
67 .sp 1
68 .br
69 # MIN HOUR DAY MONTH DAYOFWEEK   COMMAND
70 .br
71 # at 6:10 a.m. every day
72 .br
73 10 6 * * * date
75 .br
76 # every two hours at the top of the hour
77 .br
78 0 */2 * * * date
80 .br
81 # every two hours from 11p.m. to 7a.m., and at 8a.m.
82 .br
83 0 23-7/2,8 * * * date
85 .br
86 # at 11:00 a.m. on the first and last Mon, Tue, Wed of each month
87 .br
88 # if the fourth Monday in a month is the last, it will
89 .br
90 # match against both "4th" and "5th"
91 .br
92 0 11 1,5 * mon-wed date
94 .br
95 # 4:00 a.m. on january 1st
96 .br
97 0 4 1 jan * date
99 .br
100 # once an hour, all output appended to log file
102 0 4 1 jan * date >>/var/log/messages 2>&1
104 The following formats are also recognized:
107 # schedule only once, when crond starts up
109 @reboot                 date
112 # never schedule regularly, but only when triggered by other
114 # jobs, or through the "cron.update" file
116 @noauto                 date
119 # schedule whenever at least one hour has elapsed since
121 # it last ran successfully
123 @hourly                 ID=job1 date
125 The options @hourly, @daily, @weekly, @monthly, and @yearly update timestamp
126 files when their job completes successfully (exits with code zero). The
127 timestamp files are saved as /var/spool/cron/timestamps/user.jobname. (So for
128 all of these options, the command must be prefixed with an ID=<jobname>.)
132 Frequencies can also be specified as follows:
135 # run whenever it's between 2-4 am, and at least one day
137 # has elapsed since it last ran successfully
139 * 2-4 * * *             ID=job2 FREQ=1d date
142 # as before, but re-try every 10 minutes if my_command
144 # exits with status EAGAIN (code 11)
146 * 2-4 * * *             ID=job3 FREQ=1d/10m my_command
149 These options also update timestamp files, and require the jobs to be assigned
150 an ID.
154 Jobs can be told to wait for the successful completion of other jobs. With the following crontab:
157 * * * * *               ID=job5 FREQ=1d first_command
159 * * * * *               ID=job6 FREQ=1h AFTER=job5/1h second_command
161 whenever job6 is about to be scheduled, if job5 would be scheduled within the
162 next hour, job6 will first wait for it to successfully complete. If job5
163 returns with exit code EAGAIN, job6 will continue waiting (even if job5 will
164 not be retried again within an hour). If job5 returns with any other non-zero
165 exit code, job6 will be removed from the queue without running.
167 Jobs can be told to wait for multiple other jobs, as follows:
170 10 * * * *              ID=job7 AFTER=job5/1h,job4 third_command
173 The waiting job doesn't care what order job4 and job5 complete in. If job7 is
174 re-scheduled (an hour later) while an earlier instance is still waiting, only a
175 single instance of the job will remain in the queue. It will have all of its
176 "waiting flags" reset: so each of job4 and job5 (if job5 would run within the
177 next hour) will again have to complete before job7 will run.
180 If a job waits on a @reboot or @noauto job, the target job being waited on will
181 also be scheduled to run.
185 The command portion of the line is run with
186 .B /bin/sh \-c <command>
187 and may therefore contain any valid bourne shell command.  A common
188 practice is to run your command with
189 .B exec
190 to keep the process table uncluttered.  It is also common to redirect
191 output to a log file.  If you do not, and the command generates output
192 on stdout or stderr, the result will be mailed to the user in question.
193 If you use this mechanism for special users, such as UUCP, you may want
194 to create an alias for the user to direct the mail to someone else, such
195 as root or postmaster.
197 Internally, this cron uses a quick indexing system to reduce CPU overhead
198 when looking for commands to execute.  Several hundred crontabs with
199 several thousand entries can be handled without using noticable CPU
200 resources.
201 .SH BUGS
202 Ought to be able to have several crontab files for any given user, as
203 an organizational tool.
204 .SH AUTHORS
205 Matthew Dillon (dillon@apollo.backplane.com)
207 James Pryor (profjim@jimpryor.net)