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 erroronlymail
303 boolean(false)
304 Mail output only if job exited with a non-zero status.
306 See also: options mail, mailto, forcemail, nolog.
308 exesev boolean(false)
310 Can a job be executed several times simultaneously ?
312 See also: options serialonce, lavgonce.
314 first
316 f time-value
318 Delay before first execution of a job based on system up time
320 ("@"-lines). Useful in the following case: you have several jobs
321 running, say, every hour. By setting different first value for
322 each job, you can avoid them to run simultaneously everytime.
323 You can also set it to 0, which is useful when used in conjunc‐
324 tion with option volatile.
325 forcemail
327 boolean(false)
328 Mail output even if zero-length.
330 See also: options mail, mailto, erroronlymail, nolog.
332 lavg real(0) real(0) real(0)
334 Set the values of the 1, 5 and 15-minute (in this order) system
336 load average values below which the job should run. The values
337 have a maximum of 1 decimal (i.e. "2.3"): if there are more than
338 1 decimal, the value will be round off. Set a value to 0 to
339 ignore the corresponding load average (or all of the values to
340 run the job regardless of the load average).
341 See also: options lavg1, lavg5, lavg15, until, lavgonce, lavgor,
343 lavgand, strict, noticenotrun.
344 lavg1
346 lavg5
348 lavg15 real(0)
350 Set the threshold of, respectively, the 1, 5 or 15 minutes sys‐
352 tem load average value. Set one of them to 0 to ignore the cor‐
353 responding load average.
354 See also: options lavg.
356 lavgand
358 boolean(true)
359 Perform a logic AND between the 1, 5 and 15 minutes system load
361 average values.
362 See also: options lavg, lavgor.
364 lavgonce
366 boolean(1)
367 Can a job be queued several times in lavg queue simultaneously?
369 See also: options lavg.
371 lavgor boolean(false)
373 Perform a logic OR between the 1, 5 and 15 minutes system load
375 average values.
376 See also: options lavg, lavgand.
378 mail
380 m boolean(true)
382 Mail output (if any) or not.
384 See also: options mailto, forcemail, erroronlymail, nolog.
386 mailto email-address(name of file's owner)
388 Mail output (if needed) to "email-address". It can be either a
390 single user-name or a fully qualified email address. A mailto
391 declared and empty (string "") is equivalent to "mail(false)".
392 See also: options mail, forcemail, erroronlymail, nolog.
394 nice
396 n nice-value
398 Change job priority. A nice-value is an integer from -20 (high‐
400 est priority) to 19 (lowest) (only root is allowed to use a neg‐
401 ative value with this option).
402 nolog boolean(false)
404 If set to true, log only errors for the corresponding job(s).
406 May be useful for jobs running very often, and/or to reduce disk
407 access on a laptop.
408 See also: options mail, mailto, erroronlymail, forcemail.
410 noticenotrun
412 boolean(false)
413 Should fcron mail user to report the non-execution of a %-job or
415 a &-job? (because of system down state for both or a too high
416 system load average for the latter)
417 See also: options lavg, strict.
419 random boolean(false)
421 In a line run periodically, this option answers the question:
423 should this job be run as soon as possible in its time interval
424 of execution (safer), or should fcron set a random time of exe‐
425 cution in that time interval? Note that if this option is set,
426 the job may not run if fcron is not running during the whole
427 execution interval. Besides, you must know that the random
428 scheme may be quite easy to guess for skilled people: thus, you
429 shouldn't rely on this option to make important things secure.
430 However, it shouldn't be a problem for most uses.
431 reset boolean
433 Reset all the options to default.
435 runas user-name
437 Run with "user-name" permissions and environment (only root is
439 allowed to use this option).
440 runfreq
442 r integer
444 Run every "runfreq" matches of time and date. (this option is
446 ignored for lines based on elapsed system up time).
447 serial
449 s boolean(false)
451 Fcron runs at most 1 serial jobs (ie. for which the option
453 serial is set to true), and the same number of lavg serial jobs
454 (ie. for which both option serial and lavg (or lavg1 or lavg5 or
455 lavg15) are set to true) simultaneously. This value may be modi‐
456 fied by fcron's option -m. This option is especially useful when
457 used with big jobs in order to limit the system overload.
458 See also: options serialonce, lavg.
460 serialonce
462 boolean(0)
463 Can a job be queued several times in serial queue simultane‐
465 ously?
466 See also: options exesev, lavgonce.
468 stdout boolean(false)
470 If fcron is running in the foreground, then also let jobs print
472 to stderr/stdout instead of mailing or discarding it.
473 See also: fcron's option --once in fcron(8).
475 strict boolean(true)
477 When a lavg %-job is at the end of a time interval of execution,
479 should it be removed from the lavg queue (strict(true), so the
480 job is not run) or be let there until the system load average
481 allows its execution (strict(false))?
482 See also: options lavg, noticenotrun.
484 timezone
486 timezone-name(time zone of the system)
487 Run the job in the given time zone. timezone-name is a string
489 which is valid for the environment variable TZ: see the documen‐
490 tation of your system for more details. For instance,
491 "Europe/Paris" is valid on a Linux system. This option handles
492 daylight saving time changes correctly. The TZ environ,ment
493 variable is set to the value of timezone when a job defining
494 this option is run.
495 Please note that if you give an erroneous timezone-name argu‐
497 ment, it will be SILENTLY ignored, and the job will run in the
498 time zone of the system.
499 WARNING: do *not* use option timezone and option tzdiff simulta‐
501 neously! There is no need to do so, and timezone is cleverer
502 than tzdiff.
503 See also: options tzdiff.
505 tzdiff integer(0)
507 WARNING: this option is deprecated: use option timezone instead!
509 Time zone difference (in hours, between -24 and 24) between the
511 system time, and the local real time. This option allows a user
512 to define its & and %-lines in the local time. Note that this
513 value is set for a whole fcrontab file, and only the last defi‐
514 nition is taken into account. tzdiff is quite stupid: it doesn't
515 handle daylight saving changes, while option timezone does, so
516 you should use the latter.
517 See also: options timezone.
519 until time-value(0)
521 Set the timeout of the waiting of the wanted system load average
523 values. If the timeout is exceeded, the job runs no matter the
524 load average. Set until to 0 to remove the timeout.
525 See also: options lavg.
527 volatile
529 boolean(false)
530 When set to true, the job is based on a "volatile" system up
532 time, i.e. restart counting each time fcron is started, which is
533 useful when fcron is started by a script running only, for
534 instance, during a dialup connection: the "volatile" system up
535 time then refers to the dialup connection time. You may also
536 want to use option first if you use fcron that way.
537 See also: options first, stdout, lines based on elapsed system
539 up time, fcron's option --once in fcron(8).
540 A boolean argument can be non-existent, in which case parentheses are
542 not used and it means true; the string "true", "yes" or 1 to mean true;
543 and the string "false", "no" or 0 to mean false. See above for explana‐
544 tions about time value (section "entries based on elapsed system up
545 time").
546 Note that dayand and dayor are in fact the same option: a false value
548 to dayand is equivalent to a true to dayor, and reciprocally a false
549 value to dayor is equivalent a true value to dayand. It is the same for
550 lavgand and lavgor.
551 Note a special case to be handled: A job should be entered into the
553 serial queue, *but* the previous entry for this job has not been com‐
554 pleted yet, because of high system load or some external event. Option
555 serialonce answers the question: should the new entry of the job be
556 ignored? This way one can distinguish between jobs required to run a
557 certain number of times, preferably at specified times, and tasks to be
558 performed irrespective of their number (-> serialonce(true)), which
559 make the system respond faster.
560 The same considerations apply for the load average queue, and can be
562 expressed with option lavgonce.
563 Moreover, if the serial or the lavg queue contains respectively more
565 than 30 and 30 jobs, any new job is refused and not run to avoid an
566 overwhelming of system resources. In this case, an error message is
567 logged through syslog.
568 Finally, if jobs remain in the lavg or serial queues when fcron stops,
570 they will be put once in the corresponding queue on startup (their
571 order may not be conserved).
572 AN EXAMPLE OF AN OPTION DECLARATION:
574 !reset,serial(true),dayor,bootrun(0),mailto(root),lavg(.5,2,1.5)
575
577 AN EXAMPLE OF A USER FCRONTAB
578 # use /bin/bash to run commands, ignoring what /etc/passwd says
579 SHELL=/bin/bash
580 # mail output to thib, no matter whose fcrontab this is
582 !mailto(thib)
583 # define a variable which is equivalent to " Hello thib and paul! "
585 # here the newline characters are escaped by a backslash (\)
586 # and quotes are used to force to keep leading and trailing blanks
587 TEXT= " Hello\
588 thib and\
589 paul! "
590 # we want to use serial but not bootrun:
592 !serial(true),b(0)
593 # run after five minutes of execution the first time,
595 # then run every hour
596 @first(5) 1h echo "Run every hour"
597 # run every day
599 @ 1d echo "fcron daily"
600 # run once between in the morning and once in the afternoon
602 # if systems is running at any moment of these time intervals
603 %hours * 8-12,14-18 * * * echo "Hey boss, I'm working today!"
604 # run once a week during our lunch
606 %weekly * 12-13 echo "I left my system on at least once \
607 at lunch time this week."
608 # run every Sunday and Saturday at 9:05
610 5 9 * * sat,sun echo "Good morning Thibault!"
611 # run every even days of march at 18:00, except on 16th
613 0 18 2-30/2~16 Mar * echo "It's time to go back home!"
614 # the line above is equivalent to
616 & 0 18 2-30/2~16 Mar * echo "It's time to go back home!"
617 # reset options to default and set runfreq for lines below
619 !reset,runfreq(7)
620 # run once every 7 matches (thanks to the declaration above),
622 # so if system is running every day at 10:00, this will be
623 # run once a week
624 & 0 10 * * * echo "if you got this message last time 7 days ago,\
625 this computer has been running every day at 10:00 last week.\
626 If you got the message 8 days ago, then the system has been down \
627 one day at 10:00 since you got it, etc"
628 # wait every hour for a 5 minutes load average under 0.9
630 @lavg5(0.9) 1h echo "The system load average is low"
631 # wait a maximum of 5 hours every day for a fall of the load average
633 @lavgand,lavg(1,2.0,3.0),until(5h) 1d echo "Load average is going down"
634 # wait for the best moment to run a heavy job
636 @lavgor,lavg(0.8,1.2,1.5),nice(10) 1w echo "This is a heavy job"
637 # run once every night between either 21:00 and 23:00 or
639 # between 3:00 and 6:00
640 %nightly,lavg(1.5,2,2) * 21-23,3-6 echo "It's time to retrieve \
641 the latest release of Mozilla!"
642
644 /usr/local/etc/fcron.conf
645 Configuration file for fcron, fcrontab and fcrondyn: contains
646 paths (spool dir, pid file) and default programs to use (editor,
647 shell, etc). See fcron.conf(5) for more details.
648 /usr/local/etc/fcron.allow
650 Users allowed to use fcrontab and fcrondyn (one name per line,
651 special name "all" acts for everyone)
652 /usr/local/etc/fcron.deny
654 Users who are not allowed to use fcrontab and fcrondyn (same
655 format as allow file)
656 /usr/local/etc/pam.d/fcron (or /usr/local/etc/pam.conf)
658 PAM configuration file for fcron. Take a look at pam(8) for more
659 details.
660
662 fcrontab(1),
663 fcrondyn(1),
665 fcrontab(5),
667 fcron.conf(5),
669 fcron(8).
671 If you're learning how to use fcron from scratch, I suggest that you
673 read the HTML version of the documentation (if your are not reading it
674 right now! :) ): the content is the same, but it is easier to navigate
675 thanks to the hyperlinks.
676
678 Thibault Godouet <fcron@free.fr>
67903/03/2010 03 mars 2010 FCRONTAB(5)