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