1FCRONTAB(5) FCRONTAB(5)
2
6 fcrontab - tables for driving fcron
7
9 A fcrontab is a file containing all tables used by the fcron(8) daemon.
10 In other words, it is the means for a user to tell the daemon "execute
11 this command at this moment". Each user has his own fcrontab, whose
12 commands are executed as his owner (only root can run a job as another
13 using the option runas (see below)).
14 Blank lines, line beginning by a hash sign (#) (which are considered
16 comments), leading blanks and tabs are ignored. Each line in a fcrontab
17 file can be either
18 · an environment setting,
20 · an option setting,
22 · entries based on elapsed system up time,
24 · entries based on absolute time (like normal crontab entries), or
26 · entries run periodically.
28 Any logical line (an entry or an assignment) can be divided into sev‐
30 eral real lines (the lines which end by a newline character) by placing
31 a backslash (\) before the newline character (\n).
32 THE ENVIRONMENT SETTINGS
34 The environment settings are of the form
35 name = value
38 where the blanks around equal-sign (=) are ignored and optional. Trail‐
40 ing blanks are also ignored, but you can place the value in quotes
41 (simple or double, but matching) to preserve any blanks in the value.
42 When fcron executes a command, it always sets USER, and HOME as defined
44 in /etc/passwd for the owner of the fcrontab from which the command is
45 extracted. TZ is also defined to the value of the option timezone when
46 this option is used. It also defines SHELL to the value of the SHELL
47 used to run the command. Fcron uses the value of SHELL from the
48 fcrontab if any, otherwise it uses the value from fcron.conf if any, or
49 in last resort the value from /etc/passwd. HOME and SHELL may be over‐
50 ridden by settings in the fcrontab, but USER may not. Every other
51 environment assignments defined in the user fcrontab are then made, and
52 the command is executed.
53 Plus, the special variable MAILTO allows you to tell fcron to whom it
55 has to mail the command's output. Note that MAILTO is in fact equiva‐
56 lent to a global declaration of the option mailto (see below). It is
57 only used for backward compatibility, so you should use the option
58 mailto directly.
59 ENTRIES BASED ON ELAPSED SYSTEM UP TIME
61 The entries of commands which have to be run once every m minutes of
62 fcron's execution (which is normally the same as m minutes of system's
63 execution) are of the form
64 @options frequency command
66 where frequency is a time value of the form value*multiplier+value*mul‐
68 tiplier+...+value-in-minutes as "12h02" or "3w2d5h1". The first means
69 "12 hours and 2 minutes of fcron execution" while the second means "3
70 weeks, 2 days, 5 hours and 1 minute of fcron execution". The only valid
71 multipliers are: "VALID TIME MULTIPLIERS" meaning: multipliers:
72 months (4 weeks): m weeks (7 days): w days (24 hours): d
73 hours (60 minutes): h seconds: s
74 In place of options, user can put a time value: it will be interpreted
76 as @first(<time>). If first option is not set, the value of "frequency"
77 is used.
78 This kind of entry does not guarantee a time and date of execution (as
80 the job is delayed at each startup by the time elapsed since the shut‐
81 down), but should be useful for jobs depending on the number of things
82 done by the users (for instance, the filesystem should better be
83 checked after a certain amount of use by the users rather than every x
84 days, as the system may run from 1 day to x days during that x days
85 interval).
86 The time remaining before next execution is saved every 1800 seconds
88 (to limit damages caused by a crash) and when fcron exits after having
89 received a SIGTERM signal, i.e. when systems go down. Thus, this kind
90 of entries is particularly useful for systems that don't run regularly.
91 The syntax being very simple, it may also useful for tasks which don't
92 need to be run at a specific time and date.
93 See also: options first, mail, nolog, serial, lavg, nice, runas (see
95 below).
96 SOME EXAMPLES OF LINES BASED ON ELAPSED SYSTEM UP TIME
98 # Get our mails every 30 minutes
99 @ 30 getmails -all
100 # make some security tests every 48 hours of system up time,
102 # force a mail to be sent to root even if there is no output
103 @mailto(root),forcemail 2d /etc/security/msec/cron-sh/security.sh
104 ENTRIES BASED ON TIME AND DATE
106 The second type of fcrontab's entries begins by an optional "&", which
107 can be immediately followed by an optional number defining the fre‐
108 quency of execution (this is equivalent to option runfreq) or a decla‐
109 ration of options; it has five time and date fields, and a shell com‐
110 mand :
111 &options min hrs day-of-month month day-of-week command
113 Note that the shell command may be preceded by a user name, which is
115 equivalent to runas(<user>): as it is only here for backward compati‐
116 bility you should use option runas (see below) instead. The frequency
117 is interpreted as: "run this command after x matches of time and date
118 fields". The time and date fields are: "TIME AND DATE FIELDS" field:
119 allowed values: minute: 0-59 hour: 0-23 day of month:
120 1-31 month: 1-12 (or names, see below) day of week: 0-7 (0
121 and 7 are both Sunday, or names)
122 A field is always filled by either an asterisk (*), which acts as
124 "first-last" range, a single number or a list.
125 List are numbers or range separated with commas (,). For instance:
127 "2,5,15,23".
128 Ranges of number are of the form "<begin>-<end>", where "begin" and
130 "end" are included. For example, "3-5" specifies the values 3, 4 and 5.
131 You can also add an optional "/number" to a range, where the number
132 specifies skips of the number's value through the range. For example,
133 "0-23/2" can be used in the hours field to specify command execution
134 every other hour. Finally, one or several "~number" can be added to
135 turn off some specific values in a range. For example, "5-8~6~7" is
136 equivalent to "5,8". The final form of a field is:
137 a[-b[/c][~d][~e][...]][,f[-g[/h][~i][~j][...]]][,...]
140 where the letters are integers.
142 You can also use an asterisk (*) in a field. It acts for "first-last".
144 For example, a "*" in the field minute means all minutes from minute 0
145 down to minute 59.
146 Ranges can be included in a list as a single number. For instance:
148 "2,5-10/2~6,15,20-25,30".
149 Names can also be used for the "month" and "day of week" fields. To do
151 so, use the first three letters of the particular day or month (case
152 doesn't matter). Please note that names are used exactly as numbers:
153 you can use them in a list or a range.
154 If a day of month and a day of week are given, the command will execute
156 only when both match with the current time and date unless option dayor
157 is set. For example, with the line
158 5 10 31 * 7 echo ''
160 echo will only be executed days which are a Sunday AND a 31th, at
161 10:05.
162 See also: options dayor, bootrun, runfreq, mail, nolog, serial, lavg,
164 nice, runas (see below).
165 SOME EXAMPLES OF ENTRIES BASED ON TIME AND DATE
167 # run mycommand at 12:05, 12:35, 13:05, 13:35,
168 # 14:05 *and* 14:35 everyday
169 & 05,35 12-14 * * * mycommand -u me -o file
170 # get mails every hour past 20, 21, 22, and 24 minutes.
172 20-24~23 * * * * getmail
173 # save our work of the day every night at 03:45 with a low priority
175 # unless we are sunday, mail the output to jim and run that job
176 # at startup if computer was down at 03:45
177 &nice(10),mailto(jim),bootrun 45 03 * * *~0 "save --our work"
178 ENTRIES RUN PERIODICALLY
180 The third type of fcrontab's entries begin by a "%", followed by a key‐
181 word from one of 3 different lists, and optional options.
182 *LY KEYWORDS
184 Those keywords are:
185 hourly , daily , monthly , weekly
187 Those keywords tell fcron to run the command once from the beginning of
189 the corresponding time interval to the end of that time interval. A
190 time interval is, for example, the time from Monday 16:20 to Wednesday
191 01h43. For instance, the keyword weekly tells fcron to run a command
192 once between Monday and Sunday each week.
193 With this two kind of keywords, user must give the needed time fields
195 (as defined in "Entries based on time and date" (see above)) to specify
196 when the command should be run during each time interval:
197 "NEEDED TIME FIELDS FOR EACH KEYWORD" Keywords: must be followed by the
199 fields: hourly, midhourly: minutes. daily, middaily, nightly, weekly,
200 midweekly: minutes and hours. monthly, midmonthly: minutes, hours and
201 days.
202 MID*LY KEYWORDS
204 They are similar to the "*ly" ones:
205 midhourly , middaily , nightly , midmonthly , midweekly
207 They work exactly has the "*ly" keywords, except that the time inter‐
209 vals are defined from middle to middle of the corresponding "*ly"
210 intervals: midweekly will run a command once from Thursday to Wednes‐
211 day. Note that nightly is equivalent to middaily.
212 For example:
214 %nightly,mail(no) * 21-23,3-5 echo "a nigthly entry"
216 will run the command once each night either between 21:00 and 23:59, or
218 between 3:00 and 5:59 (it will run as soon as possible. To change that,
219 use option random) and won't send mail (because option mail is set to
220 "no").
221 See also: options lavg, noticenotrun, strict, mail, nolog, serial,
223 nice, runas, random (see below).
224 *S KEYWORDS
226 They are:
227 mins , hours , days , mons , dow
229 Those keywords act differently, as follows:
231 run this command once during EACH time interval specified, ignoring the
233 fields below the keyword in the time interval definition (a hours pre‐
234 vents the mins field to be considered as a time interval, but it will
235 be used to determine when the line should be run during an interval:
236 see the note below) (dow means "day of week").
237 Such a keyword is followed by 5 time and date fields (the same fields
239 used for a line based on absolute time (see above)). Furthermore, there
240 must be some non-matching time and dates in the lines with that kind of
241 keyword (i.e. the following is not allowed :
242 %hours * 0-23 * * * echo "INCORRECT line!"
244 but
245 %hours * 0-22 * * * echo "Ok."
247 is allowed).
248 Note:
250 a single number in a field is considered as a time interval:
252 %mins 15 2-4 * * * echo
254 will run at 2:15, 3:15 AND 4:15 every day.
255 But all fields below the keywords are ignored in time interval
257 definition:
258 %hours 15 2-4 * * * echo
260 will run only ONCE either at 2:15, 3:15 OR 4:15.
261 See also: option random (see below).
263 OPTIONS
265 The options can be set either for every line below the declaration or
266 for an individual line. In the first case, the setting is done on a
267 whole line immediately after an exclamation mark (!), while it is done
268 after a "&", a "%" or a "@" depending on the type of scheduling in the
269 second case. Note that an option declaration in a schedule overrides
270 the global declaration of that same option.
271 Options are separated by commas (,) and their arguments, if any, are
273 placed in parentheses ("(" and ")") and separated by commas. No spaces
274 are allowed. A declaration of options is of the form
275 option[(arg1[,arg2][...])][,option[(arg1[...])]][...]
278 where option is either the name of an option or its abbreviation. The
280 options are (default value in parentheses): "VALID OPTIONS IN A
281 FCRONTAB"
282 bootrun
284 b boolean(false)
286 Run a &-line at fcron's startup if it should have be run during
288 system down time.
289 dayand boolean(true)
291 Perform a logic AND between week and month day.
293 See also: options dayor.
295 dayor boolean(false)
297 Perform a logic OR between week and month day.
299 See also: options dayand.
301 exesev boolean(false)
303 Can a job be executed several times simultaneously ?
305 See also: options serialonce, lavgonce.
307 first
309 f time-value
311 Delay before first execution of a job based on system up time
313 ("@"-lines). Useful in the following case: you have several jobs
314 running, say, every hour. By setting different first value for
315 each job, you can avoid them to run simultaneously everytime.
316 You can also set it to 0, which is useful when used in conjunc‐
317 tion with option volatile.
318 forcemail
320 boolean(false)
321 Mail output even if zero-length.
323 See also: options mail, mailto, nolog.
325 lavg real(0) real(0) real(0)
327 Set the values of the 1, 5 and 15-minute (in this order) system
329 load average values below which the job should run. The values
330 have a maximum of 1 decimal (i.e. "2.3"): if there are more than
331 1 decimal, the value will be round off. Set a value to 0 to
332 ignore the corresponding load average (or all of the values to
333 run the job regardless of the load average).
334 See also: options lavg1, lavg5, lavg15, until, lavgonce, lavgor,
336 lavgand, strict, noticenotrun.
337 lavg1
339 lavg5
341 lavg15 real(0)
343 Set the threshold of, respectively, the 1, 5 or 15 minutes sys‐
345 tem load average value. Set one of them to 0 to ignore the cor‐
346 responding load average.
347 See also: options lavg.
349 lavgand
351 boolean(true)
352 Perform a logic AND between the 1, 5 and 15 minutes system load
354 average values.
355 See also: options lavg, lavgor.
357 lavgonce
359 boolean(1)
360 Can a job be queued several times in lavg queue simultaneously?
362 See also: options lavg.
364 lavgor boolean(false)
366 Perform a logic OR between the 1, 5 and 15 minutes system load
368 average values.
369 See also: options lavg, lavgand.
371 mail
373 m boolean(true)
375 Mail output (if any) or not.
377 See also: options mailto, forcemail, nolog.
379 mailto email-address(name of file's owner)
381 Mail output (if needed) to "email-address". It can be either a
383 single user-name or a fully qualified email address. A mailto
384 declared and empty (string "") is equivalent to "mail(false)".
385 See also: options mail, forcemail, nolog.
387 nice
389 n nice-value
391 Change job priority. A nice-value is an integer from -20 (high‐
393 est priority) to 19 (lowest) (only root is allowed to use a neg‐
394 ative value with this option).
395 nolog boolean(false)
397 If set to true, log only errors for the corresponding job(s).
399 May be useful for jobs running very often, and/or to reduce disk
400 access on a laptop.
401 See also: options mail, mailto, forcemail.
403 noticenotrun
405 boolean(false)
406 Should fcron mail user to report the non-execution of a %-job or
408 a &-job? (because of system down state for both or a too high
409 system load average for the latter)
410 See also: options lavg, strict.
412 random boolean(false)
414 In a line run periodically, this option answers the question:
416 should this job be run as soon as possible in its time interval
417 of execution (safer), or should fcron set a random time of exe‐
418 cution in that time interval? Note that if this option is set,
419 the job may not run if fcron is not running during the whole
420 execution interval. Besides, you must know that the random
421 scheme may be quite easy to guess for skilled people: thus, you
422 shouldn't rely on this option to make important things secure.
423 However, it shouldn't be a problem for most uses.
424 reset boolean
426 Reset all the options to default.
428 runas user-name
430 Run with "user-name" permissions and environment (only root is
432 allowed to use this option).
433 runfreq
435 r integer
437 Run every "runfreq" matches of time and date. (this option is
439 ignored for lines based on elapsed system up time).
440 serial
442 s boolean(false)
444 Fcron runs at most 1 serial jobs (ie. for which the option
446 serial is set to true), and the same number of lavg serial jobs
447 (ie. for which both option serial and lavg (or lavg1 or lavg5 or
448 lavg15) are set to true) simultaneously. This value may be modi‐
449 fied by fcron's option -m. This option is especially useful when
450 used with big jobs in order to limit the system overload.
451 See also: options serialonce, lavg.
453 serialonce
455 boolean(0)
456 Can a job be queued several times in serial queue simultane‐
458 ously?
459 See also: options exesev, lavgonce.
461 stdout boolean(false)
463 If fcron is running in the foreground, then also let jobs print
465 to stderr/stdout instead of mailing or discarding it.
466 See also: fcron's option --once in fcron(8).
468 strict boolean(true)
470 When a lavg %-job is at the end of a time interval of execution,
472 should it be removed from the lavg queue (strict(true), so the
473 job is not run) or be let there until the system load average
474 allows its execution (strict(false))?
475 See also: options lavg, noticenotrun.
477 timezone
479 timezone-name(time zone of the system)
480 Run the job in the given time zone. timezone-name is a string
482 which is valid for the environment variable TZ: see the documen‐
483 tation of your system for more details. For instance,
484 "Europe/Paris" is valid on a Linux system. This option handles
485 daylight saving time changes correctly. The TZ environ,ment
486 variable is set to the value of timezone when a job defining
487 this option is run.
488 Please note that if you give an erroneous timezone-name argu‐
490 ment, it will be SILENTLY ignored, and the job will run in the
491 time zone of the system.
492 WARNING: do *not* use option timezone and option tzdiff simulta‐
494 neously! There is no need to do so, and timezone is cleverer
495 than tzdiff.
496 See also: options tzdiff.
498 tzdiff integer(0)
500 WARNING: this option is deprecated: use option timezone instead!
502 Time zone difference (in hours, between -24 and 24) between the
504 system time, and the local real time. This option allows a user
505 to define its & and %-lines in the local time. Note that this
506 value is set for a whole fcrontab file, and only the last defi‐
507 nition is taken into account. tzdiff is quite stupid: it doesn't
508 handle daylight saving changes, while option timezone does, so
509 you should use the latter.
510 See also: options timezone.
512 until time-value(0)
514 Set the timeout of the waiting of the wanted system load average
516 values. If the timeout is exceeded, the job runs no matter the
517 load average. Set until to 0 to remove the timeout.
518 See also: options lavg.
520 volatile
522 boolean(false)
523 When set to true, the job is based on a "volatile" system up
525 time, i.e. restart counting each time fcron is started, which is
526 useful when fcron is started by a script running only, for
527 instance, during a dialup connection: the "volatile" system up
528 time then refers to the dialup connection time. You may also
529 want to use option first if you use fcron that way.
530 See also: options first, stdout, lines based on elapsed system
532 up time, fcron's option --once in fcron(8).
533 A boolean argument can be non-existent, in which case parentheses are
535 not used and it means true; the string "true", "yes" or 1 to mean true;
536 and the string "false", "no" or 0 to mean false. See above for explana‐
537 tions about time value (section "entries based on elapsed system up
538 time").
539 Note that dayand and dayor are in fact the same option: a false value
541 to dayand is equivalent to a true to dayor, and reciprocally a false
542 value to dayor is equivalent a true value to dayand. It is the same for
543 lavgand and lavgor.
544 Note a special case to be handled: A job should be entered into the
546 serial queue, *but* the previous entry for this job has not been com‐
547 pleted yet, because of high system load or some external event. Option
548 serialonce answers the question: should the new entry of the job be
549 ignored? This way one can distinguish between jobs required to run a
550 certain number of times, preferably at specified times, and tasks to be
551 performed irrespective of their number (-> serialonce(true)), which
552 make the system respond faster.
553 The same considerations apply for the load average queue, and can be
555 expressed with option lavgonce.
556 Moreover, if the serial or the lavg queue contains respectively more
558 than 30 and 30 jobs, any new job is refused and not run to avoid an
559 overwhelming of system resources. In this case, an error message is
560 logged through syslog.
561 Finally, if jobs remain in the lavg or serial queues when fcron stops,
563 they will be put once in the corresponding queue on startup (their
564 order may not be conserved).
565 AN EXAMPLE OF AN OPTION DECLARATION:
567 !reset,serial(true),dayor,bootrun(0),mailto(root),lavg(.5,2,1.5)
568
570 AN EXAMPLE OF A USER FCRONTAB
571 # use /bin/bash to run commands, ignoring what /etc/passwd says
572 SHELL=/bin/bash
573 # mail output to thib, no matter whose fcrontab this is
575 !mailto(thib)
576 # define a variable which is equivalent to " Hello thib and paul! "
578 # here the newline characters are escaped by a backslash (\)
579 # and quotes are used to force to keep leading and trailing blanks
580 TEXT= " Hello\
581 thib and\
582 paul! "
583 # we want to use serial but not bootrun:
585 !serial(true),b(0)
586 # run after five minutes of execution the first time,
588 # then run every hour
589 @first(5) 1h echo "Run every hour"
590 # run every day
592 @ 1d echo "fcron daily"
593 # run once between in the morning and once in the afternoon
595 # if systems is running at any moment of these time intervals
596 %hours * 8-12,14-18 * * * echo "Hey boss, I'm working today!"
597 # run once a week during our lunch
599 %weekly * 12-13 echo "I left my system on at least once \
600 at lunch time this week."
601 # run every Sunday and Saturday at 9:05
603 5 9 * * sat,sun echo "Good morning Thibault!"
604 # run every even days of march at 18:00, except on 16th
606 0 18 2-30/2~16 Mar * echo "It's time to go back home!"
607 # the line above is equivalent to
609 & 0 18 2-30/2~16 Mar * echo "It's time to go back home!"
610 # reset options to default and set runfreq for lines below
612 !reset,runfreq(7)
613 # run once every 7 matches (thanks to the declaration above),
615 # so if system is running every day at 10:00, this will be
616 # run once a week
617 & 0 10 * * * echo "if you got this message last time 7 days ago,\
618 this computer has been running every day at 10:00 last week.\
619 If you got the message 8 days ago, then the system has been down \
620 one day at 10:00 since you got it, etc"
621 # wait every hour for a 5 minutes load average under 0.9
623 @lavg5(0.9) 1h echo "The system load average is low"
624 # wait a maximum of 5 hours every day for a fall of the load average
626 @lavgand,lavg(1,2.0,3.0),until(5h) 1d echo "Load average is going down"
627 # wait for the best moment to run a heavy job
629 @lavgor,lavg(0.8,1.2,1.5),nice(10) 1w echo "This is a heavy job"
630 # run once every night between either 21:00 and 23:00 or
632 # between 3:00 and 6:00
633 %nightly,lavg(1.5,2,2) * 21-23,3-6 echo "It's time to retrieve \
634 the latest release of Mozilla!"
635
637 /usr/local/etc/fcron.conf
638 Configuration file for fcron, fcrontab and fcrondyn: contains
639 paths (spool dir, pid file) and default programs to use (editor,
640 shell, etc). See fcron.conf(5) for more details.
641 /usr/local/etc/fcron.allow
643 Users allowed to use fcrontab and fcrondyn (one name per line,
644 special name "all" acts for everyone)
645 /usr/local/etc/fcron.deny
647 Users who are not allowed to use fcrontab and fcrondyn (same
648 format as allow file)
649 /usr/local/etc/pam.d/fcron (or /usr/local/etc/pam.conf)
651 PAM configuration file for fcron. Take a look at pam(8) for more
652 details.
653
655 fcrontab(1),
656 fcrondyn(1),
658 fcrontab(5),
660 fcron.conf(5),
662 fcron(8).
664 If you're learning how to use fcron from scratch, I suggest that you
666 read the HTML version of the documentation (if your are not reading it
667 right now! :) ): the content is the same, but it is easier to navigate
668 thanks to the hyperlinks.
669
671 Thibault Godouet <fcron@free.fr>
67206/03/2007 03 juin 2007 FCRONTAB(5)