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 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 , 169and 170.Pa monthly 171subdirectories which contain standard system periodic executables 172.It Pa /etc/defaults/periodic.conf 173the 174.Pa periodic.conf 175system registry contains variables that control the behaviour of 176.Nm 177and the standard 178.Pa daily , weekly , 179and 180.Pa monthly 181scripts 182.It Pa /etc/periodic.conf 183this file contains local overrides for the default 184.Nm 185configuration 186.El 187.Sh EXIT STATUS 188Exit status is 0 on success and 1 if the command fails. 189.Sh EXAMPLES 190The system crontab should have entries for 191.Nm 192similar to the following example: 193.Bd -literal -offset indent 194# do daily/weekly/monthly maintenance 1950 2 * * * root periodic daily 1960 3 * * 6 root periodic weekly 1970 5 1 * * root periodic monthly 198.Ed 199.Pp 200The 201.Pa /etc/defaults/periodic.conf 202system registry will typically have a 203.Va local_periodic 204variable reading: 205.Pp 206.Dl local_periodic="/usr/local/etc/periodic" 207.Pp 208To log 209.Nm 210output instead of receiving it as email, add the following lines to 211.Pa /etc/periodic.conf : 212.Bd -literal -offset indent 213daily_output=/var/log/daily.log 214weekly_output=/var/log/weekly.log 215monthly_output=/var/log/monthly.log 216.Ed 217.Pp 218To only see important information from daily periodic jobs, add the 219following lines to 220.Pa /etc/periodic.conf : 221.Bd -literal -offset indent 222daily_show_success=NO 223daily_show_info=NO 224daily_show_badconfig=NO 225.Ed 226.Sh DIAGNOSTICS 227The command may fail for one of the following reasons: 228.Bl -diag 229.It usage: periodic <directory of files to execute> 230No directory path argument was passed to 231.Nm 232to specify where the script fragments reside. 233.It <directory> not found 234Self 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 243The 244.Nm 245utility first appeared in 246.Fx 3.0 . 247.Sh AUTHORS 248.An Paul Traina Aq Mt pst@FreeBSD.org 249.An Brian Somers Aq Mt brian@Awfulhak.org 250.Sh BUGS 251Since one specifies information about a directory using shell 252variables containing the string, 253.Aq Ar basedir , 254.Aq Ar basedir 255must only contain characters that are valid within a 256.Xr sh 1 257variable name, alphanumerics and underscores, and the first character 258may not be numeric. 259