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

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="updating-upgrading">

  <info>
    <title>Updating and Upgrading &os;</title>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Jim</firstname>
	  <surname>Mock</surname>
	</personname>
	<contrib>Restructured, reorganized, and parts updated
	  by </contrib>
      </author>
      <!-- Mar 2000 -->
    </authorgroup>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Jordan</firstname>
	  <surname>Hubbard</surname>
	</personname>
	<contrib>Original work by </contrib>
      </author>

      <author>
	<personname>
	  <firstname>Poul-Henning</firstname>
	  <surname>Kamp</surname>
	</personname>
      </author>

      <author>
	<personname>
	  <firstname>John</firstname>
	  <surname>Polstra</surname>
	</personname>
      </author>

      <author>
	<personname>
	  <firstname>Nik</firstname>
	  <surname>Clayton</surname>
	</personname>
      </author>
    </authorgroup>
  </info>

  <sect1 xml:id="updating-upgrading-synopsis">
    <title>Synopsis</title>

    <para>&os; is under constant development between releases.  Some
      people prefer to use the officially released versions, while
      others prefer to keep in sync with the latest developments.
      However, even official releases are often updated with security
      and other critical fixes.  Regardless of the version used, &os;
      provides all the necessary tools to keep the system updated, and
      allows for easy upgrades between versions.  This chapter
      describes how to track the development system and the basic
      tools for keeping a &os; system up-to-date.</para>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>How to keep a &os; system up-to-date with
	  <application>freebsd-update</application>,
	  <application>Subversion</application>, or
	  <application>CTM</application>.</para>
      </listitem>

      <listitem>
	<para>How to compare the state of an installed system against
	  a known pristine copy.</para>
      </listitem>

      <listitem>
	<para>How to keep the installed documentation up-to-date with
	  <application>Subversion</application> or documentation
	  ports<!--, and <application>Docsnap</application>-->.</para>
      </listitem>

      <listitem>
	<para>The difference between the two development
	  branches: &os.stable; and &os.current;.</para>
      </listitem>

      <listitem>
	<para>How to rebuild and reinstall the entire base
	  system.</para>
      </listitem>
    </itemizedlist>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>
      <listitem>
	<para>Properly set up the network connection
	  (<xref linkend="advanced-networking"/>).</para>
      </listitem>

      <listitem>
	<para>Know how to install additional third-party
	  software (<xref linkend="ports"/>).</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>Throughout this chapter, <command>svn</command> is used to
	obtain and update &os; sources.  To use it, first install the
	<package>devel/subversion</package> port or
	package.</para>
    </note>
  </sect1>

  <sect1 xml:id="updating-upgrading-freebsdupdate">
    <info>
      <title>&os; Update</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Tom</firstname>
	    <surname>Rhodes</surname>
	  </personname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Colin</firstname>
	    <surname>Percival</surname>
	  </personname>
	  <contrib>Based on notes provided by </contrib>
	</author>
      </authorgroup>
    </info>

    <indexterm>
      <primary>Updating and Upgrading</primary>
    </indexterm>
    <indexterm>
      <primary>freebsd-update</primary>
      <see>updating-upgrading</see>
    </indexterm>

    <para>Applying security patches in a timely manner and upgrading
      to a newer release of an operating system are important aspects
      of ongoing system administration.  &os; includes a utility
      called <command>freebsd-update</command> which can be used to
      perform both these tasks.</para>

    <para>This utility supports binary security and errata updates to
      &os;, without the need to manually compile and install the patch
      or a  new kernel.  Binary updates are available for all
      architectures and releases currently supported by the security
      team.  The list of supported releases and their estimated
      end-of-life dates are listed at <uri
	xlink:href="http://www.FreeBSD.org/security/">http://www.FreeBSD.org/security/</uri>.</para>

    <para>This utility also supports operating system upgrades to
      minor point releases as well as upgrades to another release
      branch.  Before upgrading to a new release, review its release
      announcement as it contains important information pertinent to
      the release.  Release announcements are available from <uri
	xlink:href="http://www.FreeBSD.org/releases/">http://www.FreeBSD.org/releases/</uri>.</para>

      <note>
	<para>If a <command>crontab</command> utilizing the features
	  of &man.freebsd-update.8; exists, it must be disabled before
	  upgrading the operating system.</para>
      </note>

    <para>This section describes the configuration file used by
      <command>freebsd-update</command>, demonstrates how to apply a
      security patch and how to upgrade to a minor or major operating
      system release, and discusses some of the considerations when
      upgrading the operating system.</para>

    <sect2 xml:id="freebsdupdate-config-file">
      <title>The Configuration File</title>

      <para>The default configuration file for
	<command>freebsd-update</command> works as-is.  Some users may
	wish to tweak the default configuration in
	<filename>/etc/freebsd-update.conf</filename>, allowing
	better control of the process.  The comments in this file
	explain the available options, but the following may require a
	bit more explanation:</para>

      <programlisting># Components of the base system which should be kept updated.
Components world kernel</programlisting>

      <para>This parameter controls which parts of &os; will be kept
	up-to-date.  The default is to update the entire base system
	and the kernel.  Individual components can instead be
	specified, such as <literal>src/base</literal> or
	<literal>src/sys</literal>.  However, the best option is to
	leave this at the default as changing it to include specific
	items requires every needed item to be listed.  Over time,
	this could have disastrous consequences as source code and
	binaries may become out of sync.</para>

      <programlisting># Paths which start with anything matching an entry in an IgnorePaths
# statement will be ignored.
IgnorePaths /boot/kernel/linker.hints</programlisting>

      <para>To leave specified directories, such as
	<filename>/bin</filename> or <filename>/sbin</filename>,
	untouched during the update process, add their paths to this
	statement.  This option may be used to prevent
	<command>freebsd-update</command> from overwriting local
	modifications.</para>

      <programlisting># Paths which start with anything matching an entry in an UpdateIfUnmodified
# statement will only be updated if the contents of the file have not been
# modified by the user (unless changes are merged; see below).
UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile</programlisting>

      <para>This option will only update unmodified configuration
	files in the specified directories.  Any changes made by the
	user will prevent the automatic updating of these files.
	There is another option,
	<literal>KeepModifiedMetadata</literal>, which will instruct
	<command>freebsd-update</command> to save the changes during
	the merge.</para>

      <programlisting># When upgrading to a new &os; release, files which match MergeChanges
# will have any local changes merged into the version from the new release.
MergeChanges /etc/ /var/named/etc/ /boot/device.hints</programlisting>

      <para>List of directories with configuration files that
	<command>freebsd-update</command> should attempt to merge.
	The file merge process is a series of &man.diff.1; patches
	similar to &man.mergemaster.8;, but with fewer options.
	Merges are either accepted, open an editor, or cause
	<command>freebsd-update</command> to abort.  When in doubt,
	backup <filename>/etc</filename> and just
	accept the merges.  See <xref linkend="mergemaster"/> for more
	information about <command>mergemaster</command>.</para>

      <programlisting># Directory in which to store downloaded updates and temporary
# files used by &os; Update.
# WorkDir /var/db/freebsd-update</programlisting>

      <para>This directory is where all patches and temporary files
	are placed.  In cases where the user is doing a version
	upgrade, this location should have at least a gigabyte of disk
	space available.</para>

      <programlisting># When upgrading between releases, should the list of Components be
# read strictly (StrictComponents yes) or merely as a list of components
# which *might* be installed of which &os; Update should figure out
# which actually are installed and upgrade those (StrictComponents no)?
# StrictComponents no</programlisting>

      <para>When this option is set to <literal>yes</literal>,
	<command>freebsd-update</command> will assume that the
	<literal>Components</literal> list is complete and will not
	attempt to make changes outside of the list.  Effectively,
	<command>freebsd-update</command> will attempt to update
	every file which belongs to the <literal>Components</literal>
	list.</para>
    </sect2>

    <sect2 xml:id="freebsdupdate-security-patches">
      <title>Security Patches</title>

      <para>&os; security patches may be downloaded and installed
	using the following command:</para>

      <screen>&prompt.root; <userinput>freebsd-update fetch</userinput>
