xref: /freebsd/usr.sbin/cron/crontab/crontab.5 (revision f6a3b357e9be4c6423c85eff9a847163a0d307c8)
1.\"/* Copyright 1988,1990,1993,1994 by Paul Vixie
2.\" * All rights reserved
3.\" *
4.\" * Distribute freely, except: don't remove my name from the source or
5.\" * documentation (don't take credit for my work), mark your changes (don't
6.\" * get me blamed for your possible bugs), don't alter or remove this
7.\" * notice.  May be sold if buildable source is provided to buyer.  No
8.\" * warrantee of any kind, express or implied, is included with this
9.\" * software; use at your own risk, responsibility for damages (if any) to
10.\" * anyone resulting from the use of this software rests entirely with the
11.\" * user.
12.\" *
13.\" * Send bug reports, bug fixes, enhancements, requests, flames, etc., and
14.\" * I'll try to keep a version up to date.  I can be reached as follows:
15.\" * Paul Vixie          <paul@vix.com>          uunet!decwrl!vixie!paul
16.\" */
17.\"
18.\" $FreeBSD$
19.\"
20.Dd April 19, 2019
21.Dt CRONTAB 5
22.Os
23.Sh NAME
24.Nm crontab
25.Nd tables for driving cron
26.Sh DESCRIPTION
27A
28.Nm
29file contains instructions to the
30.Xr cron 8
31daemon of the general form: ``run this command at this time on this date''.
32Each user has their own crontab, and commands in any given crontab will be
33executed as the user who owns the crontab.
34Uucp and News will usually have
35their own crontabs, eliminating the need for explicitly running
36.Xr su 1
37as part of a cron command.
38.Pp
39Blank lines and leading spaces and tabs are ignored.
40Lines whose first
41non-space character is a pound-sign (#) are comments, and are ignored.
42Note that comments are not allowed on the same line as cron commands, since
43they will be taken to be part of the command.
44Similarly, comments are not
45allowed on the same line as environment variable settings.
46.Pp
47An active line in a crontab will be either an environment setting or a cron
48command.
49An environment setting is of the form,
50.Bd -literal
51    name = value
52.Ed
53.Pp
54where the spaces around the equal-sign (=) are optional, and any subsequent
55non-leading spaces in
56.Em value
57will be part of the value assigned to
58.Em name .
59The
60.Em value
61string may be placed in quotes (single or double, but matching) to preserve
62leading or trailing blanks.
63The
64.Em name
65string may also be placed in quote (single or double, but matching)
66to preserve leading, trailing or inner blanks.
67.Pp
68Several environment variables are set up
69automatically by the
70.Xr cron 8
71daemon.
72.Ev SHELL
73is set to
74.Pa /bin/sh ,
75.Ev PATH
76is set to
77.Pa /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin ,
78and
79.Ev LOGNAME
80and
81.Ev HOME
82are set from the
83.Pa /etc/passwd
84line of the crontab's owner.
85.Ev HOME ,
86.Ev PATH
87and
88.Ev SHELL
89may be overridden by settings in the crontab;
90.Ev LOGNAME
91may not.
92.Pp
93(Another note: the
94.Ev LOGNAME
95variable is sometimes called
96.Ev USER
97on
98.Bx
99systems...
100On these systems,
101.Ev USER
102will be set also).
103.Pp
104In addition to
105.Ev LOGNAME ,
106.Ev HOME ,
107.Ev PATH ,
108and
109.Ev SHELL ,
110.Xr cron 8
111will look at
112.Ev MAILTO
113if it has any reason to send mail as a result of running
114commands in ``this'' crontab.
115If
116.Ev MAILTO
117is defined (and non-empty), mail is
118sent to the user so named.
119If
120.Ev MAILFROM
121is defined (and non-empty), its value will be used as the from address.
122.Ev MAILTO
123may also be used to direct mail to multiple recipients
124by separating recipient users with a comma.
125If
126.Ev MAILTO
127is defined but empty (MAILTO=""), no
128mail will be sent.
129Otherwise mail is sent to the owner of the crontab.
130This
131option is useful if you decide on
132.Pa /bin/mail
133instead of
134.Pa /usr/lib/sendmail
135as
136your mailer when you install cron --
137.Pa /bin/mail
138does not do aliasing, and UUCP
139usually does not read its mail.
140.Pp
141The format of a cron command is very much the V7 standard, with a number of
142upward-compatible extensions.
143Each line has five time and date fields,
144followed by a user name
145(with optional ``:<group>'' and ``/<login-class>'' suffixes)
146if this is the system crontab file,
147followed by a command.
148Commands are executed by
149.Xr cron 8
150when the minute, hour, and month of year fields match the current time,
151.Em and
152when at least one of the two day fields (day of month, or day of week)
153matches the current time (see ``Note'' below).
154.Xr cron 8
155examines cron entries once every minute.
156The time and date fields are:
157.Bd -literal -offset indent
158field         allowed values
159-----         --------------
160minute        0-59
161hour          0-23
162day of month  1-31
163month         1-12 (or names, see below)
164day of week   0-7 (0 or 7 is Sun, or use names)
165.Ed
166.Pp
167A field may be an asterisk (*), which always stands for ``first\-last''.
168.Pp
169Ranges of numbers are allowed.
170Ranges are two numbers separated
171with a hyphen.
172The specified range is inclusive.
173For example,
1748-11 for an ``hours'' entry specifies execution at hours 8, 9, 10
175and 11.
176.Pp
177Lists are allowed.
178A list is a set of numbers (or ranges)
179separated by commas.
180Examples: ``1,2,5,9'', ``0-4,8-12''.
181.Pp
182Step values can be used in conjunction with ranges.
183Following
184a range with ``/<number>'' specifies skips of the number's value
185through the range.
186For example, ``0-23/2'' can be used in the hours
187field to specify command execution every other hour (the alternative
188in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22'').
189Steps are
190also permitted after an asterisk, so if you want to say ``every two
191hours'', just use ``*/2''.
192.Pp
193Names can also be used for the ``month'' and ``day of week''
194fields.
195Use the first three letters of the particular
196day or month (case does not matter).
197Ranges or
198lists of names are not allowed.
199.Pp
200The ``sixth'' field (the rest of the line) specifies the command to be
201run.
202The entire command portion of the line, up to a newline or %
203character, will be executed by
204.Pa /bin/sh
205or by the shell
206specified in the
207.Ev SHELL
208variable of the cronfile.
209Percent-signs (%) in the command, unless escaped with backslash
210(\\), will be changed into newline characters, and all data
211after the first % will be sent to the command as standard
212input.
213.Pp
214Note: The day of a command's execution can be specified by two
215fields \(em day of month, and day of week.
216If both fields are
217restricted (ie, are not *), the command will be run when
218.Em either
219field matches the current time.
220For example,
221``30 4 1,15 * 5''
222would cause a command to be run at 4:30 am on the 1st and 15th of each
223month, plus every Friday.
224.Pp
225Instead of the first five fields,
226a line may start with
227.Sq @
228symbol followed either by one of eight special strings or by a numeric value.
229The recognized special strings are:
230.Bd -literal -offset indent
231string		meaning
232------		-------
233@reboot		Run once, at startup of cron.
234@yearly		Run once a year, "0 0 1 1 *".
235@annually	(same as @yearly)
236@monthly	Run once a month, "0 0 1 * *".
237@weekly		Run once a week, "0 0 * * 0".
238@daily		Run once a day, "0 0 * * *".
239@midnight	(same as @daily)
240@hourly		Run once an hour, "0 * * * *".
241@every_minute	Run once a minute, "*/1 * * * *".
242@every_second	Run once a second.
243.Ed
244.Pp
245The
246.Sq @
247symbol followed by a numeric value has a special notion of running
248a job that many seconds after completion of the previous invocation of
249the job.
250Unlike regular syntax, it guarantees not to overlap two or more
251invocations of the same job during normal cron execution.
252Note, however, that overlap may occur if the job is running when the file
253containing the job is modified and subsequently reloaded.
254The first run is scheduled for the specified number of seconds after cron
255is started or the crontab entry is reloaded.
256.Sh EXAMPLE CRON FILE
257.Bd -literal
258
259# use /bin/sh to run commands, overriding the default set by cron
260SHELL=/bin/sh
261# mail any output to `paul', no matter whose crontab this is
262MAILTO=paul
263#
264# run five minutes after midnight, every day
2655 0 * * *       $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
266# run at 2:15pm on the first of every month -- output mailed to paul
26715 14 1 * *     $HOME/bin/monthly
268# run at 10 pm on weekdays, annoy Joe
2690 22 * * 1-5	mail -s "It's 10pm" joe%Joe,%%Where are your kids?%
27023 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday"
2715 4 * * sun     echo "run at 5 after 4 every sunday"
272# run at 5 minutes intervals, no matter how long it takes
273@300		svnlite up /usr/src
274.Ed
275.Sh SEE ALSO
276.Xr crontab 1 ,
277.Xr cron 8
278.Sh EXTENSIONS
279When specifying day of week, both day 0 and day 7 will be considered Sunday.
280.Bx
281and
282.Tn ATT
283seem to disagree about this.
284.Pp
285Lists and ranges are allowed to co-exist in the same field.
286"1-3,7-9" would
287be rejected by
288.Tn ATT
289or
290.Bx
291cron -- they want to see "1-3" or "7,8,9" ONLY.
292.Pp
293Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9".
294.Pp
295Names of months or days of the week can be specified by name.
296.Pp
297Environment variables can be set in the crontab.
298In
299.Bx
300or
301.Tn ATT ,
302the
303environment handed to child processes is basically the one from
304.Pa /etc/rc .
305.Pp
306Command output is mailed to the crontab owner
307.No ( Bx
308cannot do this), can be
309mailed to a person other than the crontab owner (SysV cannot do this), or the
310feature can be turned off and no mail will be sent at all (SysV cannot do this
311either).
312.Pp
313All of the
314.Sq @
315directives that can appear in place of the first five fields
316are extensions.
317.Sh AUTHORS
318.An Paul Vixie Aq Mt paul@vix.com
319.Sh BUGS
320If you are in one of the 70-odd countries that observe Daylight
321Savings Time, jobs scheduled during the rollback or advance may be
322affected if
323.Xr cron 8
324is not started with the
325.Fl s
326flag.
327In general, it is not a good idea to schedule jobs during
328this period if
329.Xr cron 8
330is not started with the
331.Fl s
332flag, which is enabled by default.
333See
334.Xr cron 8
335for more details.
336.Pp
337For US timezones (except parts of AZ and HI) the time shift occurs at
3382AM local time.
339For others, the output of the
340.Xr zdump 8
341program's verbose
342.Fl ( v )
343option can be used to determine the moment of time shift.
344