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