Finish editorial review of FreeBSD Update chapter.

Sponsored by:	iXsystems

en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml

@@ -334,13 +334,15 @@ Uninstalling updates... done.</screen>
 	system.</para>
 
       <note>
-	<para>It is a good idea to always keep a copy of the
+	<para>Always keep a copy of the
 	  <filename>GENERIC</filename> kernel in
 	  <filename>/boot/GENERIC</filename>.  It
 	  will be helpful in diagnosing a variety of problems and in
-	  performing version upgrades using
+	  performing version upgrades.  Refer to either <xref
-	  <command>freebsd-update</command> as described in
+	    linkend="freebsd-update-custom-kernel-9x"/> or <xref
-	  <xref linkend="freebsdupdate-upgrade"/>.</para>
+	    linkend="freebsd-update-custom-kernel-8x"/> for
+	  instructions on how to get a copy of the
+	  <filename>GENERIC</filename> kernel.</para>
       </note>
 
       <para>Unless the default configuration in
@@ -377,7 +379,20 @@ Uninstalling updates... done.</screen>
 	&os; is upgraded from one major version to another, like from
 	&os;&nbsp;9.X to &os;&nbsp;10.X.  Both types of upgrades can
 	be performed by providing <command>freebsd-update</command>
-	with a release version target.  The following command, when
+	with a release version target.</para>
+
+      <note>
+	<para>If the system is running a custom kernel, make sure that
+	  a copy of the <filename>GENERIC</filename> kernel exists in
+	  <filename>/boot/GENERIC</filename> before starting the
+	  upgrade.  Refer to either <xref
+	    linkend="freebsd-update-custom-kernel-9x"/> or <xref
+	    linkend="freebsd-update-custom-kernel-8x"/> for
+	  instructions on how to get a copy of the
+	  <filename>GENERIC</filename> kernel.</para>
+      </note>
+
+	<para>The following command, when
 	run on a &os;&nbsp;9.0 system, will upgrade it to
 	&os;&nbsp;9.1:</para>
 
@@ -450,8 +465,8 @@ before running "/usr/sbin/freebsd-update install"</screen>
 
 	</note>
 
-	<para>The kernel and kernel modules will be patched first.  At
+	<para>The kernel and kernel modules will be patched first.  If
-	  this point, the machine must be rebooted.  If the system is
+	  the system is
 	  running with a custom kernel, use &man.nextboot.8; to set
 	  the kernel for the next boot to the updated
 	  <filename>/boot/GENERIC</filename>:</para>
@@ -480,9 +495,10 @@ before running "/usr/sbin/freebsd-update install"</screen>
 
 	<para>Once the system has come back online, restart
 	  <command>freebsd-update</command> using the following
-	  command.  The state of the process has been saved and thus,
+	  command.  Since the state of the process has been saved,
 	  <command>freebsd-update</command> will not start from the
-	  beginning, but will remove all old shared libraries and
+	  beginning, but will instead move on to the next phase and
+	  remove all old shared libraries and
 	  object files.</para>
 
 	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
@@ -495,37 +511,34 @@ before running "/usr/sbin/freebsd-update install"</screen>
 
 	<para>The upgrade is now complete.  If this was a major
 	  version upgrade, reinstall all ports and packages as
-	  described in <xref linkend="freebsdupdate-portsrebuild"/>.
+	  described in <xref linkend="freebsdupdate-portsrebuild"/>.</para>
-	  If the system uses a custom kernel, refer to either <xref
-	    linkend="freebsd-update-custom-kernel-9x"/> or <xref
-	    linkend="freebsd-update-custom-kernel-8x"/> for
-	  instructions on how to upgrade the custom kernel.</para>
 
 	<sect3 xml:id="freebsd-update-custom-kernel-9x">
 	  <title>Custom Kernels with &os;&nbsp;9.X and Later</title>
 
-	  <itemizedlist>
+	  <para>Before using <command>freebsd-update</command>, ensure
-	    <listitem>
+	    that a copy of the <filename>GENERIC</filename> kernel
-	      <para>If a custom kernel has only been built once, the
+	    exists in <filename>/boot/GENERIC</filename>.  If a custom
+	    kernel has only been built once, the
 		kernel in <filename>/boot/kernel.old</filename> is
