|
m
|
|
months (4 weeks)
|
d
|
|
days (24 hours)
|
|
|
h
|
|
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.
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 shutdown), 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 an
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).
|
|
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 frequency of
execution (this is equivalent to option runfreq) or a
declaration of options; it has five time and date fields,
and a shell 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
compatibility 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: |
|
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 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 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 begin by a
"%", followed by one of the keywords : |
|
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:
|
|
daily, middaily, nightly, weekly, midweekly
: |
|
For example : ’%nightly * 21-23,3-5 echo "a
monthly entry"’
will run the command once each night either between 21:00
and 23:59, or between 3:00 and 5:59.
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 keyword 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 non-matching time
and dates in the lines with that kind of keyword (i.e. the
following is not allowed : "%hours * 0-23 * * *
echo", but "%hours * 0-22 * * * echo" is
allowed).
Note : a single number in a field is considered as an
interval : "%mins 15 2-4 * * * 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 2-4 * * * 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 its
abbreviation. The options are (abbreviation and default
value between brackets): |
|
Reset options to default.
|
|
Can a job be executed several times simultaneously
?
see also : options serialonce, lavgonce.
|
|
Can a job be queued several times in serial queue
simultaneously ?
see also : options exesev, lavgonce.
|
|
serial (s)
|
|
boolean(false)
|
|
|
Fcron runs at most 1 serial jobs (and the same number of
lavg serial jobs) simultaneously (but this value may be
modified by fcron’s option -m).
see also : options serialonce, lavg.
|
|
bootrun (b)
|
|
boolean(false)
|
|
|
Run a &-line at fcron’s startup if it should
have be run during system down time.
|
|
Delay before first execution of a job based on system up
time ("@"-lines).
|
|
Run every "runfreq" matches of time and date.
(this option is ignored for lines based on elapsed system up
time).
|
|
mailto
|
|
user-name(name of file’s owner)
|
|
|
Mail output (if needed) to "mailto". A mailto
declared and empty (string "") is equivalent to
"mail(false)".
see also : options mail, forcemail, nolog.
|
|
Mail output (if any) or not.
see also : options mailto, forcemail, nolog.
|
|
Mail output even if zero-length.
see also : options mail, mailto, nolog.
|
|
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, forcemail.
|
|
Perform a logic AND between week and month day.
see also : option dayor.
|
|
Perform a logic OR between week and month day.
see also : option dayand.
|
|
Change job priority. A nice value is an integer
from -20 (highest priority) to 19 (lowest) (only root is
allowed to use a negative value with this option).
|
|
Run with "user-name" permissions and
environment (only root is allowed to use this option).
|
|
Set the values of the 1, 5 and 15 minutes (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"), any other decimals are only used to round
off. Set a value to 0 to ignore the corresponding load
average.
see also : options lavg1, lavg5, lavg15, until,
lavgonce, lavgor, lavgand, strict, noticenotrun.
|
|
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.
see also : option lavg.
|
|
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 : option lavg.
|
|
Can a job be queued several times in lavg queue
simultaneously ?
see also : option lavg.
|
|
Perform a logic AND between the 1, 5 and 15 minutes
system load average values.
see also : option lavg, lavgor.
|
|
Perform a logic OR between the 1, 5 and 15 minutes system
load average values.
see also : option lavg, lavgand.
|
|
When a lavg %-job is at the end of an 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 : option lavg, noticenotrun.
|
|
boolean(no)
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 : option lavg, strict.
|
|
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 definition is taken into
account.
see also : option lavg, strict. |
|
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 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 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 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, 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)
|
EXAMPLES
|
# 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 * 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 peer 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 last release of Mozilla !"
|
FILES
|
Configuration file for fcron and fcrontab : contains
paths (spool dir, pid file) and default programs to use
(editor, shell, etc). See fcron.conf(5) for more
details.
|
|
Users allowed to use fcrontab (one name per line, special
name "all" acts for everyone)
|
|
Users who are not allowed to use fcrontab (same format as
allow file)
|
SEE ALSO
|
fcrontab(1), fcron(8),
fcron.conf(5).
|
AUTHOR
|
Thibault Godouet <fcron@free.fr>
|
|