1.\"/* Copyright 1988,1990,1993,1994 by Paul Vixie 2.\" * All rights reserved 3.\" */ 4.\" 5.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") 6.\" Copyright (c) 1997,2000 by Internet Software Consortium, Inc. 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT 18.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.\" $OpenBSD: crontab.5,v 1.21 2007/05/31 19:20:23 jmc Exp $ 21.\" 22.Dd $Mdocdate: May 31 2007 $ 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.Do 35at these times on these dates run this command 36.Dc . 37There may be a system 38.Nm 39.Pf ( Pa /etc/crontab ) 40and each user may have their own 41.Nm 42.Pf ( Pa /var/cron/tabs/<user> ) . 43Commands in any given 44.Nm 45will be 46executed either as the user who owns the 47.Nm 48or, in the case of the system 49.Nm crontab , 50as the user specified in the command line. 51Uucp and News will usually each have 52their own 53.Nm crontab , 54eliminating the need for explicitly running 55.Xr su 1 56as part of a 57.Xr cron 8 58command. 59.Pp 60While a 61.Nm 62is a text file, it is not intended to be directly edited. 63Creation, modification, and removal of a 64.Nm 65should be done using 66.Xr crontab 1 . 67.Pp 68Blank lines, leading spaces, and tabs are ignored. 69Lines whose first non-space character is a pound sign 70.Pq Ql # 71are comments, and are ignored. 72Note that comments are not allowed on the same line as 73.Xr cron 8 74commands, since 75they will be taken to be part of the command. 76Similarly, comments are not 77allowed on the same line as environment variable settings. 78.Pp 79An active line in a 80.Nm 81is either an environment variable setting or a 82.Xr cron 8 83command. 84.Pp 85.Em Environment Variable Settings 86.Pp 87Environment variable settings create the environment 88any command in the 89.Nm 90is run in. 91An environment variable setting is of the form: 92.Pp 93.Dl name \&= value 94.Pp 95where the spaces around the equal-sign 96.Pq Ql = 97are optional, and any subsequent non-leading spaces in 98.Fa value 99will be part of the value assigned to 100.Fa name . 101The 102.Fa value 103string may be placed in quotes 104.Pq single or double , but matching 105to preserve leading or trailing blanks. 106.Pp 107Several environment variables are set automatically by the 108.Xr cron 8 109daemon. 110.Ev SHELL 111is set to 112.Pa /bin/sh , 113and 114.Ev LOGNAME 115and 116.Ev HOME 117are set from the 118.Pa /etc/passwd 119line of the 120.Nm crontab Ns \&'s 121owner. 122.Ev HOME 123and 124.Ev SHELL 125may be overridden by settings in the 126.Nm crontab ; 127.Ev LOGNAME 128may not. 129.Pp 130Note: on BSD systems the 131.Ev LOGNAME 132variable is sometimes called 133.Ev USER . 134On 135.Ox , 136.Xr cron 8 137will set both 138.Ev USER 139and 140.Ev LOGNAME 141to the same value. 142.Pp 143In addition to 144.Ev LOGNAME , 145.Ev HOME , 146and 147.Ev SHELL , 148.Xr cron 8 149will look at 150.Ev MAILTO 151if it has any reason to send mail as a result of running 152commands in 153.Dq this 154.Nm crontab . 155If 156.Ev MAILTO 157is defined (and non-empty), 158mail is sent to the user so named. 159If 160.Ev MAILTO 161is defined but empty 162.Pq Ev MAILTO \&= Sq , 163no 164mail will be sent. 165Otherwise mail is sent to the owner of the 166.Nm crontab . 167This option is useful for pseudo-users that lack an alias 168that would otherwise redirect the mail to a real person. 169.Pp 170.Em cron Commands 171.Pp 172The format of a 173.Xr cron 8 174command is very much the V7 standard, with a number of 175upward-compatible extensions. 176Lines in the system 177.Nm 178have six fixed fields plus a command in the form: 179.Bd -ragged -offset indent 180.Ar minute 181.Ar hour 182.Ar day\-of\-month 183.Ar month 184.Ar day\-of\-week 185.Ar user 186.Ar command 187.Ed 188.Pp 189While lines in a user 190.Nm 191have five fixed fields plus a command in the form: 192.Bd -ragged -offset indent 193.Ar minute 194.Ar hour 195.Ar day\-of\-month 196.Ar month 197.Ar day\-of\-week 198.Ar command 199.Ed 200.Pp 201Fields are separated by blanks or tabs. 202The command may be one or more fields long. 203The allowed values for the fields are: 204.Pp 205.Bl -tag -width "day-of-month" -compact -offset indent 206.It field 207allowed values 208.It ----- 209-------------- 210.It Ar minute 211* or 0\-59 212.It Ar hour 213* or 0\-23 214.It Ar day\&-of\&-month 215* or 1-31 216.It Ar month 217* or 1-12 or a name (see below) 218.It Ar day\&-of\&-week 219* or 0-7 or a name (0 or 7 is Sunday) 220.It Ar user 221a valid username 222.It Ar command 223text 224.El 225.Pp 226Lists are allowed. 227A list is a set of numbers (or ranges) separated by commas. 228Examples: 229.Sm off 230.Dq 1 , 2 , 5 , 9 , 231.Dq 0\&-4 , 8\&-12 . 232.Sm on 233.Pp 234Ranges of numbers are allowed. 235Ranges are two numbers separated with a hyphen. 236The specified range is inclusive. 237For example, 2388\-11 for an 239.Fa hour 240entry specifies execution at hours 8, 9, 10 and 11. 241.Pp 242Step values can be used in conjunction with ranges. 243Following a range with 244.No \&/ Ns Ar number 245specifies skips of 246.Fa number 247through the range. 248For example, 249.Dq 0-23/2 250can be used in the 251.Fa hour 252field to specify command execution every other hour (the alternative 253in the V7 standard is 254.Dq 0,2,4,6,8,10,12,14,16,18,20,22 ) . 255Steps are also permitted after an asterisk, so if you want to say 256.Dq every two hours , 257just use 258.Dq \&*\&/2 . 259.Pp 260An asterisk 261.Pq Ql * 262is short form for a range of all allowed values. 263.Pp 264Names can be used in the 265.Fa month 266and 267.Fa day\&-of\&-week 268fields. 269Use the first three letters of the particular 270day or month (case doesn't matter). 271Ranges or lists of names are not allowed. 272.Pp 273The 274.Fa command 275field (the rest of the line) is the command to be 276run. 277The entire command portion of the line, up to a newline or % 278character, will be executed by 279.Pa /bin/sh 280or by the shell 281specified in the 282.Ev SHELL 283variable of the 284.Nm crontab . 285Percent signs 286.Pq Ql % 287in the command, unless escaped with a backslash 288.Pq Ql \e , 289will be changed into newline characters, and all data 290after the first 291.Ql % 292will be sent to the command as standard input. 293.Pp 294Commands are executed by 295.Xr cron 8 296when the 297.Fa minute , 298.Fa hour , 299and 300.Fa month 301fields match the current time, 302.Em and 303when at least one of the two day fields 304.Pf ( Fa day\&-of\&-month 305or 306.Fa day\&-of\&-week , 307see Note below) match the current time. 308.Xr cron 8 309examines 310.Nm 311entries once every minute. 312.Pp 313Note: The day of a command's execution can be specified by two 314fields \(em 315.Ar day\&-of\&-month 316and 317.Ar day\&-of\&-week . 318If both fields are 319restricted (i.e., aren't *), the command will be run when 320.Em either 321field matches the current time. 322For example, 323.Pp 324.Dl 30 4 1\&,15 \&* 5 325.Pp 326would cause a command to be run at 4:30 am on the 1st and 15th of each 327month, plus every Friday. 328.Pp 329Instead of the first five fields, one of eight special strings may appear: 330.Pp 331.Bl -tag -width "@annually" -offset indent -compact 332.It string 333meaning 334.It ------ 335------- 336.It @reboot 337Run once, at 338.Xr cron 8 339startup. 340.It @yearly 341Run every January 1, "0 0 1 1 *". 342.It @annually 343(same as @yearly). 344.It @monthly 345Run the first day of every month, "0 0 1 * *". 346.It @weekly 347Run every Sunday, "0 0 * * 0". 348.It @daily 349Run every midnight, "0 0 * * *". 350.It @midnight 351(same as @daily). 352.It @hourly 353Run every hour, on the hour, "0 * * * *". 354.El 355.Sh EXAMPLES 356.Bd -literal 357# use /bin/sh to run commands, no matter what /etc/passwd says 358SHELL=/bin/sh 359# mail any output to `paul', no matter whose crontab this is 360MAILTO=paul 361# 362# run five minutes after midnight, every day 3635 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1 364# run at 2:15pm on the first of every month -- output mailed to paul 36515 14 1 * * $HOME/bin/monthly 366# run at 10 pm on weekdays, annoy Joe 3670 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?% 36823 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" 3695 4 * * sun echo "run at 5 after 4 every sunday" 370.Ed 371.Sh SEE ALSO 372.Xr crontab 1 , 373.Xr cron 8 374.Sh EXTENSIONS 375When specifying 376.Fa day\&-of\&-week , 377both day 0 and day 7 will be considered Sunday. 378BSD and ATT seem to disagree about this. 379.Pp 380Lists and ranges are allowed to coexist in the same field. 381.Dq 1\&-3,7\&-9 382would 383be rejected by ATT or BSD 384.Xr cron 385\(em they want to see 386.Dq 1\&-3 387or 388.Dq 7,8,9 389.Em only . 390.Pp 391Ranges can include 392.Dq steps , 393so 394.Dq 1-9/2 395is the same as 396.Dq 1,3,5,7,9 . 397.Pp 398Months or days of the week can be specified by name. 399.Pp 400Environment variables can be set in the crontab. 401In BSD or ATT, the 402environment handed to child processes is basically the one from /etc/rc. 403.Pp 404Command output is mailed to the crontab owner (BSD can't do this), can be 405mailed to a person other than the crontab owner (SysV can't do this), or the 406feature can be turned off and no mail will be sent at all (SysV can't do this 407either). 408.Pp 409All of the 410.Ql @ 411commands that can appear in place of the first five fields 412are extensions. 413.Sh AUTHORS 414.An Paul Vixie Aq vixie@isc.org 415