View | Details | Raw Unified | Return to bug 210621 | Differences between
and this patch

Collapse All | Expand All

(-)b/usr.sbin/cron/crontab/crontab.5 (-133 / +208 lines)
Lines 29-51 A Link Here
29
file contains instructions to the
29
file contains instructions to the
30
.Xr cron 8
30
.Xr cron 8
31
daemon of the general form: ``run this command at this time on this date''.
31
daemon of the general form: ``run this command at this time on this date''.
32
Each user has their own crontab, and commands in any given crontab will be
32
.Pp
33
executed as the user who owns the crontab.
33
Each user (including any superusers) can have their own crontab, and commands 
34
Uucp and News will usually have
34
in any user crontab will be executed as the user who owns the crontab. 
35
their own crontabs, eliminating the need for explicitly running
35
Accounts for services (such as Uucp or News) can be given user crontabs, 
36
eliminating the need for explicitly running 
36
.Xr su 1
37
.Xr su 1
37
as part of a cron command.
38
as part of a cron command.
38
.Pp
39
.Pp
40
.Fx also has a system crontab format, for /etc/crontab, /etc/cron.d files, 
41
or /usr/local/etc/cron.d files. The system crontab has an 
42
additional field 
43
.Pq Em who
44
to specify the user, group, or login class to run the 
45
command as
46
.Po see 
47
.Sx SYSTEM CRONTAB
48
.Pc .
49
.Pp
50
An active line in a crontab will be either an environment setting or a cron
51
command. Non-active lines (whitespace and comments) are ignored.
52
.Pp
53
.Ss WHITESPACE AND COMMENTS
39
Blank lines and leading spaces and tabs are ignored.
54
Blank lines and leading spaces and tabs are ignored.
40
Lines whose first
55
Lines whose first
41
non-space character is a pound-sign (#) are comments, and are ignored.
56
non-space character is a pound-sign (#) are comments, and are ignored.
42
Note that comments are not allowed on the same line as cron commands, since
57
Comments are not allowed on the same line as cron commands, since
43
they will be taken to be part of the command.
58
they will be taken to be part of the command.
44
Similarly, comments are not
59
Similarly, comments are not
45
allowed on the same line as environment variable settings.
60
allowed on the same line as environment variable settings.
46
.Pp
61
.Ss ENVIRONMENT SETTING
47
An active line in a crontab will be either an environment setting or a cron
48
command.
49
An environment setting is of the form,
62
An environment setting is of the form,
50
.Bd -literal
63
.Bd -literal
51
    name = value
64
    name = value
Lines 62-168 string may be placed in quotes (single or double, but matching) to preserve Link Here
62
leading or trailing blanks.
75
leading or trailing blanks.
63
The
76
The
64
.Em name
77
.Em name
65
string may also be placed in quote (single or double, but matching)
78
string may also be placed in quotes (single or double, but matching)
66
to preserve leading, trailing or inner blanks.
79
to preserve leading, trailing or inner blanks.
67
.Pp
80
.Pp
68
Several environment variables are set up
81
.Ss CRON COMMAND
69
automatically by the
82
The format of a user cron command is very much the V7 standard, with 
70
.Xr cron 8
83
a number of upward-compatible extensions.  Each line has five time 
71
daemon.
84
and date fields, followed by a command.
72
.Ev SHELL
73
is set to
74
.Pa /bin/sh ,
75
and
76
.Ev LOGNAME
77
and
78
.Ev HOME
79
are set from the
80
.Pa /etc/passwd
81
line of the crontab's owner.
82
In addition, the environment variables of the
83
user's login class will be set from
84
.Pa /etc/login.conf.db
85
and
86
.Pa ~/.login_conf .
87
(A setting of
88
.Ev HOME
89
in the login class will override the value from
90
.Pa /etc/passwd ,
91
but will not change the current directory when the command is
92
invoked, which can only be overridden with an explicit setting of
93
.Ev HOME
94
within the crontab file itself.)
95
If
96
.Ev PATH
97
is not set by any other means, it is defaulted to
98
.Pa /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin .
99
.Ev HOME ,
100
.Ev PATH
101
and
102
.Ev SHELL ,
103
and any variables set from the login class,
104
may be overridden by settings in the crontab;
105
.Ev LOGNAME
106
may not.
107
.Pp
108
(Another note: the
109
.Ev LOGNAME
110
variable is sometimes called
111
.Ev USER
112
on
113
.Bx
114
systems...
115
On these systems,
116
.Ev USER
117
will be set also).
118
.Pp
119
If
120
.Xr cron 8
121
has any reason to send mail as a result of running commands in
122
``this'' crontab, it will respect the following settings which may be
123
defined in the crontab (but which are not taken from the login class).
124
If
125
.Ev MAILTO
126
is defined (and non-empty), mail is
127
sent to the user so named.
128
If
129
.Ev MAILFROM
130
is defined (and non-empty), its value will be used as the from address.
131
.Ev MAILTO
132
may also be used to direct mail to multiple recipients
133
by separating recipient users with a comma.
134
If
135
.Ev MAILTO
136
is defined but empty (MAILTO=""), no
137
mail will be sent.
138
Otherwise mail is sent to the owner of the crontab.
139
This
140
option is useful if you decide on
141
.Pa /bin/mail
142
instead of
143
.Pa /usr/lib/sendmail
144
as
145
your mailer when you install cron --
146
.Pa /bin/mail
147
does not do aliasing, and UUCP
148
usually does not read its mail.
149
.Pp
85
.Pp
150
The format of a cron command is very much the V7 standard, with a number of
151
upward-compatible extensions.
152
Each line has five time and date fields,
153
followed by a user name
154
(with optional ``:<group>'' and ``/<login-class>'' suffixes)
155
if this is the system crontab file,
156
followed by a command.
157
Commands are executed by
86
Commands are executed by
158
.Xr cron 8
87
.Xr cron 8
159
when the minute, hour, and month of year fields match the current time,
88
when the minute, hour, and month of year fields match the current time,
160
.Em and
89
.Em and
161
when at least one of the two day fields (day of month, or day of week)
90
when at least one of the two day fields (day of month, or day of week)
162
matches the current time (see ``Note'' below).
91
matches the current time 
163
.Xr cron 8
92
.Po see 
93
.Sx TIME AND DAY OPTIONS
94
.Pc .
95
.Xr cron 8 
164
examines cron entries once every minute.
96
examines cron entries once every minute.
165
The time and date fields are:
97
.Pp
98
If time jitter is enabled, 
99
.Xr cron 8
100
will sleep a random number of seconds in the range from 0 to 
101
.Ar jitter
102
prior to executing commands.
103
.Pp
104
The user cron command fields are:
166
.Bd -literal -offset indent
105
.Bd -literal -offset indent
167
field         allowed values
106
field         allowed values
168
-----         --------------
107
-----         --------------
Lines 171-178 hour 0-23 Link Here
171
day of month  1-31
110
day of month  1-31
172
month         1-12 (or names, see below)
111
month         1-12 (or names, see below)
173
day of week   0-7 (0 or 7 is Sun, or use names)
112
day of week   0-7 (0 or 7 is Sun, or use names)
113
command       [command options] command
174
.Ed
114
.Ed
175
.Pp
115
.Pp
116
The command field (the rest of the line) specifies the command to be
117
run.
118
One or more command options may precede the command to modify processing
119
behavior.
120
The entire command portion of the line, up to a newline or %
121
character, will be executed by
122
.Pa /bin/sh
123
or by the shell
124
specified in the
125
.Ev SHELL
126
variable of the cronfile.
127
Percent-signs (%) in the command, unless escaped with backslash
128
(\\), will be changed into newline characters, and all data
129
after the first % will be sent to the command as standard
130
input.
131
.Pp
132
.Ss TIME AND DAY OPTIONS
176
A field may be an asterisk (*), which always stands for ``first\-last''.
133
A field may be an asterisk (*), which always stands for ``first\-last''.
177
.Pp
134
.Pp
178
Ranges of numbers are allowed.
135
Ranges of numbers are allowed.
Lines 205-243 Use the first three letters of the particular Link Here
205
day or month (case does not matter).
162
day or month (case does not matter).
206
Ranges and lists are also allowed.
163
Ranges and lists are also allowed.
207
.Pp
164
.Pp
208
The ``sixth'' field (the rest of the line) specifies the command to be
165
.Ss DAY OF COMMAND EXECUTION
209
run.
166
The day of a command's execution can be specified by two
210
One or more command options may precede the command to modify processing
211
behavior.
212
The entire command portion of the line, up to a newline or %
213
character, will be executed by
214
.Pa /bin/sh
215
or by the shell
216
specified in the
217
.Ev SHELL
218
variable of the cronfile.
219
Percent-signs (%) in the command, unless escaped with backslash
220
(\\), will be changed into newline characters, and all data
221
after the first % will be sent to the command as standard
222
input.
223
.Pp
224
The following command options can be supplied:
225
.Bl -tag -width Ds
226
.It Fl n
227
No mail is sent after a successful run.
228
The execution output will only be mailed if the command exits with a non-zero
229
exit code.
230
The
231
.Fl n
232
option is an attempt to cure potentially copious volumes of mail coming from
233
.Xr cron 8 .
234
.It Fl q
235
Execution will not be logged.
236
.El
237
.sp
238
Duplicate options are not allowed.
239
.Pp
240
Note: The day of a command's execution can be specified by two
241
fields \(em day of month, and day of week.
167
fields \(em day of month, and day of week.
242
If both fields are
168
If both fields are
243
restricted (ie, are not *), the command will be run when
169
restricted (ie, are not *), the command will be run when
Lines 279-284 Note, however, that overlap may occur if the job is running when the file Link Here
279
containing the job is modified and subsequently reloaded.
205
containing the job is modified and subsequently reloaded.
280
The first run is scheduled for the specified number of seconds after cron
206
The first run is scheduled for the specified number of seconds after cron
281
is started or the crontab entry is reloaded.
207
is started or the crontab entry is reloaded.
208
.Pp
209
.Ss COMMAND OPTIONS
210
The following command options can be supplied:
211
.Bl -tag -width Ds
212
.It Fl n
213
No mail is sent after a successful run.
214
The execution output will only be mailed if the command exits with a non-zero
215
exit code.
216
The
217
.Fl n
218
option is an attempt to cure potentially copious volumes of mail coming from
219
.Xr cron 8 .
220
.It Fl q
221
Execution will not be logged.
222
.El
223
.sp
224
Duplicate options are not allowed.
225
.Pp
226
.Ss SYSTEM CRONTAB
227
The system crontab format is identical to the user crontab format with 
228
the addition of a field between the time and day fields and the command.
229
This required field is used to specify the user to run the command as.
230
.Pp
231
To specify the group to run as, append a colon ``:'' followed by the 
232
group name. The group must have an entry in /etc/group, see
233
.Xr group 5 .
234
The group is not required.
235
.Pp
236
To specify the login class to run as, append a forward-slash ``/''
237
followed by the login class. The login class must have an entry in 
238
the login capabilities database, see 
239
.Xr login.conf 5 .
240
The login class is optional, but if not specified, the login class will be ``daemon''.
241
.Pp
242
If both the group and login class are specified, the group 
243
must precede the login class.
244
.Pp
245
The system cron command fields are:
246
.Bd -literal -offset indent
247
field         allowed values
248
-----         --------------
249
minute        0-59
250
hour          0-23
251
day of month  1-31
252
month         1-12 (or names)
253
day of week   0-7 (0 or 7 is Sun, or use names)
254
who           username:groupname/loginclass
255
command       [command options] command
256
.Ed
257
.Pp
258
All fields other than 
259
.Em who
260
function the same as in a user cron command.
261
.Pp
262
If root time jitter is enabled, and
263
.Em who
264
specifies a superuser (user id 0), 
265
.Xr cron 8
266
will sleep a random number of seconds in the range from 0 to 
267
.Ar rootjitter
268
prior to executing superuser commands.
269
.Pp 
270
If an invalid group or login class is specified, 
271
.Xr cron 8
272
will stop processing the crontab, and no further 
273
commands will be loaded from that crontab.
274
.Sh ENVIRONMENT
275
Several environment variables are set up
276
automatically by the
277
.Xr cron 8
278
daemon.
279
.Ev SHELL
280
is set to
281
.Pa /bin/sh ,
282
and
283
.Ev LOGNAME
284
and
285
.Ev HOME
286
are set from the
287
.Pa /etc/passwd
288
line of the crontab's owner.
289
In addition, the environment variables of the
290
user's login class will be set from
291
.Pa /etc/login.conf.db
292
and
293
.Pa ~/.login_conf .
294
(A setting of
295
.Ev HOME
296
in the login class will override the value from
297
.Pa /etc/passwd ,
298
but will not change the current directory when the command is
299
invoked, which can only be overridden with an explicit setting of
300
.Ev HOME
301
within the crontab file itself.)
302
If
303
.Ev PATH
304
is not set by any other means, it is defaulted to
305
.Pa /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin .
306
.Ev HOME ,
307
.Ev PATH
308
and
309
.Ev SHELL ,
310
and any variables set from the login class,
311
may be overridden by settings in the crontab;
312
.Ev LOGNAME
313
may not.
314
.Pp
315
(Another note: the
316
.Ev LOGNAME
317
variable is sometimes called
318
.Ev USER
319
on
320
.Bx
321
systems...
322
On these systems,
323
.Ev USER
324
will be set also).
325
.Pp
326
.Sh MAIL FROM COMMANDS
327
If
328
.Xr cron 8
329
has any reason to send mail as a result of running commands in
330
``this'' crontab, it will respect the following settings which may be
331
defined in the crontab (but which are not taken from the login class).
332
If
333
.Ev MAILTO
334
is defined (and non-empty), mail is
335
sent to the user so named.
336
If
337
.Ev MAILFROM
338
is defined (and non-empty), its value will be used as the from address.
339
.Ev MAILTO
340
may also be used to direct mail to multiple recipients
341
by separating recipient users with a comma.
342
If
343
.Ev MAILTO
344
is defined but empty (MAILTO=""), no
345
mail will be sent.
346
Otherwise mail is sent to the owner of the crontab.
347
This
348
option is useful if you decide on
349
.Pa /bin/mail
350
instead of
351
.Pa /usr/lib/sendmail
352
as
353
your mailer when you install cron --
354
.Pa /bin/mail
355
does not do aliasing, and UUCP
356
usually does not read its mail.
282
.Sh EXAMPLE CRON FILE
357
.Sh EXAMPLE CRON FILE
283
.Bd -literal
358
.Bd -literal
284
359

Return to bug 210621