Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 15 Feb 2012 20:31:33 -0500
From:      Eitan Adler <lists@eitanadler.com>
To:        Glen Barber <gjb@freebsd.org>
Cc:        freebsd-doc@freebsd.org
Subject:   Re: CfR: config chapter changes
Message-ID:  <CAF6rxgkY21MMfUWRMRnvWsTGC_2QspnfWqCKrFc_QDedTQMOoQ@mail.gmail.com>
In-Reply-To: <20120215221813.GB5203@glenbarber.us>
References:  <CAF6rxgnvyoibFt7ijm6GpWoeF-eAOLu3SgvhEGCBDUAV4grybw@mail.gmail.com> <alpine.GSO.1.10.1202120028440.882@multics.mit.edu> <CAF6rxgmPyVXSFRJiOZZaJQFObhCsZMHS5_5UneVrb3t=wznMhA@mail.gmail.com> <20120215040311.GB1862@glenbarber.us> <20120215213448.GA29817@hemlock.hydra> <20120215221813.GB5203@glenbarber.us>

next in thread | previous in thread | raw e-mail | index | archive | help
Everyone,

Thanks for the input.

Here is the current version.

Index: chapter.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml,v
retrieving revision 1.251
diff -u -r1.251 chapter.sgml
--- chapter.sgml	13 Feb 2012 04:28:35 -0000	1.251
+++ chapter.sgml	16 Feb 2012 01:29:21 -0000
@@ -473,13 +473,13 @@
       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>
+      types of configuration files, the system crontab and user crontabs.
+      These formats only differ in the sixth field and later.  In the
+      system crontab, <command>cron</command> will run the command as the user
+      specified in the sixth field.  In a user crontab, all commands run as
+      the user who created the crontab, so the sixth field is the last field;
+      this is an important security feature.  The final field is always
+      the command to run.</para>

     <note>
       <para>User crontabs allow individual users to schedule tasks without the
@@ -487,10 +487,11 @@
         permissions of the user who owns the crontab.</para>

       <para>The <username>root</username> 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 is usually no need to create a user crontab
-        for <username>root</username>.</para>
+	any other user.  The <username>root</username> user crontab is
+	distinct from <filename>/etc/crontab</filename> (the system crontab).
+	Because the system system crontab effectively invokes the
+	specified commands as root there is usually no need to
+	create a user crontab for <username>root</username>.</para>
     </note>

     <para>Let us take a look at the <filename>/etc/crontab</filename> file
@@ -547,11 +548,8 @@
 	  day of the week.  All these fields must be numeric values, and follow
 	  the twenty-four hour clock.  The <literal>who</literal> field is special,
 	  and only exists in the <filename>/etc/crontab</filename> file.
-	  This field specifies which user the command should be run as.
-	  When a user installs his or her <filename>crontab</filename> file, they
-	  will not have this option. Finally, the <literal>command</literal>
option is listed.
-	  This is the last field, so naturally it should designate the command
-	  to be executed.</para>
+	  This field specifies which user the command should be run
+	  as.  The last field is the command to be executed.</para>
       </callout>

       <callout arearefs="co-main">
@@ -584,8 +582,9 @@
       <title>Installing a Crontab</title>

       <important>
-      <para>You must not use the procedure described here to
-        edit/install the system crontab. Simply use your favorite
+      <para>Do not use the procedure described here to
+	edit and install the system crontab,
+	<filename>/etc/crontab</filename>.  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
@@ -596,7 +595,7 @@
       <para>To install a freshly written user
 	<filename>crontab</filename>, first use your favorite editor to create
 	a file in the proper format, and then use the
-	<command>crontab</command> utility.  The most common usage
+	<command>crontab</command>man.crontab.8; utility.  The most common usage
 	is:</para>

       <screen>&prompt.user; <userinput>crontab
crontab-file</userinput></screen>
@@ -606,18 +605,17 @@

       <para>There is also an option to list installed
 	<filename>crontab</filename> files: just pass the
-	<option>-l</option> option to <command>crontab</command> and look
+	<option>-l</option> option to
<command>crontab</command>man.crontab.8; and look
 	over the output.</para>

       <para>For users who wish to begin their own crontab file from scratch,
 	without the use of a template, the <command>crontab -e</command>
 	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>
+	automatically installed by the
<command>crontab</command>man.crontab.8; command.</para>

       <para>If you later want to remove your user <filename>crontab</filename>
-	completely, use <command>crontab</command> with the <option>-r</option>
+	completely, use <command>crontab</command>man.crontab.8; with the
<option>-r</option>
 	option.
       </para>

@@ -636,7 +634,7 @@
       </authorgroup>
     </sect1info>