&prompt.root; <userinput>freebsd-update install</userinput></screen>

      <para>If the update applied any kernel patches, the system will
	need a reboot in order to boot into the patched kernel.
	Otherwise,  the system should be patched and
	<command>freebsd-update</command> may be run as a nightly
	&man.cron.8; job by adding this entry to
	<filename>/etc/crontab</filename>:</para>

      <programlisting>@daily                                  root    freebsd-update cron</programlisting>

      <para>This entry states that <command>freebsd-update</command>
	will run once every day.  When run with <option>cron</option>,
	<command>freebsd-update</command> will only check if updates
	exist.  If patches exist, they will automatically be
	downloaded to the local disk but will not be applied.  The
	<systemitem class="username">root</systemitem> user will be
	sent an email so that they may be reviewed and manually
	installed.</para>

      <para>If anything goes wrong, <command>freebsd-update</command>
	has the ability to roll back the last set of changes with
	the following command:</para>

      <screen>&prompt.root; <userinput>freebsd-update rollback</userinput></screen>

      <para>Once complete, the system should be restarted if the
	kernel or any kernel modules were modified.  This will allow
	&os; to load the new binaries into memory.</para>

      <para>Only the <filename>GENERIC</filename> kernel can be
	automatically updated by <command>freebsd-update</command>.
	If a custom kernel is installed, it will have to be rebuilt
	and reinstalled after <command>freebsd-update</command>
	finishes installing the rest of the updates.  However,
	<command>freebsd-update</command> will detect and update the
	<filename>GENERIC</filename> kernel if
	<filename>/boot/GENERIC</filename> exists,
	even if it is not the current running kernel of the
	system.</para>

      <note>
	<para>It is a good idea to 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
	  <command>freebsd-update</command> as described in
	  <xref linkend="freebsdupdate-upgrade"/>.</para>
      </note>

      <para>Unless the default configuration in
	<filename>/etc/freebsd-update.conf</filename> has been
	changed, <command>freebsd-update</command> will install the
	updated kernel sources along with the rest of the updates.
	Rebuilding and reinstalling a new custom kernel can then be
	performed in the usual way.</para>

      <note>
	<para>The updates distributed by
	  <command>freebsd-update</command> do not always involve the
	  kernel.  It is not necessary to rebuild a custom kernel if
	  the kernel sources have not been modified by the execution
	  of <command>freebsd-update install</command>.
	  However, <command>freebsd-update</command> will always
	  update <filename>/usr/src/sys/conf/newvers.sh</filename>.
	  The current patch level, as indicated by the
	  <literal>-p</literal> number reported by
	  <command>uname -r</command>, is obtained from this file.
	  Rebuilding a custom kernel, even if nothing else changed,
	  allows &man.uname.1; to accurately report the current
	  patch level of the system.  This is particularly helpful
	  when maintaining multiple systems, as it allows for a quick
	  assessment of the updates installed in each one.</para>
      </note>
    </sect2>

    <sect2 xml:id="freebsdupdate-upgrade">
      <title>Major and Minor Version Upgrades</title>

      <para>Upgrades from one minor version of &os; to another, like
	from &os;&nbsp;9.0 to &os;&nbsp;9.1, are called
	<emphasis>minor version</emphasis> upgrades.  Generally,
	installed applications will continue to work without problems
	after minor version upgrades.</para>

      <para><emphasis>Major version</emphasis> upgrades occur when
	&os; is upgraded from one major version to another, like from
	&os;&nbsp;8.X to &os;&nbsp;9.X.  Major version upgrades remove
	old object files and libraries which will break most third
	party applications.  It is recommended that all installed
	ports either be removed and re-installed or upgraded after a
	major version upgrade using a utility such as
	<package>ports-mgmt/portmaster</package>.  A
	brute-force rebuild of all installed applications can be
	accomplished with this command:</para>

      <screen>&prompt.root; <userinput>portmaster -af</userinput></screen>

      <para>This will ensure everything will be re-installed
	correctly.  Note that setting the
	<varname>BATCH</varname> environment variable to
	<literal>yes</literal> will answer <literal>yes</literal> to
	any prompts during this process, removing the need for
	manual intervention during the build process.</para>

      <sect3 xml:id="freebsd-update-custom-kernel">
	<title>Dealing with Custom Kernels</title>

	<para>If a custom kernel is in use, the upgrade process is
	  slightly more involved, and the procedure varies depending
	  on the version of &os;.</para>

	<sect4 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
	    needed, and should be placed in
	    <filename>/boot/GENERIC</filename>.  If the
	    <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
		using the following commands:</para>

	      <screen>&prompt.root; <userinput>mount /cdrom</userinput>
&prompt.root; <userinput>cd /cdrom/X.Y-RELEASE/kernels</userinput>
&prompt.root; <userinput>./install.sh GENERIC</userinput></screen>

	      <para>Replace <filename>X.Y-RELEASE</filename>
		with the actual 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>Failing all the above, the
		<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>
&prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput>
&prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen>

	      <para>For this kernel to be picked up as
		<filename>GENERIC</filename> by
		<command>freebsd-update</command>, the
		<filename>GENERIC</filename> configuration file must
		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
	    is not required at this stage.</para>
	</sect4>

	<sect4 xml:id="freebsd-update-custom-kernel-9x">
	  <title>Custom Kernels with &os;&nbsp;9.X and Later</title>

	  <itemizedlist>
	    <listitem>
	      <para>If a custom kernel has only been built once, the
		kernel in <filename>/boot/kernel.old</filename> is
		actually the <literal>GENERIC</literal> kernel.
		Rename this directory to
		<filename>/boot/kernel</filename>.</para>
	    </listitem>

	    <listitem>
	      <para>If physical access to the machine is available, a
		copy of the <literal>GENERIC</literal> kernel can be
		installed from the installation media using these
		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>If the options above cannot be used, the
		<literal>GENERIC</literal> kernel may be rebuilt and
		installed from source:</para>

	      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput></screen>

	      <para>For this kernel to be identified as the
		<literal>GENERIC</literal> kernel by
		<command>freebsd-update</command>, the
		<filename>GENERIC</filename> configuration file must
		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
	    is not required at this stage.</para>
	</sect4>
      </sect3>

      <sect3 xml:id="freebsdupdate-using">
	<title>Performing the Upgrade</title>

	<para>Major and minor version upgrades may be performed by
	  providing <command>freebsd-update</command> with a release
	  version target.  The following command will update to
	  &os;&nbsp;9.1:</para>

	<screen>&prompt.root; <userinput>freebsd-update -r 9.1-RELEASE upgrade</userinput></screen>

	<para>After the command has been received,
	  <command>freebsd-update</command> will evaluate the
	  configuration file and current system in an attempt to
	  gather the information necessary to perform the upgrade.  A
	  screen listing will display which components have and have
	  not been detected.  For example:</para>

	<screen>Looking up update.FreeBSD.org mirrors... 1 mirrors found.
Fetching metadata signature for 9.0-RELEASE from update1.FreeBSD.org... done.
Fetching metadata index... done.
Inspecting system... done.

The following components of FreeBSD seem to be installed:
kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games
src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue
src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin
world/base world/info world/lib32 world/manpages

The following components of FreeBSD do not seem to be installed:
kernel/generic world/catpages world/dict world/doc world/games
world/proflibs

Does this look reasonable (y/n)? y</screen>

	<para>At this point, <command>freebsd-update</command> will
	  attempt to download all files required for the upgrade.  In
	  some cases, the user may be prompted with questions
	  regarding what to install or how to proceed.</para>

	<para>When using a custom kernel, the above step will produce
	  a warning similar to the following:</para>

	<screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" kernel, which is not a
kernel configuration distributed as part of FreeBSD 9.0-RELEASE.
This kernel will not be updated: you MUST update the kernel manually
before running "/usr/sbin/freebsd-update install"</screen>

	<para>This warning may be safely ignored at this point.  The
	  updated <filename>GENERIC</filename> kernel will be used as
	  an intermediate step in the upgrade process.</para>

	<para>Once all the patches have been downloaded to the local
	  system, they will be applied.  This process may take a
	  while, depending on the speed and workload of the machine.
	  Configuration files will then be merged.  The merging
	  process requires some user intervention as a file may be
	  merged or an editor may appear on screen for a manual merge.
	  The results of every successful merge will be shown to the
	  user as the process continues.  A failed or ignored merge
	  will cause the process to abort.  Users may wish to make a
	  backup of <filename>/etc</filename> and
	  manually merge important files, such as
	  <filename>master.passwd</filename> or
	  <filename>group</filename> at a later time.</para>

	<note>
	  <para>The system is not being altered yet as all patching
	    and merging is happening in another directory.  Once all
	    patches have been applied successfully, all configuration
	    files have been merged and it seems the process will go
	    smoothly, the changes can be committed to disk by the
	    user using the following command:</para>

	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>

	</note>

	<para>The kernel and kernel modules will be patched first.  At
	  this point, the machine must be rebooted.  If 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>

	<screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen>

	<warning>
	  <para>Before rebooting with the <filename>GENERIC</filename>
	    kernel, make sure it contains all the drivers required for
	    the system to boot properly and connect to the network,
	    if the machine being updated is accessed remotely.  In
	    particular, if the running custom kernel contains built-in
	    functionality usually provided by kernel modules, make
	    sure to temporarily load these modules into the
	    <filename>GENERIC</filename> kernel using the
	    <filename>/boot/loader.conf</filename> facility.
	    It is recommended to disable non-essential services as
	    well as any disk and network mounts until the upgrade
	    process is complete.</para>
	</warning>

	<para>The machine should now be restarted with the updated
	  kernel:</para>

	<screen>&prompt.root; <userinput>shutdown -r now</userinput></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>freebsd-update</command> will not start from the
	  beginning, but will remove all old shared libraries and
	  object files.</para>

	<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>

	<note>
	  <para>Depending upon whether any library version numbers
	    were bumped, there may only be two install phases instead
	    of three.</para>
	</note>
      </sect3>

      <sect3 xml:id="freebsdupdate-portsrebuild">
	<title>Rebuilding Ports After a Major Version Upgrade</title>

	<para>After a major version upgrade, all third party software
	  needs to be rebuilt and re-installed.  This is required as
	  installed software may depend on libraries which have been
	  removed during the upgrade process.  This process can be
	  automated using
	  <package>ports-mgmt/portmaster</package>:</para>

	<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>

	<para>Once this has completed, 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>

	<screen>&prompt.root; <userinput>freebsd-update install</userinput></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>

	<para>Reboot the machine into the new &os; version.  The
	  process is 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
	state of the installed &os; version against a known good copy.
	This option evaluates the current version of system utilities,
	libraries, and configuration files.  To begin the comparison,
	issue the following command:</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
	  not a replacement for a real intrusion detection system 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
	  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>
      </warning>

      <para>The system will now be inspected, and a lengthy listing of
	files, along with the &man.sha256.1; hash values for both the
	known value in the release and the current installation, will
	be sent to the specified
	<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
	list of all files which differ from those in the release,
	issue the following command:</para>

      <screen>&prompt.root; <userinput>cat outfile.ids | awk '{ print $1 }' | more</userinput>
