Date: Mon, 5 May 2014 15:48:08 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44761 - head/en_US.ISO8859-1/books/handbook/config Message-ID: <201405051548.s45Fm8P4061050@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201405051548.s45Fm8P4061050>