A copy of the license is included in gfdl.sgml.
-->
-<!-- $Id: fcrontab.5.sgml,v 1.4 2002-01-27 16:43:18 thib Exp $ -->
+<!-- $Id: fcrontab.5.sgml,v 1.5 2002-02-16 10:09:50 thib Exp $ -->
<refentry id="fcrontab.5">
<refmeta>
<para>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 a 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).</para>
<para>The time remaining before next execution is saved every &save; seconds (to limit damages caused by a crash) and when &fcron; exits after having received a <constant>SIGTERM</constant> 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.</para>
<para>&seealso; options &optfirst;, &optmail;, &optnolog;, &optserial;, &optlavg;, &optnice;, &optrunas; (see below).</para>
+ <para><example>
+ <title>Some examples of lines based on elapsed system up time</title>
+ <programlisting>
+# Get our mails every 30 minutes
+@ 30 getmails -all
+
+# make some security tests every 48 hours of system up time,
+# force a mail to be sent to root even if there is no output
+@mailto(root),forcemail 2d /etc/security/msec/cron-sh/security.sh
+</programlisting>
+ </example></para>
</refsect2>
<refsect2 id="fcrontab.5.tadent">
<title>Entries based on time and date</title>
- <para>The second type of &fcrontabf;'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 &optrunfreq;) 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 <token>runas(<replaceable>user</replaceable>)</token>: as it is only here for backward compatibility you should use option &optrunas; (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:</para>
+ <para>The second type of &fcrontabf;'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 &optrunfreq;) or a declaration of options; it has five time and date fields, and a shell command :</para>
+ <programlisting>&options min hrs day-of-month month day-of-week command</programlisting>
+ <para>Note that the shell command may be preceded by a user name, which is equivalent to <token>runas(<replaceable>user</replaceable>)</token>: as it is only here for backward compatibility you should use option &optrunas; (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:</para>
<table>
<title>Time and date fields</title>
<tgroup cols="2">
<para>You can also use an asterisk (*) in a field. It acts for "<token>first-last</token>". For example, a "*" in the field minute means all minutes from minute 0 down to minute 59.</para>
<para>Ranges can be included in a list as a single number. For instance: "2,5-10/2~6,15,20-25,30".</para>
<para>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.</para>
- <para>If a day of month and a day of week are given, the command will execute only when <emphasis>both</emphasis> match with the current time and date unless option &optdayor; is set. For example, with the line <programlisting>5 10 31 * 7 echo ''</programlisting> echo will be executed only days which are a Sunday AND a 31th.</para>
-
+ <para>If a day of month and a day of week are given, the command will execute only when <emphasis>both</emphasis> match with the current time and date unless option &optdayor; is set. For example, with the line <programlisting>5 10 31 * 7 echo ''</programlisting> echo will only be executed days which are a Sunday AND a 31th, at 10:05.</para>
<para>&seealso; options &optdayor;, &optbootrun;, &optrunfreq;, &optmail;, &optnolog;, &optserial;, &optlavg;, &optnice;, &optrunas; (see below).</para>
+ <para><example>
+ <title>Some examples of entries based on time and date</title>
+ <programlisting>
+# run mycommand at 12:05, 12:35, 13:05, 13:35, 14:05 *and* 14:35 everyday
+& 05,35 12-14 * * * mycommand -u me -o file
+
+# get mails every hours past 20, 21, 22, and 24 minutes.
+20-24~23 * * * * getmail
+
+# save our work of the day every night at 03:45 with a low priority
+# unless we are sunday, mail the output to jim and run that job
+# at startup if computer was down at 03:45
+&nice(10),mailto(jim),bootrun 45 03 * * *~0 "save --our work"
+</programlisting>
+ </example></para>
</refsect2>
<refsect2 id="fcrontab.5.periodent">
</tbody>
</tgroup>
</table>
- <para>For example :</para>
+ <para>For example :
<informalexample>
- <para>%nightly * 21-23,3-5 echo "a monthly entry"</para>
- </informalexample>
- <para>will run the command once each night either between 21:00 and 23:59, or between 3:00 and 5:59.</para>
- <para>&seealso; options &optlavg;, &optnoticenotrun;, &optstrict;, &optmail;, &optnolog;, &optserial;, &optnice;, &optrunas; (see below).</para>
+ <programlisting>
+%nightly,mail(no) * 21-23,3-5 echo "a nigthly entry"
+</programlisting>
+ </informalexample></para>
+ <para>will run the command once each night either between 21:00 and 23:59, or between 3:00 and 5:59 (it will run as soon as possible. To change that, use option &optrandom;) and won't send mail (due to the optional use of option &optmail;).</para>
+ <para>&seealso; options &optlavg;, &optnoticenotrun;, &optstrict;, &optmail;, &optnolog;, &optserial;, &optnice;, &optrunas;, &optrandom; (see below).</para>
<para>The keywords of the third list act differently, as follows:</para>
<para>run this command once during EACH interval specified, ignoring the fields below the keyword in the interval definition (a <parameter>hours</parameter> 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) (<parameter>dow</parameter> means "day of week").</para>
- <para>Such a keyword is followed by 5 time and date fields (the same fields used for a <link linkend="fcrontab.5.tadent">line based on absolut time</link> (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 : <programlisting>%hours * 0-23 * * * echo</programlisting> but <programlisting>%hours * 0-22 * * * echo</programlisting> is allowed).</para>
+ <para>Such a keyword is followed by 5 time and date fields (the same fields used for a <link linkend="fcrontab.5.tadent">line based on absolute time</link> (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 : <programlisting>%hours * 0-23 * * * echo "INCORRECT line !"</programlisting> but <programlisting>%hours * 0-22 * * * echo "Ok."</programlisting> is allowed).</para>
<note>
<para>a single number in a field is considered as an interval : <programlisting>%mins 15 2-4 * * * echo</programlisting> will run at 2:15, 3:15 AND 4:15 every day.</para>
<para>But every fields below the keywords are ignored in interval definition : <programlisting>%hours 15 2-4 * * * echo</programlisting> will run only ONCE either at 2:15, 3:15 OR 4:15.</para>
<term>reset</term>
<listitem>
<para><emphasis><type>boolean</type></emphasis></para>
- <para>Reset options to default.</para>
+ <para>Reset all the options to default.</para>
</listitem>
</varlistentry>
<varlistentry id="fcrontab.5.exesev">
<term>s</term>
<listitem>
<para><emphasis><type>boolean</type></emphasis>(<constant>false</constant>)</para>
- <para>&Fcron; runs at most &serialmaxrunning; serial jobs (and the same number of lavg serial jobs) simultaneously (but this value may be modified by &fcron;'s option <option>-m</option>).</para>
+ <para>&Fcron; runs at most &serialmaxrunning; serial jobs (and the same number of lavg serial jobs) simultaneously (but this value may be modified by &fcron;'s option <option>-m</option>). May be used with big jobs to limit system overload.</para>
<para>&seealso; options &optserialonce;, &optlavg;.</para>
</listitem>
</varlistentry>
<term>f</term>
<listitem>
<para><emphasis><type>time-value</type></emphasis></para>
- <para>Delay before first execution of a job based on system up time ("@"-lines).</para>
+ <para>Delay before first execution of a job based on system up time ("@"-lines). Useful in the following case : you have several jobs running, say, every hour. By setting different first value for each job, you can avoid them to run simultaneously everytime.</para>
</listitem>
</varlistentry>
<varlistentry id="fcrontab.5.runfreq">
<term>mailto</term>
<listitem>
<para><emphasis><type>user-name</type></emphasis>(<constant>name of file's owner</constant>)</para>
- <para>Mail output (if needed) to "<replaceable>mailto</replaceable>". A &optmailto; declared and empty (string "") is equivalent to "<token>mail(false)</token>".</para>
+ <para>Mail output (if needed) to "<replaceable>user-name</replaceable>". A &optmailto; declared and empty (string "") is equivalent to "<token>mail(false)</token>".</para>
<para>&seealso; options &optmail;, &optforcemail;, &optnolog;.</para>
</listitem>
</varlistentry>
<term>noticenotrun</term>
<listitem>
<para><emphasis><type>boolean</type></emphasis>(<constant>no</constant>)</para>
- <para>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).</para>
+ <para>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)</para>
<para>&seealso; options &optlavg;, &optstrict;.</para>
</listitem>
</varlistentry>
<para>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 <varname>serialonce</varname> 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.</para>
<para>The same considerations apply for the load average queue, and can be expressed with option <varname>lavgonce</varname>.</para>
- <para>Moreover, if the serial or the lavg queue contains respectively more than &serialqueuemax; and &lavgqueuemax; 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.</para>
+ <para>Moreover, if the serial or the lavg queue contains respectively more than &serialqueuemax; and &lavgqueuemax; jobs, any new job is refused and not run to avoid an overwhelming of system resources. In this case, an error message is logged through syslog.</para>
<para>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).</para>
<para><example>
<title>An example of an option declaration :</title>
# 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 !"
+%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 \
projects / fcron / commitdiff