CRONTAB

NAME
DESCRIPTION
EXTENSIONS
SEE ALSO
AUTHORS

---

NAME

crontab - tables for driving micrond

DESCRIPTION

Crontabs used by 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.

Each crontab line is either a variable setting or a cron command.

Cron commands
A cron command defines a command to run, a user on behalf of which it will be run, and a running schedule.

The fields are delimited by arbitrary amount of whitespace.

A cron command begins with a cron expression, which defines a time schedule. This expression consists of five fields in this order:

	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)

A field may contain a single asterisk (*), 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. */2 in second field stands for ’’each second hour’’.

The field may also be a comma-delimited list of the following constructs:

	N		A single number. E.g. 2 in first field means ’’second minute of an hour’’.
	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:

55-5 * * * *
means ’’minutes 55 through 59 and 0 through 5 of the next hour’’.

I-J/N

Same as above, but with step of N units, e.g.:

10-25/5 * * * *
which stands for ’’minutes 10,15,20,25’’.

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.

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 day field semantics. There are three cases:
Strict semantics

The command will be run only when both fields match the current time. For example,
30 4 1,15 * 5
means to run the command at 4:30 am each Friday between the 1st and 15th of each month.
This is the default for micrond.

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.

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:
0 11 2,3 * mon-wed date
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:
0 11 1,5 * mon-wed date
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.

The semantics to use is selected by setting the _MICRON_DAY_SEMANTICS variable to one of the following values: strict, vixie, dillon (case-insensitive).

Instead of the first five fields, the following macro-definitions can be used:

string meaning
------ -------
@reboot Run once, at micrond startup.
@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 * * * *".

In master crontab (/etc/crontab) and system crontabs (located in /etc/cron.d), 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.

This field is absent in user personal crontabs, since these are always run on behalf of the user that owns them,

The rest of line is taken as a shell command to be run when the time matches the schedule. Before running the command, micrond 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 SHELL variable (/bin/sh by default).

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.

Variable settings
Variable settings modify execution environment for subsequent cron commands. Some variables are internal to micrond and modify its behavior. A variable setting has the form

name = value

where name is the variable name and value 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.

You don’t need to quote value 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.

Finally, the construct

name =

unsets the variable name.

A variable setting applies to all cron commands that follow it, until another setting overwrites it or the end of file is encountered.

The following variables are built-in variables. They modify handing of the cron commands that follow them, but are not copied to the command environment. Varables prefixed with _JOB_ affect only cron command that follows them, whereas variables prefixed with _MICRON_ affect all commands that follow them, until another assignment of the same variable is encountered or the end of file is reached.
_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 INFO), instead of mailing it the usual way.
Possible values for this variable are auth, authpriv, cron, daemon, ftp, lpr, mail, news, syslog, user, uucp, and local0 through local7.
The value default means to use the default syslog facility (cron), and off or none disable syslog and revert to mailing the program output as directed by the MAILTO variable.

_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 -s option or by the SYSLOG_FACILITY setting). If not specified, the tag will be constructed as FILE:LINE(PROG), where FILE and LINE are the file name and line number of the line where the cron command appeared and PROG is the first word of the command.

The global counterpart of this variable, _MICRON_SYSLOG_TAG, is provided for completeness. It is probably of little use, since it sets the same tag for all crontab entries.

_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. micrond will refuse to start a job if its previous run has not yet terminated.

_JOB_MAILTO

This variable temporarily masks the MAILTO variable and disables the two SYSLOG 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.

The global version of this variable, _MICRON_MAILTO, is mostly equivalent to the traditional MAILTO variable, except that any existing value of MAILTO is retained in the environment.

_MICRON_DAY_SEMANTICS, _JOB_DAY_SEMANTICS

Defines the day semantics. Allowed values are: strict, vixie, and dillon. The default is strict. See the discussion of day semantics in the subsection Cron commands for a detailed description.

The following variables modify the behavior of micrond itself.

	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 MAILTO variable. If the variable is undefined, the output will be sent to the owner of the crontab. If MAILTO is set to an empty string, no mail will be sent.
	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.
	SHELL		Defines the shell used to start commands. Defaults to /bin/sh.

EXTENSIONS

This section lists the differences of the micrond crontabs over these of Vixie and Dillon crons.

	1.		Long crontab lines can be split across several physical lines using backslash continuation.
	2.		The semantics of the two day fields is configurable. The default strict semantics differs from both implementations.
	3.		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:

MAILTO=one
* * * * * command one
MAILTO=two
* * * * * command two

	4.		Job output can be logged to syslog, instead of mailing it to the user. This can happen both globally (see the -s option to micrond), or individually in a crontab (see the _MICRON_SYSLOG_FACILITY) variable.
	5.		Number of simultaneous instances of a single cron job is limited. It is configurable using the _MICRON_MAXINSTANCES 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.
	6.		Dillon’s cron implements optional job dependencies and frequences. These are not implemented in micrond.

SEE ALSO

micrond(8), crontab(1).

AUTHORS

Sergey Poznyakoff <gray@gnu.org>.

This manual page uses examples from manpages for cron implementations by Paul Vixie <paul@vix.com> and Matthew Dillon <dillon@apollo.backplane.com>.

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

---