376 lines
12 KiB
Groff
376 lines
12 KiB
Groff
.\"/* Copyright 1988,1990,1993,1994 by Paul Vixie
|
|
.\" * All rights reserved
|
|
.\" *
|
|
.\" * Distribute freely, except: don't remove my name from the source or
|
|
.\" * documentation (don't take credit for my work), mark your changes (don't
|
|
.\" * get me blamed for your possible bugs), don't alter or remove this
|
|
.\" * notice. May be sold if buildable source is provided to buyer. No
|
|
.\" * warrantee of any kind, express or implied, is included with this
|
|
.\" * software; use at your own risk, responsibility for damages (if any) to
|
|
.\" * anyone resulting from the use of this software rests entirely with the
|
|
.\" * user.
|
|
.\" *
|
|
.\" * Send bug reports, bug fixes, enhancements, requests, flames, etc., and
|
|
.\" * I'll try to keep a version up to date. I can be reached as follows:
|
|
.\" * Paul Vixie <paul@vix.com> uunet!decwrl!vixie!paul
|
|
.\" */
|
|
.\"
|
|
.\" $Id: crontab.5,v 2.4 1994/01/15 20:43:43 vixie Exp $
|
|
.\"
|
|
.TH CRONTAB 5 "03 July 2014" "{{ package }} {{ version }}" "crontab"
|
|
.UC 4
|
|
.SH NAME
|
|
crontab \- tables for driving {{ package }}
|
|
.SH DESCRIPTION
|
|
A
|
|
.I crontab
|
|
file contains instructions to
|
|
.IR {{ package }}
|
|
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.
|
|
.PP
|
|
Blank lines and leading spaces and tabs are ignored. Lines whose first
|
|
non-space character is a hash-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. The crontab file is parsed from top to bottom, so any environment
|
|
settings will affect only the cron commands below them in the file.
|
|
An environment setting is of the form,
|
|
.PP
|
|
name = value
|
|
.PP
|
|
where the spaces around the equal-sign (=) are optional, and any subsequent
|
|
non-leading spaces in
|
|
.I value
|
|
will be part of the value assigned to
|
|
.IR name .
|
|
The
|
|
.I value
|
|
string may be placed in quotes (single or double, but matching) to preserve
|
|
leading or trailing blanks. The
|
|
.I value
|
|
string is
|
|
.B not
|
|
parsed for environmental substitutions or replacement of variables, thus lines
|
|
like
|
|
.PP
|
|
PATH = $HOME/bin:$PATH
|
|
.PP
|
|
will not work as you might expect. And neither will this work
|
|
.PP
|
|
A=1
|
|
B=2
|
|
C=$A $B
|
|
.PP
|
|
There will not be any subsitution for the defined variables in the
|
|
last value.
|
|
.PP
|
|
An alternative for setting up the commands path is using the fact that
|
|
many shells will treat the tilde(~) as substitution of $HOME, so if you use
|
|
.I bash
|
|
for your tasks you can use this:
|
|
.PP
|
|
SHELL=/bin/bash
|
|
PATH=~/bin:/usr/bin/:/bin
|
|
.PP
|
|
|
|
.I Special variables:
|
|
.TP
|
|
.B SHELL, PATH, USER, LOGNAME, HOME, LANG
|
|
Those are set up automatically by systemd itself, see
|
|
.IR systemd.exec (5)
|
|
SHELL defaults to /bin/sh.
|
|
SHELL and PATH may be overridden by settings in the crontab.
|
|
|
|
.TP
|
|
.B MAILTO
|
|
.br
|
|
On error
|
|
.IR systemd.cron (7)
|
|
will look at MAILTO. If MAILTO is defined mail is sent to this email address.
|
|
MAILTO may also be used to direct mail to multiple
|
|
recipients by separating recipient users with a comma.
|
|
If MAILTO is defined but empty (MAILTO=""), no mail will be sent.
|
|
Otherwise mail is sent to the owner of the crontab.
|
|
.br
|
|
This mail only contains an small excerpt from the log, as seen when using
|
|
.B systemctl status
|
|
The full output remains available in the journal.
|
|
|
|
.TP
|
|
.B RANDOM_DELAY
|
|
(in minutes) environment variable is translated to
|
|
.B AccuracySec=.
|
|
|
|
.TP
|
|
.B DELAY
|
|
(in minutes) environment variable is translated to
|
|
.B OnBootSec=.
|
|
This works like the 'delay' field of anacrontab(5) and make systemd wait # minutes
|
|
after boot before starting the unit. This value can also be used to spread out
|
|
the start times of @daily/@weekly/@monthly... jobs on a 24/24 system.
|
|
|
|
.TP
|
|
.B START_HOURS_RANGE
|
|
(in hours) environment variable is translated to the
|
|
.I \'hour\'
|
|
component of
|
|
.B OnCalendar=.
|
|
This variable is inheritted from anacrontab(5), but also supported in crontab(5)
|
|
by systemd-crontab-generator. Anacron expect a time range in the START-END format (eg: 6-9),
|
|
systemd-crontab-generator will only use the starting hour of the range as reference.
|
|
Unless you set this variable, all the @daily/@weekly/@monthly/@yearly jobs
|
|
will run at midnight. If you set this variable and the system was off during
|
|
the ours defined in the range, the (persitent) job will start at boot.
|
|
|
|
.TP
|
|
.B PERSISTENT
|
|
With this flag, you can override the generator default heuristic.
|
|
.br
|
|
.B 'yes':
|
|
force all further jobs to be persistent
|
|
.br
|
|
.B 'auto':
|
|
only recognize @ keywords to be persistent
|
|
.br
|
|
.B 'no':
|
|
force all further jobs not to be persistent
|
|
|
|
.TP
|
|
.B BATCH
|
|
This boolean flag is translated to options
|
|
.B CPUSchedulingPolicy=idle
|
|
and
|
|
.B IOSchedulingClass=idle
|
|
when set.
|
|
|
|
.PP
|
|
The format of a
|
|
.B cron command
|
|
is the same as the one defined by the cron daemon.
|
|
Each line has five time and date fields,
|
|
followed by a command, followed by a newline character ('\\n').
|
|
The system crontab (/etc/crontab) and the packages crontabs (/etc/cron.d/*)
|
|
use the same format, except that the username for the command is specified after the time and
|
|
date fields and before the command. The fields may be separated
|
|
by spaces or tabs.
|
|
.PP
|
|
Commands are executed by
|
|
.IR systemd
|
|
when the minute, hour, and month of year fields match the current time,
|
|
.I and
|
|
when at least one of the two day fields (day of month, or day of week)
|
|
match the current time (see ``Note'' below).
|
|
The time and date fields are:
|
|
.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 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 doesn't matter). Ranges or
|
|
lists of names are not allowed.
|
|
.PP
|
|
The ``sixth'' field (the rest of the line) specifies the command to be
|
|
run.
|
|
The entire command portion of the line, up to a newline
|
|
.\" or % character
|
|
, will be executed by /bin/sh or by the shell
|
|
specified in the SHELL variable of the crontab file.
|
|
.\"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. There is no way to split a single command line onto multiple
|
|
.\"lines, like the shell's trailing "\\".
|
|
.PP
|
|
systemd-crontab-generator doesn't handle multi-line command split by
|
|
the % character like vixie-cron.
|
|
.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 (i.e., aren't *), the command will be run when
|
|
.I either
|
|
field matches the current time. For example,
|
|
.br
|
|
``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. One can, however, achieve the desired result
|
|
by adding a test to the command (see the last example in EXAMPLE CRON FILE
|
|
below).
|
|
.PP
|
|
Instead of the first five fields, one of eight special strings may appear:
|
|
.IP
|
|
.ta 1.5i
|
|
string meaning
|
|
.br
|
|
------ -------
|
|
.br
|
|
@reboot Run once, at 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
|
|
Please note that startup, as far as @reboot is concerned,
|
|
may be before some system daemons,
|
|
or other facilities, were startup. This is due to the boot order
|
|
sequence of the machine.
|
|
|
|
.SH EXAMPLE CRON FILE
|
|
|
|
The following lists an example of a user crontab file.
|
|
|
|
.nf
|
|
|
|
# use /bin/bash to run commands, instead of the default /bin/sh
|
|
SHELL=/bin/bash
|
|
# mail errors 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 on every second Saturday of the month
|
|
0 4 8-14 * * test $(date +\\%u) \-eq 6 && echo "2nd Saturday"
|
|
.fi
|
|
.SH EXAMPLE SYSTEM CRON FILE
|
|
|
|
The following lists the content of a regular system-wide crontab file. Unlike a
|
|
user's crontab, this file has the username field, as used by /etc/crontab.
|
|
|
|
.nf
|
|
# /etc/crontab: system-wide crontab
|
|
# Unlike any other crontab you don't have to run the `crontab'
|
|
# command to install the new version when you edit this file
|
|
# and files in /etc/cron.d. These files also have username fields,
|
|
# that none of the other crontabs do.
|
|
|
|
SHELL=/bin/sh
|
|
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
|
|
|
|
# m h dom mon dow user command
|
|
17 * * * * root cd / && run-parts \-\-report /etc/cron.hourly
|
|
25 6 * * * root test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.daily )
|
|
47 6 * * 7 root test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.weekly )
|
|
52 6 1 * * root test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.monthly )
|
|
#
|
|
.fi
|
|
|
|
.PP
|
|
This is only an example,
|
|
.B systemd-cron uses native units instead for those jobs.
|
|
.br
|
|
If you add those lines, your jobs will run twice.
|
|
|
|
.SH SEE ALSO
|
|
systemd.cron(7), systemd-crontab-generator(8), crontab(1)
|
|
|
|
.SH LIMITATIONS
|
|
The
|
|
.I systemd-cron
|
|
units runs with a defined timezone. It currently does not support
|
|
per-user timezones. All the tasks: system's and user's will be run based on the
|
|
configured timezone. Even if a user specifies the
|
|
.I TZ
|
|
environment variable in his
|
|
.I crontab
|
|
this will affect only the commands executed in the crontab, not the execution
|
|
of the crontab tasks themselves.
|
|
|
|
The
|
|
.I crontab
|
|
syntax does not make it possible to define all possible periods one could
|
|
image off. For example, it is not straightforward to define the last
|
|
weekday of a month. If a task needs to be run in a specific period of time
|
|
that cannot be defined in the
|
|
.I crontab
|
|
syntaxs the best approach would be to have the program itself check the
|
|
date and time information and continue execution only if the period
|
|
matches the desired one.
|
|
|
|
.B systemd-crontab-generator
|
|
doesn't support these
|
|
.B vixie-cron
|
|
features:
|
|
.TP
|
|
*
|
|
spawning forking deamons, the 'Service' units are all set with 'Type=oneshot'
|
|
.TP
|
|
*
|
|
multi-line jobs separated by the '%' character
|
|
.TP
|
|
*
|
|
vixie-cron requires that each entry in a crontab end in a newline character. If the
|
|
last entry in a crontab is missing a newline (ie, terminated by EOF), vixie-cron will
|
|
consider the crontab (at least partially) broken.
|
|
.br
|
|
systemd-crontab-generator considers this crontab as valid
|
|
|
|
.SH DIAGNOSTICS
|
|
You can see how your crontab where translated by typing:
|
|
.br
|
|
.B systemctl cat cron-<userid>-*
|
|
.PP
|
|
.B systemctl cat
|
|
does support command-line completion.
|
|
|
|
.SH AUTHOR
|
|
Paul Vixie <paul@vix.com> is the author of
|
|
.I cron
|
|
and original creator of this manual page. This page has also been modified for
|
|
Debian by Steve Greenland, Javier Fernandez-Sanguino and Christian Kastner.
|
|
.br
|
|
This page has been reworded by Alexandre Detiste for inclusion in systemd-cron.
|