/etc/master.passwd
/etc/motd
/etc/passwd
/etc/pf.conf</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
	users have been added to the system.  Other files, such 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>

  <sect1 xml:id="updating-upgrading-documentation">
    <title>Updating the Documentation Set</title>

    <indexterm><primary>Updating and Upgrading</primary></indexterm>

    <indexterm>
      <primary>Documentation</primary>
      <see>Updating and Upgrading</see>
    </indexterm>

    <para>Documentation is an integral part of the &os; operating
      system.  While an up-to-date version of the &os; Documentation
      Set is always available on the
      <link xlink:href="http://www.freebsd.org/doc/">&os; web
	site</link>, some users might have slow or no permanent
      network connectivity.  There are several ways to update the
      local copy of documentation with the latest &os; Documentation
      Set.</para>

    <sect2 xml:id="dsvn-doc">
      <title>Using <application>Subversion</application> to Update the
	Documentation</title>

      <para>The &os; documentation sources can be obtained with
	<application>svn</application>.  This section
	describes how to:</para>

      <itemizedlist>
	<listitem>
	  <para>Install the documentation toolchain, the tools that
	    are required to rebuild the &os; documentation from its
	    source.</para>
	</listitem>

	<listitem>
	  <para>Download a copy of the documentation source at
	    <filename>/usr/doc</filename>, using
	    <application>svn</application>.</para>
	</listitem>

	<listitem>
	  <para>Rebuild the &os; documentation from its source, and
	    install it under
	    <filename>/usr/share/doc</filename>.</para>
	</listitem>

	<listitem>
	  <para>Recognize some of the build options that are
	    supported by the build system of the documentation, such
	    as the options that build only some of the different
	    language translations of the documentation or the options
	    that select a specific output format.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 xml:id="installing-documentation-toolchain">
      <title>Installing <application>svn</application> and the
	Documentation Toolchain</title>

      <para>Rebuilding the &os; documentation from source requires a
	collection of tools which are not part of the &os; base system
	due to the amount of disk space these tools use.  They are
	also not useful to all &os; users, only those users that are
	actively writing new documentation for &os; or are frequently
	updating their documentation from source.</para>

      <para>The required tools, including
	<application>svn</application>, are available in the
	<package>textproc/docproj</package> meta-port
	developed by the &os; Documentation Project.</para>

      <note>
	<para>When no &postscript; or PDF documentation required, one
	  might consider installing the
	  <package>textproc/docproj-nojadetex</package> port instead.
	  This version of the documentation toolchain includes
	  everything except the <application>teTeX</application>
	  typesetting engine.  <application>teTeX</application> is a
	  very large collection of tools, so it may be quite sensible
	  to omit its installation if PDF output is not really
	  necessary.</para>
      </note>
    </sect2>

    <sect2 xml:id="updating-documentation-sources">
      <title>Updating the Documentation Sources</title>

      <para>In this example, <application>svn</application> is used to
	fetch a clean copy of the documentation sources from the
	western US mirror using the HTTPS protocol:</para>

      <screen>&prompt.root; <userinput>svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc</userinput></screen>

      <para>Select the closest mirror from the available
	<link linkend="svn-mirrors">Subversion mirror
	  sites</link>.</para>

      <para>The initial download of the documentation sources may take
	a while.  Let it run until it completes.</para>

      <para>Future updates of the documentation sources may be fetched
	by running:</para>

      <screen>&prompt.root; <userinput>svn update /usr/doc</userinput></screen>

      <para>After checking out the sources, an alternative way of
	updating the documentation is supported by the
	<filename>/usr/doc/Makefile</filename> by running the
	following commands:</para>

      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make update</userinput></screen>
    </sect2>

    <sect2 xml:id="updating-documentation-options">
      <title>Tunable Options of the Documentation Sources</title>

      <para>The updating and build system of the &os; documentation
	set supports a few options that ease the process of updating
	only parts of the documentation, or the build of specific
	translations.  These options can be set either as system-wide
	options in <filename>/etc/make.conf</filename>, or as
	command-line options passed to &man.make.1;.</para>

      <para>The options include:</para>

      <variablelist>
	<varlistentry>
	  <term><varname>DOC_LANG</varname></term>

	  <listitem>
	    <para>The list of languages and encodings to build and
	      install, such as <literal>en_US.ISO8859-1</literal> for
	      English documentation.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><varname>FORMATS</varname></term>

	  <listitem>
	    <para>A single format or a list of output formats to be
	      built.  Currently, <literal>html</literal>,
	      <literal>html-split</literal>, <literal>txt</literal>,
	      <literal>ps</literal>, <literal>pdf</literal>,
	      and <literal>rtf</literal> are supported.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><varname>DOCDIR</varname></term>

	  <listitem>
	    <para>Where to install the documentation.  It defaults to
	      <filename>/usr/share/doc</filename>.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>For more <command>make</command> variables supported as
	system-wide options in &os;, refer to
	&man.make.conf.5;.</para>

      <para>For more <command>make</command> variables supported by
	the build system of the &os; documentation, refer to the
	<link xlink:href="&url.doc.langbase;/books/fdp-primer">&os;
	  Documentation Project Primer for New
	  Contributors</link>.</para>
    </sect2>

    <sect2 xml:id="updating-installed-documentation">
      <title>Installing the &os; Documentation from Source</title>

      <para>Once an up-to-date snapshot of the documentation sources
	has been fetched to <filename>/usr/doc</filename>, everything
	is ready for an update of the installed documentation.</para>

      <para>A full update of all the languages defined in
	<varname>DOC_LANG</varname> may be performed by typing:</para>

      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

      <para>If an update of only a specific language is desired,
	&man.make.1; can be invoked in a language specific
	subdirectory of
	<filename>/usr/doc</filename>:</para>

      <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
&prompt.root; <userinput>make update install clean</userinput></screen>

      <para>The output formats that will be installed may be specified
	by setting <varname>FORMATS</varname>:</para>

      <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>

      <para>For information on editing and submitting corrections to
	the documentation, refer to the
	<link xlink:href="&url.books.fdp-primer;">&os; Documentation
	  Project Primer for New Contributors</link>.</para>
    </sect2>

    <sect2 xml:id="doc-ports">
      <info>
	<title>Using Documentation Ports</title>

	<authorgroup>
	  <author>
	    <personname>
	      <firstname>Marc</firstname>
	      <surname>Fonvieille</surname>
	    </personname>
	    <contrib>Based on the work of </contrib>
	  </author>
	</authorgroup>
      </info>

      <indexterm>
	<primary>Updating and Upgrading</primary>
      </indexterm>

      <indexterm>
	<primary>documentation package</primary>
	<see>Updating and Upgrading</see>
      </indexterm>

      <para>The previous section presented a method for updating the
	&os; documentation from sources.  Source based updates may not
	be feasible or practical for all &os; systems as building the
	documentation sources requires the <emphasis>documentation
	  toolchain</emphasis>, a certain level of familiarity with
	<application>svn</application> and source checkouts from a
	repository, and a few manual steps to build the checked out
	sources.  This section describes an alternative method which
	uses the Ports Collection and makes it possible to:</para>

      <itemizedlist>
	<listitem>
	  <para>Download and install pre-built snapshots of the
	    documentation, without having to locally build anything
	    or install the documentation toolchain.</para>
	</listitem>

	<listitem>
	  <para>Download the documentation sources and build them
	    through the ports framework, making the checkout and build
	    steps a bit easier.</para>
	</listitem>
      </itemizedlist>

      <para>These two methods of updating the &os; documentation are
	supported by a set of
	<emphasis>documentation ports</emphasis>, updated by the
	&a.doceng; on a monthly basis.  These are listed in the &os;
	Ports&nbsp;Collection, under the <link
	  xlink:href="http://www.freshports.org/docs/">docs</link>
	category.</para>

      <sect3 xml:id="doc-ports-install-make">
	<title>Building and Installing Documentation Ports</title>

	<para>The documentation ports use the ports building framework
	  to make documentation builds easier.  They automate the
	  process of checking out the documentation source, running
	  &man.make.1; with the appropriate environment settings and
	  command-line options, and they make the installation or
	  deinstallation of documentation as easy as the installation
	  of any other &os; port or package.</para>

	<note>
	  <para>As an extra feature, when the documentation ports are
	    built locally, they record a dependency to the
	    <emphasis>documentation toolchain</emphasis> ports, so
	    that they are also automatically installed.</para>
	</note>

	<para>Organization of the documentation ports is as
	  follows:</para>

	<itemizedlist>
	  <listitem>
	    <para>The <quote>master port</quote>,
	      <package>misc/freebsd-doc-en</package>, which installs
	      all of the English documentation ports.</para>
	  </listitem>

	  <listitem>
	    <para>The <quote>all in one port</quote>,
	      <package>misc/freebsd-doc-all</package>, builds and
	      installs all documentation in all available
	      languages.</para>
	  </listitem>

	  <listitem>
	    <para>There is a <quote>slave port</quote> for each
	      translation, such as
	      <package>misc/freebsd-doc-hu</package> for the
	      Hungarian-language documents.</para>
	  </listitem>
	</itemizedlist>

	<para>For example, to build and install the English
	  documentation in split <acronym>HTML</acronym> format,
	  similar to the format used on <uri
	    xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>,
	  to <filename>/usr/local/share/doc/freebsd</filename>,
	  install the following port</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

	<sect4 xml:id="doc-ports-options">
	  <title>Common Knobs and Options</title>

	  <para>There are many options for modifying the default
	    behavior of the documentation ports, including:</para>

	  <variablelist>
	    <varlistentry>
	      <term><varname>WITH_HTML</varname></term>

	      <listitem>
		<para>Builds the HTML format with a single HTML file
		  per document.  The formatted documentation is saved
		  to a file called <filename>article.html</filename>,
		  or <filename>book.html</filename>, as appropriate,
		  plus images.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><varname>WITH_PDF</varname></term>

	      <listitem>
		<para>Builds the &adobe; Portable Document Format
		  (PDF).  The formatted documentation is saved to a
		  file called <filename>article.pdf</filename> or
		  <filename>book.pdf</filename>, as
		  appropriate.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><varname>DOCBASE</varname></term>

	      <listitem>
		<para>Specifies where to install the documentation.
		  It defaults to
		  <filename>/usr/local/share/doc/freebsd</filename>.</para>

		<note>
		  <para>The default target directory differs from the
		    directory used <application>svn</application>.
		    This is because ports are usually installed within
		    <filename>/usr/local</filename>.
		    This can be overridden by using
		    <varname>PREFIX</varname>.</para>
		</note>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>This example uses variables to install the Hungarian
	    documentation as a PDF:</para>

	  <screen>&prompt.root; cd /usr/ports/misc/freebsd-doc-hu
&prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean</screen>
	</sect4>
      </sect3>

      <sect3 xml:id="doc-ports-install-package">
	<title>Using Documentation Packages</title>

	<para>Building the documentation ports from source, as
	  described in the previous section, requires a local
	  installation of the documentation toolchain and a bit of
	  disk space for the build of the ports.  When resources are
	  not available to install the documentation toolchain, or
	  because the build from sources would take too much disk
	  space, it is still possible to install pre-built snapshots
	  of the documentation ports.</para>

	<para>The &a.doceng; prepares monthly snapshots of the &os;
	  documentation packages.  These binary packages can be used
	  with any of the bundled package tools, like &man.pkg.add.1;,
	  &man.pkg.delete.1;, and so on.</para>

	<note>
	  <para>When binary packages are used, the &os; documentation
	    will be installed in <emphasis>all</emphasis> available
	    formats for the given language.</para>
	</note>

	<para>For example, the following command will install the
	  latest pre-built package of the Hungarian
	  documentation:</para>

	<screen>&prompt.root; <userinput>pkg install hu-freebsd-doc</userinput></screen>

	<note>
	  <para>Packages use a format that differs from the
	    corresponding port's name:
	    <literal>lang-freebsd-doc</literal>,
	    where <replaceable>lang</replaceable> is the short format
	    of the language code, such as <literal>hu</literal> for
	    Hungarian, or <literal>zh_cn</literal> for Simplified
	    Chinese.</para>
	</note>
      </sect3>

      <sect3 xml:id="doc-ports-update">
	<title>Updating Documentation Ports</title>

	<para>Documentation ports can be updated like any other port.
	  For example, the following command updates the installed
	  Hungarian documentation using
	  <package>ports-mgmt/portmaster</package>
	  by using packages only:</para>

	<screen>&prompt.root; <userinput>portmaster -PP hu-freebsd-doc</userinput></screen>
      </sect3>
    </sect2>
  </sect1>

  <sect1 xml:id="current-stable">
    <title>Tracking a Development Branch</title>

    <indexterm><primary>-CURRENT</primary></indexterm>
    <indexterm><primary>-STABLE</primary></indexterm>

    <para>&os; has two development branches: &os.current; and
      &os.stable;.</para>

    <para>This section provides an explanation of each branch and its
      intended audience as well as how to keep a system up-to-date
      with each respective branch.</para>

    <sect2 xml:id="current">
      <title>Using &os.current;</title>

      <para>&os.current; is the <quote>bleeding edge</quote> of &os;
	development and  &os.current; users are expected to have a
	high degree of technical skill.  Less technical users who wish
	to track a development branch should track &os.stable;
	instead.</para>

      <para>&os.current; is the very latest source code for &os; and
	includes works in progress, experimental changes, and
	transitional mechanisms that might or might not be present in
	the next official release.  While many &os; developers compile
	the &os.current; source code daily, there are short periods of
	time when the source may not be buildable.  These problems are
	resolved as quickly as possible, but whether or not
	&os.current; brings disaster or new functionality can be a
	matter of when the source code was synced.</para>

      <para>&os.current; is made available for three primary interest
	groups:</para>

      <orderedlist>
	<listitem>
	  <para>Members of the &os; community who are actively
	    working on some part of the source tree.</para>
	</listitem>

	<listitem>
	  <para>Members of the &os; community who are active testers.
	    They are willing to spend time solving problems, making
	    topical suggestions on changes and the general direction
	    of &os;, and submitting patches.</para>
	</listitem>

	<listitem>
	  <para>Users who wish to keep an eye on things, use the
	    current source for reference purposes, or make the
	    occasional comment or code contribution.</para>
	</listitem>
      </orderedlist>

      <para>&os.current; should <emphasis>not</emphasis> be
	considered a fast-track to getting new features before the
	next release as pre-release features are not yet fully tested
	and most likely contain bugs.  It is not a quick way of
	getting bug fixes as any given commit is just as likely to
	introduce new bugs as to fix existing ones.  &os.current; is
	not in any way <quote>officially supported</quote>.</para>

      <indexterm>
	<primary>-CURRENT</primary>
	<secondary>using</secondary>
      </indexterm>

      <para>To track &os.current;:</para>

      <orderedlist>
	<listitem>
	  <para>Join the &a.current.name; and the
	    &a.svn-src-head.name; lists.  This is
	    <emphasis>essential</emphasis> in order to see the
	    comments that people are making about the current state
	    of the system and to receive important bulletins about
	    the current state of &os.current;.</para>

	  <para>The &a.svn-src-head.name; list records the commit log
	    entry for each change as it is made, along with any
	    pertinent information on possible side effects.</para>

	  <para>To join these lists, go to &a.mailman.lists.link;,
	    click on the list to subscribe to, and follow the
	    instructions.  In order to track changes to the whole
	    source tree, not just the changes to &os.current;,
	    subscribe to the &a.svn-src-all.name; list.</para>
	</listitem>

	<listitem>
	  <para>Synchronize with the &os.current; sources.  Typically,
	    <link linkend="svn">svn</link> is used to check out the
	    -CURRENT code from the <literal>head</literal> branch of
	    one of the <link linkend="svn-mirrors">Subversion mirror
	      sites</link>.</para>

	  <para>Users with very slow or limited Internet connectivity
	    can instead use <link linkend="ctm">CTM</link>, but it is
	    not as reliable as <application>svn</application> and
	    <application>svn</application> is the recommended method
	    for synchronizing source.</para>
	</listitem>

	<listitem>
	  <para> Due to the size of the repository, some users choose
	    to only synchronize the sections of source that interest
	    them  or which they are contributing patches to.  However,
	    users that plan to compile the operating system from
	    source must download <emphasis>all</emphasis> of
	    &os.current;, not just selected portions.</para>

	  <para>Before compiling &os.current;
	    <indexterm>
	      <primary>-CURRENT</primary>
		<secondary>compiling</secondary>
	    </indexterm>, read <filename>/usr/src/Makefile</filename>
	    very carefully and follow the instructions in
	    <link linkend="makeworld">Rebuilding "world"</link>.
	    Read the &a.current; and
	    <filename>/usr/src/UPDATING</filename> to stay
	    up-to-date on other bootstrapping procedures that
	    sometimes become necessary on the road to the next
	    release.</para>
	</listitem>

	<listitem>
	  <para>Be active! &os.current; users are encouraged to
	    submit their suggestions for enhancements or bug fixes.
	    Suggestions with accompanying code are always
	    welcome.</para>
	</listitem>
      </orderedlist>
    </sect2>

    <sect2 xml:id="stable">
      <title>Using &os.stable;</title>

      <para>&os.stable; is the development branch from which major
	releases are made.  Changes go into this branch at a slower
	pace and with the general assumption that they have first been
	tested in &os.current;.  This is <emphasis>still</emphasis> a
	development branch and, at any given time, the sources for
	&os.stable; may or may not be suitable for general use.  It is
	simply another engineering development track, not a resource
	for end-users.  Users who do not have the resources to perform
	testing should instead run the most recent release of
	&os;.</para>

      <para>Those interested in tracking or contributing to the &os;
	development process, especially as it relates to the next
	release of &os;, should consider following &os.stable;.</para>

      <para>While the &os.stable; branch should compile and run at all
	times, this cannot be guaranteed.  Since more people run
	&os.stable; than &os.current;, it is inevitable that bugs and
	corner cases will sometimes be found in &os.stable; that were
	not apparent in &os.current;.  For this reason, one should not
	blindly track &os.stable;.  It is particularly important
	<emphasis>not</emphasis> to update any production servers to
	&os.stable; without thoroughly testing the code in a
	development or testing environment.</para>

      <para>To track &os.stable;:</para>

      <indexterm>
	<primary>-STABLE</primary>
	  <secondary>using</secondary>
      </indexterm>
      <orderedlist>
	<listitem>
	  <para>Join the &a.stable.name; list in order to stay
	    informed of build dependencies that may appear in
	    &os.stable; or any other issues requiring special
	    attention.  Developers will also make announcements in
	    this mailing list when they are contemplating some
	    controversial fix or update, giving the users a chance to
	    respond if they have any issues to raise concerning the
	    proposed change.</para>

	  <para>Join the relevant <application>svn</application> list
	    for the branch being tracked.  For example, users
	    tracking the 9-STABLE branch should join the
	    &a.svn-src-stable-9.name; list.  This list records the
	    commit log entry for each change as it is made, along
	    with any pertinent information on possible
	    side effects.</para>

	  <para>To join these lists, go to &a.mailman.lists.link;,
	    click on the list to subscribe to, and follow the
	    instructions.  In order to track changes for the whole
	    source tree, subscribe to &a.svn-src-all.name;.</para>
	</listitem>

	<listitem>
	  <para>To install a new &os.stable; system, install the most
	    recent &os.stable; release from the <link
	      linkend="mirrors">&os; mirror sites</link> or use a
	    monthly snapshot built from &os.stable;.  Refer to <link
	      xlink:href="&url.base;/snapshots/">Snapshots</link> for
	    more information about snapshots.</para>

	  <para>To compile or upgrade to an existing &os; system to
	    &os.stable;, use <link linkend="svn">svn</link>
	      <indexterm>
		<primary>Subversion</primary>
	      </indexterm> to check out the source for the desired
	    branch.  Branch names, such as
	    <literal>stable/9</literal>, are identified in <link
	      xlink:href="&url.base;/releng/">the release
	      engineering page</link>.   <link
	      linkend="ctm">CTM</link> can be used
	      <indexterm>
		<primary>-STABLE</primary>
		  <secondary>syncing with CTM</secondary>
		</indexterm> if a reliable Internet connection is not
	    available.</para>
	</listitem>

	<listitem>
	  <para>Before compiling or upgrading to &os.stable;
	    <indexterm>
	      <primary>-STABLE</primary>
		<secondary>compiling</secondary>
	    </indexterm>, read <filename>/usr/src/Makefile</filename>
	    carefully and follow the instructions in <link
	      linkend="makeworld">Rebuilding "world"</link>.  Read
	    &a.stable; and <filename>/usr/src/UPDATING</filename> to
	    keep up-to-date on other bootstrapping procedures that
	    sometimes become necessary on the road to the next
	    release.</para>
	</listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 xml:id="synching">
    <title>Synchronizing Source</title>

    <para>There are various ways of using an Internet or email
      connection to stay up-to-date with any given area, or all areas,
      of the &os; project sources.  The primary services are
      <link linkend="svn">Subversion</link> and
      <link linkend="ctm">CTM</link>.</para>

    <warning>
      <para>While it is possible to update only parts of the source
	tree, the only supported update procedure is to update the
	entire tree and recompile all the programs that run in user
	space, such as those in <filename>/bin</filename> and
	<filename>/sbin</filename>, and kernel sources.  Updating only
	part of the source tree, only the kernel, or only the userland
	programs will often result in problems ranging from compile
	errors to kernel panics or data corruption.</para>
    </warning>

    <indexterm>
      <primary>Subversion</primary>
    </indexterm>

    <para><application>Subversion</application> uses the
      <emphasis>pull</emphasis> model of updating sources.  The user,
      or a <command>cron</command> script, invokes the
      <command>svn</command> program, and it brings files up-to-date.
      <application>Subversion</application> is the preferred means of
      updating local source trees.  The updates are up-to-the-minute
      and the user controls when they are downloaded.  It is easy to
      restrict updates to specific files or directories and the
      requested updates are generated on the fly by the server.</para>

    <indexterm>
      <primary><application>CTM</application></primary>
    </indexterm>
    <para><application>CTM</application> does not interactively
      compare the local sources with those on the master archive or
      otherwise pull them across.  Instead, a script which identifies
      changes in files since its previous run is executed several
      times a day on the master CTM machine.  Any detected changes are
      compressed, stamped with a sequence-number, and encoded for
      transmission over email in printable ASCII only.  Once received,
      these <quote>CTM deltas</quote> can then be handed to the
      &man.ctm.rmail.1; utility which will automatically decode,
      verify, and apply the changes to the user's copy of the sources.
      This process is more efficient than
      <application>Subversion</application> and places less strain on
      server resources since it is a <emphasis>push</emphasis>
      rather than a <emphasis>pull</emphasis> model.</para>

    <para>There are other trade-offs.  If a user inadvertently
      wipes out portions of the local archive,
      <application>Subversion</application> will detect and rebuild
      the damaged portions.  <application>CTM</application> will not
      do this, and if a user deletes some portion of the source tree
      and does not have a backup, they will have to start from scratch
      from the most recent CTM <quote>base delta</quote> and rebuild
      it all with <application>CTM</application>.</para>
  </sect1>

  <sect1 xml:id="makeworld">
    <title>Rebuilding <quote>world</quote></title>

    <indexterm>
      <primary>Rebuilding <quote>world</quote></primary>
    </indexterm>
    <para>Once the local source tree is synchronized against a
      particular version of &os; such as &os.stable; or &os.current;,
      the source tree can be used to rebuild the system.  This process
      is known as rebuilding world.</para>

    <para><emphasis>Before</emphasis> rebuilding world, be sure to
      perform the following tasks:</para>

    <procedure>
      <title>Perform These Tasks <emphasis>Before</emphasis>
	Building World</title>

      <step>
	<para>Backup all important data to another system or removable
	  media, verify the integrity of the backup, and have a
	  bootable installation media at hand.  It cannot be stressed
	  enough how important it is to make a backup of the system
	  <emphasis>before</emphasis> rebuilding the system.  While
	  rebuilding world is an easy task, there will inevitably be
	  times when mistakes in the source tree render the system
	  unbootable.  You will probably never have to use the backup,
	  but it is better to be safe than sorry!</para>
      </step>

      <step>
	<indexterm><primary>mailing list</primary></indexterm>
	<para>Review the recent &a.stable.name; or &a.current.name;
	  entries, depending upon the branch being tracked.  Be aware
	  of any known problems and which systems are affected.  If a
	  known issue affects the version of synchronized code, wait
	  for an <quote>all clear</quote> announcement to be posted
	  stating that the problem has been solved.  Resynchronize the
	  sources to ensure that the local version of source has the
	  needed fix.</para>
      </step>

      <step>
	<para>Read <filename>/usr/src/UPDATING</filename> for any
	  pre-buildworld steps necessary for that version of the
	  source.  This file contains important information about
	  potential problems and may specify the order to run certain
	  commands.  Many upgrades require specific additional steps
	  such as renaming or deleting specific files prior to
	  installworld.  These will be listed at the end of this file
	  where the currently recommended upgrade sequence is
	  explicitly spelled out.  If
	  <filename>UPDATING</filename> contradicts any steps in this
	  chapter, the instructions in <filename>UPDATING</filename>
	  take precedence and should be followed.</para>
      </step>
    </procedure>

    <warning>
      <title>Do Not Use <command>make world</command></title>

      <para>Some older documentation recommends using
	<command>make world</command>.  However, that command skips
	some important steps and should only be used by experts.  For
	almost all circumstances <command>make world</command> is the
	wrong thing to do, and the procedure described here should be
	used instead.</para>
    </warning>

    <sect2 xml:id="canonical-build">
      <title>Overview of Process</title>

      <para>The build world process assumes an upgrade from an older
	&os; version using the source of a newer version that was
	obtained using the instructions in
	<xref linkend="synching"/>.</para>

      <para>In &os;, the term <quote>world</quote> includes the
	kernel, core system binaries, libraries, programming files,
	and built-in compiler.  The order in which these components
	are built and installed is important.</para>

      <para>For example, the old compiler might have a bug and not be
	able to compile the new kernel.  Since the new kernel should
	be built with the new compiler, the new compiler must be
	built, but not necessarily installed, before the new kernel is
	built.</para>

      <para>The new world might rely on new kernel features, so the
	new kernel must be installed before the new world is
	installed.  The old world might not run correctly on the new
	kernel, so the new world must be installed immediately upon
	installing the new kernel.</para>

      <para>Some configuration changes must be made before the new
	world is installed, but others might break the old world.
	Hence, two different configuration upgrade steps are used.
	For the most part, the update process only replaces or adds
	files and existing old files are not deleted.  Since this can
	cause problems, <filename>/usr/src/UPDATING</filename> will
	indicate if any files need to be manually deleted and at which
	step to do so.</para>

      <para>These concerns have led to the recommended upgrade
	sequence  described in
	the following procedure.</para>

      <procedure>
	<title>Overview of Build World Process</title>

	<para>The commands used in the build world process should be
	  run in the order specified here.  This section summarizes
	  the function of each command.</para>

	<step>
	  <para>Compile the new compiler and a few related
	    tools, then use the new compiler to compile the rest of
	    the new world.  The result is saved to
	    <filename class="directory">/usr/obj</filename>.</para>

	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildworld</userinput></screen>
	</step>

	<step>
	  <para>Use the new compiler residing in <filename
	      class="directory">/usr/obj</filename> to build the new
	    kernel, in order to protect against compiler-kernel
	    mismatches:</para>

	  <screen>&prompt.root; <userinput>make buildkernel</userinput></screen>
	</step>

	<step>
	  <para>Install the new kernel and kernel modules, making it
	    possible to boot with the newly updated kernel:</para>

	  <screen>&prompt.root; <userinput>make installkernel</userinput></screen>
	</step>

	<step>
	  <para>Drop the system into single user mode in order to
	    minimize problems from updating any binaries that are
	    already running.  It also minimizes any problems from
	    running the old world on a new kernel.</para>

	  <screen>&prompt.root; <userinput>shutdown now</userinput></screen>

	  <para>Once in single-user mode, run this command if the
	    system is formatted with UFS:</para>

	  <screen>&prompt.root; <userinput>mount -u /</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput></screen>

	  <para>If the system is instead formatted with ZFS, run these
	    two commands.  This example assumes a zpool name of
	    <literal>zroot</literal>:</para>

	  <screen>&prompt.root; <userinput>zfs set readonly=off zroot</userinput>
