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> or
	  <application>Subversion</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>svnlite</command> is used to
	obtain and update &os; sources.  Optionally, the
	<package>devel/subversion</package> port or
	package may be used.</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="https://www.FreeBSD.org/security/">https://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="https://www.FreeBSD.org/releases/">https://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 &man.mergemaster.8; 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>Applying Security Patches</title>

      <para>The process of applying &os; security patches has been
	simplified, allowing an administrator to keep a system fully
	patched using <command>freebsd-update</command>.  More
	information about &os; security advisories can be found in
	<xref linkend="security-advisories"/>.</para>

      <para>&os; security patches may be downloaded and installed
	using the following commands.  The first command will
	determine if any outstanding patches are available, and if so,
	will list the files that will be modifed if the patches are
	applied.  The second command will apply the patches.</para>

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

      <para>If the update applies any kernel patches, the system will
	need a reboot in order to boot into the patched kernel.  If
	the patch was applied to any running binaries, the affected
	applications should be restarted so that the patched version
	of the binary is used.</para>

      <note>
	<para>Usually, the user needs to be prepared to reboot the
	  system.  To know if a reboot is required by a kernel update,
	  execute the commands <command>freebsd-version -k</command>
	  and <command>uname -r</command> and if it differs a reboot
	  is required.</para>
      </note>

      <para>The system can be configured to automatically check for
	updates once every day by adding this entry to
	<filename>/etc/crontab</filename>:</para>

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

      <para>If patches exist, they will automatically be downloaded
	but will not be applied.  The <systemitem
	  class="username">root</systemitem> user will be sent an
	email so that the patches may be reviewed and manually
	installed with
	<command>freebsd-update install</command>.</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>
