1.\" $NetBSD: crontab.5,v 1.7 2018/06/15 23:15:56 wiz 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 June 14, 2018 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 149Step values can be used in conjunction with ranges. 150Following a range with 151.No / Ns Ar number 152specifies skips of 153.Ar number 154through the range. 155For example, 156.Dq 0\(en23/2 157can be used in the 158.Ar hour 159field to specify command execution every other hour. 160Steps are also permitted after an asterisk, so to say 161.Dq every two hours , 162just use 163.Dq */2 . 164.Pp 165An asterisk 166.Pq Ql * 167is short form for a range of all allowed values. 168.Pp 169Names can be used in the 170.Ar month 171and 172.Ar day-of-week 173fields. 174Use the first three letters of the particular 175day or month (case doesn't matter). 176Ranges or lists of names are not allowed. 177.Pp 178The 179.Ar command 180field (the rest of the line) is the command to be 181run. 182The entire command portion of the line, up to a newline or % 183character, will be executed by 184.Pa /bin/sh 185or by the shell 186specified in the 187.Ev SHELL 188variable of the 189.Nm crontab . 190Percent signs 191.Pq Ql % 192in the command, unless escaped with a backslash 193.Pq Ql \e , 194will be changed into newline characters, and all data 195after the first 196.Ql % 197will be sent to the command as standard input. 198.Pp 199Commands may be modified as follows: 200.Bl -tag -width Ds 201.It Fl n Ar command 202No mail is sent after a successful run. 203The execution output will only be mailed if the command exits with a non-zero 204exit code. 205The 206.Fl n 207option is an attempt to cure potentially copious volumes of mail coming from 208.Xr cron 8 . 209.It Fl q Ar command 210Execution will not be logged. 211.El 212.Pp 213Commands are executed by 214.Xr cron 8 215when the 216.Ar minute , 217.Ar hour , 218and 219.Ar month 220fields match the current time, 221.Em and 222when at least one of the two day fields 223.Po Ar day-of-month 224or 225.Ar day-of-week Pc , 226match the current time. 227.Pp 228Note: The day of a command's execution can be specified by two 229fields \(em 230.Ar day-of-month 231and 232.Ar day-of-week . 233If both fields are restricted (i.e. aren't *), 234the command will be run when 235.Em either 236field matches the current time. 237For example, 238.Pp 239.Dl 30 4 1,15 * 5 240.Pp 241would cause a command to be run at 4:30 am on the 1st and 15th of each 242month, plus every Friday. 243.Pp 244Instead of the first five fields, one of eight special strings may appear: 245.Bl -column "@midnight" "meaning" -offset indent 246.It Sy string Ta Sy meaning 247.It @reboot Ta Run once, at startup. 248.It @yearly Ta Run every January 1 (0 0 1 1 *). 249.It @annually Ta The same as @yearly. 250.It @monthly Ta Run the first day of every month (0 0 1 * *). 251.It @weekly Ta Run every Sunday (0 0 * * 0). 252.It @daily Ta Run every midnight (0 0 * * *). 253.It @midnight Ta The same as @daily. 254.It @hourly Ta Run every hour, on the hour (0 * * * *). 255.El 256.Sh ENVIRONMENT 257.Bl -tag -width "CRON_WITHIN" 258.It Ev CRON_TZ 259The 260.Ev CRON_TZ 261variable can be set to an alternate time zone in order to affect when the job 262is run. 263Note that this only affects the scheduling of the job, not the time zone 264that the job perceives when it is run. 265If 266.Ev CRON_TZ 267is defined but empty 268.Pq Ev CRON_TZ Ns = Ns \&"" , 269jobs are scheduled with respect to the local time zone. 270.It Ev CRON_WITHIN 271The 272.Ev CRON_WITHIN 273variable should indicate the number of seconds within a job's 274scheduled time that it should still be run. 275On a heavily loaded system, or on a system that has just been 276.Dq woken up , 277jobs will sometimes start later than originally intended, and by 278skipping non-critical jobs because of delays, system load can be 279lightened. 280If 281.Ev CRON_WITHIN 282is defined but empty 283.Pq Ev CRON_WITHIN Ns = Ns \&"" , 284or set to some non-positive value (0, a negative number, or a 285non-numeric string), it is treated as if it was unset. 286.It Ev HOME 287Set from the user's 288.Pa /etc/passwd 289entry. 290May be overridden by settings in the 291.Nm . 292.It Ev LOGNAME 293Set from the user's 294.Pa /etc/passwd 295entry. 296May not be overridden by settings in the 297.Nm . 298.It Ev MAILTO 299If 300.Ev MAILTO 301is defined and non-empty, 302mail is sent to the user so named. 303If 304.Ev MAILTO 305is defined but empty 306.Pq Ev MAILTO = Qq , 307no mail will be sent. 308Otherwise mail is sent to the owner of the 309.Nm . 310This is useful for pseudo-users that lack an alias 311that would otherwise redirect the mail to a real person. 312.It Ev SHELL 313Set to 314.Pa /bin/sh . 315May be overridden by settings in the 316.Nm . 317.It Ev USER 318Set from the user's 319.Pa /etc/passwd 320entry. 321May not be overridden by settings in the 322.Nm . 323.El 324.Sh FILES 325.Bl -tag -width "/var/cron/tabs/<user>XXX" -compact 326.It Pa /etc/crontab 327System crontab. 328.It Pa /var/cron/tabs/ Ns Aq Ar user 329User crontab. 330.El 331.Sh EXAMPLES 332.Bd -literal 333# use /bin/sh to run commands, no matter what /etc/passwd says 334SHELL=/bin/sh 335# mail any output to `paul', no matter whose crontab this is 336MAILTO=paul 337# 338# run five minutes after midnight, every day 3395 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1 340# run at 2:15pm on the first of every month -- output mailed to paul 34115 14 1 * * $HOME/bin/monthly 342# run at 10 pm on weekdays, annoy Joe 3430 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?% 34423 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" 3455 4 * * sun echo "run at 5 after 4 every sunday" 346.Ed 347.Sh SEE ALSO 348.Xr crontab 1 , 349.Xr cron 8 350.Sh STANDARDS 351The 352.Nm 353file format is compliant with the 354.St -p1003.1-2008 355specification. 356The behaviours described below are all extensions to that standard: 357.Bl -dash 358.It 359The 360.Ar day-of-week 361field may use 7 to represent Sunday. 362.It 363Ranges may include 364.Dq steps . 365.It 366Months or days of the week can be specified by name. 367.It 368Mailing after a successful run can be suppressed with 369.Fl n . 370.It 371Logging can be suppressed with 372.Fl q . 373.It 374Environment variables can be set in a crontab. 375.It 376Command output can be mailed to a person other than the crontab 377owner, or the feature can be turned off and no mail will be sent 378at all. 379.It 380All of the 381.Ql @ 382commands that can appear in place of the first five fields. 383.El 384.Sh AUTHORS 385.Nm 386was written by 387.An Paul Vixie Aq Mt vixie@isc.org . 388