Bug 66963

Here is an updated patch that adds some additional explanation/notes:

Rendered version availabe here: http://www.potentialtech.com/wmoran/configtuning-cron.html

-- 
Bill Moran
Potential Technologies
http://www.potentialtech.com

--- chapter-old.sgml	Tue May  4 16:51:58 2004
+++ chapter.sgml	Fri May 21 11:33:11 2004
@@ -441,8 +441,30 @@
        <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>The reason user crontabs exist is to 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 is a different crontab from
+        <filename>/etc/crontab</filename> (the system crontab). Because of the
+        system crontab, there's generally no reason 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 +548,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 +584,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>

just a note on the wording.. I'd suggest to replace

Note: The reason user crontabs exist is to 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.
The root user can have a user crontab just like any other user. This is 
a different crontab from /etc/crontab (the system crontab). Because of 
the system crontab, there's generally no reason to create a user 
crontab for root.

by 

Note: 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.
The root user can have a user crontab just like any other user. This one 
is different from /etc/crontab (the system crontab). Because of the 
system crontab, there's usually no need to create a user crontab for 
root.

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>

Comment 4 dannyboy 2004-05-22 06:38:58 UTC

Responsible Changed
From-To: freebsd-doc->dannyboy

I'll get this.

Comment 5 dannyboy 2004-05-22 15:54:34 UTC

State Changed
From-To: open->closed

Committed, thanks.