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: src/usr.sbin/periodic/periodic.8,v 1.11.2.15 2003/03/12 22:08:15 trhodes Exp $ 26.\" $DragonFly: src/usr.sbin/periodic/periodic.8,v 1.5 2007/09/07 23:24:20 swildner Exp $ 27.\" 28.Dd September 7, 2007 29.Os 30.Dt PERIODIC 8 31.Sh NAME 32.Nm periodic 33.Nd run periodic system functions 34.Sh SYNOPSIS 35.Nm 36.Ar directory ... 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 ".Pa monthly" 47.It Pa daily 48Perform the standard daily periodic executable run. 49This usually occurs early in the morning (local time). 50.It Pa weekly 51Perform the standard weekly periodic executable run. 52This usually occurs on Saturday mornings. 53.It Pa monthly 54Perform the standard monthly periodic executable run. 55This usually occurs on the first day of the month. 56.It Pa security 57Perform the standard daily security checks. 58This is usually spawned by the 59.Pa daily 60run. 61.It Ar path 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. 139.Pp 140If 141.Ao Ar basedir Ac Ns Va _output 142is not set or is empty, output is sent to standard output. 143.Sh ENVIRONMENT 144The 145.Nm 146utility sets the 147.Ev PATH 148environment to include all standard system directories, but no additional 149directories, such as 150.Pa /usr/local/bin . 151If executables are added which depend upon other path components, each 152executable must be responsible for configuring its own appropriate environment. 153.Sh FILES 154.Bl -tag -width ".Pa /etc/defaults/periodic.conf" 155.It Pa /etc/crontab 156the 157.Nm 158utility is typically called via entries in the system default 159.Xr cron 8 160table 161.It Pa /etc/periodic 162the top level directory containing 163.Pa daily , 164.Pa weekly , 165and 166.Pa monthly 167subdirectories which contain standard system periodic executables 168.It Pa /etc/defaults/periodic.conf 169the 170.Pa periodic.conf 171system registry contains variables that control the behaviour of 172.Nm 173and the standard 174.Pa daily , weekly , 175and 176.Pa monthly 177scripts 178.It Pa /etc/periodic.conf 179this file contains local overrides for the default 180.Nm 181configuration 182.El 183.Sh EXAMPLES 184The system crontab should have entries for 185.Nm 186similar to the following example: 187.Bd -literal -offset indent 188# do daily/weekly/monthly maintenance 1890 2 * * * root periodic daily 1900 3 * * 6 root periodic weekly 1910 5 1 * * root periodic monthly 192.Ed 193.Pp 194The 195.Pa /etc/defaults/periodic.conf 196system registry will typically have a 197.Va local_periodic 198variable reading: 199.Pp 200.Dl local_periodic="/usr/local/etc/periodic /usr/pkg/xorg/etc/periodic" 201.Pp 202To log 203.Nm 204output instead of receiving it as email, add the following lines to 205.Pa /etc/periodic.conf : 206.Bd -literal -offset indent 207daily_output=/var/log/daily.log 208weekly_output=/var/log/weekly.log 209monthly_output=/var/log/monthly.log 210.Ed 211.Pp 212To only see important information from daily periodic jobs, add the 213following lines to 214.Pa /etc/periodic.conf : 215.Bd -literal -offset indent 216daily_show_success=NO 217daily_show_info=NO 218daily_show_badconfig=NO 219.Ed 220.Sh DIAGNOSTICS 221Exit status is 0 on success and 1 if the command 222fails 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