More incorporation of redundant information. Definitely very much a WIP.

Sponsored by: iXsystems

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

@@ -1543,6 +1543,18 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	  run in the order specified here.  This section summarizes
 	  the function of each command.</para>
 
+	<step>
+	  <para>If the build world process has previously been run on
+	    this system, a copy of the previous build may still exist
+	    in <filename class="directory">/usr/obj</filename>.  To speed up the new build world
+	process, and possibly save some dependency headaches,
+	remove this directory if it already exists:</para>
+
+	  <screen>&prompt.root; <userinput>cd /usr/obj</userinput>
+&prompt.root; <userinput>chflags -R noschg *</userinput>
+&prompt.root; <userinput>rm -rf *</userinput></screen>
+	</step>
+
 	<step>
 	  <para>Compile the new compiler and a few related
 	    tools, then use the new compiler to compile the rest of
@@ -1577,11 +1589,12 @@ before running "/usr/sbin/freebsd-update install"</screen>
 
 	  <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
 
-	  <para>Once in single-user mode, run this command if the
+	  <para>Once in single-user mode, run these commands if the
 	    system is formatted with UFS:</para>
 
 	  <screen>&prompt.root; <userinput>mount -u /</userinput>
-&prompt.root; <userinput>mount -a -t ufs</userinput></screen>
+&prompt.root; <userinput>mount -a -t ufs</userinput>
+&prompt.root; <userinput>swapon -a</userinput></screen>
 
 	  <para>If the system is instead formatted with ZFS, run these
 	    two commands.  This example assumes a zpool name of
@@ -1592,18 +1605,22 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	</step>
 
 	<step>
-	  <para>Then, for either filesystem, run:</para>
+	  <para>Then, for either file system, if the <acronym>CMOS</acronym> clock is set to local time
+	  (this is true if the output of &man.date.1; does not show
+	  the correct time and zone), run:</para>
 
 	  <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
 	</step>
 
 	<step>
-	  <para>Next, perform some initial configuration file updates
+	  <para>Next, perform some initial configuration file updates to <filename class="directory">/etc</filename>
-	    in preparation for the new world.  For instance, this step
+	    in preparation for the new world.  The following command compares
-	    may add new groups or new system accounts which have been
+	only those files that are essential for the success of
+	<buildtarget>installworld</buildtarget>.  For instance, this step
+	    may add new groups, system accounts, or startup scripts which have been
 	    added to &os; since the last update.  This is necessary so
 	    that the <buildtarget>installworld</buildtarget> step will
-	    be able to use the new system accounts and groups.</para>
+	    be able to use any new system accounts, groups, and scripts.</para>
 
 	  <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
 	</step>
@@ -1646,42 +1663,51 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	  <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
 	</step>
       </procedure>
+      
+     <indexterm><primary>single-user mode</primary></indexterm>
+
+      <para>If the system can have a window of down-time, consider compiling the system in single user mode instead
+	of compiling the system in multi-user
+	mode, and then dropping into single user mode for the
+	installation.
+	Reinstalling the system touches a lot of important system
+	files, all the standard system binaries, libraries, and
+	include files.  Changing these on a running system,
+	particularly one with active users, is asking for
+	trouble.</para>
     </sect2>
 
     <sect2 xml:id="src-updating">
-      <title>Check <filename>/etc/make.conf</filename></title>
+      <title>Configuration Files</title>
 
       <indexterm>
 	<primary><filename>make.conf</filename></primary>
       </indexterm>
 
