| blob | 7f7324e9931fb4d4239c231a25eec7cfb9a1f2e5 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
46 .\"
47 .TH CRONTAB 1 "Oct 25, 2017"
48 .SH NAME
49 crontab \- user crontab file
50 .SH SYNOPSIS
51 .LP
52 .nf
53 \fB/usr/bin/crontab\fR [\fIfilename\fR]
54 .fi
56 .LP
57 .nf
58 \fB/usr/bin/crontab\fR \fB-e\fR [\fIusername\fR]
59 .fi
61 .LP
62 .nf
63 \fB/usr/bin/crontab\fR \fB-l\fR [\fIusername\fR]
64 .fi
66 .LP
67 .nf
68 \fB/usr/bin/crontab\fR \fB-r\fR [\fIusername\fR]
69 .fi
71 .SH DESCRIPTION
72 .LP
73 The \fBcrontab\fR utility manages a user's access with \fBcron\fR (see
74 \fBcron\fR(8)) by copying, creating, listing, and removing \fBcrontab\fR
75 files. If invoked without options, \fBcrontab\fR copies the specified file, or
76 the standard input if no file is specified, into a directory that holds all
77 users' crontabs.
78 .sp
79 .LP
80 If \fBcrontab\fR is invoked with \fIfilename\fR, this overwrites an existing
81 \fBcrontab\fR entry for the user that invokes it.
82 .SS "\fBcrontab\fR Access Control"
83 .LP
84 Users: Access to \fBcrontab\fR is allowed:
85 .RS +4
86 .TP
87 .ie t \(bu
88 .el o
89 if the user's name appears in \fB/etc/cron.d/cron.allow\fR.
90 .RE
91 .RS +4
92 .TP
93 .ie t \(bu
94 .el o
95 if \fB/etc/cron.d/cron.allow\fR does not exist and the user's name is not in
96 \fB/etc/cron.d/cron.deny\fR.
97 .RE
98 .sp
99 .LP
100 Users: Access to \fBcrontab\fR is denied:
101 .RS +4
102 .TP
103 .ie t \(bu
104 .el o
105 if \fB/etc/cron.d/cron.allow\fR exists and the user's name is not in it.
106 .RE
107 .RS +4
108 .TP
109 .ie t \(bu
110 .el o
111 if \fB/etc/cron.d/cron.allow\fR does not exist and user's name is in
112 \fB/etc/cron.d/cron.deny\fR.
113 .RE
114 .RS +4
115 .TP
116 .ie t \(bu
117 .el o
118 if neither file exists, only a user with the \fBsolaris.jobs.user\fR
119 authorization is allowed to submit a job.
120 .RE
121 .RS +4
122 .TP
123 .ie t \(bu
124 .el o
125 if Auditing is enabled, the user's shell is not audited and the user is
126 not the \fBcrontab\fR owner. This can occur if the user logs in by way of a
127 program, such as some versions of \fBSSH\fR, which does not set audit
128 parameters.
129 .RE
130 .sp
131 .LP
132 The rules for \fBallow\fR and \fBdeny\fR apply to \fBroot\fR only if the
133 \fBallow\fR/\fBdeny\fR files exist.
134 .sp
135 .LP
136 The \fBallow\fR/\fBdeny\fR files consist of one user name per line.
137 .SS "\fBcrontab\fR Entry Format"
138 .LP
139 A \fBcrontab\fR file consists of lines of six fields each. The fields are
140 separated by spaces or tabs. The first five are integer patterns that specify
141 the following:
142 .sp
143 .in +2
144 .nf
145 minute (0\(mi59),
146 hour (0\(mi23),
147 day of the month (1\(mi31),
148 month of the year (1\(mi12),
149 day of the week (0\(mi6 with 0=Sunday).
150 .fi
151 .in -2
152 .sp
154 .sp
155 .LP
156 Each of these patterns can be either an asterisk (meaning all legal values) or
157 a list of elements separated by commas. An element is either a number or two
158 numbers separated by a minus sign (meaning an inclusive range). Time specified
159 here is interpreted in the currently active timezone. At the top of the crontab
160 file this is the timezone which is set system-wide in /etc/default/init. A user
161 can add a line such as:
162 .sp
163 .in +2
164 .nf
165 TZ=\fItimezone\fR
166 .fi
167 .in -2
168 .sp
170 .sp
171 .LP
172 \&...and all subsequent entries will be interpreted using that timezone, until
173 a new \fBTZ=\fR\fItimezone\fR line is encountered. The specification of days
174 can be made by two fields (day of the month and day of the week). Both are
175 adhered to if specified as a list of elements. See \fBEXAMPLES\fR.
176 .sp
177 .LP
178 The sixth field of a line in a \fBcrontab\fR file is a string that is executed
179 by the shell at the specified times. A percent character in this field (unless
180 escaped by \fB\e\fR\|) is translated to a \fINEWLINE\fR character.
181 .sp
182 .LP
183 Only the first line (up to a \fB`\|%\|'\fR or end of line) of the command field
184 is executed by the shell. Other lines are made available to the command as
185 standard input. Any blank line or line beginning with a \fB`\|#\|'\fR is a
186 comment and is ignored.
187 .sp
188 .LP
189 The shell is invoked from your $HOME directory. As with $TZ, both $SHELL and
190 $HOME can be set by having a line such as:
191 .sp
192 .in +2
193 .nf
194 SHELL=/usr/bin/\fIsomeshell\fR
195 .fi
196 .in -2
197 .sp
199 .sp
200 .LP
201 \&...or:
202 .sp
203 .in +2
204 .nf
205 HOME=\fIsomedirectory\fR
206 .fi
207 .in -2
208 .sp
210 .sp
211 .LP
212 \&...which will take precedence for all the remaining entries in the
213 \fBcrontab\fR or until there is another \fBHOME\fR or \fBSHELL\fR entry. It is
214 invoked with an \fBarg0\fR of the basename of the $SHELL that is currently in
215 effect. A user who wants to have his \fB\&.profile\fR or equivalent file
216 executed must explicitly do so in the \fBcrontab\fR file. \fBcron\fR supplies
217 a default environment for every shell, defining HOME, LOGNAME, SHELL, TZ, and
218 PATH. The default PATH for user \fBcron\fR jobs is \fB/usr/bin\fR; while root
219 \fBcron\fR jobs default to \fB/usr/sbin:/usr/bin\fR. The default PATH can be
220 set in \fB/etc/default/cron\fR (see \fBcron\fR(8)). The TZ, HOME, and SHELL
221 environment variables are set to match those that are in effect in the
222 \fBcrontab\fR file at the time.
223 .sp
224 .LP
225 If you do not redirect the standard output and standard error of your commands,
226 any generated output or errors are mailed to you.
227 .SS "\fBcrontab\fR Environment Variables"
228 .LP
229 The following variables are supported:
230 .sp
231 .ne 2
232 .na
233 \fB\fBHOME\fR\fR
234 .ad
235 .sp .6
236 .RS 4n
237 Allows the user to choose and alternative directory for cron to change
238 directory to prior to running the command. For example:
239 .sp
240 .in +2
241 .nf
242 HOME=/var/tmp
243 .fi
244 .in -2
245 .sp
247 .RE
249 .sp
250 .ne 2
251 .na
252 \fB\fBSHELL\fR\fR
253 .ad
254 .sp .6
255 .RS 4n
256 The name of the shell to use to run subsequent commands. For example:
257 .sp
258 .in +2
259 .nf
260 SHELL=/usr/bin/ksh
261 .fi
262 .in -2
263 .sp
265 .RE
267 .sp
268 .ne 2
269 .na
270 \fB\fBTZ\fR\fR
271 .ad
272 .sp .6
273 .RS 4n
274 Allows the user to choose the timezone in which the \fBcron\fR entries are run.
275 This effects both the environment of the command that is run and the timing of
276 the entry. For example, to have your entries run using the timezone for
277 Iceland, use:
278 .sp
279 .in +2
280 .nf
281 TZ=Iceland
282 .fi
283 .in -2
284 .sp
286 .RE
288 .sp
289 .LP
290 Each of these variables affects all of the lines that follow it in the
291 \fBcrontab\fR file, until it is reset by a subsequent line resetting that
292 variable. Hence, it is possible to have multiple timezones supported within a
293 single \fBcrontab\fR file.
294 .sp
295 .LP
296 The lines that are not setting these environment variables are the same as
297 crontab entries that conform to the UNIX standard and are described elsewhere
298 in this man page.
299 .SS "Setting \fBcron\fR Jobs Across Timezones"
300 .LP
301 The default timezone of the \fBcron\fR daemon sets the system-wide timezone for
302 \fBcron\fR entries. This, in turn, is by set by default system-wide using
303 \fB/etc/default/init\fR.
304 .sp
305 .LP
306 If some form of \fBdaylight savings\fR or \fBsummer/winter time\fR is in
307 effect, then jobs scheduled during the switchover period could be executed
308 once, twice, or not at all.
309 .SH OPTIONS
310 .LP
311 The following options are supported:
312 .sp
313 .ne 2
314 .na
315 \fB\fB-e\fR\fR
316 .ad
317 .RS 6n
318 Edits a copy of the current user's \fBcrontab\fR file, or creates an empty file
319 to edit if \fBcrontab\fR does not exist. When editing is complete, the file is
320 installed as the user's \fBcrontab\fR file.
321 .sp
322 The environment variable \fBEDITOR\fR determines which editor is invoked with
323 the \fB-e\fR option. All \fBcrontab\fR jobs should be submitted using
324 \fBcrontab\fR. Do not add jobs by just editing the \fBcrontab\fR file, because
325 \fBcron\fR is not aware of changes made this way.
326 .sp
327 If all lines in the \fBcrontab\fR file are deleted, the old \fBcrontab\fR file
328 is restored. The correct way to delete all lines is to remove the \fBcrontab\fR
329 file using the \fB-r\fR option.
330 .sp
331 If \fIusername\fR is specified, the specified user's \fBcrontab\fR file is
332 edited, rather than the current user's \fBcrontab\fR file. This can only be
333 done by root or by a user with the \fBsolaris.jobs.admin\fR authorization.
334 .RE
336 .sp
337 .ne 2
338 .na
339 \fB\fB-l\fR\fR
340 .ad
341 .RS 6n
342 Lists the \fBcrontab\fR file for the invoking user. Only root or a user with
343 the \fBsolaris.jobs.admin\fR authorization can specify a username following the
344 \fB-l\fR option to list the \fBcrontab\fR file of the specified user.
345 .RE
347 .sp
348 .ne 2
349 .na
350 \fB\fB-r\fR\fR
351 .ad
352 .RS 6n
353 Removes a user's \fBcrontab\fR from the \fBcrontab\fR directory. Only root or a
354 user with the \fBsolaris.jobs.admin\fR authorization can specify a username
355 following the \fB-r\fR option to remove the \fBcrontab\fR file of the specified
356 user.
357 .RE
359 .SH EXAMPLES
360 .LP
361 \fBExample 1 \fRCleaning up Core Files
362 .sp
363 .LP
364 This example cleans up \fBcore\fR files every weekday morning at 3:15 am:
366 .sp
367 .in +2
368 .nf
369 \fB15 3 * * 1-5 find $HOME\fR \fB-name\fR\fBcore 2>/dev/null | xargs rm\fR \fB-f\fR
370 .fi
371 .in -2
372 .sp
374 .LP
375 \fBExample 2 \fRMailing a Birthday Greeting
376 .sp
377 .LP
378 This example mails a birthday greeting:
380 .sp
381 .in +2
382 .nf
383 \fB0 12 14 2 * mailx john%Happy Birthday!%Time for lunch.\fR
384 .fi
385 .in -2
386 .sp
388 .LP
389 \fBExample 3 \fRSpecifying Days of the Month and Week
390 .sp
391 .LP
392 This example runs a command on the first and fifteenth of each month, as well
393 as on every Monday:
395 .sp
396 .in +2
397 .nf
398 \fB0 0 1,15 * 1\fR
399 .fi
400 .in -2
401 .sp
403 .sp
404 .LP
405 To specify days by only one field, the other field should be set to *. For
406 example:
408 .sp
409 .in +2
410 .nf
411 \fB0 0 * * 1\fR
412 .fi
413 .in -2
414 .sp
416 .sp
417 .LP
418 would run a command only on Mondays.
420 .LP
421 \fBExample 4 \fRUsing Environment Variables
422 .sp
423 .LP
424 The following entries take advantage of \fBcrontab\fR support for certain
425 environment variables.
427 .sp
428 .in +2
429 .nf
430 TZ=GMT
431 HOME=/local/home/user
432 SHELL=/usr/bin/ksh
433 0 0 * * * echo $(date) > midnight.GMT
434 TZ=PST
435 0 0 * * * echo $(date) > midnight.PST
436 TZ=EST
437 HOME=/local/home/myuser
438 SHELL=/bin/csh
439 .fi
440 .in -2
441 .sp
443 .sp
444 .LP
445 The preceding entries allow two jobs to run. The first one would run at
446 midnight in the GMT timezone and the second would run at midnight in the PST
447 timezone. Both would be run in the directory \fB/local/home/user\fR using the
448 Korn shell. The file concludes with \fBTZ\fR, \fBHOME\fR, and \fBSHELL\fR
449 entries that return those variable to their default values.
451 .SH ENVIRONMENT VARIABLES
452 .LP
453 See \fBenviron\fR(5) for descriptions of the following environment variables
454 that affect the execution of \fBcrontab\fR: \fBLANG\fR, \fBLC_ALL\fR,
455 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
456 .ne 2
457 .na
458 .sp
459 \fB\fBPATH\fR\fR
460 .ad
461 .RS 10n
462 The \fBPATH\fR in \fBcrontab\fR's environment specifies the search path used to
463 find the editor.
464 .RE
466 .sp
467 .ne 2
468 .na
469 \fB\fBVISUAL\fR\fR
470 .ad
471 .RS 10n
472 Determine the visual editor to be invoked when the \fB-e\fR option is
473 specified. If \fBVISUAL\fR is not specified, then the environment variable
474 \fBEDITOR\fR is used. If that is not set, the default is \fBvi\fR(1).
475 .RE
477 .ne 2
478 .na
479 \fB\fBEDITOR\fR\fR
480 .ad
481 .RS 10n
482 Determine the editor to be invoked when the \fB-e\fR option is specified. The
483 default editor is \fB/usr/bin/vi\fR.
484 .RE
486 .SH EXIT STATUS
487 .LP
488 The following exit values are returned:
489 .sp
490 .ne 2
491 .na
492 \fB\fB0\fR\fR
493 .ad
494 .RS 6n
495 Successful completion.
496 .RE
498 .sp
499 .ne 2
500 .na
501 \fB\fB>0\fR\fR
502 .ad
503 .RS 6n
504 An error occurred.
505 .RE
507 .SH FILES
508 .ne 2
509 .na
510 \fB\fB/etc/cron.d\fR\fR
511 .ad
512 .RS 28n
513 main cron directory
514 .RE
516 .sp
517 .ne 2
518 .na
519 \fB\fB/etc/cron.d/cron.allow\fR\fR
520 .ad
521 .RS 28n
522 list of allowed users
523 .RE
525 .sp
526 .ne 2
527 .na
528 \fB\fB/etc/default/cron\fR\fR
529 .ad
530 .RS 28n
531 contains cron default settings
532 .RE
534 .sp
535 .ne 2
536 .na
537 \fB\fB/etc/cron.d/cron.deny\fR\fR
538 .ad
539 .RS 28n
540 list of denied users
541 .RE
543 .sp
544 .ne 2
545 .na
546 \fB\fB/var/cron/log\fR\fR
547 .ad
548 .RS 28n
549 accounting information
550 .RE
552 .sp
553 .ne 2
554 .na
555 \fB\fB/var/spool/cron/crontabs\fR\fR
556 .ad
557 .RS 28n
558 spool area for \fBcrontab\fR
559 .RE
561 .SH ATTRIBUTES
562 .LP
563 See \fBattributes\fR(5) for descriptions of the following attributes:
564 .SS "\fB/usr/bin/crontab\fR"
566 .TS
567 box;
568 c | c
569 l | l .
570 ATTRIBUTE TYPE ATTRIBUTE VALUE
571 _
572 Interface Stability Standard
573 .TE
575 .SH SEE ALSO
576 .LP
577 \fBatq\fR(1), \fBatrm\fR(1), \fBauths\fR(1), \fBed\fR(1), \fBsh\fR(1),
578 \fBvi\fR(1), \fBcron\fR(8), \fBsu\fR(8), \fBauth_attr\fR(4),
579 \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)
580 .SH NOTES
581 .LP
582 If you inadvertently enter the \fBcrontab\fR command with no arguments, do not
583 attempt to get out with Control-d. This removes all entries in your
584 \fBcrontab\fR file. Instead, exit with Control-c.
585 .sp
586 .LP
587 When updating \fBcron\fR, check first for existing \fBcrontab\fR entries that
588 can be scheduled close to the time of the update. Such entries can be lost if
589 the update process completes after the scheduled event. This can happen
590 because, when \fBcron\fR is notified by \fBcrontab\fR to update the internal
591 view of a user's \fBcrontab\fR file, it first removes the user's existing
592 internal \fBcrontab\fR and any internal scheduled events. Then it reads the new
593 \fBcrontab\fR file and rebuilds the internal \fBcrontab\fR and events. This
594 last step takes time, especially with a large \fBcrontab\fR file, and can
595 complete \fBafter\fR an existing \fBcrontab\fR entry is scheduled to run if it
596 is scheduled too close to the update. To be safe, start a new job at least 60
597 seconds after the current date and time.
598 .sp
599 .LP
600 If an authorized user other than root modifies another user's \fBcrontab\fR
601 file, the resulting behavior can be unpredictable. Instead, the authorized user
602 should first use \fBsu\fR(8) to become superuser to the other user's login
603 before making any changes to the \fBcrontab\fR file.
604 .sp
605 .LP
606 Care should be taken when adding \fBTZ\fR, \fBSHELL\fR and \fBHOME\fR variables
607 to the \fBcrontab\fR file when the \fBcrontab\fR file could be shared with
608 applications that do not expect those variables to be changed from the default.
609 Resetting the values to their defaults at the bottom of the file will minimize
610 the risk of problems.