xref: /freebsd/usr.sbin/cron/crontab/crontab.5 (revision 8030199c715acbdefbd86da9d28098bebf8bb143)
184f33deaSJordan K. Hubbard.\"/* Copyright 1988,1990,1993,1994 by Paul Vixie
284f33deaSJordan K. Hubbard.\" * All rights reserved
384f33deaSJordan K. Hubbard.\" *
484f33deaSJordan K. Hubbard.\" * Distribute freely, except: don't remove my name from the source or
584f33deaSJordan K. Hubbard.\" * documentation (don't take credit for my work), mark your changes (don't
684f33deaSJordan K. Hubbard.\" * get me blamed for your possible bugs), don't alter or remove this
784f33deaSJordan K. Hubbard.\" * notice.  May be sold if buildable source is provided to buyer.  No
884f33deaSJordan K. Hubbard.\" * warrantee of any kind, express or implied, is included with this
984f33deaSJordan K. Hubbard.\" * software; use at your own risk, responsibility for damages (if any) to
1084f33deaSJordan K. Hubbard.\" * anyone resulting from the use of this software rests entirely with the
1184f33deaSJordan K. Hubbard.\" * user.
1284f33deaSJordan K. Hubbard.\" *
1384f33deaSJordan K. Hubbard.\" * Send bug reports, bug fixes, enhancements, requests, flames, etc., and
1484f33deaSJordan K. Hubbard.\" * I'll try to keep a version up to date.  I can be reached as follows:
1584f33deaSJordan K. Hubbard.\" * Paul Vixie          <paul@vix.com>          uunet!decwrl!vixie!paul
1684f33deaSJordan K. Hubbard.\" */
1784f33deaSJordan K. Hubbard.\"
1897d92980SPeter Wemm.\" $FreeBSD$
1984f33deaSJordan K. Hubbard.\"
20401e6468SPhilippe Charnier.Dd January 24, 1994
21401e6468SPhilippe Charnier.Dt CRONTAB 5
22401e6468SPhilippe Charnier.Os
23401e6468SPhilippe Charnier.Sh NAME
24401e6468SPhilippe Charnier.Nm crontab
25401e6468SPhilippe Charnier.Nd tables for driving cron
26401e6468SPhilippe Charnier.Sh DESCRIPTION
2784f33deaSJordan K. HubbardA
28401e6468SPhilippe Charnier.Nm
2984f33deaSJordan K. Hubbardfile contains instructions to the
30401e6468SPhilippe Charnier.Xr cron 8
3184f33deaSJordan K. Hubbarddaemon of the general form: ``run this command at this time on this date''.
3284f33deaSJordan K. HubbardEach user has their own crontab, and commands in any given crontab will be
3384f33deaSJordan K. Hubbardexecuted as the user who owns the crontab.  Uucp and News will usually have
3484f33deaSJordan K. Hubbardtheir own crontabs, eliminating the need for explicitly running
35401e6468SPhilippe Charnier.Xr su 1
3684f33deaSJordan K. Hubbardas part of a cron command.
37401e6468SPhilippe Charnier.Pp
3884f33deaSJordan K. HubbardBlank lines and leading spaces and tabs are ignored.  Lines whose first
3984f33deaSJordan K. Hubbardnon-space character is a pound-sign (#) are comments, and are ignored.
4084f33deaSJordan K. HubbardNote that comments are not allowed on the same line as cron commands, since
4184f33deaSJordan K. Hubbardthey will be taken to be part of the command.  Similarly, comments are not
4284f33deaSJordan K. Hubbardallowed on the same line as environment variable settings.
43401e6468SPhilippe Charnier.Pp
4484f33deaSJordan K. HubbardAn active line in a crontab will be either an environment setting or a cron
4584f33deaSJordan K. Hubbardcommand.  An environment setting is of the form,
46c5083414SRuslan Ermilov.Bd -literal
4784f33deaSJordan K. Hubbard    name = value
48c5083414SRuslan Ermilov.Ed
49401e6468SPhilippe Charnier.Pp
5084f33deaSJordan K. Hubbardwhere the spaces around the equal-sign (=) are optional, and any subsequent
5184f33deaSJordan K. Hubbardnon-leading spaces in
52401e6468SPhilippe Charnier.Em value
5384f33deaSJordan K. Hubbardwill be part of the value assigned to
54401e6468SPhilippe Charnier.Em name .
5584f33deaSJordan K. HubbardThe
56401e6468SPhilippe Charnier.Em value
5784f33deaSJordan K. Hubbardstring may be placed in quotes (single or double, but matching) to preserve
5884f33deaSJordan K. Hubbardleading or trailing blanks.
59c3e1da6bSSheldon HearnThe
60c3e1da6bSSheldon Hearn.Em name
61c3e1da6bSSheldon Hearnstring may also be placed in quote (single or double, but matching)
6257bd0fc6SJens Schweikhardtto preserve leading, trailing or inner blanks.
63401e6468SPhilippe Charnier.Pp
6484f33deaSJordan K. HubbardSeveral environment variables are set up
6584f33deaSJordan K. Hubbardautomatically by the
66401e6468SPhilippe Charnier.Xr cron 8
6784f33deaSJordan K. Hubbarddaemon.
68401e6468SPhilippe Charnier.Ev SHELL
69401e6468SPhilippe Charnieris set to
70401e6468SPhilippe Charnier.Pa /bin/sh ,
71401e6468SPhilippe Charnierand
72401e6468SPhilippe Charnier.Ev LOGNAME
73401e6468SPhilippe Charnierand
74401e6468SPhilippe Charnier.Ev HOME
75401e6468SPhilippe Charnierare set from the
76401e6468SPhilippe Charnier.Pa /etc/passwd
7784f33deaSJordan K. Hubbardline of the crontab's owner.
78401e6468SPhilippe Charnier.Ev HOME
79401e6468SPhilippe Charnierand
80401e6468SPhilippe Charnier.Ev SHELL
81401e6468SPhilippe Charniermay be overridden by settings in the crontab;
82401e6468SPhilippe Charnier.Ev LOGNAME
83401e6468SPhilippe Charniermay not.
84401e6468SPhilippe Charnier.Pp
85401e6468SPhilippe Charnier(Another note: the
86401e6468SPhilippe Charnier.Ev LOGNAME
87401e6468SPhilippe Charniervariable is sometimes called
88401e6468SPhilippe Charnier.Ev USER
89753d686dSRuslan Ermilovon
90753d686dSRuslan Ermilov.Bx
91753d686dSRuslan Ermilovsystems...
92c75526d5SRuslan ErmilovOn these systems,
93401e6468SPhilippe Charnier.Ev USER
94401e6468SPhilippe Charnierwill be set also).
95401e6468SPhilippe Charnier.Pp
96401e6468SPhilippe CharnierIn addition to
97401e6468SPhilippe Charnier.Ev LOGNAME ,
98401e6468SPhilippe Charnier.Ev HOME ,
99401e6468SPhilippe Charnierand
100401e6468SPhilippe Charnier.Ev SHELL ,
101401e6468SPhilippe Charnier.Xr cron 8
102401e6468SPhilippe Charnierwill look at
103401e6468SPhilippe Charnier.Ev MAILTO
104401e6468SPhilippe Charnierif it has any reason to send mail as a result of running
105401e6468SPhilippe Charniercommands in ``this'' crontab.  If
106401e6468SPhilippe Charnier.Ev MAILTO
107401e6468SPhilippe Charnieris defined (and non-empty), mail is
1088030199cSTom Rhodessent to the user so named.
1098030199cSTom Rhodes.Ev MAILTO
1108030199cSTom Rhodesmay also be used to direct mail to multiple recipients
1118030199cSTom Rhodesby seperating recipient users with a comma.
1128030199cSTom RhodesIf
113401e6468SPhilippe Charnier.Ev MAILTO
114401e6468SPhilippe Charnieris defined but empty (MAILTO=""), no
11584f33deaSJordan K. Hubbardmail will be sent.  Otherwise mail is sent to the owner of the crontab.  This
116401e6468SPhilippe Charnieroption is useful if you decide on
117401e6468SPhilippe Charnier.Pa /bin/mail
118401e6468SPhilippe Charnierinstead of
119401e6468SPhilippe Charnier.Pa /usr/lib/sendmail
120401e6468SPhilippe Charnieras
121401e6468SPhilippe Charnieryour mailer when you install cron --
122401e6468SPhilippe Charnier.Pa /bin/mail
123401e6468SPhilippe Charnierdoesn't do aliasing, and UUCP
12484f33deaSJordan K. Hubbardusually doesn't read its mail.
125401e6468SPhilippe Charnier.Pp
12684f33deaSJordan K. HubbardThe format of a cron command is very much the V7 standard, with a number of
12784f33deaSJordan K. Hubbardupward-compatible extensions.  Each line has five time and date fields,
1280435c150SAndrey A. Chernovfollowed by a user name
1290435c150SAndrey A. Chernov(with optional ``:<group>'' and ``/<login-class>'' suffixes)
1300435c150SAndrey A. Chernovif this is the system crontab file,
13184f33deaSJordan K. Hubbardfollowed by a command.  Commands are executed by
132401e6468SPhilippe Charnier.Xr cron 8
13384f33deaSJordan K. Hubbardwhen the minute, hour, and month of year fields match the current time,
134401e6468SPhilippe Charnier.Em and
13584f33deaSJordan K. Hubbardwhen at least one of the two day fields (day of month, or day of week)
1364188e025SGiorgos Keramidasmatches the current time (see ``Note'' below).
137401e6468SPhilippe Charnier.Xr cron 8
13884f33deaSJordan K. Hubbardexamines cron entries once every minute.
13984f33deaSJordan K. HubbardThe time and date fields are:
140401e6468SPhilippe Charnier.Bd -literal -offset indent
14184f33deaSJordan K. Hubbardfield         allowed values
14284f33deaSJordan K. Hubbard-----         --------------
14384f33deaSJordan K. Hubbardminute        0-59
14484f33deaSJordan K. Hubbardhour          0-23
145043c578eSMike Pritchardday of month  1-31
146043c578eSMike Pritchardmonth         1-12 (or names, see below)
14784f33deaSJordan K. Hubbardday of week   0-7 (0 or 7 is Sun, or use names)
148401e6468SPhilippe Charnier.Ed
149401e6468SPhilippe Charnier.Pp
15084f33deaSJordan K. HubbardA field may be an asterisk (*), which always stands for ``first\-last''.
151401e6468SPhilippe Charnier.Pp
15284f33deaSJordan K. HubbardRanges of numbers are allowed.  Ranges are two numbers separated
15384f33deaSJordan K. Hubbardwith a hyphen.  The specified range is inclusive.  For example,
15484f33deaSJordan K. Hubbard8-11 for an ``hours'' entry specifies execution at hours 8, 9, 10
15584f33deaSJordan K. Hubbardand 11.
156401e6468SPhilippe Charnier.Pp
15784f33deaSJordan K. HubbardLists are allowed.  A list is a set of numbers (or ranges)
15884f33deaSJordan K. Hubbardseparated by commas.  Examples: ``1,2,5,9'', ``0-4,8-12''.
159401e6468SPhilippe Charnier.Pp
16084f33deaSJordan K. HubbardStep values can be used in conjunction with ranges.  Following
16184f33deaSJordan K. Hubbarda range with ``/<number>'' specifies skips of the number's value
16284f33deaSJordan K. Hubbardthrough the range.  For example, ``0-23/2'' can be used in the hours
16384f33deaSJordan K. Hubbardfield to specify command execution every other hour (the alternative
16484f33deaSJordan K. Hubbardin the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22'').  Steps are
16584f33deaSJordan K. Hubbardalso permitted after an asterisk, so if you want to say ``every two
16684f33deaSJordan K. Hubbardhours'', just use ``*/2''.
167401e6468SPhilippe Charnier.Pp
16884f33deaSJordan K. HubbardNames can also be used for the ``month'' and ``day of week''
16984f33deaSJordan K. Hubbardfields.  Use the first three letters of the particular
17084f33deaSJordan K. Hubbardday or month (case doesn't matter).  Ranges or
17184f33deaSJordan K. Hubbardlists of names are not allowed.
172401e6468SPhilippe Charnier.Pp
17384f33deaSJordan K. HubbardThe ``sixth'' field (the rest of the line) specifies the command to be
17484f33deaSJordan K. Hubbardrun.
17584f33deaSJordan K. HubbardThe entire command portion of the line, up to a newline or %
176401e6468SPhilippe Charniercharacter, will be executed by
177401e6468SPhilippe Charnier.Pa /bin/sh
178401e6468SPhilippe Charnieror by the shell
179401e6468SPhilippe Charnierspecified in the
180401e6468SPhilippe Charnier.Ev SHELL
181401e6468SPhilippe Charniervariable of the cronfile.
18284f33deaSJordan K. HubbardPercent-signs (%) in the command, unless escaped with backslash
18384f33deaSJordan K. Hubbard(\\), will be changed into newline characters, and all data
18484f33deaSJordan K. Hubbardafter the first % will be sent to the command as standard
18584f33deaSJordan K. Hubbardinput.
186401e6468SPhilippe Charnier.Pp
18784f33deaSJordan K. HubbardNote: The day of a command's execution can be specified by two
18884f33deaSJordan K. Hubbardfields \(em day of month, and day of week.  If both fields are
18984f33deaSJordan K. Hubbardrestricted (ie, aren't *), the command will be run when
190401e6468SPhilippe Charnier.Em either
19184f33deaSJordan K. Hubbardfield matches the current time.  For example,
19284f33deaSJordan K. Hubbard``30 4 1,15 * 5''
19384f33deaSJordan K. Hubbardwould cause a command to be run at 4:30 am on the 1st and 15th of each
19484f33deaSJordan K. Hubbardmonth, plus every Friday.
195c3e1da6bSSheldon Hearn.Pp
196c3e1da6bSSheldon HearnInstead of the first five fields,
197c3e1da6bSSheldon Hearnone of eight special strings may appear:
198c3e1da6bSSheldon Hearn.Bd -literal -offset indent
199c3e1da6bSSheldon Hearnstring		meaning
200c3e1da6bSSheldon Hearn------		-------
201c3e1da6bSSheldon Hearn@reboot		Run once, at startup.
202c3e1da6bSSheldon Hearn@yearly		Run once a year, "0 0 1 1 *".
203fd522d40SBill Fumerola@annually	(same as @yearly)
204c3e1da6bSSheldon Hearn@monthly	Run once a month, "0 0 1 * *".
205c3e1da6bSSheldon Hearn@weekly		Run once a week, "0 0 * * 0".
206c3e1da6bSSheldon Hearn@daily		Run once a day, "0 0 * * *".
207c3e1da6bSSheldon Hearn@midnight	(same as @daily)
208c3e1da6bSSheldon Hearn@hourly		Run once an hour, "0 * * * *".
209c3e1da6bSSheldon Hearn.Ed
210401e6468SPhilippe Charnier.Sh EXAMPLE CRON FILE
211401e6468SPhilippe Charnier.Bd -literal
21284f33deaSJordan K. Hubbard
213d2a864e4SNick Hibma# use /bin/sh to run commands, overriding the default set by cron
21484f33deaSJordan K. HubbardSHELL=/bin/sh
21584f33deaSJordan K. Hubbard# mail any output to `paul', no matter whose crontab this is
21684f33deaSJordan K. HubbardMAILTO=paul
21784f33deaSJordan K. Hubbard#
21884f33deaSJordan K. Hubbard# run five minutes after midnight, every day
21984f33deaSJordan K. Hubbard5 0 * * *       $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
22084f33deaSJordan K. Hubbard# run at 2:15pm on the first of every month -- output mailed to paul
22184f33deaSJordan K. Hubbard15 14 1 * *     $HOME/bin/monthly
22284f33deaSJordan K. Hubbard# run at 10 pm on weekdays, annoy Joe
22384f33deaSJordan K. Hubbard0 22 * * 1-5	mail -s "It's 10pm" joe%Joe,%%Where are your kids?%
22484f33deaSJordan K. Hubbard23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday"
22584f33deaSJordan K. Hubbard5 4 * * sun     echo "run at 5 after 4 every sunday"
226401e6468SPhilippe Charnier.Ed
227401e6468SPhilippe Charnier.Sh SEE ALSO
228bf5cbf35SWolfram Schneider.Xr crontab 1 ,
229bf5cbf35SWolfram Schneider.Xr cron 8
230401e6468SPhilippe Charnier.Sh EXTENSIONS
23184f33deaSJordan K. HubbardWhen specifying day of week, both day 0 and day 7 will be considered Sunday.
232753d686dSRuslan Ermilov.Bx
233753d686dSRuslan Ermilovand
234753d686dSRuslan Ermilov.Tn ATT
235753d686dSRuslan Ermilovseem to disagree about this.
236401e6468SPhilippe Charnier.Pp
23784f33deaSJordan K. HubbardLists and ranges are allowed to co-exist in the same field.  "1-3,7-9" would
238753d686dSRuslan Ermilovbe rejected by
239753d686dSRuslan Ermilov.Tn ATT
240753d686dSRuslan Ermilovor
241753d686dSRuslan Ermilov.Bx
242753d686dSRuslan Ermilovcron -- they want to see "1-3" or "7,8,9" ONLY.
243401e6468SPhilippe Charnier.Pp
24484f33deaSJordan K. HubbardRanges can include "steps", so "1-9/2" is the same as "1,3,5,7,9".
245401e6468SPhilippe Charnier.Pp
24684f33deaSJordan K. HubbardNames of months or days of the week can be specified by name.
247401e6468SPhilippe Charnier.Pp
248753d686dSRuslan ErmilovEnvironment variables can be set in the crontab.  In
249753d686dSRuslan Ermilov.Bx
250753d686dSRuslan Ermilovor
251753d686dSRuslan Ermilov.Tn ATT ,
252753d686dSRuslan Ermilovthe
253401e6468SPhilippe Charnierenvironment handed to child processes is basically the one from
254401e6468SPhilippe Charnier.Pa /etc/rc .
255401e6468SPhilippe Charnier.Pp
256753d686dSRuslan ErmilovCommand output is mailed to the crontab owner
257753d686dSRuslan Ermilov.No ( Bx
258753d686dSRuslan Ermilovcan't do this), can be
25984f33deaSJordan K. Hubbardmailed to a person other than the crontab owner (SysV can't do this), or the
26084f33deaSJordan K. Hubbardfeature can be turned off and no mail will be sent at all (SysV can't do this
26184f33deaSJordan K. Hubbardeither).
262c3e1da6bSSheldon Hearn.Pp
263c3e1da6bSSheldon HearnAll of the
264c3e1da6bSSheldon Hearn.Sq @
265c3e1da6bSSheldon Hearncommands that can appear in place of the first five fields
266c3e1da6bSSheldon Hearnare extensions.
267f12a1471SPhilippe Charnier.Sh AUTHORS
268401e6468SPhilippe Charnier.An Paul Vixie Aq paul@vix.com
26981f4b036SSheldon Hearn.Sh BUGS
27081f4b036SSheldon HearnIf you're in one of the 70-odd countries that observe Daylight
27181f4b036SSheldon HearnSavings Time, jobs scheduled during the rollback or advance will be
27281f4b036SSheldon Hearnaffected.  In general, it's not a good idea to schedule jobs during
27381f4b036SSheldon Hearnthis period.
27481f4b036SSheldon Hearn.Pp
27581f4b036SSheldon HearnFor US timezones (except parts of IN, AZ, and HI) the time shift occurs at
27681f4b036SSheldon Hearn2AM local time.  For others, the output of the
27781f4b036SSheldon Hearn.Xr zdump 8
27881f4b036SSheldon Hearnprogram's verbose
27981f4b036SSheldon Hearn.Fl ( v )
28081f4b036SSheldon Hearnoption can be used to determine the moment of time shift.
281