-      <para>The following sections clearly describe each step,
+      <para>This section describes the configuration files used by the
-	  especially when using a custom kernel configuration.</para>
+	build world process.</para>
-      <para>Available &man.make.1; options are shown in
+
-	&man.make.conf.5; and
+      <para>The options available to &man.make.1; are described in
-	<filename>/usr/share/examples/etc/make.conf</filename>.  These
+	&man.make.conf.5; and some common examples are included in
-	settings can be added to <filename>/etc/make.conf</filename>
+	<filename>/usr/share/examples/etc/make.conf</filename>.
-	to control the way &man.make.1; runs and how it builds
+	Any options which are added to <filename>/etc/make.conf</filename>
-	programs.  Changes to some settings can have far-reaching and
+	will control the way &man.make.1; runs and how it builds
+	programs.  Such options take
+	effect every time &man.make.1; is used, including compiling
+	applications from the Ports Collection, compiling custom C
+	programs, or building the &os; operating system.</para>
+	
+      <para>Changes to some settings can have far-reaching and
 	potentially surprising effects.  Read the comments in both
 	locations and keep in mind that the defaults have been chosen
 	for a combination of performance and safety.</para>
 
-      <para>Options set in <filename>/etc/make.conf</filename> take
-	effect every time &man.make.1; is used, including compiling
-	applications from the Ports Collection or user-written C
-	programs, or building the &os; operating system.</para>
-    </sect2>
-
-    <sect2 xml:id="src-conf">
-      <title>Check <filename>/etc/src.conf</filename></title>
-
       <indexterm>
 	<primary><filename>src.conf</filename></primary>
       </indexterm>
 
-      <para><filename>/etc/src.conf</filename> controls the building
+      <para>How
-	of the operating system from source code.  Unlike
+	the operating system is built from source code is controlled by <filename>/etc/src.conf</filename>.  Unlike
 	<filename>/etc/make.conf</filename>, the contents of
 	<filename>/etc/src.conf</filename> only take effect when the
 	&os; operating system itself is being built.  Descriptions of
@@ -1689,116 +1715,7 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	&man.src.conf.5;.  Be cautious about disabling seemingly
 	unneeded kernel modules and build options.  Sometimes there
 	are unexpected or subtle interactions.</para>
-    </sect2>
+      </sect2>
-
-    <sect2 xml:id="updating-etc">
-      <title>Update the Files in <filename>/etc</filename></title>
-
-      <para><filename>/etc</filename> contains a
-	large part of the system's configuration information, as well
-	as scripts that are run at system startup.  Some of these
-	scripts change between &os; versions.</para>
-
-      <para>Some of the configuration files are used in the day to
-	day running of the system, such as
-	<filename>/etc/group</filename>.</para>
-
-      <para>There have been occasions when the installation part of
-	<command>make installworld</command> expected certain
-	usernames or groups to exist.  When performing an upgrade, it
-	is likely that these users or groups do not yet exist.  In
-	some cases <command>make buildworld</command> will check to
-	see if these users or groups exist.</para>
-
-      <para>The solution is to run &man.mergemaster.8; in
-	pre-buildworld mode with <option>-p</option>.  This compares
-	only those files that are essential for the success of
-	<buildtarget>buildworld</buildtarget> or
-	<buildtarget>installworld</buildtarget>.</para>
-
-      <tip>
-	<para>To check which files are owned by the group being
-	  renamed or deleted:</para>
-
-	<screen>&prompt.root; <userinput>find / -group GID -print</userinput></screen>
-
-	<para>This command will show all files owned by group
-	  <replaceable>GID</replaceable>, which can be either a group
-	  name or a numeric group ID.</para>
-      </tip>
-    </sect2>
-
-    <sect2 xml:id="makeworld-singleuser">
-      <title>Drop to Single User Mode</title>
-
-      <indexterm><primary>single-user mode</primary></indexterm>
-
-      <para>Consider compiling the system in single user mode.
-	Reinstalling the system touches a lot of important system
-	files, all the standard system binaries, libraries, and
-	include files.  Changing these on a running system,
-	particularly one with active users, is asking for
-	trouble.</para>
-
-      <indexterm><primary>multi-user mode</primary></indexterm>
-      <para>Another method is to compile the system in multi-user
-	mode, and then drop into single user mode for the
-	installation.  With this method, hold off on the following
-	steps until the build has completed.  Drop to single user mode
-	in order to run <buildtarget>installkernel</buildtarget> or
-	<buildtarget>installworld</buildtarget>.</para>
-
-      <para>To enter single user mode from a running system:</para>
-
-      <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
-
-      <para>Alternatively, reboot the system, and at the boot prompt,
-	select the <quote>single user</quote> option.  Once at the
-	single user mode shell prompt, run:</para>
-
-      <screen>&prompt.root; <userinput>fsck -p</userinput>
-&prompt.root; <userinput>mount -u /</userinput>
-&prompt.root; <userinput>mount -a -t ufs</userinput>
-&prompt.root; <userinput>swapon -a</userinput></screen>
-
-      <para>This checks the file systems, remounts
-	<filename>/</filename> read/write, mounts all the other UFS
-	file systems referenced in <filename>/etc/fstab</filename>,
-	and turns swapping on.</para>
-
-      <note>
-	<para>If the CMOS clock is set to local time and not to GMT
-	  (this is true if the output of &man.date.1; does not show
-	  the correct time and zone), run the following
-	  command:</para>
-
-	<screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
-
-	<para>This ensures that the local time-zone settings get set
-	  up correctly.</para>
-      </note>
-    </sect2>
-
-    <sect2 xml:id="cleaning-usr-obj">
-      <title>Remove <filename>/usr/obj</filename></title>
-
-      <para>As parts of the system are rebuilt, they are, by default,
-	placed in subdirectories of <filename>/usr/obj</filename>.
-	The directories shadow those under
-	<filename>/usr/src</filename>.</para>
-
-      <para>To speed up the <command>make buildworld</command>
-	process, and possibly save some dependency headaches,
-	remove this directory if it already exists.</para>
-
-      <para>Some files below <filename>/usr/obj</filename> may have
-	the immutable flag set which must be removed first using
-	&man.chflags.1;.</para>
-
-      <screen>&prompt.root; <userinput>cd /usr/obj</userinput>
-&prompt.root; <userinput>chflags -R noschg *</userinput>
-&prompt.root; <userinput>rm -rf *</userinput></screen>
-    </sect2>
 
     <sect2 xml:id="make-buildworld">
       <title>Recompile the Base System</title>
