From nobody@FreeBSD.org  Thu May 20 14:50:38 2004
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id AEF6316A4CE
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 20 May 2004 14:50:38 -0700 (PDT)
Received: from www.freebsd.org (www.freebsd.org [216.136.204.117])
	by mx1.FreeBSD.org (Postfix) with ESMTP id A885943D3F
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 20 May 2004 14:50:38 -0700 (PDT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.12.11/8.12.11) with ESMTP id i4KLocBE089598
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 20 May 2004 14:50:38 -0700 (PDT)
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.12.11/8.12.11/Submit) id i4KLocKR089597;
	Thu, 20 May 2004 14:50:38 -0700 (PDT)
	(envelope-from nobody)
Message-Id: <200405202150.i4KLocKR089597@www.freebsd.org>
Date: Thu, 20 May 2004 14:50:38 -0700 (PDT)
From: platanthera <platanthera@web.de>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [patch] handbook - a note on /etc/crontab
X-Send-Pr-Version: www-2.3

>Number:         66963
>Category:       docs
>Synopsis:       [patch] handbook - a note on /etc/crontab
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    dannyboy
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Thu May 20 15:00:37 PDT 2004
>Closed-Date:    Sat May 22 07:54:54 PDT 2004
>Last-Modified:  Sat May 22 07:54:54 PDT 2004
>Originator:     platanthera
>Release:        5.2.1 i386
>Organization:
>Environment:
>Description:
      6.6.1 Installing a Crontab
To install your freshly written crontab, just use the crontab utility. The most common usage is:
# crontab crontab

Apparently quite a number of users try to apply this approach to /etc/crontab. Therefore it should be explicitly warned not to do this. (I know that it's already in the FAQ)
>How-To-Repeat:
      read freebsd-users@ for some days
>Fix:
      patch for doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml

--- chapter.sgml.old    Tue May  4 22:51:58 2004
+++ chapter.sgml        Thu May 20 23:16:56 2004

@@ -549,6 +549,17 @@
        with an empty file.  When the file is saved, it will be
        automatically installed by the <command>crontab</command> command.
       </para>
+
+
+      <note>
+        <para>Changes in <filename>/etc/crontab</filename> are picked up by
+       <citerefentry><refentrytitle>cron</refentrytitle><manvolnum>8</manvolnum>
+       </citerefentry> automatically. Do NOT try to use <citerefentry>
+       <refentrytitle>crontab</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+       to update the system crontab, in the
+       <ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/faq/admin.html#ROOT-NOT-FOUND-CRON-ERRORS">
+       FAQ</ulink> there's an explanation why this doesn't work.</para>
+      </note>

     </sect2>
   </sect1>
>Release-Note:
>Audit-Trail:

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

 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>

From: platanthera <platanthera@web.de>
To: freebsd-gnats-submit@FreeBSD.org, platanthera@web.de
Cc:  
Subject: Re: docs/66963: [patch] handbook - a note on /etc/crontab
Date: Fri, 21 May 2004 19:50:59 +0200

 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.

From: Bill Moran <wmoran@potentialtech.com>
To: freebsd-gnats-submit@FreeBSD.org, platanthera@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>
 
Responsible-Changed-From-To: freebsd-doc->dannyboy 
Responsible-Changed-By: dannyboy 
Responsible-Changed-When: Fri May 21 22:38:58 PDT 2004 
Responsible-Changed-Why:  
I'll get this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=66963 
State-Changed-From-To: open->closed 
State-Changed-By: dannyboy 
State-Changed-When: Sat May 22 07:54:34 PDT 2004 
State-Changed-Why:  
Committed, thanks. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=66963 
>Unformatted:
