diff options
Diffstat (limited to 'usr.sbin/cron/crontab/crontab.5')
| -rw-r--r-- | usr.sbin/cron/crontab/crontab.5 | 393 |
1 files changed, 393 insertions, 0 deletions
diff --git a/usr.sbin/cron/crontab/crontab.5 b/usr.sbin/cron/crontab/crontab.5 new file mode 100644 index 000000000000..e4e6fae0b01b --- /dev/null +++ b/usr.sbin/cron/crontab/crontab.5 @@ -0,0 +1,393 @@ +.\"/* Copyright 1988,1990,1993,1994 by Paul Vixie +.\" * All rights reserved +.\" */ +.\" +.\"Copyright (c) 1997 by Internet Software Consortium +.\" +.\"Permission to use, copy, modify, and distribute this software for any +.\"purpose with or without fee is hereby granted, provided that the above +.\"copyright notice and this permission notice appear in all copies. +.\" +.\"THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS +.\"ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES +.\"OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE +.\"CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL +.\"DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR +.\"PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS +.\"ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\"SOFTWARE. +.\" +.\" $Id: crontab.5,v 1.2 1998/08/14 00:32:38 vixie Exp $ +.\" +.Dd May 10, 2024 +.Dt CRONTAB 5 +.Os +.Sh NAME +.Nm crontab +.Nd tables for driving cron +.Sh DESCRIPTION +A +.Nm +file contains instructions to the +.Xr cron 8 +daemon of the general form: ``run this command at this time on this date''. +Each user has their own crontab, and commands in any given crontab will be +executed as the user who owns the crontab. +Uucp and News will usually have +their own crontabs, eliminating the need for explicitly running +.Xr su 1 +as part of a cron command. +.Pp +Blank lines and leading spaces and tabs are ignored. +Lines whose first +non-space character is a pound-sign (#) are comments, and are ignored. +Note that comments are not allowed on the same line as cron commands, since +they will be taken to be part of the command. +Similarly, comments are not +allowed on the same line as environment variable settings. +.Pp +An active line in a crontab will be either an environment setting or a cron +command. +An environment setting is of the form, +.Bd -literal + name = value +.Ed +.Pp +where the spaces around the equal-sign (=) are optional, and any subsequent +non-leading spaces in +.Em value +will be part of the value assigned to +.Em name . +The +.Em value +string may be placed in quotes (single or double, but matching) to preserve +leading or trailing blanks. +The +.Em name +string may also be placed in quote (single or double, but matching) +to preserve leading, trailing or inner blanks. +.Pp +Several environment variables are set up +automatically by the +.Xr cron 8 +daemon. +.Ev SHELL +is set to +.Pa /bin/sh , +and +.Ev LOGNAME +and +.Ev HOME +are set from the +.Pa /etc/passwd +line of the crontab's owner. +In addition, the environment variables of the +user's login class will be set from +.Pa /etc/login.conf.db +and +.Pa ~/.login_conf . +(A setting of +.Ev HOME +in the login class will override the value from +.Pa /etc/passwd , +but will not change the current directory when the command is +invoked, which can only be overridden with an explicit setting of +.Ev HOME +within the crontab file itself.) +If +.Ev PATH +is not set by any other means, it is defaulted to +.Pa /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin . +.Ev HOME , +.Ev PATH +and +.Ev SHELL , +and any variables set from the login class, +may be overridden by settings in the crontab; +.Ev LOGNAME +may not. +.Pp +(Another note: the +.Ev LOGNAME +variable is sometimes called +.Ev USER +on +.Bx +systems... +On these systems, +.Ev USER +will be set also). +.Pp +If +.Xr cron 8 +has any reason to send mail as a result of running commands in +``this'' crontab, it will respect the following settings which may be +defined in the crontab (but which are not taken from the login class). +If +.Ev MAILTO +is defined (and non-empty), mail is +sent to the user so named. +If +.Ev MAILFROM +is defined (and non-empty), its value will be used as the from address. +.Ev MAILTO +may also be used to direct mail to multiple recipients +by separating recipient users with a comma. +If +.Ev MAILTO +is defined but empty (MAILTO=""), no +mail will be sent. +Otherwise mail is sent to the owner of the crontab. +This +option is useful if you decide on +.Pa /bin/mail +instead of +.Pa /usr/lib/sendmail +as +your mailer when you install cron -- +.Pa /bin/mail +does not do aliasing, and UUCP +usually does not read its mail. +.Pp +The format of a cron command is very much the V7 standard, with a number of +upward-compatible extensions. +.Pp +Each user cron line has five time and date fields, followed by a command. +.Pp +Each line in system crontab ( +.Pa /etc/crontab, /etc/cron.d, /usr/local/etc/cron.d +) has five time and date fields, followed by a valid user name +(with optional ``:<group>'' and ``/<login-class>'' suffixes), +followed by a command. +.Pp +Commands are executed by +.Xr cron 8 +when the minute, hour, and month of year fields match the current time, +.Em and +when at least one of the two day fields (day of month, or day of week) +matches the current time (see ``Note'' below). +.Xr cron 8 +examines cron entries once every minute. +The time and date fields are: +.Bd -literal -offset indent +field allowed values +----- -------------- +minute 0-59 +hour 0-23 +day of month 1-31 +month 1-12 (or names, see below) +day of week 0-7 (0 or 7 is Sun, or use names) +.Ed +.Pp +A field may be an asterisk (*), which always stands for ``first\-last''. +.Pp +Ranges of numbers are allowed. +Ranges are two numbers separated +with a hyphen. +The specified range is inclusive. +For example, +8-11 for an ``hours'' entry specifies execution at hours 8, 9, 10 +and 11. +.Pp +Lists are allowed. +A list is a set of numbers (or ranges) +separated by commas. +Examples: ``1,2,5,9'', ``0-4,8-12''. +.Pp +Step values can be used in conjunction with ranges. +Following +a range with ``/<number>'' specifies skips of the number's value +through the range. +For example, ``0-23/2'' can be used in the hours +field to specify command execution every other hour (the alternative +in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22''). +Steps are +also permitted after an asterisk, so if you want to say ``every two +hours'', just use ``*/2''. +.Pp +Names can also be used for the ``month'' and ``day of week'' +fields. +Use the first three letters of the particular +day or month (case does not matter). +Ranges and lists are also allowed. +.Pp +The ``sixth'' field (the rest of the line) specifies the command to be +run. +One or more command options may precede the command to modify processing +behavior. +The entire command portion of the line, up to a newline or % +character, will be executed by +.Pa /bin/sh +or by the shell +specified in the +.Ev SHELL +variable of the cronfile. +Percent-signs (%) in the command, unless escaped with backslash +(\\), will be changed into newline characters, and all data +after the first % will be sent to the command as standard +input. +.Pp +The following command options can be supplied: +.Bl -tag -width Ds +.It Fl n +No mail is sent after a successful run. +The execution output will only be mailed if the command exits with a non-zero +exit code. +The +.Fl n +option is an attempt to cure potentially copious volumes of mail coming from +.Xr cron 8 . +.It Fl q +Execution will not be logged. +.El +.sp +Duplicate options are not allowed. +.Pp +Note: The day of a command's execution can be specified by two +fields \(em day of month, and day of week. +If both fields are +restricted (ie, are not *), the command will be run when +.Em either +field matches the current time. +For example, +``30 4 1,15 * 5'' +would cause a command to be run at 4:30 am on the 1st and 15th of each +month, plus every Friday. +.Pp +Instead of the first five fields, +a line may start with +.Sq @ +symbol followed either by one of eight special strings or by a numeric value. +The recognized special strings are: +.Bd -literal -offset indent +string meaning +------ ------- +@reboot Run once, at startup of cron. +@yearly Run once a year, "0 0 1 1 *". +@annually (same as @yearly) +@monthly Run once a month, "0 0 1 * *". +@weekly Run once a week, "0 0 * * 0". +@daily Run once a day, "0 0 * * *". +@midnight (same as @daily) +@hourly Run once an hour, "0 * * * *". +@every_minute Run once a minute, "*/1 * * * *". +@every_second Run once a second. +.Ed +.Pp +The +.Sq @ +symbol followed by a numeric value has a special notion of running +a job that many seconds after completion of the previous invocation of +the job. +Unlike regular syntax, it guarantees not to overlap two or more +invocations of the same job during normal cron execution. +Note, however, that overlap may occur if the job is running when the file +containing the job is modified and subsequently reloaded. +The first run is scheduled for the specified number of seconds after cron +is started or the crontab entry is reloaded. +.Sh EXAMPLE SYSTEM CRON FILE +.Bd -literal +# sample /etc/cron.d/vmstat +# run vmstat every five minutes +# note the username as sixth field! +*/5 * * * * root vmstat +.Ed +.Sh EXAMPLE USER CRON FILE +.Bd -literal +# use /bin/sh to run commands, overriding the default set by cron +SHELL=/bin/sh +# mail any output to `paul', no matter whose crontab this is +MAILTO=paul +# +# run five minutes after midnight, every day +5 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1 +# run at 2:15pm on the first of every month -- output mailed to paul +15 14 1 * * $HOME/bin/monthly +# run at 10 pm on weekdays, annoy Joe +0 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?% +23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" +5 4 * * sun echo "run at 5 after 4 every sunday" +# run at 5 minutes intervals, no matter how long it takes +@300 svnlite up /usr/src +# run every minute, suppress logging +* * * * * -q date +# run every minute, only send mail if ping fails +* * * * * -n ping -c 1 freebsd.org +.Ed +.Sh SEE ALSO +.Xr crontab 1 , +.Xr cron 8 +.Sh EXTENSIONS +When specifying day of week, both day 0 and day 7 will be considered Sunday. +.Bx +and +.Tn ATT +seem to disagree about this. +.Pp +Lists and ranges are allowed to co-exist in the same field. +"1-3,7-9" would +be rejected by +.Tn ATT +or +.Bx +cron -- they want to see "1-3" or "7,8,9" ONLY. +.Pp +Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9". +.Pp +Names of months or days of the week can be specified by name. +.Pp +Environment variables can be set in the crontab. +In +.Bx +or +.Tn ATT , +the +environment handed to child processes is basically the one from +.Pa /etc/rc . +.Pp +Command output is mailed to the crontab owner +.No ( Bx +cannot do this), can be +mailed to a person other than the crontab owner (SysV cannot do this), or the +feature can be turned off and no mail will be sent at all (SysV cannot do this +either). +.Pp +All of the +.Sq @ +directives that can appear in place of the first five fields +are extensions. +.Pp +Command processing can be modified using command options. +The +.Sq -q +option suppresses logging. +The +.Sq -n +option does not mail on successful run. +.Sh AUTHORS +.An Paul Vixie Aq Mt paul@vix.com +.Sh BUGS +If you are in one of the 70-odd countries that observe Daylight +Savings Time, jobs scheduled during the rollback or advance may be +affected if +.Xr cron 8 +is not started with the +.Fl s +flag. +In general, it is not a good idea to schedule jobs during +this period if +.Xr cron 8 +is not started with the +.Fl s +flag, which is enabled by default. +See +.Xr cron 8 +for more details. +.Pp +For US timezones (except parts of AZ and HI) the time shift occurs at +2AM local time. +For others, the output of the +.Xr zdump 8 +program's verbose +.Fl ( v ) +option can be used to determine the moment of time shift. |