&prompt.root; <userinput>zfs mount -a</userinput></screen>
	</step>

	<step>
	  <para>Then, for either filesystem, run:</para>

	  <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
	</step>

	<step>
	  <para>Next, perform some initial configuration file updates
	    in preparation for the new world.  For instance, this step
	    may add new groups or new system accounts 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>

	  <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
	</step>

	<step>
	  <para>Install the new world from <filename
	      class="directory">/usr/obj</filename>.</para>

	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput></screen>
	</step>

	<step>
	  <para>Update any remaining configuration files.</para>

	  <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
	</step>

	<step>
	  <para>Delete any obsolete files.  This is important as they
	    may cause problems if left on the disk.</para>

	  <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
	</step>

	<step>
	  <para>A full reboot is now needed to load the new kernel and
	    new world with the new configuration files.</para>

	  <screen>&prompt.root; <userinput>reboot</userinput></screen>
	</step>

	<step>
	  <para>Make sure that all installed ports have first been
	    rebuilt before old libraries are removed using the
	    instructions in  <xref linkend="ports-upgrading"/>.  When
	    finished, remove any obsolete libraries to avoid conflicts
	    with newer ones.</para>

	  <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
	</step>
      </procedure>
    </sect2>

    <sect2 xml:id="src-updating">
      <title>Check <filename>/etc/make.conf</filename></title>

      <indexterm>
	<primary><filename>make.conf</filename></primary>
      </indexterm>

      <para>The following sections clearly describe each step,
	  especially when using a custom kernel configuration.</para>
      <para>Available &man.make.1; options are shown in
	&man.make.conf.5; and
	<filename>/usr/share/examples/etc/make.conf</filename>.  These
	settings can be added to <filename>/etc/make.conf</filename>
	to control the way &man.make.1; runs and how it builds
	programs.  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
	of the operating system from source code.  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
	the many options available for this file are shown in
	&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 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>

	<para>It is a good idea to save the output from running
	  &man.make.1; to a file.  If something goes wrong, a copy of
	  the error message can be posted to one of the &os; mailing
	  lists.</para>

	<para>The easiest way to do this is to use &man.script.1;
	  with a parameter that specifies the name of the file to save
	  all output to.  Run this command immediately before
	  rebuilding the world, and then type
	  <userinput>exit</userinput> when the process has
	  finished:</para>

	<screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput>
