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