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