svn commit: r44761 - head/en_US.ISO8859-1/books/handbook/config
Dru Lavigne
dru at FreeBSD.org
Mon May 5 15:48:08 UTC 2014
Author: dru
Date: Mon May 5 15:48:07 2014
New Revision: 44761
URL: http://svnweb.freebsd.org/changeset/doc/44761
Log:
Editorial review of cron section.
This probably belongs in Basics chapter.
Modified:
head/en_US.ISO8859-1/books/handbook/config/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon May 5 13:22:25 2014 (r44760)
+++ head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon May 5 15:48:07 2014 (r44761)
@@ -232,53 +232,41 @@ run_rc_command "$1"</programlisting>
<secondary>configuration</secondary>
</indexterm>
- <para>One of the most useful utilities in &os; is &man.cron.8;.
+ <para>One of the most useful utilities in &os; is <application>cron</application>.
This utility runs in the background and regularly checks
<filename>/etc/crontab</filename> for tasks to execute and
searches <filename>/var/cron/tabs</filename> for custom
- &man.crontab.5; files. These files store information about
- specific functions which &man.cron.8; is supposed to perform at
- certain times.</para>
-
- <para>Two different types of configuration files are used by
- &man.cron.8;: the system <filename>crontab</filename> and user
- <filename>crontab</filename>s. These formats only differ in the
- sixth field and later. In the system
- <filename>crontab</filename>, &man.cron.8; runs the command as
- the user specified in the sixth field. In a user
- <filename>crontab</filename>, all commands run as the user who
- created the <filename>crontab</filename>, so the sixth field is
- the last field; this is an important security feature. The
- final field is always the command to run.</para>
+ crontab files. These files are used to schedule
+ tasks which <application>cron</application> runs at the
+ specified times. Each entry in a crontab defines a task to run
+ and is known as a <firstterm>cron job</firstterm>.</para>
+
+ <para>Two different types of configuration files are used:
+ the system crontab, which should not be modified, and user
+ crontabs, which can be created and edited as needed. The format
+ used by these files is documented in &man.crontab.5;. The
+ format of the system crontab, <filename>/etc/crontab</filename>
+ includes a <literal>who</literal> column which does not exist in
+ user crontabs. In the system crontab,
+ <application>cron</application> runs the command as
+ the user specified in this column. In a user
+ crontab, all commands run as the user who
+ created the crontab.</para>
+
+ <para>User crontabs allow
+ individual users to schedule their own tasks. The <systemitem
+ class="username">root</systemitem> user
+ can also have a user <filename>crontab</filename> which can be
+ used to schedule tasks that do not exist in the system
+ <filename>crontab</filename>.</para>
- <note>
- <para>User crontabs allow individual users to schedule tasks
- without the need for
- <systemitem class="username">root</systemitem> privileges.
- Commands in a user's crontab run with the permissions of the
- user who owns the crontab.</para>
-
- <para>The <systemitem class="username">root</systemitem> user
- can have a user <filename>crontab</filename> just like any
- other user. The
- <systemitem class="username">root</systemitem> user
- <filename>crontab</filename> is separate from the system
- <filename>crontab</filename>,
- <filename>/etc/crontab</filename>. Because the system
- <filename>crontab</filename> invokes the specified commands as
- <systemitem class="username">root</systemitem>, there is
- usually no need to create a user <filename>crontab</filename>
- for <systemitem class="username">root</systemitem>.</para>
- </note>
-
- <para>Here is a sample entry from
+ <para>Here is a sample entry from the system crontab,
<filename>/etc/crontab</filename>:</para>
<programlisting># /etc/crontab - root's crontab for FreeBSD
#
# $FreeBSD$
# <co xml:id="co-comments"/>
-#
SHELL=/bin/sh
PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co xml:id="co-env"/>
#
@@ -288,7 +276,7 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin
<calloutlist>
<callout arearefs="co-comments">
- <para>Like most &os; configuration files, lines that begin
+ <para>Lines that begin
with the <literal>#</literal> character are comments. A
comment can be placed in the file as a reminder of what and
why a desired action is performed. Comments cannot be on
@@ -302,91 +290,101 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin
define any environment settings. In this example, it is
used to define the <envar>SHELL</envar> and
<envar>PATH</envar>. If the <envar>SHELL</envar> is
- omitted, &man.cron.8; will use the default of &man.sh.1;.
- If the <envar>PATH</envar> is omitted, no default will be
- used and file locations will need to be absolute.</para>
+ omitted, <application>cron</application> will use the default Bourne shell.
+ If the <envar>PATH</envar> is omitted, the full path must be given to the
+ command or script to run.</para>
</callout>
<callout arearefs="co-field-descr">
- <para>This line defines a total of seven fields:
+ <para>This line defines the seven fields used in a system crontab:
<literal>minute</literal>,
<literal>hour</literal>, <literal>mday</literal>,
<literal>month</literal>, <literal>wday</literal>,
<literal>who</literal>, and <literal>command</literal>.
- These are almost all self explanatory.
- <literal>minute</literal> is the time in minutes when the
- specified command will be run. <literal>hour</literal> is
- the hour when the specified command will be run.
- <literal>mday</literal> stands for day of the month and
- <literal>month</literal> designates the month. The
- <literal>wday</literal> option stands for day of the week.
+ The
+ <literal>minute</literal> field is the time in minutes when the
+ specified command will be run, the <literal>hour</literal> is
+ the hour when the specified command will be run, the
+ <literal>mday</literal> is the day of the month,
+ <literal>month</literal> is the month, and
+ <literal>wday</literal> is the day of the week.
These fields must be numeric values, representing the
twenty-four hour clock, or a <literal>*</literal>,
representing all values for that field. The
<literal>who</literal> field only exists in the system
- crontab. This field specifies which user the command
+ crontab and specifies which user the command
should be run as. The last field is the command to be
executed.</para>
</callout>
<callout arearefs="co-main">
- <para>This last line defines the values discussed above.
- This example has a <literal>*/5</literal> listing,followed
- by several more <literal>*</literal> characters. These
- <literal>*</literal> characters mean
- <quote>first-last</quote>, and can be interpreted as
- <emphasis>every</emphasis> time. In this example,
- &man.atrun.8; is invoked by
+ <para>This entry defines the values for this cron job.
+ The <literal>*/5</literal>, followed
+ by several more <literal>*</literal> characters, specifies that
+ <command>/usr/libexec/atrun</command> is invoked by
<systemitem class="username">root</systemitem> every five
- minutes, regardless of the day or month.</para>
+ minutes of every hour, of every day and day of the week, of
+ every month.</para>
- <para>Commands can have any number of flags passed to them;
- however, commands which extend to multiple lines need to be
+ <para>Commands can include any number of switches.
+ However, commands which extend to multiple lines need to be
broken with the backslash <quote>\</quote> continuation
character.</para>
</callout>
</calloutlist>
- <para>This is the basic setup for every &man.crontab.5;.
- However, field number six, which specifies the username, only
- exists in the system &man.crontab.5;. This field should be
- omitted for individual user &man.crontab.5; files.</para>
-
<sect2 xml:id="configtuning-installcrontab">
- <title>Installing a Crontab</title>
+ <title>Creating a User Crontab</title>
- <important>
- <para>Do not use the procedure described here to edit and
- install the system <filename>crontab</filename>,
- <filename>/etc/crontab</filename>. Instead, use an editor
- and &man.cron.8; will notice that the file has changed and
- immediately begin using the updated version. See <link
- xlink:href="&url.books.faq;/admin.html#root-not-found-cron-errors">this
- FAQ entry</link> for more information.</para>
- </important>
+ <para>To create a user crontab, invoke
+ <command>crontab</command> in editor mode:</para>
- <para>To install a freshly written user &man.crontab.5;, use
- an editor to create and save a file in the proper format.
- Then, specify the file name with &man.crontab.1;:</para>
-
- <screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen>
-
- <para>In this example, <filename>crontab-file</filename> is the
- filename of a &man.crontab.5; that was previously
- created.</para>
-
- <para>To list installed &man.crontab.5; files, pass
- <option>-l</option> to &man.crontab.1;.</para>
-
- <para>Users who wish to begin their own
- <filename>crontab</filename> file from scratch, without the
- use of a template, can use <command>crontab -e</command>.
- This will invoke the default editor with an empty file. When
- this file is saved, it will be automatically installed by
- &man.crontab.1;.</para>
+ <screen>&prompt.user; <userinput>crontab -e</userinput></screen>
- <para>In order to remove a user &man.crontab.5; completely,
- use <command>crontab -r</command>.</para>
+ <para>This will open the user's crontab using the default text
+ editor. The first time a user runs this command, it will open
+ an empty file. Once a user creates a crontab, this command
+ will open that file for editing.</para>
+
+ <para>It is useful to add these lines to the top of the crontab
+ file in order to set the environment variables and to remember
+ the meanings of the fields in the crontab:</para>
+
+ <programlisting>SHELL=/bin/sh
+PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin
+# Order of crontab fields
+# minute hour mday month wday command</programlisting>
+
+ <para>Then add a line for each command or script to run,
+ specifying the time to run the command. This example runs the
+ specified custom Bourne shell script every day at two in the
+ afternoon. Since the path to the script is not specified in
+ <literal>PATH</literal>, the full path to the script is
+ given:</para>
+
+ <programlisting>0 14 * * * /usr/home/dru/bin/mycustomscript.sh</programlisting>
+
+ <tip>
+ <para>Before using a custom script, make sure it is executable
+ and test that it works as intended from the command line.
+ This is especially important if the script includes any
+ commands that deletes files using wildcards.</para>
+ </tip>
+
+ <para>When finished editing the crontab, save the file. It
+ will automatically be installed and
+ <application>cron</application> will read the crontab and run
+ its cron jobs at their specified times. To list the cron jobs
+ in a crontab, use this command:</para>
+
+ <screen>&prompt.user; <userinput>crontab -l</userinput>
+0 14 * * * /usr/home/dru/bin/mycustomscript.sh</screen>
+
+ <para>To remove all of the cron jobs in a user crontab:</para>
+
+ <screen>&prompt.user; <userinput>crontab -l</userinput>
+remove crontab for dru? <userinput>y</userinput></screen>
+
</sect2>
</sect1>
More information about the svn-doc-all
mailing list