-    <title>Using rc under &os;</title>
+    <title>Using <literal>rc</literal> Under &os;</title>

     <para>In 2002 &os; integrated the NetBSD
       <filename>rc.d</filename> system for system initialization.
@@ -1674,7 +1672,7 @@
   </sect1>

   <sect1 id="configtuning-sysctl">
-    <title>Tuning with sysctl</title>
+    <title>Tuning with <command>sysctl</command></title>

     <indexterm><primary>sysctl</primary></indexterm>
     <indexterm>
@@ -1944,7 +1942,7 @@
 	out of space and the update to fail.</para>

       <sect3>
-	<title>More Details about Soft Updates</title>
+	<title>More Details About Soft Updates</title>

 	<indexterm>
 	  <primary>Soft Updates</primary>
@@ -2390,15 +2388,36 @@
       <xref linkend="swap-encrypting"> of the Handbook.</para>

     <sect2 id="new-drive-swap">
-      <title>Swap on a New Hard Drive</title>
+      <title>Swap on a New or Existing Hard Drive</title>

-      <para>The best way to add swap, of course, is to use this as an
-	excuse to add another hard drive.  You can always use another
-	hard drive, after all.  If you can do this, go reread the
-	discussion of swap space
-	in <xref linkend="configtuning-initial">
-	of the Handbook for some suggestions on how to best
-	arrange your swap.</para>
+      <para>Adding a new hard drive for swap gives better performance
+	than adding a partition on an existing drive.  Setting up
+	partitions and hard drives is explained in
+	<xref linkend="disks-adding">.  <xref linkend="configtuning-initial">
+	discusses partition layouts and swap partition size considerations.</para>
+
+      <para>Use &man.swapon.8; to add a swap partition to the system.
 For example:</para>
+
+      <screen>&prompt.root;
<userinput>swapon<replaceable>/dev/ada1s1p2</replaceable></userinput></screen>
+
+      <warning>
+	<para>It is possible to use any partition not currently mounted, even
+	  if it already contains data.  Using &man.swapon.8; on a partition that
+	  contains data will overwrite and destroy that data.
+	  Make sure that the partition to be added as swap
+	  is really the intended partition before running
+	  <command>swapon</command>.</para>
+      </warning>
+
+      <para>To automatically add this swap partition on boot,
+	add an entry to <filename>/etc/fstab</filename> for the
+	partition:</para>
+
+      <programlisting><replaceable>/dev/ada1s1p1</replaceable>	none	swap	sw	0	0</programlisting>
+
+      <para>&man.fstab.5; explains the meaning of the entries and
+	their format in
+        <filename>/etc/fstab</filename>.</para>
     </sect2>

     <sect2 id="nfs-swap">
@@ -2878,7 +2897,7 @@
 	  on Linux, it is likely a &os; driver problem and narrowing down
 	  which driver causes the problems will help us fix the problem.
 	  Note that the <acronym>ACPI</acronym> maintainers do not
-	  usually maintain other drivers (e.g sound,
+	  usually maintain other drivers (e.g., sound,
 	  <acronym>ATA</acronym>, etc.) so any work done on tracking
 	  down a driver problem should probably eventually be posted
 	  to the &a.current.name; list and mailed to the driver
@@ -2898,7 +2917,7 @@
       </sect3>

       <sect3>
-	<title>System Hangs (temporary or permanent)</title>
+	<title>System Hangs (Temporary or Permanent)</title>

 	<para>Most system hangs are a result of lost interrupts or an
 	  interrupt storm.  Chipsets have a lot of problems based on how
@@ -3058,7 +3077,7 @@
 	how to fix them:</para>

       <sect3>
-	<title>_OS dependencies</title>
+	<title>_OS Dependencies</title>

 	<para>Some <acronym>AML</acronym> assumes the world consists of
 	  various &windows; versions.  You can tell &os; to claim it is
@@ -3070,7 +3089,7 @@
       </sect3>

       <sect3>
-	<title>Missing Return statements</title>
+	<title>Missing Return Statements</title>

 	<para>Some methods do not explicitly return a value as the
 	  standard requires.  While <acronym>ACPI-CA</acronym>
@@ -3112,8 +3131,7 @@
     </sect2>

     <sect2 id="ACPI-debugoutput">
-      <title>Getting Debugging Output From
-	<acronym>ACPI</acronym></title>
+      <title>Getting Debugging Output from <acronym>ACPI</acronym></title>

       <indexterm>
 	<primary>ACPI</primary>



Eitan Adler



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAF6rxgkY21MMfUWRMRnvWsTGC_2QspnfWqCKrFc_QDedTQMOoQ>