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