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