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 October 31, 2016
  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 and files in
  56 .Pa /etc/cron.d
  57 and
  58 .Pa /usr/local/etc/cron.d
  59 which are in a different format (see
  60 .Xr crontab 5 ) .
  61 .Pp
  62 The
  63 .Nm
  64 utility
  65 then wakes up every minute, examining all stored crontabs, checking each
  66 command to see if it should be run in the current minute.
  67 Before running a command from a per-account crontab file,
  68 .Nm
  69 checks the status of the account with
  70 .Xr pam 3
  71 and skips the command if the account is unavailable,
  72 e.g., locked out or expired.
  73 Commands from
  74 .Pa /etc/crontab
  75 bypass this check.
  76 When executing
  77 commands, any output is mailed to the owner of the crontab (or to the user
  78 named in the
  79 .Ev MAILTO
  80 environment variable in the crontab, if such exists).
  81 .Pp
  82 Additionally,
  83 .Nm
  84 checks each minute to see if its spool directory's modification time (or
  85 the modification time on
  86 .Pa /etc/crontab )
  87 has changed, and if it has,
  88 .Nm
  89 will then examine the modification time on all crontabs and reload those
  90 which have changed.
  91 Thus
  92 .Nm
  93 need not be restarted whenever a crontab file is modified.
  94 Note that the
  95 .Xr crontab 1
  96 command updates the modification time of the spool directory whenever it
  97 changes a crontab.
  98 .Pp
  99 Available options:
 100 .Bl -tag -width indent
 101 .It Fl j Ar jitter
 102 Enable time jitter.
 103 Prior to executing commands,
 104 .Nm
 105 will sleep a random number of seconds in the range from 0 to
 106 .Ar jitter .
 107 This will not affect superuser jobs (see
 108 .Fl J ) .
 109 A value for
 110 .Ar jitter
 111 must be between 0 and 60 inclusive.
 112 Default is 0, which effectively disables time jitter.
 113 .Pp
 114 This option can help to smooth down system load spikes during
 115 moments when a lot of jobs are likely to start at once, e.g.,
 116 at the beginning of the first minute of each hour.
 117 .It Fl J Ar rootjitter
 118 Enable time jitter for superuser jobs.
 119 The same as
 120 .Fl j
 121 except that it will affect jobs run by the superuser only.
 122 .It Fl m Ar mailto
 123 Overrides the default recipient for
 124 .Nm
 125 mail.
 126 Each
 127 .Xr crontab 5
 128 without
 129 .Ev MAILTO
 130 explicitly set will send mail to the
 131 .Ar mailto
 132 mailbox.
 133 Sending mail will be disabled by default if
 134 .Ar mailto
 135 set to a null string, usually specified in a shell as
 136 .Li ''
 137 or
 138 .Li \*q\*q .
 139 .It Fl s
 140 Enable special handling of situations when the GMT offset of the local
 141 timezone changes, such as the switches between the standard time and
 142 daylight saving time.
 143 .Pp
 144 The jobs run during the GMT offset changes time as
 145 intuitively expected.
 146 If a job falls into a time interval that disappears
 147 (for example, during the switch from
 148 standard time) to daylight saving time or is
 149 duplicated (for example, during the reverse switch), then it is handled
 150 in one of two ways:
 151 .Pp
 152 The first case is for the jobs that run every at hour of a time interval
 153 overlapping with the disappearing or duplicated interval.
 154 In other words, if the job had run within one hour before the GMT offset change
 155 (and cron was not restarted nor the
 156 .Xr crontab 5
 157 changed after that)
 158 or would run after the change at the next hour.
 159 They work as always, skip the skipped time or run in the added
 160 time as usual.
 161 .Pp
 162 The second case is for the jobs that run less frequently.
 163 They are executed exactly once, they are not skipped nor
 164 executed twice (unless cron is restarted or the user's
 165 .Xr crontab 5
 166 is changed during such a time interval).
 167 If an interval disappears
 168 due to the GMT offset change, such jobs are
 169 executed at the same absolute point of time as they would be in the
 170 old time zone.
 171 For example, if exactly one hour disappears, this
 172 point would be during the next hour at the first minute that is
 173 specified for them in
 174 .Xr crontab 5 .
 175 .It Fl o
 176 Disable the special handling of situations when the GMT offset of the local
 177 timezone changes, to be compatible with the old (default) behavior.
 178 If both options
 179 .Fl o
 180 and
 181 .Fl s
 182 are specified, the option specified last wins.
 183 .It Fl x Ar debugflag Ns Op , Ns Ar ...
 184 Enable writing of debugging information to standard output.
 185 One or more of the following comma separated
 186 .Ar debugflag
 187 identifiers must be specified:
 188 .Pp
 189 .Bl -tag -width ".Cm proc" -compact
 190 .It Cm bit
 191 currently not used
 192 .It Cm ext
 193 make the other debug flags more verbose
 194 .It Cm load
 195 be verbose when loading crontab files
 196 .It Cm misc
 197 be verbose about miscellaneous one-off events
 198 .It Cm pars
 199 be verbose about parsing individual crontab lines
 200 .It Cm proc
 201 be verbose about the state of the process, including all of its offspring
 202 .It Cm sch
 203 be verbose when iterating through the scheduling algorithms
 204 .It Cm test
 205 trace through the execution, but do not perform any actions
 206 .El
 207 .El
 208 .Sh FILES
 209 .Bl -tag -width /etc/pam.d/cron -compact
 210 .It Pa /etc/crontab
 211 System crontab file
 212 .It Pa /etc/pam.d/cron
 213 .Xr pam.conf 5
 214 configuration file for
 215 .Nm
 216 .It Pa /var/cron/tabs
 217 Directory for personal crontab files
 218 .El
 219 .Sh SEE ALSO
 220 .Xr crontab 1 ,
 221 .Xr pam 3 ,
 222 .Xr crontab 5 ,
 223 .Xr pam.conf 5
 224 .Sh AUTHORS
 225 .An Paul Vixie Aq paul@vix.com