Generated by groff

fcrontab.5


NAME
DESCRIPTION
EXAMPLE
FILES
SEE ALSO
AUTHOR

NAME

fcrontab - 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").

Blank lines, line beginning by a pound-sign (#) (which are considered as comments), leading blanks and tabs are ignored. Each line in a fcrontab file can be either an environment setting, an option setting, the entry of a command based on running time or the entry of a command based on time and date (as a normal crontab entry). 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
The environment settings are of the form

name = value

where the blanks around equal-sign (=) are ignored and optional. Trailing blanks are also ignored, but you can place the value in quotes (simple or double but matching) to preserve needed leading and trailing blanks of 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 command's output. Note that MAILTO is in fact equivalent to a global declaration of the option "mailto" (see below). It is only use for back- ward compatibility, so you should use the option "mailto" directly.

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 "&" or a "@" depending to the type of line in the second case. Note that an option declaration in a line override the global declaration of the same option.
Options are separated by comas (,) and their arguments, if any, are placed between brack- ets ("(" 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 (abbreviation and default value between brackets):

reset

boolean
Reset options to default.

serial (s)

boolean(false)
Run jobs one by one ?

bootrun (b)

boolean(false)
Run at fcron's startup if it should have be run during system down time.

first (f)

time-value
Delay before first execution of a job based on system up time.

runfreq (r)

integer
Run every "runfreq" match of time and date.

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)".

mail (m)

boolean(true)
Mail output (if any) or not.

forcemail

boolean(false)
Mail output even if zero-length.


dayand

boolean(true)
Perform a logic AND between week and month day.

dayor

boolean(false)
Perform a logic OR between week and month day.

nice (n)

nice-value
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).

runas

user-name
Run with "user-name" permissions and environment (only root is allowed to use this option).

lavg

real real real
Set the values of the 1, 5 and 15 minutes (in this order) system load average values under 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.

lavg1 lavg5 lavg15
real(0)

Set the value of, respectively, the 1, 5 or 15 minutes system load average value. Set the value to 0
to ignore a load average.

until

time-value(0)
Set the timeout of the waiting of the wanted system load average values. Set until to 0 to remove
the timeout.

lavgand

boolean(true)
Perform a logic AND between the 1, 5 and 15 minutes system load average values.

lavgor

boolean(false)
Perform a logic OR between the 1, 5 and 15 minutes system load average values.

A boolean argument can be : inexistent, in which case brackets are not used and it means true; the string "true" or 1 to mean true; and the string "false" or 0 to mean false. See below for explanations about time value and runfreq.

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. Concerning to the serial option, if the queue contains more than 30 jobs, the next job to be executed in the serial queue will be executed before adding a new job. If the following number is positive (depending to the compilation options): 0 , a job will not be put several times in the serial queue at the same time.

Alike, if the lavg queue contains more than 30 jobs, the nearest job to the until timeout in the queue will be exe- cuted before adding a new job. If the following number is positive (depending to the compilation options): 1 , a job will not be put several times in the lavg queue at the same time.

WARNING : the value of options runas and mailto are stored internally as a uid number. You MUST reinstall all your fcrontabs if you change the uid number of a user. If you do not do this, executions of jobs may fail, some job could be executed as an another user, etc.

An example of an option declaration would be :
!reset,serial(true),dayor,bootrun(0),mailto(root),lavg(.5,2,1.5)

Entries based on frequency

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*multiplier+...+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:

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.

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 com- mand. The frequency is interpreted as: "run this command after three matches of time and date fields", unless the frequency is set to 1, in which case it will be interpreted as "run this command once during each interval specified". The time and date fields are:

field

minute

hour

day of month

month

day of week

allowed values

0-59

0-23

1-31

1-12 (or names, see below)

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" speci- fies 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 par- ticular 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.

EXAMPLE

# 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 serialize but not bootrun:
!serialize(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 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 intervals
&1 * 8-12,14-18 * * * echo "Hey boss, I'm working today !"

# 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 match, so if system is running every day
# at 10:00, this will be run once a week
&7 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) 1w echo "This is a heavy job"

FILES

/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)

SEE ALSO

fcron(8), fcrontab(1)

AUTHOR

Thibault Godouet <fcron@free.fr>