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>