Script started, output file is /var/tmp/mw.out
&prompt.root; <userinput>make TARGET</userinput>
<emphasis>&hellip; compile, compile, compile &hellip;</emphasis>
&prompt.root; <userinput>exit</userinput>
Script done, &hellip;</screen>

	<para><emphasis>Do not</emphasis> save the output in
	  <filename>/tmp</filename> as this directory may be cleared
	  at next reboot.  A better place to save the file is
	  <filename>/var/tmp</filename> or in
	  <systemitem class="username">root</systemitem>'s home
	  directory.</para>

	<para>While in <filename>/usr/src</filename>
	  type:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>

	<indexterm>
	  <primary><command>make</command></primary>
	</indexterm>

	<para>To rebuild the world, use &man.make.1;.  This command
	  reads instructions from the <filename>Makefile</filename>,
	  which describes how the programs that comprise &os; should
	  be built and the order in which they should be built.</para>

	<para>The general format of the command is as follows:</para>

	<screen>&prompt.root; <userinput>make -x -DVARIABLE target</userinput></screen>

	<para>In this example,
	  <option>-<replaceable>x</replaceable></option> is an option
	  passed to &man.make.1;.  Refer to &man.make.1; for an
	  examples of available options.</para>

	<para><option>-D<replaceable>VARIABLE</replaceable></option>
	  passes a variable to the <filename>Makefile</filename>.  The
	  behavior of the <filename>Makefile</filename> is controlled
	  by these variables.  These are the same variables as are set
	  in <filename>/etc/make.conf</filename>, and this provides
	  another way of setting them.  For example:</para>

	<screen>&prompt.root; <userinput>make -DNO_PROFILE target</userinput></screen>

	<para>is another way of specifying that profiled libraries
	  should not be built, and corresponds with the</para>

	<programlisting>NO_PROFILE=    true     #    Avoid compiling profiled libraries</programlisting>

	<para>line in <filename>/etc/make.conf</filename>.</para>

	<para><replaceable>target</replaceable> tells &man.make.1;
	  what to do.  Each <filename>Makefile</filename> defines a
	  number of different <quote>targets</quote>, and the choice
	  of target determines what happens.</para>

	<para>Some targets listed in the
	  <filename>Makefile</filename> are used by the build process
	  to break out the steps necessary to rebuild the system into
	  a number of sub-steps.</para>

	<para>Most of the time, no parameters need to be passed to
	  &man.make.1; and the command looks like this:</para>

	<screen>&prompt.root; <userinput>make target</userinput></screen>

	<para>Where <replaceable>target</replaceable> is one of many
	  build options.  The first target should always be
	  <varname>buildworld</varname>.</para>

	<para>As the names imply,
	  <buildtarget>buildworld</buildtarget> builds a complete new
	  tree under <filename>/usr/obj</filename> and
	  <buildtarget>installworld</buildtarget> installs this tree
	  on the current machine.</para>

	<para>Having separate options is useful for two reasons.
	  First, it allows for a <quote>self hosted</quote> build that
	  does not affect any components of a running system.  Because
	  of this, <buildtarget>buildworld</buildtarget> can be run on
	  a machine running in multi-user mode with no fear of
	  ill-effects.  It is still recommended that
	  <buildtarget>installworld</buildtarget> be run in part in
	  single user mode, though.</para>

	<para>Secondly, it allows NFS mounts to be used to upgrade
	  multiple machines on a network.  If order to upgrade three
	  machines, <systemitem>A</systemitem>,
	  <systemitem>B</systemitem> and <systemitem>C</systemitem>,
	  run <command>make buildworld</command> and
	  <command>make installworld</command> on
	  <systemitem>A</systemitem>.  <systemitem>B</systemitem> and
	  <systemitem>C</systemitem> should then NFS mount
	  <filename>/usr/src</filename> and
	  <filename>/usr/obj</filename> from
	  <systemitem>A</systemitem>, and run
	  <command>make installworld</command> to install the results
	  of the build on <systemitem>B</systemitem> and
	  <systemitem>C</systemitem>.</para>

	<para>Although the <buildtarget>world</buildtarget> target
	  still exists, users are strongly encouraged not to use
	  it.</para>

	<para>Instead, run:</para>

	<screen>&prompt.root; <userinput>make buildworld</userinput></screen>

	<para>It is possible to specify <option>-j</option> which
	  will cause <command>make</command> to spawn several
	  simultaneous processes.  This is most useful on multi-CPU
	  machines.  However, since much of the compiling process is
	  I/O bound rather than CPU bound, it is also useful on single
	  CPU machines.</para>

	<para>On a typical single-CPU machine, run:</para>

	<screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>

	<para>&man.make.1; will then have up to 4 processes running at
	  any one time.  Empirical evidence posted to the mailing
	  lists shows this generally gives the best performance
	  benefit.</para>

	<para>On a multi-CPU machine using an SMP configured kernel,
	  try values between 6 and 10 and see how they speed things
	  up.</para>

	<indexterm>
	  <primary>rebuilding <quote>world</quote></primary>
	  <secondary>timings</secondary>
	</indexterm>

	<para>Many factors influence the build time, but fairly recent
	  machines may only take a one or two hours to build the
	  &os.stable; tree, with no tricks or shortcuts used during
	  the process.  A &os.current; tree will take somewhat
	  longer.</para>
    </sect2>

    <sect2 xml:id="new-kernel">
      <title>Compile and Install a New Kernel</title>

      <indexterm>
	<primary>kernel</primary>
	<secondary>compiling</secondary>
      </indexterm>

      <para>To take full advantage of the new system, recompile the
	kernel.  This is practically a necessity, as certain memory
	structures may have changed, and programs like &man.ps.1; and
	&man.top.1; will fail to work until the kernel and source code
	versions are the same.</para>

      <para>The simplest, safest way to do this is to build and
	install a kernel based on <filename>GENERIC</filename>.  While
	<filename>GENERIC</filename> may not have all the necessary
	devices for the system, it should contain everything necessary
	to boot the system back to single user mode.  This is a good
	test that the new system works properly.  After booting from
	<filename>GENERIC</filename> and verifying that the system
	works, a new kernel can be built based on a custom kernel
	configuration file.</para>

      <para>On &os; it is important to
	<link linkend="make-buildworld">build world</link> before
	building a new kernel.</para>

      <note>
	<para>To build a custom kernel with an existing customized
	  configuration file, use
	  <literal>KERNCONF=MYKERNEL</literal>:</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildkernel KERNCONF=MYKERNEL</userinput>
&prompt.root; <userinput>make installkernel KERNCONF=MYKERNEL</userinput></screen>

      </note>

      <para>If <varname>kern.securelevel</varname> has been raised
	above 1 <emphasis>and</emphasis> <literal>noschg</literal> or
	similar flags have been set on the kernel binary, drop into
	single user mode to use
	<buildtarget>installkernel</buildtarget>.  Otherwise, both
	these commands can be run from multi user mode without
	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
	<xref linkend="makeworld-singleuser"/>.</para>
    </sect2>

    <sect2 xml:id="make-installworld">
      <title>Install the New System Binaries</title>

      <para>Next, use <buildtarget>installworld</buildtarget> to
	install the new system binaries:</para>

      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput></screen>

      <note>
	<para>If variables were specified to
	  <command>make buildworld</command>, specify the same
	  variables to <command>make installworld</command>.  However,
	  <option>-j</option> must never be used with
	  <buildtarget>installworld</buildtarget>.</para>

	<para>For example, if you ran:</para>

	<screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen>

	<para>install the results with:</para>

	<screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>

	<para>otherwise, the command will try to install profiled
	  libraries that were not built during the
	  <command>make buildworld</command> phase.</para>
      </note>
    </sect2>

    <sect2 xml:id="post-installworld-updates">
      <title>Update Files Not Updated by
	<command>make installworld</command></title>

      <para>Remaking the world will not update certain directories,
	such as <filename>/etc</filename>,
	<filename>/var</filename> and
	<filename>/usr</filename>, with
	new or changed configuration files.</para>

      <para>The simplest way to update the files in these directories
	is to use &man.mergemaster.8;.  Be sure to first make a backup
	of <filename>/etc</filename> in case anything goes
	wrong.</para>

      <sect3 xml:id="mergemaster">
	<info>
	  <title><command>mergemaster</command></title>

	  <authorgroup>
	    <author>
	      <personname>
		<firstname>Tom</firstname>
		<surname>Rhodes</surname>
	      </personname>
	      <contrib>Contributed by </contrib>
	    </author>
	  </authorgroup>
	</info>

	<indexterm>
	  <primary>
	    <command>mergemaster</command>
	  </primary>
	</indexterm>

	<para>&man.mergemaster.8; is a Bourne script to aid in
	  determining the differences between the configuration files
	  in <filename>/etc</filename>, and the configuration files in
	  the source tree <filename>/usr/src/etc</filename>.  This is
	  the recommended solution for keeping the system
	  configuration files up to date with those located in the
	  source tree.</para>

	<para>To begin, type <command>mergemaster</command> and it
	  will build a temporary root environment, from
	  <filename>/</filename> down, and populate it with various
	  system configuration files.  Those files are then compared
	  to the ones currently installed in the system.  Files that
	  differ will be shown in &man.diff.1; format, with the
	  <option>+</option> sign representing added or modified
	  lines, and <option>-</option> representing lines that will
	  be either removed completely, or replaced with a new file.
	  Refer to &man.diff.1; for more information about the
	  &man.diff.1; syntax and how file differences are
	  shown.</para>

	<para>&man.mergemaster.8; will then display each file that
	  differs, and present the options of either deleting the new
	  file, referred to as the temporary file, installing the
	  temporary file in its unmodified state, merging the
	  temporary file with the currently installed file, or viewing
	  the &man.diff.1; results again.</para>

	<para>Choosing to delete the temporary file will tell
	  &man.mergemaster.8; to keep the current file unchanged and
	  to delete the new version.  This option is not recommended,
	  unless there is no reason to change the current file.  To
	  get help at any time, type <keycap>?</keycap> at the
	  &man.mergemaster.8; prompt.  If the user chooses to skip a
	  file, it will be presented again after all other files have
	  been dealt with.</para>

	<para>Choosing to install the unmodified temporary file will
	  replace the current file with the new one.  For most
	  unmodified files, this is the best option.</para>

	<para>Choosing to merge the file will present a text editor,
	  and the contents of both files.  The files can be merged
	  by reviewing both files side by side on the screen, and
	  choosing parts from both to create a finished product.  When
	  the files are compared side by side, <keycap>l</keycap>
	  selects the left contents and <keycap>r</keycap> selects
	  contents from the right.  The final output will be a file
	  consisting of both parts, which can then be installed.  This
	  option is customarily used for files where settings have
	  been modified by the user.</para>

	<para>Choosing to view the &man.diff.1; results again will
	  display the file differences just like &man.mergemaster.8;
	  did before prompting an option.</para>

	<para>After &man.mergemaster.8; is done with the system files,
	  it will prompt for other options.  &man.mergemaster.8; may
	  prompt to rebuild the password file and will finish up with
	  an option to remove left-over temporary files.</para>
      </sect3>

      <sect3>
	<title>Manual Update</title>

	<para>To perform the update manually instead, do not just copy
	  over the files from
	  <filename>/usr/src/etc</filename> to
	  <filename>/etc</filename> and expect it to
	  work.  Some files must be <quote>installed</quote> first as
	  <filename>/usr/src/etc</filename>
	  <emphasis>is not</emphasis> a copy of what
	  <filename>/etc</filename> should look
	  like.  In addition, some files that should be in
	  <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>

	<warning>
	  <title>Backup Your Existing
	    <filename>/etc</filename></title>

	  <para>It is recommended to first copy the existing
	    <filename>/etc</filename> somewhere
	    safe, like so:</para>

	  <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>

	  <para>where <option>-R</option> does a recursive copy and
	    <option>-p</option> preserves times and the ownerships on
	    files.</para>
	</warning>

	<para>Build a temporary set of directories into which the new
	  <filename>/etc</filename> and other files
	  can be installed:</para>

	<screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput>
