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