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