-		actually the <literal>GENERIC</literal> kernel.
+		the <literal>GENERIC</literal> kernel.
-		Rename this directory to
+		Simply rename this directory to
 		<filename>/boot/kernel</filename>.</para>
-	    </listitem>
 
-	    <listitem>
+	      <para>If a custom kernel has been built more than once
-	      <para>If physical access to the machine is available, a
+		or if it is unknown how many times the custom kernel
+		has been built, obtain a copy of the
+		<literal>GENERIC</literal> kernel that matches the
+		current version of the operating system.  If physical
+		access to the system is available, a
 		copy of the <literal>GENERIC</literal> kernel can be
-		installed from the installation media using these
+		installed from the installation media:</para>
-		commands:</para>
 
 	      <screen>&prompt.root; <userinput>mount /cdrom</userinput>
 &prompt.root; <userinput>cd /cdrom/usr/freebsd-dist</userinput>
 &prompt.root; <userinput>tar -C/ -xvf kernel.txz boot/kernel/kernel</userinput></screen>
-	    </listitem>
 
-	    <listitem>
+	      <para>Alternately, the
-	      <para>If the options above cannot be used, the
 		<literal>GENERIC</literal> kernel may be rebuilt and
 		installed from source:</para>
 
@@ -539,33 +552,19 @@ before running "/usr/sbin/freebsd-update install"</screen>
 		not have been modified in any way.  It is also
 		suggested that the kernel is built without any other
 		special options.</para>
-	    </listitem>
-	  </itemizedlist>
 
-	  <para>Rebooting to the <filename>GENERIC</filename> kernel
+	  <para>Rebooting into the <filename>GENERIC</filename> kernel
-	    is not required at this stage.</para>
+	    is not required as <command>freebsd-update</command> only
+	    needs <filename>/boot/GENERIC</filename> to exist.</para>
       </sect3>
 
 	<sect3 xml:id="freebsd-update-custom-kernel-8x">
 	  <title>Custom Kernels with &os;&nbsp;8.X</title>
 
-	  <para>A copy of the <filename>GENERIC</filename> kernel is
+	  <para>On an &os;&nbsp;8.X system, the instructions for
-	    needed, and should be placed in
+	    obtaining or building a
-	    <filename>/boot/GENERIC</filename>.  If the
+	    <filename>GENERIC</filename> kernel differ slightly.</para>
-	    <filename>GENERIC</filename> kernel is not present in the
-	    system, it may be obtained using one of the following
-	    methods:</para>
 
-	  <itemizedlist>
-	    <listitem>
-	      <para>If a custom kernel has only been built once, the
-		kernel in <filename>/boot/kernel.old</filename> is
-		actually <filename>GENERIC</filename>.  Rename this
-		directory to
-		<filename>/boot/GENERIC</filename>.</para>
-	    </listitem>
-
-	    <listitem>
 	      <para>Assuming physical access to the machine is
 		possible, a copy of the <filename>GENERIC</filename>
 		kernel can be installed from the installation media
@@ -577,16 +576,13 @@ before running "/usr/sbin/freebsd-update install"</screen>
 
 	      <para>Replace <filename
 		  class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
-		with the actual version of the release being used.
+		with the version of the release being used.
 		The <filename>GENERIC</filename> kernel will be
 		installed in <filename>/boot/GENERIC</filename> by
 		default.</para>
-	    </listitem>
 
-	    <listitem>
+	      <para>To instead build the
-	      <para>Failing all the above, the
+		<filename>GENERIC</filename> kernel from source:</para>
-		<filename>GENERIC</filename> kernel may be rebuilt and
-		installed from source:</para>
 
 	      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput>
@@ -600,11 +596,9 @@ before running "/usr/sbin/freebsd-update install"</screen>
 		not have been modified in any way.  It is also
 		suggested that it is built without any other special
 		options.</para>
-	    </listitem>
-	  </itemizedlist>
 
-	  <para>Rebooting to the <filename>GENERIC</filename> kernel
+	  <para>Rebooting into the <filename>GENERIC</filename> kernel
-	    is not required at this stage.</para>
+	    is not required.</para>
 	</sect3>
 
       <sect3 xml:id="freebsdupdate-portsrebuild">
