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 39program 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 75program 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 145command 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/periodic.conf" 154.It Pa /etc/crontab 155The 156.Nm 157program 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 EXAMPLES 183The system crontab should have entries for 184.Nm 185similar to the following example: 186.Bd -literal -offset indent 187# do daily/weekly/monthly maintenance 1880 2 * * * root periodic daily 1890 3 * * 6 root periodic weekly 1900 5 1 * * root periodic monthly 191.Ed 192.Pp 193The 194.Pa /etc/defaults/periodic.conf 195system registry will typically have a 196.Va local_periodic 197variable reading: 198.Pp 199.Dl local_periodic="/usr/local/etc/periodic /usr/X11R6/etc/periodic" 200.Pp 201To log 202.Nm 203output instead of receiving it as email, add the following lines to 204.Pa /etc/periodic.conf : 205.Bd -literal -offset indent 206daily_output=/var/log/daily.log 207weekly_output=/var/log/weekly.log 208monthly_output=/var/log/monthly.log 209.Ed 210.Pp 211To only see important information from daily periodic jobs, add the 212following lines to 213.Pa /etc/periodic.conf : 214.Bd -literal -offset indent 215daily_show_success=NO 216daily_show_info=NO 217daily_show_badconfig=NO 218.Ed 219.Sh SEE ALSO 220.Xr sh 1 , 221.Xr crontab 5 , 222.Xr periodic.conf 5 , 223.Xr cron 8 , 224.Xr newsyslog 8 225.Sh DIAGNOSTICS 226Exit status is 0 on success and 1 if the command 227fails 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 HISTORY 237The 238.Nm 239program first appeared in 240.Fx 3.0 . 241.Sh BUGS 242Since one specifies information about a directory using shell 243variables containing the string, 244.Aq Ar basedir , 245.Aq Ar basedir 246must only contain characters that are valid within a 247.Xr sh 1 248variable name, alphanumerics and underscores, and the first character 249may not be numeric. 250.Sh AUTHORS 251.An Paul Traina Aq pst@FreeBSD.org 252.An Brian Somers Aq brian@Awfulhak.org 253