&prompt.root; <userinput>cd /usr/src/etc</userinput>
&prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen>

	<para>This will build the necessary directory structure and
	  install the files.  A lot of the subdirectories that have
	  been created under <filename>/var/tmp/root</filename> are
	  empty and should be deleted.  The simplest way to do this is
	  to:</para>

	<screen>&prompt.root; <userinput>cd /var/tmp/root</userinput>
&prompt.root; <userinput>find -d . -type d | xargs rmdir 2&gt;/dev/null</userinput></screen>

	<para>This will remove all empty directories while redirecting
	  standard error to <filename>/dev/null</filename> to prevent
	  the warnings about the directories that are not
	  empty.</para>

	<para><filename>/var/tmp/root</filename> now
	  contains all the files that should be placed in appropriate
	  locations below <filename>/</filename>.
	  Go through each of these files, determining how they differ
	  from the system's existing files.</para>

	<para>Some of the files installed into
	  <filename>/var/tmp/root</filename> have a leading
	  <quote>.</quote>.  Make sure to use
	  <command>ls -a</command> in order to catch them.</para>

	<para>The simplest way to compare files is to use
	  &man.diff.1;:</para>

	<screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen>

	<para>This command will show the differences between the
	  existing <filename>/etc/shells</filename> and the new
	  <filename>/var/tmp/root/etc/shells</filename>.  Review the
	  differences to decide whether to merge in custom changes
	  or to replace the existing file with the new one.</para>

	<tip>
	  <title>Name the New Root Directory
	    (<filename>/var/tmp/root</filename>)
	    with a Time Stamp, so You Can Easily Compare Differences
	    Between Versions</title>

	  <para>Frequently rebuilding world entails frequently
	    updating <filename>/etc</filename>
	    as well, which can be a bit of a chore.</para>

	  <para>To speed up this process, use the following
	    procedure to keep a copy of the last set of changed files
	    that were merged into <filename>/etc</filename>.</para>

	  <procedure>
	    <step>
	      <para>Make the world as normal.  When updating
		<filename>/etc</filename> and the
		other directories, give the target directory a name
		based on the current date:</para>

	      <screen>&prompt.root; <userinput>mkdir /var/tmp/root-20130214</userinput>
&prompt.root; <userinput>cd /usr/src/etc</userinput>
&prompt.root; <userinput>make DESTDIR=/var/tmp/root-20130214 \
    distrib-dirs distribution</userinput></screen>
	    </step>

	    <step>
	      <para>Merge in the changes from this directory as
		outlined above.  <emphasis>Do not</emphasis> remove
		the <filename>/var/tmp/root-20130214</filename>
		directory when you have finished.</para>
	    </step>

	    <step>
	      <para>After downloading the latest version of the
		source and remaking it, follow step 1.  Create a new
		directory, which reflects the new date.  This example
		uses
		<filename>/var/tmp/root-20130221</filename>.</para>
	    </step>

	    <step>
	      <para>Use &man.diff.1; to see the differences that have
		been made in the intervening week by creating a
		recursive diff between the two directories:</para>

	      <screen>&prompt.root; <userinput>cd /var/tmp</userinput>
&prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen>

	      <para>Typically, this will be a much smaller set of
		differences than those between
		<filename>/var/tmp/root-20130221/etc</filename> and
		<filename>/etc</filename>.  Because the set of
		differences is smaller, it is easier to migrate those
		changes across into <filename>/etc</filename>.</para>
	    </step>

	    <step>
	      <para>When finished, remove the older of the two
		<filename>/var/tmp/root-*</filename>
		directories:</para>

	      <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen>
	    </step>

	    <step>
	      <para>Repeat this process whenever merging
		in changes to <filename>/etc</filename>.</para>
	    </step>
	  </procedure>

	  <para>Use &man.date.1; to automate the generation of the
	    directory names:</para>

	  <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
	</tip>
      </sect3>
    </sect2>

    <sect2 xml:id="make-delete-old">
      <info>
	<title>Deleting Obsolete Files and Directories</title>

	<authorgroup>
	  <author>
	    <personname>
	      <firstname>Anton</firstname>
	      <surname>Shterenlikht</surname>
	    </personname>
	    <contrib>Based on notes provided by </contrib>
	  </author>
	</authorgroup>
      </info>

      <indexterm>
	<primary>Deleting obsolete files and directories</primary>
      </indexterm>

      <para>As a part of the &os; development lifecycle, files and
	their contents occasionally become obsolete.  This may be
	because functionality is implemented elsewhere, the version
	number of the library has changed, or it was removed from the
	system entirely.  This includes old files, libraries, and
	directories, which should be removed when updating the system.
	The benefit is that the system is not cluttered with old files
	which take up unnecessary space on the storage and backup
	media.  Additionally, if the old library has a security or
	stability issue, the system should be updated to the newer
	library to keep it safe and to prevent crashes caused by the
	old library.  Files, directories, and libraries which are
	considered obsolete are listed in
	<filename>/usr/src/ObsoleteFiles.inc</filename>.  The
	following instructions should be used to remove obsolete files
	during the system upgrade process.</para>

      <para>After the
	<command>make installworld</command>
	and the subsequent <command>mergemaster</command> have
	finished successfully, check for obsolete files and libraries
	as follows:</para>

      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make check-old</userinput></screen>

      <para>If any obsolete files are found, they can be deleted using
	the following command:</para>

      <screen>&prompt.root; <userinput>make delete-old</userinput></screen>

      <tip>
	<para>Refer to <filename>/usr/src/Makefile</filename>
	  for more targets of interest.</para>
      </tip>

      <para>A prompt is displayed before deleting each obsolete file.
	To skip the prompt and let the system remove these files
	automatically, use
	<varname>BATCH_DELETE_OLD_FILES</varname>:</para>

      <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>

      <para>The same goal can be achieved by piping these commands
	through <command>yes</command>:</para>

      <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>

      <warning>
	<title>Warning</title>

	<para>Deleting obsolete files will break applications that
	  still depend on those obsolete files.  This is especially
	  true for old libraries.  In most cases, the programs, ports,
	  or libraries that used the old library need to be recompiled
	  before <command>make
	    delete-old-libs</command> is
	  executed.</para>
      </warning>

      <para>Utilities for checking shared library dependencies are
	available from the Ports Collection in
	<package>sysutils/libchk</package> or
	<package>sysutils/bsdadminscripts</package>.</para>

      <para>Obsolete shared libraries can conflict with newer
	libraries, causing messages like these:</para>

      <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>

      <para>To solve these problems, determine which port installed
	the library:</para>

      <screen>&prompt.root; <userinput>pkg which /usr/local/lib/libtiff.so</userinput>
  /usr/local/lib/libtiff.so was installed by package tiff-3.9.4
  &prompt.root; <userinput>pkg which /usr/local/lib/libXext.so</userinput>
  /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen>

      <para>Then deinstall, rebuild, and reinstall the port.
	<package>ports-mgmt/portmaster</package> can
	be used to automate this process.  After all ports are rebuilt
	and no longer use the old libraries, delete the old libraries
	using the following command:</para>

      <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>

      <para>You should now have successfully upgraded the &os;
	system.  Congratulations.</para>

      <para>If things went slightly wrong, it is easy to rebuild a
	particular piece of the system.  For example, if
	<filename>/etc/magic</filename> was accidentally deleted as
	part of the upgrade or merge of <filename>/etc</filename>,
	&man.file.1; will stop working.  To fix this, run:</para>

      <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
&prompt.root; <userinput>make all install</userinput></screen>
    </sect2>

    <sect2 xml:id="updating-questions">
      <title>Questions</title>

      <qandaset>
	<qandaentry>
	  <question>
	    <para>Do I need to re-make the world for every
	      change?</para>
	  </question>

	  <answer>
	    <para>There is no easy answer, as it depends on the nature
	      of the change.  For example, if running
	      <application>svn</application> only shows the following
	      files as being updated:</para>

	    <screen><filename>src/games/cribbage/instr.c</filename>