@@ -629,7 +623,7 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	screens.  To prevent this behavior, and use only the default
 	options, include <option>-G</option> in the above command.</para>
 
-	<para>Once this has completed, finish the upgrade process with
+	<para>Once the software upgrades are complete, finish the upgrade process with
 	  a final call to <command>freebsd-update</command> in order
 	  to tie up all the loose ends in the upgrade process:</para>
 
@@ -637,43 +631,49 @@ before running "/usr/sbin/freebsd-update install"</screen>
 
 	<para>If the <filename>GENERIC</filename> kernel was
 	  temporarily used, this is the time to build and install a
-	  new custom kernel in the usual way.</para>
+	  new custom kernel using the instructions in <xref
+	    linkend="kernelconfig"/>.</para>
 
-	<para>Reboot the machine into the new &os; version.  The
+	<para>Reboot the machine into the new &os; version.  The upgrade
-	  process is complete.</para>
+	  process is now complete.</para>
       </sect3>
     </sect2>
 
     <sect2 xml:id="freebsdupdate-system-comparison">
       <title>System State Comparison</title>
 
-      <para><command>freebsd-update</command> can be used to test the
+      <para>The state of the installed &os; version against a known
-	state of the installed &os; version against a known good copy.
+	good copy can be tested using <command>freebsd-update IDS</command>.
-	This option evaluates the current version of system utilities,
+	This command evaluates the current version of system utilities,
-	libraries, and configuration files.  To begin the comparison,
+	libraries, and configuration files and can be used as a
-	issue the following command:</para>
+	built-in Intrusion Detection System (<acronym>IDS</acronym>).</para>
-
-      <screen>&prompt.root; <userinput>freebsd-update IDS &gt;&gt; outfile.ids</userinput></screen>
 
       <warning>
-	<para>While the command name is <acronym>IDS</acronym> it is
+	<para>This command is
-	  not a replacement for a real intrusion detection system such
+	  not a replacement for a real <acronym>IDS</acronym> such
 	  as <package>security/snort</package>.  As
 	  <command>freebsd-update</command> stores data on disk, the
 	  possibility of tampering is evident.  While this possibility
 	  may be reduced using <varname>kern.securelevel</varname> and
 	  by storing the <command>freebsd-update</command> data on a
-	  read only file system when not in use, a better solution
+	  read-only file system when not in use, a better solution
 	  would be to compare the system against a secure disk, such
 	  as a <acronym>DVD</acronym> or securely stored external
-	  <acronym>USB</acronym> disk device.</para>
+	  <acronym>USB</acronym> disk device.  An alternative method
+	  for providing <acronym>IDS</acronym> functionality using a
+	  built-in utility is described in <xref
+	    linkend="security-ids"/></para>
       </warning>
 
-      <para>The system will now be inspected, and a lengthy listing of
+      <para>To begin the comparison,
-	files, along with the &man.sha256.1; hash values for both the
+	specify the output file to save the results to:</para>
+
+      <screen>&prompt.root; <userinput>freebsd-update IDS &gt;&gt; outfile.ids</userinput></screen>
+
+      <para>The system will now be inspected and a lengthy listing of
+	files, along with the <acronym>SHA256</acronym> hash values for both the
 	known value in the release and the current installation, will
-	be sent to the specified
+	be sent to the specified output file.</para>
-	<filename>outfile.ids</filename> file.</para>
 
       <para>The entries in the listing are extremely long, but the
 	output format may be easily parsed.  For instance, to obtain a
@@ -688,16 +688,13 @@ before running "/usr/sbin/freebsd-update install"</screen>
 
       <para>This sample output has been truncated as many more files
 	exist.  Some files have natural modifications.  For example,
-	<filename>/etc/passwd</filename> has been modified because
+	<filename>/etc/passwd</filename> will be modified if
-	users have been added to the system.  Other files, such as
+	users have been added to the system.
-	kernel modules, may differ as
+	Kernel modules may differ as
 	<command>freebsd-update</command> may have updated them.
 	To exclude specific files or directories, add them to the
 	<literal>IDSIgnorePaths</literal> option in
 	<filename>/etc/freebsd-update.conf</filename>.</para>
-
-      <para>This system may be used as part of an elaborate upgrade
-	method, aside from the previously discussed version.</para>
     </sect2>
   </sect1>