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: src/usr.sbin/periodic/periodic.8,v 1.11.2.15 2003/03/12 22:08:15 trhodes Exp $
  26 .\"
  27 .Dd September 7, 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 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 .Pp
 139 If
 140 .Ao Ar basedir Ac Ns Va _output
 141 is not set or is empty, output is sent to standard output.
 142 .Sh ENVIRONMENT
 143 The
 144 .Nm
 145 utility sets the
 146 .Ev PATH
 147 environment to include all standard system directories, but no additional
 148 directories, such as
 149 .Pa /usr/local/bin .
 150 If executables are added which depend upon other path components, each
 151 executable must be responsible for configuring its own appropriate environment.
 152 .Sh FILES
 153 .Bl -tag -width ".Pa /etc/defaults/periodic.conf"
 154 .It Pa /etc/crontab
 155 the
 156 .Nm
 157 utility is typically called via entries in the system default
 158 .Xr cron 8
 159 table
 160 .It Pa /etc/periodic
 161 the top level directory containing
 162 .Pa daily ,
 163 .Pa weekly ,
 164 and
 165 .Pa monthly
 166 subdirectories which contain standard system periodic executables
 167 .It Pa /etc/defaults/periodic.conf
 168 the
 169 .Pa periodic.conf
 170 system registry contains variables that control the behaviour of
 171 .Nm
 172 and the standard
 173 .Pa daily , weekly ,
 174 and
 175 .Pa monthly
 176 scripts
 177 .It Pa /etc/periodic.conf
 178 this file contains local overrides for the default
 179 .Nm
 180 configuration
 181 .El
 182 .Sh EXAMPLES
 183 The system crontab should have entries for
 184 .Nm
 185 similar to the following example:
 186 .Bd -literal -offset indent
 187 # do daily/weekly/monthly maintenance
 188 0      2       *       *       *       root    periodic daily
 189 0      3       *       *       6       root    periodic weekly
 190 0      5       1       *       *       root    periodic monthly
 191 .Ed
 192 .Pp
 193 The
 194 .Pa /etc/defaults/periodic.conf
 195 system registry will typically have a
 196 .Va local_periodic
 197 variable reading:
 198 .Pp
 199 .Dl local_periodic="/usr/local/etc/periodic /usr/pkg/etc/periodic"
 200 .Pp
 201 To log
 202 .Nm
 203 output instead of receiving it as email, add the following lines to
 204 .Pa /etc/periodic.conf :
 205 .Bd -literal -offset indent
 206 daily_output=/var/log/daily.log
 207 weekly_output=/var/log/weekly.log
 208 monthly_output=/var/log/monthly.log
 209 .Ed
 210 .Pp
 211 To only see important information from daily periodic jobs, add the
 212 following lines to
 213 .Pa /etc/periodic.conf :
 214 .Bd -literal -offset indent
 215 daily_show_success=NO
 216 daily_show_info=NO
 217 daily_show_badconfig=NO
 218 .Ed
 219 .Sh DIAGNOSTICS
 220 Exit status is 0 on success and 1 if the command
 221 fails for one of the following reasons:
 222 .Bl -diag
 223 .It usage: periodic <directory of files to execute>
 224 No directory path argument was passed to
 225 .Nm
 226 to specify where the script fragments reside.
 227 .It <directory> not found
 228 Self explanatory.
 229 .El
 230 .Sh SEE ALSO
 231 .Xr sh 1 ,
 232 .Xr crontab 5 ,
 233 .Xr periodic.conf 5 ,
 234 .Xr cron 8 ,
 235 .Xr newsyslog 8
 236 .Sh HISTORY
 237 The
 238 .Nm
 239 utility first appeared in
 240 .Fx 3.0 .
 241 .Sh AUTHORS
 242 .An Paul Traina Aq Mt pst@FreeBSD.org
 243 .An Brian Somers Aq Mt brian@Awfulhak.org
 244 .Sh BUGS
 245 Since one specifies information about a directory using shell
 246 variables containing the string,
 247 .Aq Ar basedir ,
 248 .Aq Ar basedir
 249 must only contain characters that are valid within a
 250 .Xr sh 1
 251 variable name, alphanumerics and underscores, and the first character
 252 may not be numeric.