FCRONTAB(5)FCRONTAB(5)NAMEfcrontab - tables for driving fcron
DESCRIPTION
A fcrontab is a file containing all tables used by the fcron(8) daemon.
In other words, it is the means for a user to tell the daemon "execute
this command at this moment". Each user has his own fcrontab, whose
commands are executed as his owner (only root can run a job as another
using the option runas (see below)).
Blank lines, line beginning by a hash sign (#) (which are considered
comments), leading blanks and tabs are ignored. Each line in a fcrontab
file can be either
· an environment setting,
· an option setting,
· entries based on elapsed system up time,
· entries based on absolute time (like normal crontab entries), or
· entries run periodically.
Any logical line (an entry or an assignment) can be divided into sev‐
eral real lines (the lines which end by a newline character) by placing
a backslash (\) before the newline character (\n).
THE ENVIRONMENT SETTINGS
The environment settings are of the form
name = value
where the blanks around equal-sign (=) are ignored and optional. Trail‐
ing blanks are also ignored, but you can place the value in quotes
(simple or double, but matching) to preserve any blanks in the value.
When fcron executes a command, it always sets USER, and HOME as defined
in /etc/passwd for the owner of the fcrontab from which the command is
extracted. TZ is also defined to the value of the option timezone when
this option is used. It also defines SHELL to the value of the SHELL
used to run the command. Fcron uses the value of SHELL from the
fcrontab if any, otherwise it uses the value from fcron.conf if any, or
in last resort the value from /etc/passwd. HOME and SHELL may be over‐
ridden by settings in the fcrontab, but USER may not. Every other
environment assignments defined in the user fcrontab are then made, and
the command is executed.
Plus, the special variable MAILTO allows you to tell fcron to whom it
has to mail the command's output. Note that MAILTO is in fact equiva‐
lent to a global declaration of the option mailto (see below). It is
only used for backward compatibility, so you should use the option
mailto directly.
ENTRIES BASED ON ELAPSED SYSTEM UP TIME
The entries of commands which have to be run once every m minutes of
fcron's execution (which is normally the same as m minutes of system's
execution) are of the form
@options frequency command
where frequency is a time value of the form value*multiplier+value*mul‐
tiplier+...+value-in-minutes as "12h02" or "3w2d5h1". The first means
"12 hours and 2 minutes of fcron execution" while the second means "3
weeks, 2 days, 5 hours and 1 minute of fcron execution". The only valid
multipliers are: "VALID TIME MULTIPLIERS" meaning: multipliers:
months (4 weeks): m weeks (7 days): w days (24 hours): d
hours (60 minutes): h seconds: s
In place of options, user can put a time value: it will be interpreted
as @first(<time>). If first option is not set, the value of "frequency"
is used.
This kind of entry does not guarantee a time and date of execution (as
the job is delayed at each startup by the time elapsed since the shut‐
down), but should be useful for jobs depending on the number of things
done by the users (for instance, the filesystem should better be
checked after a certain amount of use by the users rather than every x
days, as the system may run from 1 day to x days during that x days
interval).
The time remaining before next execution is saved every 1800 seconds
(to limit damages caused by a crash) and when fcron exits after having
received a SIGTERM signal, i.e. when systems go down. Thus, this kind
of entries is particularly useful for systems that don't run regularly.
The syntax being very simple, it may also useful for tasks which don't
need to be run at a specific time and date.
See also: options first, mail, nolog, serial, lavg, nice, runas (see
below).
SOME EXAMPLES OF LINES BASED ON ELAPSED SYSTEM UP TIME
# Get our mails every 30 minutes
@ 30 getmails -all
# make some security tests every 48 hours of system up time,
# force a mail to be sent to root even if there is no output
@mailto(root),forcemail 2d /etc/security/msec/cron-sh/security.sh
ENTRIES BASED ON TIME AND DATE
The second type of fcrontab's entries begins by an optional "&", which
can be immediately followed by an optional number defining the fre‐
quency of execution (this is equivalent to option runfreq) or a decla‐
ration of options; it has five time and date fields, and a shell com‐
mand :
&options min hrs day-of-month month day-of-week command
Note that the shell command may be preceded by a user name, which is
equivalent to runas(<user>): as it is only here for backward compati‐
bility you should use option runas (see below) instead. The frequency
is interpreted as: "run this command after x matches of time and date
fields". The time and date fields are: "TIME AND DATE FIELDS" 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
and 7 are both Sunday, or names)
A field is always filled by either an asterisk (*), which acts as
"first-last" range, a single number or a list.
List are numbers or range separated with commas (,). For instance:
"2,5,15,23".
Ranges of number are of the form "<begin>-<end>", where "begin" and
"end" are included. For example, "3-5" specifies the values 3, 4 and 5.
You can also add an optional "/number" to a range, where the 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. Finally, one or several "~number" can be added to
turn off some specific values in a range. For example, "5-8~6~7" is
equivalent to "5,8". The final form of a field is:
a[-b[/c][~d][~e][...]][,f[-g[/h][~i][~j][...]]][,...]
where the letters are integers.
You can also use an asterisk (*) in a field. It acts for "first-last".
For example, a "*" in the field minute means all minutes from minute 0
down to minute 59.
Ranges can be included in a list as a single number. For instance:
"2,5-10/2~6,15,20-25,30".
Names can also be used for the "month" and "day of week" fields. To do
so, use the first three letters of the particular day or month (case
doesn't matter). Please note that names are used exactly as numbers:
you can use them in a list or a range.
If a day of month and a day of week are given, the command will execute
only when both match with the current time and date unless option dayor
is set. For example, with the line
5 10 31 * 7 echo ''
echo will only be executed days which are a Sunday AND a 31th, at
10:05.
See also: options dayor, bootrun, runfreq, mail, nolog, serial, lavg,
nice, runas (see below).
SOME EXAMPLES OF ENTRIES BASED ON TIME AND DATE
# run mycommand at 12:05, 12:35, 13:05, 13:35,
# 14:05 *and* 14:35 everyday
& 05,35 12-14 * * * mycommand -u me -o file
# get mails every hour past 20, 21, 22, and 24 minutes.
20-24~23 * * * * getmail
# save our work of the day every night at 03:45 with a low priority
# unless we are sunday, mail the output to jim and run that job
# at startup if computer was down at 03:45
&nice(10),mailto(jim),bootrun 45 03 * * *~0 "save --our work"
ENTRIES RUN PERIODICALLY
The third type of fcrontab's entries begin by a "%", followed by a key‐
word from one of 3 different lists, and optional options.
*LY KEYWORDS
Those keywords are:
hourly , daily , monthly , weekly
Those keywords tell fcron to run the command once from the beginning of
the corresponding time interval to the end of that time interval. A
time interval is, for example, the time from Monday 16:20 to Wednesday
01h43. For instance, the keyword weekly tells fcron to run a command
once between Monday and Sunday each week.
With this two kind of keywords, user must give the needed time fields
(as defined in "Entries based on time and date" (see above)) to specify
when the command should be run during each time interval:
"NEEDED TIME FIELDS FOR EACH KEYWORD" Keywords: must be followed by the
fields: hourly, midhourly: minutes. daily, middaily, nightly, weekly,
midweekly: minutes and hours. monthly, midmonthly: minutes, hours and
days.
MID*LY KEYWORDS
They are similar to the "*ly" ones:
midhourly , middaily , nightly , midmonthly , midweekly
They work exactly has the "*ly" keywords, except that the time inter‐
vals are defined from middle to middle of the corresponding "*ly"
intervals: midweekly will run a command once from Thursday to Wednes‐
day. Note that nightly is equivalent to middaily.
For example:
%nightly,mail(no) * 21-23,3-5 echo "a nigthly entry"
will run the command once each night either between 21:00 and 23:59, or
between 3:00 and 5:59 (it will run as soon as possible. To change that,
use option random) and won't send mail (because option mail is set to
"no").
See also: options lavg, noticenotrun, strict, mail, nolog, serial,
nice, runas, random (see below).
*S KEYWORDS
They are:
mins , hours , days , mons , dow
Those keywords act differently, as follows:
run this command once during EACH time interval specified, ignoring the
fields below the keyword in the time interval definition (a hours pre‐
vents the mins field to be considered as a time interval, but it will
be used to determine when the line should be run during an interval:
see the note below) (dow means "day of week").
Such a keyword is followed by 5 time and date fields (the same fields
used for a line based on absolute time (see above)). Furthermore, there
must be some non-matching time and dates in the lines with that kind of
keyword (i.e. the following is not allowed :
%hours * 0-23 * * * echo "INCORRECT line!"
but
%hours * 0-22 * * * echo "Ok."
is allowed).
Note:
a single number in a field is considered as a time interval:
%mins 15 2-4 * * * echo
will run at 2:15, 3:15 AND 4:15 every day.
But all fields below the keywords are ignored in time interval
definition:
%hours 15 2-4 * * * echo
will run only ONCE either at 2:15, 3:15 OR 4:15.
See also: option random (see below).
OPTIONS
The options can be set either for every line below the declaration or
for an individual line. In the first case, the setting is done on a
whole line immediately after an exclamation mark (!), while it is done
after a "&", a "%" or a "@" depending on the type of scheduling in the
second case. Note that an option declaration in a schedule overrides
the global declaration of that same option.
Options are separated by commas (,) and their arguments, if any, are
placed in parentheses ("(" and ")") and separated by commas. No spaces
are allowed. A declaration of options is of the form
option[(arg1[,arg2][...])][,option[(arg1[...])]][...]
where option is either the name of an option or its abbreviation. The
options are (default value in parentheses): "VALID OPTIONS IN A
FCRONTAB"
bootrun
b boolean(false)
Run a &-line at fcron's startup if it should have be run during
system down time.
dayand boolean(true)
Perform a logic AND between week and month day.
See also: options dayor.
dayor boolean(false)
Perform a logic OR between week and month day.
See also: options dayand.
erroronlymail
boolean(false)
Mail output only if job exited with a non-zero status.
See also: options mail, mailto, forcemail, nolog.
exesev boolean(false)
Can a job be executed several times simultaneously ?
See also: options serialonce, lavgonce.
first
f time-value
Delay before first execution of a job based on system up time
("@"-lines). Useful in the following case: you have several jobs
running, say, every hour. By setting different first value for
each job, you can avoid them to run simultaneously everytime.
You can also set it to 0, which is useful when used in conjunc‐
tion with option volatile.
forcemail
boolean(false)
Mail output even if zero-length.
See also: options mail, mailto, erroronlymail, nolog.
lavg real(0)real(0)real(0)
Set the values of the 1, 5 and 15-minute (in this order) system
load average values below which the job should run. The values
have a maximum of 1 decimal (i.e. "2.3"): if there are more than
1 decimal, the value will be round off. Set a value to 0 to
ignore the corresponding load average (or all of the values to
run the job regardless of the load average).
See also: options lavg1, lavg5, lavg15, until, lavgonce, lavgor,
lavgand, strict, noticenotrun.
lavg1
lavg5
lavg15 real(0)
Set the threshold of, respectively, the 1, 5 or 15 minutes sys‐
tem load average value. Set one of them to 0 to ignore the cor‐
responding load average.
See also: options lavg.
lavgand
boolean(true)
Perform a logic AND between the 1, 5 and 15 minutes system load
average values.
See also: options lavg, lavgor.
lavgonce
boolean(1)
Can a job be queued several times in lavg queue simultaneously?
See also: options lavg.
lavgor boolean(false)
Perform a logic OR between the 1, 5 and 15 minutes system load
average values.
See also: options lavg, lavgand.
mail
m boolean(true)
Mail output (if any) or not.
See also: options mailto, forcemail, erroronlymail, nolog.
mailto email-address(name of file's owner)
Mail output (if needed) to "email-address". It can be either a
single user-name or a fully qualified email address. A mailto
declared and empty (string "") is equivalent to "mail(false)".
See also: options mail, forcemail, erroronlymail, nolog.
nice
n nice-value
Change job priority. A nice-value is an integer from -20 (high‐
est priority) to 19 (lowest) (only root is allowed to use a neg‐
ative value with this option).
nolog boolean(false)
If set to true, log only errors for the corresponding job(s).
May be useful for jobs running very often, and/or to reduce disk
access on a laptop.
See also: options mail, mailto, erroronlymail, forcemail.
noticenotrun
boolean(false)
Should fcron mail user to report the non-execution of a %-job or
a &-job? (because of system down state for both or a too high
system load average for the latter)
See also: options lavg, strict.
random boolean(false)
In a line run periodically, this option answers the question:
should this job be run as soon as possible in its time interval
of execution (safer), or should fcron set a random time of exe‐
cution in that time interval? Note that if this option is set,
the job may not run if fcron is not running during the whole
execution interval. Besides, you must know that the random
scheme may be quite easy to guess for skilled people: thus, you
shouldn't rely on this option to make important things secure.
However, it shouldn't be a problem for most uses.
reset boolean
Reset all the options to default.
runas user-name
Run with "user-name" permissions and environment (only root is
allowed to use this option).
runfreq
r integer
Run every "runfreq" matches of time and date. (this option is
ignored for lines based on elapsed system up time).
serial
s boolean(false)
Fcron runs at most 1 serial jobs (ie. for which the option
serial is set to true), and the same number of lavg serial jobs
(ie. for which both option serial and lavg (or lavg1 or lavg5 or
lavg15) are set to true) simultaneously. This value may be modi‐
fied by fcron's option -m. This option is especially useful when
used with big jobs in order to limit the system overload.
See also: options serialonce, lavg.
serialonce
boolean(0)
Can a job be queued several times in serial queue simultane‐
ously?
See also: options exesev, lavgonce.
stdout boolean(false)
If fcron is running in the foreground, then also let jobs print
to stderr/stdout instead of mailing or discarding it.
See also: fcron's option --once in fcron(8).
strict boolean(true)
When a lavg %-job is at the end of a time interval of execution,
should it be removed from the lavg queue (strict(true), so the
job is not run) or be let there until the system load average
allows its execution (strict(false))?
See also: options lavg, noticenotrun.
timezone
timezone-name(time zone of the system)
Run the job in the given time zone. timezone-name is a string
which is valid for the environment variable TZ: see the documen‐
tation of your system for more details. For instance,
"Europe/Paris" is valid on a Linux system. This option handles
daylight saving time changes correctly. The TZ environ,ment
variable is set to the value of timezone when a job defining
this option is run.
Please note that if you give an erroneous timezone-name argu‐
ment, it will be SILENTLY ignored, and the job will run in the
time zone of the system.
WARNING: do *not* use option timezone and option tzdiff simulta‐
neously! There is no need to do so, and timezone is cleverer
than tzdiff.
See also: options tzdiff.
tzdiff integer(0)
WARNING: this option is deprecated: use option timezone instead!
Time zone difference (in hours, between -24 and 24) between the
system time, and the local real time. This option allows a user
to define its & and %-lines in the local time. Note that this
value is set for a whole fcrontab file, and only the last defi‐
nition is taken into account. tzdiff is quite stupid: it doesn't
handle daylight saving changes, while option timezone does, so
you should use the latter.
See also: options timezone.
until time-value(0)
Set the timeout of the waiting of the wanted system load average
values. If the timeout is exceeded, the job runs no matter the
load average. Set until to 0 to remove the timeout.
See also: options lavg.
volatile
boolean(false)
When set to true, the job is based on a "volatile" system up
time, i.e. restart counting each time fcron is started, which is
useful when fcron is started by a script running only, for
instance, during a dialup connection: the "volatile" system up
time then refers to the dialup connection time. You may also
want to use option first if you use fcron that way.
See also: options first, stdout, lines based on elapsed system
up time, fcron's option --once in fcron(8).
A boolean argument can be non-existent, in which case parentheses are
not used and it means true; the string "true", "yes" or 1 to mean true;
and the string "false", "no" or 0 to mean false. See above for explana‐
tions about time value (section "entries based on elapsed system up
time").
Note that dayand and dayor are in fact the same option: a false value
to dayand is equivalent to a true to dayor, and reciprocally a false
value to dayor is equivalent a true value to dayand. It is the same for
lavgand and lavgor.
Note a special case to be handled: A job should be entered into the
serial queue, *but* the previous entry for this job has not been com‐
pleted yet, because of high system load or some external event. Option
serialonce answers the question: should the new entry of the job be
ignored? This way one can distinguish between jobs required to run a
certain number of times, preferably at specified times, and tasks to be
performed irrespective of their number (-> serialonce(true)), which
make the system respond faster.
The same considerations apply for the load average queue, and can be
expressed with option lavgonce.
Moreover, if the serial or the lavg queue contains respectively more
than 30 and 30 jobs, any new job is refused and not run to avoid an
overwhelming of system resources. In this case, an error message is
logged through syslog.
Finally, if jobs remain in the lavg or serial queues when fcron stops,
they will be put once in the corresponding queue on startup (their
order may not be conserved).
AN EXAMPLE OF AN OPTION DECLARATION:
!reset,serial(true),dayor,bootrun(0),mailto(root),lavg(.5,2,1.5)
EXAMPLES
AN EXAMPLE OF A USER FCRONTAB
# use /bin/bash to run commands, ignoring what /etc/passwd says
SHELL=/bin/bash
# mail output to thib, no matter whose fcrontab this is
!mailto(thib)
# define a variable which is equivalent to " Hello thib and paul! "
# here the newline characters are escaped by a backslash (\)
# and quotes are used to force to keep leading and trailing blanks
TEXT= " Hello\
thib and\
paul! "
# we want to use serial but not bootrun:
!serial(true),b(0)
# run after five minutes of execution the first time,
# then run every hour
@first(5) 1h echo "Run every hour"
# run every day
@ 1d echo "fcron daily"
# run once between in the morning and once in the afternoon
# if systems is running at any moment of these time intervals
%hours * 8-12,14-18 * * * echo "Hey boss, I'm working today!"
# run once a week during our lunch
%weekly * 12-13 echo "I left my system on at least once \
at lunch time this week."
# run every Sunday and Saturday at 9:05
5 9 * * sat,sun echo "Good morning Thibault!"
# run every even days of march at 18:00, except on 16th
0 18 2-30/2~16 Mar * echo "It's time to go back home!"
# the line above is equivalent to
& 0 18 2-30/2~16 Mar * echo "It's time to go back home!"
# reset options to default and set runfreq for lines below
!reset,runfreq(7)
# run once every 7 matches (thanks to the declaration above),
# so if system is running every day at 10:00, this will be
# run once a week
& 0 10 * * * echo "if you got this message last time 7 days ago,\
this computer has been running every day at 10:00 last week.\
If you got the message 8 days ago, then the system has been down \
one day at 10:00 since you got it, etc"
# wait every hour for a 5 minutes load average under 0.9
@lavg5(0.9) 1h echo "The system load average is low"
# wait a maximum of 5 hours every day for a fall of the load average
@lavgand,lavg(1,2.0,3.0),until(5h) 1d echo "Load average is going down"
# wait for the best moment to run a heavy job
@lavgor,lavg(0.8,1.2,1.5),nice(10) 1w echo "This is a heavy job"
# run once every night between either 21:00 and 23:00 or
# between 3:00 and 6:00
%nightly,lavg(1.5,2,2) * 21-23,3-6 echo "It's time to retrieve \
the latest release of Mozilla!"
FILES
/usr/local/etc/fcron.conf
Configuration file for fcron, fcrontab and fcrondyn: contains
paths (spool dir, pid file) and default programs to use (editor,
shell, etc). See fcron.conf(5) for more details.
/usr/local/etc/fcron.allow
Users allowed to use fcrontab and fcrondyn (one name per line,
special name "all" acts for everyone)
/usr/local/etc/fcron.deny
Users who are not allowed to use fcrontab and fcrondyn (same
format as allow file)
/usr/local/etc/pam.d/fcron (or /usr/local/etc/pam.conf)
PAM configuration file for fcron. Take a look at pam(8) for more
details.
SEE ALSOfcrontab(1),
fcrondyn(1),
fcrontab(5),
fcron.conf(5),
fcron(8).
If you're learning how to use fcron from scratch, I suggest that you
read the HTML version of the documentation (if your are not reading it
right now! :) ): the content is the same, but it is easier to navigate
thanks to the hyperlinks.
AUTHOR
Thibault Godouet <fcron@free.fr>
04/05/2010 05 avril 2010 FCRONTAB(5)
