docs/66963: [patch] handbook - a note on /etc/crontab

[Bill Moran]

The following reply was made to PR docs/66963; it has been noted by GNATS.

From: Bill Moran <wmoran at potentialtech.com>
To: freebsd-gnats-submit at FreeBSD.org, platanthera at web.de
Cc:  
Subject: Re: docs/66963: [patch] handbook - a note on /etc/crontab
Date: Fri, 21 May 2004 14:47:14 -0400

 I like that wording better as well.  Attached is a new diff, and I've updated
 the rendered version (at the above URL).
 
 --- chapter-old.sgml	Tue May  4 16:51:58 2004
 +++ chapter.sgml	Fri May 21 14:27:03 2004
 @@ -441,8 +441,29 @@
         <filename>crontab</filename> files store information about specific
         functions which <command>cron</command> is supposed to perform at
         certain times.</para>
 +
 +    <para>The <command>cron</command> utility uses two different
 +      types of configuration files, the system crontab and user crontabs. The
 +      only difference between these two formats is the sixth field.  In the
 +      system crontab, the sixth field is the name of a user for the command
 +      to run as. This gives the system crontab the ability to run commands
 +      as any user. In a user crontab, the sixth field is the command to run,
 +      and all commands run as the user who created the crontab; this is an
 +      important security feature.</para>
 +
 +    <note>
 +      <para>User crontabs allow individual users to schedule tasks without the
 +        need for root priviledges. Commands in a user's crontab run with the
 +        permissions of the user who owns the crontab.</para>
 +      <para>The root user can have a user crontab just like
 +        any other user. This one is different from
 +        <filename>/etc/crontab</filename> (the system crontab). Because of the
 +        system crontab, there's usually no need to create a user crontab
 +        for root.</para>
 +    </note>
 
 -    <para>Let us take a look at the <filename>/etc/crontab</filename> file:</para>
 +    <para>Let us take a look at the <filename>/etc/crontab</filename> file
 +      (the system crontab):</para>
 
 
       <programlisting># /etc/crontab - root's crontab for &os;
 @@ -526,21 +547,35 @@
         <filename>/etc/crontab</filename> file.  This field should be
         omitted for individual user <filename>crontab</filename>
         files.</para>
 -
 +
 
       <sect2 id="configtuning-installcrontab">
         <title>Installing a Crontab</title>
 -
 -      <para>To install your freshly written
 -	<filename>crontab</filename>, just use the
 +
 +      <important>
 +      <para>You must not use the procedure described here to
 +        edit/install the system crontab. Simply use your favorite
 +        editor, the <command>cron</command> utility will notice that the file
 +        has changed and immediately begin using the updated version.
 +        See
 +        <ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/faq/admin.html#ROOT-NOT-FOUND-CRON-ERRORS">
 +        this FAQ entry </ulink> for more information.</para>
 +      </important>
 +
 +      <para>To install a freshly written user
 +	<filename>crontab</filename>, first use your favorite editor to create
 +    a file in the proper format, then use the
   	<command>crontab</command> utility.  The most common usage
   	is:</para>
 
 -      <screen>&prompt.root; <userinput>crontab crontab</userinput></screen>
 +      <screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen>
 +
 +      <para>In this example, <filename>crontab-file</filename> is the filename
 +    of a <filename>crontab</filename> that was previously created.</para>
 
         <para>There is also an option to list installed
   	<filename>crontab</filename> files, just pass the
 -	<option>-l</option> to <command>crontab</command> and look
 +	<option>-l</option> option to <command>crontab</command> and look
   	over the output.</para>
 
         <para>For users who wish to begin their own crontab file from scratch,
 @@ -548,6 +583,11 @@
   	option is available.  This will invoke the selected editor
   	with an empty file.  When the file is saved, it will be
   	automatically installed by the <command>crontab</command> command.
 +      </para>
 +
 +      <para>If you later want to remove your user <filename>crontab</filename>
 +    completely, use <command>crontab</command> with the <option>-r</option>
 +    option.
         </para>
 
       </sect2>