usr.sbin/periodic/periodic.8

   1 .\" Copyright (c) 1997 FreeBSD, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd August 30, 2007
  28 .Dt PERIODIC 8
  29 .Os
  30 .Sh NAME
  31 .Nm periodic
  32 .Nd run periodic system functions
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Ar directory ...
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 utility is intended to be called by
  40 .Xr cron 8
  41 to execute shell scripts
  42 located in the specified directory.
  43 .Pp
  44 One or more of the following arguments must be specified:
  45 .Bl -tag -width ".Pa monthly"
  46 .It Pa daily
  47 Perform the standard daily periodic executable run.
  48 This usually occurs early in the morning (local time).
  49 .It Pa weekly
  50 Perform the standard weekly periodic executable run.
  51 This usually occurs very early on Saturday mornings.
  52 .It Pa monthly
  53 Perform the standard monthly periodic executable run.
  54 This usually occurs on the first day of the month.
  55 .It Pa security
  56 Perform the standard daily security checks.
  57 This is usually spawned by the
  58 .Pa daily
  59 run.
  60 .It Ar path
  61 An arbitrary directory containing a set of executables to be run.
  62 .El
  63 .Pp
  64 If an argument is an absolute directory name it is used as is, otherwise
  65 it is searched for under
  66 .Pa /etc/periodic
  67 and any other directories specified by the
  68 .Va local_periodic
  69 setting in
  70 .Xr periodic.conf 5
  71 (see below).
  72 .Pp
  73 The
  74 .Nm
  75 utility will run each executable file in the directory or directories
  76 specified.
  77 If a file does not have the executable bit set, it is silently ignored.
  78 .Pp
  79 Each script is required to exit with one of the following values:
  80 .Bl -tag -width 4n
  81 .It 0
  82 The script has produced nothing notable in its output.
  83 The
  84 .Ao Ar basedir Ac Ns Va _show_success
  85 variable controls the masking of this output.
  86 .It 1
  87 The script has produced some notable information in its output.
  88 The
  89 .Ao Ar basedir Ac Ns Va _show_info
  90 variable controls the masking of this output.
  91 .It 2
  92 The script has produced some warnings due to invalid configuration settings.
  93 The
  94 .Ao Ar basedir Ac Ns Va _show_badconfig
  95 variable controls the masking of this output.
  96 .It >2
  97 The script has produced output that must not be masked.
  98 .El
  99 .Pp
 100 If the relevant variable (where
 101 .Aq Ar basedir
 102 is the base directory in which the script resides) is set to
 103 .Dq Li NO
 104 in
 105 .Pa periodic.conf ,
 106 .Nm
 107 will mask the script output.
 108 If the variable is not set to either
 109 .Dq Li YES
 110 or
 111 .Dq Li NO ,
 112 it will be given a default value as described in
 113 .Xr periodic.conf 5 .
 114 .Pp
 115 All remaining script output is delivered based on the value of the
 116 .Ao Ar basedir Ac Ns Va _output
 117 setting.
 118 .Pp
 119 If this is set to a path name (beginning with a
 120 .Ql /
 121 character), output is simply logged to that file.
 122 .Xr newsyslog 8
 123 knows about the files
 124 .Pa /var/log/daily.log , /var/log/weekly.log
 125 and
 126 .Pa /var/log/monthly.log ,
 127 and if they exist, it will rotate them at the appropriate times.
 128 These are therefore good values if you wish to log
 129 .Nm
 130 output.
 131 .Pp
 132 If the
 133 .Ao Ar basedir Ac Ns Va _output
 134 value does not begin with a
 135 .Ql /
 136 and is not empty, it is assumed to contain a list of email addresses, and
 137 the output is mailed to them.
 138 If
 139 .Ao Ar basedir Ac Ns Va _show_empty_output
 140 is set to
 141 .Dq Li NO ,
 142 then no mail will be sent if the output was empty.
 143 .Pp
 144 If
 145 .Ao Ar basedir Ac Ns Va _output
 146 is not set or is empty, output is sent to standard output.
 147 .Sh ENVIRONMENT
 148 The
 149 .Nm
 150 utility sets the
 151 .Ev PATH
 152 environment to include all standard system directories, but no additional
 153 directories, such as
 154 .Pa /usr/local/bin .
 155 If executables are added which depend upon other path components, each
 156 executable must be responsible for configuring its own appropriate environment.
 157 .Sh FILES
 158 .Bl -tag -width ".Pa /etc/defaults/periodic.conf"
 159 .It Pa /etc/crontab
 160 the
 161 .Nm
 162 utility is typically called via entries in the system default
 163 .Xr cron 8
 164 table
 165 .It Pa /etc/periodic
 166 the top level directory containing
 167 .Pa daily ,
 168 .Pa weekly ,
 169 and
 170 .Pa monthly
 171 subdirectories which contain standard system periodic executables
 172 .It Pa /etc/defaults/periodic.conf
 173 the
 174 .Pa periodic.conf
 175 system registry contains variables that control the behaviour of
 176 .Nm
 177 and the standard
 178 .Pa daily , weekly ,
 179 and
 180 .Pa monthly
 181 scripts
 182 .It Pa /etc/periodic.conf
 183 this file contains local overrides for the default
 184 .Nm
 185 configuration
 186 .El
 187 .Sh EXIT STATUS
 188 Exit status is 0 on success and 1 if the command fails.
 189 .Sh EXAMPLES
 190 The system crontab should have entries for
 191 .Nm
 192 similar to the following example:
 193 .Bd -literal -offset indent
 194 # do daily/weekly/monthly maintenance
 195 0      2       *       *       *       root    periodic daily
 196 0      3       *       *       6       root    periodic weekly
 197 0      5       1       *       *       root    periodic monthly
 198 .Ed
 199 .Pp
 200 The
 201 .Pa /etc/defaults/periodic.conf
 202 system registry will typically have a
 203 .Va local_periodic
 204 variable reading:
 205 .Pp
 206 .Dl local_periodic="/usr/local/etc/periodic"
 207 .Pp
 208 To log
 209 .Nm
 210 output instead of receiving it as email, add the following lines to
 211 .Pa /etc/periodic.conf :
 212 .Bd -literal -offset indent
 213 daily_output=/var/log/daily.log
 214 weekly_output=/var/log/weekly.log
 215 monthly_output=/var/log/monthly.log
 216 .Ed
 217 .Pp
 218 To only see important information from daily periodic jobs, add the
 219 following lines to
 220 .Pa /etc/periodic.conf :
 221 .Bd -literal -offset indent
 222 daily_show_success=NO
 223 daily_show_info=NO
 224 daily_show_badconfig=NO
 225 .Ed
 226 .Sh DIAGNOSTICS
 227 The command may fail for one of the following reasons:
 228 .Bl -diag
 229 .It usage: periodic <directory of files to execute>
 230 No directory path argument was passed to
 231 .Nm
 232 to specify where the script fragments reside.
 233 .It <directory> not found
 234 Self explanatory.
 235 .El
 236 .Sh SEE ALSO
 237 .Xr sh 1 ,
 238 .Xr crontab 5 ,
 239 .Xr periodic.conf 5 ,
 240 .Xr cron 8 ,
 241 .Xr newsyslog 8
 242 .Sh HISTORY
 243 The
 244 .Nm
 245 utility first appeared in
 246 .Fx 3.0 .
 247 .Sh AUTHORS
 248 .An Paul Traina Aq pst@FreeBSD.org
 249 .An Brian Somers Aq brian@Awfulhak.org
 250 .Sh BUGS
 251 Since one specifies information about a directory using shell
 252 variables containing the string,
 253 .Aq Ar basedir ,
 254 .Aq Ar basedir
 255 must only contain characters that are valid within a
 256 .Xr sh 1
 257 variable name, alphanumerics and underscores, and the first character
 258 may not be numeric.