@@ -2005,16 +1922,9 @@ Script done, &hellip;</screen>
 	problems.  See &man.init.8; for details about
 	<varname>kern.securelevel</varname> and &man.chflags.1; for
 	details about the various file flags.</para>
-    </sect2>
-
-    <sect2 xml:id="new-kernel-singleuser">
-      <title>Reboot into Single User Mode</title>
-
-      <indexterm><primary>single-user mode</primary></indexterm>
 
       <para>Reboot into single user mode to test that the new kernel
-	works using the instructions in
+	works.</para>
-	<xref linkend="makeworld-singleuser"/>.</para>
     </sect2>
 
     <sect2 xml:id="make-installworld">
@@ -2160,11 +2070,6 @@ Script done, &hellip;</screen>
 	  <filename>/etc</filename> are not in
 	  <filename>/usr/src/etc</filename>.</para>
 
-	<para>If you are using &man.mergemaster.8; (as recommended),
-	  you can skip forward to the
-	  <link linkend="updating-upgrading-rebooting">next
-	    section</link>.</para>
-
 	<para>The simplest way to merge files by hand is to install
 	  the files into a new directory, and then work through them
 	  looking for differences.</para>
@@ -2376,15 +2281,6 @@ Script done, &hellip;</screen>
       <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
     </sect2>
 
-    <sect2 xml:id="updating-upgrading-rebooting">
-      <title>Rebooting</title>
-
-      <para>Verify that everything appears to be in the right place,
-	then reboot the system using &man.shutdown.8;:</para>
-
-      <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
-    </sect2>
-
     <sect2 xml:id="make-delete-old-libs">
       <title>Deleting obsolete libraries</title>
 
@@ -2607,10 +2503,10 @@ Building everything..
 	</varlistentry>
 
 	<varlistentry>
-	    <term>What do I do if something goes wrong?</term>
+	    <term>What if something goes wrong?</term>
 
 	  <listitem>
-	    <para>Make absolutely sure that the environment has no
+	    <para>First, make absolutely sure that the environment has no
 	      extraneous cruft from earlier builds:</para>
 
 	    <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>