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