crontab.markdown

   1 % CRONTAB(1)
   2 %
   3 % 1 May 2011
   4
   5 NAME
   6 ====
   7 crontab - manipulate per-user crontabs (dillon's lightweight cron daemon)
   8
   9 SYNOPSIS
  10 ========
  11 **crontab file [-u user]** - replace crontab from file
  12
  13 **crontab - [-u user]** - replace crontab from stdin
  14
  15 **crontab -l [-u user]** - list crontab for user
  16
  17 **crontab -e [-u user]** - edit crontab for user
  18
  19 **crontab -d [-u user]** - delete crontab for user
  20
  21 **crontab -c dir** - specify crontab directory
  22
  23 DESCRIPTION
  24 ===========
  25
  26 **crontab** manipulates the per-user crontabs.
  27
  28 Generally the -e option is used to edit your crontab. **crontab** will use
  29 the editor specified by your EDITOR or VISUAL environment
  30 variable (or /usr/bin/vi) to edit the crontab.
  31
  32 **crontab** doesn't provide the kinds of protections that programs like **visudo** do
  33 against syntax errors and simultaneous edits. Errors won't be detected until
  34 **crond** reads the crontab file. What **crontab** does is provide a mechanism for
  35 users who may not themselves have write privileges to the crontab folder
  36 to nonetheless install or edit their crontabs. It also notifies a running crond
  37 daemon of any changes to these files.
  38
  39 Only users who belong to the same group as the **crontab** binary will be able
  40 to install or edit crontabs. However it'll be possible for the superuser to
  41 install crontabs even for users who don't have the privileges to install them
  42 themselves. (Even for users who don't have a login shell.) Only the superuser may use
  43 the -u or -c switches to specify a different user and/or crontab directory.
  44
  45 The superuser also has his or her own per-user crontab, saved as
  46 /var/spool/cron/crontabs/root.
  47
  48
  49 Unlike other cron daemons, this crond/crontab package doesn't try to do
  50 everything under the sun. It doesn't try to keep track of user's preferred
  51 shells; that would require special-casing users with no login shell. Instead,
  52 it just runs all commands using `/bin/sh`. (Commands can of course be script
  53 files written in any shell you like.)
  54
  55 Nor does it do any special environment handling. A shell script is
  56 better-suited to doing that than a cron daemon. This cron daemon sets up only
  57 four environment variables: USER, LOGNAME, HOME, and SHELL.
  58
  59
  60 Our crontab format is roughly similar to that used by vixiecron. Individual
  61 fields may contain a time, a time range, a time range with a skip factor, a
  62 symbolic range for the day of week and month in year, and additional subranges
  63 delimited with commas. Blank lines in the crontab or lines that begin with a
  64 hash (#) 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.
  66
  67 Some examples:
  68
  69         # MIN HOUR DAY MONTH DAYOFWEEK  COMMAND
  70         # run `date` at 6:10 am every day
  71         10 6 * * * date
  72
  73         # run every two hours at the top of the hour
  74         0 */2 * * * date
  75
  76         # run every two hours between 11 pm and 7 am, and again at 8 am
  77         0 23-7/2,8 * * * date
  78
  79         # run at 4:00 am on January 1st
  80         0 4 1 jan * date
  81
  82         # run every day at 11 am, appending all output to a file
  83         0 11 * * * date >> /var/log/date-output 2>&1
  84
  85 To request the last Monday, etc. in a month, ask for the "5th" one. This will always match the last Monday, etc., even if there are only four Mondays in the month:
  86
  87         # run at 11 am on the first and last Mon, Tue, Wed of each month
  88         0 11 1,5 * mon-wed date
  89
  90 When the fourth Monday in a month is the last, it will match against both the "4th" and the "5th" (it will only run once if both are specified).
  91
  92 The following formats are also recognized:
  93
  94         # schedule this job only once, when crond starts up
  95         @reboot date
  96
  97         # schedule this job whenever crond is running, and sees that at least one
  98         # hour has elapsed since it last ran
  99         @hourly ID=job1 date
 100
 101 The formats @hourly, @daily, @weekly, @monthly, and @yearly need to update
 102 timestamp files when their jobs have been run. The timestamp files are saved as
 103 /var/spool/cron/cronstamps/user.jobname. So for all of these formats, the cron
 104 command needs a jobname, given by prefixing the command with `ID=jobname`.
 105 (This syntax was chosen to maximize the chance that our crontab files will be
 106 readable by other cron daemons as well. They might just interpret the
 107 ID=jobname as a command-line environment variable assignment.)
 108
 109 There's also this esoteric option, whose usefulness will be explained later:
 110
 111         # don't ever schedule this job on its own; only run it when it's triggered
 112         # as a "dependency" of another job (see below), or when the user explicitly
 113         # requests it through the "cron.update" file (see crond(8))
 114         @noauto ID=namedjob date
 115
 116 There's also a format available for finer-grained control of frequencies:
 117
 118         # run whenever it's between 2-4 am, and at least one day (1d)
 119         # has elapsed since this job ran
 120         * 2-4 * * * ID=job2 FREQ=1d date
 121
 122         # as before, but re-try every 10 minutes (10m) if my_command
 123         # exits with code 11 (EAGAIN)
 124         * 2-4 * * * ID=job3 FREQ=1d/10m my_command
 125
 126 These formats also update timestamp files, and so also require their jobs to be assigned
 127 IDs.
 128
 129 Notice the technique used in the second example: jobs can exit with code 11 to
 130 indicate they lacked the resources to run (for example, no network was
 131 available), and so should be tried again after a brief delay. This works for
 132 jobs using either @freq or FREQ=... formats; but the FREQ=.../10m syntax is the
 133 only way to customize the length of the delay before re-trying.
 134
 135 Jobs can be made to "depend" on, or wait until AFTER other jobs have
 136 successfully completed. Consider the following crontab:
 137
 138         * * * * * ID=job4 FREQ=1d first_command
 139         * * * * * ID=job5 FREQ=1h AFTER=job4/30m second_command
 140
 141 Here, whenever job5 is up to be run, if job4 is scheduled to run within the
 142 next 30 minutes (30m), job5 will first wait for it to successfully complete.
 143
 144 (What if job4 doesn't successfully complete? If job4 returns with exit code
 145 EAGAIN, job5 will continue to wait until job4 is retried---even if that won't
 146 be within the hour. If job4 returns with any other non-zero exit code, job5
 147 will be removed from the queue without running.)
 148
 149 Jobs can be told to wait for multiple other jobs, as follows:
 150
 151         10 * * * * ID=job6 AFTER=job4/1h,job7 third_command
 152
 153 The waiting job6 doesn't care what order job4 and job7 complete in. If job6 comes
 154 up to be re-scheduled (an hour later) while an earlier instance is still waiting, only a
 155 single instance of job6 will remain in the queue. It will have all of its
 156 "waiting flags" reset: so each of job7 and job4 (supposing again that job4 would run within the
 157 next 1h) will again have to complete before job6 will run.
 158
 159 If a job waits on a @reboot or @noauto job, the target job being waited on will
 160 also be scheduled to run. This technique can be used to have a common job scheduled as @noauto
 161 that several other jobs depend on (and so call as a subroutine).
 162
 163 The command portion of a cron job is run with `/bin/sh -c ...` and may
 164 therefore contain any valid Bourne shell command. A common practice is to
 165 prefix your command with **exec** to keep the process table uncluttered. It is
 166 also common to redirect job output to a file or to /dev/null. If you do not,
 167 and the command generates output on stdout or stderr, that output will be
 168 mailed to the local user whose crontab the job comes from. If you have crontabs
 169 for special users, such as uucp, who can't receive local mail, you may want to
 170 create mail aliases for them or adjust this behavior. (See crond(8) for details
 171 how to adjust it.)
 172
 173 Whenever jobs return an exit code that's neither 0 nor 11 (EAGAIN), that event
 174 will be logged, regardless of whether any stdout or stderr is generated. The job's
 175 timestamp will also be updated, and it won't be run again until it would next
 176 be normally scheduled. Any jobs waiting on the failed job will be canceled; they
 177 won't be run until they're next scheduled.
 178
 179
 180 TODO
 181 ====
 182 Ought to be able to have several crontab files for any given user, as
 183 an organizational tool.
 184
 185
 186 SEE ALSO
 187 ========
 188 **crond**(8)
 189
 190 AUTHORS
 191 =======
 192 Matthew Dillon (dillon@apollo.backplane.com): original developer
 193 Jim Pryor (profjim@jimpryor.net): current developer