Uninstalling updates... done.</screen>

      <para>Again, the system should be restarted if the kernel or any
	kernel modules were modified and any affected binaries should
	be restarted.</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 updates.  The default kernel name
	is <emphasis>GENERIC</emphasis>.  The &man.uname.1; command
	may be used to verify its installation.</para>

      <note>
	<para>Always keep a copy of the <filename>GENERIC</filename>
	  kernel in <filename>/boot/GENERIC</filename>.  It will be
	  helpful in diagnosing a variety of problems and in
	  performing version upgrades.  Refer to <xref
	    linkend="freebsd-update-custom-kernel-9x"/> for
	  instructions on how to get a copy of the
	  <filename>GENERIC</filename> kernel.</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>

      <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
	<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 <command>uname</command> 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>
    </sect2>

    <sect2 xml:id="freebsdupdate-upgrade">
      <title>Performing 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
	<firstterm>minor version</firstterm> upgrades.
	<firstterm>Major version</firstterm> upgrades occur when &os;
	is upgraded from one major version to another, like from
	&os;&nbsp;9.X to &os;&nbsp;10.X.  Both types of upgrades can
	be performed by providing <command>freebsd-update</command>
	with a release version target.</para>

      <note>
	<para>If the system is running a custom kernel, make sure that
	  a copy of the <filename>GENERIC</filename> kernel exists in
	  <filename>/boot/GENERIC</filename> before starting the
	  upgrade.  Refer to <xref
	    linkend="freebsd-update-custom-kernel-9x"/> for
	  instructions on how to get a copy of the
	  <filename>GENERIC</filename> kernel.</para>
      </note>

      <para>The following command, when run on a &os;&nbsp;9.0 system,
	will upgrade it to &os;&nbsp;9.1:</para>

       <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)? <userinput>y</userinput></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.  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.
	Since the state of the process has been saved,
	<command>freebsd-update</command> will not start from the
	beginning, but will instead move on to the next phase and
	remove all old shared libraries and object files.</para>

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

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

      <para>The upgrade is now complete.  If this was a major version
	upgrade, reinstall all ports and packages as described in
	<xref linkend="freebsdupdate-portsrebuild"/>.</para>

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

	<para>Before using <command>freebsd-update</command>, ensure
	  that a copy of the <filename>GENERIC</filename> kernel
	  exists in <filename>/boot/GENERIC</filename>.  If a custom
	  kernel has only been built once, the kernel in
	  <filename>/boot/kernel.old</filename> is the
	  <literal>GENERIC</literal> kernel.  Simply rename this
	  directory to <filename>/boot/kernel</filename>.</para>

	<para>If a custom kernel has been built more than once or if
	  it is unknown how many times the custom kernel has been
	  built, obtain a copy of the <literal>GENERIC</literal>
	  kernel that matches the current version of the operating
	  system.  If physical access to the system is available, a
	  copy of the <literal>GENERIC</literal> kernel can be
	  installed from the installation media:</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>

	<para>Alternately, 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>

	<para>Rebooting into the <filename>GENERIC</filename> kernel
	  is not required as <command>freebsd-update</command> only
	  needs <filename>/boot/GENERIC</filename> to exist.</para>
      </sect3>

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

	<para>Generally, installed applications will continue to work
	  without problems after minor version upgrades.  Major
	  versions use different Application Binary Interfaces
	  (<acronym>ABI</acronym>s), which will break most
	  third-party applications.  After a major version upgrade,
	  all installed packages and ports need to be upgraded.
	  Packages can be upgraded using <command>pkg
	    upgrade</command>.  To upgrade installed ports, use a
	  utility such as
	  <package>ports-mgmt/portmaster</package>.</para>

	<para>A forced upgrade of all installed packages will replace
	  the packages with fresh versions from the repository even if
	  the version number has not increased.  This is required
	  because of the ABI version change when upgrading between
	  major versions of &os;.  The forced upgrade can be
	  accomplished by performing:</para>

	<screen>&prompt.root; <userinput>pkg-static upgrade -f</userinput></screen>

	<para>A rebuild of all installed applications can be
	  accomplished with this command:</para>

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

	<para>This command will display the configuration screens for
	  each application that has configurable options and wait for
	  the user to interact with those screens.  To prevent this
	  behavior, and use only the default options, include
	  <option>-G</option> in the above command.</para>

	<para>Once the software upgrades are complete, finish the
	  upgrade process with a final call to
	  <command>freebsd-update</command> in order to tie up all the
	  loose ends in the upgrade process:</para>

	<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 using the instructions in <xref
	    linkend="kernelconfig"/>.</para>

	<para>Reboot the machine into the new &os; version.  The
	  upgrade process is now complete.</para>
      </sect3>
    </sect2>

    <sect2 xml:id="freebsdupdate-system-comparison">
      <title>System State Comparison</title>

      <para>The state of the installed &os; version against a known
	good copy can be tested using
	<command>freebsd-update IDS</command>.  This command evaluates
	the current version of system utilities, libraries, and
	configuration files and can be used as a built-in Intrusion
	Detection System (<acronym>IDS</acronym>).</para>

      <warning>
	<para>This command is not a replacement for a real
	  <acronym>IDS</acronym> such as
	  <package>security/snort</package>.  As
	  <command>freebsd-update</command> stores data on disk, the
	  possibility of tampering is evident.  While this possibility
	  may be reduced using <varname>kern.securelevel</varname> and
	  by storing the <command>freebsd-update</command> data on a
	  read-only file system when not in use, a better solution
	  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.  An alternative method
	  for providing <acronym>IDS</acronym> functionality using a
	  built-in utility is described in <xref
	    linkend="security-ids"/></para>
      </warning>

      <para>To begin the comparison, specify the output file to save
	the results to:</para>

      <screen>&prompt.root; <userinput>freebsd-update IDS &gt;&gt; outfile.ids</userinput></screen>

      <para>The system will now be inspected and a lengthy listing of
	files, along with the <acronym>SHA256</acronym> hash values
	for both the known value in the release and the current
	installation, will be sent to the specified output
	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> will be modified if users
	have been added to the system.  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>
    </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
      is always available on the &os; web site (<link
	xlink:href="&url.base;/doc/">https://www.freebsd.org/doc/</link>),
      it can be handy to have an up-to-date, local copy of the &os;
      website, handbooks, <acronym>FAQ</acronym>, and articles.</para>

    <para>This section describes how to use either source or the &os;
      Ports Collection to keep a local copy of the &os; documentation
      up-to-date.</para>

    <para>For information on editing and submitting corrections to the
      documentation, refer to the &os; Documentation Project Primer
      for New Contributors (<link
	xlink:href="&url.books.fdp-primer;">https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/</link>).</para>

    <sect2 xml:id="updating-installed-documentation">
      <title>Updating Documentation from Source</title>

      <para>Rebuilding the &os; documentation from source requires a
	collection of tools which are not part of the &os; base
	system.  The required tools can be installed from the
	<package>textproc/docproj</package> package or port developed
	by the &os; Documentation Project.</para>

      <para>Once installed, use <application>svnlite</application> to
	fetch a clean copy of the documentation source:</para>

      <screen>&prompt.root; <userinput>svnlite checkout https://svn.FreeBSD.org/doc/head /usr/doc</userinput></screen>

      <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>svnlite update /usr/doc</userinput></screen>

      <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 available languages 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,
	<command>make</command> 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 install clean</userinput></screen>

      <para>An alternative way of updating the documentation is to run
	this command from <filename>/usr/doc</filename> or the desired
	language-specific subdirectory:</para>

      <screen>&prompt.root; <userinput>make update</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>Several options are available to 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
	<command>make</command>.</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>, and <literal>pdf</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>
    </sect2>

    <sect2 xml:id="doc-ports-install-package">
      <info>
	<title>Updating Documentation from 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.  This section describes an
	alternative method which uses the Ports Collection and makes
	it possible to:</para>

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

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

      <para>This method of updating the &os; documentation is
	supported by a set of documentation ports and packages which
	are updated by the &a.doceng; on a monthly basis.  These are
	listed in the &os; Ports&nbsp;Collection, under the docs
	category (<link
	  xlink:href="http://www.freshports.org/docs/">http://www.freshports.org/docs/</link>).</para>

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

      <itemizedlist>
	<listitem>
	  <para>The <package>misc/freebsd-doc-en</package> package or
	    port installs all of the English documentation.</para>
	</listitem>

	<listitem>
	  <para>The <package>misc/freebsd-doc-all</package>
	    meta-package or port installs all documentation in all
	    available languages.</para>
	</listitem>

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

      <para>When binary packages are used, the &os; documentation will
	be installed in all available formats for the given language.
	For example, the following command will install the latest
	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><replaceable>lang</replaceable>-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>

      <para>To specify the format of the documentation, build the port
	instead of installing the package.  For example, to build and
	install the English documentation:</para>

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

      <para>The port provides a configuration menu where the format to
	build and install can be specified.  By default, split
	<acronym>HTML</acronym>, similar to the format used on <uri
	  xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>,
	and <acronym>PDF</acronym> are selected.</para>

      <para>Alternately, several <command>make</command> options can
	be specified when building a documentation port,
	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>.</para>
	  </listitem>
	</varlistentry>

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

	  <listitem>
	    <para>The formatted documentation is saved to a file
	      called <filename>article.pdf</filename> or
	      <filename>book.pdf</filename>.</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>
	  </listitem>
	</varlistentry>
      </variablelist>

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

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

      <para>Documentation packages or ports can be updated using the
	instructions in <xref linkend="ports"/>.  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>
    </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">svnlite</link> is used to check out the
	    -CURRENT code from the <literal>head</literal> branch of
	    one of the Subversion mirror sites listed in
	    <xref linkend="svn-mirrors"/>.</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
	    <xref linkend="makeworld"/>.
	    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/">www.freebsd.org/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 listed at <link
	      xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>.</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 <xref
	      linkend="makeworld"/>.  Read the &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="makeworld">
    <title xml:id="updating-src">Updating &os; from Source</title>

    <para>Updating &os; by compiling from source offers several
      advantages over binary updates.  Code can be built with options
      to take advantage of specific hardware.  Parts of the base
      system can be built with non-default settings, or left out
      entirely where they are not needed or desired.  The build
      process takes longer to update a system than just installing
      binary updates, but allows complete customization to produce
      a tailored version of &os;.</para>

    <sect2 xml:id="updating-src-quick-start">
      <title>Quick Start</title>

      <para>This is a quick reference for the typical steps used to
	update &os; by building from source.  Later sections describe
	the process in more detail.</para>

      <procedure>
	<step>
	  <title>Update and Build</title>

	  <screen>&prompt.root; <userinput>svnlite update /usr/src</userinput>  <co xml:id="updating-src-qs-svnup"/>
<emphasis>check <filename>/usr/src/UPDATING</filename></emphasis>  <co xml:id="updating-src-qs-review-updating"/>
&prompt.root; <userinput>cd /usr/src</userinput>          <co xml:id="updating-src-qs-cd"/>
&prompt.root; <userinput>make -j<replaceable>4</replaceable> buildworld</userinput>  <co xml:id="updating-src-qs-buildworld"/>
&prompt.root; <userinput>make -j<replaceable>4</replaceable> kernel</userinput>      <co xml:id="updating-src-qs-kernel"/>
&prompt.root; <userinput>shutdown -r now</userinput>      <co xml:id="updating-src-qs-reboot"/>
&prompt.root; <userinput>cd /usr/src</userinput>          <co xml:id="updating-src-qs-cd2"/>
&prompt.root; <userinput>make installworld</userinput>    <co xml:id="updating-src-qs-installworld"/>
&prompt.root; <userinput>mergemaster -Ui</userinput>      <co xml:id="updating-src-qs-mergemaster"/>
&prompt.root; <userinput>shutdown -r now</userinput>      <co xml:id="updating-src-qs-shutdown"/></screen>

	  <calloutlist>
	    <callout arearefs="updating-src-qs-svnup">
	      <para>Get the latest version of the source.  See
		<xref linkend="updating-src-obtaining-src"/> for
		more information on obtaining and updating
		source.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-review-updating">
	      <para>Check <filename>/usr/src/UPDATING</filename>
		for any manual steps required before or after building
		from source.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-cd">
	      <para>Go to the source directory.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-buildworld">
	      <para>Compile the world, everything except the
		kernel.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-kernel">
	      <para>Compile and install the kernel.  This is
		equivalent to <command>make buildkernel
		  installkernel</command>.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-reboot">
	      <para>Reboot the system to the new kernel.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-cd2">
	      <para>Go to the source directory.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-installworld">
	      <para>Install the world.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-mergemaster">
	      <para>Update and merge configuration files in
		<filename>/etc/</filename>.</para>
	    </callout>

	    <callout arearefs="updating-src-qs-shutdown">
	      <para>Restart the system to use the newly-built world
		and kernel.</para>
	    </callout>
	  </calloutlist>
	</step>
      </procedure>
    </sect2>

    <sect2 xml:id="updating-src-preparing">
      <title>Preparing for a Source Update</title>

      <para>Read <filename>/usr/src/UPDATING</filename>.  Any manual
	steps that must be performed before or after an update are
	described in this file.</para>
    </sect2>

    <sect2 xml:id="updating-src-obtaining-src">
      <title>Updating the Source</title>

      <para>&os; source code is located in
	<filename>/usr/src/</filename>.  The preferred method of
	updating this source is through the
	<application>Subversion</application> version control system.
	Verify that the source code is under version control:</para>

      <screen>&prompt.root; <userinput>svnlite info /usr/src</userinput>
Path: /usr/src
Working Copy Root Path: /usr/src
...</screen>

      <para>This indicates that <filename>/usr/src/</filename>
	is under version control and can be updated with
	&man.svnlite.1;:</para>

      <screen xml:id="synching">&prompt.root; <userinput>svnlite update /usr/src</userinput></screen>

      <para>The update process can take some time if the directory has
	not been updated recently.  After it finishes, the source code
	is up to date and the build process described in the next
	section can begin.</para>

      <note xml:id="updating-src-obtaining-src-checkout">
	<title>Obtaining the Source</title>

	<para>If the output says
	  <literal>'/usr/src' is not a working copy</literal>, the
	  files there are missing or were installed with a different
	  method.  A new checkout of the source is required.</para>

	<table xml:id="updating-src-obtaining-src-repopath">
	  <title>&os; Versions and Repository Paths</title>

	  <tgroup cols="3">
	    <thead>
	      <row>
		<entry><command>uname -r</command> Output</entry>
		<entry>Repository Path</entry>
		<entry>Description</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><literal><replaceable>X.Y</replaceable>-RELEASE</literal></entry>
		<entry><literal>base/releng/</literal><replaceable>X.Y</replaceable></entry>
		<entry>The Release version plus only critical security
		  and bug fix patches.  This branch is recommended
		  for most users.</entry>
	      </row>

	      <row xml:id="STABLE">
		<entry><literal><replaceable>X.Y</replaceable>-STABLE</literal></entry>
		<entry><literal>base/stable/</literal><replaceable>X</replaceable></entry>
		<entry>
		  <para>The Release version plus all additional
		    development on that branch.
		    <emphasis>STABLE</emphasis> refers to the
		    Applications Binary Interface
		    (<acronym>ABI</acronym>) not changing, so software
		    compiled for earlier versions still runs.  For
		    example, software compiled to run on &os; 10.1
		    will still run on &os; 10-STABLE compiled
		    later.</para>

		  <para>STABLE branches occasionally have bugs or
		    incompatibilities which might affect users,
		    although these are typically fixed quickly.</para>
		</entry>
	      </row>

	      <row>
		<entry><literal><replaceable>X</replaceable>-CURRENT</literal></entry>
		<entry><literal>base/head/</literal></entry>
		<entry>The latest unreleased development version of
		  &os;.  The CURRENT branch can have major bugs or
		  incompatibilities and is recommended only for
		  advanced users.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

	<para>Determine which version of &os; is being used with
	  &man.uname.1;:</para>

	<screen>&prompt.root; <userinput>uname -r</userinput>
10.3-RELEASE</screen>

	<para>Based on
	  <xref linkend="updating-src-obtaining-src-repopath"/>, the
	  source used to update <literal>10.3-RELEASE</literal> has
	  a repository path of <literal>base/releng/10.3</literal>.
	  That path is used when checking out the source:</para>

	<screen>&prompt.root; <userinput>mv /usr/src /usr/src.bak</userinput>  <co xml:id="updating-src-obtaining-src-mv"/>
&prompt.root; <userinput>svnlite checkout https://svn.freebsd.org/base/<replaceable>releng/10.3</replaceable> /usr/src</userinput>  <co xml:id="updating-src-obtaining-src-checkout-cmd"/></screen>

	<calloutlist>
	  <callout arearefs="updating-src-obtaining-src-mv">
	    <para>Move the old directory out of the way.  If there are
	      no local modifications in this directory, it can be
	      deleted.</para>
	  </callout>

	  <callout arearefs="updating-src-obtaining-src-checkout-cmd">
	    <para>The path from
	      <xref linkend="updating-src-obtaining-src-repopath"/> is
	      added to the repository <acronym>URL</acronym>.  The
	      third parameter is the destination directory for the
	      source code on the local system.</para>
	  </callout>
	</calloutlist>
      </note>
    </sect2>

    <sect2 xml:id="updating-src-building">
      <title>Building from Source</title>

      <para>The <emphasis>world</emphasis>, or all
	of the operating system except the kernel, is compiled.  This
	is done first to provide up-to-date tools to build the kernel.
	Then the kernel itself is built:</para>

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

      <para>The compiled code is written to
	<filename>/usr/obj</filename>.</para>

      <para>These are the basic steps.  Additional options to control
	the build are described below.</para>

      <sect3 xml:id="updating-src-building-clean-build">
	<title>Performing a Clean Build</title>

	<para>Some versions of the &os; build system leave
	  previously-compiled code in the temporary object directory,
	  <filename>/usr/obj</filename>.  This can speed up later
	  builds by avoiding recompiling code that has not changed.
	  To force a clean rebuild of everything, use
	  <buildtarget>cleanworld</buildtarget> before starting
	  a build:</para>

	<screen>&prompt.root; <userinput>make cleanworld</userinput></screen>
      </sect3>

      <sect3 xml:id="updating-src-building-jobs">
	<title>Setting the Number of Jobs</title>

	<para>Increasing the number of build jobs on multi-core
	  processors can improve build speed.  Determine the number of
	  cores with <command>sysctl hw.ncpu</command>.  Processors
	  vary, as do the build systems used with different versions
	  of &os;, so testing is the only sure method to tell how a
	  different number of jobs affects the build speed.  For a
	  starting point, consider values between half and double the
	  number of cores.  The number of jobs is specified with
	  <option>-j</option>.</para>

	<example xml:id="updating-src-building-jobs-example">
	  <title>Increasing the Number of Build Jobs</title>

	  <para>Building the world and kernel with four jobs:</para>

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

      <sect3 xml:id="updating-src-building-only-kernel">
	<title>Building Only the Kernel</title>

	<para>A <buildtarget>buildworld</buildtarget> must be
	  completed if the source code has changed.  After that, a
	  <buildtarget>buildkernel</buildtarget> to build a kernel can
	  be run at any time.  To build just the kernel:</para>

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

      <sect3 xml:id="updating-src-building-custom-kernel">
	<title>Building a Custom Kernel</title>

	<para>The standard &os; kernel is based on a
	  <emphasis>kernel config file</emphasis> called
	  <filename>GENERIC</filename>.  The
	  <filename>GENERIC</filename> kernel includes the most
	  commonly-needed device drivers and options.  Sometimes it
	  is useful or necessary to build a custom kernel, adding or
	  removing device drivers or options to fit a specific
	  need.</para>

	<para>For example, someone developing a small embedded
	  computer with severely limited <acronym>RAM</acronym> could
	  remove unneeded device drivers or options to make the kernel
	  slightly smaller.</para>

	<para>Kernel config files are located in
	  <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/</filename>,
	  where <replaceable>arch</replaceable> is the output from
	  <command>uname -m</command>.  On most computers, that is
	  <literal>amd64</literal>, giving a config file directory of
	  <filename>/usr/src/sys/<replaceable>amd64</replaceable>/conf/</filename>.</para>

	<tip>
	  <para><filename>/usr/src</filename> can be deleted or
	    recreated, so it is preferable to keep custom kernel
	    config files in a separate directory, like
	    <filename>/root</filename>.  Link the kernel config file
	    into the <filename>conf</filename> directory.  If that
	    directory is deleted or overwritten, the kernel config
	    can be re-linked into the new one.</para>
	</tip>

	<para>A custom config file can be created by copying the
	  <filename>GENERIC</filename> config file.  In this example,
	  the new custom kernel is for a storage server, so is named
	  <filename>STORAGESERVER</filename>:</para>

	<screen>&prompt.root; <userinput>cp /usr/src/sys/amd64/conf/GENERIC /root/STORAGESERVER</userinput>
&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput>
&prompt.root; <userinput>ln -s /root/STORAGESERVER .</userinput></screen>

	<para><filename>/root/STORAGESERVER</filename> is then edited,
	  adding or removing devices or options as shown in
	  &man.config.5;.</para>

	<para>The custom kernel is built by setting
	  <varname>KERNCONF</varname> to the kernel config file on the
	  command line:</para>

	<screen>&prompt.root; <userinput>make buildkernel KERNCONF=STORAGESERVER</userinput></screen>
      </sect3>
    </sect2>

    <sect2 xml:id="updating-src-installing">
      <title>Installing the Compiled Code</title>

      <para>After the <buildtarget>buildworld</buildtarget> and
	<buildtarget>buildkernel</buildtarget> steps have been
	completed, the new kernel and world are installed:</para>

      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installkernel</userinput>
&prompt.root; <userinput>shutdown -r now</userinput>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput>
&prompt.root; <userinput>shutdown -r now</userinput></screen>

      <para>If a custom kernel was built, <varname>KERNCONF</varname>
	must also be set to use the new custom kernel:</para>

      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installkernel KERNCONF=STORAGESERVER</userinput>
&prompt.root; <userinput>shutdown -r now</userinput>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput>
&prompt.root; <userinput>shutdown -r now</userinput></screen>
    </sect2>

    <sect2 xml:id="updating-src-completing">
      <title>Completing the Update</title>

      <para>A few final tasks complete the update.  Any modified
	configuration files are merged with the new versions, outdated
	libraries are located and removed, then the system is
	restarted.</para>

      <sect3 xml:id="updating-src-completing-merge-mergemaster">
	<title>Merging Configuration Files with
	  &man.mergemaster.8;</title>

	<para>&man.mergemaster.8; provides an easy
	  way to merge changes that have been made to system
	  configuration files with new versions of those files.</para>

	<para>With <option>-Ui</option>, &man.mergemaster.8;
	  automatically updates files that have not been user-modified
	  and installs new files that are not already present:</para>

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

	<para>If a file must be manually merged, an interactive
	  display allows the user to choose which portions of the
	  files are kept.  See &man.mergemaster.8; for more
	  information.</para>
      </sect3>

      <sect3 xml:id="updating-src-completing-check-old">
	<title>Checking for Outdated Files and Libraries</title>

	<para>Some obsolete files or directories can remain after an
	  update.  These files can be located:</para>

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

	<para>and deleted:</para>

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

	<para>Some obsolete libraries can also remain.  These can be
	  detected with:</para>

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

	<para>and deleted with</para>

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

	<para>Programs which were still using those old libraries will
	  stop working when the library has been deleted.  These
	  programs must be rebuilt or replaced after deleting the old
	  libraries.</para>

	<tip>
	  <para>When all the old files or directories are known to be
	    safe to delete, pressing <keycap>y</keycap> and
	    <keycap>Enter</keycap> to delete each file can be avoided
	    by setting <varname>BATCH_DELETE_OLD_FILES</varname> in
	    the command.  For example:</para>

	  <screen>&prompt.root; <userinput>make BATCH_DELETE_OLD_FILES=yes delete-old-libs</userinput></screen>
	</tip>
      </sect3>

      <sect3 xml:id="updating-src-completing-restart">
	<title>Restarting After the Update</title>

	<para>The last step after updating is to restart the computer
	  so all the changes take effect:</para>

	<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
      </sect3>
    </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
      <acronym>CPU</acronym> 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 <acronym>NFS</acronym>.  This section
      outlines a method of doing so.  For more information about using
      <acronym>NFS</acronym>, refer to <xref
	linkend="network-nfs"/>.</para>

    <para>First, identify a set of machines which will run the same
      set of binaries, known as a <firstterm>build set</firstterm>.
      Each machine can have a custom kernel, but will run the same
      userland binaries.  From that set, choose a machine to be the
      <firstterm>build machine</firstterm> that the world and kernel
      are built on.  Ideally, this is a fast machine that has
      sufficient spare <acronym>CPU</acronym> to run <command>make
	buildworld</command> and <command>make
	buildkernel</command>.</para>

    <para>Select a machine to be the <firstterm>test
	machine</firstterm>, 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 build machine via <acronym>NFS</acronym>.  For multiple
      build sets, <filename>/usr/src</filename> should be on one build
      machine, and <acronym>NFS</acronym> mounted on the rest.</para>

    <para>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 its <varname>KERNCONF</varname>,
      listing its own kernel first.  The build machine must have the
      kernel configuration files for each machine in its <filename
	>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>.</para>

    <para>On the build machine, build the kernel and world as
      described in <xref linkend="makeworld"/>, but do not install
      anything on the build machine.  Instead, install the built
      kernel on the test machine.  On the test machine, mount
      <filename>/usr/src</filename> and
      <filename>/usr/obj</filename> via <acronym>NFS</acronym>.  Then,
      run <command>shutdown now</command> to go to single-user mode in
      order to install the new kernel and world and run
      <command>mergemaster</command> as usual.  When done, reboot to
      return to normal multi-user operations.</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>

    <para>The same methodology can be used for the ports tree.  The
      first step is to share <filename>/usr/ports</filename> via
      <acronym>NFS</acronym> to all the machines in the build set.  To
      configure <filename>/etc/make.conf</filename> 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
      <acronym>NFS</acronym> mount.  Each machine should set
      <varname>WRKDIRPREFIX</varname> to a local build directory, if
      ports are to be built locally.  Alternately, if the build system
      is to build and distribute packages to the machines in the build
      set, set <varname>PACKAGES</varname> on the build system to a
      directory similar to <varname>DISTDIR</varname>.</para>
  </sect1>
</chapter>