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 December 20, 1993
  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 s
  31 .Op Fl o
  32 .Op Fl x Ar debugflag Ns Op , Ns Ar ...
  33 .Sh DESCRIPTION
  34 The
  35 .Nm
  36 utility should be started from
  37 .Pa /etc/rc
  38 or
  39 .Pa /etc/rc.local .
  40 It will return immediately,
  41 so you don't need to start it with '&'.
  42 .Pp
  43 The
  44 .Nm
  45 utility searches
  46 .Pa /var/cron/tabs
  47 for crontab files which are named after accounts in
  48 .Pa /etc/passwd ;
  49 crontabs found are loaded into memory.
  50 The
  51 .Nm
  52 utility also searches for
  53 .Pa /etc/crontab
  54 which is in a different format (see
  55 .Xr crontab 5 ) .
  56 The
  57 .Nm
  58 utility
  59 then wakes up every minute, examining all stored crontabs, checking each
  60 command to see if it should be run in the current minute.
  61 When executing
  62 commands, any output is mailed to the owner of the crontab (or to the user
  63 named in the
  64 .Ev MAILTO
  65 environment variable in the crontab, if such exists).
  66 .Pp
  67 Additionally,
  68 .Nm
  69 checks each minute to see if its spool directory's modification time (or
  70 the modification time on
  71 .Pa /etc/crontab )
  72 has changed, and if it has,
  73 .Nm
  74 will then examine the modification time on all crontabs and reload those
  75 which have changed.
  76 Thus
  77 .Nm
  78 need not be restarted whenever a crontab file is modified.
  79 Note that the
  80 .Xr crontab 1
  81 command updates the modification time of the spool directory whenever it
  82 changes a crontab.
  83 .Pp
  84 Available options:
  85 .Bl -tag -width indent
  86 .It Fl j Ar jitter
  87 Enable time jitter.
  88 Prior to executing commands,
  89 .Nm
  90 will sleep a random number of seconds in the range from 0 to
  91 .Ar jitter .
  92 This won't affect superuser jobs (see
  93 .Fl J ) .
  94 A value for
  95 .Ar jitter
  96 must be between 0 and 60 inclusive.
  97 Default is 0, which effectively disables time jitter.
  98 .Pp
  99 This option can help to smooth down system load spikes during
 100 moments when a lot of jobs are likely to start at once, e.g.,
 101 at the beginning of the first minute of each hour.
 102 .It Fl J Ar rootjitter
 103 Enable time jitter for superuser jobs.
 104 The same as
 105 .Fl j
 106 except that it will affect jobs run by the superuser only.
 107 .It Fl s
 108 Enable special handling of situations when the GMT offset of the local
 109 timezone changes, such as the switches between the standard time and
 110 daylight saving time.
 111 .Pp
 112 The jobs run during the GMT offset changes time as
 113 intuitively expected.
 114 If a job falls into a time interval that disappears
 115 (for example, during the switch from
 116 standard time) to daylight saving time or is
 117 duplicated (for example, during the reverse switch), then it's handled
 118 in one of two ways:
 119 .Pp
 120 The first case is for the jobs that run every at hour of a time interval
 121 overlapping with the disappearing or duplicated interval.
 122 In other words, if the job had run within one hour before the GMT offset change
 123 (and cron was not restarted nor the
 124 .Xr crontab 5
 125 changed after that)
 126 or would run after the change at the next hour.
 127 They work as always, skip the skipped time or run in the added
 128 time as usual.
 129 .Pp
 130 The second case is for the jobs that run less frequently.
 131 They are executed exactly once, they are not skipped nor
 132 executed twice (unless cron is restarted or the user's
 133 .Xr crontab 5
 134 is changed during such a time interval).
 135 If an interval disappears
 136 due to the GMT offset change, such jobs are
 137 executed at the same absolute point of time as they would be in the
 138 old time zone.
 139 For example, if exactly one hour disappears, this
 140 point would be during the next hour at the first minute that is
 141 specified for them in
 142 .Xr crontab 5 .
 143 .It Fl o
 144 Disable the special handling of situations when the GMT offset of the local
 145 timezone changes, to be compatible with the old (default) behavior.
 146 If both options
 147 .Fl o
 148 and
 149 .Fl s
 150 are specified, the option specified last wins.
 151 .It Fl x Ar debugflag Ns Op , Ns Ar ...
 152 Enable writing of debugging information to standard output.
 153 One or more of the following comma separated
 154 .Ar debugflag
 155 identifiers must be specified:
 156 .Pp
 157 .Bl -tag -width ".Cm proc" -compact
 158 .It Cm bit
 159 currently not used
 160 .It Cm ext
 161 make the other debug flags more verbose
 162 .It Cm load
 163 be verbose when loading crontab files
 164 .It Cm misc
 165 be verbose about miscellaneous one-off events
 166 .It Cm pars
 167 be verbose about parsing individual crontab lines
 168 .It Cm proc
 169 be verbose about the state of the process, including all of its offspring
 170 .It Cm sch
 171 be verbose when iterating through the scheduling algorithms
 172 .It Cm test
 173 trace through the execution, but do not perform any actions
 174 .El
 175 .El
 176 .Sh SEE ALSO
 177 .Xr crontab 1 ,
 178 .Xr crontab 5
 179 .Sh AUTHORS
 180 .An Paul Vixie Aq paul@vix.com