1.\" $NetBSD: crontab.5,v 1.11 2022/02/26 17:02:47 christos Exp $ 2.\" 3.\"/* Copyright 1988,1990,1993,1994 by Paul Vixie 4.\" * All rights reserved 5.\" */ 6.\" 7.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") 8.\" Copyright (c) 1997,2000 by Internet Software Consortium, Inc. 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT 20.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" $OpenBSD: crontab.5,v 1.36 2018/06/13 13:27:37 jmc Exp $ 23.\" 24.Dd February 26, 2022 25.Dt CRONTAB 5 26.Os 27.Sh NAME 28.Nm crontab 29.Nd tables for driving cron 30.Sh DESCRIPTION 31A 32.Nm 33file contains instructions to the 34.Xr cron 8 35daemon of the general form: 36.Dq at these times on these dates run this command . 37There may be a system 38.Nm 39and each user may have their own 40.Nm . 41Commands in any given 42.Nm 43will be 44executed either as the user who owns the 45.Nm 46or, in the case of the system 47.Nm crontab , 48as the user specified on the command line. 49.Pp 50While a 51.Nm 52is a text file, it is not intended to be directly edited. 53Creation, modification, and removal of a 54.Nm 55should be done using 56.Xr crontab 1 . 57.Pp 58Blank lines, leading spaces, and tabs are ignored. 59Lines whose first non-space character is a pound sign 60.Pq Ql # 61are comments, and are ignored. 62Note that comments are not allowed on the same line as 63.Xr cron 8 64commands, since 65they will be taken to be part of the command. 66Similarly, comments are not 67allowed on the same line as environment variable settings. 68.Pp 69An active line in a 70.Nm 71is either an environment variable setting or a 72.Xr cron 8 73command. 74.Pp 75Environment variable settings create the environment 76any command in the 77.Nm 78is run in. 79An environment variable setting is of the form: 80.Pp 81.Dl name = value 82.Pp 83The spaces around the equal sign 84.Pq Ql = 85are optional, and any subsequent non-leading spaces in 86.Ar value 87will be part of the value assigned to 88.Ar name . 89The 90.Ar value 91string may be placed in quotes 92.Pq single or double , but matching 93to preserve leading or trailing blanks. 94.Pp 95Lines in the system 96.Nm 97have six fixed fields plus a command, in the form: 98.Bd -ragged -offset indent 99.Ar minute 100.Ar hour 101.Ar day-of-month 102.Ar month 103.Ar day-of-week 104.Ar user 105.Ar command 106.Ed 107.Pp 108While lines in a user 109.Nm 110have five fixed fields plus a command, in the form: 111.Bd -ragged -offset indent 112.Ar minute 113.Ar hour 114.Ar day-of-month 115.Ar month 116.Ar day-of-week 117.Ar command 118.Ed 119.Pp 120Fields are separated by blanks or tabs. 121The command may be one or more fields long. 122The allowed values for the fields are: 123.Bl -column "day-of-month" "allowed values" -offset indent 124.It Sy field Ta Sy allowed values 125.It Ar minute Ta * or 0\(en59 126.It Ar hour Ta * or 0\(en23 127.It Ar day-of-month Ta * or 1\(en31 128.It Ar month Ta * or 1\(en12 or a name (see below) 129.It Ar day-of-week Ta * or 0\(en7 or a name (0 or 7 is Sunday) 130.It Ar user Ta a valid username 131.It Ar command Ta text 132.El 133.Pp 134Lists are allowed. 135A list is a set of numbers (or ranges) separated by commas. 136For example, 137.Dq 1,2,5,9 138or 139.Dq 0\(en4,8\(en12 . 140.Pp 141Ranges of numbers are allowed. 142Ranges are two numbers separated with a hyphen. 143The specified range is inclusive. 144For example, 1458\(en11 for an 146.Ar hour 147entry specifies execution at hours 8, 9, 10 and 11. 148.Pp 149A field may begin with a question mark 150.Pq Sq \&? , 151which indicates a single value randomly selected when the crontab 152file is read. 153If the field contains only a question mark, the value is randomly 154selected from the range of all possible values for the field. 155If the question mark precedes a range, the value is randomly selected 156from the range. 157For example, 158.Dq ? ?2-5 * * * 159specifies that a task will be performed daily between 2:00am and 160and 5:59am at a time randomly selected when the crontab file is 161first read. 162As just one example, this feature can be used to prevent a large 163number of hosts from contacting a server simultaneously and 164overloading it by staggering the time at which a download script 165is executed. 166.Pp 167Step values can be used in conjunction with ranges (but not random ranges 168which represent a single number). 169Following a range with 170.No / Ns Ar number 171specifies skips of 172.Ar number 173through the range. 174For example, 175.Dq 0\(en23/2 176can be used in the 177.Ar hour 178field to specify command execution every other hour. 179Steps are also permitted after an asterisk, so to say 180.Dq every two hours , 181just use 182.Dq */2 . 183.Pp 184An asterisk 185.Pq Ql * 186is short form for a range of all allowed values. 187.Pp 188Names can be used in the 189.Ar month 190and 191.Ar day-of-week 192fields. 193Use the first three letters of the particular 194day or month (case doesn't matter). 195Ranges or lists of names are not allowed. 196.Pp 197The 198.Ar command 199field (the rest of the line) is the command to be 200run. 201The entire command portion of the line, up to a newline or % 202character, will be executed by 203.Pa /bin/sh 204or by the shell 205specified in the 206.Ev SHELL 207variable of the 208.Nm crontab . 209Percent signs 210.Pq Ql % 211in the command, unless escaped with a backslash 212.Pq Ql \e , 213will be changed into newline characters, and all data 214after the first 215.Ql % 216will be sent to the command as standard input. 217.Pp 218Commands may be modified as follows: 219.Bl -tag -width Ds 220.It Fl n Ar command 221No mail is sent after a successful run. 222The execution output will only be mailed if the command exits with a non-zero 223exit code. 224The 225.Fl n 226option is an attempt to cure potentially copious volumes of mail coming from 227.Xr cron 8 . 228.It Fl q Ar command 229Execution will not be logged. 230.It Fl s Ar command 231Only a single instance of 232.Ar command 233will be run concurrently. 234Additional instances of 235.Ar command 236will not be scheduled until the earlier one completes. 237.El 238.Pp 239Commands are executed by 240.Xr cron 8 241when the 242.Ar minute , 243.Ar hour , 244and 245.Ar month 246fields match the current time, 247.Em and 248when at least one of the two day fields 249.Po Ar day-of-month 250or 251.Ar day-of-week Pc , 252match the current time. 253.Pp 254Note: The day of a command's execution can be specified by two 255fields \(em 256.Ar day-of-month 257and 258.Ar day-of-week . 259If both fields are restricted (i.e. aren't *), 260the command will be run when 261.Em either 262field matches the current time. 263For example, 264.Pp 265.Dl 30 4 1,15 * 5 266.Pp 267would cause a command to be run at 4:30 am on the 1st and 15th of each 268month, plus every Friday. 269.Pp 270Instead of the first five fields, one of eight special strings may appear: 271.Bl -column "@midnight" "meaning" -offset indent 272.It Sy string Ta Sy meaning 273.It @reboot Ta Run once, at startup. 274.It @yearly Ta Run every January 1 (0 0 1 1 *). 275.It @annually Ta The same as @yearly. 276.It @monthly Ta Run the first day of every month (0 0 1 * *). 277.It @weekly Ta Run every Sunday (0 0 * * 0). 278.It @daily Ta Run every midnight (0 0 * * *). 279.It @midnight Ta The same as @daily. 280.It @hourly Ta Run every hour, on the hour (0 * * * *). 281.El 282.Sh ENVIRONMENT 283.Bl -tag -width "CRON_WITHIN" 284.It Ev CRON_TZ 285The 286.Ev CRON_TZ 287variable can be set to an alternate time zone in order to affect when the job 288is run. 289Note that this only affects the scheduling of the job, not the time zone 290that the job perceives when it is run. 291If 292.Ev CRON_TZ 293is defined but empty 294.Pq Ev CRON_TZ Ns = Ns \&"" , 295jobs are scheduled with respect to the local time zone. 296.It Ev CRON_WITHIN 297The 298.Ev CRON_WITHIN 299variable should indicate the number of seconds within a job's 300scheduled time that it should still be run. 301For example if a job is scheduled for 12:30pm and 302.Ev CRON_WITHIN 303is 304.Dv 120 305(2 minutes), then the job will not be run if the system attempts 306to start it past 12:32pm. 307On a heavily loaded system, or on a system that has just been 308.Dq woken up , 309jobs will sometimes start later than originally intended, and by 310skipping non-critical jobs because of delays, system load can be 311lightened. 312If 313.Ev CRON_WITHIN 314is defined but empty 315.Pq Ev CRON_WITHIN Ns = Ns \&"" , 316or set to some non-positive value (0, a negative number, or a 317non-numeric string), it is treated as if it was unset, that is 318the job will always run, even if it is going to start at a time 319long past its scheduled time. 320.It Ev HOME 321Set from the user's 322.Pa /etc/passwd 323entry. 324May be overridden by settings in the 325.Nm . 326.It Ev LOGNAME 327Set from the user's 328.Pa /etc/passwd 329entry. 330May not be overridden by settings in the 331.Nm . 332.It Ev MAILTO 333If 334.Ev MAILTO 335is defined and non-empty, 336mail is sent to the user so named. 337If 338.Ev MAILTO 339is defined but empty 340.Pq Ev MAILTO = Qq , 341no mail will be sent. 342Otherwise mail is sent to the owner of the 343.Nm . 344This is useful for pseudo-users that lack an alias 345that would otherwise redirect the mail to a real person. 346.It Ev SHELL 347Set to 348.Pa /bin/sh . 349May be overridden by settings in the 350.Nm . 351.It Ev USER 352Set from the user's 353.Pa /etc/passwd 354entry. 355May not be overridden by settings in the 356.Nm . 357.El 358.Sh FILES 359.Bl -tag -width "/var/cron/tabs/<user>XXX" -compact 360.It Pa /etc/crontab 361System crontab. 362.It Pa /var/cron/tabs/ Ns Aq Ar user 363User crontab. 364.El 365.Sh EXAMPLES 366.Bd -literal 367# use /bin/sh to run commands, no matter what /etc/passwd says 368SHELL=/bin/sh 369# mail any output to `paul', no matter whose crontab this is 370MAILTO=paul 371# 372# run five minutes after midnight, every day 3735 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1 374# run at 2:15pm on the first of every month -- output mailed to paul 37515 14 1 * * $HOME/bin/monthly 376# run at 10 pm on weekdays, annoy Joe 3770 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?% 37823 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" 3795 4 * * sun echo "run at 5 after 4 every sunday" 380.Ed 381.Sh SEE ALSO 382.Xr crontab 1 , 383.Xr cron 8 384.Sh STANDARDS 385The 386.Nm 387file format is compliant with the 388.St -p1003.1-2008 389specification. 390The behaviours described below are all extensions to that standard: 391.Bl -dash 392.It 393The 394.Ar day-of-week 395field may use 7 to represent Sunday. 396.It 397Ranges may include 398.Dq steps . 399.It 400Months or days of the week can be specified by name. 401.It 402Mailing after a successful run can be suppressed with 403.Fl n . 404.It 405Logging can be suppressed with 406.Fl q . 407.It 408Environment variables can be set in a crontab. 409.It 410Command output can be mailed to a person other than the crontab 411owner, or the feature can be turned off and no mail will be sent 412at all. 413.It 414All of the 415.Ql @ 416commands that can appear in place of the first five fields. 417.El 418.Sh AUTHORS 419.Nm 420was written by 421.An Paul Vixie Aq Mt vixie@isc.org . 422