path: root/doc/crontab.5

.\" GNU micron - a minimal cron implementation  -*- nroff -*-
.\" Copyright (C) 2020-2021 Sergey Poznyakoff
.\"
.\" GNU micron is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" GNU micron is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with GNU micron. If not, see <http://www.gnu.org/licenses/>. */
.TH CRONTAB 5 "January 25, 2021" "CRONTAB" "File Formats Manual"
.SH NAME
crontab \- tables for driving micrond
.SH DESCRIPTION
Crontabs used by
.BR micrond (8)
are mostly compatible with Vixie crontabs.  The leading and trailing
whitespace is ignored.  Comments are introduced by a hash sign (#)
appearing as the first non-whitespace character in a line.  Comment
lines and empty lines are ignored.  Very long lines can be split
across several physical lines using backslash as continuation
character.  Total length of a valid crontab line after removing
continuation characters cannot exceed 1024 characters.
.PP
Each crontab line is either a variable setting or a cron command.
.SS Cron commands
A cron command defines a command to run, a user on behalf of which it
will be run, and a running schedule.
.PP
The fields are delimited by arbitrary amount of whitespace.
.PP
A cron command begins with a cron expression, which defines a time
schedule.  This expression consists of five fields in this order:
.IP
.ta 1.5i
field	allowed values
.br
-----	--------------
.br
minute	0-59
.br
hour	0-23
.br
day of month	1-31
.br
month	1-12 (or names, see below)
.br
day of week	0-7 (0 or 7 is Sun, or use names)
.br
.PP
A field may contain a single asterisk (\fB*\fR), which stands for
``each time unit''.  For example, it means ``each minute'' when used
in the first field, ``each hour'' in second one, and so on.  Asterisk
can be followed by a slash and a decimal number, which defines step
within the interval.  E.g. \fB*/2\fR in second field stands for ``each
second hour''.
.PP
The field may also be a comma-delimited list of the following
constructs:
.TP
.I N
A single number.  E.g. 2 in first field means ``second minute of an
hour''.
.TP
.I I-J
Two numbers delimited by a dash define a range.  E.g 2-5 in first
field is ``minutes 2,3,4, and 5 (inclusive)''.  The order is
important.  For example, the following schedule:
.br
    55-5 * * * *
.br
means ``minutes 55 through 59 and 0 through 5 of the next hour''.
.TP
.I I-J/N
Same as above, but with step of N units, e.g.:
.br
    10-25/5 * * * *
.br
which stands for ``minutes 10,15,20,25''.
.PP
Names can be used in ``month'' and ``day of week'' fields.  Day and
week names are abbreviated to their first three characters
(case-insensitive).  Ranges or lists of names are allowed as well.
.PP
The day of command's execution can be specified by two fields:
day of month, and day of week.  Their exact meaning depends on the
selected
.IR "day field semantics" .
There are three cases:
.TP
.I Strict semantics
The command will be run only when both fields match the current time.
For example,
.br
    30 4 1,15 * 5
.br
means to run the command at 4:30 am each Friday between the 1st and
15th of each month.
.br
This is the default for \fBmicrond\fR.
.TP
.I Vixie semantics
The command will be run when either field matches the current time.
Thus, the previous example would cause a command to be run at 4:30 am
on the 1st and 15th of each month, plus every Friday.
.TP
.I Dillon semantics
If both day in the month and a day of week are supplied, the former
must be integer numbers in range 1-5.  The meaning is Nth such weekday
in the month.  For example, to run the date command at 11 am on the
second and third Monday, Tuesday and Wednesday of each month:
.br
    0 11 2,3 * mon-wed date
.br    
To request the last Monday, etc. in a month, ask for the "5th" one.
This will always match the last Monday, etc., even if there are only
four Mondays in the month: 
.br
    0 11 1,5 * mon-wed date
.br
When the fourth Monday in a month is the last, it will match against
both 4 and 5, but will only run once if both are specified.
.PP
The semantics to use is selected by setting the
.B _MICRON_DAY_SEMANTICS
variable to one of the following values:
.BR strict ,
.BR vixie ,
.BR dillon 
(case-insensitive).
.PP
Instead of the first five fields, the following macro-definitions can
be used:
.IP
.ta 1.5i
string	meaning
.br
------	-------
.br
@reboot	Run once, at \fBmicrond\fR startup.
.br
@yearly	Run once a year, "0 0 1 1 *".
.br
@annually	(same as @yearly)
.br
@monthly	Run once a month, "0 0 1 * *".
.br
@weekly	Run once a week, "0 0 * * 0".
.br
@daily	Run once a day, "0 0 * * *".
.br
@midnight	(same as @daily)
.br
@hourly	Run once an hour, "0 * * * *".
.br
.PP
In master crontab (\fB/etc/crontab\fR) and system crontabs (located in
\fB/etc/cron.d\fR), the cron expression is followed by the user field,
which holds a login name of the user on whose behalf the command will
be run.
.PP
This field is absent in user personal crontabs, since these are always
run on behalf of the user that owns them,
.PP
The rest of line is taken as a shell command to be run when the time
matches the schedule.  Before running the command, \fBmicrond\fR
changes the directory to the home directory of the user for whom the
command is run, modifies the environment as defined by variable
settings (see below) and runs the command using the shell defined by
the \fBSHELL\fR variable (\fB/bin/sh\fR by default).
.PP
The standard input to be piped to the job can be supplied after the
command, by separating it from the command with a percent sign.  To
use a literal percent signs in the command, escape it with a backslash
or quote it (both single and double quotes will do).  Any occurrence
of unescaped percent sign in the input line will be replaced with a
newline.
.SS Variable settings
Variable settings modify execution environment for subsequent cron
commands.  Some variables are internal to \fBmicrond\fR and modify
its behavior.  A variable setting has the form
.PP
   \fIname\fR = \fIvalue\fR
.PP
where \fIname\fR is the variable name and \fIvalue\fR is the value to
be assigned to it.  Notice several important differences from the
similar construct in shell.  First of all, optional whitespace is
allowed on either side of the equals sign.  Secondly, the value is
assigned verbatim, after removing any trailing and leading whitespace.
No expansions or substitutions take place.  If you need this kind of
functionality, move environment manipulations to a shell script and
invoke it from the cron command.
.PP
You don't need to quote \fIvalue\fR even if it contains embedded
whitespace.  There are two cases when quoting becomes necessary: to
define an empty variable or to preserve leading or trailing
whitespace.  In the latter case both single and double quotes can be
used, the only requirement being that both quotes match.  Inside a
quoted string, a backslash character can be used to escape a quote
character or another backslash.  To define an empty variable, use a
pair of quotes.
.PP
Finally, the construct
.PP
   \fIname\fR =
.PP
unsets the variable \fIname\fR.
.PP
A variable setting applies to all cron commands that follow it, until
another setting overwrites it or the end of file is encountered.
.PP
The following variables are \fIbuilt-in variables\fR.  They modify
handing of the cron commands that follow them, but are not copied to
the command environment.  Varables prefixed with \fB_JOB_\fR
affect only cron command that follows them, whereas variables prefixed
with \fB_MICRON_\fR affect all commands that follow them, until
another assignment of the same variable is encountered or the end of
file is reached.
.TP
.BR _MICRON_SYSLOG_FACILITY ", " _JOB_SYSLOG_FACILITY
If this variable is set to a meaningful syslog facility, the program
output will be logged to that facility (priority \fBINFO\fR), instead
of mailing it the usual way.
.br
Possible values for this variable are
.BR auth ,
.BR authpriv ,
.BR cron ,
.BR daemon ,
.BR ftp ,
.BR lpr ,
.BR mail ,
.BR news ,
.BR syslog ,
.BR user ,
.BR uucp ,
and
.B local0
through
.BR local7. 
.br
The value
.B default
means to use the default syslog facility (\fBcron\fR), and
.B off
or
.B none
disable syslog and revert to mailing the program output as directed by
the \fBMAILTO\fR variable.
.TP
.B _JOB_SYSLOG_TAG
Sets the syslog tag for the next cron command.  The tag is used only if
syslog is enabled (by the use of \fB\-s\fR option or by the
\fBSYSLOG_FACILITY\fR setting).  If not specified, the tag will be
constructed as \fIFILE\fB:\fILINE\fB(\fIPROG\fB)\fR, where
\fIFILE\fR and \fILINE\fR are the file name and line number of the
line where the cron command appeared and \fIPROG\fR is the first word
of the command.
.sp
The global counterpart of this variable, \fB_MICRON_SYSLOG_TAG\fR,
is provided for completeness.  It is probably of little use, since it
sets the same tag for all crontab entries.
.TP
.BR _MICRON_MAXINSTANCES ", " _JOB_MAXINSTANCES
An integer value defining how many instances of the same cron job can
be running simultaneously.  Default is 1, i.e. \fBmicrond\fR will
refuse to start a job if its previous run has not yet terminated.
.TP
.B _JOB_MAILTO
This variable temporarily masks the \fBMAILTO\fR variable and disables
the two \fBSYSLOG\fR variables for the next crontab entry.  After
that, the previous values are restored.  Use it to redirect output of
a single crontab entry to a particular address.
.sp
The global version of this variable, \fB_MICRON_MAILTO\fR, is mostly
equivalent to the traditional \fBMAILTO\fR variable, except that any
existing value of \fBMAILTO\fR is retained in the environment.
.TP
.BR _MICRON_DAY_SEMANTICS ", " _JOB_DAY_SEMANTICS
Defines the day semantics.  Allowed values are:
.BR strict ,
.BR vixie ,
and
.BR dillon .
The default is
.BR strict .
See the discussion of day semantics in the subsection
.B "Cron commands"
for a detailed description.
.PP
The following variables modify the behavior of \fBmicrond\fR itself.
.TP
.B MAILTO
Defines an email address or a comma-delimited list of email addresses.
If any of the cron commands that follow this setting produces anything on
its standard output or standard error, the output will be collected
and mailed to the users listed in the \fBMAILTO\fR variable.  If the
variable is undefined, the output will be sent to the owner of the
crontab.  If \fBMAILTO\fR is set to an empty string, no mail will be
sent.
.TP
.B HOME
Defines the working directory from which the subsequent commands will
be run.  Defaults to the home directory of the user on whose behalf
the command is run.
.TP
.B SHELL
Defines the shell used to start commands.  Defaults to
.BR /bin/sh .
.SH EXTENSIONS
This section lists the differences of the \fBmicrond\fR crontabs over
these of Vixie and Dillon crons.
.nr step 1 1
.IP \n[step].
Long crontab lines can be split across several physical lines using
backslash continuation.
.IP \n+[step].
The semantics of the two day fields is configurable.  The default
\fBstrict\fR semantics differs from both implementations.
.IP \n+[step].
Variable assignments can appear anyplace in the crontab.  The modified
environment remains in effect for all subsequent commands until
changed by another assignment or the end of file is reached, whichever
happens first.  For example, the output of the following two example
entries is mailed to two different users:
.sp
    MAILTO=one
    * * * * * command one
    MAILTO=two
    * * * * * command two
.IP \n+[step].
Job output can be logged to syslog, instead of mailing it to the
user.  This can happen both globally (see the \fB\-s\fR option to
\fBmicrond\fR), or individually in a crontab (see the
\fB_MICRON_SYSLOG_FACILITY\fR) variable.
.IP \n+[step].
Number of simultaneous instances of a single cron job is limited.
It is configurable using the \fB_MICRON_MAXINSTANCES\fR variable.
This differs both from Vixie implementation, where a job is started no
matter how many of its instances are running, and from Dillon's cron,
which refuses to start a job until its prior instance has terminated.
.IP \n+[step].
Dillon's cron implements optional job dependencies and frequences.
These are not implemented in \fBmicrond\fR.
.SH SEE ALSO
.BR micrond (8),
.BR crontab (1).
.SH AUTHORS
Sergey Poznyakoff <[email protected]>. 
.PP
This manual page uses examples from manpages for cron implementations by 
Paul Vixie <[email protected]> and Matthew Dillon <[email protected]>.
.PP
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end: