usr.sbin/cron/cron/cron.8

   1 .\"/* Copyright 1988,1990,1993 by Paul Vixie
   2 .\" * All rights reserved
   3 .\" *
   4 .\" * Distribute freely, except: don't remove my name from the source or
   5 .\" * documentation (don't take credit for my work), mark your changes (don't
   6 .\" * get me blamed for your possible bugs), don't alter or remove this
   7 .\" * notice.  May be sold if buildable source is provided to buyer.  No
   8 .\" * warrantee of any kind, express or implied, is included with this
   9 .\" * software; use at your own risk, responsibility for damages (if any) to
  10 .\" * anyone resulting from the use of this software rests entirely with the
  11 .\" * user.
  12 .\" *
  13 .\" * Send bug reports, bug fixes, enhancements, requests, flames, etc., and
  14 .\" * I'll try to keep a version up to date.  I can be reached as follows:
  15 .\" * Paul Vixie          <paul@vix.com>          uunet!decwrl!vixie!paul
  16 .\" */
  17 .\"
  18 .\" $FreeBSD$
  19 .\"
  20 .Dd July 27, 2008
  21 .Dt CRON 8
  22 .Os
  23 .Sh NAME
  24 .Nm cron
  25 .Nd daemon to execute scheduled commands (Vixie Cron)
  26 .Sh SYNOPSIS
  27 .Nm
  28 .Op Fl j Ar jitter
  29 .Op Fl J Ar rootjitter
  30 .Op Fl m Ar mailto
  31 .Op Fl s
  32 .Op Fl o
  33 .Op Fl x Ar debugflag Ns Op , Ns Ar ...
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 utility should be started from
  38 .Pa /etc/rc
  39 or
  40 .Pa /etc/rc.local .
  41 It will return immediately,
  42 so you do not need to start it with '&'.
  43 .Pp
  44 The
  45 .Nm
  46 utility searches
  47 .Pa /var/cron/tabs
  48 for crontab files which are named after accounts in
  49 .Pa /etc/passwd ;
  50 crontabs found are loaded into memory.
  51 The
  52 .Nm
  53 utility also searches for
  54 .Pa /etc/crontab
  55 which is in a different format (see
  56 .Xr crontab 5 ) .
  57 The
  58 .Nm
  59 utility
  60 then wakes up every minute, examining all stored crontabs, checking each
  61 command to see if it should be run in the current minute.
  62 When executing
  63 commands, any output is mailed to the owner of the crontab (or to the user
  64 named in the
  65 .Ev MAILTO
  66 environment variable in the crontab, if such exists).
  67 .Pp
  68 Additionally,
  69 .Nm
  70 checks each minute to see if its spool directory's modification time (or
  71 the modification time on
  72 .Pa /etc/crontab )
  73 has changed, and if it has,
  74 .Nm
  75 will then examine the modification time on all crontabs and reload those
  76 which have changed.
  77 Thus
  78 .Nm
  79 need not be restarted whenever a crontab file is modified.
  80 Note that the
  81 .Xr crontab 1
  82 command updates the modification time of the spool directory whenever it
  83 changes a crontab.
  84 .Pp
  85 Available options:
  86 .Bl -tag -width indent
  87 .It Fl j Ar jitter
  88 Enable time jitter.
  89 Prior to executing commands,
  90 .Nm
  91 will sleep a random number of seconds in the range from 0 to
  92 .Ar jitter .
  93 This will not affect superuser jobs (see
  94 .Fl J ) .
  95 A value for
  96 .Ar jitter
  97 must be between 0 and 60 inclusive.
  98 Default is 0, which effectively disables time jitter.
  99 .Pp
 100 This option can help to smooth down system load spikes during
 101 moments when a lot of jobs are likely to start at once, e.g.,
 102 at the beginning of the first minute of each hour.
 103 .It Fl J Ar rootjitter
 104 Enable time jitter for superuser jobs.
 105 The same as
 106 .Fl j
 107 except that it will affect jobs run by the superuser only.
 108 .It Fl m Ar mailto
 109 Overrides the default recipient for
 110 .Nm
 111 mail.
 112 Each
 113 .Xr crontab 5
 114 without
 115 .Ev MAILTO
 116 explicitly set will send mail to the
 117 .Ar mailto
 118 mailbox.
 119 Sending mail will be disabled by default if
 120 .Ar mailto
 121 set to a null string, usually specified in a shell as
 122 .Li ''
 123 or
 124 .Li \*q\*q .
 125 .It Fl s
 126 Enable special handling of situations when the GMT offset of the local
 127 timezone changes, such as the switches between the standard time and
 128 daylight saving time.
 129 .Pp
 130 The jobs run during the GMT offset changes time as
 131 intuitively expected.
 132 If a job falls into a time interval that disappears
 133 (for example, during the switch from
 134 standard time) to daylight saving time or is
 135 duplicated (for example, during the reverse switch), then it is handled
 136 in one of two ways:
 137 .Pp
 138 The first case is for the jobs that run every at hour of a time interval
 139 overlapping with the disappearing or duplicated interval.
 140 In other words, if the job had run within one hour before the GMT offset change
 141 (and cron was not restarted nor the
 142 .Xr crontab 5
 143 changed after that)
 144 or would run after the change at the next hour.
 145 They work as always, skip the skipped time or run in the added
 146 time as usual.
 147 .Pp
 148 The second case is for the jobs that run less frequently.
 149 They are executed exactly once, they are not skipped nor
 150 executed twice (unless cron is restarted or the user's
 151 .Xr crontab 5
 152 is changed during such a time interval).
 153 If an interval disappears
 154 due to the GMT offset change, such jobs are
 155 executed at the same absolute point of time as they would be in the
 156 old time zone.
 157 For example, if exactly one hour disappears, this
 158 point would be during the next hour at the first minute that is
 159 specified for them in
 160 .Xr crontab 5 .
 161 .It Fl o
 162 Disable the special handling of situations when the GMT offset of the local
 163 timezone changes, to be compatible with the old (default) behavior.
 164 If both options
 165 .Fl o
 166 and
 167 .Fl s
 168 are specified, the option specified last wins.
 169 .It Fl x Ar debugflag Ns Op , Ns Ar ...
 170 Enable writing of debugging information to standard output.
 171 One or more of the following comma separated
 172 .Ar debugflag
 173 identifiers must be specified:
 174 .Pp
 175 .Bl -tag -width ".Cm proc" -compact
 176 .It Cm bit
 177 currently not used
 178 .It Cm ext
 179 make the other debug flags more verbose
 180 .It Cm load
 181 be verbose when loading crontab files
 182 .It Cm misc
 183 be verbose about miscellaneous one-off events
 184 .It Cm pars
 185 be verbose about parsing individual crontab lines
 186 .It Cm proc
 187 be verbose about the state of the process, including all of its offspring
 188 .It Cm sch
 189 be verbose when iterating through the scheduling algorithms
 190 .It Cm test
 191 trace through the execution, but do not perform any actions
 192 .El
 193 .El
 194 .Sh SEE ALSO
 195 .Xr crontab 1 ,
 196 .Xr crontab 5
 197 .Sh AUTHORS
 198 .An Paul Vixie Aq paul@vix.com