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