fcrontab - tables for driving fcron
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 poundsign (#) (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 time, |
entries based on absolut time |
(like normal crontab entries), or |
entries run periodically. |
Any logical line (an entry or an assignment) can be divided into several real lines (the lines which end by a newline character) by placing a backslash () before the newline character (n).
The environment settings are of the form
name = value |
where the blanks around equalsign (=) are ignored and optional. Trailing 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, HOME, and SHELL as defined in /etc/passwd for the owner of the fcrontab from which the command is extracted. HOME and SHELL may be overridden 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 com mand's output. Note that MAILTO is in fact equivalent 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.
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*multi plier+...+valueinminutes as "12h02" or "3w2d5h1". The first means "12 hours and 2 min utes of fcron execution" while the second means "3 weeks, 2 days, 5 hours and 1 minute of fcron execution". The only valid multipliers are:
multipliers m w d h |
meaning months (4 weeks) weeks (7 days) days (24 hours) hours (60 minutes) |
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.
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).
The second type of fcrontab's entries begins by an optional "&", which can be immediately followed by an optional number defining the frequency of execution (this is equivalent to option runfreq) or a declaration of options; it has five time and date fields, and a shell com mand. The frequency is interpreted as: "run this command after x matches of time and date fields". The time and date fields are:
field minute hour day of month month day of week |
allowed values 059 023 131 112 (or names, see below) 07 (0 and 7 are both Sunday, or names) |
A field is always filled by either an asterisk (*), which acts as "firstlast" range, a single num ber or a list.
List are numbers or range separated with commas (,). For instance: "2,5,15,23".
Ranges of number are of the form "beginend", where "begin" and "end" are included. For example, "35" 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 exam ple, "023/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 values in a range. For example, "58~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 "firstlast". 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,510/2~6,15,2025,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 be executed only days which are a Sunday AND a 31th.
see also : options dayor, bootrun, runfreq, mail, nolog, serial, lavg, nice, runas (see below).
The third type of fcrontab's entries begins by a "%" followed by one of the keywords follow ing :
hourly, daily, monthly, weekly, |
midhourly, middaily, nightly, midmonthly, midweekly, |
mins, hours, days, mons, dow. |
and optional options.
The keywords of the first line tell fcron to run the command once from the beginning of the corresponding interval to the end of that interval : for instance, the keyword weekly tells fcron to run a command once between Monday and Sunday each week. On top of that, the second list acts similarly but from middle to middle of the corresponding interval : midweekly will run a command once from Thursday to Wednesday. Note that nightly is equivalent to middaily.
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 interval :
Keywords: must be followed by the fields:
hourly, midhourly : |
minutes. |
daily, middaily, nightly, weekly, midweekly : |
minutes and hours. |
monthly, midmonthly : |
minutes, hours and days. |
For example : '%monthly * 35 1,525/5 echo "a monthly entry"'.
see also : options lavg, noticenotrun, strict, mail, nolog, serial, nice, runas (see below).
The keywords of the third list act differently, as follows:
run this command once during EACH interval specified, ignoring the fields below the key word in the interval definition (a hours prevents the mins field to be considered as an 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 absolut time (see above)). Furthermore, there must be some nonmatching time and dates in the lines with that kind of keyword (i.e. the following is not allowed : "%hours * 023 * * * echo", but "%hours * 022 * * * echo" is allowed).
Note : a single number in a field is considered as an interval : "%mins 15 24 * * * echo" will run at 2:15, 3:15 AND 4:15 every day.
But every fields below the keywords are ignored in interval definition : "%hours 15 24 * * * echo" will run only ONCE either at 2:15, 3:15 OR 4:15.
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 comas (,) and their arguments, if any, are placed between brackets ("(" and ")") and separated by comas. 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 his abbreviation. The options are (abbrevia tion and default value between brackets):
reset |
boolean |
|
exesev |
boolean(false) |
|
serialonce |
boolean(0) |
|
serial (s) |
boolean(false) |
|
bootrun (b) |
||
boolean(false) |
||
first (f) |
timevalue |
|
runfreq (r) |
integer |
based on elapsed time). |
mailto |
username(name of file's owner) |
|
mail (m) |
boolean(true) |
|
forcemail |
boolean(false) |
|
nolog |
boolean(false) |
|
dayand |
boolean(true) |
|
dayor |
boolean(false) |
|
nice (n) |
nicevalue |
|
runas |
username |
|
lavg |
real(0) |
real(0) real(0) real(0) |
Set the threshold of, respectively, the 1, 5 or 15 minutes system load average value. Set one of them to 0 to ignore the corresponding load average. |
until |
timevalue(0) |
|
lavgonce |
boolean(1) |
|
lavgand |
boolean(true) |
|
lavgor |
boolean(false) |
strict |
boolean(true) |
noticenotrun |
boolean(no) |
Should fcron mail user to report the nonexecution of a %job or a &job (because of system down state for both or a too high system load average for the latter). |
A boolean argument can be inexistent, in which case brackets 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 explanations about time value (section "entries based on elapsed 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 completed 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 distin guish 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, the next job in the serial queue or the job nearest to the until timeout in the lavg queue will be executed before adding a new job.
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 would be :
!reset,serial(true),dayor,bootrun(0),mailto(root),lavg(.5,2,1.5)
# 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 hours
@first(5) 1h echo "Run every hours"
# run every days
@ 1d echo "fcron daily"
# run once between in the morning and once in the afternoon
# if systems is running at any moment of these intervals
&hours * 812,1418 * * * echo "Hey boss, I'm working today !"
# run once a week during our lunch
%weekly * 1213 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 peer days of march at 18:00, except on 16th
0 18 230/2~16 Mar * echo "It's time to go back home !"
# the line above is equivalent to
& 0 18 230/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) * 2123,36 echo "It's time to retrieve \
the last release of Mozilla !"
/etc/fcron.allow |
Users allowed to use fcrontab (one name per line, special name "all" acts for everyone) |
|
/etc/fcron.deny |
Users who are not allowed to use fcrontab (same format as allow file) |
fcron(8), fcrontab(1)
Thibault Godouet <fcron@free.fr>