1.\" $NetBSD: crontab.5,v 1.3 2010/07/15 22:18:20 christos Exp $ 2.\" 3.\"/* Copyright 1988,1990,1993,1994 by Paul Vixie 4.\" * All rights reserved 5.\" * 6.\" * Distribute freely, except: don't remove my name from the source or 7.\" * documentation (don't take credit for my work), mark your changes (don't 8.\" * get me blamed for your possible bugs), don't alter or remove this 9.\" * notice. May be sold if buildable source is provided to buyer. No 10.\" * warrantee of any kind, express or implied, is included with this 11.\" * software; use at your own risk, responsibility for damages (if any) to 12.\" * anyone resulting from the use of this software rests entirely with the 13.\" * user. 14.\" * 15.\" * Send bug reports, bug fixes, enhancements, requests, flames, etc., and 16.\" * I'll try to keep a version up to date. I can be reached as follows: 17.\" * Paul Vixie <paul@vix.com> uunet!decwrl!vixie!paul 18.\" */ 19.\" 20.\" Id: crontab.5,v 2.4 1994/01/15 20:43:43 vixie Exp 21.\" 22.Dd July 15, 2010 23.Dt CRONTAB 5 24.Os 25.Sh NAME 26.Nm crontab 27.Nd tables for driving cron 28.Sh DESCRIPTION 29A 30.Nm 31file contains instructions to the 32.Xr cron 8 33daemon of the general form: 34.Dq run this command at this time on this date . 35Each user has their own crontab, and commands in any given crontab 36will be executed as the user who owns the crontab. 37Uucp and News will usually have their own crontabs, eliminating 38the need for explicitly running 39.Xr su 1 40as part of a cron command. 41.Pp 42Blank lines and leading spaces and tabs are ignored. 43Lines whose first non-space character is a pound-sign 44.Pq Sq # 45are comments, and are ignored. 46Note that comments are not allowed on the same line as cron commands, since 47they will be taken to be part of the command. 48Similarly, comments are not 49allowed on the same line as environment variable settings. 50.Pp 51An active line in a crontab will be either an environment setting 52or a cron command. 53An environment setting is of the form, 54.Bd -literal 55 name = value 56.Ed 57where the spaces around the equal-sign 58.Pq Sq = 59are optional, and any subsequent non-leading spaces in 60.Ar value 61will be part of the value assigned to 62.Ar name . 63The 64.Ar value 65string may be placed in quotes (single or double, but matching) to 66preserve leading or trailing blanks. 67The 68.Ar name 69string may also be placed in quotes (single or double, but matching) 70to preserve leading, trailing or inner blanks. 71.Pp 72Several environment variables are set up automatically by the 73.Xr cron 8 74daemon. 75.Ev SHELL 76is set to 77.Pa /bin/sh , 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 86and 87.Ev SHELL 88may be overridden by settings in the crontab; 89.Ev LOGNAME 90may not. 91.Pp 92(Another note: the 93.Ev LOGNAME 94variable is sometimes called 95.Ev USER 96on BSD systems... on these systems, 97.Ev USER 98will be set also.) 99.Pp 100In addition to 101.Ev LOGNAME , 102.Ev HOME , 103and 104.Ev SHELL , 105.Xr cron 8 106will look at 107.Ev MAILTO 108if it has any reason to send mail as a result of running commands in 109.Dq this 110crontab. 111If 112.Ev MAILTO 113is defined (and non-empty), mail is sent to the user so named. 114If 115.Ev MAILTO 116is defined but empty 117.Pq Ev MAILTO Ns = Ns \&"" , 118no mail will be sent. 119Otherwise mail is sent to the owner of the crontab. 120This option is useful if you decide on 121.Xr mail 1 122instead of 123.Xr sendmail 1 124as your mailer when you install cron -- 125.Xr mail 1 126doesn't do aliasing, and UUCP usually doesn't read its mail. 127.Pp 128In order to provide finer control over when jobs execute, users 129can also set the environment variables 130.Ev CRON_TZ 131and 132.Ev CRON_WITHIN . 133The 134.Ev CRON_TZ 135variable can be set to an alternate time zone in order to affect 136when the job is run. 137Note that this only affects the scheduling of the job, not the time 138zone that the job perceives when it is run. 139If 140.Ev CRON_TZ 141is defined but empty 142.Pq Ev CRON_TZ Ns = Ns \&"" , 143jobs are scheduled with respect to the local time zone. 144.Pp 145The 146.Ev CRON_WITHIN 147variable should indicate the number of seconds within a job's 148scheduled time that it should still be run. 149On a heavily loaded system, or on a system that has just been 150.Dq woken up , 151jobs will sometimes start later than originally intended, and by 152skipping non-critical jobs because of delays, system load can be 153lightened. 154If 155.Ev CRON_WITHIN 156is defined but empty 157.Pa Ev CRON_WITHIN Ns = Ns \&"" 158or set to some non-positive value (0, a negative number, or a 159non-numeric string), it is treated as if it was unset. 160.Pp 161The format of a cron command is very much the V7 standard, with a 162number of upward-compatible extensions. 163Each line has five time and date fields, followed by a user name 164if this is the system crontab file, followed by a command. 165Commands are executed by 166.Xr cron 8 167when the minute, hour, and month of year fields match the current 168time, 169.Em and 170when at least one of the two day fields (day of month, or day of week) 171match the current time (see 172.Dq Note 173below). 174.Xr cron 8 175examines cron entries once every minute. 176The time and date fields are: 177.Bl -column -offset indent "day of month" "0-7 (0 or 7 is Sun, or use names)" 178.It Em field Ta Em allowed values 179.It minute Ta 0-59 180.It hour Ta 0-23 181.It day of month Ta 1-31 182.It month Ta 1-12 (or names, see below) 183.It day of week Ta 0-7 (0 or 7 is Sun, or use names) 184.El 185.Pp 186A field may be an asterisk 187.Pq Sq * , 188which always stands for 189.Dq first\-last . 190.Pp 191Ranges of numbers are allowed. 192Ranges are two numbers separated with a hyphen. 193The specified range is inclusive. 194For example, 195.Dq 8-11 196for an 197.Dq hours 198entry specifies execution at hours 8, 9, 10, and 11. 199.Pp 200A field may begin with a question mark 201.Pq Sq \&? , 202which indicates a single value randomly selected when the crontab 203file is read. 204If the field contains only a question mark, the value is randomly 205selected from the range of all possible values for the field. 206If the question mark precedes a range, the value is randomly selected 207from the range. 208For example, 209.Dq ? ?2-5 * * * 210specifies that a task will be performed daily between 2:00am and 211and 5:59am at a time randomly selected when the crontab file is 212first read. 213As just one example, this feature can be used to prevent a large 214number of hosts from contacting a server simultaneously and 215overloading it by staggering the time at which a download script 216is executed. 217.Pp 218Lists are allowed. 219A list is a set of numbers (or ranges) separated by commas. 220Examples: 221.Dq 1,2,5,9 , 222.Dq 0-4,8-12 . 223.Pp 224Step values can be used in conjunction with ranges. 225Following a range with 226.Dq / Ns Aq number 227specifies skips of the number's value through the range. 228For example, 229.Dq 0-23/2 230can be used in the hours field to specify command execution every 231other hour (the alternative in the V7 standard is 232.Dq 0,2,4,6,8,10,12,14,16,18,20,22 ) . 233Steps are also permitted after an asterisk, so if you want to say 234.Dq every two hours , 235just use 236.Dq */2 . 237.Pp 238Names can also be used for the 239.Dq month 240and 241.Dq day of week 242fields. 243Use the first three letters of the particular day or month (case 244doesn't matter). 245Ranges or lists of names are not allowed. 246.Pp 247If the 248.Nm 249file is the system crontab 250.Pa /etc/crontab , 251then the next ( 252.Dq sixth ) 253field contains the username to run the command as. 254.Pp 255The 256.Dq sixth 257field (or the 258.Dq seventh 259one for 260.Pa /etc/crontab ) 261(the rest of the line) specifies the command to be run. 262The entire command portion of the line, up to a newline or percent 263signs 264.Pq Sq % , 265will be executed by 266.Xr sh 1 267or by the shell specified in the 268.Ev SHELL 269variable of the cronfile. 270Percent signs 271.Pq Sq % 272in the command, unless escaped with backslash 273.Pq Sq \e , 274will be changed into newline characters, and all data after the 275first % will be sent to the command as standard input. 276.Pp 277.Em Note : 278The day of a command's execution can be specified by two fields 279\(em day of month, and day of week. 280If both fields are restricted (i.e., aren't *), the command will 281be run when 282.Em either 283field matches the current time. 284For example, 285.Dq 30 4 1,15 * 5 286would cause a command to be run at 4:30 am on the 1st and 15th of 287each month, plus every Friday. 288.Pp 289Instead of the first five fields, one of eight special strings may appear: 290.Bl -column -offset indent "@annually" "Run once a month, 0 0 1 * *." 291.It Sy string Ta Sy meaning 292.It @reboot Ta Run once, at startup. 293.It @yearly Ta Run once a year, Dq 0 0 1 1 * . 294.It @annually Ta (same as @yearly) 295.It @monthly Ta Run once a month, Dq 0 0 1 * * . 296.It @weekly Ta Run once a week, Dq 0 0 * * 0 . 297.It @daily Ta Run once a day, Dq 0 0 * * * . 298.It @midnight Ta (same as @daily) 299.It @hourly Ta Run once an hour, Dq 0 * * * * . 300.El 301.Ss EXAMPLE CRON FILE 302.Bd -literal 303# use /bin/sh to run commands, no matter what /etc/passwd says 304SHELL=/bin/sh 305# mail any output to `paul', no matter whose crontab this is 306MAILTO=paul 307# 308# run five minutes after midnight, every day 3095 0 * * * $HOME/bin/daily.job \*[Gt]\*[Gt] $HOME/tmp/out 2\*[Gt]\*[Am]1 310# run at 2:15pm on the first of every month -- output mailed to paul 31115 14 1 * * $HOME/bin/monthly 312# run at 10 pm on weekdays, annoy Joe 3130 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?% 31423 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" 3155 4 * * sun echo "run at 5 after 4 every sunday" 316? ?2-4 1,15 * * echo "random between 2am-4:59am on the 1st and 15th" 317.Ed 318.Sh SEE ALSO 319.Xr crontab 1 , 320.Xr cron 8 321.Sh STANDARDS 322When specifying day of week, both day 0 and day 7 will be considered 323Sunday. 324BSD and ATT seem to disagree about this. 325.Pp 326Lists and ranges are allowed to co-exist in the same field. 327.Dq 1-3,7-9 328would be rejected by ATT or BSD cron -- they want to see 329.Dq 1-3 330or 331.Dq 7,8,9 332ONLY. 333.Pp 334Ranges can include 335.Dq steps , 336so 337.Dq 1-9/2 338is the same as 339.Dq 1,3,5,7,9 . 340.Pp 341Names of months or days of the week can be specified by name. 342.Pp 343Environment variables can be set in the crontab. 344In BSD or ATT, the environment handed to child processes is basically 345the one from 346.Pa /etc/rc . 347.Pp 348Command output is mailed to the crontab owner (BSD can't do this), 349can be mailed to a person other than the crontab owner (SysV can't 350do this), or the feature can be turned off and no mail will be sent 351at all (SysV can't do this either). 352.Pp 353All of the 354.Sq @ 355commands that can appear in place of the first five fields are 356extensions. 357.Sh AUTHORS 358.An Paul Vixie Aq paul@vix.com 359