<filename>src/games/sail/pl_main.c</filename>
<filename>src/release/sysinstall/config.c</filename>
<filename>src/release/sysinstall/media.c</filename>
<filename>src/share/mk/bsd.port.mk</filename></screen>

	    <para>it probably is not worth rebuilding the entire
	      world.  Instead, go into the appropriate sub-directories
	      and run <command>make all install</command>.  But if
	      something major changed, such as
	      <filename>src/lib/libc/stdlib</filename>, either
	      re-make world, or at least those parts of it that are
	      statically linked.</para>

	    <para>At the end of the day, it is your call.  Some users
	      re-make the world every fortnight and let changes
	      accumulate over that fortnight.  Others only re-make
	      those things that have changed and are careful to spot
	      all the dependencies.</para>

	    <para>It all depends on how often a user wants to upgrade
	      and whether they are tracking &os.stable; or
	      &os.current;.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>My compile failed with lots of
	      signal 11<indexterm>
		<primary>signal 11</primary>
	      </indexterm>
	      (or other signal number) errors.  What happened?</para>
	  </question>

	  <answer>
	    <para>This normally indicates hardware problems.
	      (Re)making world is an effective way to stress test
	      hardware, and will frequently throw up memory
	      problems which normally manifest themselves as the
	      compiler mysteriously aborts.</para>

	    <para>A sure indicator of this occurs when
	      <application>make</application> is restarted and it
	      dies at a different point in the process.</para>

	    <para>To resolve this error, start swapping around the
	      components in the machine to determine which one is
	      failing.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>Can <filename>/usr/obj</filename>
	      be removed when finished?</para>
	  </question>

	  <answer>
	    <para>The short answer is yes.</para>

	    <para><filename>/usr/obj</filename>
	      contains all the object files that were produced during
	      the compilation phase.  Normally, one of the first steps
	      in the <command>make buildworld</command> process is to
	      remove this directory and start afresh.  Keeping
	      <filename>/usr/obj</filename> around
	      when finished makes little sense, and its removal frees
	      up a approximately 2&nbsp;GB of disk space.</para>

	    <para>Advances users can instruct
	      <command>make buildworld</command> to skip this step.
	      This speeds up subsequent builds, since most of the
	      sources will not need to be recompiled.  The flip side
	      is that subtle dependency problems can creep in, causing
	      the build to fail in odd ways.  This frequently
	      generates noise on the &os; mailing lists, when one
	      person complains that their build has failed, not
	      realizing that it is because they have tried to cut
	      corners.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>Can interrupted builds be resumed?</para>
	  </question>

	  <answer>
	    <para>This depends on how far into the process the
	      problem occurs.</para>

	    <para>In general, <command>make buildworld</command>
	      builds new copies of essential tools, such as
	      &man.gcc.1; and &man.make.1;, and the system libraries.
	      These tools and libraries are then installed, used to
	      rebuild themselves, and are installed again.  The entire
	      system, including regular user programs such as
	      &man.ls.1; or &man.grep.1;, is then rebuilt with the new
	      system files.</para>

	    <para>During the last stage, it is fairly safe to:</para>

	    <screen><emphasis>&hellip; fix the problem &hellip;</emphasis>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen>

	    <para>This will not undo the work of the previous
	      <command>make buildworld</command>.</para>

	    <para>If you see the message:</para>

	    <screen>--------------------------------------------------------------
Building everything..
--------------------------------------------------------------</screen>

	    <para>in the <command>make buildworld</command> output,
	      it is probably fairly safe to do so.</para>

	    <para>If that message is not displayed, or you are not
	      sure, it is always better to be safe than sorry, and
	      restart the build from scratch.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>How can I speed up making the world?</para>
	  </question>

	  <answer>
	    <itemizedlist>
	      <listitem>
		<para>Run it in single user mode.</para>
	      </listitem>

	      <listitem>
		<para>Put <filename>/usr/src</filename> and
		  <filename>/usr/obj</filename>
		  on separate file systems held on separate disks.  If
		  possible, put these disks on separate disk
		  controllers.</para>
	      </listitem>

	      <listitem>
		<para>Alternately, put these file systems across
		  multiple disks using &man.ccd.4;.</para>
	      </listitem>

	      <listitem>
		<para>Turn off profiling by setting
		  <quote>NO_PROFILE=true</quote> in
		  <filename>/etc/make.conf</filename>.</para>
	      </listitem>

	      <listitem>
		<para>Pass
		  <option>-j<replaceable>n</replaceable></option>
		  to &man.make.1; to run multiple processes in
		  parallel.  This usually helps on both single and
		  multi processor machines.</para>
	      </listitem>

	      <listitem>
		<para>The file system holding
		  <filename>/usr/src</filename> can
		  be mounted or remounted with
		  <option>noatime</option>.
		  This prevents the file system from recording the
		  file access time which is probably not
		  needed.</para>

		<screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen>

		<warning>
		  <para>This example assumes
		    <filename>/usr/src</filename> is on its own file
		    system.  If it is part of
		    <filename>/usr</filename>, then use that file
		    system mount point instead.</para>
		</warning>
	      </listitem>

	      <listitem>
		<para>The file system holding
		  <filename>/usr/obj</filename> can be mounted or
		  remounted with <option>async</option> so that disk
		  writes happen asynchronously.  The write completes
		  immediately, and the data is written to the disk a
		  few seconds later.  This allows writes to be
		  clustered together, and can provide a dramatic
		  performance boost.</para>

		<warning>
		  <para>Keep in mind that this option makes the file
		    system more fragile.  With this option, there is
		    an increased chance that, should power fail, the
		    file system will be in an unrecoverable state when
		    the machine restarts.</para>

		  <para>If <filename>/usr/obj</filename> is the
		    only directory on this file system, this is not a
		    problem.  If you have other, valuable data on the
		    same file system, ensure that there are verified
		    backups before enabling this option.</para>
		</warning>

		<screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen>

		<warning>
		  <para>If <filename>/usr/obj</filename> is
		    not on its own file system, replace it in the
		    example with the name of the appropriate mount
		    point.</para>
		</warning>
	      </listitem>
	    </itemizedlist>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>What do I do if something goes wrong?</para>
	  </question>

	  <answer>
	    <para>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>
&prompt.root; <userinput>rm -rf /usr/obj/usr</userinput>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make cleandir</userinput>
&prompt.root; <userinput>make cleandir</userinput></screen>

	    <para>Yes, <command>make cleandir</command> really should
	      be run twice.</para>

	    <para>Then, restart the whole process, starting
	      with <command>make buildworld</command>.</para>

	    <para>If problems persist, send the error and the
	      output of <command>uname -a</command> to &a.questions;.
	      Be prepared to answer other questions about the
	      setup!</para>
	  </answer>
	</qandaentry>
      </qandaset>
    </sect2>
  </sect1>

  <sect1 xml:id="small-lan">
    <info>
      <title>Tracking for Multiple Machines</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Mike</firstname>
	    <surname>Meyer</surname>
	  </personname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </info>

    <indexterm>
      <primary>NFS</primary>
      <secondary>installing multiple machines</secondary>
    </indexterm>

    <para>When multiple machines need to track the same source tree,
      it is a waste of disk space, network bandwidth, and CPU cycles
      to have each system download the sources and rebuild everything.
      The solution is to have one machine do most of the work, while
      the rest of the machines mount that work via NFS.  This section
      outlines a method of doing so.</para>

    <sect2 xml:id="small-lan-preliminaries">
      <title>Preliminaries</title>

      <para>First, identify a set of machines which will run the
	same set of binaries, known as a <emphasis>build
	  set</emphasis>.  Each machine can have a custom kernel, but
	will run the same userland binaries.  From that set, choose a
	machine to be the <emphasis>build machine</emphasis> that the
	world and kernel are built on.  Ideally, this is a fast
	machine that has sufficient spare CPU to run
	<command>make buildworld</command> and
	<command>make buildkernel</command>.  Select a machine to be
	the <emphasis>test machine</emphasis>, which will test
	software updates before they are put into production.  This
	<emphasis>must</emphasis> be a machine that can afford to be
	down for an extended period of time.  It can be the build
	machine, but need not be.</para>

      <para>All the machines in this build set need to mount
	<filename>/usr/obj</filename> and
	<filename>/usr/src</filename> from the same
	machine, and at the same point.  Ideally, those directories
	are on two different drives on the build machine, but they can
	be NFS mounted on that machine as well.  For multiple
	build sets, <filename>/usr/src</filename>
	should be on one build machine, and NFS mounted on the
	rest.</para>

      <para>Finally, ensure that <filename>/etc/make.conf</filename>
	and <filename>/etc/src.conf</filename> on all the machines in
	the build set agree with the build machine.  That means that
	the build machine must build all the parts of the base system
	that any machine in the build set is going to install.  Also,
	each build machine should have its kernel name set with
	<varname>KERNCONF</varname> in
	<filename>/etc/make.conf</filename>, and the build machine
	should list them all in <varname>KERNCONF</varname>, listing
	its own kernel first.  The build machine must have the kernel
	configuration files for each machine in
	<filename>/usr/src/sys/arch/conf</filename>
	if it is going to build their kernels.</para>
    </sect2>

    <sect2 xml:id="small-lan-base-system">
      <title>The Base System</title>

      <para>On the build machine, build the kernel and world as
	described in <xref linkend="make-buildworld"/>, but do
	not install anything.  After the build has finished, go to the
	test machine, and install the built kernel.  If this machine
	mounts <filename>/usr/src</filename> and
	<filename>/usr/obj</filename> via NFS,
	enable the network and mount these directories after rebooting
	to single user mode.  The easiest way to do this is to boot to
	multi-user, then run <command>shutdown now</command> to go to
	single user mode.  Once there, install the new kernel and
	world and run <command>mergemaster</command> as usual.  When
	done, reboot to return to normal multi-user operations for
	this machine.</para>

      <para>After verifying that everything on the test machine is
	working properly, use the same procedure to install the new
	software on each of the other machines in the build
	set.</para>
    </sect2>

    <sect2 xml:id="small-lan-ports">
      <title>Ports</title>

      <para>The same ideas can be used for the ports tree.  The first
	critical step is to mount <filename>/usr/ports</filename> from
	the same machine to all the machines in the build set.  Then,
	configure <filename>/etc/make.conf</filename> properly to
	share distfiles.  Set <varname>DISTDIR</varname> to a common
	shared directory that is writable by whichever user
	<systemitem class="username">root</systemitem> is mapped to by
	the NFS mounts.  Each machine should set
	<varname>WRKDIRPREFIX</varname> to a local build directory.
	Finally, if the system is to build and distribute packages,
	set <varname>PACKAGES</varname> to a directory similar to
	<varname>DISTDIR</varname>.</para>
    </sect2>
  </sect1>
</chapter>