diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
index c25b044ae3..1865ae3767 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -1,1857 +1,1861 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="cutting-edge">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured, reorganized, and parts updated by </contrib>
       </author>
       <!-- Mar 2000 -->
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Jordan</firstname>
 	<surname>Hubbard</surname>
 	<contrib>Original work by </contrib>
       </author>
       <author>
 	<firstname>Poul-Henning</firstname>
 	<surname>Kamp</surname>
       </author>
       <author>
 	<firstname>John</firstname>
 	<surname>Polstra</surname>
       </author>
       <author>
 	<firstname>Nik</firstname>
 	<surname>Clayton</surname>
       </author>
     </authorgroup>
     <!-- with feedback from various others -->
   </chapterinfo>
 
   <title>The Cutting Edge</title>
 
   <sect1 id="cutting-edge-synopsis">
     <title>Synopsis</title>
 
     <para>&os; is under constant development between releases.  For
       people who want to be on the cutting edge, there are several easy
       mechanisms for keeping your system in sync with the latest
       developments.  Be warned&mdash;the cutting edge is not for everyone!
       This chapter will help you decide if you want to track the
       development system, or stick with one of the released
       versions.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem><para>The difference between the two development
       branches: &os.stable; and &os.current;.</para>
       </listitem>
       <listitem><para>How to keep your system up to date with
 	  <application>CVSup</application>,
 	  <application>CVS</application>, or
 	  <application>CTM</application>.</para>
       </listitem>
       <listitem><para>How to rebuild and reinstall the entire base
       system with <command>make buildworld</command> (etc).</para>
       </listitem>
 
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem><para>Properly set up your network connection (<xref
       linkend="advanced-networking">).</para>
       </listitem>
       <listitem><para>Know how to install additional third-party
         software (<xref linkend="ports">).</para></listitem>
     </itemizedlist>
   </sect1>
   
   <sect1 id="current-stable">
     <title>&os.current; vs. &os.stable;</title>
     <indexterm><primary>-CURRENT</primary></indexterm>
     <indexterm><primary>-STABLE</primary></indexterm>
 
     <para>There are two development branches to FreeBSD: &os.current; and
       &os.stable;.  This section will explain a bit about each and describe
       how to keep your system up-to-date with each respective tree.
       &os.current; will be discussed first, then &os.stable;.</para>
 
     <sect2 id="current">
       <title>Staying Current with &os;</title>
 
       <para>As you read this, keep in mind that &os.current; is the
 	<quote>bleeding edge</quote> of &os; development.
 	&os.current; users are expected to have a high degree of
 	technical skill, and should be capable of solving difficult
 	system problems on their own.  If you are new to &os;, think
 	twice before installing it.  </para>
 
       <sect3>
 	<title>What Is &os.current;?</title>
 	<indexterm><primary>snapshot</primary></indexterm>
 
 	<para>&os.current; is the latest working sources for &os;.
 	  This includes work in progress, experimental changes, and
 	  transitional mechanisms that might or might not be present
 	  in the next official release of the software.  While many
 	  &os; developers compile the &os.current; source code daily,
 	  there are periods of time when the sources are not
 	  buildable.  These problems are resolved as expeditiously as
 	  possible, but whether or not &os.current; brings disaster or
 	  greatly desired functionality can be a matter of which exact
 	  moment you grabbed the source code in!</para>
       </sect3>
 
       <sect3>
 	<title>Who Needs &os.current;?</title>
 
 	<para>&os.current; is made available for 3 primary
 	  interest groups:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>Members of the &os; community who are actively working
 	      on some part of the source tree and for whom keeping
 	      <quote>current</quote> is an absolute
 	      requirement.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Members of the &os; community who are active testers,
 	      willing to spend time solving problems in order to
 	      ensure that &os.current; remains as sane as possible.
 	      These are also people who wish to make topical
 	      suggestions on changes and the general direction of
 	      &os;, and submit patches to implement them.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Those who merely wish to keep an eye on things, or
 	      to use the current sources for reference purposes
 	      (e.g. for <emphasis>reading</emphasis>, not running).
 	      These people also make the occasional comment or
 	      contribute code.</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
 
       <sect3>
 	<title>What Is &os.current; <emphasis>Not</emphasis>?</title>
 
 	<orderedlist>
 	  <listitem>
 	    <para>A fast-track to getting pre-release bits because you
 	      heard there is some cool new feature in there and you
 	      want to be the first on your block to have it.  Being
 	      the first on the block to get the new feature means that
 	      you're the first on the block to get the new
 	      bugs.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>A quick way of getting bug fixes.  Any given version
 	      of &os.current; is just as likely to introduce new bugs
 	      as to fix existing ones.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>In any way <quote>officially supported</quote>.  We
 	      do our best to help people genuinely in one of the 3
 	      <quote>legitimate</quote> &os.current; groups, but we
 	      simply <emphasis>do not have the time</emphasis> to
 	      provide tech support.  This is not because we are mean
 	      and nasty people who do not like helping people out (we
 	      would not even be doing &os; if we were).  We simply
 	      cannot answer hundreds messages a day
 	      <emphasis>and</emphasis> work on FreeBSD!  Given the
 	      choice between improving &os; and answering lots of
 	      questions on experimental code, the developers opt for
 	      the former.</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
 
       <sect3>
 	<title>Using &os.current;</title>
       
 	<indexterm>
 	  <primary>-CURRENT</primary>
 	  <secondary>using</secondary>
 	</indexterm>
 	<orderedlist>
 	  <listitem>
 	    <para>Join the &a.current.name; and the &a.cvsall.name; lists.  This is not
 	      just a good idea, it is <emphasis>essential</emphasis>.  If
 	      you are not on the <emphasis>&a.current.name;</emphasis> list,
 	      you will not see the comments that people are
 	      making about the current state of the system and thus will
 	      probably end up stumbling over a lot of problems that others
 	      have already found and solved.  Even more importantly, you
 	      will miss out on important bulletins which may be critical
 	      to your system's continued health.</para>
 
 	    <para>The &a.cvsall.name; list will allow you to see 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, or one of the others available
 	      go to &a.mailman.lists.link; and click on the list that
 	      you wish to subscribe to.  Instructions on the rest of
 	      the procedure are available there.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Grab the sources from a &os; <link linkend="mirrors">mirror
 	      site</link>.  You can do this in one of two ways:</para>
 
 	    <orderedlist>
               <indexterm>
                 <primary><command>cvsup</command></primary>
               </indexterm>
               <indexterm>
                 <primary><command>cron</command></primary>
               </indexterm>
               <indexterm>
 	        <primary>-CURRENT</primary>
 		<secondary>Syncing with <application>CVSup</application></secondary>
 	      </indexterm>
 
 	      <listitem>
 		<para>Use the <link linkend="cvsup">cvsup</link> program
                   with the <filename>supfile</filename> named <filename>standard-supfile</filename>
                   available from <filename>/usr/share/examples/cvsup</filename>.
 		  This is the most recommended
 		  method, since it allows you to grab the entire
 		  collection once and then only what has changed from then
 		  on.  Many people run <command>cvsup</command> from 
 		  <command>cron</command> and keep their
  		  sources up-to-date automatically.  You have to 
  		  customize the sample <filename>supfile</filename> above, and configure 
  		  <link linkend="cvsup">cvsup</link> for your environment.</para>
 	      </listitem>
 
               <indexterm>
 	        <primary>-CURRENT</primary>
 		<secondary>Syncing with CTM</secondary>
 	      </indexterm>
 	      <listitem>
 		<para>Use the <application><link
 		  linkend="ctm">CTM</link></application> facility.  If you
 		  have very bad connectivity (high price connections or
 		  only email access) <application>CTM</application> is an option.
 		  However, it is a lot of hassle and can give you broken files.
 		  This leads to it being rarely used, which again increases
 		  the chance of it not working for fairly long periods of
 		  time.  We recommend using
 		  <application><link linkend="cvsup">CVSup</link></application>
 		  for anybody with a 9600&nbsp;bps modem or faster connection.
 		</para>
 	      </listitem>
 	    </orderedlist>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you are grabbing the sources to run, and not just
 	      look at, then grab <emphasis>all</emphasis> of &os.current;, not
 	      just selected portions.  The reason for this is that various
 	      parts of the source depend on updates elsewhere, and trying
 	      to compile just a subset is almost guaranteed to get you
 	      into trouble.</para>
 
 	  <indexterm>
 	    <primary>-CURRENT</primary>
 	    <secondary>compiling</secondary>
 	  </indexterm>
 	    <para>Before compiling &os.current;, read the
 	      <filename>Makefile</filename> in <filename>/usr/src</filename>
 	      carefully.  You should at least <link
 	      linkend="makeworld">install a new kernel and rebuild the world</link> the first time through
 	      as part of the upgrading process.  Reading the &a.current;
 	      and <filename>/usr/src/UPDATING</filename> will keep you up-to-date on other bootstrapping procedures
 	      that sometimes become necessary as we move toward the next
 	      release.</para>
 	  </listitem>
 	      
 	  <listitem>
 	    <para>Be active! If you are running &os.current;, we want
 	      to know what you have to say about it, especially if you
 	      have suggestions for enhancements or bug fixes.  Suggestions
 	      with accompanying code are received most
 	      enthusiastically!</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
   
     <sect2 id="stable">
       <title>Staying Stable with &os;</title>
 
       <sect3>
 	<title>What Is &os.stable;?</title>
 	<indexterm><primary>-STABLE</primary></indexterm>
 
 	<para>&os.stable; is our development branch from which major releases
 	  are made.  Changes go into this branch at a different pace, and
 	  with the general assumption that they have first gone into
 	  &os.current; for testing.  This is <emphasis>still</emphasis>
 	  a development branch, however, and this means that at any given time,
 	  the sources for &os.stable; may or may not be suitable for any
 	  particular purpose.  It is simply another engineering development
 	  track, not a resource for end-users.</para>
       </sect3>
 
       <sect3>
 	<title>Who Needs &os.stable;?</title>
 
 	<para>If you are interested in tracking or contributing to the
           FreeBSD development process, especially as it relates to the
 	  next <quote>point</quote> release of FreeBSD, then you should
 	  consider following &os.stable;.</para>
 
 	<para>While it is true that security fixes also go into the
 	  &os.stable; branch, you do not <emphasis>need</emphasis> to
 	  track &os.stable; to do this. Every security advisory for
 	  FreeBSD explains how to fix the problem for the releases it
 	  affects
 	  <footnote><para>That is not quite true.  We can not continue to
   	    support old releases of FreeBSD forever, although we do
   	    support them for many years.  For a complete description
   	    of the current security policy for old releases of
   	    FreeBSD, please see <ulink
   	    url="&url.base;/security/">http://www.FreeBSD.org/security/</ulink>.</para>
 	  </footnote>
 	  , and tracking an entire development branch just
 	  for security reasons is likely to bring in a lot of unwanted
 	  changes as well.</para>
 
 	<para>Although we endeavor to ensure that the &os.stable; branch
 	  compiles and runs at all times, this cannot be guaranteed.  In
 	  addition, while code is developed in &os.current; before including
 	  it in &os.stable;, more people run &os.stable; than &os.current;, so
 	  it is inevitable that bugs and corner cases will sometimes be found
 	  in &os.stable; that were not apparent in &os.current;.</para>
 
 	<para>For these reasons, we do <emphasis>not</emphasis> recommend that
 	  you blindly track &os.stable;, and it is particularly important that
 	  you do not update any production servers to &os.stable; without
 	  first thoroughly testing the code in your development
 	  environment.</para>
 
 	<para>If you do not have the resources to do this then we recommend
 	  that you run the most recent release of FreeBSD, and use the binary
 	  update mechanism to move from release to release.</para>
       </sect3>
 
       <sect3>
 	<title>Using &os.stable;</title>
       
 	<indexterm>
 	  <primary>-STABLE</primary>
 	  <secondary>using</secondary>
 	</indexterm>
 	<orderedlist>
 	  <listitem>
 	    <para>Join the &a.stable.name; list.  This will keep you 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>The &a.cvsall.name; list will allow you to see 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, or one of the others available
 	      go to &a.mailman.lists.link; and click on the list that
 	      you wish to subscribe to.  Instructions on the rest of
 	      the procedure are available there.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you are installing a new system and want it to be as
 	      stable as possible, you can simply grab the latest dated
 	      branch snapshot from <ulink
 	      url="ftp://snapshots.jp.FreeBSD.org/pub/FreeBSD/snapshots/"></ulink>
 	      and install it like any other release.  Or you can
 	      install the most recent &os.stable; release from the
 	      <link linkend="mirrors">mirror sites</link> and follow
 	      the instructions below to upgrade your system to the
 	      most up to date &os.stable; source code.</para>
 
 	    <para>If you are already running a previous release of &os;
 	      and wish to upgrade via sources then you can easily do so
 	      from &os; <link linkend="mirrors">mirror site</link>.  This can
 	      be done in one of two ways:</para>
 
 	    <orderedlist>
 	      <indexterm>
 		<primary><command>cvsup</command></primary>
 	      </indexterm>
 	      <indexterm>
 		<primary><command>cron</command></primary>
 	      </indexterm>
 	      <indexterm>
 	        <primary>-STABLE</primary>
 		<secondary>syncing with <application>CVSup</application></secondary>
 	      </indexterm>
 	      <listitem>
 		<para>Use the <link linkend="cvsup">cvsup</link> program
                   with the <filename>supfile</filename> named <filename>stable-supfile</filename>
                   from the directory
                   <filename>/usr/share/examples/cvsup</filename>.
 		  This is the most recommended
 		  method, since it allows you to grab the entire
 		  collection once and then only what has changed from then
 		  on.  Many people run <command>cvsup</command> from 
 		  <command>cron</command> to keep their
 		  sources up-to-date automatically.  You have to
 		  customize the sample <filename>supfile</filename> above,
 		  and configure <link linkend="cvsup">cvsup</link> for your
 		  environment.</para>
 	      </listitem>
 
 	      <indexterm>
 	        <primary>-STABLE</primary>
 		<secondary>syncing with CTM</secondary>
 	      </indexterm>
 	      <listitem>
 		<para>Use the <application><link
 		  linkend="ctm">CTM</link></application> facility.  If
 		  you do not have a fast and inexpensive connection to
 		  the Internet, this is the method you should consider
 		  using.
 		  </para>
 	      </listitem>
 	   </orderedlist>
 	 </listitem>
 
 	  <listitem>
 	    <para>Essentially, if you need rapid on-demand access to the
 	      source and communications bandwidth is not a consideration,
 	      use <command>cvsup</command> or <command>ftp</command>.
 	      Otherwise, use <application>CTM</application>.</para>
 	  </listitem>
 
 	  <indexterm>
 	    <primary>-STABLE</primary>
 	    <secondary>compiling</secondary>
 	  </indexterm>
 	  <listitem>
 	    <para>Before compiling &os.stable;, read the
 	    <filename>Makefile</filename> in <filename>/usr/src</filename>
 	    carefully.  You should at least <link
 	    linkend="makeworld">install a new kernel and rebuild the world</link> the first time through
 	    as part of the upgrading process.  Reading the &a.stable; and <filename>/usr/src/UPDATING</filename> will
 	    keep you up-to-date on other bootstrapping procedures that
 	    sometimes become necessary as we move toward the next
 	    release.</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="synching">
     <title>Synchronizing Your Source</title>
     
     <para>There are various ways of using an Internet (or email)
       connection to stay up-to-date with any given area of the &os;
       project sources, or all areas, depending on what interests you.  The
       primary services we offer are <link linkend="anoncvs">Anonymous
       CVS</link>, <link linkend="cvsup">CVSup</link>, and <link
       linkend="ctm">CTM</link>.</para>
 
     <warning>
       <para>While it is possible to update only parts of your source tree,
         the only supported update procedure is to update the entire tree
         and recompile both userland (i.e., 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 your source tree, only the kernel, or only userland will often
         result in problems.  These problems may range from compile errors
         to kernel panics or data corruption.</para>
     </warning>
 
-    <indexterm><primary>anonymous CVS</primary></indexterm>
+    <indexterm>
+      <primary>CVS</primary>
+      <secondary>anonymous</secondary>
+    </indexterm>
+
     <para><application>Anonymous CVS</application> and
       <application>CVSup</application> use the <emphasis>pull</emphasis>
       model of updating sources.  In the case of
       <application>CVSup</application> the user (or a 
       <command>cron</command> script) invokes
       the <command>cvsup</command> program, and it interacts with a
       <command>cvsupd</command> server somewhere to bring your files
       up-to-date.  The updates you receive are up-to-the-minute and you
       get them when, and only when, you want them.  You can easily
       restrict your updates to the specific files or directories that are
       of interest to you.  Updates are generated on the fly by the server,
       according to what you have and what you want to have.
       <application>Anonymous CVS</application> is quite a bit more
       simplistic than <application>CVSup</application> in that it is just an extension to
       <application>CVS</application> which allows it to pull changes
       directly from a remote CVS repository.
       <application>CVSup</application> can do this far more efficiently,
       but <application>Anonymous CVS</application> is easier to
       use.</para>
 
     <indexterm>
       <primary><application>CTM</application></primary>
     </indexterm>
     <para><application>CTM</application>, on the other hand, does not
       interactively compare the sources you have 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
       being 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 far more efficient than <application>CVSup</application>,
       and places less strain on our server resources since it is a
       <emphasis>push</emphasis> rather than a <emphasis>pull</emphasis>
       model.</para>
 
     <para>There are other trade-offs, of course.  If you inadvertently
       wipe out portions of your archive, <application>CVSup</application>
       will detect and rebuild the damaged portions for you.
       <application>CTM</application> will not do this, and if you wipe some
       portion of your source tree out (and do not have it backed up) then
       you will have to start from scratch (from the most recent CVS
       <quote>base delta</quote>) and rebuild it all with <application>CTM</application> or, with
       <application>Anonymous CVS</application>, simply delete the bad bits and resync.</para>
   </sect1>
 
   <sect1 id="makeworld">
     <title>Rebuilding <quote>world</quote></title>
 
     <indexterm>
       <primary>Rebuilding <quote>world</quote></primary>
     </indexterm>
     <para>Once you have synchronized your local source tree against a
       particular version of &os; (&os.stable;, &os.current;, and so on)
       you can then use the source
       tree to rebuild the system.</para>
 
     <warning>
       <title>Take a Backup</title>
 
       <para>It cannot be stressed enough how important it is to take a
 	backup of your system <emphasis>before</emphasis> you do this.
 	While rebuilding the world is (as long as you follow these
 	instructions) an easy task to do, there will inevitably be times
 	when you make mistakes, or when mistakes made by others in the
 	source tree render your system unbootable.</para>
 
       <para>Make sure you have taken a backup.  And have a fixit floppy or
 	bootable CD at
 	hand.  You will probably never have to use it, but it is better to be
 	safe than sorry!</para>
     </warning>
 
     <warning>
       <title>Subscribe to the Right Mailing List</title>
 
       <indexterm><primary>mailing list</primary></indexterm>
       <para>The &os.stable; and &os.current; branches are, by their
 	nature, <emphasis>in development</emphasis>.  People that
 	contribute to &os; are human, and mistakes occasionally
 	happen.</para>
 
       <para>Sometimes these mistakes can be quite harmless, just causing
 	your system to print a new diagnostic warning.  Or the change may
 	be catastrophic, and render your system unbootable or destroy your
 	file systems (or worse).</para>
 
       <para>If problems like these occur, a <quote>heads up</quote> is
         posted to the appropriate mailing list, explaining the nature of
 	the problem and which systems it affects.  And an <quote>all
 	clear</quote> announcement is posted when the problem has been
 	solved.</para>
 
       <para>If you try to track &os.stable; or &os.current; and do
 	not read the &a.stable; or the
 	&a.current; respectively, then you are
 	asking for trouble.</para>
     </warning>
 
     <warning>
       <title>Do not use <command>make world</command></title>
 
       <para>A lot of older documentation recommends using
 	<command>make world</command> for this.  Doing that skips
 	some important steps and should only be used if you are
 	sure of what you are doing.  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>
       <title>The Canonical Way to Update Your System</title>
 
       <para>To update your system, you should check
 	<filename>/usr/src/UPDATING</filename> for any pre-buildworld steps
 	necessary for your version of the sources and then use the following
 	procedure:</para>
 
       <screen>&prompt.root; <userinput>make buildworld</userinput>
 &prompt.root; <userinput>make buildkernel</userinput>
 &prompt.root; <userinput>make installkernel</userinput>
 &prompt.root; <userinput>reboot</userinput></screen>
 
       <note>
 	<para>There are a few rare cases when an extra run of
 	  <command>mergemaster -p</command> is needed before the
 	  <maketarget>buildworld</maketarget> step.  These are
 	  described in <filename>UPDATING</filename>.  In general,
 	  though, you can safely omit this step if you are not
 	  updating across one or more major &os; versions.</para>
       </note>
 
       <para>After <maketarget>installkernel</maketarget> finishes
 	successfully, you should boot in single user mode
 	(i.e.&nbsp;using <command>boot -s</command> from the loader
 	prompt).  Then run:</para>
 
       <screen>&prompt.root; <userinput>mergemaster -p</userinput>
 &prompt.root; <userinput>make installworld</userinput>
 &prompt.root; <userinput>mergemaster</userinput>
 &prompt.root; <userinput>reboot</userinput></screen>
 
       <warning>
 	<title>Read Further Explanations</title>
 
 	<para>The sequence described above is only a short resume to
 	  help you getting started.  You should however read the
 	  following sections to clearly understand each step, especially
 	  if you want to use a custom kernel configuration.</para>
       </warning>
     </sect2>
 
     <sect2>
       <title>Read <filename>/usr/src/UPDATING</filename></title>
 
       <para>Before you do anything else, read
 	<filename>/usr/src/UPDATING</filename> (or the equivalent file
 	wherever you have a copy of the source code).  This file should
 	contain important information about problems you might encounter, or
 	specify the order in which you might have to run certain commands.
 	If <filename>UPDATING</filename> contradicts something you read here,
 	<filename>UPDATING</filename> takes precedence.</para>
 
       <important>
 	<para>Reading <filename>UPDATING</filename> is not an acceptable
 	  substitute for subscribing to the correct mailing list, as described 
 	  previously.  The two requirements are complementary, not
 	  exclusive.</para>
       </important>
     </sect2>
 
     <sect2>
       <title>Check <filename>/etc/make.conf</filename></title>
       <indexterm>
         <primary><filename>make.conf</filename></primary>
       </indexterm>
 
       <para>Examine the files
 	<filename>/usr/share/examples/etc/make.conf</filename>
 	(called <filename>/etc/defaults/make.conf</filename> in &os;&nbsp;4.X) and
 	<filename>/etc/make.conf</filename>.  The first contains some
 	default defines &ndash; most of which are commented out.  To
 	make use of them when you rebuild your system from source, add
 	them to <filename>/etc/make.conf</filename>.  Keep in mind that
 	anything you add to <filename>/etc/make.conf</filename> is also
 	used every time you run <command>make</command>, so it is a good
 	idea to set them to something sensible for your system.</para>
 
       <para>A typical user will probably want to copy the
 	<makevar>CFLAGS</makevar> and
 	<makevar>NOPROFILE</makevar> lines found in
 	<filename>/usr/share/examples/etc/make.conf</filename>
 	(or in <filename>/etc/defaults/make.conf</filename> on &os;&nbsp;4.X) to
 	<filename>/etc/make.conf</filename> and uncomment them.</para>
 
       <para>Examine the other definitions (<makevar>COPTFLAGS</makevar>, 
 	<makevar>NOPORTDOCS</makevar> and so
 	on) and decide if they are relevant to you.</para>
     </sect2>
 
     <sect2>
       <title>Update the Files in <filename>/etc</filename></title>
 
       <para>The <filename>/etc</filename> directory contains a large part
 	of your system's configuration information, as well as scripts
 	that are run at system startup.  Some of these scripts change from
 	version to version of FreeBSD.</para>
 
       <para>Some of the configuration files are also used in the day to
 	day running of the system.  In particular,
 	<filename>/etc/group</filename>.</para>
 
       <para>There have been occasions when the installation part of
         <command>make installworld</command> has expected certain usernames or groups
 	to exist.  When performing an upgrade it is likely that these
 	users or groups did not exist. This caused problems when upgrading.
 	In some cases <command>make buildworld</command> will check to see if
 	these users or groups exist.</para>
 
       <para>A recent example of this is when the
 	<username>smmsp</username> user was added.  Users had the
 	installation process fail for them when
 	&man.mtree.8; was trying to create
 	<filename>/var/spool/clientmqueue</filename>.</para>
 
       <para>The solution is to examine
 	<filename>/usr/src/etc/group</filename> and compare its list of
 	groups with your own.  If there are any groups in the new file that
 	are not in your file then copy them over.  Similarly, you should
 	rename any groups in <filename>/etc/group</filename> which have
 	the same GID but a different name to those in
 	<filename>/usr/src/etc/group</filename>.</para>
 
       <para>Since 4.6-RELEASE you can run &man.mergemaster.8; in
 	pre-buildworld mode by providing the <option>-p</option> option.
 	This will compare only those files that are essential for the success
 	of <maketarget>buildworld</maketarget> or
 	<maketarget>installworld</maketarget>.  If your old version of
 	<command>mergemaster</command> does not support <option>-p</option>,
 	use the new version in the source tree when running for the first
 	time:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/mergemaster</userinput>
 &prompt.root; <userinput>./mergemaster.sh -p</userinput></screen>
 
       <tip>
 	<para>If you are feeling particularly paranoid, you can check your
 	  system to see which files are owned by the group you are
 	  renaming or deleting:</para>
 
 	<screen>&prompt.root; <userinput>find / -group <replaceable>GID</replaceable> -print</userinput></screen>
 
 	<para>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 id="makeworld-singleuser">
       <title>Drop to Single User Mode</title>
       <indexterm><primary>single-user mode</primary></indexterm>
 
       <para>You may want to compile the system in single user mode.  Apart
 	from the obvious benefit of making things go slightly faster,
 	reinstalling the system will touch a lot of important system
 	files, all the standard system binaries, libraries, include files
 	and so on.  Changing these on a running system (particularly if
 	you have active users on the system at the time) 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.  If you would
         like to do it this way, simply hold off on the following steps until
         the build has completed.  You can postpone dropping to single user
 	mode until you have to <maketarget>installkernel</maketarget> or
 	<maketarget>installworld</maketarget>.</para>
 
       <para>As the superuser, you can execute:</para>
 
       <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
 
       <para>from a running system, which will drop it to single user
 	mode.</para>
 
       <para>Alternatively, reboot the system, and at the boot prompt,
         enter the <option>-s</option> flag.  The system will then boot
 	single user.  At the shell prompt you should then 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 then turns swapping on.</para>
 
 
         <note>
           <para>If your CMOS clock is set to local time and not to GMT
 	    (this is true if the output of the &man.date.1; command
 	    does not show the correct time and zone),
             you may also need to run the following command:</para>
 <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
 
           <para>This will make sure that your local time-zone settings
             get set up correctly &mdash; without this, you may later run into some
             problems.
           </para>
         </note>
 
     </sect2>
 
     <sect2>
       <title>Remove <filename>/usr/obj</filename></title>
 
       <para>As parts of the system are rebuilt they are placed in
 	directories which (by default) go under
 	<filename>/usr/obj</filename>.  The directories shadow those under
 	<filename>/usr/src</filename>.</para>
 
       <para>You can speed up the <command>make buildworld</command> process, and
 	possibly save yourself some dependency headaches by removing this
 	directory as well.</para>
 
       <para>Some files below <filename>/usr/obj</filename> may have the
 	immutable flag set (see &man.chflags.1; for more information)
 	which must be removed first.</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>
       <title>Recompile the Source</title>
 
       <sect3>
 	<title>Saving the Output</title>
 
 	<para>It is a good idea to save the output you get from running
 	  &man.make.1; to another file.  If something goes wrong you will
 	  have a copy of the error message.  While this might not help you
 	  in diagnosing what has gone wrong, it can help others if you post
 	  your problem to one of the &os; mailing lists.</para>
 
 	<para>The easiest way to do this is to use the &man.script.1;
 	  command, with a parameter that specifies the name of the file to
 	  save all output to.  You would do this 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>If you do this, <emphasis>do not</emphasis> save the output
 	  in <filename>/tmp</filename>.  This directory may be cleared
 	  next time you reboot.  A better place to store it is in
 	  <filename>/var/tmp</filename> (as in the previous example) or
 	  in <username>root</username>'s home directory.</para>
       </sect3>
 
       <sect3 id="make-buildworld">
 	<title>Compile the Base System</title>
 
 	<para>You must be in the <filename>/usr/src</filename>
 	  directory:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
 
 	<para>(unless, of course, your source code is elsewhere, in which
 	  case change to that directory instead).</para>
 	<indexterm><primary><command>make</command></primary></indexterm>
 
 	<para>To rebuild the world you use the &man.make.1; command.  This
           command reads instructions from the <filename>Makefile</filename>,
           which describes how the programs that comprise &os; should be
           rebuilt, the order in which they should be built, and so on.</para>
 
 	<para>The general format of the command line you will type is as
 	  follows:</para>
 
 	<screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>
 
 	<para>In this example, <option>-<replaceable>x</replaceable></option>
 	  is an option that you would pass to &man.make.1;.  See the
 	  &man.make.1; manual page for an example of the options you can
 	  pass.</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.</para>
 
 	<screen>&prompt.root; <userinput>make -DNOPROFILE <replaceable>target</replaceable></userinput></screen>
 
 	<para>is another way of specifying that profiled libraries should
 	  not be built, and corresponds with the</para>
 
 	<programlisting>NOPROFILE=    true 	#    Avoid compiling profiled libraries</programlisting>
 
 	<para>line in <filename>/etc/make.conf</filename>.</para>
 
 	<para><replaceable>target</replaceable> tells &man.make.1; what
 	  you want to do.  Each <filename>Makefile</filename> defines a
 	  number of different <quote>targets</quote>, and your choice of
 	  target determines what happens.</para>
 
 	<para>Some targets are listed in the
 	  <filename>Makefile</filename>, but are not meant for you to run.
 	  Instead, they 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 you will not need to pass any parameters to
 	    &man.make.1;, and so your command like will look like
 	    this:</para>
 
 	<screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen>
 
 	<para>Beginning with version 2.2.5 of &os; (actually, it was
 	  first created on the &os.current; branch, and then retrofitted to
 	  &os.stable; midway between 2.2.2 and 2.2.5) the
 	  <maketarget>world</maketarget> target has been split in
 	  two: <maketarget>buildworld</maketarget> and
 	  <maketarget>installworld</maketarget>.  Beginning with version
 	  5.3 of &os; the <maketarget>world</maketarget> target will be changed
 	  so it will not work at all by default because it is actually
 	  dangerous for most users.</para>
 
 	<para>As the names imply, <maketarget>buildworld</maketarget>
 	  builds a complete new tree under <filename>/usr/obj</filename>,
 	  and <maketarget>installworld</maketarget> installs this tree on
 	  the current machine.</para>
 
 	<para>This is very useful for 2 reasons.  First, it allows you
 	  to do the build safe in the knowledge that no components of
 	  your running system will be affected.  The build is
 	  <quote>self hosted</quote>.  Because of this, you can safely
 	  run <maketarget>buildworld</maketarget> on a machine running
 	  in multi-user mode with no fear of ill-effects.  It is still
 	  recommended that you run the
 	  <maketarget>installworld</maketarget> part in single user
 	  mode, though.</para>
 
 	<para>Secondly, it allows you to use NFS mounts to upgrade 
 	  multiple machines on your network.  If you have three machines,
 	  <hostid>A</hostid>, <hostid>B</hostid> and <hostid>C</hostid> that you want to upgrade, run <command>make
 	  buildworld</command> and <command>make installworld</command> on
 	  <hostid>A</hostid>.  <hostid>B</hostid> and <hostid>C</hostid> should then NFS mount <filename>/usr/src</filename>
 	  and <filename>/usr/obj</filename> from <hostid>A</hostid>, and you can then run
 	  <command>make installworld</command> to install the results of 
 	  the build on <hostid>B</hostid> and <hostid>C</hostid>.</para>
 
 	<para>Although the <maketarget>world</maketarget> target still exists,
 	  you are strongly encouraged not to use it.</para>
 
 	<para>Run</para>
 
 	<screen>&prompt.root; <userinput>make buildworld</userinput></screen>
  
         <para>It is now possible to specify a <option>-j</option> option to
           <command>make</command> which will cause it to spawn several
           simultaneous processes.  This is most useful on multi-CPU machines.
           However, since much of the compiling process is IO bound rather
           than CPU bound it is also useful on single CPU machines.</para>
 
 	<para>On a typical single-CPU machine you would 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>If you have a multi-CPU machine and you are using an SMP
 	  configured kernel try values between 6 and 10 and see how they speed
 	  things up.</para>
 
 	<para>Be aware that this is still somewhat experimental, and commits
 	  to the source tree may occasionally break this feature.  If the
 	  world fails to compile using this parameter try again without it
 	  before you report any problems.</para>
       </sect3>
       
       <sect3>
 	<title>Timings</title>
 	<indexterm>
 	  <primary>rebuilding <quote>world</quote></primary>
 	  <secondary>timings</secondary>
 	</indexterm>
 
         <para>Many factors influence the build time, but currently a 500&nbsp;MHz
           &pentium;&nbsp;III with 128&nbsp;MB of RAM takes about 2&nbsp;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>
       </sect3>
     </sect2>
     
     <sect2>
       <title>Compile and Install a New Kernel</title>
       <indexterm>
         <primary>kernel</primary>
 	<secondary>compiling</secondary>
       </indexterm>
 
       <para>To take full advantage of your new system you should 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 your system, it should contain everything necessary to boot your
 	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 your system works you
 	can then build a new kernel based on your normal kernel	configuration
 	file.</para>
 
       <para>On modern versions of FreeBSD it is important to <link
         linkend="make-buildworld">build world</link> before building a
         new kernel.</para>
 
       <note><para>If you want to build a custom kernel, and already have a configuration
 	file, just use <literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal>
 	like this:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput>
 &prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
 
 	<para>In FreeBSD&nbsp;4.2 and older you must replace
 	  <literal>KERNCONF=</literal> with <literal>KERNEL=</literal>.
 	  4.2-STABLE that was fetched before Feb 2nd, 2001 does not
 	  recognize <literal>KERNCONF=</literal>.</para>
       </note>
 
       <para>Note that if you have raised <literal>kern.securelevel</literal>
 	above 1 <emphasis>and</emphasis> you have set either the
 	<literal>noschg</literal> or similar flags to your kernel binary, you
 	might find it necessary to drop into single user mode to use
 	<maketarget>installkernel</maketarget>.  Otherwise you should be able
 	to run both these commands from multi user mode without
 	problems.  See &man.init.8; for details about
 	<literal>kern.securelevel</literal> and &man.chflags.1; for details
 	about the various file flags.</para>
       <para>If you are upgrading to a version of &os; below 4.0 you should
 	use the old kernel build procedure.  However, it is recommended
 	that you use the new version of &man.config.8;, using a command line
 	like this.</para>
       
       <screen>&prompt.root; <userinput>/usr/obj/usr/src/usr.sbin/config/config <replaceable>KERNELNAME</replaceable></userinput></screen>
     </sect2>
 
     <sect2>
       <title>Reboot into Single User Mode</title>
       <indexterm><primary>single-user mode</primary></indexterm>
 
       <para>You should reboot into single user mode to test the new kernel
 	works.  Do this by following the instructions in
 	<xref linkend="makeworld-singleuser">.</para>
     </sect2>
 
     <sect2>
       <title>Install the New System Binaries</title>
 
       <para>If you were building a version of &os; recent enough to have
 	used <command>make buildworld</command> then you should now use
 	<maketarget>installworld</maketarget> to install the new system
 	binaries.</para>
 
       <para>Run</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make installworld</userinput></screen>
 
       <note>
 	<para>If you specified variables on the <command>make
 	    buildworld</command> command line, you must specify the same
 	  variables in the <command>make installworld</command> command
 	  line.  This does not necessarily hold true for other options;
 	  for example, <option>-j</option> must never be used with
 	  <maketarget>installworld</maketarget>.</para>
 	
 	<para>For example, if you ran:</para>
 
 	<screen>&prompt.root; <userinput>make -DNOPROFILE buildworld</userinput></screen>
 
 	<para>you must install the results with:</para>
 
 	<screen>&prompt.root; <userinput>make -DNOPROFILE installworld</userinput></screen>
 
 	<para>otherwise it would try to install profiled libraries that
 	  had not been built during the <command>make buildworld</command>
 	  phase.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Update Files Not Updated by <command>make installworld</command></title>
       
       <para>Remaking the world will not update certain directories (in
 	particular, <filename>/etc</filename>, <filename>/var</filename> and
 	<filename>/usr</filename>) with new or changed configuration files.</para>
 
       <para>The simplest way to update these files is to use
         &man.mergemaster.8;, though it is possible to do it manually
         if you would prefer to do that.  Regardless of which way you
 	choose, be sure to make a backup of <filename>/etc</filename> in
 	case anything goes wrong.</para>
 
     <sect3 id="mergemaster">
       <sect3info>
 	<authorgroup>
 	  <author>
 	    <firstname>Tom</firstname>
 	    <surname>Rhodes</surname>
 	    <contrib>Contributed by </contrib>
 	  </author>
 	</authorgroup>
       </sect3info>
       <title><command>mergemaster</command></title>
         <indexterm><primary><command>mergemaster</command></primary></indexterm>
 
       <para>The &man.mergemaster.8; utility is a Bourne script that will
         aid you in determining the differences between your 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><command>mergemaster</command> was integrated into the FreeBSD base
         system between 3.3-RELEASE and 3.4-RELEASE, which means it is
         present in all -STABLE and -CURRENT systems since 3.3.</para>
 
       <para>To begin simply type <command>mergemaster</command> at your prompt, and
         watch it start going.  <command>mergemaster</command> will then 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 your system.  At this point, 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 line.
         See the &man.diff.1; manual page for more information about the &man.diff.1;
         syntax and how file differences are shown.</para>
 
       <para>&man.mergemaster.8; will then show you each file that displays variances,
         and at this point you will have the option 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; that we
         wish to keep our current file unchanged, and to delete the new version.
         This option is not recommended, unless you see no
         reason to change the current file.  You can get help at any time by
         typing <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 you with a text editor,
         and the contents of both files.  You can now merge them 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,
         the <keycap>l</keycap> key will select the left contents and the
         <keycap>r</keycap> key will select contents from your 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 show you the file differences
         just like &man.mergemaster.8; did before prompting you for an option.</para>
 
       <para>After &man.mergemaster.8; is done with the system files you will be
         prompted for other options.  &man.mergemaster.8; may ask if you want to rebuild
         the password file and/or run &man.MAKEDEV.8; if you run a FreeBSD version prior to 5.0, and will finish up with an option to
         remove left-over temporary files.</para>
       </sect3>
 
       <sect3>
 	<title>Manual Update</title>
 
       <para>If you wish to do the update manually, however,
         you cannot just copy over the files from
 	<filename>/usr/src/etc</filename> to <filename>/etc</filename> and
 	have it work.  Some of these files must be <quote>installed</quote>
 	first.  This is because the <filename>/usr/src/etc</filename>
 	directory <emphasis>is not</emphasis> a copy of what your
 	<filename>/etc</filename> directory should look like.  In addition,
 	there are files that should be in <filename>/etc</filename> that 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="update-dev">next
 	section</link>.</para>
 
       <para>The simplest way to do this 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>Although, in theory, nothing is going to touch this directory
 	  automatically, it is always better to be sure.  So copy your
 	  existing <filename>/etc</filename> directory somewhere safe.
 	  Something like:</para>
 
 	<screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
 
 	<para><option>-R</option> does a recursive copy, <option>-p</option>
 	  preserves times, ownerships on files and suchlike.</para>
       </warning>
       
       <para>You need to build a dummy set of directories to install the new
 	<filename>/etc</filename> and other files into.
 	<filename>/var/tmp/root</filename> is a reasonable choice, and
 	there are a number of subdirectories required under this as
 	well.</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.  (Standard error is
         redirected 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>.  You now have to go through each of these
 	files, determining how they differ with your existing files.</para>
     
       <para>Note that some of the files that will have been installed in
 	<filename>/var/tmp/root</filename> have a leading <quote>.</quote>.  At the
 	time of writing the only files like this are shell startup files in
 	<filename>/var/tmp/root/</filename> and
 	<filename>/var/tmp/root/root/</filename>, although there may be others
 	(depending on when you are reading this).  Make sure you use
 	<command>ls -a</command> to catch them.</para>
     
       <para>The simplest way to do this is to use &man.diff.1; to compare the
 	two files:</para>
     
       <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen>
       
       <para>This will show you the differences between your
 	<filename>/etc/shells</filename> file and the new
 	<filename>/var/tmp/root/etc/shells</filename> file.  Use these to decide whether to
 	merge in changes that you have made or whether to copy over your old
 	file.</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 the world means that you have to update
 	<filename>/etc</filename> frequently as well, which can be a bit of
 	  a chore.</para>
 
 	<para>You can speed this process up by keeping a copy of the last set
 	  of changed files that you merged into <filename>/etc</filename>.
 	  The following procedure gives one idea of how to do this.</para>
 
 	<procedure>
 	  <step>
 	    <para>Make the world as normal.  When you want to update
 	      <filename>/etc</filename> and the other directories, give the
 	      target directory a name based on the current date.  If you were
 	      doing this on the 14th of February 1998 you could do the
 	      following:</para>
 	  
 	    <screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput>
 &prompt.root; <userinput>cd /usr/src/etc</userinput>
 &prompt.root; <userinput>make DESTDIR=/var/tmp/root-19980214 \
     distrib-dirs distribution</userinput></screen>
 	  </step>
 	  
 	  <step>
 	    <para>Merge in the changes from this directory as outlined
 	      above.</para>
 	    
 	    <para><emphasis>Do not</emphasis> remove the
 	      <filename>/var/tmp/root-19980214</filename> directory when you
 	      have finished.</para>
 	  </step>
 	  
 	  <step>
 	    <para>When you have downloaded the latest version of the source
 	      and remade it, follow step 1.  This will give you a new
 	      directory, which might be called
 	      <filename>/var/tmp/root-19980221</filename> (if you wait a week
 	      between doing updates).</para>
 	  </step>
 	  
 	  <step>
 	    <para>You can now see the differences that have been made in the
 	      intervening week using &man.diff.1; to create a recursive diff
 	      between the two directories:</para>
 	      
 	    <screen>&prompt.root; <userinput>cd /var/tmp</userinput>
 &prompt.root; <userinput>diff -r root-19980214 root-19980221</userinput></screen>
 	  
 	    <para>Typically, this will be a much smaller set of differences
 	      than those between
 	      <filename>/var/tmp/root-19980221/etc</filename> and
 	      <filename>/etc</filename>.  Because the set of differences is
 	      smaller, it is easier to migrate those changes across into your
 	      <filename>/etc</filename> directory.</para>
 	  </step>
 	  
 	  <step>
 	    <para>You can now remove the older of the two
 	      <filename>/var/tmp/root-*</filename> directories:</para>
 	      
 	    <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen>
 	  </step>
 	  
 	  <step>
 	    <para>Repeat this process every time you need to merge in changes
 	      to <filename>/etc</filename>.</para>
 	  </step>
 	</procedure>
 
 	<para>You can 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 id="update-dev">
       <title>Update <filename>/dev</filename></title>
       
       <note>
         <indexterm><primary>DEVFS</primary></indexterm>
 	<para>If you are running FreeBSD&nbsp;5.0 or later you can safely
 	  skip this section.  These versions use &man.devfs.5; to
 	  allocate device nodes transparently for the user.</para>
       </note>
 
       <para>In most cases, the &man.mergemaster.8; tool will realize when
         it is necessary to update the device nodes, and offer to complete it
         automatically.  These instructions tell how to update the device
         nodes manually.</para>
       
       <para>For safety's sake, this is a multi-step process.</para>
 
       <procedure>
 	<step>
 	  <para>Copy <filename>/var/tmp/root/dev/MAKEDEV</filename> to
 	    <filename>/dev</filename>:</para>
 
 	  <screen>&prompt.root; <userinput>cp /var/tmp/root/dev/MAKEDEV /dev</userinput></screen>
 	  <indexterm>
 	    <primary><filename>MAKEDEV</filename></primary>
 	  </indexterm>
 
           <para>If you used &man.mergemaster.8; to
             update <filename>/etc</filename>, then your
             <filename>MAKEDEV</filename> script should have been updated
             already, though it cannot hurt to check (with &man.diff.1;)
             and copy it manually if necessary.</para>
 	</step>
 
 	<step>
 	  <para>Now, take a snapshot of your current
 	    <filename>/dev</filename>.  This snapshot needs to contain the
 	    permissions, ownerships, major and minor numbers of each filename,
 	    but it should not contain the time stamps.  The easiest way to do
 	    this is to use &man.awk.1; to strip out some of the
 	    information:</para>
 
 	  <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.out</userinput></screen>
 	</step>
 
 	<step>
 	  <para>Remake all the device nodes:</para>
 	    
 	    <screen>&prompt.root; <userinput>sh MAKEDEV all</userinput></screen>
 	</step>
 
 	<step>
 	  <para>Write another snapshot of the directory, this time to
 	    <filename>/var/tmp/dev2.out</filename>.  Now look through these
 	    two files for any device node that you missed creating.  There should
 	    not be any, but it is better to be safe than sorry.</para>
 
 	  <screen>&prompt.root; <userinput>diff /var/tmp/dev.out /var/tmp/dev2.out</userinput></screen>
 
 	  <para>You are most likely to notice disk slice discrepancies which
 	    will involve commands such as:</para>
 	  
 	    <screen>&prompt.root; <userinput>sh MAKEDEV sd0s1</userinput></screen>
 
 	  <para>to recreate the slice entries.  Your precise circumstances may
 	    vary.</para>
 	</step>
       </procedure>
     </sect2>
     
     <sect2>
       <title>Update <filename>/stand</filename></title>
       
       <note>
 	<para>This step is included only for completeness.  It can safely be
 	  omitted.  If you are using FreeBSD&nbsp;5.2 or later, the
           <filename>/rescue</filename> directory is automatically updated
           for the user with current, statically compiled binaries during
 	  <command>make installworld</command>, thus obsoleting the need
 	  to update <filename>/stand</filename> (which does not exist at
 	  all on FreeBSD&nbsp;5.2 and later).</para>
       </note>
       
       <para>For the sake of completeness, you may want to update the files in
 	<filename>/stand</filename> as well.  These files consist of hard
 	links to the <filename>/stand/sysinstall</filename> binary.  This
 	binary should be statically linked, so that it can work when no other
 	file systems (and in particular <filename>/usr</filename>) have been
 	mounted.</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src/release/sysinstall</userinput>
 &prompt.root; <userinput>make all install</userinput></screen>
     </sect2>
     
     <sect2>
       <title>Rebooting</title>
       
       <para>You are now done.  After you have verified that everything appears
 	to be in the right place you can reboot the system.  A simple
 	&man.shutdown.8; should do it:</para>
 
       <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Finished</title>
       
       <para>You should now have successfully upgraded your &os; system.
 	Congratulations.</para>
       
       <para>If things went slightly wrong, it is easy to rebuild a particular
         piece of the system.  For example, if you accidentally deleted
         <filename>/etc/magic</filename> as part of the upgrade or merge of
         <filename>/etc</filename>, the &man.file.1; command will stop working.
         In this case, the fix would be to run:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
 &prompt.root; <userinput>make all install</userinput></screen>
     </sect2>    
     
     <sect2>
       <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 to this one, as it depends on the
 	      nature of the change.  For example, if you just ran <application>CVSup</application>, and
 	      it has shown 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.
 	      You could just go to the appropriate sub-directories and
 	      <command>make all install</command>, and that's about it.  But
 	      if something major changed, for example
 	      <filename>src/lib/libc/stdlib</filename> then you should either
 	      re-make the world, or at least those parts of it that are
 	      statically linked (as well as anything else you might have added
 	      that is statically linked).</para>
       
 	    <para>At the end of the day, it is your call.  You might be happy
 	      re-making the world every fortnight say, and let changes
 	      accumulate over that fortnight.  Or you might want to re-make
 	      just those things that have changed, and be confident you can
 	      spot all the dependencies.</para>
       
 	    <para>And, of course, this all depends on how often you want to
 	      upgrade, and whether you are tracking &os.stable; or
 	      &os.current;.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>My compile failed with lots of signal 11 (or other signal
 	      number) errors.  What has happened?</para>
 	  </question>
     <indexterm><primary>signal 11</primary></indexterm>
 
 	  <answer>
 
 	    <para>This is normally indicative of hardware problems.
 	      (Re)making the world is an effective way to stress test your
 	      hardware, and will frequently throw up memory problems.  These
 	      normally manifest themselves as the compiler mysteriously dying
 	      on receipt of strange signals.</para>
       
 	    <para>A sure indicator of this is if you can restart the make and
 	      it dies at a different point in the process.</para>
       
 	    <para>In this instance there is little you can do except start
 	      swapping around the components in your machine to determine
 	      which one is failing.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Can I remove <filename>/usr/obj</filename> when I have
 	      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.  In this case, keeping
 	      <filename>/usr/obj</filename> around after you have finished
 	      makes little sense, and will free up a large chunk of disk space
 	      (currently about 340&nbsp;MB).</para>
       
 	    <para>However, if you know what you are doing you can have
 	      <command>make buildworld</command> skip this step.  This will make subsequent
 	      builds run much faster, since most of sources will not need to
 	      be recompiled.  The flip side of this is that subtle dependency
 	      problems can creep in, causing your 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 through the process you got before
 	      you found a problem.</para>
 
 	    <para><emphasis>In general</emphasis> (and this is not a hard and
 	      fast rule) the <command>make buildworld</command> process 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.  The new tools and libraries are
 	      then used to rebuild themselves, and are installed again. The
 	      entire system (now including regular user programs, such as
 		&man.ls.1; or &man.grep.1;) is then rebuilt with the new
 	      system files.</para>
 
 	    <para>If you are at the last stage, and you know it (because you
 	      have looked through the output that you were storing) then you
 	      can (fairly safely) do:</para>
 
 	    <screen><emphasis>&hellip; fix the problem &hellip;</emphasis>
 &prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make -DNOCLEAN 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 then it is
 	      probably fairly safe to do so.</para>
 	    
 	    <para>If you do not see that message, or you are not sure, then 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 in single user mode.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Put the <filename>/usr/src</filename> and
 		  <filename>/usr/obj</filename> directories on separate
 		  file systems held on separate disks.  If possible, put these
 		  disks on separate disk controllers.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Better still, put these file systems across multiple
 		  disks using the &man.ccd.4; (concatenated disk
 		  driver) device.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Turn off profiling (set <quote>NOPROFILE=true</quote> in
 		  <filename>/etc/make.conf</filename>).  You almost certainly
 		  do not need it.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Also in <filename>/etc/make.conf</filename>, set
 		  <makevar>CFLAGS</makevar> to something like <option>-O
 		  -pipe</option>.  The optimization <option>-O2</option> is much
 		  slower, and the optimization difference between
 		  <option>-O</option> and <option>-O2</option> is normally
 		  negligible.  <option>-pipe</option> lets the compiler use
 		  pipes rather than temporary files for communication, which
 		  saves disk access (at the expense of memory).</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Pass the <option>-j<replaceable>n</replaceable></option> option to &man.make.1; to
 		  run multiple processes in parallel.  This usually helps 
 		  regardless of whether you have a single or a multi processor
 		  machine.</para>
 	      </listitem>
 	      
 	      <listitem><para>The file system holding
 		  <filename>/usr/src</filename> can be mounted (or remounted)
 		  with the <option>noatime</option> option.  This prevents the
 		  file system from recording the file access time.  You probably
 		  do not need this information anyway.</para>
 		  
 		  <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen>
 		  
 		  <warning>
 		    <para>The example assumes <filename>/usr/src</filename> is
 		      on its own file system.  If it is not (if it is a part of
 		      <filename>/usr</filename> for example) then you will
 		      need to use that file system mount point, and not
 		      <filename>/usr/src</filename>.</para>
 		  </warning>
 	      </listitem>
 	      
 	      <listitem>
 		<para>The file system holding <filename>/usr/obj</filename> can
 		  be mounted (or remounted) with the <option>async</option>
 		  option.  This causes disk writes to happen asynchronously.
 		  In other words, 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 be a
 		  dramatic performance boost.</para>
 
 		<warning>
 		  <para>Keep in mind that this option makes your 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 thing on
 		    this file system then it is not a problem.  If you have
 		    other, valuable data on the same file system then ensure
 		    your backups are fresh before you enable this
 		    option.</para>
 		</warning>
 		
 		<screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen>
 		
 		<warning>
 		  <para>As above, 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 your environment has no
               extraneous cruft from earlier builds.  This is simple
               enough.</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 you still have problems, send the error and the
               output of <command>uname -a</command> to &a.questions;.
               Be prepared to answer other questions about your
               setup!</para>
           </answer>
         </qandaentry>
       </qandaset>
     </sect2>
   </sect1>
 
   <sect1 id="small-lan">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Mike</firstname>
 	  <surname>Meyer</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Tracking for Multiple Machines</title>
     <indexterm>
       <primary>NFS</primary>
       <secondary>installing multiple machines</secondary>
     </indexterm>
     
     <para>If you have multiple machines that you want to track the
       same source tree, then having all of them download sources and
       rebuild everything seems like a waste of resources: disk space,
       network bandwidth, and CPU cycles.  It is, and 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 id="small-lan-preliminaries">
       <title>Preliminaries</title>
 
       <para>First, identify a set of machines that is going to run
 	the same set of binaries, which we will call a
 	<emphasis>build set</emphasis>.  Each machine can have a
 	custom kernel, but they will be running the same userland
 	binaries.  From that set, choose a machine to be the
 	<emphasis>build machine</emphasis>.  It is going to be the
 	machine that the world and kernel are built on. Ideally, it
 	should be a fast machine that has sufficient spare CPU to
 	run <command>make buildworld</command> and
 	<command>make buildkernel</command>.  You will also want to
 	choose 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 you can afford to have 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 are on two different drives
 	on the build machine, but they can be NFS mounted on that machine
 	as well.  If you have multiple build sets,
 	<filename>/usr/src</filename> should be on one build machine, and
 	NFS mounted on the rest.</para>
 	  
       <para>Finally make sure that
 	<filename>/etc/make.conf</filename> on all the machines in
 	the build set agrees 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 <makevar>KERNCONF</makevar> in
 	<filename>/etc/make.conf</filename>, and the build machine
 	should list them all in <makevar>KERNCONF</makevar>, listing
 	its own kernel first.  The build machine must have the kernel
 	configuration files for each machine in
 	<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>
 	if it is going to build their kernels.</para>
     </sect2>
 
     <sect2>
       <title>The Base System</title>
 
       <para>Now that all that is done, you are ready to build
 	everything.  Build the kernel and world as described in <xref
 	linkend="make-buildworld"> on the build machine,
 	but do not install anything.  After the build has finished, go
 	to the test machine, and install the kernel you just
 	built.  If this machine mounts <filename>/usr/src</filename>
 	and <filename>/usr/obj</filename> via NFS, when you reboot
 	to single user you will need to enable the network and mount
 	them.  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, you can install the new kernel and world and run
 	<command>mergemaster</command> just as you normally would.  When
 	done, reboot to return to normal multi-user operations for this
 	machine.</para>
 
       <para>After you are certain 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>
       <title>Ports</title>
 
       <para>The same ideas can be used for the ports tree.  The first
 	critical step is mounting <filename>/usr/ports</filename> from
 	the same machine to all the machines in the build set.  You can
 	then set up <filename>/etc/make.conf</filename> properly to share
 	distfiles.  You should set <makevar>DISTDIR</makevar> to a
 	common shared directory that is writable by whichever user
 	<username>root</username> is mapped to by your NFS mounts.  Each
 	machine should set <makevar>WRKDIRPREFIX</makevar> to a
 	local build directory.  Finally, if you are going to be
 	building and distributing packages, you should set
 	<makevar>PACKAGES</makevar> to a directory similar to
 	<makevar>DISTDIR</makevar>.</para> 
     </sect2>
   </sect1>
 </chapter>
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml b/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml
index b762cb7a18..b4514cac30 100644
--- a/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml
@@ -1,1262 +1,1267 @@
 <!--
      The FreeBSD Documentation Project
      $FreeBSD$
 -->
 
 <chapter id="desktop">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Christophe</firstname>
         <surname>Juniet</surname>
         <contrib>Contributed by </contrib>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Desktop Applications</title>
 
   <sect1 id="desktop-synopsis">
     <title>Synopsis</title>
 
     <para>FreeBSD can run a wide variety of desktop applications, such
       as browsers and word processors.  Most of these are available as
       packages or can be automatically built from the ports
       collection.  Many new users expect to find these kinds of
       applications on their desktop.  This chapter will show you how
       to install some popular desktop applications effortlessly,
       either from their packages or from the ports collection.</para>
 
     <para>Note that when installing programs from the ports, they are
       compiled from source.  This can take a very long time, depending
       on what you are compiling and the processing power of your
       machine(s).  If building from source takes a prohibitively long
       amount of time for you, you can install most of the programs of
       the ports collection from pre-built packages.</para>
 
     <para>As FreeBSD features Linux binary compatibility, many
       applications originally developed for Linux are available for
       your desktop.  It is strongly recommended that you read
       <xref linkend="linuxemu"> before installing any of the Linux
       applications.  Many of the ports using the Linux binary
       compatibility start with <quote>linux-</quote>.  Remember this
       when you search for a particular port, for instance with
       &man.whereis.1;.  In the following text, it is assumed that you
       have enabled Linux binary compatibility before installing any of
       the Linux applications.</para>
 
     <para>Here are the categories covered by this chapter:</para>
 
     <itemizedlist>
       <listitem>
         <para>Browsers (such as <application>Mozilla</application>,
           <application>&netscape;</application>,
           <application>Opera</application>,
           <application>Firefox</application>,
 	  <application>Konqueror</application>)</para>
       </listitem>
 
       <listitem>
         <para>Productivity (such as
           <application>KOffice</application>,
           <application>AbiWord</application>,
           <application>The GIMP</application>,
           <application>OpenOffice.org</application>)</para>
       </listitem>
 
       <listitem>
         <para>Document Viewers (such as <application>&acrobat.reader;</application>,
           <application>gv</application>,
           <application>Xpdf</application>,
           <application>GQview</application>)</para>
       </listitem>
 
       <listitem>
         <para>Finance (such as
           <application>GnuCash</application>,
           <application>Gnumeric</application>,
           <application>Abacus</application>)</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
         <para>Know how to install additional third-party software
           (<xref linkend="ports">).</para>
       </listitem>
 
       <listitem>
         <para>Know how to install additional Linux software
 	  (<xref linkend="linuxemu">).</para>
       </listitem>
     </itemizedlist>
 
     <para>For information on how to get a multimedia environment, read
       <xref linkend="multimedia">.  If you want to set up and use
       electronic mail, please refer to <xref linkend="mail">.</para>
   </sect1>
 
   <sect1 id="desktop-browsers">
     <title>Browsers</title>
 
+    <indexterm>
+      <primary>browsers</primary>
+      <secondary>web</secondary>
+    </indexterm>
+
     <para>FreeBSD does not come with a particular browser
       pre-installed.  Instead, the
       <ulink url="http://www.FreeBSD.org/ports/www.html">www</ulink>
       directory of the ports collection contains a lot of browsers
       ready to be installed.  If you do not have time to compile
       everything (this can take a very long time in some cases) many
       of them are available as packages.</para>
 
     <para><application>KDE</application> and
       <application>GNOME</application> already provide HTML browsers.
       Please refer to <xref linkend="x11-wm"> for more information on
       how to set up these complete desktops.</para>
 
     <para>If you are looking for light-weight browsers, you should
       investigate the ports collection for
       <filename role="package">www/dillo</filename>,
       <filename role="package">www/links</filename>, or
       <filename role="package">www/w3m</filename>.</para>
 
     <para>This section covers these applications:</para>
 
     <informaltable frame="none" pgwide="1">
       <tgroup cols="4">
         <thead>
           <row>
             <entry>Application Name</entry>
             <entry>Resources Needed</entry>
             <entry>Installation from Ports</entry>
             <entry>Major Dependencies</entry>
           </row>
         </thead>
 
         <tbody>
           <row>
             <entry><application>Mozilla</application></entry>
             <entry>heavy</entry>
             <entry>heavy</entry>
             <entry><application>Gtk+</application></entry>
           </row>
 
           <row>
             <entry><application>&netscape;</application></entry>
             <entry>heavy</entry>
             <entry>light</entry>
             <entry>Linux Binary Compatibility</entry>
           </row>
 
           <row>
             <entry><application>Opera</application></entry>
             <entry>light</entry>
             <entry>light</entry>
 	    <entry>FreeBSD and Linux versions available.  The Linux
 	      version depends on the Linux Binary Compatibility and
 	      <application>linux-openmotif</application>.</entry>
           </row>
 
           <row>
             <entry><application>Firefox</application></entry>
             <entry>medium</entry>
             <entry>heavy</entry>
             <entry><application>Gtk+</application></entry>
           </row>
           
 	  <row>
 	    <entry><application>Konqueror</application></entry>
 	    <entry>medium</entry>
 	    <entry>heavy</entry>
 	    <entry><application>KDE</application> Libraries</entry>
           </row>
         </tbody>
       </tgroup>
     </informaltable>
 
     <sect2>
       <title>Mozilla</title>
       <indexterm>
 	<primary><application>Mozilla</application></primary>
       </indexterm>
 
       <para><application>Mozilla</application> is perhaps the most
         suitable browser for your FreeBSD Desktop.  It is modern,
         stable, and fully ported to FreeBSD.  It features a very
         standards-compliant HTML display engine.  It provides a mail
         and news reader.  It even has a HTML composer if you plan to
         write some web pages yourself.  Users of
         <application>&netscape;</application> will recognize the
         similarities with <application>Communicator</application>
         suite, as both browsers shared the same basis.</para>
 
       <para>On slow machines, with a CPU speed less than 233MHz or
         with less than 64MB of RAM, <application>Mozilla</application>
         can be too resource-consuming to be fully usable.  You may
         want to look at the <application>Opera</application> browser
         instead, described a little later in this chapter.</para>
 
       <para>If you cannot or do not want to compile
         <application>Mozilla</application> for any reason, the FreeBSD
         GNOME team has already done this for you.  Just install the
         package from the network by:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r mozilla</userinput></screen>
 
       <para>If the package is not available, and you have enough time
         and disk space, you can get the source for
         <application>Mozilla</application>, compile it and install it
         on your system.  This is accomplished by:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/www/mozilla</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
       <para>The <application>Mozilla</application> port ensures a
         correct initialization by running the chrome registry setup
         with <username>root</username> privileges.  However, if you
         want to fetch some add-ons like mouse gestures, you must run
         <application>Mozilla</application> as
         <username>root</username> to get them properly
         installed.</para>
 
       <para>Once you have completed the installation of
         <application>Mozilla</application>, you do not need to be
         <username>root</username> any longer.  You can start
         <application>Mozilla</application> as a browser by typing:</para>
 
       <screen>&prompt.user; <userinput>mozilla</userinput></screen>
 
       <para>You can start it directly as a mail and news reader as
         shown below:</para>
 
       <screen>&prompt.user; <userinput>mozilla -mail</userinput></screen>
     </sect2>
     
     <sect2 id="moz-java-flash">
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Tom</firstname>
 	    <surname>Rhodes</surname>
 	    <contrib>Contributed by </contrib>
 	  </author>
 	</authorgroup>
     </sect2info>
 
       <title>Mozilla, &java;, and &macromedia; &flash;</title>
       
       <para>Installing <application>Mozilla</application> is simple, but
 	unfortunately installing <application>Mozilla</application> with
 	support for add-ons like &java; and
 	&macromedia; &flash;
 	consumes both time and disk
 	space.</para>
 
       <para>The first thing is to download the files which will be used
 	with <application>Mozilla</application>.  Take your current web
 	browser up to
 	<ulink url="http://www.sun.com/software/java2/download.html"></ulink> and
 	create an account on their website.  Remember to save the username
 	and password from here as it may be needed in the future.  Download
 	a copy of the file <filename>j2sdk-1_3_1-src.tar.gz</filename> and place this in
 	<filename>/usr/ports/distfiles/</filename> as the port will not
 	fetch it automatically.  This is due to license restrictions.  While
 	we are here, download the <quote>java environment</quote> from
 	<ulink url="http://java.sun.com/webapps/download/Display?BundleId=7905"></ulink>.
 	The filename is <filename>j2sdk-1_3_1_08-linux-i586.bin</filename> and is large (about 25
 	megabytes!).  Like before, this file must be placed into
 	<filename>/usr/ports/distfiles/</filename>.  Finally download a copy
 	of the <quote>java patchkit</quote> from
 	<ulink url="http://www.eyesbeyond.com/freebsddom/java/"></ulink>
 	and place it
 	into <filename>/usr/ports/distfiles/</filename>.</para>
       
       <para>Install the <filename role="package">java/jdk13</filename> port
 	with the standard <command>make install clean</command> and
 	then install the <filename role="package">www/flashpluginwrapper</filename>
 	port.  This port requires
 	<filename role="package">emulators/linux_base</filename> which is a
 	large port.  True that other <application>&flash;</application> plugins exist, however they have
 	not worked for me.</para>
 
       <para>Install the <filename role="package">www/mozilla</filename> port,
 	if <application>Mozilla</application> is not already installed.</para>
 
       <para>Now copy the <application>&flash;</application> plug-in files with:</para>
     
       <screen>&prompt.root; <userinput>cp /usr/local/lib/flash/libflashplayer.so \
 	/usr/X11R6/lib/browser_plugins/libflashplayer_linux.so</userinput></screen>
 
       <screen>&prompt.root; <userinput>cp /usr/local/lib/flash/ShockwaveFlash.class \
 	/usr/X11R6/lib/browser_plugins/</userinput></screen>
 
     <para>Now add the following lines to the top of (but right under
       <literal>#!/bin/sh</literal>) <application>Mozilla</application> startup script:
       <filename>/usr/X11R6/bin/mozilla</filename>.</para>
 
 <programlisting>LD_PRELOAD=/usr/local/lib/libflashplayer.so.1
 export LD_PRELOAD</programlisting>
 
       <para>This will enable the <application>&flash;</application> plug-in.</para>
 
       <para>Now just start <application>Mozilla</application> with:</para>
 
       <screen>&prompt.user; <userinput>mozilla &amp;</userinput></screen>
 
       <para>And access the <guimenuitem>About Plug-ins</guimenuitem> option from the
 	<guimenu>Help</guimenu> menu.  A list should appear with all the currently
 	available plugins.  <application>&java;</application> and
 	<application>&shockwave; &flash;</application> should both be listed.</para>
     
     </sect2>
 
     <sect2>
       <title>&netscape;</title>
       <indexterm>
 	<primary><application>Netscape</application></primary>
       </indexterm>
 
       <para>The ports collection contains several versions of the
         &netscape; browser.  Since the native FreeBSD ones contain a
         serious security bug, installing them is strongly
         discouraged.  Instead, use a more recent Linux or DIGITAL UNIX
         version.</para>
 
       <para>The latest stable release of the &netscape; browser is
         <application>&netscape; 7</application>.  It can be installed
         from the ports collection:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/www/netscape7</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
       <para>There are localized versions in the French, German, and
         Japanese categories.</para>
 
       <caution>
         <para><application>&netscape; 4.x</application> versions are not
           recommended because they are not compliant with today's
           standards.  However, <application>&netscape; 7.x</application>
           and newer versions are only available for the &i386;
           platform.</para>
       </caution>
     </sect2>
 
     <sect2>
       <title>Opera</title>
       <indexterm>
 	<primary><application>Opera</application></primary>
       </indexterm>
 
       <para><application>Opera</application> is a very fast,
         full-featured, and standards-compliant browser.  It comes in
         two favors: a <quote>native</quote> FreeBSD version and a
         version that runs under Linux emulation.
 	For each operating system, there is a no-cost version of the
         browser that displays advertising and an ad-free 
         version that can be purchased on the <ulink
         url="http://www.opera.com/">Opera web site</ulink>.</para>
 
       <para>To browse the Web with the FreeBSD version of <application>Opera</application>,
         install the package:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r opera</userinput></screen>
 
       <para>Some FTP sites do not have all the packages, but the same
         result can be obtained with the ports collection by
         typing:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/www/opera</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
       <para>To install the Linux version of
 	<application>Opera</application>, substitute
 	<literal>linux-opera</literal> in place of
 	<literal>opera</literal> in the examples above.  The Linux
 	version is useful in situations requiring the use of plug-ins
 	that are only available for Linux, such as <application>Adobe
 	&acrobat.reader;</application>.  In all other respects, the
 	FreeBSD and Linux versions appear to be functionally
 	identical.</para>
 
     </sect2>
 
     <sect2>
       <title>Firefox</title>
       <indexterm>
 	<primary><application>Firefox</application></primary>
       </indexterm>
 
       <para><application>Firefox</application> is the next-generation
          browser based on the <application>Mozilla</application>
          codebase. <application>Mozilla</application> is a complete
          suite of applications, such as a browser, a mail client, a chat
          client and much more. <application>Firefox</application> is
          just a browser, which makes it smaller and faster.</para>
 
       <para>Install the package by typing:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r firefox</userinput></screen>
 
       <para>You can also use the ports collection if you
          prefer to compile from source code:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/www/firefox</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
     </sect2>
     <sect2>
       <title>Konqueror</title>
       <indexterm>
         <primary><application>Konqueror</application></primary>
       </indexterm>
 
       <para><application>Konqueror</application> is part of
 	<application>KDE</application> but it can also be used outside
        	of <application>KDE</application> by installing
 	<filename role="package">x11/kdebase3</filename>.
 	<application>Konqueror</application> is much more than a browser,
 	it is also a file manager and a multimedia viewer.</para>
 
       <para><application>Konqueror</application> also comes with a set of plugins,
 	available in <filename role="package">misc/konq-plugins</filename>.</para>
 
       <para><application>Konqueror</application> also supports <application>&flash;</application> and a How To
 	is available at <ulink url="http://freebsd.kde.org/howto.php"></ulink>.</para>
     </sect2>
   </sect1>
 
   <sect1 id="desktop-productivity">
     <title>Productivity</title>
 
     <para>When it comes to productivity, new users often look for a
        good office suite or a friendly word processor.  While some
        <link linkend="x11-wm">desktop environments</link> like
        <application>KDE</application> already provide an office suite,
        there is no default application.  FreeBSD provides all that is
        needed, regardless of your desktop environment.</para>
 
     <para>This section covers these applications:</para>
 
     <informaltable frame="none" pgwide="1">
       <tgroup cols="4">
         <thead>
           <row>
             <entry>Application Name</entry>
             <entry>Resources Needed</entry>
             <entry>Installation from Ports</entry>
             <entry>Major Dependencies</entry>
           </row>
         </thead>
 
         <tbody>
           <row>
             <entry><application>KOffice</application></entry>
             <entry>light</entry>
             <entry>heavy</entry>
             <entry><application>KDE</application></entry>
           </row>
 
           <row>
             <entry><application>AbiWord</application></entry>
             <entry>light</entry>
             <entry>light</entry>
             <entry><application>Gtk+</application> or <application>GNOME</application></entry>
           </row>
 
           <row>
             <entry><application>The Gimp</application></entry>
             <entry>light</entry>
             <entry>heavy</entry>
             <entry><application>Gtk+</application></entry>
           </row>
 
           <row>
             <entry><application>OpenOffice.org</application></entry>
             <entry>heavy</entry>
             <entry>huge</entry>
             <entry><application>GCC 3.1</application>, <application>&jdk; 1.3</application>, <application>Mozilla</application></entry>
           </row>
         </tbody>
       </tgroup>
     </informaltable>
    
     <sect2>
       <title>KOffice</title>
       <indexterm>
 	<primary><application>KOffice</application></primary>
       </indexterm>
       <indexterm>
 	<primary>office suite</primary>
 	<secondary><application>KOffice</application></secondary>
       </indexterm>
 
       <para>The KDE community has provided its desktop environment
         with an office suite which can be used outside
         <application>KDE</application>.  It includes the four standard
         components that can be found in other office suites.
         <application>KWord</application> is the word processor,
         <application>KSpread</application> is the spreadsheet program,
         <application>KPresenter</application> manages slide
         presentations, and <application>Kontour</application> lets you
         draw graphical documents.</para>
 
       <para>Before installing the latest
         <application>KOffice</application>, make sure you have an
         up-to-date version of <application>KDE</application>.</para>
 
       <para>To install <application>KOffice</application> as a
         package, issue the following command:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r koffice</userinput></screen>
 
       <para>If the package is not available, you can use the ports
         collection.  For instance, to install
         <application>KOffice</application> for
         <application>KDE3</application>, do:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/editors/koffice-kde3</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
     </sect2>
 
     <sect2>
       <title>AbiWord</title>
       <indexterm>
 	<primary><application>AbiWord</application></primary>
       </indexterm>
 
       <para><application>AbiWord</application> is a free word
         processing program similar in look and feel to <application>&microsoft; Word</application>.
         It is suitable for typing papers, letters, reports, memos, and
         so forth.  It is very fast, contains many features, and is
         very user-friendly.</para>
 
       <para><application>AbiWord</application> can import or export
         many file formats, including some proprietary ones like
         Microsoft <filename>.doc</filename>.</para>
 
       <para><application>AbiWord</application> is available as a
         package.  You can install it by:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r AbiWord2</userinput></screen>
 
       <para>If the package is not available, it can be compiled from
         the ports collection.  The ports collection should be more
         up to date.  It can be done as follows:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/editors/AbiWord2</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
     </sect2>
 
     <sect2>
       <title>The GIMP</title>
       <indexterm>
 	<primary><application>The GIMP</application></primary>
       </indexterm>
 
       <para>For image authoring or picture retouching,
         <application>The GIMP</application> is a very sophisticated
         image manipulation program.  It can be used as a simple paint
         program or as a quality photo retouching suite.  It supports a
         large number of plug-ins and features a scripting interface.
         <application>The GIMP</application> can read and write a wide
         range of file formats.  It supports interfaces with scanners
         and tablets.</para>
 
       <para>You can install the package by issuing this
         command:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r gimp</userinput></screen>
 
       <para>If your FTP site does not have this package, you can use
         the ports collection.  The
         <ulink url="http://www.FreeBSD.org/ports/graphics.html">graphics</ulink>
         directory of the ports collection also contains
         <application>The Gimp Manual</application>.  Here is how to
         get them installed:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/graphics/gimp</userinput>
 &prompt.root; <userinput>make install clean</userinput>
 &prompt.root; <userinput>cd /usr/ports/graphics/gimp-manual-pdf</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
       <note>
         <para>The
           <ulink url="http://www.FreeBSD.org/ports/graphics.html">graphics</ulink>
           directory of the ports collection holds the development
           version of <application>The GIMP</application> in
           <filename role="package">graphics/gimp-devel</filename>.
           An HTML version of
           <application>The Gimp Manual</application> is available from
           <filename role="package">graphics/gimp-manual-html</filename>.</para>
        </note>
     </sect2>
 
     <sect2>
       <title>OpenOffice.org</title>
       <indexterm>
 	<primary><application>OpenOffice.org</application></primary>
       </indexterm>
       <indexterm>
 	<primary>office suite</primary>
 	<secondary><application>OpenOffice.org</application></secondary>
       </indexterm>
 
       <para><application>OpenOffice.org</application> includes all of the
         mandatory applications in a complete office productivity
         suite: a word processor, a spreadsheet, a presentation manager,
         and a drawing program.  Its user interface is very similar
         to other office suites, and it can import and export in various
         popular file formats.  It is available in a number of
         different languages including interfaces, spell checkers, and
         dictionaries.</para>
 
       <para>The word processor of
         <application>OpenOffice.org</application> uses a native XML
         file format for increased portability and flexibility.  The
         spreadsheet program features a macro language and it can be
         interfaced with external databases.
         <application>OpenOffice.org</application> is already stable
         and runs natively on &windows;, &solaris;, Linux, FreeBSD,
         and &macos;&nbsp;X.  More
         information about <application>OpenOffice.org</application>
         can be found on the
 	<ulink url="http://www.openoffice.org/">OpenOffice web site</ulink>.
 	For FreeBSD specific information, and to directly
 	download packages use the <ulink
 	url="http://porting.openoffice.org/freebsd/">FreeBSD OpenOffice
 	Porting Team</ulink>'s web site.</para>
 
       <para>To install <application>OpenOffice.org</application>,
         do:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r openoffice</userinput></screen>
 
       <para>Once the package is installed, you must run the setup
         program and choose a <option>standard workstation installation</option>.
         Run this command as the user who will use
         <application>OpenOffice.org</application>:</para>
 
       <screen>&prompt.user; <userinput>openoffice-setup</userinput></screen>
 
       <para>If the <application>OpenOffice.org</application> packages
         are not available, you still have the option to compile the
         port.  However, you must bear in mind that it requires a lot of
         disk space and a fairly long time to compile.</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/editors/openoffice-1.1</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
       <para>Once this is done, run the setup as the user who will use
         <application>OpenOffice.org</application> and choose a
         <option>standard workstation installation</option> by:</para>
 
       <screen>&prompt.user; <userinput>cd /usr/ports/editors/openoffice-1.1</userinput>
 &prompt.user; <userinput>make install-user</userinput></screen>
 
       <para>If you want to use a localized version, here are the available
         ports:</para>
 
       <informaltable frame="none" pgwide="1">
         <tgroup cols="2">
           <colspec colwidth="1*">
           <colspec colwidth="2*">
           <thead>
             <row>
               <entry>Language</entry>
               <entry>Port</entry>
             </row>
           </thead>
 
           <tbody>
             <row>
               <entry>Catalan</entry>
               <entry><filename role="package">editors/openoffice-1.1-ca</filename></entry>
             </row>
 
             <row>
               <entry>Czech</entry>
               <entry><filename role="package">editors/openoffice-1.1-cs</filename></entry>
             </row>
 
             <row>
               <entry>Danish</entry>
               <entry><filename role="package">editors/openoffice-1.1-dk</filename></entry>
             </row>
 
             <row>
               <entry>Greek</entry>
               <entry><filename role="package">editors/openoffice-1.1-el</filename></entry>
             </row>
 
             <row>
               <entry>Spanish</entry>
               <entry><filename role="package">editors/openoffice-1.1-es</filename></entry>
             </row>
 
             <row>
               <entry>Estonian</entry>
               <entry><filename role="package">editors/openoffice-1.1-et</filename></entry>
             </row>
 
             <row>
               <entry>Finnish</entry>
               <entry><filename role="package">editors/openoffice-1.1-fi</filename></entry>
             </row>
 
             <row>
               <entry>Italian</entry>
               <entry><filename role="package">editors/openoffice-1.1-it</filename></entry>
             </row>
 
             <row>
               <entry>Dutch</entry>
               <entry><filename role="package">editors/openoffice-1.1-nl</filename></entry>
             </row>
 
             <row>
               <entry>Swedish</entry>
               <entry><filename role="package">editors/openoffice-1.1-se</filename></entry>
             </row>
 
             <row>
               <entry>Slovak</entry>
               <entry><filename role="package">editors/openoffice-1.1-sk</filename></entry>
             </row>
 
             <row>
               <entry>Slovenian</entry>
               <entry><filename role="package">editors/openoffice-1.1-sl_SI</filename></entry>
             </row>
 
             <row>
               <entry>Turkish</entry>
               <entry><filename role="package">editors/openoffice-1.1-tr</filename></entry>
             </row>
 
             <row>
               <entry>Arabic</entry>
               <entry><filename role="package">arabic/openoffice-1.1</filename></entry>
             </row>
 
             <row>
               <entry>Chinese (Simplified)</entry>
               <entry><filename role="package">chinese/openoffice-1.1-zh_CN</filename></entry>
             </row>
 
             <row>
               <entry>Chinese (Traditional)</entry>
               <entry><filename role="package">chinese/openoffice-1.1-zh_TW</filename></entry>
             </row>
 
             <row>
               <entry>French</entry>
               <entry><filename role="package">french/openoffice-1.1</filename></entry>
             </row>
 
             <row>
               <entry>German</entry>
               <entry><filename role="package">german/openoffice-1.1</filename></entry>
             </row>
 
             <row>
               <entry>Hungarian</entry>
               <entry><filename role="package">hungarian/openoffice-1.1</filename></entry>
             </row>
 
             <row>
               <entry>Japanese</entry>
               <entry><filename role="package">japanese/openoffice-1.1</filename></entry>
             </row>
 
             <row>
               <entry>Korean</entry>
               <entry><filename role="package">korean/openoffice-1.1</filename></entry>
             </row>
 	    
             <row>
               <entry>Polish</entry>
               <entry><filename role="package">polish/openoffice-1.1</filename></entry>
             </row>
 	    
             <row>
               <entry>Portuguese (Brazil)</entry>
               <entry><filename role="package">portuguese/openoffice-1.1-pt_BR</filename></entry>
             </row>
 
             <row>
               <entry>Portuguese</entry>
               <entry><filename role="package">portuguese/openoffice-1.1-pt_PT</filename></entry>
             </row>
 
             <row>
               <entry>Russian</entry>
               <entry><filename role="package">russian/openoffice-1.1</filename></entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
     </sect2>
   </sect1>
 
   <sect1 id="desktop-viewers">
     <title>Document Viewers</title>
 
     <para>Some new document formats have recently gained popularity.
       The standard viewers they require may not be available in the
       base system.  We will see how to install them in this
       section.</para>
 
     <para>This section covers these applications:</para>
 
     <informaltable frame="none" pgwide="1">
       <tgroup cols="4">
         <thead>
           <row>
             <entry>Application Name</entry>
             <entry>Resources Needed</entry>
             <entry>Installation from Ports</entry>
             <entry>Major Dependencies</entry>
           </row>
         </thead>
 
         <tbody>
           <row>
             <entry><application>&acrobat.reader;</application></entry>
             <entry>light</entry>
             <entry>light</entry>
             <entry>Linux Binary Compatibility</entry>
           </row>
 
           <row>
             <entry><application>gv</application></entry>
             <entry>light</entry>
             <entry>light</entry>
             <entry><application>Xaw3d</application></entry>
           </row>
 
           <row>
             <entry><application>Xpdf</application></entry>
             <entry>light</entry>
             <entry>light</entry>
             <entry><application>FreeType</application></entry>
           </row>
 
           <row>
             <entry><application>GQview</application></entry>
             <entry>light</entry>
             <entry>light</entry>
             <entry><application>Gtk+</application> or <application>GNOME</application></entry>
           </row>
         </tbody>
       </tgroup>
     </informaltable>
 
     <sect2>
       <title>&acrobat.reader;</title>
       <indexterm>
 	<primary><application>Acrobat Reader</application></primary>
       </indexterm>
       <indexterm>
 	<primary>PDF</primary>
 	<secondary>viewing</secondary>
       </indexterm>
 
       <para>Many documents are now distributed as PDF files,
         which stands for <quote>Portable Document Format</quote>.  One
         of the recommended viewers for these types of files is
         <application>&acrobat.reader;</application>, released by Adobe
         for Linux.  As FreeBSD can run Linux binaries, it is also
         available for FreeBSD.</para>
 
       <para>To install the <application>&acrobat.reader; 5</application>
         package, do:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r acroread</userinput></screen>
 
       <para>As usual, if the package is not available or you want the
         latest version, you can use the ports collection as
         well:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/print/acroread5</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
     </sect2>
 
     <sect2>
       <title>gv</title>
       <indexterm>
 	<primary><application>gv</application></primary>
       </indexterm>
       <indexterm>
 	<primary>PDF</primary>
 	<secondary>viewing</secondary>
       </indexterm>
       <indexterm>
 	<primary>PostScript</primary>
 	<secondary>viewing</secondary>
       </indexterm>
 
       <para><application>gv</application> is a &postscript; and PDF
         viewer.  It is originally based on
         <application>ghostview</application> but it has a nicer look
         thanks to the <application>Xaw3d</application> library.  It is fast and its interface is
         clean.  <application>gv</application> has many features like
         orientation, paper size, scale, or antialias.  Almost any
         operation can be done either from the keyboard or the
         mouse.</para>
 
       <para>To install <application>gv</application> as a package,
         do:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r gv</userinput></screen>
 
       <para>If you cannot get the package, you can use the ports
         collection:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/print/gv</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Xpdf</title>
       <indexterm>
 	<primary><application>Xpdf</application></primary>
       </indexterm>
       <indexterm>
 	<primary>PDF</primary>
 	<secondary>viewing</secondary>
       </indexterm>
 
       <para>If you want a small FreeBSD PDF viewer,
         <application>Xpdf</application> is a light-weight and
         efficient viewer.  It requires very few resources and is
         very stable.  It uses the standard X fonts and does not
         require <application>&motif;</application> or any other X toolkit.</para>
 
       <para>To install the <application>Xpdf</application> package,
         issue this command:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r xpdf</userinput></screen>
 
       <para>If the package is not available or you prefer to use the
         ports collection, do:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/graphics/xpdf</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
       <para>Once the installation is complete, you can launch
         <application>Xpdf</application> and use the right mouse button
         to activate the menu.</para>
     </sect2>
 
     <sect2>
       <title>GQview</title>
       <indexterm>
 	<primary><application>GQview</application></primary>
       </indexterm>
 
       <para><application>GQview</application> is an image manager.
         You can view a file with a single click, launch an external
         editor, get thumbnail previews, and much more.  It also
         features a slideshow mode and some basic file operations.  You
         can manage image collections and easily find duplicates.
         <application>GQview</application> can do full screen viewing
         and supports internationalization.</para>
 
       <para>If you want to install the
         <application>GQview</application> package, do:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r gqview</userinput></screen>
 
       <para>If the package is not available or you prefer to use the
         ports collection, do:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/graphics/gqview</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
     </sect2>
   </sect1>
 
   <sect1 id="desktop-finance">
     <title>Finance</title>
 
     <para>If, for any reason, you would like to manage your personal
       finances on your FreeBSD Desktop, there are some powerful and
       easy to use applications ready to be installed.  Some of them
       are compatible with widespread file formats like those of
       <application><trademark class="registered">Quicken</trademark></application> or <application>Excel</application> documents.</para>
 
     <para>This section covers these applications:</para>
      
     <informaltable frame="none" pgwide="1">
       <tgroup cols="4">
         <thead>
           <row>
             <entry>Application Name</entry>
             <entry>Resources Needed</entry>
             <entry>Installation from Ports</entry>
             <entry>Major Dependencies</entry>
           </row>
         </thead>
 
         <tbody>
           <row>
             <entry><application>GnuCash</application></entry>
             <entry>light</entry>
             <entry>heavy</entry>
             <entry><application>GNOME</application></entry>
           </row>
 
           <row>
             <entry><application>Gnumeric</application></entry>
             <entry>light</entry>
             <entry>heavy</entry>
             <entry><application>GNOME</application></entry>
           </row>
 
           <row>
             <entry><application>Abacus</application></entry>
             <entry>light</entry>
             <entry>light</entry>
             <entry><application>Tcl/Tk</application></entry>
           </row>
         </tbody>
       </tgroup>
     </informaltable>
    
     <sect2>
       <title>GnuCash</title>
       <indexterm>
 	<primary><application>GnuCash</application></primary>
       </indexterm>
 
       <para><application>GnuCash</application> is part of the
         <application>GNOME</application> effort to provide
         user-friendly yet powerful applications to end-users.  With
         <application>GnuCash</application>, you can keep track of your
         income and expenses, your bank accounts, or your stocks.  It
         features an intuitive interface while remaining very
         professional.</para>
 
       <para><application>GnuCash</application> provides a smart
         register, a hierarchical system of accounts, many keyboard
         accelerators and auto-completion methods.  It can split a
         single transaction into several more detailed pieces.
         <application>GnuCash</application> can import and merge
         <application>Quicken</application> QIF files.  It also handles most international date
         and currency formats.</para>
 
       <para>To install <application>GnuCash</application> on your
         system, do:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r gnucash</userinput></screen>
 
       <para>If the package is not available, you can use the ports
         collection:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/finance/gnucash</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Gnumeric</title>
       <indexterm>
 	<primary><application>Gnumeric</application></primary>
       </indexterm>
       <indexterm>
 	<primary>spreadsheet</primary>
 	<secondary><application>Gnumeric</application></secondary>
       </indexterm>
 
       <para><application>Gnumeric</application> is a spreadsheet, part
         of the <application>GNOME</application> desktop environment.
         It features convenient automatic <quote>guessing</quote> of user
         input according to the cell format and an autofill system for
         many sequences.  It can import files in a number of popular
         formats like those of <application>Excel</application>, <application>Lotus 1-2-3</application>, or <application>Quattro Pro</application>.
         <application>Gnumeric</application> supports graphs through
         the <filename role="package">math/guppi</filename> graphing
         program.  It has a large number of built-in functions and
         allows all of the usual cell formats such as number, currency,
         date, time, and much more.</para>
 
       <para>To install <application>Gnumeric</application> as a
         package, type in:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r gnumeric</userinput></screen>
 
       <para>If the package is not available, you can use the ports
         collection by doing:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/math/gnumeric</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Abacus</title>
       <indexterm>
 	<primary><application>Abacus</application></primary>
       </indexterm>
       <indexterm>
 	<primary>spreadsheet</primary>
 	<secondary><application>Abacus</application></secondary>
       </indexterm>
 
       <para><application>Abacus</application> is a small and easy to
         use spreadsheet.  It includes many built-in functions useful
         in several domains such as statistics, finances, and
         mathematics.  It can import and export the <application>Excel</application> file format.
         <application>Abacus</application> can produce &postscript;
         output.</para>
 
       <para>To install <application>Abacus</application> from its
         package, do:</para>
 
       <screen>&prompt.root; <userinput>pkg_add -r abacus</userinput></screen>
 
       <para>If the package is not available, you can use the ports
         collection by doing:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/deskutils/abacus</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
     </sect2>
   </sect1>
 
   <sect1 id="desktop-summary">
     <title>Summary</title>
 
     <para>While FreeBSD is popular among ISPs for its performance and
       stability, it is quite ready for day-to-day use as a desktop.
       With several thousand applications available as
       <ulink url="http://www.FreeBSD.org/where.html">packages</ulink> or
       <ulink url="http://www.FreeBSD.org/ports/index.html">ports</ulink>,
       you can build a perfect desktop that suits all your needs.</para>
 
     <para>Once you have achieved the installation of your desktop, you
       may want to go one step further with
       <filename role="package">misc/instant-workstation</filename>.
       This <quote>meta-port</quote> allows you to build a typical set
       of ports for a workstation.  You can customize it by editing
       <filename>/usr/ports/misc/instant-workstation/Makefile</filename>.
       Follow the syntax used for the default set to add or remove
       ports, and build it with the usual procedure.
       Eventually, you will be able to create a big package that
       corresponds to your very own desktop and install it to your
       other workstations!</para>
 
     <para>Here is a quick review of all the desktop applications
       covered in this chapter:</para>
 
     <informaltable frame="none" pgwide="1">
       <tgroup cols="3">
         <thead>
           <row>
             <entry>Application Name</entry>
 	    <entry>Package Name</entry>
 	    <entry>Ports Name</entry>
 	  </row>
 	</thead>
 
 	<tbody>
 	  <row>
             <entry><application>Mozilla</application></entry>
 	    <entry><literal>mozilla</literal></entry>
 	    <entry><filename role="package">www/mozilla</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>&netscape;</application></entry>
 	    <entry><literal>linux-netscape7</literal></entry>
 	    <entry><filename role="package">www/netscape7</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>Opera</application></entry>
 	    <entry><literal>opera</literal></entry>
 	    <entry><filename role="package">www/opera</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>Firefox</application></entry>
 	    <entry><literal>firefox</literal></entry>
 	    <entry><filename role="package">www/firefox</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>KOffice</application></entry>
 	    <entry><literal>koffice-kde3</literal></entry>
 	    <entry><filename role="package">editors/koffice-kde3</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>AbiWord</application></entry>
 	    <entry><literal>AbiWord2</literal></entry>
 	    <entry><filename role="package">editors/AbiWord2</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>The GIMP</application></entry>
 	    <entry><literal>gimp</literal></entry>
 	    <entry><filename role="package">graphics/gimp</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>OpenOffice.org</application></entry>
 	    <entry><literal>openoffice</literal></entry>
 	    <entry><filename role="package">editors/openoffice-1.1</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>&acrobat.reader;</application></entry>
 	    <entry><literal>acroread</literal></entry>
 	    <entry><filename role="package">print/acroread5</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>gv</application></entry>
 	    <entry><literal>gv</literal></entry>
 	    <entry><filename role="package">print/gv</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>Xpdf</application></entry>
 	    <entry><literal>xpdf</literal></entry>
 	    <entry><filename role="package">graphics/xpdf</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>GQview</application></entry>
 	    <entry><literal>gqview</literal></entry>
 	    <entry><filename role="package">graphics/gqview</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>GnuCash</application></entry>
 	    <entry><literal>gnucash</literal></entry>
 	    <entry><filename role="package">finance/gnucash</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>Gnumeric</application></entry>
 	    <entry><literal>gnumeric</literal></entry>
 	    <entry><filename role="package">math/gnumeric</filename></entry>
 	  </row>
 
 	  <row>
             <entry><application>Abacus</application></entry>
 	    <entry><literal>abacus</literal></entry>
 	    <entry><filename role="package">deskutils/abacus</filename></entry>
 	  </row>
         </tbody>
       </tgroup>
     </informaltable>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
index 7d8855d9d1..d93cfd7b69 100644
--- a/en_US.ISO8859-1/books/handbook/install/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
@@ -1,5605 +1,5615 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="install">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured, reorganized, and parts
 	  rewritten by </contrib>
       </author>
     </authorgroup>
 
     <authorgroup>
       <author>
 	<firstname>Randy</firstname>
 	<surname>Pratt</surname>
 	<contrib>The sysinstall walkthrough, screenshots, and general
 	  copy by </contrib>
       </author>
     </authorgroup>
     <!-- January 2000 -->
   </chapterinfo>
 
   <title>Installing FreeBSD</title>
 
   <sect1 id="install-synopsis">
     <title>Synopsis</title>
 
     <indexterm><primary>installation</primary></indexterm>
 
     <para>FreeBSD is provided with a text-based, easy to use installation
       program called <application>sysinstall</application>.  This is the
       default installation program for FreeBSD, although vendors are free to
       provide their own installation suite if they wish.  This chapter
       describes how to use <application>sysinstall</application> to install
       FreeBSD.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How to create the FreeBSD installation disks.</para>
       </listitem>
       
       <listitem>
 	<para>How FreeBSD refers to, and subdivides, your hard disks.</para>
       </listitem>
 
       <listitem>
 	<para>How to start <application>sysinstall</application>.</para>
       </listitem>
 
       <listitem>
 	<para>The questions <application>sysinstall</application> will ask
 	  you, what they mean, and how to answer them.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Read the supported hardware list that shipped with the version
 	  of FreeBSD you are installing, and verify that your hardware is
 	  supported.</para>
       </listitem>
     </itemizedlist>
 
     <note>
       <para>In general, these installation instructions are written
         for &i386; (<quote>PC compatible</quote>) architecture
         computers.  Where applicable, instructions specific to other
         platforms (for example, Alpha) will be listed.  Although this
 	guide is kept as up to date as possible, you may find minor
 	differences between the installer and what is shown here.  It is
 	suggested that you use this chapter as a general guide rather 
 	than a literal installation manual.</para>
     </note>
 
   </sect1>
 
   <sect1 id="install-pre">
     <title>Pre-installation Tasks</title>
 
     <sect2 id="install-inventory">
       <title>Inventory Your Computer</title>
 
       <para>Before installing FreeBSD you should attempt to inventory the
 	components in your computer.  The FreeBSD installation routines will
 	show you the components (hard disks, network cards, CDROM drives, and
 	so forth) with their model number and manufacturer.  FreeBSD will also
 	attempt to determine the correct configuration for these devices,
 	which includes information about IRQ and IO port usage.  Due to the
 	vagaries of PC hardware this process is not always completely
 	successful, and you may need to correct FreeBSD's determination of
 	your configuration.</para>
 
       <para>If you already have another operating system installed, such as
 	&windows; or Linux, it is a good idea to use the facilities provided
 	by those operating systems to see how your hardware is already
 	configured.  If you are not sure what settings an expansion
 	card is using, you may find it printed on the card itself.  Popular IRQ
 	numbers are 3, 5, and 7, and IO port addresses are normally written as
 	hexadecimal numbers, such as 0x330.</para>
 
       <para>We recommend you print or write down this information before
 	installing FreeBSD.  It may help to use a table, like this:</para>
 
       <table pgwide="1" frame="none">
 	<title>Sample Device Inventory</title>
 
 	<tgroup cols="4">
           <colspec colwidth="2*">
           <colspec colwidth="1*">
           <colspec colwidth="1*">
           <colspec colwidth="4*">
 	  <thead>
 	    <row>
 	      <entry>Device Name</entry>
 
 	      <entry>IRQ</entry>
 
 	      <entry>IO port(s)</entry>
 
 	      <entry>Notes</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>First hard disk</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>40&nbsp;GB, made by Seagate, first IDE master</entry>
 	    </row>
 
 	    <row>
 	      <entry>CDROM</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>First IDE slave</entry>
 	    </row>
 
 	    <row>
 	      <entry>Second hard disk</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>20&nbsp;GB, made by IBM, second IDE master</entry>
 	    </row>
 
 	    <row>
 	      <entry>First IDE controller</entry>
 
 	      <entry>14</entry>
 
 	      <entry>0x1f0</entry>
 
 	      <entry></entry>
 	    </row>
 
 	    <row>
 	      <entry>Network card</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>&intel; 10/100</entry>
 	    </row>
 
 	    <row>
 	      <entry>Modem</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>&tm.3com; 56K faxmodem, on COM1</entry>
 	    </row>
 
 	    <row>
 	      <entry>&hellip;</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
     </sect2>
 
     <sect2>
       <title>Backup Your Data</title>
       
       <para>If the computer you will be installing FreeBSD on contains
 	valuable data, then ensure you have it backed up, and that you have
 	tested the backups before installing FreeBSD.  The FreeBSD
 	installation routine will prompt you before writing any
 	data to your disk, but once that process has started it cannot be
 	undone.</para>
     </sect2>
 
     <sect2 id="install-where">
       <title>Decide Where to Install FreeBSD</title>
 
       <para>If you want FreeBSD to use your entire hard disk, then there is nothing
 	more to concern yourself with at this point &mdash; you can skip this
 	section.</para>
 
       <para>However, if you need FreeBSD to co-exist with other operating
 	systems then you need to have a rough understanding of how data is
 	laid out on the disk, and how this affects you.</para>
 
       <sect3 id="install-where-i386">
 	<title>Disk Layouts for the &i386;</title>
 
       <para>A PC disk can be divided into discrete chunks.  These chunks are
 	called <firstterm>partitions</firstterm>.  By design, the PC only
 	supports four partitions per disk.  These partitions are called
 	<firstterm>primary partitions</firstterm>.  To work around this
 	limitation and allow more than four partitions, a new partition type
 	was created, the <firstterm>extended partition</firstterm>.  A disk
 	may contain only one extended partition.  Special partitions, called
 	<firstterm>logical partitions</firstterm>, can be created inside this
 	extended partition.</para>
 
       <para>Each partition has a <firstterm>partition ID</firstterm>, which is
 	a number used to identify the type of data on the partition.  FreeBSD
 	partitions have the partition ID of <literal>165</literal>.</para>
 
       <para>In general, each operating system that you use will identify
 	partitions in a particular way.  For example, DOS, and its
 	descendants, like &windows;, assign each primary and logical partition a
 	<firstterm>drive letter</firstterm>, starting with
 	<devicename>C:</devicename>.</para>
 
       <para>FreeBSD must be installed into a primary partition.  FreeBSD can
 	keep all its data, including any files that you create, on this one
 	partition.  However, if you have multiple disks, then you can create a
 	FreeBSD partition on all, or some, of them.  When you install FreeBSD,
 	you must have one partition available.  This might be a blank
 	partition that you have prepared, or it might be an existing partition
 	that contains data that you no longer care about.</para>
 
       <para>If you are already using all the partitions on all your disks, then
 	you will have to free one of them for FreeBSD using the tools
 	provided by the other operating systems you use (e.g.,
 	<command>fdisk</command> on DOS or &windows;).</para>
 
       <para>If you have a spare partition then you can use that.  However, you
 	may need to shrink one or more of your existing partitions
 	first.</para>
 
       <para>A minimal installation of FreeBSD takes as little as 100&nbsp;MB of disk
 	space.  However, that is a <emphasis>very</emphasis> minimal install,
 	leaving almost no space for your own files.  A more realistic minimum
 	is 250&nbsp;MB without a graphical environment, and 350&nbsp;MB or more if you
 	want a graphical user interface.  If you intend to install a lot of
 	third party software as well, then you will need more space.</para>
 
       <para>You can use a commercial tool such as <application>&partitionmagic;</application>
 	to resize your partitions to make space for
 	FreeBSD.  The <filename>tools</filename> directory on the CDROM
 	contains two free software tools which can carry out this task, namely
 	<application>FIPS</application> and
 	<application>PResizer</application>.  Documentation for both
 	of these is available in the same directory.
 	<application>FIPS</application>,
 	<application>PResizer</application>, and
 	<application>&partitionmagic;</application> can resize
 	<acronym>FAT16</acronym> and <acronym>FAT32</acronym>
 	partitions &mdash; used in &ms-dos; through &windows; ME.
 	<application>&partitionmagic;</application> is the only known
 	application that can resize <acronym>NTFS</acronym>.</para>
 
       <warning>
 	<para>Incorrect use of these tools can delete the data on your disk.
 	  Be sure that you have recent, working backups before using
 	  them.</para>
       </warning>
 
       <example>
 	<title>Using an Existing Partition Unchanged</title>
 
 	<para>Suppose that you have a computer with a single 4&nbsp;GB disk that
 	  already has a version of &windows; installed, and you have split the
 	  disk into two drive letters, <devicename>C:</devicename> and
 	  <devicename>D:</devicename>, each of which is 2&nbsp;GB in size.  You have
 	  1&nbsp;GB of data on <devicename>C:</devicename>, and 0.5&nbsp;GB of data on
 	  <devicename>D:</devicename>.</para>
 
 	<para>This means that your disk has two partitions on it, one per
 	  drive letter.  You can copy all your existing data from
 	  <devicename>D:</devicename> to <devicename>C:</devicename>, which
 	  will free up the second partition, ready for FreeBSD.</para>
       </example>
 
       <example>
 	<title>Shrinking an Existing Partition</title>
 
 	<para>Suppose that you have a computer with a single 4&nbsp;GB disk that
 	  already has a version of &windows; installed.  When you installed
 	  &windows; you created one large partition, giving you a
 	  <devicename>C:</devicename> drive that is 4&nbsp;GB in size.  You are
 	  currently using 1.5&nbsp;GB of space, and want FreeBSD to have 2&nbsp;GB of
 	  space.</para>
 
 	<para>In order to install FreeBSD you will need to either:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>Backup your &windows; data, and then reinstall &windows;,
 	      asking for a 2&nbsp;GB partition at install time.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use one of the tools such as <application>&partitionmagic;</application>,
 	      described above, to shrink your &windows;
 		partition.</para>
 	  </listitem>
 	</orderedlist>
       </example>
 
       </sect3>
 
       <sect3>
 	<title>Disk Layouts for the Alpha</title>
 
 	<indexterm><primary>Alpha</primary></indexterm>
 
 	<para>You will need a dedicated disk for FreeBSD on the
 	  Alpha.  It is not possible to share a disk with another
 	  operating system at this time.  Depending on the specific
 	  Alpha machine you have, this disk can either be a SCSI disk
 	  or an IDE disk, as long as your machine is capable of
 	  booting from it.</para>
 
 	<para>Following the conventions of the Digital / Compaq
 	  manuals all SRM input is shown in uppercase.  SRM is case
 	  insensitive.</para>
 
 	<para>To find the names and types of disks in your machine, use
 	  the <literal>SHOW DEVICE</literal> command from the SRM
 	  console prompt:</para>
 
 	<screen>&gt;&gt;&gt;<userinput>SHOW DEVICE</userinput>
 dka0.0.0.4.0               DKA0           TOSHIBA CD-ROM XM-57  3476
 dkc0.0.0.1009.0            DKC0                       RZ1BB-BS  0658
 dkc100.1.0.1009.0          DKC100             SEAGATE ST34501W  0015
 dva0.0.0.0.1               DVA0
 ewa0.0.0.3.0               EWA0              00-00-F8-75-6D-01
 pkc0.7.0.1009.0            PKC0                  SCSI Bus ID 7  5.27
 pqa0.0.0.4.0               PQA0                       PCI EIDE
 pqb0.0.1.4.0               PQB0                       PCI EIDE</screen>
 
 	<para>This example is from a Digital Personal Workstation
 	  433au and shows three disks attached to the machine.  The
 	  first is a CDROM drive called <devicename>DKA0</devicename> and
 	  the other two are disks and are called
 	  <devicename>DKC0</devicename> and
 	  <devicename>DKC100</devicename> respectively.</para>
 
 	<para>Disks with names of the form <devicename>DKx</devicename>
 	  are SCSI disks.  For example <devicename>DKA100</devicename>
 	  refers to a SCSI disk with SCSI target ID 1 on the first SCSI bus (A), 
 	  whereas <devicename>DKC300</devicename> refers to a SCSI disk
 	  with SCSI ID 3 on the third SCSI bus (C).  Devicename <devicename>
 	  PKx</devicename> refers to the SCSI host bus adapter.  As
 	  seen in the <literal>SHOW DEVICE</literal> output SCSI
 	  CDROM drives are treated as any other SCSI hard disk drive.</para>
 
 	<para>IDE disks have names similar to <devicename>DQx</devicename>,
 	  while <devicename>PQx</devicename> is the associated IDE
 	  controller.</para>
 
       </sect3>
     </sect2>
 
     <sect2>
       <title>Collect Your Network Configuration Details</title>
 
       <para>If you intend to connect to a network as part of your FreeBSD
 	installation (for example, if you will be installing from an FTP
 	site or an
 	NFS server), then you need to know your network configuration.  You
 	will be prompted for this information during the installation so that
 	FreeBSD can connect to the network to complete the install.</para>
 
       <sect3>
 	<title>Connecting to an Ethernet Network or Cable/DSL Modem</title>
 
 	<para>If you connect to an Ethernet network, or you have an Internet
 	  connection using an Ethernet adapter via cable or DSL, then you will need the following
 	  information:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>IP address</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>IP address of the default gateway</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Hostname</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>DNS server IP addresses</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Subnet Mask</para>
 	  </listitem>
 	</orderedlist>
 
 	<para>If you do not know this information, then ask your system
 	  administrator or service provider.  They may say that this
 	  information is assigned automatically, using
 	  <firstterm>DHCP</firstterm>.  If so, make a note of this.</para>
       </sect3>
 
       <sect3>
 	<title>Connecting Using a Modem</title>
 
 	<para>If you dial up to an ISP using a regular modem then you can
 	  still install FreeBSD over the Internet, it will just take a very
 	  long time.</para>
 
 	<para>You will need to know:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>The phone number to dial for your ISP</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The COM: port your modem is connected to</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The username and password for your ISP account</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
     <sect2>
       <title>Check for FreeBSD Errata</title>
       
       <para>Although the FreeBSD project strives to ensure that each release
 	of FreeBSD is as stable as possible, bugs do occasionally creep into
 	the process.  On very rare occasions those bugs affect the
 	installation process.  As these problems are discovered and fixed, they
 	are noted in the <ulink url="http://www.FreeBSD.org/releases/&rel.current;R/errata.html">FreeBSD Errata</ulink>, which is found on the FreeBSD web site.  You
 	should check the errata before installing to make sure that there are
 	no late-breaking problems which you should be aware of.</para>
 
       <para>Information about all the releases, including the errata for each
 	release, can be found on the 
 	<ulink
 	url="&url.base;/releases/index.html">release
 	information</ulink> section of the 
 	<ulink
 	  url="&url.base;/index.html">FreeBSD web site</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>Obtain the FreeBSD Installation Files</title>
 
       <para>The FreeBSD installation process can install FreeBSD from files
 	located in any of the following places:</para>
 
       <itemizedlist>
 	<title>Local Media</title>
 	
 	<listitem>
 	  <para>A CDROM or DVD</para>
 	</listitem>
 
 	<listitem>
 	  <para>A DOS partition on the same computer</para>
 	</listitem>
 
 	<listitem>
 	  <para>A SCSI or QIC tape</para>
 	</listitem>
 
 	<listitem>
 	  <para>Floppy disks</para>
 	</listitem>
       </itemizedlist>
 
       <itemizedlist>
 	<title>Network</title>
 
 	<listitem>
 	  <para>An FTP site, going through a firewall, or using an HTTP proxy,
 	    as necessary</para>
 	</listitem>
 
 	<listitem>
 	  <para>An NFS server</para>
 	</listitem>
 
 	<listitem>
 	  <para>A dedicated parallel or serial connection</para>
 	</listitem>
       </itemizedlist>
 
       <para>If you have purchased FreeBSD on CD or DVD then you already have
 	everything you need, and should proceed to the next section 
 	(<xref linkend="install-floppies">).</para>
 
       <para>If you have not obtained the FreeBSD installation files you should
 	skip ahead to <xref linkend="install-diff-media"> which explains how
 	to prepare to install FreeBSD from any of the above.  After reading
 	that section, you should come back here, and read on to 
 	<xref linkend="install-floppies">.</para>
     </sect2>
 
     <sect2 id="install-floppies">
       <title>Prepare the Boot Media</title>
       
       <para>The FreeBSD installation process is started by booting your
 	computer into the FreeBSD installer&mdash;it is not a program you run
 	within another operating system.  Your computer normally boots using
 	the operating system installed on your hard disk, but it can also be
 	configured to use a <quote>bootable</quote> floppy disk.
 	Most modern computers can also
 	boot from a CDROM in the CDROM drive.</para>
 
       <tip>
 	<para>If you have FreeBSD on CDROM or DVD (either one you purchased
 	  or you prepared yourself), and your computer allows you to boot from
 	  the CDROM or DVD (typically a BIOS option called <quote>Boot
 	    Order</quote> or similar), then you can skip this section.  The
 	  FreeBSD CDROM and DVD images are bootable and can be used to install
 	  FreeBSD without any other special preparation.</para>
       </tip>
     
       <para>To create boot floppy images, follow these steps:</para>
 
       <procedure>
 	<step>
 	  <title>Acquire the Boot Floppy Images</title>
 	  
 	  <para>The boot disks are available on your installation media
 	    in the <filename>floppies/</filename> directory, and
 	    can also be downloaded from the floppies directory, <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<replaceable>&lt;arch&gt;</replaceable>/<replaceable>&lt;version&gt;</replaceable>-RELEASE/floppies/</literal>.
 	    Replace <replaceable>&lt;arch&gt;</replaceable> and
 	    <replaceable>&lt;version&gt;</replaceable>
 	    with the architecture and the version number
 	    which you want to install, respectively.
 	    For example, the boot floppy images for
 	    &os;&nbsp;&rel.current;-RELEASE for &i386; are available
 	    from <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/"></ulink>.</para>
 
 	  <para>The floppy images have a <filename>.flp</filename> extension.
 	    The <filename>floppies/</filename> directory contains a number of
 	    different images, and the ones you will need to use depends on the
 	    version of FreeBSD you are installing, and in some cases, the
 	    hardware you are installing to.  If you are installing
 	    FreeBSD&nbsp;4.X in most cases you will just need
 	    two files, <filename>kern.flp</filename> and
 	    <filename>mfsroot.flp</filename>.  If you are
 	    installing FreeBSD&nbsp;5.X in most cases you will need three
 	    floppies, <filename>boot.flp</filename>,
 	    <filename>kern1.flp</filename>, and
 	    <filename>kern2.flp</filename>.  Check
 	    <filename>README.TXT</filename> in the same directory for the
 	    most up to date information about these floppy images.</para>
 
 	  <note><para>Additional device drivers may
 	    be necessary for 5.X systems older than &os;&nbsp;5.3.
 	    These drivers are provided on the
 	    <filename>drivers.flp</filename> image.</para></note>
 
 	  <important>
 	    <para>Your FTP program must use <emphasis>binary mode</emphasis>
 	      to download these disk images.  Some web browsers have been
 	      known to use <emphasis>text</emphasis> (or
 	      <emphasis>ASCII</emphasis>) mode, which will be apparent if you
 	      cannot boot from the disks.</para>
 	  </important>
 	</step>
 
 	<step>
 	  <title>Prepare the Floppy Disks</title>
 	  
 	  <para>You must prepare one floppy disk per image file you had to
 	    download.  It is imperative that these disks are free from
 	    defects.  The easiest way to test this is to format the disks
 	    for yourself.  Do not trust pre-formatted floppies.  The format
 	    utility in &windows; will not tell about the presence of
 	    bad blocks, it simply marks them as <quote>bad</quote>
 	    and ignores them.  It is advised that you use brand new
 	    floppies if choosing this installation route.</para>
 
 	  <important>
 	    <para>If you try to install FreeBSD and the installation
 	      program crashes, freezes, or otherwise misbehaves, one of
 	      the first things to suspect is the floppies.  Try writing
 	      the floppy image files to new disks and try
 	      again.</para>
 	  </important>
 	</step>
 
 	<step>
 	  <title>Write the Image Files to the Floppy Disks</title>
 
 	  <para>The <filename>.flp</filename> files are
 	    <emphasis>not</emphasis> regular files you copy to the disk.
 	    They are images of the complete contents of the
 	    disk.  This means that you <emphasis>cannot</emphasis> simply
 	    copy files from one disk to another.
 	    Instead, you must use specific tools to write the
 	    images directly to the disk.</para>
 
 	  <indexterm><primary>DOS</primary></indexterm>
 	  <para>If you are creating the floppies on a computer running
       &ms-dos;/&windows;, then we provide a tool to do
       this called <command>fdimage</command>.</para>
 
 	  <para>If you are using the floppies from the CDROM, and your
 	    CDROM is the <devicename>E:</devicename> drive, then you would 
 	    run this:</para>
 
 	  <screen><prompt>E:\&gt;</prompt> <userinput>tools\fdimage floppies\kern.flp A:</userinput></screen>
 
 	  <para>Repeat this command for each <filename>.flp</filename>
 	    file, replacing the floppy disk each time, being sure to label
 	    the disks with the name of the file that you copied to them.
 	    Adjust the command line as necessary, depending on where you have
 	    placed the <filename>.flp</filename> files.  If you do not have
 	    the CDROM, then <command>fdimage</command> can be downloaded from
 	    the <ulink
 	    url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/"><filename class="directory">tools</filename>
 	    directory</ulink> on the FreeBSD FTP site.</para>
 	  
 	  <para>If you are writing the floppies on a &unix; system (such as
 	    another FreeBSD system) you can use the &man.dd.1; command to
 	    write the image files directly to disk.  On FreeBSD, you would
 	    run:</para>
 	  
 	  <screen>&prompt.root; <userinput>dd if=kern.flp of=/dev/fd0</userinput></screen>
 
 	  <para>On FreeBSD, <filename>/dev/fd0</filename> refers to the
 	    first floppy disk (the <devicename>A:</devicename> drive).
 	    <filename>/dev/fd1</filename> would be the
 	    <devicename>B:</devicename> drive, and so on.  Other &unix;
 	    variants might have different names for the floppy disk
 	    devices, and you will need to check the documentation for the
 	    system as necessary.</para>
 	</step>
       </procedure>
 
       <para>You are now ready to start installing FreeBSD.</para>
     </sect2>
   </sect1>
 
   <sect1 id="install-start">
     <title>Starting the Installation</title>
 
     <important>
       <para>By default, the installation will not make any changes to your
 	disk(s) until you see the following message:</para>
 
       <literallayout class="monospaced">Last Chance: Are you SURE you want continue the installation?
 
 If you're running this on a disk with data you wish to save then WE
 STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding!
 
 We can take no responsibility for lost disk contents!</literallayout>
 
       <para>The install can be exited at any time prior to the final
 	warning without changing the contents of the hard drive.  If you are
 	concerned that you have configured something incorrectly you can just
 	turn the computer off before this point, and no damage will be
 	done.</para>
     </important>
 
     <sect2 id="install-starting">
       <title>Booting</title>
 
       <sect3 id="install-starting-i386">
         <title>Booting for the &i386;</title>
 
       <procedure>
 	<step>
 	  <para>Start with your computer turned off.</para>
 	</step>
 
 	<step>
 	  <para>Turn on the computer.  As it starts it should display an
 	    option to enter the system set up menu, or BIOS, commonly reached
 	    by keys like <keycap>F2</keycap>, <keycap>F10</keycap>,
 	    <keycap>Del</keycap>, or
 	    <keycombo action="simul">
 	      <keycap>Alt</keycap>
 	      <keycap>S</keycap>
 	    </keycombo>.  Use whichever keystroke is indicated on screen.  In
 	    some cases your computer may display a graphic while it starts.
 	    Typically, pressing <keycap>Esc</keycap> will dismiss the graphic
 	    and allow you to see the necessary messages.</para>
 	</step>
 
 	<step>
 	  <para>Find the setting that controls which devices the system boots
 	    from.  This is usually labeled as the <quote>Boot Order</quote>
             and commonly shown as a list of devices, such as
 	    <literal>Floppy</literal>, <literal>CDROM</literal>,
 	    <literal>First Hard Disk</literal>, and so on.</para>
 
 	  <para>If you needed to prepare boot floppies, then make sure that the
 	    floppy disk is selected.  If you are booting from the CDROM then
 	    make sure that that is selected instead.  In case of doubt, you
 	    should consult the manual that came with your computer, and/or its
 	    motherboard.</para>
 
 	  <para>Make the change, then save and exit.  The computer should now
 	    restart.</para>
 	</step>
 
 	<step>
 	  <para>If you needed to prepare boot floppies, as described in 
 	    <xref linkend="install-floppies">, then one of them will be the
 	    first boot disc, probably the one containing
 	    <filename>kern.flp</filename>.  Put this disc in your floppy
 	    drive.</para>
 
 	  <para>If you are booting from CDROM, then you will need to turn on
 	    the computer, and insert the CDROM at the first
 	    opportunity.</para>
 
 	  <para>If your computer starts up as normal and loads your existing
 	    operating system, then either:</para>
 
 	  <orderedlist>
 	    <listitem>
 	      <para>The disks were not inserted early enough in the boot
 		process.  Leave them in, and try restarting your
 		computer.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>The BIOS changes earlier did not work correctly.  You
 		should redo that step until you get the right option.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Your particular BIOS does not support booting from
 		the desired media.</para>
 	    </listitem>
 	</orderedlist>
 	</step>
     
 	<step>
 	  <para>FreeBSD will start to boot.  If you are booting from CDROM you
 	    will see a display similar to this (version information omitted):</para>
 	  
 	  <screen>Verifying DMI Pool Data ........
 Boot from ATAPI CD-ROM :
  1. FD 2.88MB  System Type-(00)
 Uncompressing ... done
 
 BTX loader 1.00 BTX version is 1.01
 Console: internal video/keyboard
 BIOS drive A: is disk0
 BIOS drive B: is disk1
 BIOS drive C: is disk2
 BIOS drive D: is disk3
 BIOS 639kB/261120kB available memory
 
 FreeBSD/i386 bootstrap loader, Revision 0.8
 
 /kernel text=0x277391 data=0x3268c+0x332a8 |
 
 |
 Hit [Enter] to boot immediately, or any other key for command prompt.
 Booting [kernel] in 9 seconds... _</screen>
 	
 	  <para>If you are booting from floppy disc, you will see a display
 	    similar to this (version information omitted):</para>
 	
 	  <screen>Verifying DMI Pool Data ........ 
 
 BTX loader 1.00  BTX version is 1.01 
 Console: internal video/keyboard 
 BIOS drive A: is disk0 
 BIOS drive C: is disk1 
 BIOS 639kB/261120kB available memory 
 
 FreeBSD/i386 bootstrap loader, Revision 0.8 
 
 /kernel text=0x277391 data=0x3268c+0x332a8 |
 
 Please insert MFS root floppy and press enter:</screen>
 
 	  <para>Follow these instructions by removing the
 	    <filename>kern.flp</filename> disc, insert the
 	    <filename>mfsroot.flp</filename> disc, and press
 	    <keycap>Enter</keycap>.  &os;&nbsp;5.3
 	    and above provide other floppy disks set, as described
 	    in <link linkend="install-floppies">previous
 	    section</link>.  Boot from first floppy;
 	    when prompted, insert the other disks as required.</para>
 	</step>
 
 	<step>
 	  <para>Whether you booted from floppy or CDROM, the
 	    boot process will then get to this point:</para>
 
 	  <screen>Hit [Enter] to boot immediately, or any other key for command prompt. 
 Booting [kernel] in 9 seconds... _</screen>
 
 	  <para>Either wait ten seconds, or press <keycap>Enter</keycap>
 	    (for &os;&nbsp;4.X this
 	    will then launch the kernel configuration menu).</para>
 	</step>
       </procedure>
 
       </sect3>
       <sect3>
         <title>Booting for the Alpha</title>
 
 	<indexterm><primary>Alpha</primary></indexterm>
 
       <procedure>
 	<step>
 	  <para>Start with your computer turned off.</para>
 	</step>
 
 	<step>
 	  <para>Turn on the computer and wait for a boot monitor
 	    prompt.</para>
         </step>
 
 	<step>
 	  <para>If you needed to prepare boot floppies, as described in 
 	    <xref linkend="install-floppies"> then one of them will be the
 	    first boot disc, probably the one containing
 	    <filename>kern.flp</filename>.  Put this disc in your floppy
 	    drive and type the following command to boot the disk
 	    (substituting the name of your floppy drive if
 	    necessary):</para>
 
 	  <screen>&gt;&gt;&gt;<userinput>BOOT DVA0 -FLAGS '' -FILE ''</userinput></screen>
 
 	  <para>If you are booting from CDROM, insert the CDROM into
 	    the drive and type the following command to start the
 	    installation (substituting the name of the appropriate
 	    CDROM drive if necessary):</para>
 
           <screen>&gt;&gt;&gt;<userinput>BOOT DKA0 -FLAGS '' -FILE ''</userinput></screen>
 	</step>
     
 	<step>
 	  <para>FreeBSD will start to boot.  If you are booting from a
 	    floppy disc, at some point you will see the message:</para>
 
 	  <screen>Please insert MFS root floppy and press enter:</screen>
 
 	  <para>Follow these instructions by removing the
 	    <filename>kern.flp</filename> disc, insert the
 	    <filename>mfsroot.flp</filename> disc, and press
 	    <keycap>Enter</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>Whether you booted from floppy or CDROM, the
 	    boot process will then get to this point:</para>
 
 	  <screen>Hit [Enter] to boot immediately, or any other key for command prompt. 
 Booting [kernel] in 9 seconds... _</screen>
 
 	  <para>Either wait ten seconds, or press <keycap>Enter</keycap>.  This
 	    will then launch the kernel configuration menu.</para>
 	</step>
       </procedure>
 
       </sect3>
 
     </sect2>
 
     <sect2 id="start-userconfig">
       <title>Kernel Configuration</title>
 
       <note><para>From FreeBSD versions 5.0 and later, userconfig has been deprecated
 	in favor of the new &man.device.hints.5; method.  For more information
 	on &man.device.hints.5; please visit <xref linkend="device-hints"></para></note>
 
       <para>The <firstterm>kernel</firstterm> is the core of the operating
 	system.  It is responsible for many things, including access to all
 	the devices you may have on your system, such as hard disks, network
 	cards, sound cards, and so on.  Each piece of hardware supported by
 	the FreeBSD kernel has a driver associated with it.  Each driver has a
 	two or three letter name, such as <devicename>sa</devicename> for the
 	SCSI sequential access driver, or <devicename>sio</devicename> for the
 	Serial I/O driver (which manages COM ports).</para>
 
       <para>When the kernel starts, each driver checks the system to see
 	whether or not the hardware it supports exists on your system.  If it
 	does, then the driver configures the hardware and makes it available
 	to the rest of the kernel.</para>
 
       <para>This checking is commonly referred to as <firstterm>device
 	  probing</firstterm>.  Unfortunately, it is not always possible to do
 	this in a safe way.  Some hardware drivers do not co-exist well,
 	and probing for one piece of hardware can sometimes leave
 	another in an inconsistent state.  This is a basic
 	limitation of the <acronym>PC</acronym> design.</para>
 
       <para>Many older devices are called ISA devices&mdash;as opposed
 	to PCI devices.  The ISA specification requires each device to have
 	some information hard coded into it, typically the Interrupt Request
 	Line number (IRQ) and IO port address that the driver uses.  This
 	information is commonly set by using physical
 	<firstterm>jumpers</firstterm> on the card, or by using a DOS based
 	utility.</para>
 
       <para>This was often a source of problems, because it was not possible
 	to have two devices that shared the same IRQ or port address.</para>
 
       <para>Newer devices follow the PCI specification, which does not require
 	this, as the devices are supposed to cooperate with the BIOS, and are
 	told which IRQ and IO port addresses to use.</para>
 
       <para>If you have any ISA devices in your computer then FreeBSD's
 	driver for that device will need to be configured with the IRQ and
 	port address that you have set the card to.  This is why carrying out
 	an inventory of	your hardware (see <xref
 	linkend="install-inventory">) can be useful.</para>
 
       <para>Unfortunately, the default IRQs and memory ports used by some
 	drivers clash.  This is because some ISA devices are shipped with IRQs
 	or memory ports that clash.  The defaults in FreeBSD's drivers are
 	deliberately set to mirror the manufacturer's defaults, so that, out
 	of the box, as many devices as possible will work.</para>
 
       <para>This is almost never an issue when running FreeBSD day-to-day.
 	Your computer will not normally contain two pieces of hardware that
 	clash, because one of them would not work (irrespective of the
 	operating system you are using).</para>
 
       <para>It becomes an issue when you are installing FreeBSD for the first
 	time because the kernel used to carry out the install has to contain
 	as many drivers as possible, so that many different hardware
 	configurations can be supported.  This means that some of
 	those drivers will have conflicting configurations.  The devices are
 	probed in a strict order, and if you own a device that is probed late
 	in the process, but conflicted with an earlier probe, then your
 	hardware might not function or be probed correctly when you install
 	FreeBSD.</para>
 
       <para>Because of this, the first thing you have the opportunity to do
 	when installing FreeBSD is look at the list of drivers that are
 	configured into the kernel, and either disable some of them, if you
 	do not own that device, or confirm (and alter) the driver's
 	configuration if you do own the device but the defaults are
 	wrong.</para>
 
       <para>This probably sounds much more complicated than it actually
 	is.</para>
 
       <para><xref linkend="kernel-config"> shows the first kernel
 	configuration menu.  We recommend that you choose the
 	<guimenuitem>Start kernel configuration in full-screen visual
 	  mode</guimenuitem> option, as it presents the easiest interface for
 	the new user.</para>
 
       <figure id="kernel-config">
 	<title>Kernel Configuration Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/userconfig" format="PNG">
 	  </imageobject>
 
 	  <textobject>
 	    <screen>&txt.install.userconfig;</screen>
 	  </textobject>
 	</mediaobject>
       </figure>
 
       <para>The kernel configuration screen (<xref linkend="fig-userconfig">)
 	is then divided into four sections:</para>
 
       <orderedlist>
 	<listitem>
 	  <para>A collapsible list of all the drivers that are currently
 	    marked as <quote>active</quote>, subdivided into groups such as
 	    <literal>Storage</literal>, and <literal>Network</literal>.  Each
 	    driver is shown as a description, its two or three letter driver
 	    name, and the IRQ and memory port used by that driver.  In
 	    addition, if an active driver conflicts with another active driver
 	    then <literal>CONF</literal> is shown next to the driver name.
 	    This section also shows the total number of conflicting drivers
 	    that are currently active.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Drivers that have been marked inactive.  They remain in the
 	    kernel, but they will not probe for their device when the kernel
 	    starts.  These are subdivided into groups in the same way as the
 	    active driver list.</para>
 	</listitem>
 
 	<listitem>
 	  <para>More detail about the currently selected driver, including its
 	    IRQ and memory port address.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Information about the keystrokes that are valid at this point
 	    in time.</para>
 	</listitem>
       </orderedlist>
 
       <figure id="fig-userconfig">
 	<title>The Kernel Device Configuration Visual Interface</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/userconfig2" format="PNG">
 	  </imageobject>
 
           <textobject>
             <screen>&txt.install.userconfig2;</screen>
           </textobject>
         </mediaobject>
       </figure>
 
       <para>Do not worry if any conflicts are listed,
 	it is to be expected; all the drivers are enabled, and
 	as has already been explained, some of them will conflict with one
 	another.</para>
 
       <para>You now have to work through the list of drivers, resolving the
 	conflicts.</para>
 
       <procedure>
 	<title>Resolving Driver Conflicts</title>
 
 	<step>
 	  <para>Press <keycap>X</keycap>.  This will completely expand the
 	    list of drivers, so you can see all of them.  You will need to use
 	    the arrow keys to scroll back and forth through the active driver
 	    list.</para>
 
 	  <para><xref linkend="hardware-conflicts"> shows the result of
 	    pressing <keycap>X</keycap>.</para>
 
 	  <figure id="hardware-conflicts">
 	    <title>Expanded Driver List</title>
 
 	    <mediaobject>
 	      <imageobject>
 		<imagedata fileref="install/hdwrconf" format="PNG">
 	      </imageobject>
 	    </mediaobject>
 	  </figure>
 	</step>
 
 	<step>
 	  <para>Disable all the drivers for devices that you do not have.  To
 	    disable a driver, highlight it with the arrow keys and press
 	    <keycap>Del</keycap>.  The driver will be moved to the
 	    <literal>Inactive Drivers</literal> list.</para>
 
 	  <para>If you inadvertently disable a device that you need then press
 	    <keycap>Tab</keycap> to switch to the <literal>Inactive
 	    Drivers</literal> list, select the driver that you disabled, and
 	    press <keycap>Enter</keycap> to move it back to the active
 	    list.</para>
 
 	  <warning>
 	    <para>Do not disable <devicename>sc0</devicename>.  This controls
 	      the screen, and you will need this unless you are installing
 	      over a serial cable.</para>
 	  </warning>
 
 	  <warning>
 	    <para>Only disable <devicename>atkbd0</devicename> if you are
 	      using a USB keyboard.  If you have a normal keyboard then you
 	      must keep <devicename>atkbd0</devicename>.</para>
 	  </warning>
 	</step>
 
 	<step>
 	  <para>If there are no conflicts listed then you can skip this step.
 	    Otherwise, the remaining conflicts need to be examined.  If they
 	    do not have the indication of an <quote>allowed conflict</quote>
 	    in the message area, then either the IRQ/address for device probe
 	    will need to be changed, <emphasis>or</emphasis> the IRQ/address
 	    on the hardware will need to be changed.</para>
 
 	  <para>To change the driver's configuration for IRQ and IO port
 	    address, select the device and press <keycap>Enter</keycap>.  The
 	    cursor will move to the third section of the screen, and you can
 	    change the values.  You should enter the values for IRQ and port
 	    address that you discovered when you made your hardware inventory.
 	    Press <keycap>Q</keycap> to finish editing the device's
 	    configuration and return to the active driver list.</para>
 	  
 	  <para>If you are not sure what these figures should be then you can
 	    try using <literal>-1</literal>.  Some FreeBSD drivers can safely
 	    probe the hardware to discover what the correct value should be,
 	    and a value of <literal>-1</literal> configures them to do
 	    this.</para>
 
 	  <para>The procedure for changing the address on the hardware varies
 	    from device to device.  For some devices you may need to
 	    physically remove the card from your computer and adjust jumper
 	    settings or DIP switches.  Other cards may have come with a DOS
 	    floppy that contains the programs used to reconfigure the card.
 	    In any case, you should refer to the documentation that came with
 	    the device.  This will obviously entail restarting your computer,
 	    so you will need to boot back into the FreeBSD installation
 	    routine when you have reconfigured the card.</para>
 	</step>
 
 	<step>
 	  <para>When all the conflicts have been resolved the screen will look
 	    similar to <xref linkend="userconfig-done">.</para>
 
 	  <figure id="userconfig-done">
 	    <title>Driver Configuration With No Conflicts</title>
 
 	    <mediaobject>
 	      <imageobject>
 		<imagedata fileref="install/probstart" format="PNG">
 	      </imageobject>
 	    </mediaobject>
 	  </figure>
 
 	  <para>As you can see, the active driver list is now much smaller,
 	    with only drivers for the hardware that actually exists being
 	    listed.</para>
 	  
 	  <para>You can now save these changes, and move on to the next step
 	    of the install.  Press <keycap>Q</keycap> to quit the device
 	    configuration interface.  This message will appear:</para>
 
 	  <screen>Save these parameters before exiting? ([Y]es/[N]o/[C]ancel)</screen>
 
 	  <para>Answer <keycap>Y</keycap> to save the parameters to memory
 	    (it will be saved to disk if you finish the install) and the
 	    probing will start.  After displaying the probe results in white
 	    on black text <application>sysinstall</application> will start
 	    and display its main menu 
 	    (<xref linkend="sysinstall-main">).</para>
 
 	  <figure id="sysinstall-main">
 	    <title>Sysinstall Main Menu</title>
 	    
 	    <mediaobject>
 	      <imageobject>
 		<imagedata fileref="install/main1" format="PNG">
 	      </imageobject>
 	    </mediaobject>
 	  </figure>
 	</step>
       </procedure>
     </sect2>
 
     <sect2 id="view-probe">
       <title>Reviewing the Device Probe Results</title>
 
       <para>The last few hundred lines that have been displayed on screen are
 	stored and can be reviewed.</para>
 
       <para>To review the buffer, press <keycap>Scroll Lock</keycap>.  This
 	turns on scrolling in the display.  You can then use the arrow keys, or
 	<keycap>PageUp</keycap> and <keycap>PageDown</keycap> to view the
 	results.  Press <keycap>Scroll Lock</keycap> again to stop
 	scrolling.</para>
 
       <para>Do this now, to review the text that scrolled off the screen when
 	the kernel was carrying out the device probes.  You will see text
 	similar to <xref linkend="install-dev-probe">, although the precise
 	text will differ depending on the devices that you have in your
 	computer.</para>
 
       <figure id="install-dev-probe">
 	<title>Typical Device Probe Results</title>
 
 	<screen>avail memory = 253050880 (247120K bytes) 
 Preloaded elf kernel "kernel" at 0xc0817000.
 Preloaded mfs_root "/mfsroot" at 0xc0817084.
 md0: Preloaded image &lt;/mfsroot&gt; 4423680 bytes at 0xc03ddcd4
 
 md1: Malloc disk
 Using $PIR table, 4 entries at 0xc00fde60
 npx0: &lt;math processor&gt; on motherboard   
 npx0: INT 16 interface   
 pcib0: &lt;Host to PCI bridge&gt; on motherboard
 pci0: &lt;PCI bus&gt; on pcib0
 pcib1:&lt;VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge&gt; at device 1.0 on pci0
 pci1: &lt;PCI bus&gt; on pcib1
 pci1: &lt;Matrox MGA G200 AGP graphics accelerator&gt; at 0.0 irq 11
 isab0: &lt;VIA 82C586 PCI-ISA bridge&gt; at device 7.0 on pci0
 isa0: &lt;iSA bus&gt; on isab0
 atapci0: &lt;VIA 82C586 ATA33 controller&gt; port 0xe000-0xe00f at device 7.1 on pci0
 ata0: at 0x1f0 irq 14 on atapci0
 ata1: at 0x170 irq 15 on atapci0
 uhci0 &lt;VIA 83C572 USB controller&gt; port 0xe400-0xe41f irq 10 at device 7.2 on pci
 0
 usb0: &lt;VIA 83572 USB controller&gt; on uhci0
 usb0: USB revision 1.0
 uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr1
 uhub0: 2 ports with 2 removable, self powered
 pci0: &lt;unknown card&gt; (vendor=0x1106, dev=0x3040) at 7.3
 dc0: &lt;ADMtek AN985 10/100BaseTX&gt; port 0xe800-0xe8ff mem 0xdb000000-0xeb0003ff ir
 q 11 at device 8.0 on pci0
 dc0: Ethernet address: 00:04:5a:74:6b:b5
 miibus0: &lt;MII bus&gt; on dc0
 ukphy0: &lt;Generic IEEE 802.3u media interface&gt; on miibus0
 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
 ed0: &lt;NE2000 PCI Ethernet (RealTek 8029)&gt; port 0xec00-0xec1f irq 9 at device 10.
 0 on pci0
 ed0 address 52:54:05:de:73:1b, type NE2000 (16 bit)
 isa0: too many dependant configs (8)
 isa0: unexpected small tag 14
 orm0: &lt;Option ROM&gt; at iomem 0xc0000-0xc7fff on isa0
 fdc0: &lt;NEC 72065B or clone&gt; at port 0x3f0-0x3f5,0x3f7 irq 6 drq2 on isa0
 fdc0: FIFO enabled, 8 bytes threshold
 fd0: &lt;1440-KB 3.5" drive&gt; on fdc0 drive 0
 atkbdc0: &lt;Keyboard controller (i8042)&gt; at port 0x60,0x64 on isa0
 atkbd0: &lt;AT Keyboard&gt; flags 0x1 irq1 on atkbdc0
 kbd0 at atkbd0
 psm0: &lt;PS/2 Mouse&gt; irq 12 on atkbdc0
 psm0: model Generic PS/@ mouse, device ID 0
 vga0: &lt;Generic ISA VGA&gt; at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0
 sc0: &lt;System console&gt; at flags 0x100 on isa0
 sc0: VGA &lt;16 virtual consoles, flags=0x300&gt;
 sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0
 sio0: type 16550A
 sio1 at port 0x2f8-0x2ff irq 3 on isa0
 sio1: type 16550A
 ppc0: &lt;Parallel port&gt; at port 0x378-0x37f irq 7 on isa0
 pppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode
 ppc0: FIFO with 16/16/15 bytes threshold
 plip0: &lt;PLIP network interface&gt; on ppbus0
 ad0: 8063MB &lt;IBM-DHEA-38451&gt; [16383/16/63] at ata0-master UDMA33
 acd0: CD-RW &lt;LITE-ON LTR-1210B&gt; at ata1-slave PIO4
 Mounting root from ufs:/dev/md0c
 /stand/sysinstall running as init on vty0</screen>
       </figure>
 
       <para>Check the probe results carefully to make sure that FreeBSD found
 	all the devices you expected.  If a device was not found, then it will
 	not be listed.  If the device's driver required configuring
 	with the IRQ and port address then you should check that you entered
 	them correctly.</para>
 
       <para>If you need to make changes to the UserConfig device probing,
 	it is easy to exit the <application>sysinstall</application> program
 	and start over again.  It is also a good way to become more familiar
 	with the process.</para>
 
       <figure id="sysinstall-exit">
 	<title>Select Sysinstall Exit</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/sysinstall-exit" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the arrow keys to select 
 	<guimenuitem>Exit Install</guimenuitem> from the Main
 	Install Screen menu.  The following message will display:</para>
 
 
       <screen>                      User Confirmation Requested 
          Are you sure you wish to exit? The system will reboot 
            (be sure to remove any floppies from the drives).
 
                             [ Yes ]    No</screen>
 
       <para>The install program will start again if the CDROM is left
 	in the drive and &gui.yes; is selected.</para>
 
       <para>If you are booting from floppies it will be necessary to remove
 	the <filename>mfsroot.flp</filename> floppy and replace it with
 	<filename>kern.flp</filename> before rebooting.</para>
     </sect2>
   </sect1>
 
   <sect1 id="using-sysinstall">
     <title>Introducing Sysinstall</title>
 
     <para>The <application>sysinstall</application> utility is the installation
       application provided by the FreeBSD Project.  It is console based and is
       divided into a number of menus and screens that you can use to
       configure and control the installation process.</para>
 
     <para>The <application>sysinstall</application> menu system is controlled
       by the arrow keys, <keycap>Enter</keycap>, <keycap>Space</keycap>, and
       other keys.  A detailed description of these keys and what they do is
       contained in <application>sysinstall</application>'s usage 
       information.</para>
 
     <para>To review this information, ensure that the
       <guimenuitem>Usage</guimenuitem> entry is highlighted and that the
       <guibutton>[Select]</guibutton> button is selected, as shown in <xref
       linkend="sysinstall-main3">, then press <keycap>Enter</keycap>.</para>
 
     <para>The instructions for using the menu system will be displayed.  After
       reviewing them, press <keycap>Enter</keycap> to return to the Main
       Menu.</para>
 
     <figure id="sysinstall-main3">
       <title>Selecting Usage from Sysinstall Main Menu</title>
 
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="install/main1" format="PNG">
 	</imageobject>
       </mediaobject>
     </figure>
 
     <sect2 id="select-doc">
       <title>Selecting the Documentation Menu</title>
 
       <para>From the Main Menu, select <guimenuitem>Doc</guimenuitem> with
 	the arrow keys and
 	press <keycap>Enter</keycap>.</para>
 
       <figure id="main-doc">
 	<title>Selecting Documentation Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/main-doc" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>This will display the Documentation Menu.</para>
 
       <figure id="docmenu1">
 	<title>Sysinstall Documentation Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/docmenu1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>It is important to read the documents provided.</para>
 
       <para>To view a document, select it with the arrow keys and
 	press <keycap>Enter</keycap>.  When finished reading a document,
 	pressing <keycap>Enter</keycap> will return to the Documentation
 	Menu.</para>
 
       <para>To return to the Main Installation Menu, select
 	<guimenuitem>Exit</guimenuitem> with the 
 	arrow keys and press <keycap>Enter</keycap>.</para>
     </sect2>
 
     <sect2 id="keymap">
       <title>Selecting the Keymap Menu</title>
 
       <para>To change the keyboard mapping, use the arrow keys to select
 	<guimenuitem>Keymap</guimenuitem> from the menu and press
 	<keycap>Enter</keycap>.  This is only required if you are
 	using a non-standard or non-US keyboard.</para>
 
       <figure id="sysinstall-keymap">
 	<title>Sysinstall Main Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/main-keymap" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>A different keyboard mapping may be chosen by selecting the
 	menu item using up/down arrow keys and pressing <keycap>Space</keycap>.
 	Pressing <keycap>Space</keycap> again will unselect the item.
 	When finished, choose the &gui.ok; using the arrow keys and press
 	<keycap>Enter</keycap>.</para>
 
       <para>Only a partial list is shown in this screen representation.
 	Selecting &gui.cancel; by pressing <keycap>Tab</keycap> will use the default
 	keymap and return to the Main Install Menu.</para>
 
       <figure id="sysinstall-keymap-menu">
 	<title>Sysinstall Keymap Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/keymap" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
     </sect2>
 
     <sect2 id="viewsetoptions">
       <title>Installation Options Screen</title>
 
     <para>Select <guimenuitem>Options</guimenuitem> and press
 	<keycap>Enter</keycap>.</para>
 
     <figure id="sysinstall-options">
       <title>Sysinstall Main Menu</title>
 
       <mediaobject>
         <imageobject>
 	  <imagedata fileref="install/main-options" format="PNG">
 	</imageobject>
       </mediaobject>
     </figure>
 
       <figure id="options">
 	<title>Sysinstall Options</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/options" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The default values are usually fine for most users and do
 	not need to be changed.  The release name will vary according
 	to the version being installed.</para>
 
       <para>The description of the selected item will appear at the
 	bottom of the screen highlighted in blue.  Notice that one of the
 	options is <guimenuitem>Use Defaults</guimenuitem> to reset all
 	values to startup defaults.</para>
 
       <para>Press <keycap>F1</keycap> to read the help screen about the
 	various options.</para>
 
       <para>Pressing <keycap>Q</keycap> will return to the Main Install
 	menu.</para>
     </sect2>
 
     <sect2 id="start-install">
       <title>Begin a Standard Installation</title>
 
       <para>The <guimenuitem>Standard</guimenuitem> installation is the
 	option recommended for those new to &unix; or FreeBSD.  Use the arrow
 	keys to select <guimenuitem>Standard</guimenuitem> and
 	then press <keycap>Enter</keycap> to start the installation.</para>
 
       <figure id="sysinstall-standard">
 	<title>Begin Standard Installation</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/main-std" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
     </sect2>
   </sect1>
 
   <sect1 id="install-steps">
     <title>Allocating Disk Space</title>
 
     <para>Your first task is to allocate disk space for FreeBSD, and label
       that space so that <application>sysinstall</application> can prepare
       it.  In order to do this you need to know how FreeBSD expects to find
       information on the disk.</para>
 
     <sect2 id="install-drive-bios-numbering">
       <title>BIOS Drive Numbering</title>
 
       <para>Before you install and configure FreeBSD on your system, there is an
 	important subject that you should be aware of, especially if you have
 	multiple hard drives.</para>
 
       <indexterm><primary>DOS</primary></indexterm>
       <indexterm><primary>Microsoft Windows</primary></indexterm>
       <para>In a PC running a BIOS-dependent operating system such as
 	&ms-dos; or &microsoft.windows;, the BIOS is able to abstract the
 	normal disk drive order, and
 	the operating system goes along with the change.  This allows the user
 	to boot from a disk drive other than the so-called <quote>primary
 	  master</quote>.  This is especially convenient for some users who have
 	found that the simplest and cheapest way to keep a system backup is to
 	buy an identical second hard drive, and perform routine copies of the
 	first drive to the second drive using 
 	<application><trademark class="registered">Ghost</trademark></application> or <application>XCOPY</application>
 	.  Then, if the
 	first drive fails, or is attacked by a virus, or is scribbled upon by an
 	operating system defect, he can easily recover by instructing the BIOS
 	to logically swap the drives.  It is like switching the cables on the
 	drives, but without having to open the case.</para>
 
       <indexterm><primary>SCSI</primary></indexterm>
       <indexterm><primary>BIOS</primary></indexterm>
       <para>More expensive systems with SCSI controllers often include BIOS
 	extensions which allow the SCSI drives to be re-ordered in a similar
 	fashion for up to seven drives.</para>
 
       <para>A user who is accustomed to taking advantage of these features may
 	become surprised when the results with FreeBSD are not as expected.
 	FreeBSD does not use the BIOS, and does not know the <quote>logical BIOS
 	  drive mapping</quote>.  This can lead to very perplexing situations,
 	especially when drives are physically identical in geometry, and have
 	also been made as data clones of one another.</para>
 
       <para>When using FreeBSD, always restore the BIOS to natural drive
 	numbering before installing FreeBSD, and then leave it that way.  If you
 	need to switch drives around, then do so, but do it the hard way, and
 	open the case and move the jumpers and cables.</para>
 
       <sidebar>
 	<title>An Illustration from the Files of Bill and Fred's Exceptional
 	  Adventures:</title>
       
 	<para>Bill breaks-down an older Wintel box to make another FreeBSD box
 	  for Fred.  Bill installs a single SCSI drive as SCSI unit zero and
 	  installs FreeBSD on it.</para>
 
 	<para>Fred begins using the system, but after several days notices that
 	  the older SCSI drive is reporting numerous soft errors and reports
 	  this fact to Bill.</para>
 
 	<para>After several more days, Bill decides it is time to address the
 	  situation, so he grabs an identical SCSI drive from the disk drive
 	  <quote>archive</quote> in the back room.  An initial surface scan
 	  indicates that
 	  this drive is functioning well, so Bill installs this drive as SCSI
 	  unit four and makes an image copy from drive zero to drive four.  Now
 	  that the new drive is installed and functioning nicely, Bill decides
 	  that it is a good idea to start using it, so he uses features in the
 	  SCSI BIOS to re-order the disk drives so that the system boots from
 	  SCSI unit four.  FreeBSD boots and runs just fine.</para>
 
 	<para>Fred continues his work for several days, and soon Bill and Fred
 	  decide that it is time for a new adventure &mdash; time to upgrade to a
 	  newer version of FreeBSD.  Bill removes SCSI unit zero because it was
 	  a bit flaky and replaces it with another identical disk drive from
 	  the <quote>archive</quote>.  Bill then installs the new version of
 	  FreeBSD onto the new SCSI unit zero using Fred's magic Internet FTP
 	  floppies.  The installation goes well.</para>
 
 	<para>Fred uses the new version of FreeBSD for a few days, and certifies
 	  that it is good enough for use in the engineering department.  It is
 	  time to copy all of his work from the old version.  So Fred mounts
 	  SCSI unit four (the latest copy of the older FreeBSD version).  Fred
 	  is dismayed to find that none of his precious work is present on SCSI
 	  unit four.</para>
 
 	<para>Where did the data go?</para>
 
 	<para>When Bill made an image copy of the original SCSI unit zero onto
 	  SCSI unit four, unit four became the <quote>new clone</quote>.
 	  When Bill re-ordered the SCSI BIOS so that he could boot from
 	  SCSI unit four, he was only fooling himself.
 	  FreeBSD was still running on SCSI unit zero.
 	  Making this kind of BIOS change will cause some or all of the Boot and
 	  Loader code to be fetched from the selected BIOS drive, but when the
 	  FreeBSD kernel drivers take-over, the BIOS drive numbering will be
 	  ignored, and FreeBSD will transition back to normal drive numbering.
 	  In the illustration at hand, the system continued to operate on the
 	  original SCSI unit zero, and all of Fred's data was there, not on SCSI
 	  unit four.  The fact that the system appeared to be running on SCSI
 	  unit four was simply an artifact of human expectations.</para>
 
 	<para>We are delighted to mention that no data bytes were killed or
 	  harmed in any way by our discovery of this phenomenon.  The older SCSI
 	  unit zero was retrieved from the bone pile, and all of Fred's work was
 	  returned to him, (and now Bill knows that he can count as high as
 	  zero).</para>
 
 	<para>Although SCSI drives were used in this illustration, the concepts
 	  apply equally to IDE drives.</para>
       </sidebar>
     </sect2>
 
     <sect2 id="main-fdisk">
       <title>Creating Slices Using FDisk</title>
 
       <note>
 	<para>No changes you make at this point will be written to the disk.
 	  If you think you have made a mistake and want to start again you can
 	  use the menus to exit <application>sysinstall</application> and try
 	  again or press <keycap>U</keycap> to use the <guimenuitem>Undo</guimenuitem> option.
 	  If you get confused and can not see how to exit you can
 	  always turn your computer off.</para>
       </note>
 
       <para>After choosing to begin a standard installation in
 	<application>sysinstall</application> you will be shown this
 	message:</para>
 
       <screen>                                 Message
  In the next menu, you will need to set up a DOS-style ("fdisk")
  partitioning scheme for your hard disk. If you simply wish to devote
  all disk space to FreeBSD (overwriting anything else that might be on
  the disk(s) selected) then use the (A)ll command to select the default
  partitioning scheme followed by a (Q)uit. If you wish to allocate only
  free space to FreeBSD, move to a partition marked "unused" and use the
  (C)reate command. 
                                 [  OK  ] 
 
                       [ Press enter or space ]</screen>
 
       <para>Press <keycap>Enter</keycap> as instructed.  You will then be
 	shown a list of all the hard drives that the kernel found when it
 	carried out the device probes.  
 	<xref linkend="sysinstall-fdisk-drive1"> shows an example from a
 	system with two IDE disks.  They have been called
 	<devicename>ad0</devicename> and <devicename>ad2</devicename>.</para>
 
       <figure id="sysinstall-fdisk-drive1">
 	<title>Select Drive for FDisk</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/fdisk-drive1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>You might be wondering why <devicename>ad1</devicename> is not
 	listed here.  Why has it been missed?</para>
 
       <para>Consider what would happen if you had two IDE hard disks, one
 	as the master on the first IDE controller, and one as the master on
 	the second IDE controller.  If FreeBSD numbered these as it found
 	them, as <devicename>ad0</devicename> and
 	<devicename>ad1</devicename> then everything would work.</para>
 
       <para>But if you then added a third disk, as the slave device on the
 	first IDE controller, it would now be <devicename>ad1</devicename>,
 	and the previous <devicename>ad1</devicename> would become
 	<devicename>ad2</devicename>.  Because device names (such as
 	<devicename>ad1s1a</devicename>) are used to find filesystems, you
 	may suddenly discover that some of your filesystems no longer
 	appear correctly, and you would need to change your FreeBSD
 	configuration.</para>
       
       <para>To work around this, the kernel can be configured to name IDE
 	disks based on where they are, and not the order in which they were
 	found.  With this scheme the master disk on the second IDE
 	controller will <emphasis>always</emphasis> be
 	<devicename>ad2</devicename>, even if there are no
 	<devicename>ad0</devicename> or <devicename>ad1</devicename>
 	devices.</para>
 
       <para>This configuration is the default for the FreeBSD kernel, which
 	is why this display shows <devicename>ad0</devicename> and
 	<devicename>ad2</devicename>.  The machine on which this screenshot
 	was taken had IDE disks on both master channels of the IDE
 	controllers, and no disks on the slave channels.</para>
 
       <para>You should select the disk on which you want to install FreeBSD,
 	and then press &gui.ok;.
 	<application>FDisk</application> will start, with a display similar to
 	that shown in <xref linkend="sysinstall-fdisk1">.</para>
 
       <para>The <application>FDisk</application> display is broken into three
 	sections.</para>
 
       <para>The first section, covering the first two lines of the display,
 	shows details about the currently selected disk, including its FreeBSD
 	name, the disk geometry, and the total size of the disk.</para>
 
       <para>The second section shows the slices that are currently on the
 	disk, where they start and end, how large they are, the name FreeBSD
 	gives them, and their description and sub-type.  This example shows two
 	small unused slices, which are artifacts of disk layout schemes on the
 	PC.  It also shows one large <acronym>FAT</acronym> slice, which almost certainly appears
 	as <devicename>C:</devicename> in &ms-dos; / &windows;, and an extended
 	slice, which may contain other drive letters for &ms-dos; / &windows;.</para>
 
       <para>The third section shows the commands that are available in
 	<application>FDisk</application>.</para>
 
       <figure id="sysinstall-fdisk1">
 	<title>Typical Fdisk Partitions before Editing</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/fdisk-edit1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>What you do now will depend on how you want to slice up your
 	disk.</para>
 
       <para>If you want to use FreeBSD for the entire disk (which will delete
 	all the other data on this disk when you confirm that you want
 	<application>sysinstall</application> to continue later in the
 	installation process) then you can press <keycap>A</keycap>, which
 	corresponds to the <guimenuitem>Use Entire Disk</guimenuitem> option.
 	The existing slices will be removed, and replaced with a small area
 	flagged as <literal>unused</literal> (again, an artifact of PC disk
 	layout), and then one large slice for FreeBSD.  If you do this, then
 	you should select the newly created FreeBSD slice using the arrow
 	keys, and press <keycap>S</keycap> to mark the slice as being
 	bootable.  The screen will then look very similar to 
 	<xref linkend="sysinstall-fdisk2">.  Note the
 	<literal>A</literal> in the <literal>Flags</literal> column, which
 	indicates that this slice is <emphasis>active</emphasis>, and will be
 	booted from.</para>
 
       <para>If you will be deleting an existing slice to make space for
 	FreeBSD then you should select the slice using the arrow keys, and
 	then press <keycap>D</keycap>.  You can then press <keycap>C</keycap>,
 	and be prompted for size of slice you want to create.  Enter the
 	appropriate figure and press <keycap>Enter</keycap>.  The default
         value in this box represents the largest possible slice you can
 	make, which could be the largest contiguous block of unallocated
 	space or the size of the entire hard disk.</para>
       
       <para>If you have already made space for FreeBSD (perhaps by using a
 	tool such as <application>&partitionmagic;</application>) then you can
 	press <keycap>C</keycap> to create a new slice.  Again, you will be
 	prompted for the size of slice you would like to create.</para>
 
       <figure id="sysinstall-fdisk2">
 	<title>Fdisk Partition Using Entire Disk</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/fdisk-edit2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>When finished, press <keycap>Q</keycap>.  Your changes will be
 	saved in <application>sysinstall</application>, but will not yet be
 	written to disk.</para>
     </sect2>
 
     <sect2 id="bootmgr">
       <title>Install a Boot Manager</title>
 
       <para>You now have the option to install a boot manager.  In general,
 	you should choose to install the FreeBSD boot manager if:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>You have more than one drive, and have installed FreeBSD onto
 	    a drive other than the first one.</para>
 	</listitem>
 
 	<listitem>
 	  <para>You have installed FreeBSD alongside another operating system
 	    on the same disk, and you want to choose whether to start FreeBSD
 	    or the other operating system when you start the computer.</para>
 	</listitem>
       </itemizedlist>
 
       <para>If FreeBSD is going to be the only operating system on
 	this machine, installed on the first hard disk, then the
 	<guimenuitem>Standard</guimenuitem> boot manager will suffice.
 	Choose <guimenuitem>None</guimenuitem> if you are using a
 	third-party boot manager capable of booting FreeBSD.</para>
 
       <para>Make your choice and press <keycap>Enter</keycap>.</para>
 
       <figure id="sysinstall-bootmgr">
 	<title>Sysinstall Boot Manager Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/boot-mgr" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The help screen, reached by pressing <keycap>F1</keycap>,
 	discusses the problems that can be encountered when trying to share
 	the hard disk between operating systems.</para>
     </sect2>
 
     <sect2>
       <title>Creating Slices on Another Drive</title>
 
       <para>If there is more than one drive, it will return to the
 	Select Drives screen after the boot manager selection.  If you wish to
 	install FreeBSD on to more than one disk, then you can select another
 	disk here and repeat the slice process using
 	<application>FDisk</application>.</para>
 
       <important>
 	<para>If you are installing FreeBSD on a drive other than your
 	  first, then the FreeBSD boot manager needs to be installed on
 	  both drives.</para>
       </important>
 
       <figure id="sysinstall-fdisk-drive2">
 	<title>Exit Select Drive</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/fdisk-drive2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The <keycap>Tab</keycap> key toggles between the last drive
 	selected, &gui.ok;, and 
 	&gui.cancel;.</para>
 
       <para>Press the <keycap>Tab</keycap> once to toggle to the
 	&gui.ok;, then
 	press <keycap>Enter</keycap>
 	to continue with the installation.</para>
     </sect2>
 
     <sect2 id="disklabeleditor">
       <title>Creating Partitions Using
 	<application>Disklabel</application></title>
       
       <para>You must now create some partitions inside each slice that you
 	have just created.  Remember that each partition is lettered, from
 	<literal>a</literal> through to <literal>h</literal>, and that
 	partitions <literal>b</literal>, <literal>c</literal>, and
 	<literal>d</literal> have conventional meanings that you should adhere
 	to.</para>
 
       <para>Certain applications can benefit from particular partition
 	schemes, especially if you are laying out partitions across more than
 	one disk.  However, for this, your first FreeBSD installation, you do
 	not need to give too much thought to how you partition the disk.  It
 	is more important that you install FreeBSD and start learning how to
 	use it.  You can always re-install FreeBSD to change your partition
 	scheme when you are more familiar with the operating system.</para>
 
       <para>This scheme features four partitions&mdash;one for swap space, and
 	three for filesystems.</para>
 
       <table frame="none" pgwide="1">
 	<title>Partition Layout for First Disk</title>
 
 	<tgroup cols="4">
           <colspec colwidth="1*">
           <colspec colwidth="1*">
           <colspec colwidth="1*">
           <colspec colwidth="4*">
 
 	  <thead>
 	    <row>
 	      <entry>Partition</entry>
 	      
 	      <entry>Filesystem</entry>
 
 	      <entry>Size</entry>
 
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><literal>a</literal></entry>
 
 	      <entry><filename>/</filename></entry>
 
 	      <entry>100&nbsp;MB</entry>
 
 	      <entry>This is the root filesystem.  Every other filesystem
 		will be mounted somewhere under this one.  100&nbsp;MB is a
 		reasonable size for this filesystem.  You will not be storing
 		too much data on it, as a regular FreeBSD install will put
 		about 40&nbsp;MB of data here.  The remaining space is for temporary
 		data, and also leaves expansion space if future versions of
 		FreeBSD need more space in <filename>/</filename>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>b</literal></entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>2-3 x RAM</entry>
 
 	      <entry><para>The system's swap space is kept on this partition.
 		  Choosing the right amount of swap space can be a bit of an
 		  art.  A good rule of thumb is that your swap
 		  space should be two or three times as much as the
 		  available physical memory (RAM).
 		  You should also have at least 64&nbsp;MB of swap, so if you have
 		  less than 32&nbsp;MB of RAM in your computer then set the swap
 		  amount to 64&nbsp;MB.</para><para>
 
 		  If you have more than one disk then you can put swap
 		  space on each disk.  FreeBSD will then use each disk for 
 		  swap, which effectively speeds up the act of swapping.  In
 		  this case, calculate the total amount of swap you need
 		  (e.g., 128&nbsp;MB), and then divide this by the number of disks
 		  you have (e.g., two disks) to give the amount of swap you
 		  should put on each disk, in this example, 64&nbsp;MB of swap per
 		  disk.</para></entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>e</literal></entry>
 
 	      <entry><filename>/var</filename></entry>
 
 	      <entry>50&nbsp;MB</entry>
 
 	      <entry>The <filename>/var</filename> directory contains
 		files that are constantly varying;
 		log files, and other administrative files.  Many
 		of these files are read-from or written-to extensively during
 		FreeBSD's day-to-day running.  Putting these files on another
 		filesystem allows FreeBSD to optimize the access of these
 		files without affecting other files in other directories that
 		do not have the same access pattern.</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>f</literal></entry>
 
 	      <entry><filename>/usr</filename></entry>
 
 	      <entry>Rest of disk</entry>
 
 	      <entry>All your other files will typically be stored in
 		<filename>/usr</filename> and its subdirectories.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
       
       <para>If you will be installing FreeBSD on to more than one disk then
 	you must also create partitions in the other slices that you
 	configured.  The easiest way to do this is to create two partitions on
 	each disk, one for the swap space, and one for a filesystem.</para>
 
       <table frame="none" pgwide="1">
 	<title>Partition Layout for Subsequent Disks</title>
 
 	<tgroup cols="4">
           <colspec colwidth="1*">
           <colspec colwidth="1*">
           <colspec colwidth="2*">
           <colspec colwidth="3*">
 
 	  <thead>
 	    <row>
 	      <entry>Partition</entry>
 	      
 	      <entry>Filesystem</entry>
 
 	      <entry>Size</entry>
 
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><literal>b</literal></entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>See description</entry>
 
 	      <entry>As already discussed, you can split swap space across
 		each disk.  Even though the <literal>a</literal> partition is
 		free, convention dictates that swap space stays on the
 		<literal>b</literal> partition.</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>e</literal></entry>
 
 	      <entry>/disk<replaceable>n</replaceable></entry>
 
 	      <entry>Rest of disk</entry>
 
 	      <entry>The rest of the disk is taken up with one big partition.
 		This could easily be put on the <literal>a</literal>
 		partition, instead of the <literal>e</literal> partition.
 		However, convention says that the <literal>a</literal>
 		partition on a slice is reserved for the filesystem that will
 		be the root (<filename>/</filename>) filesystem.  You do not
 		have to follow this convention, but
 		<application>sysinstall</application> does, so following it
 		yourself makes the installation slightly cleaner.  You can
 		choose to mount this filesystem anywhere; this example
 		suggests that you mount them as directories
 		<filename>/disk<replaceable>n</replaceable></filename>, where
 		<replaceable>n</replaceable> is a number that changes for each
 		disk.  But you can use another scheme if you prefer.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
       <para>Having chosen your partition layout you can now create it using
 	<application>sysinstall</application>.  You will see this
 	message:</para>
 
       <screen>                                 Message
  Now, you need to create BSD partitions inside of the fdisk
  partition(s) just created. If you have a reasonable amount of disk
  space (200MB or more) and don't have any special requirements, simply
  use the (A)uto command to allocate space automatically. If you have
  more specific needs or just don't care for the layout chosen by
  (A)uto, press F1 for more information on manual layout.  
 
                                 [  OK  ]
                           [ Press enter or space ]</screen>
 
       <para>Press <keycap>Enter</keycap> to start the FreeBSD partition
 	editor, called <application>Disklabel</application>.</para>
 
       <para><xref linkend="sysinstall-label"> shows the display when you first
 	start <application>Disklabel</application>.  The display is divided in
 	to three sections.</para>
 
       <para>The first few lines show the name of the disk you are currently
 	working on, and the slice that contains the partitions you are
 	creating (at this point <application>Disklabel</application> calls
 	this the <literal>Partition name</literal> rather than slice name).
 	This display also shows the amount of free space within the slice;
 	that is, space that was set aside in the slice, but that has not yet
 	been assigned to a partition.</para>
 
       <para>The middle of the display shows the partitions that have been
 	created, the name of the filesystem that each partition contains,
 	their size, and some options pertaining to the creation of the
 	filesystem.</para>
 
       <para>The bottom third of the screen shows the keystrokes that are valid
 	in <application>Disklabel</application>.</para>
 
       <figure id="sysinstall-label">
 	<title>Sysinstall Disklabel Editor</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-ed1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para><application>Disklabel</application> can automatically create
 	partitions for you and assign them default sizes.  Try this now, by
 	Pressing <keycap>A</keycap>.  You will see a display similar to that
 	shown in <xref linkend="sysinstall-label2">.  Depending on the size of
 	the disk you are using, the defaults may or may not be appropriate.
 	This does not matter, as you do not have to accept the
 	defaults.</para>
 
 	<note>
 	  <para>Beginning with FreeBSD&nbsp;4.5, the default partitioning assigns
 	    the <filename>/tmp</filename> directory its own partition instead
 	    of being part of the <filename>/</filename> partition.  This
 	    helps avoid filling the <filename>/</filename> partition with
 	    temporary files.</para>
 	</note>
 
       <figure id="sysinstall-label2">
 	<title>Sysinstall Disklabel Editor with Auto Defaults</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-auto" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>If you choose to not use the default partitions and wish to
 	replace them with your
 	own, use the arrow keys to select the first partition, and press
 	<keycap>D</keycap> to delete it.  Repeat this to delete all the
 	suggested partitions.</para>
 
       <para>To create the first partition (<literal>a</literal>, mounted as
 	<filename>/</filename> &mdash; root), make sure the proper disk slice at the top of
 	the screen is selected and press <keycap>C</keycap>.  A dialog box
 	will appear prompting you for the size of the new partition (as shown
 	in <xref linkend="sysinstall-label-add">).  You can enter the size as
 	the number of disk blocks you want to use, or as a
 	number followed by either <literal>M</literal> for megabytes,
 	<literal>G</literal> for gigabytes, or <literal>C</literal> for
 	cylinders.</para>
 
       <note><para>Beginning with FreeBSD&nbsp;5.X, users can: select
 	<acronym>UFS2</acronym> (which is default on &os;&nbsp;5.1 and
 	above) using the <literal>Custom Newfs</literal>
 	(<keycap>Z</keycap>) option, create labels with
 	<literal>Auto Defaults</literal> and modify them with the <literal>Custom Newfs</literal> option or
 	add <option>-O 2</option> during the regular creation period.
 	Do not forget to add <option>-U</option> for SoftUpdates if you use the <literal>Custom Newfs</literal>
 	option!</para></note>
 
       <figure id="sysinstall-label-add">
 	<title>Free Space for Root Partition</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-root1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The default size shown will create a partition that takes up the
 	rest of the slice.  If you are using the partition sizes described
 	in the earlier example, then delete the existing figure using
 	<keycap>Backspace</keycap>, and then type in
 	<userinput>64M</userinput>, as shown in 
 	<xref linkend="sysinstall-label-add2">.  Then press
 	&gui.ok;.</para>
       
       <figure id="sysinstall-label-add2">
 	<title>Edit Root Partition Size</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-root2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Having chosen the partition's size you will then be asked whether
 	this partition will contain a filesystem or swap space.  The dialog
 	box is shown in <xref linkend="sysinstall-label-type">.  This first
 	partition will contain a filesystem, so check that
 	<guimenuitem>FS</guimenuitem> is selected and press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="sysinstall-label-type">
 	<title>Choose the Root Partition Type</title>
 	
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-fs" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
       
       <para>Finally, because you are creating a filesystem, you must tell
 	<application>Disklabel</application> where the filesystem is to be
 	mounted.  The dialog box is shown in 
 	<xref linkend="sysinstall-label-mount">.  The root filesystem's mount
 	point is <filename>/</filename>, so type <userinput>/</userinput>, and
 	then press <keycap>Enter</keycap>.</para>
 
       <figure id="sysinstall-label-mount">
 	<title>Choose the Root Mount Point</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-root3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The display will then update to show you the newly created
 	partition.  You should repeat this procedure for the other
 	partitions.  When you create the swap partition, you will not be
 	prompted for the filesystem mount point, as swap partitions are never
 	mounted.  When you create the final partition,
 	<filename>/usr</filename>, you can leave the suggested size as is, to
 	use the rest of the slice.</para>
 
       <para>Your final FreeBSD DiskLabel Editor screen will appear similar to
 	<xref linkend="sysinstall-label4">, although your values chosen may
 	be different.  Press <keycap>Q</keycap> to finish.</para>
 
       <figure id="sysinstall-label4">
 	<title>Sysinstall Disklabel Editor</title>
 	
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-ed2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
     </sect2>
   </sect1>
 
   <sect1 id="install-choosing">
     <title>Choosing What to Install</title>
 
     <sect2 id="distset">
       <title>Select the Distribution Set</title>
 
       <para>Deciding which distribution set to install will depend largely
 	on the intended use of the system and the amount of disk space
 	available.  The predefined options range from installing the
 	smallest possible configuration to everything.  Those who are
 	new to &unix; and/or FreeBSD should almost certainly select one
 	of these canned options.  Customizing a distribution set is
 	typically for the more experienced user.</para>
 
       <para>Press <keycap>F1</keycap> for more information on the 
 	distribution set options and what they contain.  When finished
 	reviewing the help, pressing <keycap>Enter</keycap> will return
 	to the Select Distributions Menu.</para>
 
       <para>If a graphical user interface is desired then a distribution
 	set that is preceded by an <literal>X</literal> should be
 	chosen.  The configuration of the X server and selection of a default
 	desktop must be done after the installation of &os;.  More
 	information regarding the configuration of a X server can be
 	found in <xref linkend="x11">.</para>
 
       <para>The default version of X11 that is installed depends on the
 	version of FreeBSD that you are installing.  For FreeBSD versions
 	prior to 5.3, <application>&xfree86;&nbsp;4.X</application> is installed.  For &os;&nbsp;5.3 and later,
 	<application>&xorg;</application> is the default.</para>
 
       <para>If compiling a custom kernel is anticipated, select an option
 	which includes the source code.  For more information on why a
 	custom kernel should be built or how to build a custom kernel, see
 	<xref linkend="kernelconfig">.</para>
 
       <para>Obviously, the most versatile system is one that includes
 	everything.  If there is adequate disk space, select 
 	<guimenuitem>All</guimenuitem> as shown in
 	<xref linkend="distribution-set1"> by using the arrow keys and
 	press <keycap>Enter</keycap>.  If there is a concern about disk
 	space consider using an option that is more suitable for the
 	situation.
 	Do not fret over the perfect choice, as other distributions can be
 	added after installation.</para>
 
       <figure id="distribution-set1">
 	<title>Choose Distributions</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/dist-set" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
     </sect2>
 
     <sect2 id="portscol">
       <title>Installing the Ports Collection</title>
 
       <para>After selecting the desired distribution, an opportunity to
 	install the FreeBSD Ports Collection is presented.  The ports
 	collection is an easy and convenient way to install software.
 	The ports collection does not contain the source code necessary
 	to compile the software.  Instead, it is a collection of files which
 	automates the downloading, compiling and installation
 	of third-party software packages.
 	<xref linkend="ports"> discusses how to use the ports
 	collection.</para>
 
       <para>The installation program does not check to see if you have
 	adequate space.  Select this option only if you have
 	adequate hard disk space. As of FreeBSD &rel.current;, the FreeBSD
 	Ports Collection takes up about &ports.size; of disk space.
 	You can safely assume a larger value for more recent versions
 	of FreeBSD.</para>
 
 <screen>                         User Confirmation Requested
  Would you like to install the FreeBSD ports collection? 
 
  This will give you ready access to over &os.numports; ported software packages,
  at a cost of around &ports.size; of disk space when "clean" and possibly much
  more than that if a lot of the distribution tarballs are loaded
  (unless you have the extra CDs from a FreeBSD CD/DVD distribution
  available and can mount it on /cdrom, in which case this is far less
  of a problem). 
 
  The ports collection is a very valuable resource and well worth having
  on your /usr partition, so it is advisable to say Yes to this option. 
 
  For more information on the ports collection & the latest ports,
  visit: 
      http://www.FreeBSD.org/ports  
 
                               [ Yes ]     No</screen>
 
       <para>Select &gui.yes; with the arrow keys to
 	install the ports collection or &gui.no; to
 	skip this option.  Press <keycap>Enter</keycap> to continue.
 	The Choose Distributions menu will redisplay.</para>
 
       <figure id="distribution-set2">
 	<title>Confirm Distributions</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/dist-set2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>If satisfied with the options, select
 	<guimenuitem>Exit</guimenuitem> with the arrow keys, ensure that
 	&gui.ok; is highlighted, and pressing
 	<keycap>Enter</keycap> to continue.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="install-media">
     <title>Choosing Your Installation Media</title>
 
     <para>If Installing from a CDROM or DVD, use the arrow keys to highlight 
       <guimenuitem>Install from a FreeBSD CD/DVD</guimenuitem>.  Ensure
       that &gui.ok; is highlighted, then press
       <keycap>Enter</keycap> to proceed with the installation.</para>
     
     <para>For other methods of installation, select the appropriate
       option and follow the instructions.</para>
 
     <para>Press <keycap>F1</keycap> to display the Online Help for
       installation media.  Press <keycap>Enter</keycap> to return
       to the media selection menu.</para>
 
     <figure id="choose-media">
       <title>Choose Installation Media</title>
 
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="install/media" format="PNG">
 	</imageobject>
       </mediaobject>
     </figure>
 
     <note>
       <title>FTP Installation Modes</title>
 
       <indexterm>
 	<primary>installation</primary>
 	<secondary>network</secondary>
 	<tertiary>FTP</tertiary>
       </indexterm>
       
       <para>There are three FTP installation modes you can choose from:
 	active FTP, passive FTP, or via a HTTP proxy.</para>
 
       <variablelist>
 	<varlistentry>
 	  <term>FTP Active: <guimenuitem>Install from an FTP
 	      server</guimenuitem></term>
 	  
 	  <listitem>
 	    <para>This option will make all FTP transfers 
 	      use <quote>Active</quote>
 	      mode.  This will not work through firewalls, but will
 	      often work with older FTP servers that do not support
 	      passive mode.  If your connection hangs with passive
 	      mode (the default), try active!</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term>FTP Passive: <guimenuitem>Install from an FTP server through a
 	      firewall</guimenuitem></term>
 	  
 	  <listitem>
 	    <indexterm>
 	      <primary>FTP</primary>
 	      <secondary>passive mode</secondary>
 	    </indexterm>
 
 	    <para>This option instructs <application>sysinstall</application> to use 
 	      <quote>Passive</quote> mode for all FTP operations.  
 	      This allows the user to pass through firewalls
 	      that do not allow incoming connections on random TCP ports.
 	    </para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term>FTP via a HTTP proxy: <guimenuitem>Install from an FTP server
 	      through a http proxy</guimenuitem></term>
 	    
 	  <listitem>
 	    <indexterm>
 	      <primary>FTP</primary>
 	      <secondary>via a HTTP proxy</secondary>
 	    </indexterm>
 	    
 	    <para>This option instructs <application>sysinstall</application> to use the HTTP
 	      protocol (like a web browser) to connect to a proxy
 	      for all FTP operations.  The proxy will translate
 	      the requests and send them to the FTP server.
 	      This allows the user to pass through firewalls
 	      that do not allow FTP at all, but offer a HTTP
 	      proxy.
 	      In this case, you have to specify the proxy in
 	      addition to the FTP server.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <para>For a proxy FTP server, you should usually give the name of the
 	server you really want as a part of the username, after an
 	<quote>@</quote> sign.  The proxy server then <quote>fakes</quote>
 	the real server.  For example, assuming you want to install from
 	<hostid role="fqdn">ftp.FreeBSD.org</hostid>, using the proxy FTP
 	server <hostid role="fqdn">foo.example.com</hostid>, listening on port
 	1024.</para>
       
       <para>In this case, you go to the options menu, set the FTP username
 	to <literal>ftp@ftp.FreeBSD.org</literal>, and the password to your
 	email address.  As your installation media, you specify FTP (or
 	passive FTP, if the proxy supports it), and the URL
 	<literal>ftp://foo.example.com:1234/pub/FreeBSD</literal>.</para>
 
       <para>Since <filename>/pub/FreeBSD</filename> from 
 	<hostid role="fqdn">ftp.FreeBSD.org</hostid> is proxied under 
 	<hostid role="fqdn">foo.example.com</hostid>, you are able to install
 	from <emphasis>that</emphasis> machine (which will fetch the files
 	from <hostid role="fqdn">ftp.FreeBSD.org</hostid> as your 
 	installation requests them).</para>
     </note>
   </sect1>
 
   <sect1 id="install-final-warning">
     <title>Committing to the Installation</title>
 
     <para>The installation can now proceed if desired.  This is also
       the last chance for aborting the installation to prevent changes
       to the hard drive.</para>
 
     <screen>                       User Confirmation Requested
  Last Chance! Are you SURE you want to continue the installation? 
 
  If you're running this on a disk with data you wish to save then WE
  STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! 
 
  We can take no responsibility for lost disk contents!  
 
                              [ Yes ]    No</screen>
 
     <para>Select &gui.yes; and press 
       <keycap>Enter</keycap> to proceed.</para>
 
     <para>The installation time will vary according to the distribution
       chosen, installation media, and the speed of the computer.
       There will be a series of
       messages displayed indicating the status.</para>
     
     <para>The installation is complete when the following message is
       displayed:</para>
 
     <screen>                               Message 
 
 Congratulations! You now have FreeBSD installed on your system. 
 
 We will now move on to the final configuration questions. 
 For any option you do not wish to configure, simply select No. 
 
 If you wish to re-enter this utility after the system is up, you may
 do so by typing: /stand/sysinstall .  
 
                                  [ OK ] 
 
                       [  Press enter to continue  ]</screen>
 
     <para>Press <keycap>Enter</keycap> to proceed with post-installation
       configurations.</para>
 
     <para>Selecting &gui.no; and pressing
       <keycap>Enter</keycap> will abort
       the installation so no changes will be made to your system.  The
       following message will appear:</para>
 
     <screen>                                Message
 Installation complete with some errors.  You may wish to scroll
 through the debugging messages on VTY1 with the scroll-lock feature. 
 You can also choose "No" at the next prompt and go back into the
 installation menus to retry whichever operations have failed. 
 
                                  [ OK ]</screen>
 
     <para>This message is generated because nothing was installed.
       Pressing <keycap>Enter</keycap> will return to the
       Main Installation Menu to exit the installation.</para>
   </sect1>
 
   <sect1 id="install-post">
     <title>Post-installation</title>
 
     <para>Configuration of various options follows the successful 
       installation.    An option can be configured by re-entering the
       configuration options before booting the new FreeBSD
       system or after installation using
       <command>sysinstall</command> (<command>/stand/sysinstall</command>
       in &os; versions older than 5.2) and selecting
       <guimenuitem>Configure</guimenuitem>.</para>
 
     <sect2 id="inst-network-dev">
       <title>Network Device Configuration</title>
 
       <para>If you previously configured PPP for an FTP install, this screen
 	will not display and can be configured later as described
 	above.</para>
 
       <para>For detailed information on Local Area Networks and
 	configuring FreeBSD as a gateway/router refer to the
 	<link linkend="advanced-networking">Advanced Networking</link>
 	chapter.</para>
 
       <screen>                      User Confirmation Requested 
    Would you like to configure any Ethernet or SLIP/PPP network devices?
 
                              [ Yes ]   No</screen>
 
       <para>To configure a network device, select
 	&gui.yes; and press <keycap>Enter</keycap>.
       Otherwise, select &gui.no; to continue.</para>
 
       <figure id="ed-config1">
 	<title>Selecting an Ethernet Device</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/ed0-conf" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select the interface to be configured with the arrow keys and press
 	<keycap>Enter</keycap>.</para>
 
       <screen>                      User Confirmation Requested 
        Do you want to try IPv6 configuration of the interface?
 
                               Yes   [ No ]</screen>
 
       <para>In this private local area network, the current Internet
 	type protocol (<acronym>IPv4</acronym>) was sufficient and &gui.no;
 	was selected with the arrow keys and <keycap>Enter</keycap>
 	pressed.</para>
 
       <para>If you are connected to an existing <acronym>IPv6</acronym> network
 	with an <acronym>RA</acronym> server, then choose
 	&gui.yes; and press <keycap>Enter</keycap>.
 	It will take several seconds to scan for RA servers.</para>
 
       <screen>                             User Confirmation Requested 
         Do you want to try DHCP configuration of the interface?
 
                               Yes   [ No ]</screen>
 
       <para>If DHCP (Dynamic Host Configuration Protocol) is not required
 	select &gui.no; with the arrow keys and press
 	<keycap>Enter</keycap>.</para>
 
       <para>Selecting &gui.yes; will execute
 	<application>dhclient</application>, and if successful, will fill
 	in the network configuration information automatically.  Refer to
 	<xref linkend="network-dhcp"> for more information.</para>
 
       <para>The following Network Configuration screen shows the
 	configuration of the Ethernet device for a system that will act
 	as the gateway for a Local Area Network.</para>
 
       <figure id="ed-config2">
 	<title>Set Network Configuration for ed0</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/ed0-conf2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use <keycap>Tab</keycap> to select the information fields and
 	fill in appropriate information:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term>Host</term>
 
 	  <listitem>
 	    <para>The fully-qualified hostname, such as <hostid role="fqdn">k6-2.example.com</hostid> in
 	      this case.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Domain</term>
 
 	  <listitem>
 	    <para>The name of the domain that your machine is
 	      in, such as <hostid role="domainname">example.com</hostid> for this case.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>IPv4 Gateway</term>
 
 	  <listitem>
 	    <para>IP address of host forwarding packets to non-local
 	      destinations.  You must fill this in if the machine is a node
 	      on the network.  <emphasis>Leave this field blank</emphasis>
 	      if the machine is the gateway to the Internet for the
 	      network.  The IPv4 Gateway is also known as the default
 	      gateway or default route.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Name server</term>
 
 	  <listitem>
 	    <para>IP address of your local DNS server.  There is no local
 	      DNS server on this private local area network so the IP
 	      address of the provider's DNS server
 	      (<hostid role="ipaddr">208.163.10.2</hostid>) was used.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>IPv4 address</term>
 
 	  <listitem>
 	    <para>The IP address to be used for this interface was
 	      <hostid role="ipaddr">192.168.0.1</hostid></para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Netmask</term>
 
 	  <listitem>
 	    <para>The address block being used for this local area
 	      network is a Class C block
 	      (<hostid role="ipaddr">192.168.0.0</hostid> -
 	      <hostid role="ipaddr">192.168.255.255</hostid>).
 	      The default netmask is for a Class C network
 	      (<hostid role="netmask">255.255.255.0</hostid>).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Extra options to ifconfig</term>
 
 	  <listitem>
 	    <para>Any interface-specific options to <command>ifconfig</command>
 	      you would like to add.  There were none in this case.</para>
 	  </listitem>
 	</varlistentry>
 
       </variablelist>
 
       <para>Use <keycap>Tab</keycap> to select &gui.ok;
 	when finished and press <keycap>Enter</keycap>.</para>
 
 
       <screen>                      User Confirmation Requested 
         Would you like to Bring Up the ed0 interface right now?
 
                              [ Yes ]   No</screen>
 
       <para>Choosing &gui.yes; and pressing
 	<keycap>Enter</keycap> will bring
 	the machine up on the network and be ready for use.  However,
 	this does not accomplish much during installation, since
 	the machine still needs to be rebooted.</para>
     </sect2>
 
     <sect2 id="gateway">
       <title>Configure Gateway</title>
 
       <screen>                       User Confirmation Requested 
        Do you want this machine to function as a network gateway?
 
                               [ Yes ]    No</screen>
 
       <para>If the machine will be acting as the gateway for a local area
 	network and forwarding packets between other machines then select
 	&gui.yes; and press <keycap>Enter</keycap>.
 	If the machine is a node on a network then 
 	select &gui.no; and press
 	<keycap>Enter</keycap> to continue.</para>
     </sect2>
 
     <sect2 id="inetd-services">
       <title>Configure Internet Services</title>
 
       <screen>                      User Confirmation Requested
 Do you want to configure inetd and the network services that it provides?
 
                                Yes   [ No ]</screen>
 
       <para>If &gui.no; is selected, various services
 	such <application>telnetd</application> will not be enabled.  This
 	means that remote users will not be able to
 	<application>telnet</application> into this machine.  Local users
 	will be still be able to access remote machines with
 	<application>telnet</application>.</para>
 
       <para>These services can be enabled after installation by editing
 	<filename>/etc/inetd.conf</filename> with your favorite text editor.
 	See <xref linkend="network-inetd-overview"> for more information.</para>
 
       <para>Select &gui.yes; if you wish to
 	configure these services during install.  An additional
 	confirmation will display:</para>
 
       <screen>                      User Confirmation Requested
 The Internet Super Server (inetd) allows a number of simple Internet
 services to be enabled, including finger, ftp and telnetd.  Enabling
 these services may increase risk of security problems by increasing
 the exposure of your system.
 
 With this in mind, do you wish to enable inetd?
 
                              [ Yes ]   No</screen>
 
       <para>Select &gui.yes; to continue.</para>
 
       <screen>                      User Confirmation Requested
 inetd(8) relies on its configuration file, /etc/inetd.conf, to determine
 which of its Internet services will be available.  The default FreeBSD
 inetd.conf(5) leaves all services disabled by default, so they must be
 specifically enabled in the configuration file before they will
 function, even once inetd(8) is enabled.  Note that services for
 IPv6 must be separately enabled from IPv4 services.
 
 Select [Yes] now to invoke an editor on /etc/inetd.conf, or [No] to
 use the current settings.
 
                              [ Yes ]   No</screen>
 
       <para>Selecting &gui.yes; will allow adding
 	services by deleting the <literal>#</literal> at the beginning
 	of a line.</para>
 
       <figure id="inetd-edit">
 	<title>Editing <filename>inetd.conf</filename></title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/edit-inetd-conf" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>After adding the desired services, pressing <keycap>Esc</keycap>
 	will display a menu which will allow exiting and saving 
 	the changes.</para>
 
     </sect2>
 
     <sect2 id="ftpanon">
       <title>Anonymous FTP</title>
 
+      <indexterm>
+	<primary>FTP</primary>
+	<secondary>anonymous</secondary>
+      </indexterm>
+
       <screen>                      User Confirmation Requested
  Do you want to have anonymous FTP access to this machine? 
 
                               Yes    [ No ]</screen>
 
       <sect3 id="deny-anon">
 	<title>Deny Anonymous FTP</title>
       
 	<para>Selecting the default &gui.no; and pressing
 	  <keycap>Enter</keycap> will still allow users who have accounts
 	  with passwords to use FTP to access the machine.</para>
       </sect3>
 
       <sect3 id="ftpallow">
 	<title>Allow Anonymous FTP</title>
 
 	<para>Anyone can access your machine if you elect to allow
 	  anonymous FTP connections.  The security implications should be
 	  considered before enabling this option.  For more information
 	  about security see <xref linkend="security">.</para>
 
 	<para>To allow anonymous FTP, use the arrow keys to select
 	  &gui.yes; and press <keycap>Enter</keycap>.
 	  The following screen (or similar) will display:</para>
 
 	<figure id="anon-ftp2">
 	  <title>Default Anonymous FTP Configuration</title>
 
 	  <mediaobject>
 	    <imageobject>
 	      <imagedata fileref="install/ftp-anon1" format="PNG">
 	    </imageobject>
 	  </mediaobject>
 	</figure>
 
 	<para>Pressing <keycap>F1</keycap> will display the help:</para>
 
 	<screen>This screen allows you to configure the anonymous FTP user.
 
 The following configuration values are editable:
 
 UID:     The user ID you wish to assign to the anonymous FTP user.
          All files uploaded will be owned by this ID.
 
 Group:   Which group you wish the anonymous FTP user to be in.
 
 Comment: String describing this user in /etc/passwd
 
 
 FTP Root Directory:
 
         Where files available for anonymous FTP will be kept.
 
 Upload subdirectory:
 
         Where files uploaded by anonymous FTP users will go.</screen>
 
 	<para>The ftp root directory will be put in <filename>/var</filename>
 	  by default.  If you do not have enough room there for the
 	  anticipated FTP needs, the <filename>/usr</filename> directory
 	  could be used by setting the FTP Root Directory to
 	  <filename>/usr/ftp</filename>.</para>
 
 	<para>When you are satisfied with the values, press 
 	  <keycap>Enter</keycap> to continue.</para>
 
 	<screen>                          User Confirmation Requested 
          Create a welcome message file for anonymous FTP users?
 
                               [ Yes ]    No</screen>
 
 	<para>If you select &gui.yes; and press
 	  <keycap>Enter</keycap>, an editor will automatically start
 	  allowing you to edit the message.</para>
 
 	<figure id="anon-ftp4">
 	  <title>Edit the FTP Welcome Message</title>
 
 	  <mediaobject>
 	    <imageobject>
 	      <imagedata fileref="install/ftp-anon2" format="PNG">
 	    </imageobject>
 	  </mediaobject>
 	</figure>
 
 	<para>This is a text editor called <command>ee</command>.  Use the
 	  instructions to change the message or change the message later
 	  using a text editor of your choice.  Note the file name/location
 	  at the bottom of the editor screen.</para>
 
 	<para>Press <keycap>Esc</keycap> and a pop-up menu will default
 	  to <guimenuitem>a) leave editor</guimenuitem>.  Press
 	  <keycap>Enter</keycap> to exit and continue.  Press
 	  <keycap>Enter</keycap> again to save changes if you made
 	  any.</para>
       </sect3>
     </sect2>
 
     <sect2 id="nfsconf">
       <title>Configure Network File System</title>
 
       <para>Network File System (NFS) allows sharing of files across a
 	network.  A machine can be configured as a server, a client, or
 	both.  Refer to <xref linkend="network-nfs"> for a more information.</para>
 
       <sect3 id="nsf-server-options">
 	<title>NFS Server</title>
 
 	<screen>                       User Confirmation Requested
  Do you want to configure this machine as an NFS server? 
 
                               Yes    [ No ]</screen>
 
 	<para>If there is no need for a Network File System server,
 	  select &gui.no; and press
 	  <keycap>Enter</keycap>.</para>
 
 	<para>If &gui.yes; is chosen, a message will
 	  pop-up indicating that the <filename>exports</filename> file must be
 	  created.</para>
 
 	<screen>                               Message
 Operating as an NFS server means that you must first configure an
 /etc/exports file to indicate which hosts are allowed certain kinds of
 access to your local filesystems.
 Press [Enter] now to invoke an editor on /etc/exports
                                [ OK ]</screen>
 
 	<para>Press <keycap>Enter</keycap> to continue.  A text editor will
 	  start allowing the <filename>exports</filename> file to be created
 	  and edited.</para>
 
 	<figure id="nfs-server-edit">
 	  <title>Editing <filename>exports</filename></title>
 
 	  <mediaobject>
 	    <imageobject>
 	      <imagedata fileref="install/nfs-server-edit" format="PNG">
 	    </imageobject>
 	  </mediaobject>
 	</figure>
 
 	<para>Use the instructions to add the actual exported filesystems
 	  now or later using a text editor of your choice.  Note the
 	  file name/location at the bottom of the editor screen.</para>
 
 	<para>Press <keycap>Esc</keycap> and a pop-up menu will default to
 	  <guimenuitem>a) leave editor</guimenuitem>.  Press
 	  <keycap>Enter</keycap> to exit and continue.</para>
       </sect3>
 
       <sect3 id="nfs-client-options">
 	<title>NFS Client</title>
 
 	<para>The NFS client allows your machine to access NFS servers.</para>
 
 	<screen>                       User Confirmation Requested
  Do you want to configure this machine as an NFS client? 
 
                               Yes   [ No ]</screen>
 
 	<para>With the arrow keys, select &gui.yes;
 	  or &gui.no; as appropriate and
 	  press <keycap>Enter</keycap>.</para>
       </sect3>
     </sect2>
 
     <sect2 id="securityprofile">
       <title>Security Profile</title>
 
       <para>A <quote>security profile</quote> is a set of
 	configuration options that attempts to achieve the desired
 	ratio of security to convenience by enabling and disabling
 	certain programs and other settings.  The more severe the
 	security profile, the fewer programs will be enabled by
 	default.  This is one of the basic principles of security: do
 	not run anything except what you must.</para>
 
       <para>Please note that the security profile is just a default
 	setting.  All programs can be enabled and disabled after you
 	have installed FreeBSD by editing or adding the appropriate
 	line(s) to <filename>/etc/rc.conf</filename>.  For more
 	information, please see the &man.rc.conf.5; manual
 	page.</para>
 
       <para>The following table describes what each of the security
 	profiles does.  The columns are the choices you have for a
 	security profile, and the rows are the program or feature that
 	the profile enables or disables.</para>
 
       <table>
 	<title>Possible Security Profiles</title>
 
 	<tgroup cols=3>
 	  <thead>
 	    <row>
 	      <entry></entry>
 
 	      <entry>Extreme</entry>
 
 	      <entry>Moderate</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 
 	    <row>
 	      <entry>&man.sendmail.8;</entry>
 
 	      <entry>NO</entry>
 
 	      <entry>YES</entry>
 	    </row>
 
 	    <row>
 	      <entry>&man.sshd.8;</entry>
 
 	      <entry>NO</entry>
 
 	      <entry>YES</entry>
 	    </row>
 
 	    <row>
 	      <entry>&man.portmap.8;</entry>
 
 	      <entry>NO</entry>
 
 	      <entry>MAYBE
 		<footnote>
 		  <para>The portmapper is enabled if the machine has
 		    been configured as an NFS client or server earlier
 		    in the installation.</para>
 		</footnote>
 	      </entry>
 	    </row>
 
 	    <row>
 	      <entry>NFS server</entry>
 
 	      <entry>NO</entry>
 
 	      <entry>YES</entry>
 	    </row>
 
 	    <row>
 	      <entry>&man.securelevel.8;</entry>
 
 	      <entry>YES
 		<footnote>
 		  <para>If you choose a security profile that sets the
 		    securelevel to <quote>Extreme</quote> or
 		    <quote>High</quote>, you must be aware of the
 		    implications.  Please read the &man.init.8;
 		    manual page and pay particular attention to the
 		    meanings of the security levels, or you may have
 		    significant trouble later!</para>
 		</footnote>
 	      </entry>
 
 	      <entry>NO</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
       <screen>                       User Confirmation Requested
  Do you want to select a default security profile for this host (select
  No for "medium" security)? 
 
                             [ Yes ]    No</screen>
 
       <para>Selecting &gui.no; and pressing
 	<keycap>Enter</keycap> will set the security profile to medium.</para>
 
       <para>Selecting &gui.yes; and pressing
 	<keycap>Enter</keycap> will allow selecting a different security
 	profile.</para>
 
       <figure id="security-profile">
 	<title>Security Profile Options</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/security" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Press <keycap>F1</keycap> to display the help.  Press
 	<keycap>Enter</keycap> to return to selection menu.</para>
 
       <para>Use the arrow keys to choose <guimenuitem>Medium</guimenuitem>
 	unless your are sure that another level is required for your needs.
 	With &gui.ok; highlighted, press
 	<keycap>Enter</keycap>.</para>
 
       <para>An appropriate confirmation message will display depending on
 	which security setting was chosen.</para>
 
       <screen>                                 Message
 
 Moderate security settings have been selected.
 
 Sendmail and SSHd have been enabled, securelevels are
 disabled, and NFS server setting have been left intact.
 PLEASE NOTE that this still does not save you from having
 to properly secure your system in other ways or exercise
 due diligence in your administration, this simply picks
 a standard set of out-of-box defaults to start with.
 
 To change any of these settings later, edit /etc/rc.conf
 
                                   [OK]</screen>
 
       <screen>                                 Message
 
 Extreme security settings have been selected.
 
 Sendmail, SSHd, and NFS services have been disabled, and
 securelevels have been enabled.
 PLEASE NOTE that this still does not save you from having
 to properly secure your system in other ways or exercise
 due diligence in your administration, this simply picks
 a more secure set of out-of-box defaults to start with.
 
 To change any of these settings later, edit /etc/rc.conf
 
                                   [OK]</screen>
 
       <para>Press <keycap>Enter</keycap> to continue with the
 	post-installation configuration.</para>
 
       <warning>
 	<para>The security profile is not a silver bullet!  Even if
 	  you use the extreme setting, you need to keep up with
 	  security issues by reading an appropriate mailing
 	  list (<xref linkend="eresources-mail">),
 	  using good passwords and passphrases, and
 	  generally adhering to good security practices.  It simply
 	  sets up the desired security to convenience ratio out of the
 	  box.</para>
       </warning>
 
     </sect2>
 
     <sect2 id="console">
       <title>System Console Settings</title>
 
       <para>There are several options available to customize the system
 	console.</para>
 
       <screen>                      User Confirmation Requested 
        Would you like to customize your system console settings?
 
                               [ Yes ]  No</screen>
 
       <para>To view and configure the options, select
 	&gui.yes; and press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="saver-options">
 	<title>System Console Configuration Options</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/console-saver1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>A commonly used option is the screen saver.  Use the arrow keys
 	to select <guimenuitem>Saver</guimenuitem> and then press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="saver-select">
 	<title>Screen Saver Options</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/console-saver2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select the desired screen saver using the arrow keys
 	and then press <keycap>Enter</keycap>.  The System Console
 	Configuration menu will redisplay.</para>
 
       <para>The default time interval is 300 seconds.  To change the time
 	interval, select <guimenuitem>Saver</guimenuitem> again.  At the
 	Screen Saver Options menu, select <guimenuitem>Timeout</guimenuitem>
 	using the arrow keys and press <keycap>Enter</keycap>.  A pop-up
 	menu will appear:</para>
 
       <figure id="saver-timeout">
 	<title>Screen Saver Timeout</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/console-saver3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The value can be changed, then select &gui.ok;
 	and press <keycap>Enter</keycap> to return to the System Console
 	Configuration menu.</para>
 
       <figure id="saver-exit">
 	<title>System Console Configuration Exit</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/console-saver4" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Selecting <guimenuitem>Exit</guimenuitem> and pressing
 	<keycap>Enter</keycap> will continue with the post-installation
 	configurations.</para>
     </sect2>
 
     <sect2 id="timezone">
       <title>Setting the Time Zone</title>
 
       <para>Setting the time zone for your machine will allow it to
 	automatically correct for any regional time changes and perform
 	other time zone related functions properly.</para>
 
       <para>The example shown is for a machine located in the Eastern
 	time zone of the United States.  Your selections will vary according
 	to your geographical location.</para>
 
       <screen>                      User Confirmation Requested 
           Would you like to set this machine's time zone now?
 
                             [ Yes ]   No</screen>
 
       <para>Select &gui.yes; and press
 	<keycap>Enter</keycap> to set the time zone.</para>
 
       <screen>                       User Confirmation Requested
  Is this machine's CMOS clock set to UTC? If it is set to local time
  or you don't know, please choose NO here! 
 
                               Yes   [ No ]</screen>
 
       <para>Select &gui.yes; 
 	or &gui.no; according to how the machine's
 	clock is configured and press <keycap>Enter</keycap>.</para>
 
       <figure id="set-timezone-region">
 	<title>Select Your Region</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/timezone1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The appropriate region is selected using the arrow keys
 	and then pressing <keycap>Enter</keycap>.</para>
 
       <figure id="set-timezone-country">
 	<title>Select Your Country</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/timezone2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select the appropriate country using the arrow keys
 	and press <keycap>Enter</keycap>.</para>
 
       <figure id="set-timezone-locality">
 	<title>Select Your Time Zone</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/timezone3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The appropriate time zone is selected using the arrow
 	keys and pressing <keycap>Enter</keycap>.</para>
 
       <screen>                            Confirmation 
             Does the abbreviation 'EDT' look reasonable?
 
                             [ Yes ]   No</screen>
 
       <para>Confirm the abbreviation for the time zone is correct.
 	If it looks okay, press <keycap>Enter</keycap> to continue with
 	the post-installation configuration.</para>
     </sect2>
 
     <sect2 id="linuxcomp">
       <title>Linux Compatibility</title>
 
       <screen>                      User Confirmation Requested 
           Would you like to enable Linux binary compatibility?
 
                             [ Yes ]   No</screen>
 
       <para>Selecting &gui.yes; and pressing
 	<keycap>Enter</keycap> will allow
 	running Linux software on FreeBSD.  The install will add
 	the appropriate packages for Linux compatibility.</para>
 
       <para>If installing by FTP, the machine will need to be connected to
 	the Internet.  Sometimes a remote ftp site will not have all the
 	distributions like the Linux binary compatibility.  This can
 	be installed later if necessary.</para>
     </sect2>
 
     <sect2 id="mouse">
       <title>Mouse Settings</title>
 
       <para>This option will allow you to cut and paste text in the
 	console and user programs with a 3-button mouse.  If using a 2-button
 	mouse, refer to manual page, &man.moused.8;, after installation for
 	details on emulating the 3-button style.  This example depicts a
 	non-USB mouse configuration (such as a PS/2 or COM port mouse):</para>
 
       <screen>                      User Confirmation Requested 
          Does this system have a non-USB mouse attached to it?
 
                             [ Yes ]    No </screen>
 
       <para>Select &gui.yes; for a non-USB mouse or
 	&gui.no; for a USB mouse and press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="mouse-protocol">
 	<title>Select Mouse Protocol Type</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the arrow keys to select <guimenuitem>Type</guimenuitem> and
 	press <keycap>Enter</keycap>.</para>
 
       <figure id="set-mouse-protocol">
 	<title>Set Mouse Protocol</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The mouse used in this example is a PS/2 type, so the default
 	<guimenuitem>Auto</guimenuitem> was appropriate.  To change protocol,
 	use the arrow keys to select another option.  Ensure that &gui.ok; is
 	highlighted and press <keycap>Enter</keycap> to exit this menu.</para>
 
       <figure id="config-mouse-port">
 	<title>Configure Mouse Port</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the arrow keys to select <guimenuitem>Port</guimenuitem> and
 	press <keycap>Enter</keycap>.</para>
 
       <figure id="set-mouse-port">
 	<title>Setting the Mouse Port</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse4" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>This system had a PS/2 mouse, so the default
 	<guimenuitem>PS/2</guimenuitem> was appropriate.  To change the port,
 	use the arrow keys and then press <keycap>Enter</keycap>.</para>
 
       <figure id="test-daemon">
 	<title>Enable the Mouse Daemon</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse5" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Last, use the arrow keys to select
 	<guimenuitem>Enable</guimenuitem>, and press
 	<keycap>Enter</keycap> to enable and test the mouse
 	daemon.</para>
 
 
       <figure id="test-mouse-daemon">
 	<title>Test the Mouse Daemon</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse6" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Move the mouse around the screen and verify the cursor
 	shown responds properly.  If it does, select
 	&gui.yes; and press <keycap>Enter</keycap>.  If
 	not, the mouse has not been configured correctly &mdash; select
 	&gui.no; and try using different configuration
 	options.</para>
 
       <para>Select <guimenuitem>Exit</guimenuitem> with the arrow keys
 	and press <keycap>Enter</keycap> to return to continue with the
 	post-installation configuration.</para>
     </sect2>
 
     <sect2 id="network-services">
       <title>Configure Additional Network Services</title>
 
       <para>Configuring network services can be a daunting
 	task for new users if they lack previous
 	knowledge in this area.  Networking, including the Internet,
 	is critical to all modern operating systems including &os;;
 	as a result, it is very useful to have some understanding
 	&os;'s extensive networking capabilities.  Doing this
 	during the installation will ensure users have some
 	understanding of the various services available to them.</para>
 
       <para>Network services are programs that accept input from
 	anywhere on the network.  Every effort is made to make sure
 	these programs will not do anything <quote>harmful</quote>.
 	Unfortunately, programmers are not perfect and through time
 	there have been cases where bugs in network services have been
 	exploited by attackers to do bad things.  It is important that
 	you only enable the network services you know that you need.  If
 	in doubt it is best if you do not enable a network service until
 	you find out that you do need it.  You can always enable it
 	later by re-running <application>sysinstall</application> or by
 	using the features provided by the
 	<filename>/etc/rc.conf</filename> file.</para>
 
       <para>Selecting the <guimenu>Networking</guimenu> option will display
 	a menu similar to the one below:</para>
 
       <figure id="network-configuration">
 	<title>Network Configuration Upper-level</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/net-config-menu1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The first option, <guimenuitem>Interfaces</guimenuitem>, was previously covered during
 	the <xref linkend="inst-network-dev">, thus this option can
 	safely be ignored.</para>
 
       <para>Selecting the <guimenuitem>AMD</guimenuitem> option adds
 	support for the <acronym>BSD</acronym> automatic mount utility.
 	This is usually used in conjunction with the
 	<acronym>NFS</acronym> protocol (see below)
 	for automatically mounting remote file systems.
 	No special configuration is required here.</para>
 
       <para>Next in line is the <guimenuitem>AMD Flags</guimenuitem>
 	option.  When selected, a menu will pop up for you
 	to enter specific <acronym>AMD</acronym> flags.
 	The menu already contains a set of default options:</para>
 
       <screen>-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map</screen>
 
       <para>The <option>-a</option> option sets the default mount
 	location which is specified here as
 	<filename>/.amd_mnt</filename>.  The <option>-l</option>
 	option specifies the default <filename>log</filename> file;
 	however, when <literal>syslogd</literal> is used all log
 	activity will be sent to the system log daemon.  The
 	<filename class="directory">/host</filename> directory is used
 	to mount an exported file system from a remote
 	host, while <filename class="directory">/net</filename>
 	directory is used to mount an exported file system from an
 	<acronym>IP</acronym> address.  The
 	<filename>/etc/amd.map</filename> file defines the default
 	options for <acronym>AMD</acronym> exports.</para>
 
+      <indexterm>
+	<primary>FTP</primary>
+	<secondary>anonymous</secondary>
+      </indexterm>
+
       <para>The <guimenuitem>Anon FTP</guimenuitem> option permits anonymous
 	<acronym>FTP</acronym> connections.  Select this option to
 	make this machine an anonymous <acronym>FTP</acronym> server.
 	Be aware of the security risks involved with this option.
 	Another menu will be displayed to explain the security risks
 	and configuration in depth.</para>
 
       <para>The <guimenuitem>Gateway</guimenuitem> configuration menu will set
 	the machine up to be a gateway as explained previously.  This
 	can be used to unset the <guimenuitem>Gateway</guimenuitem> option if you accidentally
 	selected it during the installation process.</para>
 
       <para>The <guimenuitem>Inetd</guimenuitem> option can be used to configure
 	or completely disable the &man.inetd.8; daemon as discussed
 	above.</para>
 
       <para>The <guimenuitem>Mail</guimenuitem> option is used to configure the system's
 	default <acronym>MTA</acronym> or Mail Transfer Agent.
 	Selecting this option will bring up the following menu:</para>
 
       <figure id="mta-selection">
 	<title>Select a default MTA</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mta-main" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Here you are offered a choice as to which
 	<acronym>MTA</acronym> to install
 	and set as the default.  An <acronym>MTA</acronym> is nothing
 	more than a mail server which delivers email to users on the
 	system or the Internet.</para>
 
       <para>Selecting <guimenuitem>Sendmail</guimenuitem> will install
 	the popular <application>sendmail</application> server which
 	is the &os; default.  The <guimenuitem>Sendmail local</guimenuitem> option
 	will set <application>sendmail</application> to be the default
 	<acronym>MTA</acronym>, but disable its ability to receive
 	incoming email from the Internet.  The other options here,
 	<guimenuitem>Postfix</guimenuitem> and
 	<guimenuitem>Exim</guimenuitem> act similar to
 	<guimenuitem>Sendmail</guimenuitem>.  They both deliver
 	email; however, some users prefer these alternatives to the
 	<application>sendmail</application>
 	<acronym>MTA</acronym>.</para>
 
       <para>After selecting an <acronym>MTA</acronym>, or choosing
 	not to select an MTA, the network configuration menu will appear
 	with the next option being <guimenuitem>NFS client</guimenuitem>.</para>
 
       <para>The <guimenuitem>NFS client</guimenuitem> option will
 	configure the system to communicate with a server via
 	<acronym>NFS</acronym>.  An <acronym>NFS</acronym> server
 	makes file systems available to other machines on the
 	network via the <acronym>NFS</acronym> protocol.  If this is
 	a stand alone machine, this option can remain unselected.
 	The system may require more configuration later; see
 	<xref linkend="network-nfs"> for more
 	information about client and server configuration.</para>
 
       <para>Below that option is the <guimenuitem>NFS server</guimenuitem>
 	option, permitting you to set the system up as an
 	<acronym>NFS</acronym> server.  This adds the required
 	information to start up the <acronym>RPC</acronym> remote
 	procedure call services.  <acronym>RPC</acronym> is used to
 	coordinate connections between hosts and programs.</para>
 
       <para>Next in line is the <guimenuitem>Ntpdate</guimenuitem> option,
 	which deals with time synchronization.  When selected, a menu
 	like the one below shows up:</para>
 
       <figure id="Ntpdate-config">
 	<title>Ntpdate Configuration</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/ntp-config" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>From this menu, select the server which is the closest
 	to your location.  Selecting a close one will make the time
 	synchronization more accurate as a server further from your
 	location may have more connection latency.</para>
 
       <para>The next option is the <acronym>PCNFSD</acronym> selection.
 	This option will install the
 	<filename role="package">net/pcnfsd</filename> package from
 	the ports collection.  This is a useful utility which provides
 	<acronym>NFS</acronym> authentication services for systems which
 	are unable to provide their own, such as Microsoft's
 	&ms-dos; operating system.</para>
 
       <para>Now you must scroll down a bit to see the other
 	options:</para>
 
       <figure id="Network-configuration-cont">
 	<title>Network Configuration Lower-level</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/net-config-menu2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The &man.rpcbind.8;, &man.rpc.statd.8;, and
 	&man.rpc.lockd.8; utilities are all used for Remote Procedure
 	Calls (<acronym>RPC</acronym>).
 	The <command>rpcbind</command> utility manages communication
 	between <acronym>NFS</acronym> servers and clients, and is
 	required for <acronym>NFS</acronym> servers to operate
 	correctly.  The <application>rpc.statd</application> daemon interacts
 	with the <application>rpc.statd</application> daemon on other hosts to
 	provide status monitoring.  The reported status is usually held
 	in the <filename>/var/db/statd.status</filename> file.  The
 	next option listed here is the <guimenuitem>rpc.lockd</guimenuitem>
 	option, which, when selected, will provide file locking
 	services.  This is usually used with
 	<application>rpc.statd</application> to monitor what hosts are
 	requesting locks and how frequently they request them.
 	While these last two options are marvelous for debugging, they
 	are not required for <acronym>NFS</acronym> servers and clients
 	to operate correctly.</para>
 
       <para>As you progress down the list the next item here is
 	<guimenuitem>Routed</guimenuitem>, which is the routing daemon.  The
 	&man.routed.8; utility manages network routing tables,
 	discovers multicast routers, and supplies a copy of the routing
 	tables to any physically connected host on the network upon
 	request.  This is mainly used for machines which act as a
 	gateway for the local network.  When selected, a menu will be
 	presented requesting the default location of the utility.
 	The default location is already defined for you and can be
 	selected with the <keycap>Enter</keycap> key.  You will then
 	be presented with yet another menu, this time asking for the
 	flags you wish to pass on to <application>routed</application>.  The
 	default is <option>-q</option> and it should already appear
 	on the screen.</para>
 
       <para>Next in line is the <guimenuitem>Rwhod</guimenuitem> option which,
 	when selected, will start the &man.rwhod.8; daemon
 	during system initialization.  The <command>rwhod</command>
 	utility broadcasts system messages across the network
 	periodically, or collects them when in <quote>consumer</quote>
 	mode.  More information can be found in the &man.ruptime.1; and
 	&man.rwho.1; manual pages.</para>
 
       <para>The next to the last option in the list is for the
 	&man.sshd.8; daemon.  This is the secure shell server for
 	<application>OpenSSH</application> and it is highly recommended
 	over the standard <application>telnet</application> and
 	<acronym>FTP</acronym> servers.  The <application>sshd</application>
 	server is used to create a secure connection from one host to
 	another by using encrypted connections.</para>
 
       <para>Finally there is the <guimenuitem>TCP Extensions</guimenuitem>
 	option.  This enables the <acronym>TCP</acronym> Extensions
 	defined in <acronym>RFC</acronym>&nbsp;1323 and
 	<acronym>RFC</acronym>&nbsp;1644.  While on many hosts this can
 	speed up connections, it can also cause some connections to be
 	dropped.  It is not recommended for servers, but may be
 	beneficial for stand alone machines.</para>
 
       <para>Now that you have configured the network services, you can
 	scroll up to the very top item which is <guimenuitem>Exit</guimenuitem>
 	and continue on to the next configuration section.</para>
 
     </sect2>
 
     <sect2 id="x-server">
       <title>Configure X Server</title>
 
       <note>
 	<para>As of &os;&nbsp;5.3-RELEASE, the X server configuration
 	  facility has been removed from
 	  <application>sysinstall</application>, you have to install
 	  and configure the X server after the installation of &os;.
 	  More information regarding the installation and the
 	  configuration of a X server can be found in <xref
 	  linkend="x11">.  You can skip this section if you are not
 	  installing a &os; version prior to 5.3-RELEASE.</para>
       </note>
 
       <para>In order to use a graphical user interface such as 
 	<application>KDE</application>, <application>GNOME</application>,
 	or others, the X server will need to be configured.</para>
 
       <note>
 	<para>In order to run <application>&xfree86;</application> as a
 	  non <username>root</username> user you will need to
 	  have <filename role="package">x11/wrapper</filename> installed.
 	  This is installed by default beginning with FreeBSD 4.7.  For
 	  earlier versions this can be added
 	  from the Package Selection menu.</para>
       </note>
 
       <para>To see whether your video card is supported, check the
 	<ulink url="http://www.xfree86.org/">&xfree86;</ulink> web site.</para>
 
       <screen>                      User Confirmation Requested 
         Would you like to configure your X server at this time?
 
                             [ Yes ]   No</screen>
 
       <warning>
 	<para>It is necessary to know your monitor specifications and
 	  video card information.  Equipment damage can occur if settings
 	  are incorrect.  If you do not have this information, select
 	  &gui.no; and perform the configuration
 	  after installation when you have the information using 
 	  <command>sysinstall</command> (<command>/stand/sysinstall</command>
 	  in &os; versions older than 5.2), selecting
 	  <guimenuitem>Configure</guimenuitem> and then 
 	  <guimenuitem>XFree86</guimenuitem>.  Improper configuration
 	  of the X server at this time can leave the machine in a
 	  frozen state.  It is often advised to configure the X server
 	  once the installation has completed.
 	</para>
       </warning>
 
       <para>If you have graphics card and monitor information, select
 	&gui.yes; and press <keycap>Enter</keycap>
 	to proceed with configuring the X server.</para>
 
       <figure id="xserver2">
 	<title>Select Configuration Method Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/xf86setup" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>There are several ways to configure the X server.
 	Use the arrow keys to select one of the methods  and press
 	<keycap>Enter</keycap>.  Be sure to read all instructions
 	carefully.</para>
 
       <para>The <application>xf86cfg</application> and 
 	<application>xf86cfg -textmode</application> methods may make the screen
 	go dark and take a few seconds to start.  Be patient.</para>
 
 
       <para>The following will illustrate the use of the
 	<application>xf86config</application> configuration tool.  The
 	configuration choices you make will depend on the hardware in the
 	system so your choices will probably be different than those
 	shown:</para>
 
       <screen>                                Message
  You have configured and been running the mouse daemon. 
  Choose "/dev/sysmouse" as the mouse port and "SysMouse" or
  "MouseSystems" as the mouse protocol in the X configuration utility. 
 
                                  [ OK ]
 
                       [ Press enter to continue ]</screen>
 
       <para>This indicates that the mouse daemon previously configured has been
 	detected.
 	Press <keycap>Enter</keycap> to continue.</para>
 
       <para>Starting <application>xf86config</application> will display
 	a brief introduction:</para>
 
       <screen>This program will create a basic XF86Config file, based on menu selections you
 make.
 
 The XF86Config file usually resides in /usr/X11R6/etc/X11 or /etc/X11. A sample
 XF86Config file is supplied with XFree86; it is configured for a standard
 VGA card and monitor with 640x480 resolution. This program will ask for a
 pathname when it is ready to write the file.
 
 You can either take the sample XF86Config as a base and edit it for your
 configuration, or let this program produce a base XF86Config file for your
 configuration and fine-tune it.
 
 Before continuing with this program, make sure you know what video card
 you have, and preferably also the chipset it uses and the amount of video
 memory on your video card. SuperProbe may be able to help with this.
 
 Press enter to continue, or ctrl-c to abort.</screen>
 
       <para>Pressing <keycap>Enter</keycap> will start the mouse
 	configuration.  Be sure to follow the instructions and use
 	<quote>Mouse Systems</quote> as the mouse protocol and
 	<filename>/dev/sysmouse</filename> as the mouse port even if
 	using a PS/2 mouse is shown as an illustration.</para>
 
       <screen>First specify a mouse protocol type. Choose one from the following list:
 
  1.  Microsoft compatible (2-button protocol)
  2.  Mouse Systems (3-button protocol) & FreeBSD moused protocol
  3.  Bus Mouse
  4.  PS/2 Mouse
  5.  Logitech Mouse (serial, old type, Logitech protocol)
  6.  Logitech MouseMan (Microsoft compatible)
  7.  MM Series
  8.  MM HitTablet
  9.  Microsoft IntelliMouse
 
 If you have a two-button mouse, it is most likely of type 1, and if you have
 a three-button mouse, it can probably support both protocol 1 and 2. There are
 two main varieties of the latter type: mice with a switch to select the
 protocol, and mice that default to 1 and require a button to be held at
 boot-time to select protocol 2. Some mice can be convinced to do 2 by sending
 a special sequence to the serial port (see the ClearDTR/ClearRTS options).
 
 Enter a protocol number: 2
 
 You have selected a Mouse Systems protocol mouse. If your mouse is normally
 in Microsoft-compatible mode, enabling the ClearDTR and ClearRTS options
 may cause it to switch to Mouse Systems mode when the server starts.
 
 Please answer the following question with either 'y' or 'n'.
 Do you want to enable ClearDTR and ClearRTS? n
 
 You have selected a three-button mouse protocol. It is recommended that you
 do not enable Emulate3Buttons, unless the third button doesn't work.
 
 Please answer the following question with either 'y' or 'n'.
 Do you want to enable Emulate3Buttons? y
 
 Now give the full device name that the mouse is connected to, for example
 /dev/tty00. Just pressing enter will use the default, /dev/mouse.
 On FreeBSD, the default is /dev/sysmouse.
 
 Mouse device: /dev/sysmouse</screen>
 
       <para>The keyboard is the next item to be configured. A generic
 	101-key model is shown for illustration.  Any name may be used
 	for the variant or simply press <keycap>Enter</keycap> to accept
 	the default value.</para>
 
       <screen>Please select one of the following keyboard types that is the better
 description of your keyboard. If nothing really matches,
 choose 1 (Generic 101-key PC)
 
   1  Generic 101-key PC                                
   2  Generic 102-key (Intl) PC                         
   3  Generic 104-key PC                                
   4  Generic 105-key (Intl) PC                         
   5  Dell 101-key PC                                   
   6  Everex STEPnote                                   
   7  Keytronic FlexPro                                 
   8  Microsoft Natural                                 
   9  Northgate OmniKey 101                             
  10  Winbook Model XP5                                 
  11  Japanese 106-key                                  
  12  PC-98xx Series                                    
  13  Brazilian ABNT2                                   
  14  HP Internet                                       
  15  Logitech iTouch                                   
  16  Logitech Cordless Desktop Pro                     
  17  Logitech Internet Keyboard                        
  18  Logitech Internet Navigator Keyboard              
  19  Compaq Internet                                   
  20  Microsoft Natural Pro                             
  21  Genius Comfy KB-16M                               
  22  IBM Rapid Access                                  
  23  IBM Rapid Access II                               
  24  Chicony Internet Keyboard                         
  25  Dell Internet Keyboard                            
 
 Enter a number to choose the keyboard.
 
 1
 
 
 Please select the layout corresponding to your keyboard
 
 
   1  U.S. English                                      
   2  U.S. English w/ ISO9995-3                         
   3  U.S. English w/ deadkeys                          
   4  Albanian                                          
   5  Arabic                                            
   6  Armenian                                          
   7  Azerbaidjani                                      
   8  Belarusian                                        
   9  Belgian                                           
  10  Bengali                                           
  11  Brazilian                                         
  12  Bulgarian                                         
  13  Burmese                                           
  14  Canadian                                          
  15  Croatian                                          
  16  Czech                                             
  17  Czech (qwerty)                                    
  18  Danish                                            
 
 Enter a number to choose the country.
 Press enter for the next page
 
 1
 
 
 Please enter a variant name for 'us' layout. Or just press enter
 for default variant
 
 us
 
 
 Please answer the following question with either 'y' or 'n'.
 Do you want to select additional XKB options (group switcher,
 group indicator, etc.)? n</screen>
 
       <para>Next, we proceed to the configuration for the monitor.  Do not
 	exceed the ratings of your monitor. Damage could occur.  If you
 	have any doubts, do the configuration after you have the
 	information.</para>
 
       <screen>Now we want to set the specifications of the monitor. The two critical
 parameters are the vertical refresh rate, which is the rate at which the
 whole screen is refreshed, and most importantly the horizontal sync rate,
 which is the rate at which scanlines are displayed.
 
 The valid range for horizontal sync and vertical sync should be documented
 in the manual of your monitor. If in doubt, check the monitor database
 /usr/X11R6/lib/X11/doc/Monitors to see if your monitor is there.
 
 Press enter to continue, or ctrl-c to abort.
 
 
 
 You must indicate the horizontal sync range of your monitor. You can either
 select one of the predefined ranges below that correspond to industry-
 standard monitor types, or give a specific range.
 
 It is VERY IMPORTANT that you do not specify a monitor type with a horizontal
 sync range that is beyond the capabilities of your monitor. If in doubt,
 choose a conservative setting.
 
     hsync in kHz; monitor type with characteristic modes
  1  31.5; Standard VGA, 640x480 @ 60 Hz
  2  31.5 - 35.1; Super VGA, 800x600 @ 56 Hz
  3  31.5, 35.5; 8514 Compatible, 1024x768 @ 87 Hz interlaced (no 800x600)
  4  31.5, 35.15, 35.5; Super VGA, 1024x768 @ 87 Hz interlaced, 800x600 @ 56 Hz
  5  31.5 - 37.9; Extended Super VGA, 800x600 @ 60 Hz, 640x480 @ 72 Hz
  6  31.5 - 48.5; Non-Interlaced SVGA, 1024x768 @ 60 Hz, 800x600 @ 72 Hz
  7  31.5 - 57.0; High Frequency SVGA, 1024x768 @ 70 Hz
  8  31.5 - 64.3; Monitor that can do 1280x1024 @ 60 Hz
  9  31.5 - 79.0; Monitor that can do 1280x1024 @ 74 Hz
 10  31.5 - 82.0; Monitor that can do 1280x1024 @ 76 Hz
 11  Enter your own horizontal sync range
 
 Enter your choice (1-11): 6
 
 You must indicate the vertical sync range of your monitor. You can either
 select one of the predefined ranges below that correspond to industry-
 standard monitor types, or give a specific range. For interlaced modes,
 the number that counts is the high one (e.g. 87 Hz rather than 43 Hz).
 
  1  50-70
  2  50-90
  3  50-100
  4  40-150
  5  Enter your own vertical sync range
 
 Enter your choice: 2
 
 You must now enter a few identification/description strings, namely an
 identifier, a vendor name, and a model name. Just pressing enter will fill
 in default names.
 
 The strings are free-form, spaces are allowed.
 Enter an identifier for your monitor definition: Hitachi</screen>
 
       <para>The selection of a video card driver from a list is
 	next.  If you pass your card on the list, continue to press
 	<keycap>Enter</keycap> and the list will repeat.  Only an
 	excerpt from the list is shown:</para>
 
       <screen>Now we must configure video card specific settings. At this point you can
 choose to make a selection out of a database of video card definitions.
 Because there can be variation in Ramdacs and clock generators even
 between cards of the same model, it is not sensible to blindly copy
 the settings (e.g. a Device section). For this reason, after you make a
 selection, you will still be asked about the components of the card, with
 the settings from the chosen database entry presented as a strong hint.
 
 The database entries include information about the chipset, what driver to
 run, the Ramdac and ClockChip, and comments that will be included in the
 Device section. However, a lot of definitions only hint about what driver
 to run (based on the chipset the card uses) and are untested.
 
 If you can't find your card in the database, there's nothing to worry about.
 You should only choose a database entry that is exactly the same model as
 your card; choosing one that looks similar is just a bad idea (e.g. a
 GemStone Snail 64 may be as different from a GemStone Snail 64+ in terms of
 hardware as can be).
 
 Do you want to look at the card database? y
 
 
 
 288  Matrox Millennium G200 8MB                        mgag200
 289  Matrox Millennium G200 SD 16MB                    mgag200
 290  Matrox Millennium G200 SD 4MB                     mgag200
 291  Matrox Millennium G200 SD 8MB                     mgag200
 292  Matrox Millennium G400                            mgag400
 293  Matrox Millennium II 16MB                         mga2164w
 294  Matrox Millennium II 4MB                          mga2164w
 295  Matrox Millennium II 8MB                          mga2164w
 296  Matrox Mystique                                   mga1064sg
 297  Matrox Mystique G200 16MB                         mgag200
 298  Matrox Mystique G200 4MB                          mgag200
 299  Matrox Mystique G200 8MB                          mgag200
 300  Matrox Productiva G100 4MB                        mgag100
 301  Matrox Productiva G100 8MB                        mgag100
 302  MediaGX                                           mediagx
 303  MediaVision Proaxcel 128                          ET6000
 304  Mirage Z-128                                      ET6000
 305  Miro CRYSTAL VRX                                  Verite 1000
 
 Enter a number to choose the corresponding card definition.
 Press enter for the next page, q to continue configuration.
 
 288
 
 Your selected card definition:
 
 Identifier: Matrox Millennium G200 8MB
 Chipset:    mgag200
 Driver:     mga
 Do NOT probe clocks or use any Clocks line.
 
 Press enter to continue, or ctrl-c to abort.
 
 
 
 Now you must give information about your video card. This will be used for
 the "Device" section of your video card in XF86Config.
 
 You must indicate how much video memory you have. It is probably a good
 idea to use the same approximate amount as that detected by the server you
 intend to use. If you encounter problems that are due to the used server
 not supporting the amount memory you have (e.g. ATI Mach64 is limited to
 1024K with the SVGA server), specify the maximum amount supported by the
 server.
 
 How much video memory do you have on your video card:
 
  1  256K
  2  512K
  3  1024K
  4  2048K
  5  4096K
  6  Other
 
 Enter your choice: 6
 
 Amount of video memory in Kbytes: 8192
 
 You must now enter a few identification/description strings, namely an
 identifier, a vendor name, and a model name. Just pressing enter will fill
 in default names (possibly from a card definition).
 
 Your card definition is Matrox Millennium G200 8MB.
 
 The strings are free-form, spaces are allowed.
 Enter an identifier for your video card definition:</screen>
 
       <para>Next, the video modes are set for the resolutions
 	desired.  Typically, useful ranges are 640x480, 800x600, and 1024x768
 	but those are a function of video card capability, monitor size,
 	and eye comfort.  When selecting a color depth, select the highest
 	mode that your card will support.</para>
 
       <screen>For each depth, a list of modes (resolutions) is defined. The default
 resolution that the server will start-up with will be the first listed
 mode that can be supported by the monitor and card.
 Currently it is set to:
 
 "640x480" "800x600" "1024x768" "1280x1024" for 8-bit
 "640x480" "800x600" "1024x768" "1280x1024" for 16-bit
 "640x480" "800x600" "1024x768" "1280x1024" for 24-bit
 
 Modes that cannot be supported due to monitor or clock constraints will
 be automatically skipped by the server.
 
  1  Change the modes for 8-bit (256 colors)
  2  Change the modes for 16-bit (32K/64K colors)
  3  Change the modes for 24-bit (24-bit color)
  4  The modes are OK, continue.
 
 Enter your choice: 2
 
 Select modes from the following list:
 
  1  "640x400"
  2  "640x480"
  3  "800x600"
  4  "1024x768"
  5  "1280x1024"
  6  "320x200"
  7  "320x240"
  8  "400x300"
  9  "1152x864"
  a  "1600x1200"
  b  "1800x1400"
  c  "512x384"
 
 Please type the digits corresponding to the modes that you want to select.
 For example, 432 selects "1024x768" "800x600" "640x480", with a
 default mode of 1024x768.
 
 Which modes? 432
 
 You can have a virtual screen (desktop), which is screen area that is larger
 than the physical screen and which is panned by moving the mouse to the edge
 of the screen. If you don't want virtual desktop at a certain resolution,
 you cannot have modes listed that are larger. Each color depth can have a
 differently-sized virtual screen
 
 Please answer the following question with either 'y' or 'n'.
 Do you want a virtual screen that is larger than the physical screen? n
 
 
 
 For each depth, a list of modes (resolutions) is defined. The default
 resolution that the server will start-up with will be the first listed
 mode that can be supported by the monitor and card.
 Currently it is set to:
 
 "640x480" "800x600" "1024x768" "1280x1024" for 8-bit
 "1024x768" "800x600" "640x480" for 16-bit
 "640x480" "800x600" "1024x768" "1280x1024" for 24-bit
 
 Modes that cannot be supported due to monitor or clock constraints will
 be automatically skipped by the server.
 
  1  Change the modes for 8-bit (256 colors)
  2  Change the modes for 16-bit (32K/64K colors)
  3  Change the modes for 24-bit (24-bit color)
  4  The modes are OK, continue.
 
 Enter your choice: 4
 
 
 
 Please specify which color depth you want to use by default:
 
   1  1 bit (monochrome)                                
   2  4 bits (16 colors)                                
   3  8 bits (256 colors)                               
   4  16 bits (65536 colors)                            
   5  24 bits (16 million colors)                       
 
 Enter a number to choose the default depth.
 
 4</screen>
 
       <para>Finally, the configuration needs to be saved.  Be sure
 	to enter <filename>/etc/XF86Config</filename> as the location
 	for saving the configuration.</para>
 
       <screen>I am going to write the XF86Config file now. Make sure you don't accidently
 overwrite a previously configured one.
 
 Shall I write it to /etc/X11/XF86Config? y</screen>
 
       <para>If the configuration fails, you can try the configuration again
 	by selecting &gui.yes; when the following
 	message appears:</para>
 
       <screen>          User Confirmation Requested
 The XFree86 configuration process seems to have
 failed.  Would you like to try again?
 
              [ Yes ]         No</screen>
 
       <para>If you have trouble configuring <application>&xfree86;</application>, select
 	&gui.no; and press <keycap>Enter</keycap>
 	and continue with the installation process.  After installation
 	you can use <command>xf86cfg -textmode</command> or
 	<command>xf86config</command> to access the command line
 	configuration utilities as <username>root</username>.  There is
 	an additional method for configuring <application>&xfree86;</application> described in
 	<xref linkend="x11">.   If you choose not to configure
 	<application>&xfree86;</application> at this time the next menu will be for package
 	selection.</para>
 
       <para>The default setting which allows the server to be killed
 	is the hotkey sequence <keycombo action='simul'>
 	<keycap>Ctrl</keycap><keycap>Alt</keycap>
 	<keycap>Backspace</keycap></keycombo>.  This
 	can be executed if something is wrong with the server settings and
 	prevent hardware damage.</para>
 
       <para>The default setting that allows video mode switching will
 	permit changing of the mode while running X with the hotkey
 	sequence
 	<keycombo action='simul'>
 	  <keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>+</keycap>
 	</keycombo> or
 	<keycombo action='simul'>
 	  <keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>-</keycap>
 	</keycombo>.   
       </para>
 
       <para>After you have <application>&xfree86;</application>
 	running, the display can be adjusted for height, width,
 	or centering by using <application>xvidtune</application>.</para>
 
       <para>There are warnings that improper settings can
 	damage your equipment.  Heed them.  If in doubt, do not do
 	it.  Instead, use the monitor controls to adjust the display for
 	X Window.  There may be some display differences when switching
 	back to text mode, but it is better than damaging equipment.</para>
 
       <para>Read the &man.xvidtune.1; manual page before making
 	any adjustments.</para>
 
       <para>Following a successful <application>&xfree86;</application> configuration, it will proceed
 	to the selection of a default desktop.</para>
     </sect2>
 
     <sect2 id="default-desktop">
       <title>Select Default X Desktop</title>
 
       <note>
 	<para>As of &os;&nbsp;5.3-RELEASE, the X desktop selection
 	  facility has been removed from
 	  <application>sysinstall</application>, you have to configure
 	  the X desktop after the installation of &os;.  More
 	  information regarding the installation and the configuration
 	  of a X desktop can be found in <xref linkend="x11">.  You
 	  can skip this section if you are not installing a &os;
 	  version prior to 5.3-RELEASE.</para>
       </note>
 
       <para>There are a variety of window managers available.  They range
 	from very basic environments to full desktop environments with a
 	large suite of software.  Some require only minimal disk space and
 	low memory while others with more features require much more.  The
 	best way to determine which is most suitable for you is to try a few
 	different ones.  Those are available from the ports collection or as
 	packages and can be added after installation.</para>
 
       <para>You can select one of the popular desktops to be installed
 	and configured as the default desktop.  This will allow you
 	to start it right after installation.</para>
 
       <figure id="x-desktop">
 	<title>Select Default Desktop</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/desktop" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the arrow keys to select a desktop and press
 	<keycap>Enter</keycap>.  Installation of the selected desktop will
 	proceed.</para>
     </sect2>
 
     <sect2 id="packages">
     <title>Install Packages</title>
 
       <para>Packages are pre-compiled binaries and are a convenient
 	way to install software.</para>
 
       <para>Installation of one package is shown for purposes of
 	illustration.  Additional packages can also be added at this
 	time if desired.  After installation
 	<command>sysinstall</command> (<command>/stand/sysinstall</command>
 	in &os; versions older than 5.2) can be used to add additional
 	packages.</para>
 
       <screen>                     User Confirmation Requested
  The FreeBSD package collection is a collection of hundreds of
  ready-to-run applications, from text editors to games to WEB servers
  and more. Would you like to browse the collection now? 
 
                             [ Yes ]   No</screen>
 
       <para>Selecting &gui.yes; and pressing
 	<keycap>Enter</keycap> will be
 	followed by the Package Selection screens:</para>
 
       <figure id="package-category">
 	<title>Select Package Category</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/pkg-cat" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Only packages on the current installation media are
 	available for installation at any given time.</para>
 
       <para>All packages available will be displayed if 
 	<guimenuitem>All</guimenuitem> is selected or you can select a
 	particular category.  Highlight your selection with the arrow
 	keys and press <keycap>Enter</keycap>.</para>
 
       <para>A menu will display showing all the packages available for
 	the selection made:</para>
 
       <figure id="package-select">
 	<title>Select Packages</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/pkg-sel" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The <application>bash</application> shell is shown selected.
 	Select as many as desired by highlighting the package and pressing the
 	<keycap>Space</keycap> key.  A short description of each package will
 	appear in the lower left corner of the screen.</para>
 
       <para>Pressing the <keycap>Tab</keycap> key will toggle between the last
 	selected package, &gui.ok;, and &gui.cancel;.</para>
 
       <para>When you have finished marking the packages for installation,
 	press <keycap>Tab</keycap> once to toggle to the &gui.ok; and press
 	<keycap>Enter</keycap> to return to the Package Selection menu.</para>
 
       <para>The left and right arrow keys will also toggle between &gui.ok;
 	and &gui.cancel;.  This method can also be used to select &gui.ok; and
 	press <keycap>Enter</keycap> to return to the Package Selection
 	menu.</para>
 
       <figure id="package-install">
 	<title>Install Packages</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/pkg-install" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the <keycap>Tab</keycap> and arrow keys to select <guibutton>[&nbsp;Install&nbsp;]</guibutton>
 	and press <keycap>Enter</keycap>.  You will then need to confirm
 	that you want to install the packages:</para>
 
       <figure id="package-install-confirm">
 	<title>Confirm Package Installation</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/pkg-confirm" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Selecting &gui.ok; and pressing <keycap>Enter</keycap> will start
 	the package installation.  Installing messages will appear until
 	completed.  Make note if there are any error messages.</para>
 
       <para>The final configuration continues after packages are
 	installed.  If you end up not selecting any packages, and wish
 	to return to the final configuration, select
 	<guibutton>Install</guibutton> anyways.</para>
     </sect2>
 
     <sect2 id="addusers">
       <title>Add Users/Groups</title>
 
       <para>You should add at least one user during the installation so
 	that you can use the system without being logged in as
 	<username>root</username>.  The root partition is generally small
 	and running applications as <username>root</username> can quickly
 	fill it.  A bigger danger is noted below:</para>
 
       <screen>                     User Confirmation Requested
  Would you like to add any initial user accounts to the system? Adding
  at least one account for yourself at this stage is suggested since
  working as the "root" user is dangerous (it is easy to do things which
  adversely affect the entire system). 
 
                             [ Yes ]   No</screen>
 
       <para>Select &gui.yes; and press
 	<keycap>Enter</keycap> to continue with adding a user.</para>
 
       <figure id="add-user2">
 	<title>Select User</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/adduser1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select <guimenuitem>User</guimenuitem> with the arrow keys
 	and press <keycap>Enter</keycap>.</para>
 
       <figure id="add-user3">
 	<title>Add User Information</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/adduser2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The following descriptions will appear in the lower part of
 	the screen as the items are selected with <keycap>Tab</keycap>
 	to assist with entering the required information:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term>Login ID</term>
 
 	  <listitem>
 	    <para>The login name of the new user (mandatory).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>UID</term>
 	
 	  <listitem>
 	    <para>The numerical ID for this user (leave blank for
 	      automatic choice).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Group</term>
 
 	  <listitem>
 	    <para>The login group name for this user (leave blank for
 	      automatic choice).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Password</term>
 
 	  <listitem>
 	    <para>The password for this user (enter this field with
 	      care!).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Full name</term>
 
 	  <listitem>
 	    <para>The user's full name (comment).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Member groups</term>
 
 	  <listitem>
 	    <para>The groups this user belongs to (i.e. gets access
 	      rights for).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Home directory</term>
 
 	  <listitem>
 	    <para>The user's home directory (leave blank for
 	      default).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Login shell</term>
 	  <listitem>
 	    <para>The user's login shell (leave blank for
 	      default, e.g. <filename>/bin/sh</filename>).</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
       <para>The login shell was changed from <filename>/bin/sh</filename> to
 	<filename>/usr/local/bin/bash</filename> to use the
 	<application>bash</application> shell that was previously installed as
 	a package.  Do not try to use a shell that does not exist or you will
 	not be able to login.  The most common shell used in the
 	BSD-world is the C shell, which can be indicated as
 	<filename>/bin/tcsh</filename>.</para>
 
       <para>The user was also added to the <groupname>wheel</groupname> group
 	to be able to become a superuser with <username>root</username>
 	privileges.</para>
 
       <para>When you are satisfied, press &gui.ok; and
 	the User and Group Management menu will redisplay:</para>
 
       <figure id="add-user4">
 	<title>Exit User and Group Management</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/adduser3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Groups can also be added at this time if specific needs
 	are known.  Otherwise, this may be accessed through using
 	<command>sysinstall</command> (<command>/stand/sysinstall</command>
 	in &os; versions older than 5.2) after installation is
 	completed.</para>
 
       <para>When you are finished adding users, select 
 	<guimenuitem>Exit</guimenuitem> with the arrow keys and press
 	<keycap>Enter</keycap> to continue the installation.</para>
     </sect2>
 
     <sect2 id="rootpass">
       <title>Set the <username>root</username> Password</title>
 
       <screen>                        Message
  Now you must set the system manager's password.  
  This is the password you'll use to log in as "root". 
 
                          [ OK ] 
 
                [ Press enter to continue ]</screen>
 
       <para>Press <keycap>Enter</keycap> to set the <username>root</username>
 	password.</para>
 
       <para>The password will need to be typed in twice correctly.  Needless to
 	say, make sure you have a way of finding the password if you
 	forget.  Notice that the password you type in is not echoed, nor
 	are asterisks displayed.</para>
 
       <screen>Changing local password for root. 
 New password : 
 Retype new password :</screen>
 
       <para>The installation will continue after the password is
 	successfully entered.</para>
     </sect2>
 
     <sect2 id="exit-inst">
       <title>Exiting Install</title>
 
       <para>If you need to configure additional network devices or
 	any other configuration, you can do it at this point or
 	after installation with <command>sysinstall</command>
 	(<command>/stand/sysinstall</command> in &os; versions older
 	than 5.2).</para>
 
       <screen>                     User Confirmation Requested
  Visit the general configuration menu for a chance to set any last
  options? 
 
                               Yes   [ No ]</screen>
 
       <para>Select &gui.no; with the arrow keys
 	and press <keycap>Enter</keycap> to return to the Main
 	Installation Menu.</para>
 
       <figure id="final-main">
 	<title>Exit Install</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mainexit" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select <guibutton>[X Exit Install]</guibutton> with the arrow
 	keys and press <keycap>Enter</keycap>.  You will be asked to
 	confirm exiting the installation:</para>
 
       <screen>                     User Confirmation Requested
  Are you sure you wish to exit? The system will reboot (be sure to  
  remove any floppies from the drives). 
 
                             [ Yes ]   No</screen>
 
       <para>Select &gui.yes; and remove the floppy if
 	booting from the floppy.  The CDROM drive is locked until the machine
 	starts to reboot.  The CDROM drive is then unlocked and the disk can
 	be removed from drive (quickly).</para>
 
       <para>The system will reboot so watch for any error messages that
 	may appear.</para>
     </sect2>
 
     <sect2 id="freebsdboot">
       <title>FreeBSD Bootup</title>
 
       <sect3 id="freebsdboot-i386">
         <title>FreeBSD Bootup on the &i386;</title>
 
       <para>If everything went well, you will see messages scroll
 	off the screen and you will arrive at a login prompt.  You can view
 	the content of the messages by pressing <keycap>Scroll-Lock</keycap>
 	and using <keycap>PgUp</keycap> and <keycap>PgDn</keycap>.
 	Pressing <keycap>Scroll-Lock</keycap> again will return
 	to the prompt.</para>
 
       <para>The entire message may not display (buffer limitation) but
 	it can be viewed from the command line after logging in by typing
 	<command>dmesg</command> at the prompt.</para>
 
       <para>Login using the username/password you set during installation
 	(<username>rpratt</username>, in this example).  Avoid logging in as
 	<username>root</username> except when necessary.</para>
 
       <para>Typical boot messages (version information omitted):</para>
 
 <screen>Copyright (c) 1992-2002 The FreeBSD Project. 
 Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
         The Regents of the University of California. All rights reserved. 
 
 Timecounter "i8254"  frequency 1193182 Hz
 CPU: AMD-K6(tm) 3D processor (300.68-MHz 586-class CPU)
   Origin = "AuthenticAMD"  Id = 0x580  Stepping = 0
   Features=0x8001bf&lt;FPU,VME,DE,PSE,TSC,MSR,MCE,CX8,MMX&gt; 
   AMD Features=0x80000800&lt;SYSCALL,3DNow!&gt; 
 real memory  = 268435456 (262144K bytes) 
 config&gt; di sn0 
 config&gt; di lnc0 
 config&gt; di le0 
 config&gt; di ie0 
 config&gt; di fe0 
 config&gt; di cs0 
 config&gt; di bt0  
 config&gt; di aic0 
 config&gt; di aha0 
 config&gt; di adv0 
 config&gt; q 
 avail memory = 256311296 (250304K bytes)
 Preloaded elf kernel "kernel" at 0xc0491000. 
 Preloaded userconfig_script "/boot/kernel.conf" at 0xc049109c. 
 md0: Malloc disk 
 Using $PIR table, 4 entries at 0xc00fde60
 npx0: &lt;math processor&gt; on motherboard 
 npx0: INT 16 interface 
 pcib0: &lt;Host to PCI bridge&gt; on motherboard 
 pci0: &lt;PCI bus&gt; on pcib0 
 pcib1: &lt;VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge&gt; at device 1.0 on pci0 
 pci1: &lt;PCI bus&gt; on pcib1 
 pci1: &lt;Matrox MGA G200 AGP graphics accelerator&gt; at 0.0 irq 11 
 isab0: &lt;VIA 82C586 PCI-ISA bridge&gt; at device 7.0 on pci0 
 isa0: &lt;ISA bus&gt; on isab0 
 atapci0: &lt;VIA 82C586 ATA33 controller&gt; port 0xe000-0xe00f at device 7.1 on pci0 
 ata0: at 0x1f0 irq 14 on atapci0 
 ata1: at 0x170 irq 15 on atapci0 
 uhci0: &lt;VIA 83C572 USB controller&gt; port 0xe400-0xe41f irq 10 at device 7.2 on pci0 
 usb0: &lt;VIA 83C572 USB controller&gt; on uhci0 
 usb0: USB revision 1.0 
 uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr 1 
 uhub0: 2 ports with 2 removable, self powered 
 chip1: &lt;VIA 82C586B ACPI interface&gt; at device 7.3 on pci0 
 ed0: &lt;NE2000 PCI Ethernet (RealTek 8029)&gt; port 0xe800-0xe81f irq 9 at
 device 10.0 on pci0 
 ed0: address 52:54:05:de:73:1b, type NE2000 (16 bit) 
 isa0: too many dependant configs (8) 
 isa0: unexpected small tag 14 
 fdc0: &lt;NEC 72065B or clone&gt; at port 0x3f0-0x3f5,0x3f7 irq 6 drq 2 on isa0
 fdc0: FIFO enabled, 8 bytes threshold 
 fd0: &lt;1440-KB 3.5" drive&gt; on fdc0 drive 0 
 atkbdc0: &lt;keyboard controller (i8042)&gt; at port 0x60-0x64 on isa0 
 atkbd0: &lt;AT Keyboard&gt; flags 0x1 irq 1 on atkbdc0 
 kbd0 at atkbd0 
 psm0: &lt;PS/2 Mouse&gt; irq 12 on atkbdc0 
 psm0: model Generic PS/2 mouse, device ID 0 
 vga0: &lt;Generic ISA VGA&gt; at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0
 sc0: &lt;System console&gt; at flags 0x1 on isa0 
 sc0: VGA &lt;16 virtual consoles, flags=0x300&gt; 
 sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0 
 sio0: type 16550A 
 sio1 at port 0x2f8-0x2ff irq 3 on isa0 
 sio1: type 16550A 
 ppc0: &lt;Parallel port&gt; at port 0x378-0x37f irq 7 on isa0 
 ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode 
 ppc0: FIFO with 16/16/15 bytes threshold 
 ppbus0: IEEE1284 device found /NIBBLE
 Probing for PnP devices on ppbus0: 
 plip0: &lt;PLIP network interface&gt; on ppbus0 
 lpt0: &lt;Printer&gt; on ppbus0 
 lpt0: Interrupt-driven port 
 ppi0: &lt;Parallel I/O&gt; on ppbus0
 ad0: 8063MB &lt;IBM-DHEA-38451&gt; [16383/16/63] at ata0-master using UDMA33 
 ad2: 8063MB &lt;IBM-DHEA-38451&gt; [16383/16/63] at ata1-master using UDMA33 
 acd0: CDROM &lt;DELTA OTC-H101/ST3 F/W by OIPD&gt; at ata0-slave using PIO4 
 Mounting root from ufs:/dev/ad0s1a 
 swapon: adding /dev/ad0s1b as swap device 
 Automatic boot in progress... 
 /dev/ad0s1a: FILESYSTEM CLEAN; SKIPPING CHECKS 
 /dev/ad0s1a: clean, 48752 free (552 frags, 6025 blocks, 0.9% fragmentation)
 /dev/ad0s1f: FILESYSTEM CLEAN; SKIPPING CHECKS 
 /dev/ad0s1f: clean, 128997 free (21 frags, 16122 blocks, 0.0% fragmentation)
 /dev/ad0s1g: FILESYSTEM CLEAN; SKIPPING CHECKS
 /dev/ad0s1g: clean, 3036299 free (43175 frags, 374073 blocks, 1.3% fragmentation)
 /dev/ad0s1e: filesystem CLEAN; SKIPPING CHECKS 
 /dev/ad0s1e: clean, 128193 free (17 frags, 16022 blocks, 0.0% fragmentation)
 Doing initial network setup: hostname. 
 ed0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
         inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
         inet6 fe80::5054::5ff::fede:731b%ed0 prefixlen 64 tentative scopeid 0x1
         ether 52:54:05:de:73:1b
 lo0: flags=8049&lt;UP,LOOPBACK,RUNNING,MULTICAST&gt; mtu 16384 
         inet6 fe80::1%lo0 prefixlen 64 scopeid 0x8 
         inet6 ::1 prefixlen 128 
         inet 127.0.0.1 netmask 0xff000000 
 Additional routing options: IP gateway=YES TCP keepalive=YES
 routing daemons:. 
 additional daemons: syslogd. 
 Doing additional network setup:. 
 Starting final network daemons: creating ssh RSA host key 
 Generating public/private rsa1 key pair.
 Your identification has been saved in /etc/ssh/ssh_host_key. 
 Your public key has been saved in /etc/ssh/ssh_host_key.pub. 
 The key fingerprint is: 
 cd:76:89:16:69:0e:d0:6e:f8:66:d0:07:26:3c:7e:2d root@k6-2.example.com
  creating ssh DSA host key 
 Generating public/private dsa key pair.
 Your identification has been saved in /etc/ssh/ssh_host_dsa_key. 
 Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub. 
 The key fingerprint is: 
 f9:a1:a9:47:c4:ad:f9:8d:52:b8:b8:ff:8c:ad:2d:e6 root@k6-2.example.com.
 setting ELF ldconfig path: /usr/lib /usr/lib/compat /usr/X11R6/lib
 /usr/local/lib 
 a.out ldconfig path: /usr/lib/aout /usr/lib/compat/aout /usr/X11R6/lib/aout 
 starting standard daemons: inetd cron sshd usbd sendmail.
 Initial rc.i386 initialization:. 
 rc.i386 configuring syscons: blank_time screensaver moused. 
 Additional ABI support: linux. 
 Local package initialization:. 
 Additional TCP options:. 
 
 FreeBSD/i386 (k6-2.example.com) (ttyv0)
 
 login: rpratt 
 Password:</screen>
 
       <para>Generating the RSA and DSA keys may take some time on slower
 	machines.  This happens only on the initial boot-up of a new
 	installation.  Subsequent boots will be faster.</para>
 
       <para>If the X server has been configured and a Default Desktop
 	chosen, it can be started by typing <command>startx</command> at
 	the command line.</para>
 
       </sect3>
 
       <sect3>
         <title>Bootup of FreeBSD on the Alpha</title>
 
 	<indexterm><primary>Alpha</primary></indexterm>
 
         <para>Once the install procedure has finished, you will be
           able to start FreeBSD by typing something like this to the
           SRM prompt:</para>
 
 	<screen>&gt;&gt;&gt;<userinput>BOOT DKC0</userinput></screen>
 
 	<para>This instructs the firmware to boot the specified
 	  disk.  To make FreeBSD boot automatically in the future, use
 	  these commands:</para>
 
 	<screen><prompt>&gt;&gt;&gt;</prompt> <userinput>SET BOOT_OSFLAGS A</userinput>
 <prompt>&gt;&gt;&gt;</prompt> <userinput>SET BOOT_FILE ''</userinput>
 <prompt>&gt;&gt;&gt;</prompt> <userinput>SET BOOTDEF_DEV DKC0</userinput>
 <prompt>&gt;&gt;&gt;</prompt> <userinput>SET AUTO_ACTION BOOT</userinput></screen>
 
 	<para>The boot messages will be similar (but not identical) to
 	those produced by FreeBSD booting on the &i386;.</para>
       </sect3>
     </sect2>
 
     <sect2 id="shutdown">
       <title>FreeBSD Shutdown</title>
 
       <para>It is important to properly shutdown the operating
 	system.  Do not just turn off power.  First, become a superuser by
 	typing <command>su</command> at the command line and entering the
 	<username>root</username> password.  This will work only if the user
 	is a member of the <groupname>wheel</groupname> group.
 	Otherwise, login as <username>root</username> and use
 	<command>shutdown -h now</command>.</para>
 
       <screen>The operating system has halted. 
 Please press any key to reboot.</screen>
 
       <para>It is safe to turn off the power after the shutdown command
 	has been issued and the message <quote>Please press any key to reboot</quote>
 	appears.  If any key is pressed instead of turning off the power
 	switch, the system will reboot.</para>
 
       <para>You could also use the
         <keycombo action="simul">
 	  <keycap>Ctrl</keycap>
 	  <keycap>Alt</keycap>
 	  <keycap>Del</keycap>
 	</keycombo>
 	key combination to reboot the system, however this is not recommended
 	during normal operation.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="install-supported-hardware">
     <title>Supported Hardware</title>
 
     <indexterm><primary>hardware</primary></indexterm>
     <para>FreeBSD currently runs on a wide variety of ISA, VLB, EISA, and PCI
       bus-based PCs with Intel, AMD, Cyrix, or NexGen <quote>x86</quote>
       processors, as well as a number of machines based on the Compaq Alpha
       processor.  Support for generic IDE or ESDI drive configurations,
       various SCSI controllers, PCMCIA cards, USB devices, and network and
       serial cards is also provided.  FreeBSD also supports IBM's microchannel
       (MCA) bus.</para>
 
     <para>A list of supported hardware is provided with each FreeBSD release
       in the FreeBSD Hardware Notes.  This document can usually be found in a
       file named <filename>HARDWARE.TXT</filename>, in the top-level directory
       of a CDROM or FTP distribution or in
       <application>sysinstall</application>'s documentation menu.  It lists,
       for a given architecture, what hardware devices are known to be
       supported by each release of FreeBSD.  Copies of the supported
       hardware list for various releases and architectures can also be
       found on the <ulink
       url="http://www.FreeBSD.org/releases/index.html">Release
       Information</ulink> page of the FreeBSD Web site.</para>
   </sect1>
 
   <sect1 id="install-trouble">
     <title>Troubleshooting</title>
 
     <indexterm>
       <primary>installation</primary>
       <secondary>troubleshooting</secondary>
     </indexterm>
     <para>The following section covers basic installation troubleshooting,
       such as common problems people have reported.  There are also a few
       questions and answers for people wishing to dual-boot FreeBSD with
       &ms-dos;.</para>
 
     <sect2>
       <title>What to Do If Something Goes Wrong</title>
 
       <para>Due to various limitations of the PC architecture, it is
         impossible for probing to be 100% reliable, however, there are a
         few things you can do if it fails.</para>
 
       <para>Check the Hardware Notes document for your version of
         FreeBSD to make sure your hardware is
         supported.</para>
 
       <para>If your hardware is supported and you still experience
         lock-ups or other problems, reset your computer, and when the
         visual kernel configuration option is given, choose it.  This will
         allow you to go through your hardware and supply information to the
         system about it.  The kernel on the boot disks is configured
         assuming that most hardware devices are in their factory default
         configuration in terms of IRQs, IO addresses, and DMA channels.  If
         your hardware has been reconfigured, you will most likely need to
         use the configuration editor to tell FreeBSD where to find
         things.</para>
 
       <para>It is also possible that a probe for a device not present will
         cause a later probe for another device that is present to fail.  In
         that case, the probes for the conflicting driver(s) should be
         disabled.</para>
 
       <note>
         <para>Some installation problems can be avoided or alleviated
           by updating the firmware on various hardware components, most notably
           the motherboard.  The motherboard firmware may also be referred to
           as <acronym>BIOS</acronym> and most of the motherboard or computer
           manufactures have a website where the upgrades and upgrade information
           may be located.</para>
 
         <para>Most manufacturers strongly advise against upgrading the motherboard
           <acronym>BIOS</acronym> unless there is a good reason for doing so, which
           could possibly be a critical update of sorts.  The upgrade process
           <emphasis>can</emphasis> go wrong, causing permanent damage to the
           <acronym>BIOS</acronym> chip.</para>
         </note>
 
       <warning>
         <para>Do not disable any drivers you will need during the
           installation, such as your screen (<devicename>sc0</devicename>).
 	  If the installation wedges or fails mysteriously after leaving
 	  the configuration editor, you have probably removed or changed
 	  something you should not have.  Reboot and try again.</para>
       </warning>
 
       <para>In configuration mode, you can:</para>
 
       <itemizedlist>
         <listitem>
           <para>List the device drivers installed in the kernel.</para>
         </listitem>
 
         <listitem>
           <para>Disable device drivers for hardware that is not present in
 	    your system.</para>
         </listitem>
 
         <listitem>
           <para>Change IRQs, DRQs, and IO port addresses used by a device
 	    driver.</para>
         </listitem>
       </itemizedlist>
 
       <para>After adjusting the kernel to match your hardware
         configuration, type <command>Q</command> to boot with the new
         settings.  Once the installation has completed, any changes you
         made in the configuration mode will be permanent so you do not have
         to reconfigure every time you boot.  It is still highly likely that
         you will eventually want to build a <link
         linkend="kernelconfig">custom kernel</link>.</para>
     </sect2>
     
     <sect2>
       <title>Dealing with Existing &ms-dos; Partitions</title>
 
       <indexterm><primary>DOS</primary></indexterm>
       <para>Many users wish to install &os; on <acronym>PC</acronym>s inhabited by
 	&microsoft; based operating systems.  For those instances, &os; has a
 	utility known as <application>FIPS</application>.  This utility can be found
 	in the <filename>tools</filename> directory on the install CD-ROM, or downloaded
 	from one of various <link linkend="mirrors">&os; mirrors</link>.</para>
 
       <para>The <application>FIPS</application> utility allows you to split an
 	existing &ms-dos; partition into two pieces, preserving the original
 	partition and allowing you to install onto the second free piece.
 	You first need to defragment your &ms-dos; partition using the &windows;;
 	<application>Disk Defragmenter</application> utility (go into Explorer, right-click on
 	the hard drive, and choose to defrag your hard drive), or use
 	<application>Norton Disk Tools</application>.  Now you can run the
 	<application>FIPS</application> utility.  It will prompt you for the rest of
 	the information, just follow the on screen instructions.  Afterwards, you can
 	reboot and install &os; on the new free slice.  See the <guimenuitem>Distributions</guimenuitem> menu
 	for an estimate of how much free space you will need for the kind of
 	installation you want.</para>
 
       <para>There is also a very useful product from PowerQuest
 	(<ulink url="http://www.powerquest.com/">http://www.powerquest.com</ulink>) called
 	<application>&partitionmagic;</application>.  This application has far more
 	functionality than <application>FIPS</application>, and is highly recommended
 	if you plan to add/remove operating systems often.  It does cost money, so if you
 	plan to install &os; and keep it installed, <application>FIPS</application>
 	will probably be fine for you.</para>
     </sect2>
 
     <sect2>
       <title>Using &ms-dos; and &windows; File Systems</title>
 
       <para>At this time, &os; does not support file systems compressed with the
 	<application>Double Space&trade;</application> application.  Therefore the file
 	system will need to be uncompressed before &os; can access the data.  This
 	can be done by running the <application>Compression Agent</application>
 	located in the <guimenuitem>Start</guimenuitem>&gt; <guimenuitem>Programs</guimenuitem> &gt;
 	<guimenuitem>System Tools</guimenuitem> menu.</para>
 
       <para>&os; can support &ms-dos; based file systems.  This requires you use
 	the &man.mount.msdos.8; command (in &os; 5.X, the command is &man.mount.msdosfs.8;)
 	with the required parameters.  The utilities most common usage is:</para>
 
       <screen>&prompt.root; <userinput>mount_msdos /dev/ad0s1 /mnt</userinput></screen>
 
       <para>In this example, the &ms-dos; file system is located on the first partition of
 	the primary hard disk.  Your situation may be different, check the output from
 	the <command>dmesg</command>, and <command>mount</command> commands.  They should
 	produce enough information to give an idea of the partition layout.</para>
 
       <note><para>Extended &ms-dos; file systems are usually mapped after the &os;
 	partitions.  In other words, the slice number may be higher than the ones
 	&os; is using.  For instance, the first &ms-dos; partition may be
 	<filename>/dev/ad0s1</filename>, the &os; partition may be
 	<filename>/dev/ad0s2</filename>, with the extended &ms-dos; partition being
 	located on <filename>/dev/ad0s3</filename>.  To some, this can be confusing
 	at first.</para></note>
 
       <para>NTFS partitions can also be mounted in a similar manner
 	using the &man.mount.ntfs.8; command.</para>
     </sect2>
 
     <sect2>
       <title>Alpha User's Questions and Answers</title>
 
       <indexterm><primary>Alpha</primary></indexterm>
 
       <para>This section answers some commonly asked questions about
         installing FreeBSD on Alpha systems.</para>
 
       <qandaset>
 	<qandaentry>
 	  <question>
 	    <para>Can I boot from the ARC or Alpha BIOS Console?</para>
 	  </question>
 
 	  <indexterm><primary>ARC</primary></indexterm>
 	  <indexterm><primary>Alpha BIOS</primary></indexterm>
 	  <indexterm><primary>SRM</primary></indexterm>
 
 	  <answer>
 	    <para>No.  &os;, like Compaq Tru64 and VMS, will only boot
 	    from the SRM console.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Help, I have no space!  Do I need to delete
 	    everything first?</para>
 	  </question>
 
 	  <answer>
 	    <para>Unfortunately, yes.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Can I mount my Compaq Tru64 or VMS filesystems?</para>
 	  </question>
 
 	  <answer>
 	    <para>No, not at this time.</para>
 	  </answer>
 	</qandaentry>
       </qandaset>
     </sect2>
   </sect1>
 
   <sect1 id="install-advanced">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Valentino</firstname>
 	  <surname>Vaschetto</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<!-- May 2001 -->
       </authorgroup>
     </sect1info>
 
     <title>Advanced Installation Guide</title>
 
     <para>This section describes how to install FreeBSD in exceptional
        cases.</para>
 
     <sect2 id="headless-install">
       <title>Installing FreeBSD on a System without a Monitor or
         Keyboard</title>
 
       <indexterm>
         <primary>installation</primary>
         <secondary>headless (serial console)</secondary>
       </indexterm>
       <indexterm><primary>serial console</primary></indexterm>
       <para>This type of installation is called a <quote>headless
 	install</quote>, because the machine that you are trying to install
 	FreeBSD on either does not have a monitor attached to it, or does not
 	even have a VGA output.  How is this possible you ask? Using a
         serial console.  A serial console is basically using another
         machine to act as the main display and keyboard for a
         system.  To do this, just follow the steps to create
         installation floppies, explained in <xref
         linkend="install-floppies">.</para>
 
       <para>To modify these floppies to boot into a serial console, follow
 	these steps:</para>
 
       <procedure>
 	<step>
 	  <title>Enabling the Boot Floppies to Boot into a Serial Console</title>
   	    <indexterm>
 	      <primary><command>mount</command></primary>
 	    </indexterm>
 	    <para>If you were to boot into the floppies that you just
 	      made, FreeBSD would boot into its normal install mode.  We
 	      want FreeBSD to boot into a serial console for our
 	      install.  To do this, you have to mount the
 	      <filename>kern.flp</filename> floppy onto your FreeBSD
 	      system using the &man.mount.8; command.</para>
 
             <screen>&prompt.root; <userinput>mount /dev/fd0 /mnt</userinput></screen>
 
 	    <para>Now that you have the floppy mounted, you must
 	      change into the <filename class="directory">/mnt</filename> directory:</para>
 
 	    <screen>&prompt.root; <userinput>cd /mnt</userinput></screen>
 
 	    <para>Here is where you must set the floppy to boot into a
 	      serial console.  You have to make a file called
 	      <filename>boot.config</filename> containing 
 	      <literal>/boot/loader -h</literal>.  All this does is pass a flag to the bootloader to
 	      boot into a serial console.</para>
 
 	    <screen>&prompt.root; <userinput>echo "/boot/loader -h" > boot.config</userinput></screen>
 
 	    <para>Now that you have your floppy configured correctly,
 	      you must unmount the floppy using the &man.umount.8;
 	      command:</para>
 
             <screen>&prompt.root; <userinput>cd /</userinput>
 &prompt.root; <userinput>umount /mnt</userinput></screen>
 
 	    <para>Now you can remove the floppy from the floppy
 	      drive.</para>
 	  </step>
 
 	  <step>
 	    <title>Connecting Your Null Modem Cable</title>
 
   	    <indexterm><primary>null-modem cable</primary></indexterm>
 	    <para>You now need to connect a
 	      <link linkend="term-cables-null">null-modem cable</link> between
 	      the two machines.  Just connect the cable to the serial
 	      ports of the 2 machines.  <emphasis>A normal serial cable
 	      will not work here</emphasis>, you need a null-modem
 	      cable because it has some of the wires inside crossed
 	      over.</para>
 	  </step>
 
 	  <step>
 	    <title>Booting Up for the Install</title>
 
 	    <para>It is now time to go ahead and start the install.  Put
 	      the <filename>kern.flp</filename> floppy in the floppy
 	      drive of the machine you are doing the headless install
 	      on, and power on the machine.</para>
 	  </step>
 
 	  <step>
 	    <title>Connecting to Your Headless Machine</title>
 	    <indexterm>
 	      <primary><command>cu</command></primary>
 	    </indexterm>
 	    <para>Now you have to connect to that machine with
 	      &man.cu.1;:</para> 
 
 	    <screen>&prompt.root; <userinput>cu -l /dev/cuaa0</userinput></screen>
 	  </step>
       </procedure>
 
       <para>That's it! You should now be able to control the headless machine
 	through your <command>cu</command> session.  It will ask you to
 	put in the <filename>mfsroot.flp</filename>, and then it will come up
 	with a selection of what kind of terminal to use.  Select the
 	FreeBSD color console and proceed with your install!</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="install-diff-media">
     <title>Preparing Your Own Installation Media</title>
 
     <note>
       <para>To prevent repetition, <quote>FreeBSD disk</quote> in this context
 	means a FreeBSD CDROM or DVD that you have purchased or produced
 	yourself.</para>
     </note>
 
     <para>There may be some situations in which you need to create your own
       FreeBSD installation media and/or source.  This might be physical media,
       such as a tape, or a source that <application>sysinstall</application>
       can use to retrieve the files, such as a local FTP site, or an &ms-dos;
       partition.</para>
 
     <para>For example:</para>
 
     <itemizedlist>
       <listitem>
 	<para>You have many machines connected to your local network, and one
 	  FreeBSD disk.  You want to create a local FTP site using the
 	  contents of the FreeBSD disk, and then have your machines use this
 	  local FTP site instead of needing to connect to the Internet.</para>
       </listitem>
 
       <listitem>
 	<para>You have a FreeBSD disk, and FreeBSD does not recognize your CD/DVD
 	  drive, but &ms-dos;/&windows; does.  You want to copy the FreeBSD
 	  installations files to a DOS partition on the same computer, and
 	  then install FreeBSD using those files.</para>
       </listitem>
 
       <listitem>
 	<para>The computer you want to install on does not have a CD/DVD
 	  drive or a network card, but you can connect a
 	  <quote>Laplink-style</quote> serial or parallel cable to a computer
 	  that does.</para>
       </listitem>
 
       <listitem>
 	<para>You want to create a tape that can be used to install
 	  FreeBSD.</para>
       </listitem>
     </itemizedlist>
 
     <sect2 id="install-cdrom">
       <title>Creating an Installation CDROM</title>
 
       <para>As part of each release, the FreeBSD project makes available two
 	CDROM images (<quote>ISO images</quote>).  These images can be written
 	(<quote>burned</quote>) to CDs if you have a CD writer, and then used
 	to install FreeBSD.  If you have a CD writer, and bandwidth is cheap,
 	then this is the easiest way to install FreeBSD.</para>
 
       <procedure>
 	<step>
 	  <title>Download the Correct ISO Images</title>
 
 	  <para>The ISO images for each release can be downloaded from <filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/ISO-IMAGES-<replaceable>arch</replaceable>/<replaceable>version</replaceable></filename> or the closest mirror.  
 	    Substitute <replaceable>arch</replaceable> and 
 	    <replaceable>version</replaceable> as appropriate.</para>
 
 	  <para>That directory will normally contain the following images:</para>
 
 	  <table frame="none">
 	    <title>FreeBSD ISO Image Names and Meanings</title>
 
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>Filename</entry>
 
 		  <entry>Contains</entry>
 		</row>
 	      </thead>
 
 	      <tbody>
 		<row>
 		  <entry><filename><replaceable>version</replaceable>-mini.iso</filename></entry>
 		  
 		  <entry>Everything you need to install FreeBSD.</entry>
 		</row>
 
 		<row>
 		  <entry><filename><replaceable>version</replaceable>-disc1.iso</filename></entry>
 
 		  <entry>Everything you need to install FreeBSD, and as many
 		    additional third party packages as would fit on the
 		    disc.</entry>
 		</row>
 
 		<row>
 		  <entry><filename><replaceable>version</replaceable>-disc2.iso</filename></entry>
 
 		  <entry>A <quote>live filesystem</quote>, which is used in
 		    conjunction with the <quote>Repair</quote> facility in
 		    <application>sysinstall</application>.  A copy of the
 		    FreeBSD CVS tree.  As many additional third party packages
 		    as would fit on the disc.</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </table>
 
 <!-- XXX we don't need to mention things prior to 4.4 anymore
 	  <note>
 	    <para>The mini ISO was only produced for FreeBSD&nbsp;4.4 and
 	      subsequent releases.  The images for discs two, three, and four
 	      were only produced for FreeBSD&nbsp;4.5 and subsequent
 	      releases.</para>
 	  </note>
 -->
 
 	  <para>You <emphasis>must</emphasis> download one of either the mini
 	    ISO image, or the image of disc one.  Do not download both of them,
 	    since the disc one image contains everything that the mini ISO
 	    image contains.</para>
 
 	  <para>Use the mini ISO if Internet access is cheap for you.  It will
 	    let you install FreeBSD, and you can then install third party
 	    packages by downloading them using the ports/packages system (see
 	    <xref linkend="ports">) as
 	    necessary.</para>
 
 	  <para>Use the image of disc one if you want a reasonable selection
 	    of third party packages on the disc as well.</para>
 
 	  <para>The additional disc images are useful, but not essential,
 	    especially if you have high-speed access to the Internet.</para>
 	</step>
 
 	<step>
 	  <title>Write the CDs</title>
 
 	  <para>You must then write the CD images to disc.  If you will be
 	    doing this on another FreeBSD system then see 
 	    <xref linkend="creating-cds"> for more information (in 
 	    particular, <xref linkend="burncd"> and 
 	    <xref linkend="cdrecord">).</para>
 
 	  <para>If you will be doing this on another platform then you will
 	    need to use whatever utilities exist to control your CD writer on
 	    that platform.  The images provided are in the standard ISO format,
 	    which many CD writing applications support.</para>
 	</step>
       </procedure>
     </sect2>
 
     <sect2 id="install-ftp">
       <title>Creating a Local FTP Site with a FreeBSD Disk</title>
 	
       <indexterm>
 	<primary>installation</primary>
 	<secondary>network</secondary>
 	<tertiary>FTP</tertiary>
       </indexterm>
 
       <para>FreeBSD disks are laid out in the same way as the FTP site.  This
 	makes it very easy for you to create a local FTP site that can be used
 	by other machines on your network when installing FreeBSD.</para>
 
       <procedure>
 	<step>
 	  <para>On the FreeBSD computer that will host the FTP site, ensure
 	    that the CDROM is in the drive, and mounted on
 	    <filename>/cdrom</filename>.</para>
 
 	  <screen>&prompt.root; <userinput>mount /cdrom</userinput></screen>
 	</step>
 
 	<step>
 	  <para>Create an account for anonymous FTP in
 	    <filename>/etc/passwd</filename>.  Do this by editing
 	    <filename>/etc/passwd</filename> using &man.vipw.8; and adding
 	    this line:</para>
 
 	  <programlisting>ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
 	</step>
 
 	<step>
 	  <para>Ensure that the FTP service is enabled in
 	    <filename>/etc/inetd.conf</filename>.</para>
 	</step>
       </procedure>
 
       <para>Anyone with network connectivity to your machine can now
 	chose a media type of FTP and type in
 	<userinput>ftp://<replaceable>your machine</replaceable></userinput>
 	after picking <quote>Other</quote> in the FTP sites menu during
 	the install.</para>
 
       <warning>
 	<para>This approach is OK for a machine that is on your local network,
 	  and that is protected by your firewall.  Offering up FTP services to
 	  other machines over the Internet (and not your local network)
 	  exposes your computer to the attention of crackers and other
 	  undesirables.  We strongly recommend that you follow good security
 	  practices if you do this.</para>
       </warning>
     </sect2>
 
       <sect2>
         <title>Creating Installation Floppies</title>
 
       <indexterm>
 	<primary>installation</primary>
 	<secondary>floppies</secondary>
       </indexterm>
 
       <para>If you must install from floppy disk (which we suggest you
 	do <emphasis>not</emphasis> do), either due to unsupported
 	hardware or simply because you insist on doing things the hard
 	way, you must first prepare some floppies for the installation.</para>
 
 	<para>At a minimum, you will need as many 1.44&nbsp;MB or 1.2&nbsp;MB floppies
 	  as it takes to hold all the files in the
 	  <filename>bin</filename> (binary distribution) directory.  If
 	  you are preparing the floppies from DOS, then they
 	  <emphasis>must</emphasis> be formatted using the &ms-dos;
 	  <command>FORMAT</command> command.  If you are using &windows;,
 	  use Explorer to format the disks (right-click on the
 	  <devicename>A:</devicename> drive, and select <quote>Format</quote>.</para>
 
 	<para>Do <emphasis>not</emphasis> trust factory pre-formatted
 	  floppies.  Format them again yourself, just to be sure.  Many
 	  problems reported by our users in the past have resulted from
 	  the use of improperly formatted media, which is why we are
 	  making a point of it now.</para>
 
 	<para>If you are creating the floppies on another FreeBSD machine,
 	  a format is still not a bad idea, though you do not need to put
 	  a DOS filesystem on each floppy.  You can use the
 	  <command>disklabel</command> and <command>newfs</command>
 	  commands to put a UFS filesystem on them instead, as the
 	  following sequence of commands (for a 3.5" 1.44&nbsp;MB floppy)
 	  illustrates:</para>
 
 	<screen>&prompt.root; <userinput>fdformat -f 1440 fd0.1440</userinput>
 &prompt.root; <userinput>disklabel -w -r fd0.1440 floppy3</userinput>
 &prompt.root; <userinput>newfs -t 2 -u 18 -l 1 -i 65536 /dev/fd0</userinput></screen>
 
 	<note>
 	  <para>Use <literal>fd0.1200</literal> and
 	    <literal>floppy5</literal> for 5.25" 1.2&nbsp;MB disks.</para>
 	</note>
 
 	<para>Then you can mount and write to them like any other
 	  filesystem.</para>
 
 	<para>After you have formatted the floppies, you will need to copy
 	  the files to them.  The distribution files are split into chunks
 	  conveniently sized so that five of them will fit on a conventional
 	  1.44&nbsp;MB floppy.  Go through all your floppies, packing as many
 	  files as will fit on each one, until you have all of the
 	  distributions you want packed up in this fashion.  Each
 	  distribution should go into a subdirectory on the floppy, e.g.:
 	  <filename>a:\bin\bin.aa</filename>,
 	  <filename>a:\bin\bin.ab</filename>, and so on.</para>
 
 	<para>Once you come to the Media screen during the install
 	  process, select <guimenuitem>Floppy</guimenuitem> and you
 	  will be prompted for the rest.</para>
       </sect2>
 
       <sect2 id="install-msdos">
         <title>Installing from an &ms-dos; Partition</title>
 
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>from MS-DOS</secondary>
 	</indexterm>
 	<para>To prepare for an installation from an &ms-dos; partition,
 	  copy the files from the distribution into a directory
           called <filename>freebsd</filename> in the root directory of the
 	  partition.  For example, <filename>c:\freebsd</filename>.  The
 	  directory structure of the CDROM or FTP site must be partially
 	  reproduced within this directory, so we suggest using the DOS
 	  <command>xcopy</command> command if you are copying it from a CD.
 	  For example, to prepare for a minimal installation of
 	  FreeBSD:</para>
 
 	<screen><prompt>C:\&gt;</prompt> <userinput>md c:\freebsd</userinput>
 <prompt>C:\&gt;</prompt> <userinput>xcopy e:\bin c:\freebsd\bin\ /s</userinput>
 <prompt>C:\&gt;</prompt> <userinput>xcopy e:\manpages c:\freebsd\manpages\ /s</userinput></screen>
 
 	<para>Assuming that <devicename>C:</devicename> is where you have
 	  free space and <devicename>E:</devicename> is where your CDROM
 	  is mounted.</para>
 	
 	<para>If you do not have a CDROM drive, you can download the
 	  distribution from <ulink
 	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">ftp.FreeBSD.org</ulink>.
 	  Each distribution is in its own directory; for example, the
 	  <emphasis>base</emphasis> distribution can be found in the <ulink
 	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/base/">&rel.current;/base/</ulink>
 	  directory.</para>
 
 	<note>
 	  <para>In the 4.X and older releases of &os; the <quote>base</quote>
 	    distribution is called <quote>bin</quote>.  Adjust the sample
 	    commands and URLs above accordingly, if you are using one of these
 	    versions.</para>
 	</note>
     
 	<para>For as many distributions you wish to install from an &ms-dos;
 	  partition (and you have the free space for), install each one
 	  under <filename>c:\freebsd</filename> &mdash; the
 	  <literal>BIN</literal> distribution is the only one required for
 	  a minimum installation.</para>
       </sect2>
 
       <sect2>
         <title>Creating an Installation Tape</title>
 
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>from QIC/SCSI Tape</secondary>
 	</indexterm>
 	<para>Installing from tape is probably the easiest method, short
 	  of an online FTP install or CDROM install.  The installation
 	  program expects the files to be simply tarred onto the tape.
 	  After getting all of the distribution files you are interested
 	  in, simply tar them onto the tape:</para>
 
 	<screen>&prompt.root; <userinput>cd /freebsd/distdir</userinput>
 &prompt.root; <userinput>tar cvf /dev/rwt0 dist1 ... dist2</userinput></screen>
 
 	<para>When you perform the installation, you should make
 	  sure that you leave enough room in some temporary directory
 	  (which you will be allowed to choose) to accommodate the
 	  <emphasis>full</emphasis> contents of the tape you have created.
 	  Due to the non-random access nature of tapes, this method of
 	  installation requires quite a bit of temporary storage.</para>
 
 	<note>
 	  <para>When starting the installation, the tape must be in the
 	    drive <emphasis>before</emphasis> booting from the boot
 	    floppy.  The installation probe may otherwise fail to find
 	    it.</para>
 	</note>
       </sect2>
 
       <sect2>
         <title>Before Installing over a Network</title>
 
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>network</secondary>
 	  <tertiary>serial (SLIP or PPP)</tertiary>
 	</indexterm>
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>network</secondary>
 	  <tertiary>parallel (PLIP)</tertiary>
 	</indexterm>
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>network</secondary>
 	  <tertiary>Ethernet</tertiary>
 	</indexterm>
 	<para>There are three types of network installations available.
 	  Serial port (SLIP or PPP), Parallel port (PLIP (laplink cable)),
 	  or Ethernet (a standard Ethernet controller (includes some
 	  PCMCIA)).</para>
 
 	<para>The SLIP support is rather primitive, and limited primarily
 	  to hard-wired links, such as a serial cable running between a
 	  laptop computer and another computer.  The link should be
 	  hard-wired as the SLIP installation does not currently offer a
 	  dialing capability; that facility is provided with the PPP
 	  utility, which should be used in preference to SLIP whenever
 	  possible.</para>
 
 	<para>If you are using a modem, then PPP is almost certainly
 	  your only choice.  Make sure that you have your service
 	  provider's information handy as you will need to know it fairly
 	  early in the installation process.</para>  
 
 	<para>If you use PAP or CHAP to connect your ISP (in other words, if
 	  you can connect to the ISP in &windows; without using a script), then
 	  all you will need to do is type in <command>dial</command> at the
 	  <application>ppp</application> prompt.  Otherwise, you will need to
 	  know how to dial your ISP using the <quote>AT commands</quote>
 	  specific to your modem, as the PPP dialer provides only a very
 	  simple terminal emulator.  Please refer to the user-ppp <link
 	  linkend="userppp">handbook</link> and <ulink
 	  url="&url.books.faq;/ppp.html">FAQ</ulink> entries for further information.
 	  If you have problems, logging can be directed to the screen using
 	  the command <command>set log local ...</command>.</para>
 
 	<para>If a hard-wired connection to another FreeBSD (2.0-R or
 	  later) machine is available, you might also consider installing
 	  over a <quote>laplink</quote> parallel port cable.  The data rate
 	  over the parallel port is much higher than what is typically
 	  possible over a serial line (up to 50&nbsp;kbytes/sec), thus resulting
 	  in a quicker installation.</para>
 
 	<para>Finally, for the fastest possible network installation, an
 	  Ethernet adapter is always a good choice!  FreeBSD supports most
 	  common PC Ethernet cards; a table of supported cards (and their
 	  required settings) is provided in the Hardware Notes for each
 	  release of FreeBSD.  If you are using one of the supported PCMCIA
 	  Ethernet cards, also be sure that it is plugged in
 	  <emphasis>before</emphasis> the laptop is powered on!  FreeBSD does
 	  not, unfortunately, currently support hot insertion of PCMCIA cards
 	  during installation.</para>
 
 	<para>You will also need to know your IP address on the network,
 	  the netmask value for your address class, and the name of your
 	  machine.  If you are installing over a PPP connection and do not
 	  have a static IP, fear not, the IP address can be dynamically
 	  assigned by your ISP.  Your system administrator can tell you
 	  which values to use for your particular network setup.  If you
 	  will be referring to other hosts by name rather than IP address,
 	  you will also need a name server and possibly the address of a
 	  gateway (if you are using PPP, it is your provider's IP address)
 	  to use in talking to it.  If you want to install by FTP via a
 	  HTTP proxy, you will also need the proxy's address.
 	  If you do not know the answers to all or most of these questions,
 	  then you should really probably talk to your system administrator
 	  or ISP <emphasis>before</emphasis> trying this type of
 	  installation.</para>
 
 	<sect3>
 	  <title>Before Installing via NFS</title>
 
 	  <indexterm>
 	    <primary>installation</primary>
 	    <secondary>network</secondary>
 	    <tertiary>NFS</tertiary>
 	  </indexterm>
 	  <para>The NFS installation is fairly straight-forward.  Simply
 	    copy the FreeBSD distribution files you want onto an NFS server
 	    and then point the NFS media selection at it.</para>
 
 	  <para>If this server supports only <quote>privileged port</quote>
 	    (as is generally the default for Sun workstations), you will
 	    need to set the option <literal>NFS Secure</literal> in the
 	    <guimenu>Options</guimenu> menu before installation can proceed.</para>
 
 	  <para>If you have a poor quality Ethernet card which suffers
 	    from very slow transfer rates, you may also wish to toggle the
 	    <literal>NFS Slow</literal> flag.</para>
 
 	  <para>In order for NFS installation to work, the server must
 	    support subdir mounts, for example, if your FreeBSD&nbsp;&rel.current; distribution
 	    directory lives on:
 	    <filename>ziggy:/usr/archive/stuff/FreeBSD</filename>, then
 	    <hostid>ziggy</hostid> will have to allow the direct mounting
 	    of <filename>/usr/archive/stuff/FreeBSD</filename>, not just
 	    <filename>/usr</filename> or
 	    <filename>/usr/archive/stuff</filename>.</para>
 
 	  <para>In FreeBSD's <filename>/etc/exports</filename> file, this
 	    is controlled by the <option>-alldirs</option> options.  Other NFS
 	    servers may have different conventions.  If you are getting
 	    <errorname>permission denied</errorname> messages from the
 	    server, then it is likely that you do not have this enabled
 	    properly.</para>
 	</sect3>
 
       </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
index 878ad54569..74522b6123 100644
--- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
@@ -1,1751 +1,1747 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="kernelconfig">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Updated and restructured by </contrib>
 	<!-- Mar 2000 -->
       </author>
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Jake</firstname>
 	<surname>Hamby</surname>
 	<contrib>Originally contributed by </contrib>
 	<!-- 6 Oct 1995 -->
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Configuring the FreeBSD Kernel</title>
 
   <sect1 id="kernelconfig-synopsis">
     <title>Synopsis</title>
 
     <indexterm>
       <primary>kernel</primary>
       <secondary>building a custom kernel</secondary>
     </indexterm>
 
     <para>The kernel is the core of the &os; operating system.  It is
       responsible for managing memory, enforcing security controls,
       networking, disk access, and much more.  While more and more of &os;
       becomes dynamically configurable it is still occasionally necessary to
       reconfigure and recompile your kernel.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Why you might need to build a custom kernel.</para>
       </listitem>
 
       <listitem>
 	<para>How to write a kernel configuration file, or alter an existing
 	  configuration file.</para>
       </listitem>
 
       <listitem>
 	<para>How to use the kernel configuration file to create and build a
 	  new kernel.</para>
       </listitem>
 
       <listitem>
 	<para>How to install the new kernel.</para>
       </listitem>
 
       <listitem>
 	<para>How to create any entries in <filename>/dev</filename> that may
 	  be required.</para>
       </listitem>
 
       <listitem>
 	<para>How to troubleshoot if things go wrong.</para>
       </listitem>
     </itemizedlist>
 
     <para>All of the commands listed within this chapter by way of example
       should be executed as <username>root</username> in order to
       succeed.</para>
   </sect1>
 
   <sect1 id="kernelconfig-custom-kernel">
     <title>Why Build a Custom Kernel?</title>
 
     <para>Traditionally, &os; has had what is called a
       <quote>monolithic</quote> kernel.  This means that the kernel was one
       large program, supported a fixed list of devices, and if you wanted to
       change the kernel's behavior then you had to compile a new kernel, and
       then reboot your computer with the new kernel.</para>
 
     <para>Today, &os; is rapidly moving to a model where much of the
       kernel's functionality is contained in modules which can be
       dynamically loaded and unloaded from the kernel as necessary.
       This allows the kernel to adapt to new hardware suddenly
       becoming available (such as PCMCIA cards in a laptop), or for
       new functionality to be brought into the kernel that was not
       necessary when the kernel was originally compiled.  This is
       known as a modular kernel.</para>
 
     <para>Despite this, it is still necessary to carry out some static kernel
       configuration.  In some cases this is because the functionality is so
       tied to the kernel that it can not be made dynamically loadable.  In
       others it may simply be because no one has yet taken the time to write a
       dynamic loadable kernel module for that functionality.</para>
 
     <para>Building a custom kernel is one of the most important rites of
       passage nearly every BSD user must endure.  This process, while
       time consuming, will provide many benefits to your &os; system.
       Unlike the <filename>GENERIC</filename> kernel, which must support a
       wide range of hardware, a custom kernel only contains support for
       <emphasis>your</emphasis> PC's hardware.  This has a number of
       benefits, such as:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Faster boot time.  Since the kernel will only probe the
 	hardware you have on your system, the time it takes your system to
 	boot can decrease dramatically.</para>
       </listitem>
 
       <listitem>
 	<para>Lower memory usage.  A custom kernel often uses less memory
 	  than the <filename>GENERIC</filename> kernel, which is important
 	  because the kernel must always be present in real
 	  memory.  For this reason, a custom kernel is especially useful
 	  on a system with a small amount of RAM.</para>
       </listitem>
 
       <listitem>
 	<para>Additional hardware support.  A custom kernel allows you to
 	  add in support for devices which are not
 	  present in the <filename>GENERIC</filename> kernel, such as
 	  sound cards.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="kernelconfig-building">
     <title>Building and Installing a Custom Kernel</title>
     <indexterm>
       <primary>kernel</primary>
       <secondary>building / installing</secondary>
     </indexterm>
 
     <para>First, let us take a quick tour of the kernel build directory.
       All directories mentioned will be relative to the main
       <filename>/usr/src/sys</filename> directory, which is also
       accessible through the path name <filename>/sys</filename>.  There are a number of
       subdirectories here representing different parts of the kernel, but
       the most important for our purposes are
       <filename><replaceable>arch</replaceable>/conf</filename>, where you
       will edit your custom kernel configuration, and
       <filename>compile</filename>, which is the staging area where your
       kernel will be built.  <replaceable>arch</replaceable> represents
       one of <filename>i386</filename>, <filename>alpha</filename>,
       <filename>amd64</filename>, <filename>ia64</filename>,
       <filename>powerpc</filename>, <filename>sparc64</filename>, or
       <filename>pc98</filename> (an alternative development branch of PC
       hardware, popular in Japan).  Everything inside a particular
       architecture's directory deals with that architecture only; the rest
       of the code is machine independent code common to all platforms to which &os; could
       potentially be ported.  Notice the logical organization of the
       directory structure, with each supported device, file system, and
       option in its own subdirectory.  Versions of &os; prior to 5.X
       support only the <filename>i386</filename>, <filename>alpha</filename>
       and <filename>pc98</filename> architectures.</para>
 
     <para>This chapter assumes that you are using the i386 architecture
       in the examples.  If this is not the case for your situation,
       make appropriate adjustments to the path names for your system's
       architecture.</para>
 
     <note>
       <para>If there is <emphasis>not</emphasis> a
 	<filename>/usr/src/sys</filename> directory on your system,
 	then the kernel source has not been installed.  The easiest
 	way to do this is by running
 	<command>sysinstall</command> (<command>/stand/sysinstall</command>
 	in &os; versions older than 5.2) as
 	<username>root</username>, choosing
 	<guimenuitem>Configure</guimenuitem>, then
 	<guimenuitem>Distributions</guimenuitem>, then
 	<guimenuitem>src</guimenuitem>, then
 	<guimenuitem>sys</guimenuitem>.  If you have an aversion to
 	<application>sysinstall</application> and you have access to
 	an <quote>official</quote> &os; CDROM, then you can also
 	install the source from the command line:</para>
 
       <screen>&prompt.root; <userinput>mount /cdrom</userinput>
 &prompt.root; <userinput>mkdir -p /usr/src/sys</userinput>
 &prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput>
 &prompt.root; <userinput>cat /cdrom/src/ssys.[a-d]* | tar -xzvf -</userinput></screen>
     </note>
 
     <para>Next, move to the
       <filename><replaceable>arch</replaceable>/conf</filename> directory
       and copy the <filename>GENERIC</filename> configuration file to the
       name you want to give your kernel.  For example:</para>
 
     <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
 &prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
 
     <para>Traditionally, this name is in all capital letters and, if you
       are maintaining multiple &os; machines with different hardware,
       it is a good idea to name it after your machine's hostname.  We will
       call it <filename>MYKERNEL</filename> for the purpose of this
       example.</para>
 
     <tip>
       <para>Storing your kernel configuration file directly under
 	<filename>/usr/src</filename> can be a bad idea.  If you are
 	experiencing problems it can be tempting to just delete
 	<filename>/usr/src</filename> and start again.  After doing this,
 	it usually only takes a few seconds for
 	you to realize that you have deleted your custom kernel
 	configuration file.  Also, do not edit <filename>GENERIC</filename>
 	directly, as it may get overwritten the next time you
 	<link linkend="cutting-edge">update your source tree</link>, and
 	your kernel modifications will be lost.</para>
 
       <para>You might want to keep your kernel configuration file
 	elsewhere, and then create a symbolic link to the file in
 	the <filename><replaceable>i386</replaceable></filename>
 	directory.</para>
 
       <para>For example:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
 &prompt.root; <userinput>mkdir /root/kernels</userinput>
 &prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>	
 &prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
     </tip>
 
     <para>Now, edit <filename>MYKERNEL</filename> with your favorite text
       editor.  If you are just starting out, the only editor available
       will probably be <application>vi</application>, which is too complex to
       explain here, but is covered well in many books in the <link
       linkend="bibliography">bibliography</link>.  However, &os; does
       offer an easier editor called <application>ee</application> which, if
       you are a beginner, should be your editor of choice.  Feel free to
       change the comment lines at the top to reflect your configuration or
       the changes you have made to differentiate it from
       <filename>GENERIC</filename>.</para>
     <indexterm><primary>SunOS</primary></indexterm>
 
     <para>If you have built a kernel under &sunos; or some other BSD
       operating system, much of this file will be very familiar to you.
       If you are coming from some other operating system such as DOS, on
       the other hand, the <filename>GENERIC</filename> configuration file
       might seem overwhelming to you, so follow the descriptions in the
       <link linkend="kernelconfig-config">Configuration File</link>
       section slowly and carefully.</para>
 
     <note>
       <para>If you <link
         linkend="cutting-edge">sync your source tree</link> with the
         latest sources of the &os; project,
         be sure to always check the file
         <filename>/usr/src/UPDATING</filename> before you perform any update
         steps.  This file describes any important issues or areas
         requiring special attention within the updated source code.
         <filename>/usr/src/UPDATING</filename> always matches
         your version of the &os; source, and is therefore more up to date
         with new information than this handbook.</para>
     </note>
 
     <para>You must now compile the source code for the kernel.  There are two
       procedures you can use to do this, and the one you will use depends on
       why you are rebuilding the kernel and the version of &os; that you are
       running.</para>
 
     <itemizedlist>
       <listitem>
 	<para>If you have installed <emphasis>only</emphasis> the kernel
 	  source code, use procedure 1.</para>
       </listitem>
 
       <listitem>
 	<para>If you are running a &os; version prior to 4.0, and you are
 	  <emphasis>not</emphasis> upgrading to &os;&nbsp;4.0 or higher using
 	  the <command>make buildworld</command> procedure, use procedure 1.
         </para>
       </listitem>
 
       <listitem>
 	<para>If you are building a new kernel without updating the source
 	  code (perhaps just to add a new option, such as
 	  <literal>IPFIREWALL</literal>) you can use either procedure.</para>
       </listitem>
 
       <listitem>
 	<para>If you are rebuilding the kernel as part of a
           <command>make buildworld</command> process, use procedure 2.
         </para>
       </listitem>
     </itemizedlist>
     
     <indexterm>
       <primary><command>cvsup</command></primary>
     </indexterm>
-    <indexterm><primary>anonymous CVS</primary></indexterm>
     <indexterm><primary>CTM</primary></indexterm>
     <indexterm>
       <primary>CVS</primary>
       <secondary>anonymous</secondary>
     </indexterm>
 
     <para>If you have <emphasis>not</emphasis> upgraded your source
       tree in any way since the last time you successfully completed
       a <maketarget>buildworld</maketarget>-<maketarget>installworld</maketarget> cycle
       (you have not run <application>CVSup</application>,
       <application>CTM</application>, or used 
       <application>anoncvs</application>), then it is safe to use the
       <command>config</command>, <command>make depend</command>,
       <command>make</command>, <command>make install</command> sequence.
     </para>
 
     <procedure>
       <title>Procedure 1.  Building a Kernel the <quote>Traditional</quote> Way</title>
       
       <step>
 	<para>Run &man.config.8; to generate the kernel source code.</para>
 	
 	<screen>&prompt.root; <userinput>/usr/sbin/config <replaceable>MYKERNEL</replaceable></userinput></screen>
       </step>
 
       <step>
 	<para>Change into the build directory.  &man.config.8; will print
 	  the name of this directory after being run as above.</para>
 
 	<screen>&prompt.root; <userinput>cd ../compile/<replaceable>MYKERNEL</replaceable></userinput></screen>
 
 	<para>For &os; versions prior to 5.0, use the following form instead:</para>
 
 	<screen>&prompt.root; <userinput>cd ../../compile/<replaceable>MYKERNEL</replaceable></userinput></screen>
       </step>
 
       <step>
 	<para>Compile the kernel.</para>
 	
 	<screen>&prompt.root; <userinput>make depend</userinput>
 &prompt.root; <userinput>make</userinput></screen>
       </step>
 
       <step>
 	<para>Install the new kernel.</para>
 	
 	<screen>&prompt.root; <userinput>make install</userinput></screen>
       </step>
     </procedure>
 
     <procedure>
       <title>Procedure 2.  Building a Kernel the <quote>New</quote>
 	Way</title>
       
       <step>
 	<para>Change to the <filename>/usr/src</filename> directory.</para>
 	
 	<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
       </step>
 
       <step>
 	<para>Compile the kernel.</para>
 	
 	<screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
       </step>
 
       <step>
 	<para>Install the new kernel.</para>
 
 	<screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
       </step>
     </procedure>
     
     <note>
       <para>In &os;&nbsp;4.2 and older you must replace
         <literal>KERNCONF=</literal> with <literal>KERNEL=</literal>.
         4.2-STABLE that was fetched before Feb 2nd, 2001 does not
         recognize <literal>KERNCONF=</literal>.</para>
     </note>
 
     <indexterm>
       <primary><filename class="directory">/boot/kernel.old</filename></primary>
     </indexterm> 
 
     <para>The new kernel will be copied to the <filename
         class="directory">/boot/kernel</filename> directory as
       <filename>/boot/kernel/kernel</filename> and the old kernel will be moved to
       <filename>/boot/kernel.old/kernel</filename>.  Now, shutdown the system and
       reboot to use your new kernel.  If something goes wrong, there are
       some <link linkend="kernelconfig-trouble">troubleshooting</link>
       instructions at the end of this chapter that you may find useful.  Be sure to read the
       section which explains how to recover in case your new kernel <link
       linkend="kernelconfig-noboot">does not boot</link>.</para>
 
     <note>
       <para>In &os; 4.X and earlier, kernels are installed
 	in <filename>/kernel</filename>, modules in <filename
           class="directory">/modules</filename>, and old kernels
 	are backed up in <filename>/kernel.old</filename>.
 	Other files relating to the boot process, such as the boot
 	&man.loader.8; and configuration are stored in
 	<filename>/boot</filename>.  Third party or custom modules
 	can be placed in <filename class="directory">/modules</filename>, although
 	users should be aware that keeping modules in sync with the
 	compiled kernel is very important.  Modules not intended
 	to run with the compiled kernel may result in instability
 	or incorrectness.</para>
     </note>
 
     <note>
       <para>If you have added any new devices (such as sound cards)
 	and you are running &os;&nbsp;4.X or previous versions, you
 	may have to add some device nodes to your
 	<filename class="directory">/dev</filename> directory before
 	you can use them. For more information, take a look at <link
 	linkend="kernelconfig-nodes">Making Device Nodes</link>
 	section later on in this chapter.</para>
     </note>
   </sect1>
 
   <sect1 id="kernelconfig-config">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Joel</firstname>
 	  <surname>Dahl</surname>
 	  <contrib>Updated for &os; 5.X by </contrib>
 	  <!-- August 2004, PR docs/70674 -->
 	</author>
 	<!--  <editor><othername role="freefall login">ceri</othername></editor> -->
       </authorgroup>
     </sect1info>
     <title>The Configuration File</title>
     <indexterm>
       <primary>kernel</primary>
       <secondary>NOTES</secondary>
     </indexterm>
     <indexterm>
       <primary>kernel</primary>
       <secondary>LINT</secondary>
     </indexterm>
     <indexterm><primary>NOTES</primary></indexterm>
     <indexterm><primary>LINT</primary></indexterm>
     <indexterm>
       <primary>kernel</primary>
       <secondary>configuration file</secondary>
     </indexterm>
 
     <para>The general format of a configuration file is quite simple.
       Each line contains a keyword and one or more arguments.  For
       simplicity, most lines only contain one argument.  Anything
       following a <literal>#</literal> is considered a comment and
       ignored.  The following sections describe each keyword, generally in
       the order they are listed in <filename>GENERIC</filename>, although
       some related keywords have been grouped together in a single section
       (such as Networking) even though they are actually scattered
       throughout the <filename>GENERIC</filename> file.  <anchor
       id="kernelconfig-options"> For an exhaustive list of architecture
       dependent options and devices, see the <filename>NOTES</filename>
       file in the same directory as <filename>GENERIC</filename>. For
       architecture independent options, see
       <filename>/usr/src/sys/conf/NOTES</filename>.</para>
 
     <note>
       <para><filename>NOTES</filename> does not exist in &os;&nbsp;4.X.
         Instead, see the <filename>LINT</filename> file for detailed
         explanations of options and devices in <filename>GENERIC</filename>.
         <filename>LINT</filename> served two purposes in 4.X: to provide a
         reference for choosing kernel options when building a custom
         kernel, and to provide a kernel configuration with as many
         tweakable options tweaked to non-default values as possible. The
         reason behind this was that such a configuration helped (and still
         does) a lot when testing new code and changes to existing code that
         may cause conflicts with other parts of the kernel. However,
         the kernel configuration framework went through some heavy changes
         in 5.X; one example of this is that the driver configuration options were moved
         to a <literal>hints</literal> file so that they could be changed
         and loaded dynamically at boot time, and <filename>LINT</filename>
         could not contain those hints anymore.  For this and other
         reasons, the <filename>LINT</filename> file was renamed to
         <filename>NOTES</filename> and retained mostly the first reason for
         its existence: documenting the available options for user
         convenience.</para>
 
       <para>In &os; 5.X and later versions you can still generate a buildable
 	<filename>LINT</filename> file by typing:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf && make LINT</userinput></screen>
     </note>
 
     <indexterm>
       <primary>kernel</primary>
       <secondary>configuration file</secondary>
     </indexterm>
 
     <para>The following is an example of the <filename>GENERIC</filename> kernel
       configuration file with various additional comments where needed for
       clarity.  This example should match your copy in
       <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename>
       fairly closely.</para>
 
     <programlisting>#
 # GENERIC -- Generic kernel configuration file for &os;/i386
 #
 # For more information on this file, please read the handbook section on
 # Kernel Configuration Files:
 #
 #    http://www.&os;.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig-config.html
 #
 # The handbook is also available locally in /usr/share/doc/handbook
 # if you've installed the doc distribution, otherwise always see the
 # &os; World Wide Web server (http://www.FreeBSD.org/) for the
 # latest information.
 #
 # An exhaustive list of options and more detailed explanations of the
 # device lines is also present in the ../../conf/NOTES and NOTES files. 
 # If you are in doubt as to the purpose or necessity of a line, check first 
 # in NOTES.
 #
 # &dollar;FreeBSD: /repoman/r/ncvs/src/sys/i386/conf/GENERIC,v 1.413 2004/08/11 01:34:18 rwatson Exp &dollar;</programlisting>
 
     <para>The following are the mandatory keywords required in
       <emphasis>every</emphasis> kernel you build:</para>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>machine</secondary>
     </indexterm>
 
     <programlisting>machine		i386</programlisting>
 
     <para>This is the machine architecture.  It must be either
       <literal>alpha</literal>, <literal>amd64</literal>,
       <literal>i386</literal>, <literal>ia64</literal>,
       <literal>pc98</literal>, <literal>powerpc</literal>, or
       <literal>sparc64</literal>.</para>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>cpu</secondary>
     </indexterm>
     <programlisting>cpu          I486_CPU
 cpu          I586_CPU
 cpu          I686_CPU</programlisting>
 
     <para>The above option specifies the type of CPU you have in your
       system.  You may have multiple instances of the CPU line (if, for
       example, you are not sure whether you should use
       <literal>I586_CPU</literal> or <literal>I686_CPU</literal>),
       but for a custom kernel it is best to specify only the CPU
       you have.  If you are unsure of your CPU type, you can check the
       <filename>/var/run/dmesg.boot</filename> file to view your boot
       messages.</para>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>cpu type</secondary>
     </indexterm>
     <para>Support for <literal>I386_CPU</literal> is still provided in the
       source of &os;, but it is disabled by default in both -STABLE and
       -CURRENT.  This means that to install &os; with a 386-class cpu, you now
       have the following options:</para>
 
     <itemizedlist>
       <listitem>
         <para>Install an older &os; release and rebuild from source as
 	  described in <xref linkend="kernelconfig-building">.</para>
       </listitem>
 
       <listitem>
         <para>Build the userland and kernel on a newer machine and install on
           the 386 using the precompiled <filename>/usr/obj</filename>
           files (see <xref linkend="small-lan"> for details).</para>
       </listitem>
 
       <listitem>
         <para>Roll your own release of &os; which includes
           <literal>I386_CPU</literal> support in the kernels of the
           installation CD-ROM.</para>
       </listitem>
     </itemizedlist>
 
     <para>The first of these options is probably the easiest of all, but you
       will need a lot of disk space which, on a 386-class machine, may be
       difficult to find.</para>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>ident</secondary>
     </indexterm>
 
     <programlisting>ident          GENERIC</programlisting>
 
     <para>This is the identification of the kernel.  You should change
       this to whatever you named your kernel,
       i.e. <literal>MYKERNEL</literal> if you have followed the
       instructions of the previous examples.  The value you put in the
       <literal>ident</literal> string will print when you boot up the
       kernel, so it is useful to give the new kernel a different name if you
       want to keep it separate from your usual kernel (e.g., you want to
       build an experimental kernel).</para>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>maxusers</secondary>
     </indexterm>
 
     <programlisting>maxusers          <replaceable>n</replaceable></programlisting>
 
     <para>The <literal>maxusers</literal> option sets the size of a number
       of important system tables.  This number is supposed to be roughly
       equal to the number of simultaneous users you expect to have on your
       machine.</para>
 
     <para>Starting with &os;&nbsp;4.5, the system will auto-tune this setting
       for you if you explicitly set it to <literal>0</literal><footnote>
 	<para>The auto-tuning algorithm sets <literal>maxusers</literal> equal
 	  to the amount of memory in the system, with a minimum of 32, and a
 	  maximum of 384.</para></footnote>.
       In &os;&nbsp;5.X and above, <literal>maxusers</literal> will default to
       <literal>0</literal> if not specified.  If you are using an
       version of &os; earlier than 4.5, or you want to manage it
       yourself you will want to set
       <literal>maxusers</literal> to at least 4, especially if you are
       using the X Window System or compiling software.  The reason is that
       the most important table set by <literal>maxusers</literal> is the
       maximum number of processes,  which is set to <literal>20 + 16 *
       maxusers</literal>, so if you set <literal>maxusers</literal> to 1,
       then you can only have 36 simultaneous processes, including the 18
       or so that the system starts up at boot time and the 15 or so you
       will probably create when you start the X Window System.  Even a
       simple task like reading a manual page will start up nine processes to
       filter, decompress, and view it.  Setting
       <literal>maxusers</literal> to 64 will allow you to have up to 1044
       simultaneous processes, which should be enough for nearly all uses.
       If, however, you see the dreaded <errortype>proc table
       full</errortype> error when trying to start another program, or are
       running a server with a large number of simultaneous users (like
       <hostid role="fqdn">ftp.FreeBSD.org</hostid>), you can always
       increase the number and rebuild.</para>
 
     <note>
       <para><literal>maxusers</literal> does <emphasis>not</emphasis>
 	limit the number of users which can log into your machine.  It
 	simply sets various table sizes to reasonable values considering
 	the maximum number of users you will likely have on your system
 	and how many processes each of them will be running.  One keyword
 	which <emphasis>does</emphasis> limit the number of simultaneous
 	remote logins and X terminal windows is <link
 	linkend="kernelconfig-ptys"><literal>pseudo-device pty
 	16</literal></link>.  With &os;&nbsp;5.X, you do not have to
 	worry about this number since the &man.pty.4; driver is
 	<quote>auto-cloning</quote>; you simply use the line
 	<literal>device pty</literal> in your configuration file.</para>
     </note>
     
     <programlisting># Floating point support - do not disable.
 device          npx</programlisting>
     
     <para><literal>npx</literal> is the interface to the floating point
       math unit in &os;, which is either the hardware co-processor or
       the software math emulator.  This is <emphasis>not</emphasis>
       optional.</para>
 
     <programlisting># Pseudo devices
 device   loop          # Network loopback</programlisting>
 
     <para>This is the generic loopback device for TCP/IP.  If you telnet
       or FTP to <hostid>localhost</hostid> (a.k.a. <hostid
       role="ipaddr">127.0.0.1</hostid>) it will come back at you through
       this device.  This is <emphasis>mandatory</emphasis>.  Under
       &os;&nbsp;4.X you have to use the line <literal>pseudo-device
       loop</literal>.</para>
 
     <para>Everything that follows is more or less optional.  See the notes
       underneath or next to each option for more information.</para>
 
     <programlisting>#To statically compile in device wiring instead of /boot/device.hints
 #hints          "GENERIC.hints"         # Default places to look for devices.</programlisting>
 
     <para>In &os; 5.X and newer versions the &man.device.hints.5; is
       used to configure options of the device drivers.  The default
       location that &man.loader.8; will check at boot time is
       <filename>/boot/device.hints</filename>.  Using the
       <literal>hints</literal> option you can compile these hints
       statically into your kernel.  Then there is no need to create a
       <filename>device.hints</filename> file in
       <filename>/boot</filename>.</para>
 
     <!-- XXX: Add a comment here that explains when compiling hints into
       the kernel is a good idea and why. -->
 
     <programlisting>#makeoptions     DEBUG=-g          # Build kernel with gdb(1) debug symbols</programlisting>
 
     <para>The normal build process of &os; does not include
       debugging information when building the kernel and strips most
       symbols after the resulting kernel is linked, to save some space
       at the install location.  If you are going to do tests of kernels
       in the -CURRENT branch or develop changes of your own for the &os;
       kernel, you might want to uncomment this line.  It will enable the
       use of the <option>-g</option> option which enables debugging
       information when passed to &man.gcc.1;.  The same can be
       accomplished by the &man.config.8; <option>-g</option> option, if
       you are using the <quote>traditional</quote> way for building your
       kernels (see <xref linkend="kernelconfig-building">
       for more information).</para>
 
     <programlisting>options          SCHED_4BSD         # 4BSD scheduler</programlisting>
 
     <para>The traditional scheduler for &os;.  Depending on your system's
       workload, you may gain performance by using the new ULE scheduler for
       &os; that has been designed specially for SMP, but works just fine on UP
       systems too.  If you wish to try it out, replace <literal>SCHED_4BSD</literal>
       with <literal>SCHED_ULE</literal> in your configuration file.</para>
 
     <programlisting>options          INET              # InterNETworking</programlisting>
 
     <para>Networking support.  Leave this in, even if you do not plan to
       be connected to a network.  Most programs require at least loopback
       networking (i.e., making network connections within your PC), so
       this is essentially mandatory.</para>
 
     <programlisting>options          INET6             # IPv6 communications protocols</programlisting>
 
     <para>This enables the IPv6 communication protocols.</para>
 
     <programlisting>options          FFS               # Berkeley Fast Filesystem</programlisting>
 
     <para>This is the basic hard drive file system.  Leave it in if you
       boot from the hard disk.</para>
 
     <programlisting>options          UFS_ACL           # Support for access control lists</programlisting>
 
     <para>This option, present only in &os;&nbsp;5.X, enables kernel support
       for access control lists.  This relies on the use of extended
       attributes and <acronym>UFS2</acronym>, and the feature is described
       in detail in <xref linkend="fs-acl">.  <acronym>ACL</acronym>s are
       enabled by default and should not be
       disabled in the kernel if they have been used previously on a file
       system, as this will remove the access control lists, changing the
       way files are protected in unpredictable ways.</para>
 
     <programlisting>options          UFS_DIRHASH       # Improve performance on big directories</programlisting>
 
     <para>This option includes functionality to speed up disk
       operations on large directories, at the expense of using
       additional memory.  You would normally keep this for a large
       server, or interactive workstation, and remove it if you are
       using &os; on a smaller system where memory is at a premium and
       disk access speed is less important, such as a firewall.</para>
 
     <programlisting>options          SOFTUPDATES       # Enable FFS Soft Updates support</programlisting>
 
     <para>This option enables Soft Updates in the kernel, this will
       help speed up write access on the disks.  Even when this
       functionality is provided by the kernel, it must be turned on
       for specific disks.  Review the output from &man.mount.8; to see
       if Soft Updates is enabled for your system disks.  If you do not
       see the <literal>soft-updates</literal> option then you will
       need to activate it using the &man.tunefs.8; (for existing
       file systems) or &man.newfs.8; (for new file systems)
       commands.</para>
 
     <programlisting>options          MD_ROOT           # MD is a potential root device</programlisting>
 
     <para>This option enables support for a memory backed virtual disk
       used as a root device.</para>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>NFS</secondary>
     </indexterm>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>NFS_ROOT</secondary>
     </indexterm>
     <programlisting>options          NFSCLIENT         # Network Filesystem Client
 options          NFSSERVER         # Network Filesystem Server
 options          NFS_ROOT          # NFS usable as /, requires NFSCLIENT</programlisting>
 
     <para>The network file system.  Unless you plan to mount partitions
       from a &unix; file server over TCP/IP, you can comment these
       out.</para>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>MSDOSFS</secondary>
     </indexterm>
     <programlisting>options          MSDOSFS           # MSDOS Filesystem</programlisting>
 
     <para>The &ms-dos; file system.  Unless you plan to mount a DOS formatted
       hard drive partition at boot time, you can safely comment this out.
       It will be automatically loaded the first time you mount a DOS
       partition, as described above.  Also, the excellent
       <filename role="package">emulators/mtools</filename> software
       allows you to access DOS floppies without having to mount and
       unmount them (and does not require <literal>MSDOSFS</literal> at
       all).</para>
 
     <programlisting>options          CD9660            # ISO 9660 Filesystem</programlisting>
 
     <para>The ISO 9660 file system for CDROMs.  Comment it out if you do
       not have a CDROM drive or only mount data CDs occasionally (since it
       will be dynamically loaded the first time you mount a data CD).
       Audio CDs do not need this file system.</para>
 
     <programlisting>options          PROCFS            # Process filesystem</programlisting>
 
     <para>The process file system.  This is a <quote>pretend</quote>
       file system mounted on <filename>/proc</filename> which allows
       programs like &man.ps.1; to give you more information on what
       processes are running.  In &os; 5.X and above, use of <literal>PROCFS</literal>
       is not required under most circumstances, as most
       debugging and monitoring tools have been adapted to run without
       <literal>PROCFS</literal>: unlike in &os; 4.X, new installations of
       &os; 5.X will not mount the process file system by default.
       In addition, 6.X-CURRENT kernels
       making use of <literal>PROCFS</literal> must now also include
       support for <literal>PSEUDOFS</literal>:</para>
 
     <programlisting>options          PSEUDOFS          # Pseudo-filesystem framework</programlisting>
 
     <para><literal>PSEUDOFS</literal> is not available in &os; 4.X.</para>
 
     <programlisting>options          GEOM_GPT          # GUID Partition Tables.</programlisting>
 
     <para>This option brings the ability to have a large number of
       partitions on a single disk.</para>
 
     <programlisting>options          COMPAT_43         # Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
 
     <para>Compatibility with 4.3BSD.  Leave this in; some programs will
       act strangely if you comment this out.</para>
 
     <programlisting>options          COMPAT_FREEBSD4   # Compatible with &os;4</programlisting>
 
     <para>This option is required on &os;&nbsp;5.X &i386; and Alpha systems
       to support applications compiled on older versions of &os;
       that use older system call interfaces.  It is recommended that
       this option be used on all &i386; and Alpha systems that may
       run older applications; platforms that gained support only in
       5.X, such as ia64 and &sparc64;, do not require this option.</para>
 
     <programlisting>options          SCSI_DELAY=15000  # Delay (in ms) before probing SCSI</programlisting>
 
     <para>This causes the kernel to pause for 15 seconds before probing
       each SCSI device in your system.  If you only have IDE hard drives,
       you can ignore this, otherwise you will probably want to lower this
       number, perhaps to 5 seconds, to speed up booting.  Of course, if
       you do this and &os; has trouble recognizing your SCSI devices,
       you will have to raise it again.</para>
 
     <programlisting>options          KTRACE            # ktrace(1) support</programlisting>
 
     <para>This enables kernel process tracing, which is useful in
       debugging.</para>
 
     <programlisting>options          SYSVSHM           # SYSV-style shared memory</programlisting>
 
     <para>This option provides for System&nbsp;V shared memory.  The most
       common use of this is the XSHM extension in X, which many
       graphics-intensive programs will automatically take advantage of for
       extra speed.  If you use X, you will definitely want to include
       this.</para>
 
     <programlisting>options          SYSVSEM           # SYSV-style semaphores</programlisting>
 
     <para>Support for System&nbsp;V semaphores.  Less commonly used but only
       adds a few hundred bytes to the kernel.</para>
 
     <programlisting>options          SYSVMSG           # SYSV-style message queues</programlisting>
 
     <para>Support for System&nbsp;V messages.  Again, this option only adds
       a few hundred bytes to the kernel.</para>
 
     <note>
       <para>The <option>-p</option> option of the &man.ipcs.1; command will
 	list any processes using each of these System&nbsp;V facilities.</para>
     </note>
 
     <programlisting>options 	     _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions</programlisting>
 
     <para>Real-time extensions added in the 1993 &posix;.  Certain
       applications in the ports collection use these
       (such as <application>&staroffice;</application>).</para>
 
     <programlisting>options          KBD_INSTALL_CDEV  # install a CDEV entry in /dev</programlisting>
 
     <para>This option is related to the keyboard. It installs a CDEV entry
       in <filename>/dev</filename>.</para>
 
     <programlisting>options          AHC_REG_PRETTY_PRINT     # Print register bitfields in debug
                                           # output.  Adds ~128k to driver.
 options          AHD_REG_PRETTY_PRINT     # Print register bitfields in debug
                                           # output.  Adds ~215k to driver.</programlisting>
 
     <para>This helps debugging by printing easier register definitions for
       reading.</para>
 
     <programlisting>options          ADAPTIVE_GIANT    # Giant mutex is adaptive.</programlisting>
 
     <para>Giant is the name of a mutual exclusion mechanism (a sleep mutex)
       that protects a large set of kernel resources.  Today, this is an
       unacceptable performance bottleneck which is actively being replaced
       with locks that protect individual resources.  The
       <literal>ADAPTIVE_GIANT</literal> option causes Giant to be included
       in the set of mutexes adaptively spun on.  That is, when a thread
       wants to lock the Giant mutex, but it is already locked by a thread
       on another CPU, the first thread will keep running and wait for the
       lock to be released.  Normally, the thread would instead go back to
       sleep and wait for its next chance to run.  If you are not sure,
       leave this in.</para>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>SMP</secondary>
     </indexterm>
     <programlisting>device          apic               # I/O APIC</programlisting>
 
     <para>The apic device enables the use of the I/O APIC for interrupt
       delivery.  The apic device can be used in both UP and SMP kernels, but
       is required for SMP kernels.  Add <literal>options SMP</literal> to
       include support for multiple processors.</para>
 
     <programlisting>device          isa</programlisting>
 
     <para>All PCs supported by &os; have one of these.  Do not remove this,
       even if you have no ISA slots.  If you have an
       IBM PS/2 (Micro Channel Architecture) system, &os; provides only
       limited support at this time.  For more information about the
       MCA support, see
       <filename>/usr/src/sys/i386/conf/NOTES</filename>.</para>
 
     <programlisting>device          eisa</programlisting>
 
     <para>Include this if you have an EISA motherboard.  This enables
       auto-detection and configuration support for all devices on the EISA
       bus.</para>
 
     <programlisting>device          pci</programlisting>
 
     <para>Include this if you have a PCI motherboard.  This enables
       auto-detection of PCI cards and gatewaying from the PCI to ISA
       bus.</para>
 
     <programlisting>device          agp</programlisting>
 
     <para>Include this if you have an AGP card in the system.  This
       will enable support for AGP, and AGP GART for boards which
       have these features.</para>
 
     <programlisting># Floppy drives
 device          fdc</programlisting>
 
     <para>This is the floppy drive controller.</para>
 
     <programlisting># ATA and ATAPI devices
 device          ata</programlisting>
 
     <para>This driver supports all ATA and ATAPI devices.  You only need
       one <literal>device ata</literal> line for the kernel to detect all
       PCI ATA/ATAPI devices on modern machines.</para>
 
     <programlisting>device          atadisk                 # ATA disk drives</programlisting>
 
     <para>This is needed along with <literal>device ata</literal> for
       ATA disk drives.</para>
 
     <programlisting>device          ataraid                 # ATA RAID drives</programlisting>
 
     <para>This is needed along with <literal>device ata</literal> for ATA
       RAID drives.</para>
 
     <programlisting><anchor id="kernelconfig-atapi">
 device          atapicd                 # ATAPI CDROM drives</programlisting>
 
     <para>This is needed along with <literal>device ata</literal> for
       ATAPI CDROM drives.</para>
 
     <programlisting>device          atapifd                 # ATAPI floppy drives</programlisting>
 
     <para>This is needed along with <literal>device ata</literal> for
       ATAPI floppy drives.</para>
 
     <programlisting>device          atapist                 # ATAPI tape drives</programlisting>
 
     <para>This is needed along with <literal>device ata</literal> for
       ATAPI tape drives.</para>
 
     <programlisting>options         ATA_STATIC_ID           # Static device numbering</programlisting>
 
     <para>This makes the controller number static; without this,
       the device numbers are dynamically allocated.</para>
 
     <programlisting># SCSI Controllers
 device          ahb        # EISA AHA1742 family
 device          ahc        # AHA2940 and onboard AIC7xxx devices
 device          ahd        # AHA39320/29320 and onboard AIC79xx devices
 device          amd        # AMD 53C974 (Teckram DC-390(T))
 device          isp        # Qlogic family
 device          mpt        # LSI-Logic MPT-Fusion
 #device         ncr        # NCR/Symbios Logic
 device          sym        # NCR/Symbios Logic (newer chipsets)
 device          trm        # Tekram DC395U/UW/F DC315U adapters
 
 device          adv        # Advansys SCSI adapters
 device          adw        # Advansys wide SCSI adapters
 device          aha        # Adaptec 154x SCSI adapters
 device          aic        # Adaptec 15[012]x SCSI adapters, AIC-6[23]60.
 device          bt         # Buslogic/Mylex MultiMaster SCSI adapters
 
 device          ncv        # NCR 53C500
 device          nsp        # Workbit Ninja SCSI-3
 device          stg        # TMC 18C30/18C50</programlisting>
 
     <para>SCSI controllers.  Comment out any you do not have in your
       system.  If you have an IDE only system, you can remove these
       altogether.</para>
 
     <programlisting># SCSI peripherals
 device          scbus      # SCSI bus (required for SCSI)
 device          ch         # SCSI media changers
 device          da         # Direct Access (disks)
 device          sa         # Sequential Access (tape etc)
 device          cd         # CD
 device          pass       # Passthrough device (direct SCSI access)
 device          ses        # SCSI Environmental Services (and SAF-TE)</programlisting>
 
     <para>SCSI peripherals.  Again, comment out any you do not have, or if
       you have only IDE hardware, you can remove them completely.</para>
 
     <note>
       <para>The USB &man.umass.4; driver and a few other drivers use
 	the SCSI subsystem even though they are not real SCSI devices.
 	Therefore make sure not to remove SCSI support, if any such
 	drivers are included in the kernel configuration.</para>
     </note>
 
     <programlisting># RAID controllers interfaced to the SCSI subsystem
 device          amr        # AMI MegaRAID
 device          asr        # DPT SmartRAID V, VI and Adaptec SCSI RAID
 device          ciss       # Compaq Smart RAID 5*
 device          dpt        # DPT Smartcache III, IV - See NOTES for options
 device          hptmv      # Highpoint RocketRAID 182x
 device          iir        # Intel Integrated RAID
 device          ips        # IBM (Adaptec) ServeRAID
 device          mly        # Mylex AcceleRAID/eXtremeRAID
 device          twa        # 3ware 9000 series PATA/SATA RAID
 
 # RAID controllers
 device          aac        # Adaptec FSA RAID
 device          aacp       # SCSI passthrough for aac (requires CAM)
 device          ida        # Compaq Smart RAID
 device          mlx        # Mylex DAC960 family
 device          pst        # Promise Supertrak SX6000
 device          twe        # 3ware ATA RAID</programlisting>
 
     <para>Supported RAID controllers.  If you do not have any of these,
       you can comment them out or remove them.</para>
 
     <programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse
 device          atkbdc     # AT keyboard controller</programlisting>
 
     <para>The keyboard controller (<literal>atkbdc</literal>) provides I/O
       services for the AT keyboard and PS/2 style pointing devices.  This
       controller is required by the keyboard driver
       (<literal>atkbd</literal>) and the PS/2 pointing device driver
       (<literal>psm</literal>).</para>
 
     <programlisting>device          atkbd      # AT keyboard</programlisting>
 
     <para>The <literal>atkbd</literal> driver, together with
       <literal>atkbdc</literal> controller, provides access to the AT 84
       keyboard or the AT enhanced keyboard which is connected to the AT
       keyboard controller.</para>
 
     <programlisting>device          psm        # PS/2 mouse</programlisting>
 
     <para>Use this device if your mouse plugs into the PS/2 mouse
       port.</para>
 
     <programlisting>device          vga        # VGA video card driver</programlisting>
 
     <para>The video card driver.</para>
 
     <programlisting># splash screen/screen saver
 device          splash     # Splash screen and screen saver support</programlisting>
 
     <para>Splash screen at start up!  Screen savers require this
       too.  Use the line <literal>pseudo-device splash</literal> with
       &os;&nbsp;4.X.</para>
 
     <programlisting># syscons is the default console driver, resembling an SCO console
 device          sc</programlisting>
 
     <para><literal>sc</literal> is the default console driver and
       resembles a SCO console.  Since most full-screen programs access the
       console through a terminal database library like
       <filename>termcap</filename>, it should not matter whether you use
       this or <literal>vt</literal>, the <literal>VT220</literal>
       compatible console driver.  When you log in, set your
       <envar>TERM</envar> variable to <literal>scoansi</literal> if
       full-screen programs have trouble running under this console.</para>
 
     <programlisting># Enable this for the pcvt (VT220 compatible) console driver
 #device          vt
 #options         XSERVER          # support for X server on a vt console
 #options         FAT_CURSOR       # start with block cursor</programlisting>
 
     <para>This is a VT220-compatible console driver, backward compatible to
       VT100/102.  It works well on some laptops which have hardware
       incompatibilities with <literal>sc</literal>.  Also set your
       <envar>TERM</envar> variable to <literal>vt100</literal> or
       <literal>vt220</literal> when you log in.  This driver might also
       prove useful when connecting to a large number of different machines
       over the network, where <filename>termcap</filename> or
       <filename>terminfo</filename> entries for the <literal>sc</literal>
       device are often not available &mdash; <literal>vt100</literal>
       should be available on virtually any platform.</para>
 
     <indexterm>
       <primary>APM</primary>
     </indexterm>
 
     <programlisting># Power management support (see NOTES for more options)
 #device          apm</programlisting>
 
     <para>Advanced Power Management support.  Useful for laptops,
       although in &os; 5.X and above this is disabled in
       <filename>GENERIC</filename> by default.</para>
 
     <programlisting># Add suspend/resume support for the i8254.
 device           pmtimer</programlisting>
 
     <para>Timer device driver for power management events, such as APM and
       ACPI.</para>
 
     <programlisting># PCCARD (PCMCIA) support
 # PCMCIA and cardbus bridge support
 device          cbb               # cardbus (yenta) bridge
 device          pccard            # PC Card (16-bit) bus
 device          cardbus           # CardBus (32-bit) bus</programlisting>
 
     <para>PCMCIA support.  You want this if you are using a
       laptop.</para>
 
     <programlisting># Serial (COM) ports
 device          sio               # 8250, 16[45]50 based serial ports</programlisting>
 
     <para>These are the serial ports referred to as
       <devicename>COM</devicename> ports in the &ms-dos;/&windows;
       world.</para>
 
     <note>
       <para>If you have an internal modem on <devicename>COM4</devicename>
 	and a serial port at <devicename>COM2</devicename>, you will have
 	to change the IRQ of the modem to 2 (for obscure technical reasons,
 	IRQ2 = IRQ 9) in order to access it
 	from &os;.  If you have a multiport serial card, check the
 	manual page for &man.sio.4; for more information on the proper
 	values to add to your <filename>/boot/device.hints</filename>.
 	Some video cards (notably those based on
 	S3 chips) use IO addresses in the form of
 	<literal>0x*2e8</literal>, and since many cheap serial cards do
 	not fully decode the 16-bit IO address space, they clash with
 	these cards making the <devicename>COM4</devicename> port
 	practically unavailable.</para>
 
       <para>Each serial port is required to have a unique IRQ (unless you
         are using one of the multiport cards where shared interrupts are
 	supported), so the default IRQs for <devicename>COM3</devicename>
 	and <devicename>COM4</devicename> cannot be used.</para>
     </note>
 
     <programlisting># Parallel port
 device          ppc</programlisting>
 
     <para>This is the ISA-bus parallel port interface.</para>
 
     <programlisting>device          ppbus      # Parallel port bus (required)</programlisting>
 
     <para>Provides support for the parallel port bus.</para>
 
     <programlisting>device          lpt        # Printer</programlisting>
 
     <para>Support for parallel port printers.</para>
 
     <note>
       <para>All three of the above are required to enable parallel printer
 	support.</para>
     </note>
 
     <programlisting>device          plip       # TCP/IP over parallel</programlisting>
 
     <para>This is the driver for the parallel network interface.</para>
 
     <programlisting>device          ppi        # Parallel port interface device</programlisting>
 
     <para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284
       I/O.</para>
 
     <programlisting>#device         vpo        # Requires scbus and da</programlisting>
 
     <indexterm><primary>zip drive</primary></indexterm>
     <para>This is for an Iomega Zip drive.  It requires
       <literal>scbus</literal> and <literal>da</literal> support.  Best
       performance is achieved with ports in EPP 1.9 mode.</para>
 
     <programlisting>#device         puc</programlisting>
 
     <para>Uncomment this device if you have a <quote>dumb</quote> serial
       or parallel PCI card that is supported by the &man.puc.4; glue
       driver.</para>
 
     <programlisting># PCI Ethernet NICs.
 device          de         # DEC/Intel DC21x4x (<quote>Tulip</quote>)
 device          em         # Intel PRO/1000 adapter Gigabit Ethernet Card
 device          ixgb       # Intel PRO/10GbE Ethernet Card
 device          txp        # 3Com 3cR990 (<quote>Typhoon</quote>)
 device          vx         # 3Com 3c590, 3c595 (<quote>Vortex</quote>)</programlisting>
 
     <para>Various PCI network card drivers.  Comment out or remove any of
       these not present in your system.</para>
 
     <programlisting># PCI Ethernet NICs that use the common MII bus controller code.
 # NOTE: Be sure to keep the 'device miibus' line in order to use these NICs!
 device          miibus     # MII bus support</programlisting>
 
     <para>MII bus support is required for some PCI 10/100 Ethernet NICs,
       namely those which use MII-compliant transceivers or implement
       transceiver control interfaces that operate like an MII.  Adding
       <literal>device miibus</literal> to the kernel config pulls in
       support for the generic miibus API and all of the PHY drivers,
       including a generic one for PHYs that are not specifically handled
       by an individual driver.</para>
 
     <programlisting>device          dc         # DEC/Intel 21143 and various workalikes
 device          miibus     # MII bus support
 device          bfe        # Broadcom BCM440x 10/100 Ethernet
 device          bge        # Broadcom BCM570xx Gigabit Ethernet
 device          dc         # DEC/Intel 21143 and various workalikes
 device          fxp        # Intel EtherExpress PRO/100B (82557, 82558)
 device          pcn        # AMD Am79C97x PCI 10/100 (precedence over 'lnc')
 device          re         # RealTek 8139C+/8169/8169S/8110S
 device          rl         # RealTek 8129/8139
 device          sf         # Adaptec AIC-6915 (<quote>Starfire</quote>)
 device          sis        # Silicon Integrated Systems SiS 900/SiS 7016
 device          sk         # SysKonnect SK-984x & SK-982x gigabit Ethernet
 device          ste        # Sundance ST201 (D-Link DFE-550TX)
 device          ti         # Alteon Networks Tigon I/II gigabit Ethernet
 device          tl         # Texas Instruments ThunderLAN
 device          tx         # SMC EtherPower II (83c170 <quote>EPIC</quote>)
 device          vr         # VIA Rhine, Rhine II
 device          wb         # Winbond W89C840F
 device          xl         # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting>
 
     <para>Drivers that use the MII bus controller code.</para>
 
     <programlisting># ISA Ethernet NICs.  pccard NICs included.
 device          cs         # Crystal Semiconductor CS89x0 NIC
 # 'device ed' requires 'device miibus'
 device          ed         # NE[12]000, SMC Ultra, 3c503, DS8390 cards
 device          ex         # Intel EtherExpress Pro/10 and Pro/10+
 device          ep         # Etherlink III based cards
 device          fe         # Fujitsu MB8696x based cards
 device          ie         # EtherExpress 8/16, 3C507, StarLAN 10 etc.
 device          lnc        # NE2100, NE32-VL Lance Ethernet cards
 device          sn         # SMC's 9000 series of Ethernet chips
 device          xe         # Xircom pccard Ethernet
 
 # ISA devices that use the old ISA shims
 #device         le</programlisting>
 
     <para>ISA Ethernet drivers.  See
       <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename> for details
 of which cards are
       supported by which driver.</para>
 
     <programlisting># Wireless NIC cards
 device          wlan       # 802.11 support
 device          an         # Aironet 4500/4800 802.11 wireless NICs.
 device          awi        # BayStack 660 and others
 device          wi         # WaveLAN/Intersil/Symbol 802.11 wireless NICs.
 #device         wl         # Older non 802.11 Wavelan wireless NIC.</programlisting>
 
     <para>Support for various wireless cards.</para>
 
     <programlisting>device   mem           # Memory and kernel memory devices</programlisting>
 
     <para>The system memory devices.</para>
 
     <programlisting>device   io            # I/O device</programlisting>
 
     <para>This option allows a process to gain I/O privileges. This is
       useful in order to write userland programs that can handle hardware
       directly.  This is required to run the X Window system.</para>
 
     <programlisting>device   random        # Entropy device</programlisting>
 
     <para>Cryptographically secure random number generator.</para>
 
     <programlisting>device   ether         # Ethernet support</programlisting>
 
     <para><literal>ether</literal> is only needed if you have an Ethernet
       card.  It includes generic Ethernet protocol code.  Under
       &os;&nbsp;4.X use the line <literal>pseudo-device
       ether</literal>.</para>
 
     <programlisting>device   sl            # Kernel SLIP</programlisting>
 
     <para><literal>sl</literal> is for SLIP support.  This has been almost
       entirely supplanted by PPP, which is easier to set up, better suited
       for modem-to-modem connection, and more powerful.
       With &os;&nbsp;4.X use the line <literal>pseudo-device
       sl</literal>.</para>
 
     <programlisting>device   ppp           # Kernel PPP</programlisting>
 
     <para>This is for kernel PPP support for dial-up connections.  There
       is also a version of PPP implemented as a userland application that
       uses <literal>tun</literal> and offers more flexibility and features
       such as demand dialing.
       With &os;&nbsp;4.X use the line
       <literal>pseudo-device ppp</literal>.</para>
 
     <programlisting>device   tun           # Packet tunnel.</programlisting>
 
     <para>This is used by the userland PPP software.
       See
       the <link linkend="userppp">PPP</link> section of this book for more
       information.  With &os;&nbsp;4.X use the line <literal>pseudo-device
       tun</literal>.</para>
 
     <programlisting><anchor id="kernelconfig-ptys">
 device   pty           # Pseudo-ttys (telnet etc)</programlisting>
 
     <para>This is a <quote>pseudo-terminal</quote> or simulated login port.
       It is used by incoming <command>telnet</command> and
       <command>rlogin</command> sessions,
       <application>xterm</application>, and some other applications such
       as <application>Emacs</application>.</para>
 
     <note><para>Under &os;&nbsp;4.X, you
       have to use the line <literal>pseudo-device pty
       <replaceable>number</replaceable></literal>.  The
       <replaceable>number</replaceable> after <literal>pty</literal>
       indicates the number of
       <literal>pty</literal>s to create.  If you need more than the
       default of 16 simultaneous <application>xterm</application> windows
       and/or remote logins, be sure to increase this number accordingly,
       up to a maximum of 256.</para></note>
 
     <programlisting>device   md            # Memory <quote>disks</quote></programlisting>
 
     <para>Memory disk pseudo-devices.  With &os;&nbsp;4.X use the
       line <literal>pseudo-device md</literal>.</para>
 
     <programlisting>device   gif           # IPv6 and IPv4 tunneling</programlisting>
 
     <para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling,
       IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.  Beginning with
       &os;&nbsp;4.4 the <literal>gif</literal> device is
       <quote>auto-cloning</quote>, and you should use the line
       <literal>pseudo-device gif</literal>.
       Earlier versions of &os;&nbsp;4.X require a number, for example
       <literal>pseudo-device gif 4</literal>.</para>
 
     <programlisting>device   faith         # IPv6-to-IPv4 relaying (translation)</programlisting>
 
     <para>This pseudo-device captures packets that are sent to it and
       diverts them to the IPv4/IPv6 translation daemon.  With
       &os;&nbsp;4.X use the line
       <literal>pseudo-device faith 1</literal>.</para>
 
     <programlisting># The `bpf' device enables the Berkeley Packet Filter.
 # Be aware of the administrative consequences of enabling this!
 device   bpf           # Berkeley packet filter</programlisting>
 
     <para>This is the Berkeley Packet Filter.  This pseudo-device allows
       network interfaces to be placed in promiscuous mode, capturing every
       packet on a broadcast network (e.g., an Ethernet).  These packets
       can be captured to disk and or examined with the &man.tcpdump.1;
       program.  With &os;&nbsp;4.X use the line
       <literal>pseudo-device bpf</literal>.</para>
 
     <note>
       <para>The &man.bpf.4; device is also used by
 	&man.dhclient.8; to obtain the IP address of the default router
 	(gateway) and so on.  If you use DHCP, leave this
 	uncommented.</para>
     </note>
 
     <programlisting># USB support
 device          uhci          # UHCI PCI-&gt;USB interface
 device          ohci          # OHCI PCI-&gt;USB interface
 device          usb           # USB Bus (required)
 #device         udbp          # USB Double Bulk Pipe devices
 device          ugen          # Generic
 device          uhid          # <quote>Human Interface Devices</quote>
 device          ukbd          # Keyboard
 device          ulpt          # Printer
 device          umass         # Disks/Mass storage - Requires scbus and da
 device          ums           # Mouse
 device          urio          # Diamond Rio 500 MP3 player
 device          uscanner      # Scanners
 # USB Ethernet, requires mii
 device          aue           # ADMtek USB Ethernet
 device          axe           # ASIX Electronics USB Ethernet
 device          cue           # CATC USB Ethernet
 device          kue           # Kawasaki LSI USB Ethernet
 device          rue           # RealTek RTL8150 USB Ethernet</programlisting>
 
     <para>Support for various USB devices.</para>
 
     <programlisting># FireWire support
 device          firewire      # FireWire bus code
 device          sbp           # SCSI over FireWire (Requires scbus and da)
 device          fwe           # Ethernet over FireWire (non-standard!)</programlisting>
 
     <para>Support for various Firewire devices.</para>
 
     <para>For more information and additional devices supported by
       &os;, see
       <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename>.</para>
 
       <sect2>
         <title>Large Memory Configurations (<acronym>PAE</acronym>)</title>
 	<indexterm>
-	  <primary>
-	    Physical Address Extensions (<acronym>PAE</acronym>)
-	  </primary>
-	  <secondary>
-	    Large Memory Configurations
-	  </secondary>
+	  <primary>Physical Address Extensions
+	    (<acronym>PAE</acronym>)</primary>
+	  <secondary>large memory</secondary>
 	</indexterm>
 
 	<para>Large memory configuration machines require access to
 	  more than the 4 gigabyte limit on User+Kernel Virtual
 	  Address (<acronym>KVA</acronym>) space.  Due to this
 	  limitation, Intel added support for 36-bit physical address
 	  space access in the &pentium; Pro and later line of CPUs.</para>
 	
 	<para>The Physical Address Extension (<acronym>PAE</acronym>)
 	  capability of the &intel; &pentium; Pro and later CPUs
 	  allows memory configurations of up to 64 gigabytes.
 	  &os; provides support for this capability via the
 	  <option>PAE</option> kernel configuration option, available
 	  in the 4.X series of &os; beginning with 4.9-RELEASE and
 	  in the 5.X series of &os; beginning with 5.1-RELEASE.  Due to
 	  the limitations of the Intel memory architecture, no distinction
 	  is made for memory above or below 4 gigabytes.  Memory allocated
 	  above 4 gigabytes is simply added to the pool of available
 	  memory.</para>
 
 	<para>To enable <acronym>PAE</acronym> support in the kernel,
 	  simply add the following line to your kernel configuration
 	  file:</para>
 	
 	<programlisting>options		    PAE</programlisting>
 
 	<note>
 	  <para>The <acronym>PAE</acronym> support in &os; is only
 	    available for &intel; IA-32 processors.  It should also be
 	    noted, that the <acronym>PAE</acronym> support in &os; has
 	    not received wide testing, and should be considered beta
 	    quality compared to other stable features of &os;.</para>
 	</note>
 
 	<para><acronym>PAE</acronym> support in &os; has a few limitations:</para>
 	
 	<itemizedlist>
 	  <listitem>
 	    <para>A process is not able to access more than 4
 	      gigabytes of VM space.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><acronym>KLD</acronym> modules cannot be loaded into
 	      a <acronym>PAE</acronym> enabled kernel, due to the
 	      differences in the build framework of a module and the
 	      kernel.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Device drivers that do not use the &man.bus.dma.9;
 	      interface will cause data corruption in a
 	      <acronym>PAE</acronym> enabled kernel and are not
 	      recommended for use.  For this reason, the
 	      <filename>PAE</filename> kernel
 	      configuration file is provided in &os; 5.X, which
 	      excludes all drivers not known to work in a <acronym>PAE</acronym> enabled
 	      kernel.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Some system tunables determine memory resource usage
 	      by the amount of available physical memory.  Such
 	      tunables can unnecessarily over-allocate due to the
 	      large memory nature of a <acronym>PAE</acronym> system.
 	      One such example is the <option>kern.maxvnodes</option>
 	      sysctl, which controls the maximum number of vnodes allowed
 	      in the kernel.  It is advised to adjust this and other
 	      such tunables to a reasonable value.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>It might be necessary to increase the kernel virtual
 	      address (<acronym>KVA</acronym>) space or to reduce the
 	      amount of specific kernel resource that is heavily used
 	      (see above) in order to avoid <acronym>KVA</acronym>
 	      exhaustion.  The <option>KVA_PAGES</option> kernel option
 	      can be used for increasing the
 	      <acronym>KVA</acronym> space.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>For performance and stability concerns, it is advised to
 	  consult the &man.tuning.7; manual page.  The &man.pae.4;
 	  manual page contains up-to-date information on &os;'s
 	  <acronym>PAE</acronym> support.</para>
     </sect2>
   </sect1>
 
   <sect1 id="kernelconfig-nodes">
     <title>Making Device Nodes</title>
 
     <indexterm><primary>device nodes</primary></indexterm>
     <indexterm>
       <primary><command>MAKEDEV</command></primary>
     </indexterm>
 
     <para><emphasis>If you are running &os;&nbsp;5.0 or later
       you can safely skip this section.  These versions use
       &man.devfs.5; to allocate device nodes transparently for
       the user.</emphasis></para>
 
     <para>Almost every device in the kernel has a corresponding
       <quote>node</quote> entry in the <filename>/dev</filename> directory.
       These nodes look like regular files, but are actually special
       entries into the kernel which programs use to access the device.
       The shell script <filename>/dev/MAKEDEV</filename>, which is
       executed when you first install the operating system, creates
       nearly all of the device nodes supported.  However, it does not
       create <emphasis>all</emphasis> of them, so when you add support for
       a new device, it pays to make sure that the appropriate entries are
       in this directory, and if not, add them.  Here is a simple
       example:</para>
 
     <para>Suppose you add the IDE CD-ROM support to the kernel.  The line
       to add is:</para>
 
     <programlisting>device acd0</programlisting>
 
     <para>This means that you should look for some entries that start with
       <filename>acd0</filename> in the <filename>/dev</filename>
       directory, possibly followed by a letter, such as
       <literal>c</literal>, or preceded by the letter
       <literal>r</literal>, which means a <quote>raw</quote> device.  It
       turns out that those files are not there, so you must change to the
       <filename>/dev</filename> directory and type:</para>
 
     <indexterm>
       <primary><command>MAKEDEV</command></primary></indexterm>
     <screen>&prompt.root; <userinput>sh MAKEDEV acd0</userinput></screen>
 
     <para>When this script finishes, you will find that there are now
       <filename>acd0c</filename> and <filename>racd0c</filename> entries
       in <filename>/dev</filename> so you know that it executed
       correctly.</para>
 
     <para>For sound cards, the following command creates the appropriate
       entries:</para>
 
     <screen>&prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen>
 
     <note>
       <para>When creating device nodes for devices such as sound cards, if
 	other people have access to your machine, it may be desirable to
 	protect the devices from outside access by adding them to the
 	<filename>/etc/fbtab</filename> file.  See &man.fbtab.5; for more
 	information.</para>
     </note>
 
     <para>Follow this simple procedure for any other
       non-<filename>GENERIC</filename>  devices which do not have
       entries.</para>
 
     <note>
       <para>All SCSI controllers use the same set of
 	<filename>/dev</filename> entries, so you do not need to create
 	these.  Also, network cards and SLIP/PPP pseudo-devices do not
 	have entries in <filename>/dev</filename> at all, so you do not
 	have to worry about these either.</para>
     </note>
   </sect1>
 
   <sect1 id="kernelconfig-trouble">
     <title>If Something Goes Wrong</title>
 
     <para>There are five categories of trouble that can occur when
       building a custom kernel.  They are:</para>
 
     <variablelist>
       <varlistentry>
 	<term><command>config</command> fails:</term>
 
 	<listitem>
 	  <para>If the &man.config.8; command fails when you
 	    give it your kernel description, you have probably made a
 	    simple error somewhere.  Fortunately,
 	    &man.config.8; will print the line number that it
 	    had trouble with, so that you can quickly locate the line
 	    containing the error.  For example, if you see:</para>
 
 	  <screen>config: line 17: syntax error</screen>
 
 	  <para>Make sure the
 	    keyword is typed correctly by comparing it to the
 	    <filename>GENERIC</filename> kernel or another
 	    reference.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>make</command> fails:</term>
 
 	<listitem>
 	  <para>If the <command>make</command> command fails, it usually
 	    signals an error in your kernel description which is not severe
 	    enough for &man.config.8; to catch.  Again, look
 	    over your configuration, and if you still cannot resolve the
 	    problem, send mail to the &a.questions; with your kernel
 	    configuration, and it should be diagnosed quickly.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Installing the new kernel fails:</term>
 	
 	<listitem>
 	  <para>If the kernel compiled fine, but failed to install
 	    (the <command>make install</command> or
 	    <command>make installkernel</command> command failed),
 	    the first thing to check is if your system is running at
 	    securelevel 1 or higher (see &man.init.8;).  The kernel
 	    installation tries to remove the immutable flag from
 	    your kernel and set the immutable flag on the new one.
 	    Since securelevel 1 or higher prevents unsetting the immutable
 	    flag for any files on the system, the kernel installation needs
 	    to be performed at securelevel 0 or lower.</para>
 
 	  <para>The above only applies to &os; 4.X and earlier versions.
 	    &os; 5.X, along with later versions, does not set the
 	    immutable flag on the kernel and a failure to install a
 	    kernel probably indicates a more fundamental problem.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>The kernel does not boot:<anchor
 	  id="kernelconfig-noboot"></term>
 
 	<listitem>
 	  <para>If your new kernel does not boot, or fails to
 	    recognize your devices, do not panic!  Fortunately, &os; has
 	    an excellent mechanism for recovering from incompatible
 	    kernels.  Simply choose the kernel you want to boot from at
 	    the &os; boot loader. You can access this when the system
 	    counts down from 10 at the boot menu.  Hit any key except for the
             <keycap>Enter</keycap> key, type <command>unload</command>
             and then type
 	    <command>boot /boot/<replaceable>kernel.old</replaceable>/kernel</command>,
             or the filename of any other kernel that will boot properly.
             When reconfiguring a kernel, it is always a good idea to keep
             a kernel that is known to work on hand.</para>
 
 	  <para>After booting with a good kernel you can check over your
 	    configuration file and try to build it again.  One helpful
 	    resource is the <filename>/var/log/messages</filename> file
 	    which records, among other things, all of the kernel messages
 	    from every successful boot.  Also, the &man.dmesg.8; command
 	    will print the kernel messages from the current boot.</para>
 
 	  <note>
 	    <para>If you are having trouble building a kernel, make sure
 	      to keep a <filename>GENERIC</filename>, or some other kernel
 	      that is known to work on hand as a different name that will
 	      not get erased on the next build.  You cannot rely on
 	      <filename>kernel.old</filename> because when installing a
 	      new kernel, <filename>kernel.old</filename> is overwritten
 	      with the last installed kernel which may be non-functional.
 	      Also, as soon as possible, move the working kernel to the
 	      proper <filename class="directory">/boot/kernel</filename>
 	      location or commands such
 	      as &man.ps.1; may not work properly.  To do this, simply
 	      rename the directory containing the good kernel:</para>
 
 	    <screen>&prompt.root; <userinput>mv /boot/kernel /boot/kernel.bad</userinput>
 &prompt.root; <userinput>mv /boot/<replaceable>kernel.good</replaceable> /boot/kernel</userinput></screen>
 
 	    <para>For versions of &os; prior to 5.X, the proper command to
 	      <quote>unlock</quote> the kernel file that
 	      <command>make</command> installs (in order to move another
 	      kernel back permanently) is:</para>
 
 	    <screen>&prompt.root; <userinput>chflags noschg /kernel</userinput></screen>
 
 	    <para>If you find you cannot do this, you are probably running
 	      at a &man.securelevel.8; greater than zero.  Edit
 	      <literal>kern_securelevel</literal> in
 	      <filename>/etc/rc.conf</filename> and set it to
 	      <literal>-1</literal>, then reboot.  You can change it back
 	      to its previous setting when you are happy with your new
 	      kernel.</para>
 
 	    <para>And, if you want to <quote>lock</quote> your new kernel
 	      into place, or any file for that matter, so that it cannot
 	      be moved or tampered with:</para>
 
 	    <screen>&prompt.root; <userinput>chflags schg /kernel</userinput></screen>
 	  </note>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>The kernel works, but &man.ps.1; does not work
 	  any more:</term>
 
 	<listitem>
 	  <para>If you have installed a different version of the kernel
 	    from the one that the system utilities have been built with,
 	    for example, a 5.X kernel on a 4.X system, many system-status
 	    commands like &man.ps.1; and &man.vmstat.8; will not work any
 	    more.  You should <link linkend="makeworld">recompile and install
 	    a world</link> built with the same version of the source tree as
 	    your kernel.  This is one reason it is
 	    not normally a good idea to use a different version of the
 	    kernel from the rest of the operating system.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
index 5909bf1bf6..1e83eeb79f 100644
--- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
@@ -1,2935 +1,2944 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <appendix id="mirrors">
   <title>Obtaining FreeBSD</title>
 
   <sect1 id="mirrors-cdrom">
     <title>CDROM and DVD Publishers</title>
 
     <sect2>
       <title>Retail Boxed Products</title>
 
       <para>FreeBSD is available as a boxed product (FreeBSD CDs,
 	additional software, and printed documentation) from several
 	retailers:</para>
 
       <itemizedlist>
 	<listitem>
 	  <address>
 	    <otheraddr>CompUSA</otheraddr>
 	    WWW: <otheraddr><ulink url="http://www.compusa.com/"></ulink></otheraddr>
 	  </address>
 	</listitem>
 
 	<listitem>
 	  <address>
 	    <otheraddr>Frys Electronics</otheraddr>
 	    WWW: <otheraddr><ulink url="http://www.frys.com/"></ulink></otheraddr>
 	  </address>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>CD and DVD Sets</title>
 
       <para>FreeBSD CD and DVD sets are available from many online
 	retailers:</para>
 
     <itemizedlist>
       <listitem>
         <address>
 	  <otheraddr>BSD Mall by Daemon News</otheraddr>
 	  <street>PO Box 161</street>
 	  <city>Nauvoo</city>, <state>IL</state> <postcode>62354</postcode>
 	  <country>USA</country>
 	  Phone: <phone>+1 866 273-6255</phone>
 	  Fax: <fax>+1 217 453-9956</fax>
 	  Email: <email>sales@bsdmall.com</email>
 	  WWW: <otheraddr><ulink url="http://www.bsdmall.com/freebsd1.html"></ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
         <address>
 	  <otheraddr>BSD-Systems</otheraddr>
 	  Email: <email>info@bsd-systems.co.uk</email>
 	  WWW: <otheraddr><ulink url="http://www.bsd-systems.co.uk"></ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
         <address>
 	  <otheraddr>fastdiscs.com</otheraddr>
 	  <street>6 Eltham Close</street>
 	  <city>Leeds</city>, <postcode>LS6 2TY</postcode>
 	  <country>United Kingdom</country>
 	  Phone: <phone>+44 870 1995 171</phone>
 	  Email: <email>sales@fastdiscs.com</email>
 	  WWW: <otheraddr><ulink url="http://fastdiscs.com/freebsd/"></ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
         <address>
 	  <otheraddr>FreeBSD Mall, Inc.</otheraddr>
 	  <street>3623 Sanford Street</street>
 	  <city>Concord</city>, <state>CA</state>  <postcode>94520-1405</postcode>
 	  <country>USA</country>
 	  Phone: <phone>+1 925 674-0783</phone>
 	  Fax: <fax>+1 925 674-0821</fax>
 	  Email: <email>info@freebsdmall.com</email>
 	  WWW: <otheraddr><ulink url="http://www.freebsdmall.com/"></ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
         <address>
 	  <otheraddr>FreeBSD Services Ltd</otheraddr>
 	  <street>11 Lapwing Close</street>
 	  <city>Bicester</city>
 	  <postcode>OX26 6XR</postcode>
 	  <country>United Kingdom</country>
 	  WWW: <otheraddr><ulink url="http://www.freebsd-services.com/"></ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>Hinner EDV</otheraddr>
 	  <street>St. Augustinus-Str. 10</street>
 	  <postcode>D-81825</postcode> <city>M&uuml;nchen</city>
 	  <country>Germany</country>
 	  Phone: <phone>(089) 428 419</phone>
 	  WWW: <otheraddr><ulink url="http://www.hinner.de/linux/freebsd.html"></ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>Ikarios</otheraddr>
 	  <street>22-24 rue Voltaire</street>
 	  <postcode>92000</postcode> <city>Nanterre</city>
 	  <country>France</country>
 	  WWW: <otheraddr><ulink url="http://ikarios.com/form/#freebsd"></ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>JMC Software</otheraddr>
 	  <country>Ireland</country>
 	  Phone: <phone>353 1 6291282</phone>
 	  WWW: <otheraddr><ulink url="http://www.thelinuxmall.com"></ulink></otheraddr>
 	</address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>The Linux Emporium</otheraddr>
 	  <street>Hilliard House, Lester Way</street>
 	  <city>Wallingford</city>
 	  <postcode>OX10 9TA</postcode>
 	  <country>United Kingdom</country>
 	  Phone: <phone>+44 1491 837010</phone>
 	  Fax: <fax>+44 1491 837016</fax>
 	  WWW: <otheraddr><ulink url="http://www.linuxemporium.co.uk/products/freebsd/"></ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>Linux System Labs Australia</otheraddr>
 	  <street>21 Ray Drive</street>
 	  <city>Balwyn North</city>
 	  <postcode>VIC - 3104</postcode>
 	  <country>Australia</country>
 	  Phone: <phone>+61 3 9857 5918</phone>
 	  Fax: <fax>+61 3 9857 8974</fax>
 	  WWW: <otheraddr><ulink url="http://www.lsl.com.au"></ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>LinuxCenter.Ru</otheraddr>
 	  <street>Galernaya Street, 55</street>
 	  <city>Saint-Petersburg</city>
 	  <postcode>190000</postcode>
 	  <country>Russia</country>
 	  Phone: <phone>+7-812-3125208</phone>
 	  Email: <email>info@linuxcenter.ru</email>
 	  WWW: <otheraddr><ulink url="http://linuxcenter.ru/freebsd"></ulink></otheraddr>
 	</address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>UNIXDVD.COM LTD</otheraddr>
 	  <street>57 Primrose Avenue</street>
 	  <city>Sheffield</city>
 	  <postcode>S5 6FS</postcode>
 	  <country>United Kingdom</country>
 	  WWW: <otheraddr><ulink url="http://www.unixdvd.com/"></ulink></otheraddr>
 	</address>
       </listitem>
 
     </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Distributors</title>
 
       <para>If you are a reseller and want to carry FreeBSD CDROM products,
 	please contact a distributor:</para>
 
       <itemizedlist>
 	<listitem>
 	  <address>
 	    <otheraddr>Cylogistics</otheraddr>
 	    <street>809B Cuesta Dr., #2149</street>
 	    <city>Mountain View</city>, <state>CA</state> <postcode>94040</postcode>
 	    <country>USA</country>
 	    Phone: <phone>+1 650 694-4949</phone>
 	    Fax: <fax>+1 650 694-4953</fax>
 	    Email: <email>sales@cylogistics.com</email>
 	    WWW: <otheraddr><ulink url="http://www.cylogistics.com/"></ulink></otheraddr>
 	  </address>
 	</listitem>
 
 	<listitem>
 	  <address>
 	    <otheraddr>FreeBSD Services Ltd</otheraddr>
 	    <street>11 Lapwing Close</street>
 	    <city>Bicester</city>
 	    <postcode>OX26 6XR</postcode>
 	    <country>United Kingdom</country>
 	    WWW: <otheraddr><ulink url="http://www.freebsd-services.com/"></ulink></otheraddr>
 	  </address>
 	</listitem>
 
         <listitem>
 	  <address>
 	    <otheraddr>Ingram Micro</otheraddr>
 	    <street>1600 E. St. Andrew Place</street>
 	    <city>Santa Ana</city>, <state>CA</state>  <postcode>92705-4926</postcode>
 	    <country>USA</country>
 	    Phone: <phone>1 (800) 456-8000</phone>
 	    WWW: <otheraddr><ulink url="http://www.ingrammicro.com/"></ulink></otheraddr>
           </address>
         </listitem>
 
 	<listitem>
 	  <address>
 	    <otheraddr>Kudzu, LLC</otheraddr>
 	    <street>7375 Washington Ave. S.</street>
 	    <city>Edina</city>, <state>MN</state> <postcode>55439</postcode>
 	    <country>USA</country>
 	    Phone: <phone>+1 952 947-0822</phone>
 	    Fax: <fax>+1 952 947-0876</fax>
 	    Email: <email>sales@kudzuenterprises.com</email>
 	  </address>
 	</listitem>
 
 	<listitem>
 	  <address>
 	    <otheraddr>LinuxCenter.Ru</otheraddr>
 	    <street>Galernaya Street, 55</street>
 	    <city>Saint-Petersburg</city>
 	    <postcode>190000</postcode>
 	    <country>Russia</country>
 	    Phone: <phone>+7-812-3125208</phone>
 	    Email: <email>info@linuxcenter.ru</email>
 	    WWW: <otheraddr><ulink url="http://linuxcenter.ru/freebsd"></ulink></otheraddr>
 	  </address>
 	</listitem>
 
 	<listitem>
 	  <address>
 	    <otheraddr>Navarre Corp</otheraddr>
 	    <street>7400 49th Ave South</street>
 	    <city>New Hope</city>, <state>MN</state> <postcode>55428</postcode>
 	    <country>USA</country>
 	    Phone: <phone>+1 763 535-8333</phone>
 	    Fax: <fax>+1 763 535-0341</fax>
 	    WWW: <otheraddr><ulink url="http://www.navarre.com/"></ulink></otheraddr>
 	  </address>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="mirrors-ftp">
     <title>FTP Sites</title>
 
     <para>The official sources for FreeBSD are available via anonymous FTP
       from a worldwide set of mirror sites.  The site
       <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"></ulink> is well
       connected and allows a large number of connections to it, but
       you are probably better off finding a <quote>closer</quote>
       mirror site (especially if you decide to set up some sort of
       mirror site).</para>
 
     <para>The <ulink
 	url="http://mirrorlist.FreeBSD.org/">FreeBSD mirror
 	sites database</ulink> is more accurate than the mirror listing in the
       Handbook, as it gets its information from the DNS rather than relying on
       static lists of hosts.</para>
 
     <para>Additionally, FreeBSD is available via anonymous FTP from the
       following mirror sites.  If you choose to obtain FreeBSD via anonymous
       FTP, please try to use a site near you.  The mirror sites listed as
       <quote>Primary Mirror Sites</quote> typically have the entire FreeBSD archive (all
       the currently available versions for each of the architectures) but
       you will probably have faster download times from a site that is
       in your country or region.  The regional sites carry the most recent
       versions for the most popular architecture(s) but might not carry
       the entire FreeBSD archive.  All sites provide access via anonymous
       FTP but some sites also provide access via other methods.  The access
       methods available for each site are provided in parentheses
       after the hostname.</para>
 
     &chap.mirrors.ftp.inc;
   </sect1>
 
     <sect1 id="anoncvs">
       <title>Anonymous CVS</title>
 
       <sect2>
 	<title><anchor id="anoncvs-intro">Introduction</title>
 
+	<indexterm>
+	  <primary>CVS</primary>
+	  <secondary>anonymous</secondary>
+	</indexterm>
+
 	<para>Anonymous CVS (or, as it is otherwise known,
 	  <emphasis>anoncvs</emphasis>) is a feature provided by the CVS
 	  utilities bundled with FreeBSD for synchronizing with a remote
 	  CVS repository.  Among other things, it allows users of FreeBSD
 	  to perform, with no special privileges, read-only CVS operations
 	  against one of the FreeBSD project's official anoncvs servers.
 	  To use it, one simply sets the <envar>CVSROOT</envar>
 	  environment variable to point at the appropriate anoncvs server,
 	  provides the well-known password <quote>anoncvs</quote> with the
 	  <command>cvs login</command> command, and then uses the
 	  &man.cvs.1; command to access it like any local
 	  repository.</para>
 
 	<note>
 	  <para>The <command>cvs login</command> command, stores the passwords
 	    that are used for authenticating to the CVS server in a file
 	    called <filename>.cvspass</filename> in your
 	    <envar>HOME</envar> directory.  If this file does not exist,
 	    you might get an error when trying to use <command>cvs
 	    login</command> for the first time.  Just make an empty
 	    <filename>.cvspass</filename> file, and retry to login.</para>
 	</note>
 
 	<para>While it can also be said that the <link
 	  linkend="cvsup">CVSup</link> and <emphasis>anoncvs</emphasis>
 	  services both perform essentially the same function, there are
 	  various trade-offs which can influence the user's choice of
 	  synchronization methods.  In a nutshell,
 	  <application>CVSup</application> is much more efficient in its
 	  usage of network resources and is by far the most technically
 	  sophisticated of the two, but at a price.  To use
 	  <application>CVSup</application>, a special client must first be
 	  installed and configured before any bits can be grabbed, and
 	  then only in the fairly large chunks which
 	  <application>CVSup</application> calls
 	  <emphasis>collections</emphasis>.</para>
 
 	<para><application>Anoncvs</application>, by contrast, can be used
 	  to examine anything from an individual file to a specific
 	  program (like <command>ls</command> or <command>grep</command>)
 	  by referencing the CVS module name.  Of course,
 	  <application>anoncvs</application> is also only good for
 	  read-only operations on the CVS repository, so if it is your
 	  intention to support local development in one repository shared
 	  with the FreeBSD project bits then
 	  <application>CVSup</application> is really your only
 	  option.</para>
       </sect2>
 
       <sect2>
 	<title><anchor id="anoncvs-usage">Using Anonymous CVS</title>
 
 	<para>Configuring &man.cvs.1; to use an Anonymous CVS repository
 	  is a simple matter of setting the <envar>CVSROOT</envar>
 	  environment variable to point to one of the FreeBSD project's
 	  <emphasis>anoncvs</emphasis> servers.  At the time of this
 	  writing, the following servers are available:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><emphasis>Austria</emphasis>:
 	      :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs
 	      (Use <command>cvs login</command> and enter any
 	      password when prompted.)</para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>France</emphasis>:
 	      :pserver:anoncvs@anoncvs.fr.FreeBSD.org:/home/ncvs
 	      (pserver (password <quote>anoncvs</quote>), ssh (no password))
 	    </para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>Germany</emphasis>:
 	      :pserver:anoncvs@anoncvs.de.FreeBSD.org:/home/ncvs
 	      (Use <command>cvs login</command> and enter the password
 	      <quote>anoncvs</quote> when prompted.)</para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>Germany</emphasis>:
 	      :pserver:anoncvs@anoncvs2.de.FreeBSD.org:/home/ncvs
 	      (rsh, pserver, ssh, ssh/2022)
 	      </para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>Japan</emphasis>:
 	      :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs
 	      (Use <command>cvs login</command> and enter the password
 	      <quote>anoncvs</quote> when prompted.)</para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>Sweden</emphasis>:
 	      freebsdanoncvs@anoncvs.se.FreeBSD.org:/home/ncvs
 	      (ssh only - no password)</para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>USA</emphasis>:
 	      freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs
 	      (ssh only - no password)</para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>USA</emphasis>:
 	      anoncvs@anoncvs1.FreeBSD.org:/home/ncvs (ssh only - no
 	      password)</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>Since CVS allows one to <quote>check out</quote> virtually
 	  any version of the FreeBSD sources that ever existed (or, in
 	  some cases, will exist), you need to be
 	  familiar with the revision (<option>-r</option>) flag to
 	  &man.cvs.1; and what some of the permissible values for it in
 	  the FreeBSD Project repository are.</para>
 
 	<para>There are two kinds of tags, revision tags and branch tags.
 	  A revision tag refers to a specific revision.  Its meaning stays
 	  the same from day to day.  A branch tag, on the other hand,
 	  refers to the latest revision on a given line of development, at
 	  any given time.  Because a branch tag does not refer to a
 	  specific revision, it may mean something different tomorrow than
 	  it means today.</para>
 
 	<para><xref linkend="cvs-tags"> contains revision tags that users
  	  might be interested
 	  in.  Again, none of these are valid for the ports collection
 	  since the ports collection does not have multiple
 	  revisions.</para>
 
 	<para>When you specify a branch tag, you normally receive the
 	  latest versions of the files on that line of development.  If
 	  you wish to receive some past version, you can do so by
 	  specifying a date with the <option>-D date</option> flag.
 	  See the &man.cvs.1; manual page for more details.</para>
       </sect2>
 
       <sect2>
 	<title>Examples</title>
 
 	<para>While it really is recommended that you read the manual page
 	  for &man.cvs.1; thoroughly before doing anything, here are some
 	  quick examples which essentially show how to use Anonymous
 	  CVS:</para>
 
 	<example>
 	  <title>Checking Out Something from -CURRENT (&man.ls.1;) and
 	    Deleting It Again:</title>
 
 	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
 &prompt.user; <userinput>cvs login</userinput>
 <emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
 &prompt.user; <userinput>cvs co ls</userinput>
 &prompt.user; <userinput>cvs release -d ls</userinput>
 &prompt.user; <userinput>cvs logout</userinput>
 	  </screen>
 	</example>
 
 	<example>
 	  <title>Using SSH to check out the <filename>src/</filename>
 	    tree:</title>
 	  <screen>&prompt.user; <userinput>cvs -d freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs co src</userinput>
 The authenticity of host 'anoncvs.freebsd.org (128.46.156.46)' can't be established.
 DSA key fingerprint is 52:02:38:1a:2f:a8:71:d3:f5:83:93:8d:aa:00:6f:65.
 Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput>
 Warning: Permanently added 'anoncvs.freebsd.org' (DSA) to the list of known hosts.</screen>
 	</example>
 
 	<example>
 	  <title>Checking Out the Version of &man.ls.1; in the 3.X-STABLE
 	    Branch:</title>
 	    
 	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
 &prompt.user; <userinput>cvs login</userinput>
 <emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
 &prompt.user; <userinput>cvs co -rRELENG_3 ls</userinput>
 &prompt.user; <userinput>cvs release -d ls</userinput>
 &prompt.user; <userinput>cvs logout</userinput>
 	  </screen>
 	</example>
 
 	<example>
 	  <title>Creating a List of Changes (as Unified Diffs) to &man.ls.1;</title>
 
 	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
 &prompt.user; <userinput>cvs login</userinput>
 <emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
 &prompt.user; <userinput>cvs rdiff -u -rRELENG_3_0_0_RELEASE -rRELENG_3_4_0_RELEASE ls</userinput>
 &prompt.user; <userinput>cvs logout</userinput>
 	  </screen>
 	</example>
 
 	<example>
 	  <title>Finding Out What Other Module Names Can Be Used:</title>
 
 	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
 &prompt.user; <userinput>cvs login</userinput>
 <emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
 &prompt.user; <userinput>cvs co modules</userinput>
 &prompt.user; <userinput>more modules/modules</userinput>
 &prompt.user; <userinput>cvs release -d modules</userinput>
 &prompt.user; <userinput>cvs logout</userinput>
 	  </screen>
 	</example>
       </sect2>
 
       <sect2>
 	<title>Other Resources</title>
 
 	<para>The following additional resources may be helpful in learning
 	  CVS:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><ulink 
 		url="http://www.csc.calpoly.edu/~dbutler/tutorials/winter96/cvs/">CVS Tutorial</ulink> from Cal Poly.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.cvshome.org/">CVS Home</ulink>,
 	      the CVS development and support community.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink
 		url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVSweb</ulink> is
 	      the FreeBSD Project web interface for CVS.</para>
 	  </listitem>
 	</itemizedlist>
       </sect2>
     </sect1>
     
     
   <sect1 id="ctm">
     <title>Using CTM</title>
 
+      <indexterm>
+	<primary>CTM</primary>
+      </indexterm>
+
       <para><application>CTM</application> is a method for keeping a
 	remote directory tree in sync with a central one.  It has been
 	developed for usage with FreeBSD's source trees, though other
 	people may find it useful for other purposes as time goes by.
 	Little, if any, documentation currently exists at this time on the
 	process of creating deltas, so contact the &a.ctm-users.name; mailing list for more
 	information and if you wish to use <application>CTM</application>
 	for other things.</para>
 
       <sect2>
 	<title>Why Should I Use <application>CTM</application>?</title>
 
 	<para><application>CTM</application> will give you a local copy of
 	  the FreeBSD source trees.  There are a number of
 	  <quote>flavors</quote> of the tree available.  Whether you wish
 	  to track the entire CVS tree or just one of the branches,
 	  <application>CTM</application> can provide you the information.
 	  If you are an active developer on FreeBSD, but have lousy or
 	  non-existent TCP/IP connectivity, or simply wish to have the
 	  changes automatically sent to you,
 	  <application>CTM</application> was made for you.  You will need
 	  to obtain up to three deltas per day for the most  active
 	  branches.  However, you should consider having them sent by
 	  automatic email.  The sizes of the updates are always kept as
 	  small as possible.  This is typically less than 5K, with an
 	  occasional (one in ten) being 10-50K and every now and then a
 	  large 100K+ or more coming around.</para>
 
 	<para>You will also need to make yourself aware of the various
 	  caveats related to working directly from the development sources
 	  rather than a pre-packaged release.  This is particularly true
 	  if you choose the <quote>current</quote> sources.  It is
 	  recommended that you read <link linkend="current">Staying
 	  current with FreeBSD</link>.</para>
       </sect2>
 
       <sect2>
 	<title>What Do I Need to Use
 	  <application>CTM</application>?</title>
 
 	<para>You will need two things: The <application>CTM</application>
 	  program, and the initial deltas to feed it (to get up to
 	  <quote>current</quote> levels).</para>
 	    
 	<para>The <application>CTM</application> program has been part of
 	  FreeBSD ever since version 2.0 was released, and lives in
 	  <filename>/usr/src/usr.sbin/ctm</filename> if you have a copy
 	  of the source available.</para>
 
 	<para>If you are running a pre-2.0 version of FreeBSD, you can
 	  fetch the current <application>CTM</application> sources
 	  directly from:</para>
 	    
 	<para><ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/usr.sbin/ctm/"></ulink></para>
 
 	<para>The <quote>deltas</quote> you feed
 	  <application>CTM</application> can be had two ways, FTP or
 	  email.  If you have general FTP access to the Internet then the
 	  following FTP sites support access to
 	  <application>CTM</application>:</para>
 
 	<para><ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para>
 
 	<para>or see section <link
 	  linkend="mirrors-ctm">mirrors</link>.</para>
 
 	<para>FTP the relevant directory and fetch the
 	  <filename>README</filename> file, starting from there.</para>
 
 	<para>If you wish to get your deltas via email:</para>
 
 	<para>Subscribe to one of the
 	  <application>CTM</application> distribution lists.
 	  &a.ctm-cvs-cur.name; supports the entire CVS tree.
 	  &a.ctm-src-cur.name; supports the head of the development
 	  branch.  &a.ctm-src-4.name; supports the 4.X release
 	  branch, etc..  (If you do not know how to subscribe yourself
 	  to a list, click on the list name above or go to
 	  &a.mailman.lists.link; and click on the list that you
 	  wish to subscribe to.  The list page should contain all of
 	  the necessary subscription instructions.)</para>
 
 	<para>When you begin receiving your <application>CTM</application>
 	  updates in the mail, you may use the
 	  <command>ctm_rmail</command> program to unpack and apply them.
 	  You can actually use the <command>ctm_rmail</command> program
 	  directly from a entry in <filename>/etc/aliases</filename> if
 	  you want to have the process run in a fully automated fashion.
 	  Check the <command>ctm_rmail</command> manual page for more
 	  details.</para>
 
 	<note>
 	  <para>No matter what method you use to get the
 	    <application>CTM</application> deltas, you should subscribe to
 	    the &a.ctm-announce.name; mailing list.  In
 	    the future, this will be the only place where announcements
 	    concerning the operations of the
 	    <application>CTM</application> system will be posted.  Click
 	    on the list name above and follow the instructions
 	    to subscribe to the
 	    list.</para>
 	</note>
       </sect2>
 
       <sect2>
 	<title>Using <application>CTM</application> for the First
 	  Time</title>
 
 	<para>Before you can start using <application>CTM</application>
 	  deltas, you will need to get to a starting point for the deltas
 	  produced subsequently to it.</para>
 
 	<para>First you should determine what you already have.  Everyone
 	  can start from an <quote>empty</quote> directory.  You must use
 	  an initial <quote>Empty</quote> delta to start off your
 	  <application>CTM</application> supported tree.  At some point it
 	  is intended that one of these <quote>started</quote> deltas be
 	  distributed on the CD for your convenience, however, this does
 	  not currently happen.</para>
 
 	<para>Since the trees are many tens of megabytes, you should
 	  prefer to start from something already at hand.  If you have a
 	  -RELEASE CD, you can copy or extract an initial source from it.
 	  This will save a significant transfer of data.</para>
 
 	<para>You can recognize these <quote>starter</quote> deltas by the
 	  <literal>X</literal> appended to the number
 	  (<filename>src-cur.3210XEmpty.gz</filename> for instance).  The
 	  designation following the <literal>X</literal> corresponds to
 	  the origin of your initial <quote>seed</quote>.
 	  <filename>Empty</filename> is an empty directory.  As a rule a
 	  base transition from <literal>Empty</literal> is produced
 	  every 100 deltas.  By the way, they are large! 70 to 80
 	  Megabytes of <command>gzip</command>'d data is common for the
 	  <filename>XEmpty</filename> deltas.</para>
 
 	<para>Once you have picked a base delta to start from, you will also
 	  need all deltas with higher numbers following it.</para>
       </sect2>
 
       <sect2>
 	<title>Using <application>CTM</application> in Your Daily
 	  Life</title>
 
 	<para>To apply the deltas, simply say:</para>
 
 	<screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput>
 &prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen>
 
 	<para><application>CTM</application> understands deltas which have
 	  been put through <command>gzip</command>, so you do not need to
 	  <command>gunzip</command> them first, this saves disk space.</para>
 
 	<para>Unless it feels very secure about the entire process,
 	  <application>CTM</application> will not touch your tree.  To
 	  verify a delta you can also use the <option>-c</option> flag and
 	  <application>CTM</application> will not actually touch your
 	  tree; it will merely verify the integrity of the delta and see
 	  if it would apply cleanly to your current tree.</para>
 
 	<para>There are other options to <application>CTM</application>
 	  as well, see the manual pages or look in the sources for more
 	  information.</para>
 
 	<para>That is really all there is to it.  Every time you get a new
 	  delta, just run it through <application>CTM</application> to
 	  keep your sources up to date.</para>
 
 	<para>Do not remove the deltas if they are hard to download again.
 	  You just might want to keep them around in case something bad
 	  happens.  Even if you only have floppy disks, consider using
 	  <command>fdwrite</command> to make a copy.</para>
       </sect2>
 
       <sect2>
 	<title>Keeping Your Local Changes</title>
 
 	<para>As a developer one would like to experiment with and change
 	  files in the source tree.  <application>CTM</application>
 	  supports local modifications in a limited way: before checking
 	  for the presence of a file <filename>foo</filename>, it first
 	  looks for <filename>foo.ctm</filename>.  If this file exists,
 	  <application>CTM</application> will operate on it instead of
 	  <filename>foo</filename>.</para>
 
 	<para>This behavior gives us a simple way to maintain local
 	  changes:  simply copy the files you plan to modify to the
 	  corresponding file names with a <filename>.ctm</filename>
 	  suffix.  Then you can freely hack  the code, while <application>CTM</application> keeps the
 	  <filename>.ctm</filename> file up-to-date.</para>
       </sect2>
 
       <sect2>
 	<title>Other Interesting <application>CTM</application> Options</title>
 
 	<sect3>
 	  <title>Finding Out Exactly What Would Be Touched by an
 	    Update</title>
 
 	  <para>You can determine the list of changes that
 	    <application>CTM</application> will make on your source
 	    repository using the <option>-l</option> option to
 	    <application>CTM</application>.</para>
 
 	  <para>This is useful if you would like to keep logs of the
 	    changes, pre- or post- process the modified files in any
 	    manner, or just are feeling a tad paranoid.</para>
 	</sect3>
 
 	<sect3>
 	  <title>Making Backups Before Updating</title>
 
 	  <para>Sometimes you may want to backup all the files that would
 	    be changed by a <application>CTM</application> update.</para>
 
 	  <para>Specifying the <option>-B backup-file</option> option
 	    causes <application>CTM</application> to backup all files that
 	    would be touched by a given <application>CTM</application>
 	    delta to <filename>backup-file</filename>.</para>
 	</sect3>
 
 	<sect3>
 	  <title>Restricting the Files Touched by an Update</title>
 
 	  <para>Sometimes you would be interested in restricting the scope
 	    of a given <application>CTM</application> update, or may be
 	    interested in extracting just a few files from a sequence of
 	    deltas.</para>
 
 	  <para>You can control the list of files that
 	    <application>CTM</application> would operate on by specifying
 	    filtering regular expressions using the <option>-e</option>
 	    and <option>-x</option> options.</para>
 
 	  <para>For example, to extract an up-to-date copy of
 	    <filename>lib/libc/Makefile</filename> from your collection of
 	    saved <application>CTM</application> deltas, run the commands:</para>
 
 	  <screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput>
 &prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen>
 
 	  <para>For every file specified in a
 	    <application>CTM</application> delta, the <option>-e</option>
 	    and <option>-x</option> options are applied in the order given
 	    on the command line.  The file is processed by
 	    <application>CTM</application> only if it is marked as
 	    eligible after all the <option>-e</option> and
 	    <option>-x</option> options are applied to it.</para>
 	</sect3>
       </sect2>
 
       <sect2>
 	<title>Future Plans for <application>CTM</application></title>
 
 	<para>Tons of them:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>Use some kind of authentication into the <application>CTM</application> system, so
 	      as to allow detection of spoofed <application>CTM</application> updates.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Clean up the options to <application>CTM</application>,
 	      they became confusing and counter intuitive.</para>
 	  </listitem>
 	</itemizedlist>
       </sect2>
 
       <sect2>
 	<title>Miscellaneous Stuff</title>
 
 	<para>There is a sequence of deltas for the
 	  <literal>ports</literal> collection too, but interest has not
 	  been all that high yet.</para>
       </sect2>
 
     <sect2 id="mirrors-ctm">
       <title>CTM Mirrors</title>
       
     <para><link linkend="ctm">CTM</link>/FreeBSD is available via anonymous
       FTP from the following mirror sites.  If you choose to obtain <application>CTM</application> via
       anonymous FTP, please try to use a site near you.</para>
 
     <para>In case of problems, please contact the &a.ctm-users.name;
       mailing list.</para>
 
     <variablelist>
       <varlistentry>
 	<term>California, Bay Area, official source</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>South Africa, backup server for old deltas</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink url="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Taiwan/R.O.C.</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink url="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink url="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink url="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>If you did not find a mirror near to you or the mirror is
       incomplete, try to use a search engine such as
       <ulink url="http://www.alltheweb.com/">alltheweb</ulink>.</para>
   </sect2></sect1>
 
   <sect1 id="cvsup">
     <title>Using CVSup</title>
     
     <sect2 id="cvsup-intro">
       <title>Introduction</title>
       
       <para><application>CVSup</application> is a software package for
 	distributing and updating source trees from a master CVS
 	repository on a remote server host.  The FreeBSD sources are
 	maintained in a CVS repository on a central development machine
 	in California.  With <application>CVSup</application>, FreeBSD
 	users can easily keep their own source trees up to date.</para>
       
       <para><application>CVSup</application> uses the so-called
 	<emphasis>pull</emphasis> model of updating.  Under the pull
 	model, each client asks the server for updates, if and when they
 	are wanted.  The server waits passively for update requests from
 	its clients.  Thus all updates are instigated by the client.
 	The server never sends unsolicited updates.  Users must either
 	run the <application>CVSup</application> client manually to get
 	an update, or they must set up a <command>cron</command> job to
 	run it automatically on a regular basis.</para>
       
       <para>The term <application>CVSup</application>, capitalized just
 	so, refers to the entire software package.  Its main components
 	are the client <command>cvsup</command> which runs on each
 	user's machine, and the server <command>cvsupd</command> which
 	runs at each of the FreeBSD mirror sites.</para>
 
       <para>As you read the FreeBSD documentation and mailing lists, you
 	may see references to <application>sup</application>.
 	<application>Sup</application> was the predecessor of
 	<application>CVSup</application>, and it served a similar
 	purpose.  <application>CVSup</application> is used much in the
 	same way as sup and, in fact, uses configuration files which are
 	backward-compatible with <command>sup</command>'s.
 	<application>Sup</application> is no longer used in the FreeBSD
 	project, because <application>CVSup</application> is both faster
 	and more flexible.</para>
     </sect2>
 
     <sect2 id="cvsup-install">
       <title>Installation</title>
       
       <para>The easiest way to install <application>CVSup</application>
 	is to use the precompiled <filename role="package">net/cvsup</filename> package
 	from the FreeBSD <link linkend="ports">packages collection</link>.
 	If you prefer to build <application>CVSup</application> from
 	source, you can use the <filename role="package">net/cvsup</filename>
 	port instead.  But be forewarned: the
 	<filename role="package">net/cvsup</filename> port depends on the Modula-3
 	system, which takes a substantial amount of time and
 	disk space to download and build.</para>
 
 	<note>
 	  <para>If you are going to be using
 	  <application>CVSup</application> on a machine which will not have
 	  <application>&xfree86;</application> or <application>&xorg;</application> installed, such as a server, be
 	  sure to use the port which does not include the
 	  <application>CVSup</application> <acronym>GUI</acronym>,
 	  <filename role="package">net/cvsup-without-gui</filename>.</para>
 	</note>
     </sect2>
 
     <sect2 id="cvsup-config">
       <title>CVSup Configuration</title>
       
       <para><application>CVSup</application>'s operation is controlled
 	by a configuration file called the <filename>supfile</filename>.
 	There are some sample <filename>supfiles</filename> in the
 	directory <ulink type="html"
 	  url="file://localhost/usr/share/examples/cvsup/"><filename>/usr/share/examples/cvsup/</filename></ulink>.</para>
       
       <para>The information in a <filename>supfile</filename> answers
 	the following questions for <application>CVSup</application>:</para>
       
       <itemizedlist>
 	<listitem>
 	  <para><link linkend="cvsup-config-files">Which files do you
 	      want to receive?</link></para>
 	</listitem>
 	
 	<listitem>
 	  <para><link linkend="cvsup-config-vers">Which versions of them
 	      do you want?</link></para>
 	</listitem>
 	
 	<listitem>
 	  <para><link linkend="cvsup-config-where">Where do you want to
 	      get them from?</link></para>
 	</listitem>
 	
 	<listitem>
 	  <para><link linkend="cvsup-config-dest">Where do you want to
 	      put them on your own machine?</link></para>
 	</listitem>
 	
 	<listitem>
 	  <para><link linkend="cvsup-config-status">Where do you want to
 	      put your status files?</link></para>
 	</listitem>
       </itemizedlist>
 
       <para>In the following sections, we will construct a typical
 	<filename>supfile</filename> by answering each of these
 	questions in turn.  First, we describe the overall structure of
 	a <filename>supfile</filename>.</para>
 
       <para>A <filename>supfile</filename> is a text file.  Comments
 	begin with <literal>#</literal> and extend to the end of the
 	line.  Lines that are blank and lines that contain only
 	comments are ignored.</para>
       
       <para>Each remaining line describes a set of files that the user
 	wishes to receive.  The line begins with the name of a
 	<quote>collection</quote>, a logical grouping of files defined by
 	the server. The name of the collection tells the server which
 	files you want.  After the collection name come zero or more
 	fields, separated by white space.  These fields answer the
 	questions listed above.  There are two types of fields: flag
 	fields and value fields.  A flag field consists of a keyword
 	standing alone, e.g., <literal>delete</literal> or
 	<literal>compress</literal>.  A value field also begins with a
 	keyword, but the keyword is followed without intervening white
 	space by <literal>=</literal> and a second word.  For example,
 	<literal>release=cvs</literal> is a value field.</para>
       
       <para>A <filename>supfile</filename> typically specifies more than
 	one collection to receive.  One way to structure a
 	<filename>supfile</filename> is to specify all of the relevant
 	fields explicitly for each collection.  However, that tends to
 	make the <filename>supfile</filename> lines quite long, and it
 	is inconvenient because most fields are the same for all of the
 	collections in a <filename>supfile</filename>.
 	<application>CVSup</application> provides a defaulting mechanism
 	to avoid these problems.  Lines beginning with the special
 	pseudo-collection name <literal>*default</literal> can be used
 	to set flags and values which will be used as defaults for the
 	subsequent collections in the <filename>supfile</filename>.  A
 	default value can be overridden for an individual collection, by
 	specifying a different value with the collection itself.
 	Defaults can also be changed or augmented in mid-supfile by
 	additional <literal>*default</literal> lines.</para>
 
       <para>With this background, we will now proceed to construct a
 	<filename>supfile</filename> for receiving and updating the main
 	source tree of <link
 	  linkend="current">FreeBSD-CURRENT</link>.</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><anchor id="cvsup-config-files">Which files do you want
 	    to receive?</para>
 	  
 	  <para>The files available via <application>CVSup</application>
 	    are organized into named groups called
 	    <quote>collections</quote>.  The collections that are
 	    available are described in the <link
 	      linkend="cvsup-collec">following section</link>.  In this
 	    example, we
 	    wish to receive the entire main source tree for the FreeBSD
 	    system.  There is a single large collection
 	    <literal>src-all</literal> which will give us all of that.
 	    As a first step toward constructing our
 	    <filename>supfile</filename>, we
 	    simply list the collections, one per line (in this case,
 	    only one line):</para>
 
 	  <programlisting>src-all</programlisting>
 	</listitem>
 
 	<listitem>
 	  <para><anchor id="cvsup-config-vers">Which version(s) of them
 	    do you want?</para>
 
 	  <para>With <application>CVSup</application>, you can receive
 	    virtually any version of the sources that ever existed.
 	    That is possible because the
 	    <application>cvsupd</application> server works directly from
 	    the CVS repository, which contains all of the versions.  You
 	    specify which one of them you want using the
 	    <literal>tag=</literal> and <option>date=</option> value
 	    fields.</para>
 	  
 	  <warning>
 	    <para>Be very careful to specify any <literal>tag=</literal>
 	      fields correctly.  Some tags are valid only for certain
 	      collections of files.  If you specify an incorrect or
 	      misspelled tag, <application>CVSup</application>
 	      will delete files which you probably
 	      do not want deleted.  In particular, use <emphasis>only
 	      </emphasis> <literal>tag=.</literal> for the
 	      <literal>ports-*</literal> collections.</para>
 	  </warning>
 
 	  <para>The <literal>tag=</literal> field names a symbolic tag
 	    in the repository.  There are two kinds of tags, revision
 	    tags and branch tags.  A revision tag refers to a specific
 	    revision.  Its meaning stays the same from day to day.  A
 	    branch tag, on the other hand, refers to the latest revision
 	    on a given line of development, at any given time.  Because
 	    a branch tag does not refer to a specific revision, it may
 	    mean something different tomorrow than it means
 	    today.</para>
 	  
 	  <para><xref linkend="cvs-tags"> contains branch tags that
 	    users might be interested in.  When specifying a tag in
 	    <application>CVSup</application>'s configuration file, it
 	    must be preceded with <literal>tag=</literal>
 	    (<literal>RELENG_4</literal> will become
 	    <literal>tag=RELENG_4</literal>).
 	    Keep in mind that only the <literal>tag=.</literal> is
 	    relevant for the ports collection.</para>
 
 	  <warning>
 	    <para>Be very careful to type the tag name exactly as shown.
 	      <application>CVSup</application> cannot distinguish
 	      between valid and invalid tags.  If you misspell the tag,
 	      <application>CVSup</application> will behave as though you
 	      had specified a valid tag which happens to refer to no
 	      files at all.  It will delete your existing sources in
 	      that case.</para>
 	  </warning>
 
 	  <para>When you specify a branch tag, you normally receive the
 	    latest versions of the files on that line of development.
 	    If you wish to receive some past version, you can do so by
 	    specifying a date with the <option>date=</option> value
 	    field. The &man.cvsup.1; manual page explains how to do
 	    that.</para>
 
 	  <para>For our example, we wish to receive FreeBSD-CURRENT.  We
 	    add this line at the beginning of our
 	    <filename>supfile</filename>:</para>
 	  
 	  <programlisting>*default tag=.</programlisting>
 
 	  <para>There is an important special case that comes into play
 	    if you specify neither a <literal>tag=</literal> field nor a
 	    <literal>date=</literal> field.  In that case, you receive
 	    the actual RCS files directly from the server's CVS
 	    repository, rather than receiving a particular version.
 	    Developers generally prefer this mode of operation.  By
 	    maintaining a copy of the repository itself on their
 	    systems, they gain the ability to browse the revision
 	    histories and examine past versions of files.  This gain is
 	    achieved at a large cost in terms of disk space,
 	    however.</para>
 	</listitem>
 
 	<listitem>
 	  <para><anchor id="cvsup-config-where">Where do you want to get
 	    them from?</para>
 	  
 	  <para>We use the <literal>host=</literal> field to tell
 	    <command>cvsup</command> where to obtain its updates.  Any
 	    of the <link linkend="cvsup-mirrors">CVSup mirror
 	      sites</link> will do, though you should try to select one
 	    that is close to you in cyberspace.  In this example we will
 	    use a fictional FreeBSD distribution site,
 	    <hostid role="fqdn">cvsup99.FreeBSD.org</hostid>:</para>
 
 	  <programlisting>*default host=cvsup99.FreeBSD.org</programlisting>
 	  
 	  <para>You will need to change the host to one that actually
 	    exists before running <application>CVSup</application>.
 	    On any particular run of
 	    <command>cvsup</command>, you can override the host  setting
 	    on the command line, with <option>-h
 	      <replaceable>hostname</replaceable></option>.</para>
 	</listitem>
 	
 	<listitem>
 	  <para><anchor id="cvsup-config-dest">Where do you want to put
 	    them on your own machine?</para>
 	  
 	  <para>The <literal>prefix=</literal> field tells
 	    <command>cvsup</command> where to put the files it receives.
 	    In this example, we will put the source files directly into
 	    our main source tree, <filename>/usr/src</filename>.  The
 	    <filename>src</filename> directory is already implicit in
 	    the collections we have chosen to receive, so this is the
 	    correct specification:</para>
 	  
 	  <programlisting>*default prefix=/usr</programlisting>
 	</listitem>
 
 	<listitem>
 	  <para><anchor id="cvsup-config-status">Where should
 	    <command>cvsup</command> maintain its status files?</para>
 
 	  <para>The <application>CVSup</application> client maintains
 	    certain status files in what
 	    is called the <quote>base</quote> directory.  These files
 	    help <application>CVSup</application> to work more
 	    efficiently, by keeping track of which updates you have
 	    already received.  We will use the standard base directory,
 	    <filename>/var/db</filename>:</para>
 
 	  <programlisting>*default base=/var/db</programlisting>
 
 	  <para>If your base directory does not already exist, now would
 	    be a good time to create it.  The <command>cvsup</command>
 	    client will refuse to run if the base directory does not
 	    exist.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Miscellaneous <filename>supfile</filename>
 	    settings:</para>
 	  
 	  <para>There is one more line of boiler plate that normally
 	    needs to be present in the
 	    <filename>supfile</filename>:</para>
 
 	  <programlisting>*default release=cvs delete use-rel-suffix compress</programlisting>
 
 	  <para><literal>release=cvs</literal> indicates that the server
 	    should get its information out of the main FreeBSD CVS
 	    repository.  This is virtually always the case, but there
 	    are other possibilities which are beyond the scope of this
 	    discussion.</para>
 	  
 	  <para><literal>delete</literal> gives
 	    <application>CVSup</application> permission to delete files.
 	    You should always specify this, so that
 	    <application>CVSup</application> can keep your source tree
 	    fully up-to-date.  <application>CVSup</application> is
 	    careful to delete only those files for which it is
 	    responsible.  Any extra files you happen to have will be
 	    left strictly alone.</para>
 	  
 	  <para><literal>use-rel-suffix</literal> is ... arcane.  If you
 	    really want to know about it, see the &man.cvsup.1; manual
 	    page.  Otherwise, just specify it and do not worry about
 	    it.</para>
 
 	  <para><literal>compress</literal> enables the use of
 	    gzip-style compression on the communication channel.  If
 	    your network link is T1 speed or faster, you probably should
 	    not use compression.  Otherwise, it helps
 	    substantially.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Putting it all together:</para>
 
 	  <para>Here is the entire <filename>supfile</filename> for our
 	    example:</para>
 
 	  <programlisting>*default tag=.
 *default host=cvsup99.FreeBSD.org
 *default prefix=/usr
 *default base=/var/db
 *default release=cvs delete use-rel-suffix compress
 
 src-all</programlisting>
 	</listitem>
       </itemizedlist>
       <sect3 id="cvsup-refuse-file">
        <title>The <filename>refuse</filename> File</title>
 
        <para>As mentioned above, <application>CVSup</application> uses
        a <emphasis>pull method</emphasis>. Basically, this means that
        you connect to the <application>CVSup</application> server, and
        it says, <quote>Here is what you can download from
        me...</quote>, and your client responds <quote>OK, I will take
        this, this, this, and this.</quote> In the default
        configuration, the <application>CVSup</application> client will
        take every file associated with the collection and tag you
        chose in the configuration file. However, this is not always
        what you want, especially if you are synching the <filename>doc</filename>, <filename>ports</filename>, or
        <filename>www</filename> trees &mdash; most people cannot read four or five
        languages, and therefore they do not need to download the
        language-specific files. If you are
        <application>CVSup</application>ing the ports collection, you
        can get around this by specifying each collection individually
        (e.g., <emphasis>ports-astrology</emphasis>,
        <emphasis>ports-biology</emphasis>, etc instead of simply
        saying <emphasis>ports-all</emphasis>). However, since the <filename>doc</filename>
        and <filename>www</filename> trees do not have language-specific collections, you
        must use one of <application>CVSup</application>'s many nifty
        features: the <filename>refuse</filename> file.</para>
 
        <para>The <filename>refuse</filename> file essentially tells
        <application>CVSup</application> that it should not take every
        single file from a collection; in other words, it tells the
        client to <emphasis>refuse</emphasis> certain files from the
        server. The <filename>refuse</filename> file can be found (or, if you do not yet
        have one, should be placed) in
        <filename><replaceable>base</replaceable>/sup/</filename>.
        <replaceable>base</replaceable> is defined in your <filename>supfile</filename>;
        our defined <replaceable>base</replaceable> is
        <filename>/var/db</filename>, 
        which means that by default the <filename>refuse</filename> file is
        <filename>/var/db/sup/refuse</filename>.</para>
 
        <para>The <filename>refuse</filename> file has a very simple format; it simply
        contains the names of files or directories that you do not wish
        to download.  For example, if you cannot speak any languages other
        than English and some German, and you do not feel the need to read
        the German translation of documentation, you can put the following in your
        <filename>refuse</filename> file:</para>
 
        <screen>doc/bn_*
 doc/da_*
 doc/de_*
 doc/el_*
 doc/es_*
 doc/fr_*
 doc/it_*
 doc/ja_*
 doc/nl_*
 doc/no_*
 doc/pl_*
 doc/pt_*
 doc/ru_*
 doc/sr_*
 doc/tr_*
 doc/zh_*</screen>
 
        <para>and so forth for the other languages (you can find the
        full list by browsing the <ulink
        url="http://www.FreeBSD.org/cgi/cvsweb.cgi/">FreeBSD
        CVS repository</ulink>).</para>
 
        <para>With this very useful feature, those users who are on
        slow links or pay by the minute for their Internet connection
        will be able to save valuable time as they will no longer need
        to download files that they will never use. For more
        information on <filename>refuse</filename> files and other neat
        features of <application>CVSup</application>, please view its
        manual page.</para> 
       </sect3>
     </sect2>
     
     <sect2>
       <title>Running <application>CVSup</application></title>
       
       <para>You are now ready to try an update.  The command line for
 	doing this is quite simple:</para>
 
       <screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen>
 
       <para>where <filename><replaceable>supfile</replaceable></filename>
 	is of course the name of the <filename>supfile</filename> you have just created. 
 	Assuming you are running under X11, <command>cvsup</command>
 	will display a GUI window with some buttons to do the usual
 	things.  Press the <guibutton>go</guibutton> button, and watch it
 	run.</para>
       
       <para>Since you are updating your actual
 	<filename>/usr/src</filename> tree in this example, you will
 	need to run the program as <username>root</username> so that
 	<command>cvsup</command> has the permissions it needs to update
 	your files.  Having just created your configuration file, and
 	having never used this program before, that might
 	understandably make you nervous. There is an easy way to do a
 	trial run without touching your precious files.  Just create an
 	empty directory somewhere convenient, and name it as an extra
 	argument on the command line:</para>
 
       <screen>&prompt.root; <userinput>mkdir /var/tmp/dest</userinput>
 &prompt.root; <userinput>cvsup supfile /var/tmp/dest</userinput></screen>
       
       <para>The directory you specify will be used as the destination
 	directory for all file updates.
 	<application>CVSup</application> will examine your usual files
 	in <filename>/usr/src</filename>, but it will not modify or
 	delete any of them.  Any file updates will instead land in
 	<filename>/var/tmp/dest/usr/src</filename>.
 	<application>CVSup</application> will also leave its base
 	directory status files untouched when run this way.  The new
 	versions of those files will be written into the specified
 	directory.  As long as you have read access to
 	<filename>/usr/src</filename>, you do not even need to be
 	<username>root</username> to perform this kind of trial run.</para>
       
       <para>If you are not running X11 or if you just do not like GUIs,
 	you should add a couple of options to the command line when you
 	run <command>cvsup</command>:</para>
       
       <screen>&prompt.root; <userinput>cvsup -g -L 2 <replaceable>supfile</replaceable></userinput></screen>
 	    
       <para>The <option>-g</option> tells
 	<application>CVSup</application> not to use its GUI.  This is
 	automatic if you are not running X11, but otherwise you have to
 	specify it.</para>
       
       <para>The <option>-L 2</option> tells 
 	<application>CVSup</application> to print out the
 	details of all the file updates it is doing.  There are three
 	levels of verbosity, from <option>-L 0</option> to
 	<option>-L 2</option>.  The default is 0, which means total
 	silence except for error messages.</para>
       
       <para>There are plenty of other options available.  For a brief
 	list of them, type <command>cvsup -H</command>.  For more
 	detailed descriptions, see the manual page.</para>
 
       <para>Once you are satisfied with the way updates are working, you
 	can arrange for regular runs of <application>CVSup</application>
 	using &man.cron.8;.
 	Obviously, you should not let <application>CVSup</application>
 	use its GUI when running it from &man.cron.8;.</para>
     </sect2>
 
     <sect2 id="cvsup-collec">
       <title><application>CVSup</application> File Collections</title>
 	    
       <para>The file collections available via
 	<application>CVSup</application> are organized hierarchically.
 	There are a few large collections, and they are divided into
 	smaller sub-collections.  Receiving a large collection is
 	equivalent to receiving each of its sub-collections.  The
 	hierarchical relationships among collections are reflected by
 	the use of indentation in the list below.</para>
       
       <para>The most commonly used collections are
 	<literal>src-all</literal>, and
 	<literal>ports-all</literal>.  The other collections are used
 	only by small groups of people for specialized purposes, and
 	some mirror sites may not carry all of them.</para>
       
       <variablelist>
 	<varlistentry>
 	  <term><literal>cvs-all release=cvs</literal></term>
 	  
 	  <listitem>
 	    <para>The main FreeBSD CVS repository, including the
 	      cryptography code.</para>
 	    
 	    <variablelist>
 	      <varlistentry>
 		<term><literal>distrib release=cvs</literal></term>
 		
 		<listitem>
 		  <para>Files related to the distribution and mirroring
 		    of FreeBSD.</para>
 		</listitem>
 	      </varlistentry>
 	      
 	      <varlistentry>
 		<term><literal>doc-all release=cvs</literal></term>
 		<listitem>
 		  <para>Sources for the FreeBSD Handbook and other
 		    documentation.  This does not include files for
 		    the FreeBSD web site.</para>
 		</listitem>
 	      </varlistentry>
 
 	      <varlistentry>
 		<term><literal>ports-all release=cvs</literal></term>
 
 		<listitem>
 		  <para>The FreeBSD Ports Collection.</para>
 
 		  <important id="cvsup-collec-pbase-warn">
 		    <para>If you do not want to update the whole of
 		      <literal>ports-all</literal> (the whole ports tree),
 		      but use one of the subcollections listed below,
 		      make sure that you <emphasis>always</emphasis> update
 		      the <literal>ports-base</literal> subcollection!
 		      Whenever something changes in the ports build
 		      infrastructure represented by
 		      <literal>ports-base</literal>, it is virtually certain
 		      that those changes will be used by <quote>real</quote>
 		      ports real soon.  Thus, if you only update the
 		      <quote>real</quote> ports and they use some of the new
 		      features, there is a very high chance that their build
 		      will fail with some mysterious error message.  The
 		      <emphasis>very first</emphasis> thing to do in this
 		      case is to make sure that your
 		      <literal>ports-base</literal> subcollection is up to
 		      date.</para>
 		  </important>
 
 		  <important id="cvsup-collec-index-warn">
 		    <para>If you are going to be building your own local
 		      copy of <filename>ports/INDEX</filename>, you
 		      <emphasis>must</emphasis> accept 
 		      <literal>ports-all</literal> (the whole ports tree).
 		      Building <filename>ports/INDEX</filename> with
 		      a partial tree is not supported.  See the
 		      <ulink url="&url.books.faq;/applications.html#MAKE-INDEX">
 		      FAQ</ulink>.</para>
 		  </important>
 
 		  <variablelist>
 		    <varlistentry>
 		      <term><literal>ports-accessibility
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Software to help disabled users.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-arabic
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Arabic language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-archivers
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Archiving tools.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-astro
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Astronomical ports.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-audio
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Sound support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-base
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>The Ports Collection build infrastructure -
 			  various files located in the
 			  <filename>Mk/</filename> and
 			  <filename>Tools/</filename> subdirectories of
 			  <filename>/usr/ports</filename>.</para>
 
 			<note>
 			  <para>Please see the <link
 			    linkend="cvsup-collec-pbase-warn">important
 			    warning above</link>: you should
 			    <emphasis>always</emphasis> update this
 			    subcollection, whenever you update any part of
 			    the FreeBSD Ports Collection!</para>
 			</note>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-benchmarks
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Benchmarks.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-biology
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Biology.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-cad
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Computer aided design tools.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-chinese
 			  release=cvs</literal></term>
 			
 		      <listitem>
 			<para>Chinese language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-comms
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Communication software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-converters
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>character code converters.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-databases
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Databases.</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>ports-deskutils
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Things that used to be on the desktop
 			  before computers were invented.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-devel
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Development utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-dns
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>DNS related software.</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>ports-editors
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Editors.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-emulators
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Emulators for other operating
 			  systems.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-finance
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Monetary, financial and related applications.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-ftp
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>FTP client and server utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-games
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Games.</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>ports-german
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>German language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-graphics
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Graphics utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-hebrew
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Hebrew language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-hungarian
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Hungarian language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-irc
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Internet Relay Chat utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-japanese
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Japanese language support.</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>ports-java
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>&java; utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-korean
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Korean language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-lang
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Programming languages.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-mail
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Mail software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-math
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Numerical computation software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-mbone
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>MBone applications.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-misc
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Miscellaneous utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-multimedia
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Multimedia software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-net
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Networking software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-net-mgmt
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Network management software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-news
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>USENET news software.</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>ports-palm
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Software support for <trademark class="trade">Palm</trademark>
 			  series.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-polish
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Polish language support.</para>
 		      </listitem>
 		    </varlistentry>
 	
 		    <varlistentry>
 		      <term><literal>ports-portuguese
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Portuguese language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-print
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Printing software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-russian
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Russian language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-science
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Science.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-security
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Security utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-shells
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Command line shells.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-sysutils
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>System utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-textproc
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>text processing utilities (does not
 			  include desktop publishing).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-ukrainian
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Ukrainian language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-vietnamese
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Vietnamese language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-www
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Software related to the World Wide
 			  Web.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Ports to support the X window
 			  system.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-clocks
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>X11 clocks.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-fm
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>X11 file managers.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-fonts
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>X11 fonts and font utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-toolkits
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>X11 toolkits.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-servers
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>X11 servers.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-themes
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>X11 themes.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-wm
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>X11 window managers.</para>
 		      </listitem>
 		    </varlistentry>
 		  </variablelist>
 		</listitem>
 	      </varlistentry>
 
 	      <varlistentry>
 		<term><literal>src-all release=cvs</literal></term>
 		
 		<listitem>
 		  <para>The main FreeBSD sources, including the
 		    cryptography code.</para>
 
 		  <variablelist>
 		    <varlistentry>
 		      <term><literal>src-base
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Miscellaneous files at the top of
 			  <filename>/usr/src</filename>.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-bin
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>User utilities that may be needed in
 			  single-user mode
 			  (<filename>/usr/src/bin</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-contrib
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Utilities and libraries from outside the
 			  FreeBSD project, used relatively unmodified
 			  (<filename>/usr/src/contrib</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-crypto release=cvs</literal></term>
 
 		      <listitem>
 			<para>Cryptography utilities and libraries from
 			  outside the FreeBSD project, used relatively
 			  unmodified
 			  (<filename>/usr/src/crypto</filename>).</para>
 			  </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-eBones release=cvs</literal></term>
 		
 		      <listitem>
 			<para>Kerberos and DES
 			  (<filename>/usr/src/eBones</filename>).  Not
 			  used in current releases of FreeBSD.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-etc
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>System configuration files
 			  (<filename>/usr/src/etc</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-games
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Games
 			  (<filename>/usr/src/games</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-gnu
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Utilities covered by the GNU Public
 			  License (<filename>/usr/src/gnu</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-include
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Header files
 			  (<filename>/usr/src/include</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-kerberos5
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Kerberos5 security package
 			  (<filename>/usr/src/kerberos5</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-kerberosIV
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>KerberosIV security package
 			  (<filename>/usr/src/kerberosIV</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-lib
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Libraries
 			  (<filename>/usr/src/lib</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-libexec
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>System programs normally executed by other
 			  programs
 			  (<filename>/usr/src/libexec</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>src-release
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Files required to produce a FreeBSD
 			  release
 			  (<filename>/usr/src/release</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-sbin release=cvs</literal></term>
 
 		      <listitem>
 			<para>System utilities for single-user mode
 			  (<filename>/usr/src/sbin</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>src-secure
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Cryptographic libraries and commands
 			  (<filename>/usr/src/secure</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-share
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Files that can be shared across multiple
 			  systems
 			  (<filename>/usr/src/share</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-sys
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>The kernel
 			  (<filename>/usr/src/sys</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-sys-crypto
 			release=cvs</literal></term>
 		
 		      <listitem>
 			<para>Kernel cryptography code
 			  (<filename>/usr/src/sys/crypto</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-tools
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Various tools for the maintenance of
 			  FreeBSD
 			  (<filename>/usr/src/tools</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-usrbin
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>User utilities
 			  (<filename>/usr/src/usr.bin</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-usrsbin
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>System utilities
 			  (<filename>/usr/src/usr.sbin</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 		  </variablelist>
 		</listitem>
 	      </varlistentry>
 	      
 	      <varlistentry>
 		<term><literal>www release=cvs</literal></term>
 		
 		<listitem>
 		  <para>The sources for the FreeBSD WWW site.</para>
 		</listitem>
 	      </varlistentry>
 	    </variablelist>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><literal>distrib release=self</literal></term>
 
 	  <listitem>
 	    <para>The <application>CVSup</application> server's own 
 	      configuration files.  Used by <application>CVSup</application>
 	      mirror sites.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>gnats release=current</literal></term>
 
 	  <listitem>
 	    <para>The GNATS bug-tracking database.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>mail-archive release=current</literal></term>
 	  
 	  <listitem>
 	    <para>FreeBSD mailing list archive.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>www release=current</literal></term>
 
 	  <listitem>
 	    <para>The pre-processed FreeBSD WWW site files (not the
 	      source files).  Used by WWW mirror sites.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2>
       <title>For More Information</title>
 
       <para>For the <application>CVSup</application> FAQ and other 
 	information about <application>CVSup</application>, see
 	<ulink url="http://www.polstra.com/projects/freeware/CVSup/">The
 	  CVSup Home Page</ulink>.</para>
 
       <para>Most FreeBSD-related discussion of
 	<application>CVSup</application> takes place on the
 	&a.hackers;.  New versions of the software are announced there,
 	as well as on the &a.announce;.</para>
       
       <para>Questions and bug reports should be addressed to the author
 	of the program at <email>cvsup-bugs@polstra.com</email>.</para>
     </sect2>
 
     <sect2 id="cvsup-mirrors">
     <title>CVSup Sites</title>
 
     <para><link linkend="cvsup">CVSup</link> servers for FreeBSD are running
       at the following sites:</para>
 
     &chap.mirrors.cvsup.inc;
     </sect2>
   </sect1>
   
   <sect1 id="cvs-tags">
     <title>CVS Tags</title>
 
     <para>When obtaining or updating sources using
       <application>cvs</application> or
       <application>CVSup</application>, a revision tag must be specified.
       A revision tag refers to either a particular line of &os;
       development, or a specific point in time.  The first type are called
       <quote>branch tags</quote>, and the second type are called
       <quote>release tags</quote>.</para>
 
     <sect2>
       <title>Branch Tags</title>
 
       <para>All of these, with the exception of <literal>HEAD</literal> (which
 	is always a valid tag), only apply to the <filename>src/</filename>
 	tree.  The <filename>ports/</filename>, <filename>doc/</filename>, and
 	<filename>www/</filename> trees are not branched.</para>
 
     <variablelist>
       <varlistentry>
 	<term>HEAD</term>
 
 	<listitem>
 	  <para>Symbolic name for the main line, or FreeBSD-CURRENT.
 	    Also the default when no revision is specified.</para>
 
 	  <para>In <application>CVSup</application>, this tag is represented
 	    by a <literal>.</literal> (not punctuation, but a literal
 	    <literal>.</literal> character).</para>
 
 	  <note>
 	    <para>In CVS, this is the default when no revision tag is
 	      specified.  It is usually <emphasis>not</emphasis>
 	      a good idea to checkout or update to CURRENT sources
 	      on a STABLE machine, unless that is your intent.</para>
 	  </note>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_5</term>
 
 	<listitem>
 	  <para>The line of development for FreeBSD-5.X, also known
 	    as FreeBSD 5-STABLE.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_5_3</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-5.3, used only 
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_5_2</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-5.2 and FreeBSD-5.2.1, used only 
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_5_1</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-5.1, used only 
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_5_0</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-5.0, used only 
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4</term>
 
 	<listitem>
 	  <para>The line of development for FreeBSD-4.X, also known
 	    as FreeBSD 4-STABLE.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_10</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.10, used only 
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_9</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.9, used only 
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_8</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.8, used only 
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_7</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.7, used only 
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_6</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.6 and FreeBSD-4.6.2,
             used only for security advisories and other
             critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_5</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.5, used only
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_4</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.4, used only
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_3</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.3, used only
 	    for security advisories and other critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3</term>
 
 	<listitem>
 	  <para>The line of development for FreeBSD-3.X, also known
 	    as 3.X-STABLE.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2</term>
 
 	<listitem>
 	  <para>The line of development for FreeBSD-2.2.X, also known
 	    as 2.2-STABLE.  This branch is mostly obsolete.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
     </sect2>
 
     <sect2>
       <title>Release Tags</title>
 
       <para>These tags refer to a specific point in time when a particular
 	version	of &os; was released.  The release engineering process is
 	documented in more detail by the
 	<ulink url="&url.base;/releng/">Release Engineering
 	  Information</ulink> and
         <ulink url="&url.articles.releng;/release-proc.html">Release
 	  Process</ulink> documents.
 	The <filename class="directory">src</filename> tree uses tag names that
 	start with <literal>RELENG_</literal> tags.
 	The <filename class="directory">ports</filename> and
 	<filename class="directory">doc</filename> trees use tags whose names
 	begin with <literal>RELEASE</literal> tags.
 	Finally, the <filename class="directory">www</filename> tree is not
 	tagged with any special name for releases.</para>
 
     <variablelist>
       <varlistentry>
 	<term>RELENG_5_3_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 5.3</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_10_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.10</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_5_2_1_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 5.2.1</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_5_2_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 5.2</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_9_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.9</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_5_1_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 5.1</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_8_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.8</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_5_0_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 5.0</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_7_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.7</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_6_2_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.6.2</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_6_1_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.6.1</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_6_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.6</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_5_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.5</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_4_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.4</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_3_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.3</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_2_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.2</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_1_1_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.1.1</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_1_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.1</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_0_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.0</para>
 	</listitem>
       </varlistentry>
 	  
       <varlistentry>
 	<term>RELENG_3_5_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.5</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_4_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.4</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_3_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.3</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_2_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.2</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_1_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.1</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_0_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.0</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_8_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.8</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_7_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.7</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_6_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.6</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_5_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.5</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_2_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.2</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_1_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.1</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.0</para>
 	</listitem>
       </varlistentry>
     </variablelist>
     </sect2>
   </sect1>
 
   <sect1 id="mirrors-afs">
     <title>AFS Sites</title>
 
     <para>AFS servers for FreeBSD are running at the following sites:</para>
 
     <variablelist>
       <varlistentry>
 	<term>Sweden</term>
 
 	<listitem>
 	  <para>The path to the files are:
   	    <filename>/afs/stacken.kth.se/ftp/pub/FreeBSD/</filename></para>
 
 	  <programlisting>stacken.kth.se         # Stacken Computer Club, KTH, Sweden
 130.237.234.43         #hot.stacken.kth.se
 130.237.237.230        #fishburger.stacken.kth.se
 130.237.234.3          #milko.stacken.kth.se</programlisting>
 
 	  <para>Maintainer <email>ftp@stacken.kth.se</email></para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
   <sect1 id="mirrors-rsync">
     <title>rsync Sites</title>
 
     <para>The following sites make FreeBSD available through the rsync
       protocol.  The <application>rsync</application> utility works in
       much the same way as the &man.rcp.1; command,
       but has more options and uses the rsync remote-update protocol
       which transfers only the differences between two sets of files,
       thus greatly speeding up the synchronization over the network.  
       This is most useful if you are a mirror site for the
       FreeBSD FTP server, or the CVS repository.  The
       <application>rsync</application> suite is available for many
       operating systems, on FreeBSD, see the
       <filename role="package">net/rsync</filename>
       port or use the package.</para>
 
     <variablelist>
       <varlistentry>
 	<term>Czech Republic</term>
 
 	<listitem>
 	  <para>rsync://ftp.cz.FreeBSD.org/</para>
 
 	  <para>Available collections:</para>
 	  <itemizedlist>
 	    <listitem><para>ftp: A partial mirror of the FreeBSD FTP
 	      server.</para></listitem>
 	    <listitem><para>FreeBSD: A full mirror of the FreeBSD FTP
 	      server.</para></listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Germany</term>
 
 	<listitem>
 	  <para>rsync://grappa.unix-ag.uni-kl.de/</para>
 
 	  <para>Available collections:</para>
 	  <itemizedlist>
 	    <listitem><para>freebsd-cvs: The full FreeBSD CVS
 	      repository.</para></listitem>
 	  </itemizedlist>
 	  <para>This machine also mirrors the CVS repositories of the
 	    NetBSD and the OpenBSD projects, among others.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Netherlands</term>
 
 	<listitem>
 	  <para>rsync://ftp.nl.FreeBSD.org/</para>
 
 	  <para>Available collections:</para>
 	  <itemizedlist>
 	    <listitem><para>vol/4/freebsd-core: A full mirror of the
 	      FreeBSD FTP server.</para></listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>United Kingdom</term>
 
 	<listitem>
 	  <para>rsync://rsync.mirror.ac.uk/</para>
 
 	  <para>Available collections:</para>
 	  <itemizedlist>
 	    <listitem><para>ftp.FreeBSD.org: A full mirror of the
 	      FreeBSD FTP server.</para></listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>United States of America</term>
 
 	<listitem>
 	  <para>rsync://ftp-master.FreeBSD.org/</para>
 
 	  <para>This server may only be used by FreeBSD primary mirror
 	    sites.</para>
 	  <para>Available collections:</para>
 	  <itemizedlist>
 	    <listitem><para>FreeBSD: The master archive of the FreeBSD
 	      FTP server.</para></listitem>
 	    <listitem><para>acl: The FreeBSD master ACL
 	      list.</para></listitem>  
 	  </itemizedlist>
 
 	  <para>rsync://ftp13.FreeBSD.org/</para>
 
 	  <para>Available collections:</para>
 	  <itemizedlist>
 	    <listitem><para>FreeBSD: A full mirror of the FreeBSD FTP
 	      server.</para></listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>  
 </appendix>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../appendix.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "appendix")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml b/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml
index 452fcffd92..dd7e4d8598 100644
--- a/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml
@@ -1,5113 +1,5123 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="network-servers">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Murray</firstname>
 	<surname>Stokely</surname>
 	<contrib>Reorganized by </contrib>
       </author>
     </authorgroup>
     <!-- 23 July 2004 -->
   </chapterinfo>
 
   <title>Network Servers</title>
 
   <sect1 id="network-servers-synopsis">
     <title>Synopsis</title>
 
     <para>This chapter will cover some of the more frequently used
       network services on &unix; systems.  We will cover how to
       install, configure, test, and maintain many different types of
       network services.  Example configuration files are included
       throughout this chapter for you to benefit from.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
 
       <listitem>
 	<para>How to manage the <application>inetd</application>
 	  daemon.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up a network filesystem.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up a network information server for sharing
 	  user accounts.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up automatic network settings using DHCP.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up a domain name server.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up the <application>Apache</application> HTTP Server.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up a File Transfer Protocol (FTP) Server.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up a file and print server for &windows;
 	  clients using <application>Samba</application>.</para>
       </listitem>
 
       <listitem>
 	<para>How to synchronize the time and date, and set up a
 	  time server, with the NTP protocol.</para>
       </listitem>
 
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Understand the basics of the
 	  <filename>/etc/rc</filename> scripts.</para>
       </listitem>
 
       <listitem>
 	<para>Be familiar with basic network terminology.</para>
       </listitem>
 
       <listitem>
       <para>Know how to install additional third-party
         software (<xref linkend="ports">).</para>
       </listitem>
 
     </itemizedlist>
   </sect1>
 
   <sect1 id="network-inetd">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
           <surname>Lee</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
 
     <title>The <application>inetd</application> <quote>Super-Server</quote></title>
 
     <sect2 id="network-inetd-overview">
       <title>Overview</title>
 
       <para>&man.inetd.8; is referred to as the <quote>Internet
 	Super-Server</quote> because it manages connections for
 	several services.  When a
 	connection is received by <application>inetd</application>, it
 	determines which program the connection is destined for, spawns
 	the particular process and delegates the socket to it (the program
 	is invoked with the service socket as its standard input, output
 	and error descriptors).  Running
 	one instance of <application>inetd</application> reduces the
 	overall system load as compared to running each daemon
 	individually in stand-alone mode.</para>
 
       <para>Primarily, <application>inetd</application> is used to
 	spawn other daemons, but several trivial protocols are handled
 	directly, such as <application>chargen</application>,
 	<application>auth</application>, and
 	<application>daytime</application>.</para>
 
       <para>This section will cover the basics in configuring
 	<application>inetd</application> through its command-line
 	options and its configuration file,
 	<filename>/etc/inetd.conf</filename>.</para>
     </sect2>
 
     <sect2 id="network-inetd-settings">
       <title>Settings</title>
 
       <para><application>inetd</application> is initialized through
 	the <filename>/etc/rc.conf</filename> system.  The
 	<literal>inetd_enable</literal> option is set to
 	<literal>NO</literal> by default, but is often times turned on
 	by <application>sysinstall</application> with the medium
 	security profile.  Placing:
 	<programlisting>inetd_enable="YES"</programlisting> or
 	<programlisting>inetd_enable="NO"</programlisting> into
 	<filename>/etc/rc.conf</filename> can enable or disable
 	<application>inetd</application> starting at boot time.</para>
 
       <para>Additionally, different command-line options can be passed
 	to <application>inetd</application> via the
 	<literal>inetd_flags</literal> option.</para>
     </sect2>
 
     <sect2 id="network-inetd-cmdline">
       <title>Command-Line Options</title>
 
       <para><application>inetd</application> synopsis:</para>
 
       <para><option>     inetd [-d] [-l] [-w] [-W] [-c maximum] [-C rate] [-a address | hostname]
            [-p filename] [-R rate] [configuration file]</option></para>
 
       <variablelist>
 	<varlistentry>
 	  <term>-d</term>
 
 	  <listitem>
 	    <para>Turn on debugging.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-l</term>
 
 	  <listitem>
 	    <para>Turn on logging of successful connections.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-w</term>
 
 	  <listitem>
 	    <para>Turn on TCP Wrapping for external services (on by
 	      default).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-W</term>
 
 	  <listitem>
 	    <para>Turn on TCP Wrapping for internal services which are
 	      built into <application>inetd</application> (on by
 	      default).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-c maximum</term>
 
 	  <listitem>
 	    <para>Specify the default maximum number of simultaneous
 	      invocations of each service; the default is unlimited.
 	      May be overridden on a per-service basis with the
 	      <option>max-child</option> parameter.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-C rate</term>
 
 	  <listitem>
 	    <para>Specify the default maximum number of times a
 	      service can be invoked from a single IP address in one
 	      minute; the default is unlimited.  May be overridden on a
 	      per-service basis with the
 	      <option>max-connections-per-ip-per-minute</option>
 	      parameter.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-R rate</term>
 
 	  <listitem>
 	    <para>Specify the maximum number of times a service can be
 	      invoked in one minute; the default is 256.  A rate of 0
 	      allows an unlimited number of invocations.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-a</term>
 
 	  <listitem>
 	    <para>Specify one specific IP address to bind to.
 	      Alternatively, a hostname can be specified, in which case
 	      the IPv4 or IPv6 address which corresponds to that
 	      hostname is used.  Usually a hostname is specified when
 	      <application>inetd</application> is run inside a
 	      &man.jail.8;, in which case the hostname corresponds to
 	      the &man.jail.8; environment.</para>
 
 	    <para>When hostname specification is used and both IPv4
 	      and IPv6 bindings are desired, one entry with the
 	      appropriate protocol type for each binding is required
 	      for each service in
 	      <filename>/etc/inetd.conf</filename>.  For example, a
 	      TCP-based service would need two entries, one using
 	      <literal>tcp4</literal> for the protocol and the other
 	      using <literal>tcp6</literal>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-p</term>
 
 	  <listitem>
 	    <para>Specify an alternate file in which to store the
 	      process ID.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
       <para>These options can be passed to
 	<application>inetd</application> using the
 	<literal>inetd_flags</literal> option in
 	<filename>/etc/rc.conf</filename>.  By default,
 	<literal>inetd_flags</literal> is set to
 	<literal>-wW</literal>, which turns on TCP wrapping for
 	<application>inetd</application>'s internal and external
 	services.  For novice users, these parameters usually do not
 	need to be modified or even entered in
 	<filename>/etc/rc.conf</filename>.</para>
 
       <note>
 	<para>An external service is a daemon outside of
 	  <application>inetd</application>, which is invoked when a
 	  connection is received for it.  On the other hand, an
 	  internal service is one that
 	  <application>inetd</application> has the facility of
 	  offering within itself.</para>
       </note>
 
     </sect2>
 
     <sect2 id="network-inetd-conf">
       <title><filename>inetd.conf</filename></title>
 
       <para>Configuration of <application>inetd</application> is
 	controlled through the <filename>/etc/inetd.conf</filename>
 	file.</para>
 
       <para>When a modification is made to
 	<filename>/etc/inetd.conf</filename>,
 	<application>inetd</application> can be forced to re-read its
 	configuration file by sending a HangUP signal to the
 	<application>inetd</application> process as shown:</para>
 
       <example id="network-inetd-hangup">
 	<title>Sending <application>inetd</application> a HangUP Signal</title>
 
 	<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
       </example>
 
       <para>Each line of the configuration file specifies an
 	individual daemon.  Comments in the file are preceded by a
 	<quote>#</quote>.  The format of
 	<filename>/etc/inetd.conf</filename> is as follows:</para>
 
       <programlisting>service-name
 socket-type
 protocol
 {wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
 user[:group][/login-class]
 server-program
 server-program-arguments</programlisting>
 
       <para>An example entry for the <application>ftpd</application> daemon
 	using IPv4:</para>
 
       <programlisting>ftp     stream  tcp     nowait  root    /usr/libexec/ftpd       ftpd -l</programlisting>
 
       <variablelist>
 	<varlistentry>
 	  <term>service-name</term>
 
 	  <listitem>
 	    <para>This is the service name of the particular daemon.
 	      It must correspond to a service listed in
 	      <filename>/etc/services</filename>.  This determines
 	      which port <application>inetd</application> must listen
 	      to.  If a new service is being created, it must be
 	      placed in <filename>/etc/services</filename>
 	      first.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>socket-type</term>
 
 	  <listitem>
 	    <para>Either <literal>stream</literal>,
 	      <literal>dgram</literal>, <literal>raw</literal>, or
 	      <literal>seqpacket</literal>.  <literal>stream</literal>
 	      must be used for connection-based, TCP daemons, while
 	      <literal>dgram</literal> is used for daemons utilizing
 	      the <acronym>UDP</acronym> transport protocol.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>protocol</term>
 
 	  <listitem>
 	    <para>One of the following:</para>
 
 	    <informaltable frame="none" pgwide="1">
 	      <tgroup cols="2">
 		<thead>
 		  <row>
 		    <entry>Protocol</entry>
 		    <entry>Explanation</entry>
 		  </row>
 		</thead>
 		<tbody>
 		  <row>
 		    <entry>tcp, tcp4</entry>
 		    <entry>TCP IPv4</entry>
 		  </row>
 		  <row>
 		    <entry>udp, udp4</entry>
 		    <entry>UDP IPv4</entry>
 		  </row>
 		  <row>
 		    <entry>tcp6</entry>
 		    <entry>TCP IPv6</entry>
 		  </row>
 		  <row>
 		    <entry>udp6</entry>
 		    <entry>UDP IPv6</entry>
 		  </row>
 		  <row>
 		    <entry>tcp46</entry>
 		    <entry>Both TCP IPv4 and v6</entry>
 		  </row>
 		  <row>
 		    <entry>udp46</entry>
 		    <entry>Both UDP IPv4 and v6</entry>
 		  </row>
 		</tbody>
 	      </tgroup>
 	    </informaltable>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]</term>
 
 	  <listitem>
 	    <para><option>wait|nowait</option> indicates whether the
 	      daemon invoked from <application>inetd</application> is
 	      able to handle its own socket or not.
 	      <option>dgram</option> socket types must use the
 	      <option>wait</option> option, while stream socket
 	      daemons, which are usually multi-threaded, should use
 	      <option>nowait</option>.  <option>wait</option> usually
 	      hands off multiple sockets to a single daemon, while
 	      <option>nowait</option> spawns a child daemon for each
 	      new socket.</para>
 
 	    <para>The maximum number of child daemons
 	      <application>inetd</application> may spawn can be set
 	      using the <option>max-child</option> option.  If a limit
 	      of ten instances of a particular daemon is needed, a
 	      <literal>/10</literal> would be placed after
 	      <option>nowait</option>.</para>
 
 	    <para>In addition to <option>max-child</option>, another
 	      option limiting the maximum connections from a single
 	      place to a particular daemon can be enabled.
 	      <option>max-connections-per-ip-per-minute</option> does
 	      just this.  A value of ten here would limit any particular
 	      IP address connecting to a particular service to ten
 	      attempts per minute.  This is useful to prevent
 	      intentional or unintentional resource consumption and
 	      Denial of Service (DoS) attacks to a machine.</para>
 
 	    <para>In this field, <option>wait</option> or
 	      <option>nowait</option> is mandatory.
 	      <option>max-child</option> and
 	      <option>max-connections-per-ip-per-minute</option> are
 	      optional.</para>
 
 	    <para>A stream-type multi-threaded daemon without any
 	      <option>max-child</option> or
 	      <option>max-connections-per-ip-per-minute</option> limits
 	      would simply be: <literal>nowait</literal>.</para>
 
 	    <para>The same daemon with a maximum limit of ten daemons
 	      would read: <literal>nowait/10</literal>.</para>
 
 	    <para>Additionally, the same setup with a limit of twenty
 	      connections per IP address per minute and a maximum
 	      total limit of ten child daemons would read:
 	      <literal>nowait/10/20</literal>.</para>
 
 	    <para>These options are all utilized by the default
 	      settings of the <application>fingerd</application> daemon,
 	      as seen here:</para>
 
 	    <programlisting>finger stream  tcp     nowait/3/10 nobody /usr/libexec/fingerd fingerd -s</programlisting>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>user</term>
 
 	  <listitem>
 	    <para>This is the username that the particular daemon
 	      should run as.  Most commonly, daemons run as the
 	      <username>root</username> user.  For security purposes, it is
 	      common to find some servers running as the
 	      <username>daemon</username> user, or the least privileged
 	      <username>nobody</username> user.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>server-program</term>
 
 	  <listitem>
 	    <para>The full path of the daemon to be executed when a
 	      connection is received.  If the daemon is a service
 	      provided by <application>inetd</application> internally,
 	      then <option>internal</option> should be
 	      used.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>server-program-arguments</term>
 
 	  <listitem>
 	    <para>This works in conjunction with
 	      <option>server-program</option> by specifying the
 	      arguments, starting with <literal>argv[0]</literal>,
 	      passed to the daemon on invocation.  If
 	      <command>mydaemon -d</command> is the command line,
 	      <literal>mydaemon -d</literal> would be the value of
 	      <option>server-program-arguments</option>.  Again, if
 	      the daemon is an internal service, use
 	      <option>internal</option> here.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2 id="network-inetd-security">
       <title>Security</title>
 
       <para>Depending on the security profile chosen at install, many
 	of <application>inetd</application>'s daemons may be enabled
 	by default.  If there is no apparent need for a particular
 	daemon, disable it!  Place a <quote>#</quote> in front of the
 	daemon in question in <filename>/etc/inetd.conf</filename>,
 	and then send a <link linkend="network-inetd-hangup">hangup
 	signal to inetd</link>.  Some daemons, such as
 	<application>fingerd</application>, may not be desired at all
 	because they provide an attacker with too much
 	information.</para>
 
       <para>Some daemons are not security-conscious and have long, or
 	non-existent timeouts for connection attempts.  This allows an
 	attacker to slowly send connections to a particular daemon,
 	thus saturating available resources.  It may be a good idea to
 	place <option>max-connections-per-ip-per-minute</option> and
 	<option>max-child</option> limitations on certain
 	daemons.</para>
 
       <para>By default, TCP wrapping is turned on.  Consult the
 	&man.hosts.access.5; manual page for more information on placing
 	TCP restrictions on various <application>inetd</application>
 	invoked daemons.</para>
     </sect2>
 
     <sect2 id="network-inetd-misc">
       <title>Miscellaneous</title>
 
       <para><application>daytime</application>,
 	<application>time</application>,
 	<application>echo</application>,
 	<application>discard</application>,
 	<application>chargen</application>, and
 	<application>auth</application> are all internally provided
 	services of <application>inetd</application>.</para>
 
       <para>The <application>auth</application> service provides
 	identity (<application>ident</application>,
 	<application>identd</application>) network services, and is
 	configurable to a certain degree.</para>
 
       <para>Consult the &man.inetd.8; manual page for more in-depth
 	information.</para>
     </sect2>
   </sect1>
 
   <sect1 id="network-nfs">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Tom</firstname>
           <surname>Rhodes</surname>
           <contrib>Reorganized and enhanced by </contrib>
         </author>
       </authorgroup>
       <authorgroup>
         <author>
           <firstname>Bill</firstname>
       	  <surname>Swingle</surname>
 	  <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Network File System (NFS)</title>
 
     <indexterm><primary>NFS</primary></indexterm>
     <para>Among the many different filesystems that FreeBSD supports
       is the Network File System, also known as <acronym role="Network
       File System">NFS</acronym>.  <acronym role="Network File
       System">NFS</acronym> allows a system to share directories and
       files with others over a network.  By using <acronym
       role="Network File System">NFS</acronym>, users and programs can
       access files on remote systems almost as if they were local
       files.</para>
 
     <para>Some of the most notable benefits that
       <acronym>NFS</acronym> can provide are:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Local workstations use less disk space because commonly
 	  used data can be stored on a single machine and still remain
 	  accessible to others over the network.</para>
       </listitem>
 
       <listitem>
 	<para>There is no need for users to have separate home
 	  directories on every network machine.  Home directories
 	  could be set up on the <acronym>NFS</acronym> server and
 	  made available throughout the network.</para>
       </listitem>
 
       <listitem>
 	<para>Storage devices such as floppy disks, CDROM drives, and
 	  &iomegazip; drives can be used by other machines on the network.
 	  This may reduce the number of removable media drives
 	  throughout the network.</para>
       </listitem>
     </itemizedlist>
 
     <sect2>
       <title>How <acronym>NFS</acronym> Works</title>
 
       <para><acronym>NFS</acronym> consists of at least two main
         parts: a server and one or more clients.  The client remotely
         accesses the data that is stored on the server machine.  In
         order for this to function properly a few processes have to be
         configured and running.</para>
 
       <note><para>Under &os;&nbsp;4.X, the <application>portmap</application>
 	utility is used in place of the
 	<application>rpcbind</application> utility.  Thus, in &os;&nbsp;4.X
 	the user is required to replace every instance of
 	<application>rpcbind</application> with
 	<application>portmap</application> in the forthcoming
 	examples.</para></note>
 
       <para>The server has to be running the following daemons:</para>
       <indexterm>
         <primary>NFS</primary>
         <secondary>server</secondary>
       </indexterm>
       <indexterm>
         <primary>file server</primary>
         <secondary>UNIX clients</secondary>
       </indexterm>
 
       <indexterm>
 	<primary><application>rpcbind</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>portmap</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>mountd</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>nfsd</application></primary>
       </indexterm>
 
       <informaltable frame="none" pgwide="1">
 	<tgroup cols="2">
 	  <colspec colwidth="1*">
 	  <colspec colwidth="3*">
 
 	  <thead>
 	    <row>
 	      <entry>Daemon</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  <tbody>
 	    <row>
 	      <entry><application>nfsd</application></entry>
 	      <entry>The <acronym>NFS</acronym> daemon which services
 	      requests from the <acronym>NFS</acronym>
 	      clients.</entry>
 	    </row>
 	    <row>
 	      <entry><application>mountd</application></entry>
 	      <entry>The <acronym>NFS</acronym> mount daemon which carries out
 		the requests that &man.nfsd.8; passes on to it.</entry>
 	    </row>
 	    <row>
 	      <entry><application>rpcbind</application></entry>
 	      <entry> This daemon allows
 	      <acronym>NFS</acronym> clients to discover which port
 	      the <acronym>NFS</acronym> server is using.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>The client can also run a daemon, known as
         <application>nfsiod</application>.  The
         <application>nfsiod</application> daemon services the requests
         from the <acronym>NFS</acronym> server.  This is optional, and
         improves performance, but is not required for normal and
         correct operation.  See the &man.nfsiod.8; manual page for
         more information.
       </para>
     </sect2>
 
     <sect2 id="network-configuring-nfs">
       <title>Configuring <acronym>NFS</acronym></title>
       <indexterm>
         <primary>NFS</primary>
         <secondary>configuration</secondary>
       </indexterm>
 
       <para><acronym>NFS</acronym> configuration is a relatively
         straightforward process.  The processes that need to be
         running can all start at boot time with a few modifications to
         your <filename>/etc/rc.conf</filename> file.</para>
 
       <para>On the <acronym>NFS</acronym> server, make sure that the
         following options are configured in the
         <filename>/etc/rc.conf</filename> file:</para>
 
       <programlisting>rpcbind_enable="YES"
 nfs_server_enable="YES"
 mountd_flags="-r"</programlisting>
 
       <para><application>mountd</application> runs automatically
         whenever the <acronym>NFS</acronym> server is enabled.</para>
 
       <para>On the client, make sure this option is present in
         <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>nfs_client_enable="YES"</programlisting>
 
       <para>The <filename>/etc/exports</filename> file specifies which
         filesystems <acronym>NFS</acronym> should export (sometimes
         referred to as <quote>share</quote>).  Each line in
         <filename>/etc/exports</filename> specifies a filesystem to be
         exported and which machines have access to that filesystem.
         Along with what machines have access to that filesystem,
         access options may also be specified.  There are many such
         options that can be used in this file but only a few will be
         mentioned here.  You can easily discover other options by
         reading over the &man.exports.5; manual page.</para>
 
       <para>Here are a few example <filename>/etc/exports</filename>
 	entries:</para>
 
       <indexterm>
         <primary>NFS</primary>
         <secondary>export examples</secondary>
       </indexterm>
 
       <para>The following examples give an idea of how to export
         filesystems, although the settings may be different depending
         on your environment and network configuration.  For instance,
         to export the <filename>/cdrom</filename> directory to three
         example machines that have the same domain name as the server
         (hence the lack of a domain name for each) or have entries in
         your <filename>/etc/hosts</filename> file.  The
         <option>-ro</option> flag makes the exported filesystem
         read-only.  With this flag, the remote system will not be able
         to write any changes to the exported filesystem.</para>
 
       <programlisting>/cdrom -ro host1 host2 host3</programlisting>
 
       <para>The following line exports <filename>/home</filename> to
 	three hosts by IP address.  This is a useful setup if you have
 	a private network without a <acronym>DNS</acronym> server
 	configured.  Optionally the <filename>/etc/hosts</filename>
 	file could be configured for internal hostnames; please review
 	&man.hosts.5; for more information.  The
 	<option>-alldirs</option> flag allows the subdirectories to be
 	mount points.  In other words, it will not mount the
 	subdirectories but permit the client to mount only the
 	directories that are required or needed.</para>
 
       <programlisting>/home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4</programlisting>
 
       <para>The following line exports <filename>/a</filename> so that
 	two clients from different domains may access the filesystem.
 	The <option>-maproot=root</option> flag allows the
 	<username>root</username> user on the remote system to write
 	data on the exported filesystem as <username>root</username>.
 	If the <literal>-maproot=root</literal> flag is not specified,
 	then even if a user has <username>root</username> access on
 	the remote system, he will not be able to modify files on
 	the exported filesystem.</para>
 
       <programlisting>/a  -maproot=root  host.example.com box.example.org</programlisting>
 
       <para>In order for a client to access an exported filesystem,
 	the client must have permission to do so.  Make sure the
 	client is listed in your <filename>/etc/exports</filename>
 	file.</para>
 
       <para>In <filename>/etc/exports</filename>, each line represents
 	the export information for one filesystem to one host.  A
 	remote host can only be specified once per filesystem, and may
 	only have one default entry.  For example, assume that
 	<filename>/usr</filename> is a single filesystem.  The
 	following <filename>/etc/exports</filename> would be
 	invalid:</para>
 
       <programlisting># Invalid when /usr is one file system
 /usr/src   client
 /usr/ports client</programlisting>
 
       <para>One filesystem, <filename>/usr</filename>, has two lines
 	specifying exports to the same host, <hostid>client</hostid>.
         The correct format for this situation is:</para>
 
       <programlisting>/usr/src /usr/ports  client</programlisting>
 
       <para>The properties of one filesystem exported to a given host
 	must all occur on one line.  Lines without a client specified
 	are treated as a single host.  This limits how you can export
 	filesystems, but for most people this is not an issue.</para>
 
       <para>The following is an example of a valid export list, where
 	<filename>/usr</filename> and <filename>/exports</filename>
 	are local filesystems:</para>
 
       <programlisting># Export src and ports to client01 and client02, but only
 # client01 has root privileges on it
 /usr/src /usr/ports -maproot=root    client01
 /usr/src /usr/ports               client02
 # The client machines have root and can mount anywhere
 # on /exports. Anyone in the world can mount /exports/obj read-only
 /exports -alldirs -maproot=root      client01 client02
 /exports/obj -ro</programlisting>
 
       <para>You must restart
         <application>mountd</application> whenever you modify
         <filename>/etc/exports</filename> so the changes can take effect.
         This can be accomplished by sending the HUP signal
         to the <command>mountd</command> process:</para>
 
       <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
 
       <para>Alternatively, a reboot will make FreeBSD set everything
         up properly.  A reboot is not necessary though.
         Executing the following commands as <username>root</username>
         should start everything up.</para>
 
       <para>On the <acronym>NFS</acronym> server:</para>
 
       <screen>&prompt.root; <userinput>rpcbind</userinput>
 &prompt.root; <userinput>nfsd -u -t -n 4</userinput>
 &prompt.root; <userinput>mountd -r</userinput></screen>
 
       <para>On the <acronym>NFS</acronym> client:</para>
 
       <screen>&prompt.root; <userinput>nfsiod -n 4</userinput></screen>
 
       <para>Now everything should be ready to actually mount a remote file
 	system.  In these examples the
 	server's name will be <hostid>server</hostid> and the client's
 	name will be <hostid>client</hostid>.  If you only want to
 	temporarily mount a remote filesystem or would rather test the
 	configuration, just execute a command like this as <username>root</username> on the
         client:</para>
       <indexterm>
         <primary>NFS</primary>
         <secondary>mounting</secondary>
       </indexterm>
       <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>
 
       <para>This will mount the <filename>/home</filename> directory
 	on the server at <filename>/mnt</filename> on the client.  If
 	everything is set up correctly you should be able to enter
 	<filename>/mnt</filename> on the client and see all the files
         that are on the server.</para>
 
       <para>If you want to automatically mount a remote filesystem
 	each time the computer boots, add the filesystem to the
 	<filename>/etc/fstab</filename> file.  Here is an example:</para>
 
       <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>
 
       <para>The &man.fstab.5; manual page lists all the available
         options.</para>
     </sect2>
 
     <sect2>
       <title>Practical Uses</title>
 
       <para><acronym>NFS</acronym> has many practical uses.  Some of
         the more common ones are listed below:</para>
 
       <indexterm>
         <primary>NFS</primary>
         <secondary>uses</secondary>
       </indexterm>
       <itemizedlist>
         <listitem>
 	  <para>Set several machines to share a CDROM or other media
 	    among them.  This is cheaper and often a more convenient
 	    method to install software on multiple machines.</para>
 	</listitem>
 
 	<listitem>
 	  <para>On large networks, it might be more convenient to
 	    configure a central <acronym>NFS</acronym> server in which
 	    to store all the user home directories.  These home
 	    directories can then be exported to the network so that
 	    users would always have the same home directory,
 	    regardless of which workstation they log in to.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Several machines could have a common
             <filename>/usr/ports/distfiles</filename> directory.  That
             way, when you need to install a port on several machines,
             you can quickly access the source without downloading it
             on each machine.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2 id="network-amd">
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Wylie</firstname>
 	    <surname>Stilwell</surname>
 	    <contrib>Contributed by </contrib>
 	  </author>
 	</authorgroup>
 	<authorgroup>
 	  <author>
 	    <firstname>Chern</firstname>
 	    <surname>Lee</surname>
 	    <contrib>Rewritten by </contrib>
 	  </author>
 	</authorgroup>
       </sect2info>
       <title>Automatic Mounts with <application>amd</application></title>
 
       <indexterm><primary>amd</primary></indexterm>
       <indexterm><primary>automatic mounter daemon</primary></indexterm>
 
       <para>&man.amd.8; (the automatic mounter daemon)
 	automatically mounts a
 	remote filesystem whenever a file or directory within that
 	filesystem is accessed.  Filesystems that are inactive for a
 	period of time will also be automatically unmounted by
 	<application>amd</application>.  Using
 	<application>amd</application> provides a simple alternative
 	to permanent mounts, as permanent mounts are usually listed in
         <filename>/etc/fstab</filename>.</para>
 
       <para><application>amd</application> operates by attaching
 	itself as an NFS server to the <filename>/host</filename> and
 	<filename>/net</filename> directories.  When a file is accessed
 	within one of these directories, <application>amd</application>
 	looks up the corresponding remote mount and automatically mounts
 	it.  <filename>/net</filename> is used to mount an exported
 	filesystem from an IP address, while <filename>/host</filename>
 	is used to mount an export from a remote hostname.</para>
 
       <para>An access to a file within
 	<filename>/host/foobar/usr</filename> would tell
 	<application>amd</application> to attempt to mount the
 	<filename>/usr</filename> export on the host
 	<hostid>foobar</hostid>.</para>
 
       <example>
 	<title>Mounting an Export with <application>amd</application></title>
 
 	<para>You can view the available mounts of a remote host with
 	  the <command>showmount</command> command.  For example, to
 	  view the mounts of a host named <hostid>foobar</hostid>, you
 	  can use:</para>
 
 	<screen>&prompt.user; <userinput>showmount -e foobar</userinput>
 Exports list on foobar:
 /usr                               10.10.10.0
 /a                                 10.10.10.0
 &prompt.user; <userinput>cd /host/foobar/usr</userinput></screen>
       </example>
 
       <para>As seen in the example, the <command>showmount</command> shows
 	<filename>/usr</filename> as an export.  When changing directories to
 	<filename>/host/foobar/usr</filename>, <application>amd</application>
 	attempts to resolve the hostname <hostid>foobar</hostid> and
 	automatically mount the desired export.</para>
 
       <para><application>amd</application> can be started by the
 	startup scripts by placing the following lines in
 	<filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>amd_enable="YES"</programlisting>
 
       <para>Additionally, custom flags can be passed to
       <application>amd</application> from the
       <varname>amd_flags</varname> option.  By default,
       <varname>amd_flags</varname> is set to:</para>
 
       <programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting>
 
       <para>The <filename>/etc/amd.map</filename> file defines the
 	default options that exports are mounted with.  The
 	<filename>/etc/amd.conf</filename> file defines some of the more
 	advanced features of <application>amd</application>.</para>
 
       <para>Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more
 	information.</para>
     </sect2>
 
     <sect2 id="network-nfs-integration">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>John</firstname>
             <surname>Lind</surname>
             <contrib>Contributed by </contrib>
           </author>
         </authorgroup>
       </sect2info>
       <title>Problems Integrating with Other Systems</title>
 
       <para>Certain Ethernet adapters for ISA PC systems have limitations
 	which can lead to serious network problems, particularly with NFS.
 	This difficulty is not specific to FreeBSD, but FreeBSD systems
 	are affected by it.</para>
 
       <para>The problem nearly always occurs when (FreeBSD) PC systems are
 	networked with high-performance workstations, such as those made
 	by Silicon Graphics, Inc., and Sun Microsystems, Inc.  The NFS
 	mount will work fine, and some operations may succeed, but
 	suddenly the server will seem to become unresponsive to the
 	client, even though requests to and from other systems continue to
 	be processed.  This happens to the client system, whether the
 	client is the FreeBSD system or the workstation.  On many systems,
 	there is no way to shut down the client gracefully once this
 	problem has manifested itself.  The only solution is often to
 	reset the client, because the NFS situation cannot be
 	resolved.</para>
 
       <para>Though the <quote>correct</quote> solution is to get a
 	higher performance and capacity Ethernet adapter for the
 	FreeBSD system, there is a simple workaround that will allow
 	satisfactory operation.  If the FreeBSD system is the
 	<emphasis>server</emphasis>, include the option
 	<option>-w=1024</option> on the mount from the client.  If the
 	FreeBSD system is the <emphasis>client</emphasis>, then mount
 	the NFS filesystem with the option <option>-r=1024</option>.
 	These options may be specified using the fourth field of the
 	<filename>fstab</filename> entry on the client for automatic
 	mounts, or by using the <option>-o</option> parameter of the
 	&man.mount.8; command for manual mounts.</para>
 
       <para>It should be noted that there is a different problem,
 	sometimes mistaken for this one, when the NFS servers and
 	clients are on different networks.  If that is the case, make
 	<emphasis>certain</emphasis> that your routers are routing the
 	necessary <acronym>UDP</acronym> information, or you will not get anywhere, no
 	matter what else you are doing.</para>
 
       <para>In the following examples, <hostid>fastws</hostid> is the host
 	(interface) name of a high-performance workstation, and
 	<hostid>freebox</hostid> is the host (interface) name of a FreeBSD
 	system with a lower-performance Ethernet adapter.  Also,
 	<filename>/sharedfs</filename> will be the exported NFS
 	filesystem (see &man.exports.5;), and
 	<filename>/project</filename> will be the mount point on the
 	client for the exported filesystem.  In all cases, note that
 	additional options, such as <option>hard</option> or
 	<option>soft</option> and <option>bg</option> may be desirable in
 	your application.</para>
 
       <para>Examples for the FreeBSD system (<hostid>freebox</hostid>)
 	as the client in <filename>/etc/fstab</filename> on
 	<hostid>freebox</hostid>:</para>
 
       <programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting>
 
       <para>As a manual mount command on <hostid>freebox</hostid>:</para>
 
       <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen>
 
       <para>Examples for the FreeBSD system as the server in
 	<filename>/etc/fstab</filename> on
 	<hostid>fastws</hostid>:</para>
 
       <programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
 
       <para>As a manual mount command on <hostid>fastws</hostid>:</para>
 
       <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen>
 
       <para>Nearly any 16-bit Ethernet adapter will allow operation
 	without the above restrictions on the read or write size.</para>
 
       <para>For anyone who cares, here is what happens when the
 	failure occurs, which also explains why it is unrecoverable.
 	NFS typically works with a <quote>block</quote> size of
 	8&nbsp;K (though it may do fragments of smaller sizes).  Since
 	the maximum Ethernet packet is around 1500&nbsp;bytes, the NFS
 	<quote>block</quote> gets split into multiple Ethernet
 	packets, even though it is still a single unit to the
 	upper-level code, and must be received, assembled, and
 	<emphasis>acknowledged</emphasis> as a unit.  The
 	high-performance workstations can pump out the packets which
 	comprise the NFS unit one right after the other, just as close
 	together as the standard allows.  On the smaller, lower
 	capacity cards, the later packets overrun the earlier packets
 	of the same unit before they can be transferred to the host
 	and the unit as a whole cannot be reconstructed or
 	acknowledged.  As a result, the workstation will time out and
 	try again, but it will try again with the entire 8&nbsp;K
 	unit, and the process will be repeated, ad infinitum.</para>
 
       <para>By keeping the unit size below the Ethernet packet size
 	limitation, we ensure that any complete Ethernet packet
 	received can be acknowledged individually, avoiding the
 	deadlock situation.</para>
 
       <para>Overruns may still occur when a high-performance
 	workstations is slamming data out to a PC system, but with the
 	better cards, such overruns are not guaranteed on NFS
 	<quote>units</quote>.  When an overrun occurs, the units
 	affected will be retransmitted, and there will be a fair
 	chance that they will be received, assembled, and
 	acknowledged.</para>
     </sect2>
   </sect1>
 
   <sect1 id="network-nis">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Bill</firstname>
       	  <surname>Swingle</surname>
 	  <contrib>Written by </contrib>
          </author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Eric</firstname>
 	  <surname>Ogren</surname>
 	  <contrib>Enhanced by </contrib>
 	</author>
 	<author>
 	  <firstname>Udo</firstname>
 	  <surname>Erdelhoff</surname>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Network Information System (NIS/YP)</title>
 
     <sect2>
       <title>What Is It?</title>
       <indexterm><primary>NIS</primary></indexterm>
       <indexterm><primary>Solaris</primary></indexterm>
       <indexterm><primary>HP-UX</primary></indexterm>
       <indexterm><primary>AIX</primary></indexterm>
       <indexterm><primary>Linux</primary></indexterm>
       <indexterm><primary>NetBSD</primary></indexterm>
       <indexterm><primary>OpenBSD</primary></indexterm>
 
       <para><acronym role="Network Information System">NIS</acronym>,
         which stands for Network Information Services, was developed
         by Sun Microsystems to centralize administration of &unix;
         (originally &sunos;) systems.  It has now essentially become
         an industry standard; all major &unix; like systems
         (&solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, FreeBSD,
         etc) support <acronym role="Network Information
         System">NIS</acronym>.</para>
 
       <indexterm><primary>yellow pages</primary><see>NIS</see></indexterm>
 
       <para><acronym role="Network Information System">NIS</acronym>
 	was formerly known as Yellow Pages, but because of trademark
 	issues, Sun changed the name.  The old term (and yp) is still
 	often seen and used.</para>
 
       <indexterm>
         <primary>NIS</primary>
         <secondary>domains</secondary>
       </indexterm>
 
       <para>It is a RPC-based client/server system that allows a group
 	of machines within an NIS domain to share a common set of
 	configuration files.  This permits a system administrator to
 	set up NIS client systems with only minimal configuration data
 	and add, remove or modify configuration data from a single
 	location.</para>
 
       <indexterm><primary>Windows NT</primary></indexterm>
 
       <para>It is similar to the &windowsnt; domain system; although
         the internal implementation of the two are not at all similar,
         the basic functionality can be compared.</para>
     </sect2>
 
     <sect2>
       <title>Terms/Processes You Should Know</title>
 
       <para>There are several terms and several important user
         processes that you will come across when attempting to
         implement NIS on FreeBSD, whether you are trying to create an
         NIS server or act as an NIS client:</para>
 
       <indexterm>
 	<primary><application>rpcbind</application></primary>
       </indexterm>
       <indexterm>
 	<primary><application>portmap</application></primary>
       </indexterm>
 
       <informaltable frame="none" pgwide="1">
 	<tgroup cols="2">
 	<colspec colwidth="1*">
 	<colspec colwidth="3*">
 
 	  <thead>
 	    <row>
 	      <entry>Term</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  <tbody>
 	    <row>
 	      <entry>NIS domainname</entry>
 
 	      <entry>An NIS master server and all of its clients
 		(including its slave servers) have a NIS domainname.
 		Similar to an &windowsnt; domain name, the NIS
 		domainname does not have anything to do with
 		<acronym>DNS</acronym>.</entry>
 	    </row>
 	    <row>
 	      <entry><application>rpcbind</application></entry>
 
 	      <entry>Must be running in order to enable
 		<acronym>RPC</acronym> (Remote Procedure Call, a
 		network protocol used by NIS).  If
 		<application>rpcbind</application> is not running, it
 		will be impossible to run an NIS server, or to act as
 		an NIS client (Under &os;&nbsp;4.X
 		<application>portmap</application> is used in place of
 		<application>rpcbind</application>).</entry>
 	    </row>
 	    <row>
 	      <entry><application>ypbind</application></entry>
 
 	      <entry><quote>Binds</quote> an NIS client to its NIS
 		server.  It will take the NIS domainname from the
 		system, and using <acronym>RPC</acronym>, connect to
 		the server.  <application>ypbind</application> is the
 		core of client-server communication in an NIS
 		environment; if <application>ypbind</application> dies
 		on a client machine, it will not be able to access the
 		NIS server.</entry>
 	    </row>
 	    <row>
 	      <entry><application>ypserv</application></entry>
 	      <entry>Should only be running on NIS servers; this is
 		the NIS server process itself.  If &man.ypserv.8;
 		dies, then the server will no longer be able to
 		respond to NIS requests (hopefully, there is a slave
 		server to take over for it).  There are some
 		implementations of NIS (but not the FreeBSD one), that
 		do not try to reconnect to another server if the
 		server it used before dies.  Often, the only thing
 		that helps in this case is to restart the server
 		process (or even the whole server) or the
 		<application>ypbind</application> process on the
 		client.
 	      </entry>
 	    </row>
 	    <row>
 	      <entry><application>rpc.yppasswdd</application></entry>
 	      <entry>Another process that should only be running on
 		NIS master servers; this is a daemon that will allow NIS
 		clients to change their NIS passwords.  If this daemon
 		is not running, users will have to login to the NIS
 		master server and change their passwords there.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
       <!-- XXX Missing: rpc.ypxfrd (not important, though) May only run
       on the master -->
 
     </sect2>
 
     <sect2>
       <title>How Does It Work?</title>
 
       <para>There are three types of hosts in an NIS environment:
 	master servers, slave servers, and clients.  Servers act as a
 	central repository for host configuration information.  Master
 	servers hold the authoritative copy of this information, while
 	slave servers mirror this information for redundancy.  Clients
 	rely on the servers to provide this information to
 	them.</para>
 
       <para>Information in many files can be shared in this manner.
 	The <filename>master.passwd</filename>,
 	<filename>group</filename>, and <filename>hosts</filename>
 	files are commonly shared via NIS.  Whenever a process on a
 	client needs information that would normally be found in these
 	files locally, it makes a query to the NIS server that it is
 	bound to instead.</para>
 
       <sect3>
         <title>Machine Types</title>
 
         <itemizedlist>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>master server</secondary>
 	  </indexterm>
           <listitem>
             <para>A <emphasis>NIS master server</emphasis>.  This
               server, analogous to a &windowsnt; primary domain
               controller, maintains the files used by all of the NIS
               clients.  The <filename>passwd</filename>,
               <filename>group</filename>, and other various files used
               by the NIS clients live on the master server.</para>
 
             <note><para>It is possible for one machine to be an NIS
               master server for more than one NIS domain.  However,
               this will not be covered in this introduction, which
               assumes a relatively small-scale NIS
               environment.</para></note>
           </listitem>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>slave server</secondary>
 	  </indexterm>
           <listitem>
             <para><emphasis>NIS slave servers</emphasis>.  Similar to
               the &windowsnt; backup domain controllers, NIS slave
               servers maintain copies of the NIS master's data files.
               NIS slave servers provide the redundancy, which is
               needed in important environments.  They also help to
               balance the load of the master server: NIS Clients
               always attach to the NIS server whose response they get
               first, and this includes slave-server-replies.</para>
           </listitem>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>client</secondary>
 	  </indexterm>
           <listitem>
             <para><emphasis>NIS clients</emphasis>.  NIS clients, like
               most &windowsnt; workstations, authenticate against the
               NIS server (or the &windowsnt; domain controller in the
               &windowsnt; workstations case) to log on.</para>
           </listitem>
         </itemizedlist>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Using NIS/YP</title>
 
       <para>This section will deal with setting up a sample NIS
         environment.</para>
 
       <note><para>This section assumes that you are running
         FreeBSD&nbsp;3.3 or later.  The instructions given here will
         <emphasis>probably</emphasis> work for any version of FreeBSD
         greater than 3.0, but there are no guarantees that this is
         true.</para></note>
 
 
       <sect3>
         <title>Planning</title>
 
         <para>Let us assume that you are the administrator of a small
           university lab.  This lab, which consists of 15 FreeBSD
           machines, currently has no centralized point of
           administration; each machine has its own
           <filename>/etc/passwd</filename> and
           <filename>/etc/master.passwd</filename>.  These files are
           kept in sync with each other only through manual
           intervention; currently, when you add a user to the lab, you
           must run <command>adduser</command> on all 15 machines.
           Clearly, this has to change, so you have decided to convert
           the lab to use NIS, using two of the machines as
           servers.</para>
 
         <para>Therefore, the configuration of the lab now looks something
           like:</para>
 
         <informaltable frame="none" pgwide="1">
           <tgroup cols="3">
             <thead>
               <row>
                 <entry>Machine name</entry>
                 <entry>IP address</entry>
                 <entry>Machine role</entry>
               </row>
             </thead>
             <tbody>
               <row>
                 <entry><hostid>ellington</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.2</hostid></entry>
                 <entry>NIS master</entry>
               </row>
               <row>
                 <entry><hostid>coltrane</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.3</hostid></entry>
                 <entry>NIS slave</entry>
               </row>
               <row>
                 <entry><hostid>basie</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.4</hostid></entry>
                 <entry>Faculty workstation</entry>
               </row>
               <row>
                 <entry><hostid>bird</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.5</hostid></entry>
                 <entry>Client machine</entry>
               </row>
               <row>
                 <entry><hostid>cli[1-11]</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.[6-17]</hostid></entry>
                 <entry>Other client machines</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
         <para>If you are setting up a NIS scheme for the first time, it
 	  is a good idea to think through how you want to go about it.  No
 	  matter what the size of your network, there are a few decisions
 	  that need to be made.</para>
 
         <sect4>
           <title>Choosing a NIS Domain Name</title>
 
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>domainname</secondary>
 	  </indexterm>
           <para>This might not be the <quote>domainname</quote> that
 	    you are used to.  It is more accurately called the
 	    <quote>NIS domainname</quote>.  When a client broadcasts
 	    its requests for info, it includes the name of the NIS
 	    domain that it is part of.  This is how multiple servers
 	    on one network can tell which server should answer which
 	    request.  Think of the NIS domainname as the name for a
 	    group of hosts that are related in some way.</para>
 
 	  <para>Some organizations choose to use their Internet
 	    domainname for their NIS domainname.  This is not
 	    recommended as it can cause confusion when trying to debug
 	    network problems.  The NIS domainname should be unique
 	    within your network and it is helpful if it describes the
 	    group of machines it represents.  For example, the Art
 	    department at Acme Inc. might be in the
 	    <quote>acme-art</quote> NIS domain.  For this example,
 	    assume you have chosen the name
 	    <literal>test-domain</literal>.</para>
 
 	  <indexterm><primary>SunOS</primary></indexterm>
           <para>However, some operating systems (notably &sunos;) use
           their NIS domain name as their Internet domain name.  If one
           or more machines on your network have this restriction, you
           <emphasis>must</emphasis> use the Internet domain name as
           your NIS domain name.</para>
         </sect4>
 
         <sect4>
           <title>Physical Server Requirements</title>
 
 	  <para>There are several things to keep in mind when choosing
 	    a machine to use as a NIS server.  One of the unfortunate
 	    things about NIS is the level of dependency the clients
 	    have on the server.  If a client cannot contact the server
 	    for its NIS domain, very often the machine becomes
 	    unusable.  The lack of user and group information causes
 	    most systems to temporarily freeze up.  With this in mind
 	    you should make sure to choose a machine that will not be
 	    prone to being rebooted regularly, or one that might be
 	    used for development.  The NIS server should ideally be a
 	    stand alone machine whose sole purpose in life is to be an
 	    NIS server.  If you have a network that is not very
 	    heavily used, it is acceptable to put the NIS server on a
 	    machine running other services, just keep in mind that if
 	    the NIS server becomes unavailable, it will affect
 	    <emphasis>all</emphasis> of your NIS clients
 	    adversely.</para>
         </sect4>
       </sect3>
 
       <sect3>
         <title>NIS Servers</title>
 
 	<para> The canonical copies of all NIS information are stored
 	  on a single machine called the NIS master server.  The
 	  databases used to store the information are called NIS maps.
 	  In FreeBSD, these maps are stored in
 	  <filename>/var/yp/[domainname]</filename> where
 	  <filename>[domainname]</filename> is the name of the NIS
 	  domain being served.  A single NIS server can support
 	  several domains at once, therefore it is possible to have
 	  several such directories, one for each supported domain.
 	  Each domain will have its own independent set of
 	  maps.</para>
 
 	<para>NIS master and slave servers handle all NIS requests
 	  with the <command>ypserv</command> daemon.
 	  <command>ypserv</command> is responsible for receiving
 	  incoming requests from NIS clients, translating the
 	  requested domain and map name to a path to the corresponding
 	  database file and transmitting data from the database back
 	  to the client.</para>
 
         <sect4>
 	  <title>Setting Up a NIS Master Server</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>server configuration</secondary>
 	  </indexterm>
 	  <para>Setting up a master NIS server can be relatively
 	    straight forward, depending on your needs.  FreeBSD comes
 	    with support for NIS out-of-the-box.  All you need is to
 	    add the following lines to
 	    <filename>/etc/rc.conf</filename>, and FreeBSD will do the
 	    rest for you.</para>
 
           <procedure>
             <step>
               <para><programlisting>nisdomainname="test-domain"</programlisting>
                 This line will set the NIS domainname to
                 <literal>test-domain</literal>
                 upon network setup (e.g. after reboot).</para>
             </step>
             <step>
               <para><programlisting>nis_server_enable="YES"</programlisting>
                 This will tell FreeBSD to start up the NIS server processes
                 when the networking is next brought up.</para>
             </step>
             <step>
               <para><programlisting>nis_yppasswdd_enable="YES"</programlisting>
                 This will enable the <command>rpc.yppasswdd</command>
                 daemon which, as mentioned above, will allow users to
                 change their NIS password from a client machine.</para>
             </step>
           </procedure>
 
           <note>
             <para>Depending on your NIS setup, you may need to add
               further entries.  See the <link
               linkend="network-nis-server-is-client">section about NIS
               servers that are also NIS clients</link>, below, for
               details.</para>
           </note>
 
           <para>Now, all you have to do is to run the command
             <command>/etc/netstart</command> as superuser.  It will
             set up everything for you, using the values you defined in
             <filename>/etc/rc.conf</filename>.</para>
         </sect4>
 
         <sect4>
           <title>Initializing the NIS Maps</title>
           <indexterm>
             <primary>NIS</primary>
             <secondary>maps</secondary>
           </indexterm>
           <para>The <emphasis>NIS maps</emphasis> are database files,
             that are kept in the <filename>/var/yp</filename>
             directory.  They are generated from configuration files in
             the <filename>/etc</filename> directory of the NIS master,
             with one exception: the
             <filename>/etc/master.passwd</filename> file.  This is for
             a good reason, you do not want to propagate passwords to
             your <username>root</username> and other administrative
             accounts to all the servers in the NIS domain.  Therefore,
             before we initialize the NIS maps, you should:</para>
 
           <screen>&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput>
 &prompt.root; <userinput>cd /var/yp</userinput>
 &prompt.root; <userinput>vi master.passwd</userinput></screen>
 
           <para>You should remove all entries regarding system
             accounts (<username>bin</username>,
             <username>tty</username>, <username>kmem</username>,
             <username>games</username>, etc), as well as any accounts
             that you do not want to be propagated to the NIS clients
             (for example <username>root</username> and any other UID 0
             (superuser) accounts).</para>
 
           <note><para>Make sure the
             <filename>/var/yp/master.passwd</filename> is neither group
             nor world readable (mode 600)!  Use the
             <command>chmod</command> command, if appropriate.</para></note>
 
 	  <indexterm><primary>Tru64 UNIX</primary></indexterm>
 
           <para>When you have finished, it is time to initialize the
             NIS maps!  FreeBSD includes a script named
             <command>ypinit</command> to do this for you (see its
             manual page for more information).  Note that this script
             is available on most &unix; Operating Systems, but not on
             all.  On Digital UNIX/Compaq Tru64 UNIX it is called
             <command>ypsetup</command>.  Because we are generating
             maps for an NIS master, we are going to pass the
             <option>-m</option> option to <command>ypinit</command>.
             To generate the NIS maps, assuming you already performed
             the steps above, run:</para>
 
           <screen>ellington&prompt.root; <userinput>ypinit -m test-domain</userinput>
 Server Type: MASTER Domain: test-domain
 Creating an YP server will require that you answer a few questions.
 Questions will all be asked at the beginning of the procedure.
 Do you want this procedure to quit on non-fatal errors? [y/n: n] <userinput>n</userinput>
 Ok, please remember to go back and redo manually whatever fails.
 If you don't, something might not work.
 At this point, we have to construct a list of this domains YP servers.
 rod.darktech.org is already known as master server.
 Please continue to add any slave servers, one per line. When you are
 done with the list, type a &lt;control D&gt;.
 master server   :  ellington
 next host to add:  <userinput>coltrane</userinput>
 next host to add:  <userinput>^D</userinput>
 The current list of NIS servers looks like this:
 ellington
 coltrane
 Is this correct?  [y/n: y] <userinput>y</userinput>
 
 [..output from map generation..]
 
 NIS Map update completed.
 ellington has been setup as an YP master server without any errors.</screen>
 
           <para><command>ypinit</command> should have created
             <filename>/var/yp/Makefile</filename> from
             <filename>/var/yp/Makefile.dist</filename>.
             When created, this file assumes that you are operating
             in a single server NIS environment with only FreeBSD
             machines.  Since <literal>test-domain</literal> has
             a slave server as well, you must edit
             <filename>/var/yp/Makefile</filename>:</para>
 
           <screen>ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput></screen>
 
 	  <para>You should comment out the line that says</para>
 
 	  <programlisting>NOPUSH = "True"</programlisting>
 
 	  <para>(if it is not commented out already).</para>
         </sect4>
 
         <sect4>
 	  <title>Setting up a NIS Slave Server</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>slave server</secondary>
 	  </indexterm>
 	  <para>Setting up an NIS slave server is even more simple than
 	    setting up the master.  Log on to the slave server and edit the
             file <filename>/etc/rc.conf</filename> as you did before.
             The only difference is that we now must use the
             <option>-s</option> option when running <command>ypinit</command>.
             The <option>-s</option> option requires the name of the NIS
             master be passed to it as well, so our command line looks
             like:</para>
 
   <screen>coltrane&prompt.root; <userinput>ypinit -s ellington test-domain</userinput>
 
 Server Type: SLAVE Domain: test-domain Master: ellington
 
 Creating an YP server will require that you answer a few questions.
 Questions will all be asked at the beginning of the procedure.
 
 Do you want this procedure to quit on non-fatal errors? [y/n: n]  <userinput>n</userinput>
 
 Ok, please remember to go back and redo manually whatever fails.
 If you don't, something might not work.
 There will be no further questions. The remainder of the procedure
 should take a few minutes, to copy the databases from ellington.
 Transferring netgroup...
 ypxfr: Exiting: Map successfully transferred
 Transferring netgroup.byuser...
 ypxfr: Exiting: Map successfully transferred
 Transferring netgroup.byhost...
 ypxfr: Exiting: Map successfully transferred
 Transferring master.passwd.byuid...
 ypxfr: Exiting: Map successfully transferred
 Transferring passwd.byuid...
 ypxfr: Exiting: Map successfully transferred
 Transferring passwd.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring group.bygid...
 ypxfr: Exiting: Map successfully transferred
 Transferring group.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring services.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring rpc.bynumber...
 ypxfr: Exiting: Map successfully transferred
 Transferring rpc.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring protocols.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring master.passwd.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring networks.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring networks.byaddr...
 ypxfr: Exiting: Map successfully transferred
 Transferring netid.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring hosts.byaddr...
 ypxfr: Exiting: Map successfully transferred
 Transferring protocols.bynumber...
 ypxfr: Exiting: Map successfully transferred
 Transferring ypservers...
 ypxfr: Exiting: Map successfully transferred
 Transferring hosts.byname...
 ypxfr: Exiting: Map successfully transferred
 
 coltrane has been setup as an YP slave server without any errors.
 Don't forget to update map ypservers on ellington.</screen>
 
 	  <para>You should now have a directory called
 	    <filename>/var/yp/test-domain</filename>.  Copies of the NIS
 	    master server's maps should be in this directory.  You will
 	    need to make sure that these stay updated.  The following
 	    <filename>/etc/crontab</filename> entries on your slave
 	    servers should do the job:</para>
 
 	  <programlisting>20      *       *       *       *       root   /usr/libexec/ypxfr passwd.byname
 21      *       *       *       *       root   /usr/libexec/ypxfr passwd.byuid</programlisting>
 
 	  <para>These two lines force the slave to sync its maps with
 	    the maps on the master server.  Although these entries are
 	    not mandatory, since the master server attempts to ensure
 	    any changes to its NIS maps are communicated to its slaves
 	    and because password information is vital to systems
 	    depending on the server, it is a good idea to force the
 	    updates.  This is more important on busy networks where map
 	    updates might not always complete.</para>
 
           <para>Now, run the command <command>/etc/netstart</command> on the
             slave server as well, which again starts the NIS server.</para>
 	</sect4>
       </sect3>
 
       <sect3>
         <title>NIS Clients</title>
 
 	<para> An NIS client establishes what is called a binding to a
 	  particular NIS server using the
 	  <command>ypbind</command> daemon.
 	  <command>ypbind</command> checks the system's default
 	  domain (as set by the <command>domainname</command> command),
 	  and begins broadcasting RPC requests on the local network.
 	  These requests specify the name of the domain for which
 	  <command>ypbind</command> is attempting to establish a binding.
 	  If a server that has been configured to serve the requested
 	  domain receives one of the broadcasts, it will respond to
 	  <command>ypbind</command>,  which will record the server's
 	  address.  If there are several servers available (a master and
 	  several slaves, for example), <command>ypbind</command> will
 	  use the address of the first one to respond.  From that point
 	  on, the client system will direct all of its NIS requests to
 	  that server.  <command>ypbind</command> will
 	  occasionally <quote>ping</quote> the server to make sure it is
 	  still up and running.  If it fails to receive a reply to one of
 	  its pings within a reasonable amount of time,
 	  <command>ypbind</command> will mark the domain as unbound and
 	  begin broadcasting again in the hopes of locating another
 	  server.</para>
 
 	<sect4>
 	  <title>Setting Up a NIS Client</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>client configuration</secondary>
 	  </indexterm>
 	  <para>Setting up a FreeBSD machine to be a NIS client is fairly
 	    straightforward.</para>
 
 	  <procedure>
 	    <step>
 	      <para>Edit the file <filename>/etc/rc.conf</filename> and
                 add the following lines in order to set the NIS domainname
                 and start <command>ypbind</command> upon network
                 startup:</para>
 
 	      <programlisting>nisdomainname="test-domain"
 nis_client_enable="YES"</programlisting>
 	    </step>
 
 	    <step>
 	      <para>To import all possible password entries from the NIS
 		server, remove all user accounts from your
 		<filename>/etc/master.passwd</filename> file and use
 		<command>vipw</command> to add the following line to
                 the end of the file:</para>
 
 	      <programlisting>+:::::::::</programlisting>
 
 	      <note>
 		<para>This line will afford anyone with a valid account in
 		  the NIS server's password maps an account.  There are
 		  many ways to configure your NIS client by changing this
 		  line.  See the <link linkend="network-netgroups">netgroups
 		  section</link> below for more information.
                   For more detailed reading see O'Reilly's book on
 		  <literal>Managing NFS and NIS</literal>.</para>
 	      </note>
 
               <note>
                 <para>You should keep at least one local account (i.e.
                   not imported via NIS) in your
                   <filename>/etc/master.passwd</filename> and this
                   account should also be a member of the group
                   <groupname>wheel</groupname>.  If there is something
                   wrong with NIS, this account can be used to log in
                   remotely, become <username>root</username>, and fix things.</para>
               </note>
             </step>
 
 	    <step>
 	      <para>To import all possible group entries from the NIS
 		server, add this line to your
 		<filename>/etc/group</filename> file:</para>
 
 	      <programlisting>+:*::</programlisting>
 	    </step>
 	  </procedure>
 
 	  <para>After completing these steps, you should be able to run
 	    <command>ypcat passwd</command> and see the NIS server's
 	    passwd map.</para>
 	</sect4>
       </sect3>
     </sect2>
 
     <sect2>
       <title>NIS Security</title>
 
       <para>In general, any remote user can issue an RPC to
 	&man.ypserv.8; and retrieve the contents of your NIS maps,
 	provided the remote user knows your domainname.  To prevent
 	such unauthorized transactions, &man.ypserv.8; supports a
 	feature called <quote>securenets</quote> which can be used to
 	restrict access to a given set of hosts.  At startup,
 	&man.ypserv.8; will attempt to load the securenets information
 	from a file called
 	<filename>/var/yp/securenets</filename>.</para>
 
       <note>
 	<para>This path varies depending on the path specified with the
 	  <option>-p</option> option.  This file contains entries that
 	  consist of a network specification and a network mask separated
 	  by white space.  Lines starting with <quote>#</quote> are
 	  considered to be comments.  A sample securenets file might look
 	  like this:</para>
       </note>
 
       <programlisting># allow connections from local host -- mandatory
 127.0.0.1     255.255.255.255
 # allow connections from any host
 # on the 192.168.128.0 network
 192.168.128.0 255.255.255.0
 # allow connections from any host
 # between 10.0.0.0 to 10.0.15.255
 # this includes the machines in the testlab
 10.0.0.0      255.255.240.0</programlisting>
 
       <para>If &man.ypserv.8; receives a request from an address that
 	matches one of these rules, it will process the request
 	normally.  If the address fails to match a rule, the request
 	will be ignored and a warning message will be logged.  If the
 	<filename>/var/yp/securenets</filename> file does not exist,
 	<command>ypserv</command> will allow connections from any
 	host.</para>
 
       <para>The <command>ypserv</command> program also has support for
-	Wietse Venema's <application>tcpwrapper</application> package.
+	Wietse Venema's <application>TCP Wrapper</application> package.
 	This allows the administrator to use the
-	<application>tcpwrapper</application> configuration files for
+	<application>TCP Wrapper</application> configuration files for
 	access control instead of
 	<filename>/var/yp/securenets</filename>.</para>
 
       <note>
         <para>While both of these access control mechanisms provide some
           security, they, like the privileged port test, are
           vulnerable to <quote>IP spoofing</quote> attacks.  All
           NIS-related traffic should be blocked at your firewall.</para>
 
         <para>Servers using <filename>/var/yp/securenets</filename>
           may fail to serve legitimate NIS clients with archaic TCP/IP
           implementations.  Some of these implementations set all
           host bits to zero when doing broadcasts and/or fail to
           observe the subnet mask when calculating the broadcast
           address.  While some of these problems can be fixed by
           changing the client configuration, other problems may force
           the retirement of the client systems in question or the
           abandonment of <filename>/var/yp/securenets</filename>.</para>
 
         <para>Using <filename>/var/yp/securenets</filename> on a
           server with such an archaic implementation of TCP/IP is a
           really bad idea and will lead to loss of NIS functionality
           for large parts of your network.</para>
 
-	<indexterm><primary>tcpwrapper</primary></indexterm>
-        <para>The use of the <application>tcpwrapper</application>
+	<indexterm><primary>TCP Wrappers</primary></indexterm>
+        <para>The use of the <application>TCP Wrapper</application>
           package increases the latency of your NIS server.  The
           additional delay may be long enough to cause timeouts in
           client programs, especially in busy networks or with slow
           NIS servers.  If one or more of your client systems
           suffers from these symptoms, you should convert the client
           systems in question into NIS slave servers and force them
           to bind to themselves.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Barring Some Users from Logging On</title>
 
       <para>In our lab, there is a machine <hostid>basie</hostid> that
         is supposed to be a faculty only workstation.  We do not want
         to take this machine out of the NIS domain, yet the
         <filename>passwd</filename> file on the master NIS server
         contains accounts for both faculty and students.  What can we
         do?</para>
 
       <para>There is a way to bar specific users from logging on to a
         machine, even if they are present in the NIS database.  To do
         this, all you must do is add
         <literal>-<replaceable>username</replaceable></literal> to the
         end of the <filename>/etc/master.passwd</filename> file on the
         client machine, where <replaceable>username</replaceable> is
         the username of the user you wish to bar from logging in.
         This should preferably be done using <command>vipw</command>,
         since <command>vipw</command> will sanity check your changes
         to <filename>/etc/master.passwd</filename>, as well as
         automatically rebuild the password database when you finish
         editing.  For example, if we wanted to bar user
         <username>bill</username> from logging on to
         <hostid>basie</hostid> we would:</para>
 
         <screen>basie&prompt.root; <userinput>vipw</userinput>
 <userinput>[add -bill to the end, exit]</userinput>
 vipw: rebuilding the database...
 vipw: done
 
 basie&prompt.root; <userinput>cat /etc/master.passwd</userinput>
 
 root:[password]:0:0::0:0:The super-user:/root:/bin/csh
 toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
 daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
 operator:*:2:5::0:0:System &:/:/sbin/nologin
 bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
 tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
 kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
 games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
 news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
 man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
 bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
 uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
 xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
 pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
 nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
 +:::::::::
 -bill
 
 basie&prompt.root;</screen>
     </sect2>
 
     <sect2 id="network-netgroups">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Udo</firstname>
             <surname>Erdelhoff</surname>
             <contrib>Contributed by </contrib>
           </author>
         </authorgroup>
       </sect2info>
 
       <title>Using Netgroups</title>
       <indexterm><primary>netgroups</primary></indexterm>
 
       <para>The method shown in the previous section works reasonably
         well if you need special rules for a very small number of
         users and/or machines.  On larger networks, you
         <emphasis>will</emphasis> forget to bar some users from logging
         onto sensitive machines, or you may even have to modify each
         machine separately, thus losing the main benefit of NIS:
         <emphasis>centralized</emphasis> administration.</para>
 
       <para>The NIS developers' solution for this problem is called
         <emphasis>netgroups</emphasis>.  Their purpose and semantics
         can be compared to the normal groups used by &unix; file
         systems.  The main differences are the lack of a numeric ID
         and the ability to define a netgroup by including both user
         accounts and other netgroups.</para>
 
       <para>Netgroups were developed to handle large, complex networks
         with hundreds of users and machines.  On one hand, this is
         a Good Thing if you are forced to deal with such a situation.
         On the other hand, this complexity makes it almost impossible to
         explain netgroups with really simple examples.  The example
         used in the remainder of this section demonstrates this
         problem.</para>
 
       <para>Let us assume that your successful introduction of NIS in
         your laboratory caught your superiors' interest.  Your next
         job is to extend your NIS domain to cover some of the other
         machines on campus.  The two tables contain the names of the
         new users and new machines as well as brief descriptions of
         them.</para>
 
       <informaltable frame="none" pgwide="1">
         <tgroup cols="2">
           <thead>
             <row>
               <entry>User Name(s)</entry>
               <entry>Description</entry>
             </row>
           </thead>
 
           <tbody>
             <row>
               <entry><username>alpha</username>, <username>beta</username></entry>
               <entry>Normal employees of the IT department</entry>
             </row>
 
             <row>
               <entry><username>charlie</username>, <username>delta</username></entry>
               <entry>The new apprentices of the IT department</entry>
             </row>
 
             <row>
               <entry><username>echo</username>, <username>foxtrott</username>, <username>golf</username>, ...</entry>
               <entry>Ordinary employees</entry>
             </row>
 
             <row>
               <entry><username>able</username>, <username>baker</username>, ...</entry>
               <entry>The current interns</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <informaltable frame="none" pgwide="1">
         <tgroup cols="2">
           <thead>
             <row>
               <entry>Machine Name(s)</entry>
               <entry>Description</entry>
             </row>
           </thead>
 
           <tbody>
             <row>
               <!--  Names taken from "Good Omens" by Neil Gaiman and Terry
                     Pratchett.  Many thanks for a brilliant book.  -->
 
               <entry><hostid>war</hostid>, <hostid>death</hostid>,
               <hostid>famine</hostid>,
               <hostid>pollution</hostid></entry>
               <entry>Your most important servers.  Only the IT
                 employees are allowed to log onto these
                 machines.</entry>
             </row>
             <row>
               <!-- gluttony was omitted because it was too fat -->
 
               <entry><hostid>pride</hostid>, <hostid>greed</hostid>,
               <hostid>envy</hostid>, <hostid>wrath</hostid>,
               <hostid>lust</hostid>, <hostid>sloth</hostid></entry>
               <entry>Less important servers.  All members of the IT
               department are allowed to login onto these
               machines.</entry>
             </row>
 
             <row>
               <entry><hostid>one</hostid>, <hostid>two</hostid>,
                 <hostid>three</hostid>, <hostid>four</hostid>,
                 ...</entry>
 
               <entry>Ordinary workstations.  Only the
                 <emphasis>real</emphasis> employees are allowed to use
                 these machines.</entry>
             </row>
 
             <row>
               <entry><hostid>trashcan</hostid></entry>
               <entry>A very old machine without any critical data.
                 Even the intern is allowed to use this box.</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>If you tried to implement these restrictions by separately
         blocking each user, you would have to add one
         <literal>-<replaceable>user</replaceable></literal> line to
         each system's <filename>passwd</filename> for each user who is
         not allowed to login onto that system.  If you forget just one
         entry, you could be in trouble.  It may be feasible to do this
         correctly during the initial setup, however you
         <emphasis>will</emphasis> eventually forget to add the lines
         for new users during day-to-day operations.  After all, Murphy
         was an optimist.</para>
 
       <para>Handling this situation with netgroups offers several
         advantages.  Each user need not be handled separately; you
         assign a user to one or more netgroups and allow or forbid
         logins for all members of the netgroup.  If you add a new
         machine, you will only have to define login restrictions for
         netgroups.  If a new user is added, you will only have to add
         the user to one or more netgroups.  Those changes are
         independent of each other: no more <quote>for each combination
         of user and machine do...</quote> If your NIS setup is planned
         carefully, you will only have to modify exactly one central
         configuration file to grant or deny access to machines.</para>
 
       <para>The first step is the initialization of the NIS map
         netgroup.  FreeBSD's &man.ypinit.8; does not create this map by
         default, but its NIS implementation will support it once it has
         been created.  To create an empty map, simply type</para>
 
       <screen>ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput></screen>
 
       <para>and start adding content.  For our example, we need at
          least four netgroups: IT employees, IT apprentices, normal
          employees and interns.</para>
 
       <programlisting>IT_EMP  (,alpha,test-domain)    (,beta,test-domain)
 IT_APP  (,charlie,test-domain)  (,delta,test-domain)
 USERS   (,echo,test-domain)     (,foxtrott,test-domain) \
         (,golf,test-domain)
 INTERNS (,able,test-domain)     (,baker,test-domain)</programlisting>
 
       <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc.
         are the names of the netgroups.  Each bracketed group adds
         one or more user accounts to it.  The three fields inside a
         group are:</para>
 
       <orderedlist>
         <listitem>
           <para>The name of the host(s) where the following items are
             valid.  If you do not specify a hostname, the entry is
             valid on all hosts.  If you do specify a hostname, you
             will enter a realm of darkness, horror and utter confusion.</para>
         </listitem>
 
         <listitem>
           <para>The name of the account that belongs to this
             netgroup.</para>
         </listitem>
 
         <listitem>
           <para>The NIS domain for the account.  You can import
             accounts from other NIS domains into your netgroup if you
             are one of the unlucky fellows with more than one NIS
             domain.</para>
         </listitem>
       </orderedlist>
 
       <para>Each of these fields can contain wildcards.  See
         &man.netgroup.5; for details.</para>
 
       <note>
         <indexterm><primary>netgroups</primary></indexterm>
         <para>Netgroup names longer than 8 characters should not be
           used, especially if you have machines running other
           operating systems within your NIS domain.  The names are
           case sensitive; using capital letters for your netgroup
           names is an easy way to distinguish between user, machine
           and netgroup names.</para>
 
         <para>Some NIS clients (other than FreeBSD) cannot handle
           netgroups with a large number of entries.  For example, some
           older versions of &sunos; start to cause trouble if a netgroup
           contains more than 15 <emphasis>entries</emphasis>.  You can
           circumvent this limit by creating several sub-netgroups with
           15 users or less and a real netgroup that consists of the
           sub-netgroups:</para>
 
         <programlisting>BIGGRP1  (,joe1,domain)  (,joe2,domain)  (,joe3,domain) [...]
 BIGGRP2  (,joe16,domain)  (,joe17,domain) [...]
 BIGGRP3  (,joe31,domain)  (,joe32,domain)
 BIGGROUP  BIGGRP1 BIGGRP2 BIGGRP3</programlisting>
 
         <para>You can repeat this process if you need more than 225
           users within a single netgroup.</para>
       </note>
 
       <para>Activating and distributing your new NIS map is
         easy:</para>
 
       <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput>
 ellington&prompt.root; <userinput>make</userinput></screen>
 
       <para>This will generate the three NIS maps
         <filename>netgroup</filename>,
         <filename>netgroup.byhost</filename> and
         <filename>netgroup.byuser</filename>.  Use &man.ypcat.1; to
         check if your new NIS maps are available:</para>
 
       <screen>ellington&prompt.user; <userinput>ypcat -k netgroup</userinput>
 ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput>
 ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen>
 
       <para>The output of the first command should resemble the
         contents of <filename>/var/yp/netgroup</filename>.  The second
         command will not produce output if you have not specified
         host-specific netgroups.  The third command can be used to
         get the list of netgroups for a user.</para>
 
       <para>The client setup is quite simple.  To configure the server
         <hostid>war</hostid>, you only have to start
         &man.vipw.8; and replace the line</para>
 
       <programlisting>+:::::::::</programlisting>
 
       <para>with</para>
 
       <programlisting>+@IT_EMP:::::::::</programlisting>
 
       <para>Now, only the data for the users defined in the netgroup
         <literal>IT_EMP</literal> is imported into
         <hostid>war</hostid>'s password database and only
         these users are allowed to login.</para>
 
       <para>Unfortunately, this limitation also applies to the
 	<literal>~</literal> function of the shell and all routines
 	converting between user names and numerical user IDs.  In
 	other words, <command>cd
 	~<replaceable>user</replaceable></command> will not work,
 	<command>ls -l</command> will show the numerical ID instead of
 	the username and <command>find . -user joe -print</command>
 	will fail with <errorname>No such user</errorname>.  To fix
 	this, you will have to import all user entries
 	<emphasis>without allowing them to login onto your
 	servers</emphasis>.</para>
 
       <para>This can be achieved by adding another line to
         <filename>/etc/master.passwd</filename>.  This line should
         contain:</para>
 
       <para><literal>+:::::::::/sbin/nologin</literal>, meaning
         <quote>Import all entries but replace the shell with
         <filename>/sbin/nologin</filename> in the imported
         entries</quote>.  You can replace any field in the
         <literal>passwd</literal> entry by placing a default value in
         your <filename>/etc/master.passwd</filename>.</para>
 
       <!-- Been there, done that, got the scars to prove it - ue -->
       <warning>
         <para>Make sure that the line
         <literal>+:::::::::/sbin/nologin</literal> is placed after
         <literal>+@IT_EMP:::::::::</literal>.  Otherwise, all user
         accounts imported from NIS will have <filename>/sbin/nologin</filename> as their
         login shell.</para>
       </warning>
 
       <para>After this change, you will only have to change one NIS
         map if a new employee joins the IT department.  You could use
         a similar approach for the less important servers by replacing
         the old <literal>+:::::::::</literal> in their local version
         of <filename>/etc/master.passwd</filename> with something like
         this:</para>
 
       <programlisting>+@IT_EMP:::::::::
 +@IT_APP:::::::::
 +:::::::::/sbin/nologin</programlisting>
 
       <para>The corresponding lines for the normal workstations
         could be:</para>
 
       <programlisting>+@IT_EMP:::::::::
 +@USERS:::::::::
 +:::::::::/sbin/nologin</programlisting>
 
       <para>And everything would be fine until there is a policy
         change a few weeks later: The IT department starts hiring
         interns.  The IT interns are allowed to use the normal
         workstations and the less important servers; and the IT
         apprentices are allowed to login onto the main servers.  You
         add a new netgroup <literal>IT_INTERN</literal>, add the new
         IT interns to this netgroup and start to change the
         configuration on each and every machine...  As the old saying
         goes: <quote>Errors in centralized planning lead to global
         mess</quote>.</para>
 
       <para>NIS' ability to create netgroups from other netgroups can
         be used to prevent situations like these.  One possibility
         is the creation of role-based netgroups.  For example, you
         could create a netgroup called
         <literal>BIGSRV</literal> to define the login
         restrictions for the important servers, another netgroup
         called <literal>SMALLSRV</literal> for the less
         important servers and a third netgroup called
         <literal>USERBOX</literal> for the normal
         workstations.  Each of these netgroups contains the netgroups
         that are allowed to login onto these machines.  The new
         entries for your NIS map netgroup should look like this:</para>
 
       <programlisting>BIGSRV    IT_EMP  IT_APP
 SMALLSRV  IT_EMP  IT_APP  ITINTERN
 USERBOX   IT_EMP  ITINTERN USERS</programlisting>
 
       <para>This method of defining login restrictions works
         reasonably well if you can define groups of machines with
         identical restrictions.  Unfortunately, this is the exception
         and not the rule.  Most of the time, you will need the ability
         to define login restrictions on a per-machine basis.</para>
 
       <para>Machine-specific netgroup definitions are the other
         possibility to deal with the policy change outlined above.  In
         this scenario, the <filename>/etc/master.passwd</filename> of
         each box contains two lines starting with <quote>+</quote>.
         The first of them adds a netgroup with the accounts allowed to
         login onto this machine, the second one adds all other
         accounts with <filename>/sbin/nologin</filename> as shell.  It
         is a good idea to use the <quote>ALL-CAPS</quote> version of
         the machine name as the name of the netgroup.  In other words,
         the lines should look like this:</para>
 
       <programlisting>+@<replaceable>BOXNAME</replaceable>:::::::::
 +:::::::::/sbin/nologin</programlisting>
 
       <para>Once you have completed this task for all your machines,
         you will not have to modify the local versions of
         <filename>/etc/master.passwd</filename> ever again.  All
         further changes can be handled by modifying the NIS map.  Here
         is an example of a possible netgroup map for this
         scenario with some additional goodies:</para>
 
       <programlisting># Define groups of users first
 IT_EMP    (,alpha,test-domain)    (,beta,test-domain)
 IT_APP    (,charlie,test-domain)  (,delta,test-domain)
 DEPT1     (,echo,test-domain)     (,foxtrott,test-domain)
 DEPT2     (,golf,test-domain)     (,hotel,test-domain)
 DEPT3     (,india,test-domain)    (,juliet,test-domain)
 ITINTERN  (,kilo,test-domain)     (,lima,test-domain)
 D_INTERNS (,able,test-domain)     (,baker,test-domain)
 #
 # Now, define some groups based on roles
 USERS     DEPT1   DEPT2     DEPT3
 BIGSRV    IT_EMP  IT_APP
 SMALLSRV  IT_EMP  IT_APP    ITINTERN
 USERBOX   IT_EMP  ITINTERN  USERS
 #
 # And a groups for a special tasks
 # Allow echo and golf to access our anti-virus-machine
 SECURITY  IT_EMP  (,echo,test-domain)  (,golf,test-domain)
 #
 # machine-based netgroups
 # Our main servers
 WAR       BIGSRV
 FAMINE    BIGSRV
 # User india needs access to this server
 POLLUTION  BIGSRV  (,india,test-domain)
 #
 # This one is really important and needs more access restrictions
 DEATH     IT_EMP
 #
 # The anti-virus-machine mentioned above
 ONE       SECURITY
 #
 # Restrict a machine to a single user
 TWO       (,hotel,test-domain)
 # [...more groups to follow]</programlisting>
 
       <para>If you are using some kind of database to manage your user
         accounts, you should be able to create the first part of the
         map with your database's report tools.  This way, new users
         will automatically have access to the boxes.</para>
 
       <para>One last word of caution: It may not always be advisable
         to use machine-based netgroups.  If you are deploying a couple of
         dozen or even hundreds of identical machines for student labs,
         you should use role-based netgroups instead of machine-based
         netgroups to keep the size of the NIS map within reasonable
         limits.</para>
     </sect2>
 
     <sect2>
       <title>Important Things to Remember</title>
 
       <para>There are still a couple of things that you will need to do
         differently now that you are in an NIS environment.</para>
 
       <itemizedlist>
         <listitem>
           <para>Every time you wish to add a user to the lab, you
             must add it to the master NIS server <emphasis>only</emphasis>,
             and <emphasis>you must remember to rebuild the NIS
             maps</emphasis>.  If you forget to do this, the new user will
             not be able to login anywhere except on the NIS master.
             For example, if we needed to add a new user
             <username>jsmith</username> to the lab, we would:</para>
 
           <screen>&prompt.root; <userinput>pw useradd jsmith</userinput>
 &prompt.root; <userinput>cd /var/yp</userinput>
 &prompt.root; <userinput>make test-domain</userinput></screen>
 
           <para>You could also run <command>adduser jsmith</command> instead
             of <command>pw useradd jsmith</command>.</para>
         </listitem>
         <listitem>
           <para><emphasis>Keep the administration accounts out of the
             NIS maps</emphasis>.  You do not want to be propagating
             administrative accounts and passwords to machines that
             will have users that should not have access to those
             accounts.</para>
         </listitem>
         <listitem>
           <para><emphasis>Keep the NIS master and slave secure, and
             minimize their downtime</emphasis>.  If somebody either
             hacks or simply turns off these machines, they have
             effectively rendered many people without the ability to
             login to the lab.</para>
 
           <para>This is the chief weakness of any centralized administration
             system.  If you do
             not protect your NIS servers, you will have a lot of angry
             users!</para>
         </listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>NIS v1 Compatibility</title>
 
       <para> FreeBSD's <application>ypserv</application> has some
 	support for serving NIS v1 clients.  FreeBSD's NIS
 	implementation only uses the NIS v2 protocol, however other
 	implementations include support for the v1 protocol for
 	backwards compatibility with older systems.  The
 	<application>ypbind</application> daemons supplied with these
 	systems will try to establish a binding to an NIS v1 server
 	even though they may never actually need it (and they may
 	persist in broadcasting in search of one even after they
 	receive a response from a v2 server).  Note that while support
 	for normal client calls is provided, this version of
 	<application>ypserv</application> does not handle v1 map
 	transfer requests; consequently, it cannot be used as a master
 	or slave in conjunction with older NIS servers that only
 	support the v1 protocol.  Fortunately, there probably are not
 	any such servers still in use today.</para>
     </sect2>
 
     <sect2 id="network-nis-server-is-client">
       <title>NIS Servers That Are Also NIS Clients</title>
 
       <para> Care must be taken when running
 	<application>ypserv</application> in a multi-server domain
 	where the server machines are also NIS clients.  It is
 	generally a good idea to force the servers to bind to
 	themselves rather than allowing them to broadcast bind
 	requests and possibly become bound to each other.  Strange
 	failure modes can result if one server goes down and others
 	are dependent upon it.  Eventually all the clients will time
 	out and attempt to bind to other servers, but the delay
 	involved can be considerable and the failure mode is still
 	present since the servers might bind to each other all over
 	again.</para>
 
       <para>You can force a host to bind to a particular server by running
 	<command>ypbind</command> with the <option>-S</option>
 	flag.  If you do not want to do this manually each time you
         reboot your NIS server, you can add the following lines to
         your <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>nis_client_enable="YES"	# run client stuff as well
 nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</replaceable>"</programlisting>
 
       <para>See &man.ypbind.8; for further information.</para>
     </sect2>
 
     <sect2>
       <title>Password Formats</title>
       <indexterm>
         <primary>NIS</primary>
 	<secondary>password formats</secondary>
       </indexterm>
       <para>One of the most common issues that people run into when trying
 	to implement NIS is password format compatibility.  If your NIS
 	server is using DES encrypted passwords, it will only support
 	clients that are also using DES.  For example, if you have
 	&solaris; NIS clients in your network, then you will almost certainly
 	need to use DES encrypted passwords.</para>
 
       <para>To check which format your servers
 	and clients are using, look at <filename>/etc/login.conf</filename>.
 	If the host is configured to use DES encrypted passwords, then the
 	<literal>default</literal> class will contain an entry like this:</para>
 
       <programlisting>default:\
 	:passwd_format=des:\
 	:copyright=/etc/COPYRIGHT:\
 	[Further entries elided]</programlisting>
 
       <para>Other possible values for the <literal>passwd_format</literal>
 	capability include <literal>blf</literal> and <literal>md5</literal>
 	(for Blowfish and MD5 encrypted passwords, respectively).</para>
 
       <para>If you have made changes to
 	<filename>/etc/login.conf</filename>, you will also need to
 	rebuild the login capability database, which is achieved by
 	running the following command as
 	<username>root</username>:</para>
 
       <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
 
       <note><para>The format of passwords already in
 	<filename>/etc/master.passwd</filename> will not be updated
 	until a user changes his password for the first time
 	<emphasis>after</emphasis> the login capability database is
 	rebuilt.</para></note>
 
       <para>Next, in order to ensure that passwords are encrypted with
 	the format that you have chosen, you should also check that
 	the <literal>crypt_default</literal> in
 	<filename>/etc/auth.conf</filename> gives precedence to your
 	chosen password format.  To do this, place the format that you
 	have chosen first in the list.  For example, when using DES
 	encrypted passwords, the entry would be:</para>
 
       <programlisting>crypt_default	=	des blf md5</programlisting>
 
       <para>Having followed the above steps on each of the &os; based
 	NIS servers and clients, you can be sure that they all agree
 	on which password format is used within your network.  If you
 	have trouble authenticating on an NIS client, this is a pretty
 	good place to start looking for possible problems.  Remember:
 	if you want to deploy an NIS server for a heterogenous
 	network, you will probably have to use DES on all systems
 	because it is the lowest common standard.</para>
     </sect2>
   </sect1>
 
   <sect1 id="network-dhcp">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Greg</firstname>
       	  <surname>Sutter</surname>
 	  <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Automatic Network Configuration (DHCP)</title>
 
     <sect2>
       <title>What Is DHCP?</title>
       <indexterm>
         <primary>Dynamic Host Configuration Protocol</primary>
         <see>DHCP</see>
       </indexterm>
       <indexterm>
         <primary>Internet Software Consortium (ISC)</primary>
       </indexterm>
 
       <para>DHCP, the Dynamic Host Configuration Protocol, describes
         the means by which a system can connect to a network and obtain the
         necessary information for communication upon that network.  FreeBSD
         uses the ISC (Internet Software Consortium) DHCP implementation, so
         all implementation-specific information here is for use with the ISC
         distribution.</para>
     </sect2>
 
     <sect2>
       <title>What This Section Covers</title>
 
       <para>This section describes both the client-side and
         server-side components of the ISC DHCP system.  The
         client-side program, <command>dhclient</command>, comes
         integrated within FreeBSD, and the server-side portion is
         available from the <filename
         role="package">net/isc-dhcp3-server</filename> port.  The
         &man.dhclient.8;, &man.dhcp-options.5;, and
         &man.dhclient.conf.5; manual pages, in addition to the
         references below, are useful resources.</para>
     </sect2>
 
     <sect2>
       <title>How It Works</title>
       <indexterm><primary>UDP</primary></indexterm>
       <para>When <command>dhclient</command>, the DHCP client, is
 	executed on the client machine, it begins broadcasting
 	requests for configuration information.  By default, these
 	requests are on UDP port 68.  The server replies on UDP 67,
 	giving the client an IP address and other relevant network
 	information such as netmask, router, and DNS servers.  All of
 	this information comes in the form of a DHCP
 	<quote>lease</quote> and is only valid for a certain time
 	(configured by the DHCP server maintainer).  In this manner,
 	stale IP addresses for clients no longer connected to the
 	network can be automatically reclaimed.</para>
 
       <para>DHCP clients can obtain a great deal of information from
         the server.  An exhaustive list may be found in
         &man.dhcp-options.5;.</para>
     </sect2>
 
     <sect2>
       <title>FreeBSD Integration</title>
 
       <para>FreeBSD fully integrates the ISC DHCP client,
         <command>dhclient</command>.  DHCP client support is provided
         within both the installer and the base system, obviating the need
         for detailed knowledge of network configurations on any network
         that runs a DHCP server.  <command>dhclient</command> has been
         included in all FreeBSD distributions since 3.2.</para>
         <indexterm>
           <primary><application>sysinstall</application></primary>
         </indexterm>
 
         <para>DHCP is supported by
           <application>sysinstall</application>.  When configuring a
           network interface within
           <application>sysinstall</application>, the second question
           asked is: <quote>Do you want to try DHCP configuration of
           the interface?</quote>. Answering affirmatively will
           execute <command>dhclient</command>, and if successful, will
           fill in the network configuration information
           automatically.</para>
 
         <para>There are two things you must do to have your system use
 	  DHCP upon startup:</para>
         <indexterm>
           <primary>DHCP</primary>
           <secondary>requirements</secondary>
         </indexterm>
 	<itemizedlist>
 	  <listitem>
             <para>Make sure that the <devicename>bpf</devicename>
 	      device is compiled into your kernel.  To do this, add
 	      <literal>device bpf</literal> (<literal>pseudo-device
 	      bpf</literal> under &os;&nbsp;4.X) to your kernel
 	      configuration file, and rebuild the kernel.  For more
 	      information about building kernels, see <xref
 	      linkend="kernelconfig">.</para> <para>The
 	      <devicename>bpf</devicename> device is already part of
 	      the <filename>GENERIC</filename> kernel that is supplied
 	      with FreeBSD, so if you do not have a custom kernel, you
 	      should not need to create one in order to get DHCP
 	      working.</para>
 	    <note>
 	      <para>For those who are particularly security conscious,
 	        you should be warned that <devicename>bpf</devicename>
 		is also the device that allows packet sniffers to work
 		correctly (although they still have to be run as
 		<username>root</username>).  <devicename>bpf</devicename>
 		<emphasis>is</emphasis> required to use DHCP, but if
 		you are very sensitive about security, you probably
 		should not add <devicename>bpf</devicename> to your
 		kernel in the expectation that at some point in the
 		future you will be using DHCP.</para>
 	    </note>
 	  </listitem>
           <listitem>
             <para>Edit your <filename>/etc/rc.conf</filename> to
 	      include the following:</para>
 
             <programlisting>ifconfig_fxp0="DHCP"</programlisting>
 
             <note>
               <para>Be sure to replace <literal>fxp0</literal> with the
                 designation for the interface that you wish to dynamically
                  configure, as described in
 		 <xref linkend="config-network-setup">.</para>
             </note>
 
             <para>If you are using a different location for
               <command>dhclient</command>, or if you wish to pass additional
               flags to <command>dhclient</command>, also include the
               following (editing as necessary):</para>
 
             <programlisting>dhcp_program="/sbin/dhclient"
 dhcp_flags=""</programlisting>
           </listitem>
         </itemizedlist>
 
         <indexterm>
           <primary>DHCP</primary>
           <secondary>server</secondary>
         </indexterm>
         <para>The DHCP server, <application>dhcpd</application>, is included
           as part of the <filename
           role="package">net/isc-dhcp3-server</filename> port in the ports
           collection.  This port contains the ISC DHCP server and
           documentation.</para>
     </sect2>
 
     <sect2>
       <title>Files</title>
       <indexterm>
         <primary>DHCP</primary>
         <secondary>configuration files</secondary>
       </indexterm>
       <itemizedlist>
         <listitem><para><filename>/etc/dhclient.conf</filename></para>
           <para><command>dhclient</command> requires a configuration file,
             <filename>/etc/dhclient.conf</filename>.  Typically the file
             contains only comments, the defaults being reasonably sane.  This
             configuration file is described by the &man.dhclient.conf.5;
             manual page.</para>
         </listitem>
 
         <listitem><para><filename>/sbin/dhclient</filename></para>
           <para><command>dhclient</command> is statically linked and
             resides in <filename>/sbin</filename>.  The &man.dhclient.8;
             manual page gives more information about
             <command>dhclient</command>.</para>
         </listitem>
 
         <listitem><para><filename>/sbin/dhclient-script</filename></para>
           <para><command>dhclient-script</command> is the FreeBSD-specific
             DHCP client configuration script.  It is described in
             &man.dhclient-script.8;, but should not need any user
             modification to function properly.</para>
         </listitem>
 
         <listitem><para><filename>/var/db/dhclient.leases</filename></para>
           <para>The DHCP client keeps a database of valid leases in this
             file, which is written as a log.  &man.dhclient.leases.5;
             gives a slightly longer description.</para>
         </listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
 
       <para>The DHCP protocol is fully described in
         <ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>.
         An informational resource has also been set up at
         <ulink url="http://www.dhcp.org/"></ulink>.</para>
     </sect2>
 
     <sect2 id="network-dhcp-server">
 	<title>Installing and Configuring a DHCP Server</title>
 
 	<sect3>
 	  <title>What This Section Covers</title>
 
 	  <para>This section provides information on how to configure
 	    a FreeBSD system to act as a DHCP server using the ISC
 	    (Internet Software Consortium) implementation of the DHCP
 	    suite.</para>
 
 	  <para>The server portion of the suite is not provided as part of
 	    FreeBSD, and so you will need to install the
 	    <filename role="package">net/isc-dhcp3-server</filename>
 	    port to provide this service.  See <xref linkend="ports"> for
 	    more information on using the ports collection.</para>
 	</sect3>
 
 	<sect3>
 	  <title>DHCP Server Installation</title>
 	  <indexterm>
 	    <primary>DHCP</primary>
 	    <secondary>installation</secondary>
 	  </indexterm>
 	  <para>In order to configure your FreeBSD system as a DHCP
 	    server, you will need to ensure that the &man.bpf.4;
 	    device is compiled into your kernel.  To do this, add
 	    <literal>device bpf</literal> (<literal>pseudo-device
 	    bpf</literal> under &os;&nbsp;4.X) to your kernel
 	    configuration file, and rebuild the kernel.  For more
 	    information about building kernels, see <xref
 	    linkend="kernelconfig">.</para>
 
 	  <para>The <devicename>bpf</devicename> device is already
 	    part of the <filename>GENERIC</filename> kernel that is
 	    supplied with FreeBSD, so you do not need to create a custom
 	    kernel in order to get DHCP working.</para>
 
 	    <note>
 	      <para>Those who are particularly security conscious
 	        should note that <devicename>bpf</devicename>
 		is also the device that allows packet sniffers to work
 		correctly (although such programs still need privileged
 		access).  <devicename>bpf</devicename>
 		<emphasis>is</emphasis> required to use DHCP, but if
 		you are very sensitive about security, you probably
 		should not include <devicename>bpf</devicename> in your
 		kernel purely because you expect to use DHCP at some
 		point in the future.</para>
 	    </note>
 
 	  <para>The next thing that you will need to do is edit the sample
 	    <filename>dhcpd.conf</filename> which was installed by the
 	    <filename role="package">net/isc-dhcp3-server</filename> port.
 	    By default, this will be
 	    <filename>/usr/local/etc/dhcpd.conf.sample</filename>, and you
 	    should copy this to
 	    <filename>/usr/local/etc/dhcpd.conf</filename> before proceeding
 	    to make changes.</para>
 	</sect3>
 
 	<sect3>
 	  <title>Configuring the DHCP Server</title>
 	  <indexterm>
 	    <primary>DHCP</primary>
 	    <secondary>dhcpd.conf</secondary>
 	  </indexterm>
 	  <para><filename>dhcpd.conf</filename> is
 	    comprised of declarations regarding subnets and hosts, and is
 	    perhaps most easily explained using an example :</para>
 
 	  <programlisting>option domain-name "example.com";<co id="domain-name">
 option domain-name-servers 192.168.4.100;<co id="domain-name-servers">
 option subnet-mask 255.255.255.0;<co id="subnet-mask">
 
 default-lease-time 3600;<co id="default-lease-time">
 max-lease-time 86400;<co id="max-lease-time">
 ddns-update-style none;<co id="ddns-update-style">
 
 subnet 192.168.4.0 netmask 255.255.255.0 {
   range 192.168.4.129 192.168.4.254;<co id="range">
   option routers 192.168.4.1;<co id="routers">
 }
 
 host mailhost {
   hardware ethernet 02:03:04:05:06:07;<co id="hardware">
   fixed-address mailhost.example.com;<co id="fixed-address">
 }</programlisting>
 
 	  <calloutlist>
 	    <callout arearefs="domain-name">
 	      <para>This option specifies the domain that will be provided
 		to clients as the default search domain.  See
 		&man.resolv.conf.5; for more information on what this
 		means.</para>
 	    </callout>
 
 	    <callout arearefs="domain-name-servers">
 	      <para>This option specifies a comma separated list of DNS
 		servers that the client should use.</para>
 	    </callout>
 
 	    <callout arearefs="subnet-mask">
 	      <para>The netmask that will be provided to clients.</para>
 	    </callout>
 
 	    <callout arearefs="default-lease-time">
 	      <para>A client may request a specific length of time that a
 		lease will be valid.  Otherwise the server will assign
 		a lease with this expiry value (in seconds).</para>
 	    </callout>
 
 	    <callout arearefs="max-lease-time">
 	      <para>This is the maximum length of time that the server will
 		lease for.  Should a client request a longer lease, a lease
 		will be issued, although it will only be valid for
 		<literal>max-lease-time</literal> seconds.</para>
 	    </callout>
 
 	    <callout arearefs="ddns-update-style">
 	      <para>This option specifies whether the DHCP server should
 		attempt to update DNS when a lease is accepted or released.
 		In the ISC implementation, this option is
 		<emphasis>required</emphasis>.</para>
 	    </callout>
 
 	    <callout arearefs="range">
 	      <para>This denotes which IP addresses should be used in
 		the pool reserved for allocating to clients.  IP
 		addresses between, and including, the ones stated are
 		handed out to clients.</para>
 	    </callout>
 
 	    <callout arearefs="routers">
 	      <para>Declares the default gateway that will be provided to
 		clients.</para>
 	    </callout>
 
 	    <callout arearefs="hardware">
 	      <para>The hardware MAC address of a host (so that the DHCP server
 		can recognize a host when it makes a request).</para>
 	    </callout>
 
 	    <callout arearefs="fixed-address">
 	      <para>Specifies that the host should always be given the
 		same IP address.  Note that using a hostname is
 		correct here, since the DHCP server will resolve the
 		hostname itself before returning the lease
 		information.</para>
 	    </callout>
 	  </calloutlist>
 
 	  <para>Once you have finished writing your
 	    <filename>dhcpd.conf</filename>, you can proceed to start the
 	    server by issuing the following command:</para>
 
 	  <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/isc-dhcpd.sh start</userinput></screen>
 
 	  <para>Should you need to make changes to the configuration of your
 	    server in the future, it is important to note that sending a
 	    <literal>SIGHUP</literal> signal to
 	    <application>dhcpd</application> does <emphasis>not</emphasis>
 	    result in the configuration being reloaded, as it does with most
 	    daemons.  You will need to send a <literal>SIGTERM</literal>
 	    signal to stop the process, and then restart it using the command
 	    above.</para>
 	</sect3>
 
 	<sect3>
 	  <title>Files</title>
 	  <indexterm>
 	    <primary>DHCP</primary>
 	    <secondary>configuration files</secondary>
 	  </indexterm>
 	  <itemizedlist>
 	    <listitem><para><filename>/usr/local/sbin/dhcpd</filename></para>
 	      <para><application>dhcpd</application> is statically linked and
 		resides in <filename>/usr/local/sbin</filename>.  The
 		&man.dhcpd.8; manual page installed with the
 		port gives more information about
 		<application>dhcpd</application>.</para>
 	    </listitem>
 
 	    <listitem><para><filename>/usr/local/etc/dhcpd.conf</filename></para>
 	      <para><application>dhcpd</application> requires a configuration
 		file, <filename>/usr/local/etc/dhcpd.conf</filename> before it
 		will start providing service to clients.  This file needs to
 		contain all the information that should be provided to clients
 		that are being serviced, along with information regarding the
 		operation of the server.  This configuration file is described
 		by the &man.dhcpd.conf.5; manual page installed
 		by the port.</para>
 	    </listitem>
 
 	    <listitem><para><filename>/var/db/dhcpd.leases</filename></para>
 	      <para>The DHCP server keeps a database of leases it has issued
 		in this file, which is written as a log.  The manual page
 		&man.dhcpd.leases.5;, installed by the port
 		gives a slightly longer description.</para>
 	    </listitem>
 
 	    <listitem><para><filename>/usr/local/sbin/dhcrelay</filename></para>
 	      <para><application>dhcrelay</application> is used in advanced
 		environments where one DHCP server forwards a request from a
 		client to another DHCP server on a separate network.  If you
 		require this functionality, then install the <filename
 		role="package">net/isc-dhcp3-relay</filename> port.  The
 		&man.dhcrelay.8; manual page provided with the
 		port contains more detail.</para>
 	    </listitem>
 	  </itemizedlist>
 	</sect3>
 
       </sect2>
 
   </sect1>
 
   <sect1 id="network-dns">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
           <surname>Lee</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Domain Name System (DNS)</title>
 
     <sect2>
       <title>Overview</title>
       <indexterm><primary>BIND</primary></indexterm>
 
       <para>FreeBSD utilizes, by default, a version of BIND (Berkeley
         Internet Name Domain), which is the most common implementation
         of the DNS protocol.  DNS is the protocol through which names
         are mapped to IP addresses, and vice versa.  For example, a
         query for <hostid role="fqdn">www.FreeBSD.org</hostid> will
         receive a reply with the IP address of The FreeBSD Project's
         web server, whereas, a query for <hostid
         role="fqdn">ftp.FreeBSD.org</hostid> will return the IP
         address of the corresponding FTP machine.  Likewise, the
         opposite can happen.  A query for an IP address can resolve
         its hostname.  It is not necessary to run a name server to
         perform DNS lookups on a system.
       </para>
 
       <indexterm><primary>DNS</primary></indexterm>
       <para>DNS is coordinated across the Internet through a somewhat
         complex system of authoritative root name servers, and other
         smaller-scale name servers who host and cache individual domain
         information.
       </para>
 
       <para>
         This document refers to BIND 8.x, as it is the stable version
 	used in FreeBSD.  BIND 9.x in FreeBSD can be installed through
 	the <filename role="package">net/bind9</filename> port.
       </para>
 
       <para>
         RFC1034 and RFC1035 dictate the DNS protocol.
       </para>
 
       <para>
         Currently, BIND is maintained by the
         Internet Software Consortium <ulink url="http://www.isc.org/"></ulink>.
       </para>
     </sect2>
 
     <sect2>
       <title>Terminology</title>
 
       <para>To understand this document, some terms related to DNS must be
 	understood.</para>
 
       <indexterm><primary>resolver</primary></indexterm>
       <indexterm><primary>reverse DNS</primary></indexterm>
       <indexterm><primary>root zone</primary></indexterm>
       <informaltable frame="none" pgwide="1">
 	<tgroup cols="2">
 	  <colspec colwidth="1*">
 	  <colspec colwidth="3*">
 
 	  <thead>
 	    <row>
 	      <entry>Term</entry>
 	      <entry>Definition</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>Forward DNS</entry>
 	      <entry>Mapping of hostnames to IP addresses</entry>
 	    </row>
 
 	    <row>
 	      <entry>Origin</entry>
 	      <entry>Refers to the domain covered in a particular zone
 		file</entry>
 	    </row>
 
 	    <row>
 	      <entry><application>named</application>, BIND, name server</entry>
 	      <entry>Common names for the BIND name server package within
 		FreeBSD</entry>
 	    </row>
 
 	    <row>
 	      <entry>Resolver</entry>
 	      <entry>A system process through which a
 		machine queries a name server for zone information</entry>
 	    </row>
 
 	    <row>
 	      <entry>Reverse DNS</entry>
 	      <entry>The opposite of forward DNS; mapping of IP addresses to
 		hostnames</entry>
 	    </row>
 
 	    <row>
 	      <entry>Root zone</entry>
 
 	      <entry>The beginning of the Internet zone hierarchy.
 		All zones fall under the root zone, similar to how
 		all files in a file system fall under the root directory.</entry>
 	    </row>
 
 	    <row>
 	      <entry>Zone</entry>
 	      <entry>An individual domain, subdomain, or portion of the DNS administered by
 		the same authority</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <indexterm>
 	<primary>zones</primary>
 	<secondary>examples</secondary>
       </indexterm>
 
       <para>Examples of zones:
       </para>
       <itemizedlist>
         <listitem>
           <para><hostid>.</hostid> is the root zone</para>
         </listitem>
         <listitem>
           <para><hostid>org.</hostid> is a zone under the root zone</para>
         </listitem>
         <listitem>
           <para><hostid role="domainname">example.org.</hostid> is a
           zone under the <hostid>org.</hostid> zone</para>
         </listitem>
         <listitem>
           <para><hostid role="domainname">foo.example.org.</hostid> is
             a subdomain, a zone under the <hostid
             role="domainname">example.org.</hostid> zone</para>
         </listitem>
         <listitem>
           <para>
             <hostid>1.2.3.in-addr.arpa</hostid> is a zone referencing
 	    all IP addresses which fall under the <hostid
 	    role="ipaddr">3.2.1.*</hostid> IP space.
           </para>
         </listitem>
       </itemizedlist>
 
       <para>As one can see, the more specific part of a hostname
         appears to its left.  For example, <hostid
         role="domainname">example.org.</hostid> is more specific than
         <hostid>org.</hostid>, as <hostid>org.</hostid> is more
         specific than the root zone.  The layout of each part of a
         hostname is much like a filesystem: the
         <filename>/dev</filename> directory falls within the root, and
         so on.</para>
 
 
     </sect2>
 
     <sect2>
       <title>Reasons to Run a Name Server</title>
 
       <para>Name servers usually come in two forms: an authoritative
 	name server, and a caching name server.</para>
 
       <para>An authoritative name server is needed when:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>one wants to serve DNS information to the
 	    world, replying authoritatively to queries.</para>
 	</listitem>
 	<listitem>
 	  <para>a domain, such as <hostid role="domainname">example.org</hostid>, is
 	    registered and IP addresses need to be assigned to hostnames
 	    under it.</para>
 	</listitem>
 	<listitem>
 	  <para>an IP address block requires reverse DNS entries (IP to
 	    hostname).</para>
 	</listitem>
 	<listitem>
 	  <para>a backup name server, called a slave, must reply to queries
 	    when the primary is down or inaccessible.</para>
 	  </listitem>
       </itemizedlist>
 
       <para>A caching name server is needed when:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>a local DNS server may cache and respond more quickly
 	    than querying an outside name server.</para>
 	</listitem>
 	<listitem>
 	  <para>a reduction in overall network traffic is desired (DNS
 	    traffic has been measured to account for 5% or more of total
 	    Internet traffic).</para>
 	</listitem>
       </itemizedlist>
 
       <para>When one queries for <hostid
 	role="fqdn">www.FreeBSD.org</hostid>, the resolver usually
 	queries the uplink ISP's name server, and retrieves the reply.
 	With a local, caching DNS server, the query only has to be
 	made once to the outside world by the caching DNS server.
 	Every additional query will not have to look to the outside of
 	the local network, since the information is cached
 	locally.</para>
 
     </sect2>
 
     <sect2>
       <title>How It Works</title>
       <para>In FreeBSD, the BIND daemon is called
 	<application>named</application> for obvious reasons.</para>
 
       <informaltable frame="none" pgwide="1">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>File</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><application>named</application></entry>
 	      <entry>the BIND daemon</entry>
 	    </row>
 
 	    <row>
 	      <entry><command>ndc</command></entry>
 	      <entry>name daemon control program</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>/etc/namedb</filename></entry>
 	      <entry>directory where BIND zone information resides</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>/etc/namedb/named.conf</filename></entry>
 	      <entry>daemon configuration file</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>
         Zone files are usually contained within the
         <filename>/etc/namedb</filename>
         directory, and contain the DNS zone information
 	served by the name server.
       </para>
     </sect2>
 
     <sect2>
       <title>Starting BIND</title>
       <indexterm>
         <primary>BIND</primary>
 	<secondary>starting</secondary>
       </indexterm>
       <para>
         Since BIND is installed by default, configuring it all is
         relatively simple.
       </para>
       <para>
         To ensure the <application>named</application> daemon is
          started at boot, put the following line in
          <filename>/etc/rc.conf</filename>:
       </para>
       <programlisting>named_enable="YES"</programlisting>
       <para>To start the daemon manually (after configuring it):</para>
       <screen>&prompt.root; <userinput>ndc start</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Configuration Files</title>
       <indexterm>
         <primary>BIND</primary>
 	<secondary>configuration files</secondary>
       </indexterm>
       <sect3>
         <title>Using <command>make-localhost</command></title>
         <para>Be sure to:
         </para>
         <screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
 &prompt.root; <userinput>sh make-localhost</userinput></screen>
         <para>to properly create the local reverse DNS zone file in
           <filename>/etc/namedb/localhost.rev</filename>.
         </para>
       </sect3>
 
       <sect3>
         <title><filename>/etc/namedb/named.conf</filename></title>
 
         <programlisting>// &dollar;FreeBSD$
 //
 // Refer to the named(8) manual page for details.  If you are ever going
 // to setup a primary server, make sure you've understood the hairy
 // details of how DNS is working.  Even with simple mistakes, you can
 // break connectivity for affected parties, or cause huge amount of
 // useless Internet traffic.
 
 options {
         directory "/etc/namedb";
 
 // In addition to the "forwarders" clause, you can force your name
 // server to never initiate queries of its own, but always ask its
 // forwarders only, by enabling the following line:
 //
 //      forward only;
 
 // If you've got a DNS server around at your upstream provider, enter
 // its IP address here, and enable the line below.  This will make you
 // benefit from its cache, thus reduce overall DNS traffic in the
 Internet.
 /*
         forwarders {
                 127.0.0.1;
         };
 */</programlisting>
 
         <para>
 	  Just as the comment says, to benefit from an uplink's cache,
           <literal>forwarders</literal> can be enabled here.  Under normal
           circumstances, a name server will recursively query the Internet
           looking at certain name servers until it finds the answer it is
           looking for.  Having this enabled will have it query the uplink's
           name server (or name server provided) first, taking advantage of
           its cache.  If the uplink name server in question is a heavily
           trafficked, fast name server, enabling this may be worthwhile.
         </para>
 
 	<warning><para><hostid role="ipaddr">127.0.0.1</hostid>
             will <emphasis>not</emphasis> work here.
             Change this IP address to a name server at your uplink.</para>
         </warning>
 
         <programlisting>        /*
          * If there is a firewall between you and name servers you want
          * to talk to, you might need to uncomment the query-source
          * directive below.  Previous versions of BIND always asked
          * questions using port 53, but BIND 8.1 uses an unprivileged
          * port by default.
          */
         // query-source address * port 53;
 
         /*
          * If running in a sandbox, you may have to specify a different
          * location for the dumpfile.
          */
         // dump-file "s/named_dump.db";
 };
 
 // Note: the following will be supported in a future release.
 /*
 host { any; } {
         topology {
                 127.0.0.0/8;
         };
 };
 */
 
 // Setting up secondaries is way easier and the rough picture for this
 // is explained below.
 //
 // If you enable a local name server, don't forget to enter 127.0.0.1
 // into your /etc/resolv.conf so this server will be queried first.
 // Also, make sure to enable it in /etc/rc.conf.
 
 zone "." {
         type hint;
         file "named.root";
 };
 
 zone "0.0.127.IN-ADDR.ARPA" {
         type master;
         file "localhost.rev";
 };
 
 zone
 "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.INT" {
         type master;
         file "localhost.rev";
 };
 
 // NB: Do not use the IP addresses below, they are faked, and only
 // serve demonstration/documentation purposes!
 //
 // Example secondary config entries.  It can be convenient to become
 // a secondary at least for the zone where your own domain is in.  Ask
 // your network administrator for the IP address of the responsible
 // primary.
 //
 // Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
 // (This is the first bytes of the respective IP address, in reverse
 // order, with ".IN-ADDR.ARPA" appended.)
 //
 // Before starting to setup a primary zone, better make sure you fully
 // understand how DNS and BIND works, however.  There are sometimes
 // unobvious pitfalls.  Setting up a secondary is comparably simpler.
 //
 // NB: Don't blindly enable the examples below. :-)  Use actual names
 // and addresses instead.
 //
 // NOTE!!! FreeBSD runs BIND in a sandbox (see named_flags in rc.conf).
 // The directory containing the secondary zones must be write accessible
 // to BIND.  The following sequence is suggested:
 //
 //      mkdir /etc/namedb/s
 //      chown bind:bind /etc/namedb/s
 //      chmod 750 /etc/namedb/s</programlisting>
 
 	<para>For more information on running BIND in a sandbox, see
 	  <link linkend="network-named-sandbox">Running named in a sandbox</link>.
 	</para>
 
 	<programlisting>/*
 zone "example.com" {
         type slave;
         file "s/example.com.bak";
         masters {
                 192.168.1.1;
         };
 };
 
 zone "0.168.192.in-addr.arpa" {
         type slave;
         file "s/0.168.192.in-addr.arpa.bak";
         masters {
                 192.168.1.1;
         };
 };
 */</programlisting>
         <para>In <filename>named.conf</filename>, these are examples of slave
 	  entries for a forward and reverse zone.</para>
 
         <para>For each new zone served, a new zone entry must be added to
 	  <filename>named.conf</filename>.</para>
 
         <para>For example, the simplest zone entry for
 	  <hostid role="domainname">example.org</hostid> can look like:</para>
 
         <programlisting>zone "example.org" {
 	type master;
 	file "example.org";
 };</programlisting>
 
 	<para>The zone is a master, as indicated by the <option>type</option>
 	  statement, holding its zone information in
 	  <filename>/etc/namedb/example.org</filename> indicated by
 	  the <option>file</option> statement.</para>
 
         <programlisting>zone "example.org" {
 	type slave;
 	file "example.org";
 };</programlisting>
 
         <para>In the slave case, the zone information is transferred from
 	  the master name server for the particular zone, and saved in the
 	  file specified.  If and when the master server dies or is
 	  unreachable, the slave name server will have the transferred
 	  zone information and will be able to serve it.</para>
       </sect3>
 
       <sect3>
         <title>Zone Files</title>
         <para>
           An example master zone file for <hostid
 	  role="domainname">example.org</hostid> (existing within
 	  <filename>/etc/namedb/example.org</filename>) is as follows:
         </para>
 
         <programlisting>$TTL 3600
 
 example.org. IN SOA ns1.example.org. admin.example.org. (
                         5               ; Serial
                         10800           ; Refresh
                         3600            ; Retry
                         604800          ; Expire
                         86400 )         ; Minimum TTL
 
 ; DNS Servers
 @       IN NS           ns1.example.org.
 @       IN NS           ns2.example.org.
 
 ; Machine Names
 localhost       IN A    127.0.0.1
 ns1             IN A    3.2.1.2
 ns2             IN A    3.2.1.3
 mail            IN A    3.2.1.10
 @               IN A    3.2.1.30
 
 ; Aliases
 www             IN CNAME        @
 
 ; MX Record
 @               IN MX   10      mail.example.org.</programlisting>
 
         <para>
           Note that every hostname ending in a <quote>.</quote> is an
           exact hostname, whereas everything without a trailing
           <quote>.</quote> is referenced to the origin.  For example,
           <literal>www</literal> is translated into
           <literal>www.<replaceable>origin</replaceable></literal>.
           In our fictitious zone file, our origin is
           <hostid>example.org.</hostid>, so <literal>www</literal>
           would translate to <hostid>www.example.org.</hostid>
         </para>
 
         <para>
           The format of a zone file follows:
         </para>
         <programlisting>recordname      IN recordtype   value</programlisting>
 
 	<indexterm>
 	  <primary>DNS</primary>
 	  <secondary>records</secondary>
 	</indexterm>
         <para>
           The most commonly used DNS records:
         </para>
 
 	<variablelist>
 	  <varlistentry>
 	    <term>SOA</term>
 
 	    <listitem><para>start of zone authority</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>NS</term>
 
 	    <listitem><para>an authoritative name server</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>A</term>
 
 	    <listitem><para>a host address</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>CNAME</term>
 
 	    <listitem><para>the canonical name for an alias</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>MX</term>
 
 	    <listitem><para>mail exchanger</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>PTR</term>
 
 	    <listitem><para>a domain name pointer (used in reverse DNS)
 	      </para></listitem>
 	  </varlistentry>
 	</variablelist>
 
         <programlisting>
 example.org. IN SOA ns1.example.org. admin.example.org. (
                         5               ; Serial
                         10800           ; Refresh after 3 hours
                         3600            ; Retry after 1 hour
                         604800          ; Expire after 1 week
                         86400 )         ; Minimum TTL of 1 day</programlisting>
 
 
 
 	<variablelist>
 	  <varlistentry>
 	    <term><hostid role="domainname">example.org.</hostid></term>
 
 	    <listitem><para>the domain name, also the origin for this
 		zone file.</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><hostid role="fqdn">ns1.example.org.</hostid></term>
 
 	    <listitem><para>the primary/authoritative name server for this
 		zone.</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>admin.example.org.</literal></term>
 
 	    <listitem><para>the responsible person for this zone,
 		email address with <quote>@</quote>
           replaced.  (<email>admin@example.org</email> becomes
 		<literal>admin.example.org</literal>)</para>
 	    </listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>5</literal></term>
 
 	      <listitem><para>the serial number of the file.  This
 		  must be incremented each time the zone file is
 		  modified.  Nowadays, many admins prefer a
 		  <literal>yyyymmddrr</literal> format for the serial
 		  number.  <literal>2001041002</literal> would mean
 		  last modified 04/10/2001, the latter
 		  <literal>02</literal> being the second time the zone
 		  file has been modified this day.  The serial number
 		  is important as it alerts slave name servers for a
 		  zone when it is updated.</para>
 	      </listitem>
 	  </varlistentry>
 	</variablelist>
 
         <programlisting>
 @       IN NS           ns1.example.org.</programlisting>
 
         <para>
           This is an NS entry.  Every name server that is going to reply
           authoritatively for the zone must have one of these entries.
 	  The <literal>@</literal> as seen here could have been
 	  <hostid role="domainname">example.org.</hostid>
 	  The <literal>@</literal> translates to the origin.
         </para>
 
         <programlisting>
 localhost       IN A    127.0.0.1
 ns1             IN A    3.2.1.2
 ns2             IN A    3.2.1.3
 mail            IN A    3.2.1.10
 @               IN A    3.2.1.30</programlisting>
 
         <para>
           The A record indicates machine names.  As seen above,
           <hostid role="fqdn">ns1.example.org</hostid> would resolve
           to <hostid role="ipaddr">3.2.1.2</hostid>.  Again, the
           origin symbol, <literal>@</literal>, is used here, thus
           meaning <hostid role="domainname">example.org</hostid> would
           resolve to <hostid role="ipaddr">3.2.1.30</hostid>.
         </para>
 
         <programlisting>
 www             IN CNAME        @</programlisting>
 
         <para>
           The canonical name record is usually used for giving aliases
           to a machine.  In the example, <hostid>www</hostid> is
           aliased to the machine addressed to the origin, or
           <hostid role="domainname">example.org</hostid>
           (<hostid role="ipaddr">3.2.1.30</hostid>).
           CNAMEs can be used to provide alias
           hostnames, or round robin one hostname among multiple
           machines.
         </para>
 
 	<indexterm>
 	  <primary>MX record</primary>
 	</indexterm>
 
         <programlisting>
 @               IN MX   10      mail.example.org.</programlisting>
 
         <para>
           The MX record indicates which mail
           servers are responsible for handling incoming mail for the
           zone.  <hostid role="fqdn">mail.example.org</hostid> is the
           hostname of the mail server, and 10 being the priority of
           that mail server.
         </para>
 
         <para>
           One can have several mail servers, with priorities of 3, 2,
           1.  A mail server attempting to deliver to <hostid
           role="domainname">example.org</hostid> would first try the
           highest priority MX, then the second highest, etc, until the
           mail can be properly delivered.
         </para>
 
         <para>
           For in-addr.arpa zone files (reverse DNS), the same format is
           used, except with PTR entries instead of
 	  A or CNAME.
         </para>
 
         <programlisting>$TTL 3600
 
 1.2.3.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
                         5               ; Serial
                         10800           ; Refresh
                         3600            ; Retry
                         604800          ; Expire
                         3600 )          ; Minimum
 
 @       IN NS   ns1.example.org.
 @       IN NS   ns2.example.org.
 
 2       IN PTR  ns1.example.org.
 3       IN PTR  ns2.example.org.
 10      IN PTR  mail.example.org.
 30      IN PTR  example.org.</programlisting>
 
         <para>This file gives the proper IP address to hostname
           mappings of our above fictitious domain.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Caching Name Server</title>
       <indexterm>
         <primary>BIND</primary>
         <secondary>caching name server</secondary>
       </indexterm>
 
       <para>A caching name server is a name server that is not
         authoritative for any zones.  It simply asks queries of its
         own, and remembers them for later use.  To set one up, just
         configure the name server as usual, omitting any inclusions of
         zones.</para>
     </sect2>
 
     <sect2 id="network-named-sandbox">
       <title>Running <application>named</application> in a Sandbox</title>
       <indexterm>
         <primary>BIND</primary>
         <secondary>running in a sandbox</secondary>
       </indexterm>
 
       <indexterm>
         <primary><command>chroot</command></primary>
       </indexterm>
       <para>For added security you may want to run &man.named.8; as an
 	unprivileged user, and configure it to &man.chroot.8; into a
 	sandbox directory.  This makes everything outside of the
 	sandbox inaccessible to the <application>named</application>
 	daemon.  Should <application>named</application> be
 	compromised, this will help to reduce the damage that can be
 	caused.  By default, FreeBSD has a user and a group called
 	<groupname>bind</groupname>, intended for this use.</para>
 
       <note><para>Various people would recommend that instead of configuring
 	<application>named</application> to <command>chroot</command>, you
 	should run <application>named</application> inside a &man.jail.8;.
 	This section does not attempt to cover this situation.</para>
       </note>
 
       <para>Since <application>named</application> will not be able to
 	access anything outside of the sandbox (such as shared
 	libraries, log sockets, and so on), there are a number of steps
 	that need to be followed in order to allow
 	<application>named</application> to function correctly.  In the
 	following checklist, it is assumed that the path to the sandbox
 	is <filename>/etc/namedb</filename> and that you have made no
 	prior modifications to the contents of this directory.  Perform
 	the following steps as <username>root</username>:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Create all directories that <application>named</application>
 	    expects to see:</para>
 
 	  <screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
 &prompt.root; <userinput>mkdir -p bin dev etc var/tmp var/run master slave</userinput>
 &prompt.root; <userinput>chown bind:bind slave var/*</userinput><co id="chown-slave"></screen>
 
 
 
 	  <calloutlist>
 	    <callout arearefs="chown-slave">
 	      <para><application>named</application> only needs write access to
 		these directories, so that is all we give it.</para>
 	    </callout>
 	  </calloutlist>
 	</listitem>
 
 	<listitem>
 	  <para>Rearrange and create basic zone and configuration files:</para>
 	  <screen>&prompt.root; <userinput>cp /etc/localtime etc</userinput><co id="localtime">
 &prompt.root; <userinput>mv named.conf etc && ln -sf etc/named.conf</userinput>
 &prompt.root; <userinput>mv named.root master</userinput>
 <!-- I don't like this next bit -->
 &prompt.root; <userinput>sh make-localhost && mv localhost.rev localhost-v6.rev master</userinput>
 &prompt.root; <userinput>cat > master/named.localhost
 $ORIGIN localhost.
 $TTL 6h
 @	IN	SOA	localhost. postmaster.localhost. (
 			1	; serial
 			3600	; refresh
 			1800	; retry
 			604800	; expiration
 			3600 )	; minimum
 	IN	NS	localhost.
 	IN	A		127.0.0.1
 ^D</userinput></screen>
 
 	  <calloutlist>
 	    <callout arearefs="localtime">
 	      <para>This allows <application>named</application> to log the
 		correct time to &man.syslogd.8;.</para>
 	    </callout>
 	  </calloutlist>
 	</listitem>
 
 	<listitem>
 
         <indexterm><primary>syslog</primary></indexterm>
         <indexterm><primary>log files</primary>
 	  <secondary>named</secondary></indexterm>
 
 	  <para>If you are running a version of &os; prior to 4.9-RELEASE, build a statically linked copy of
 	    <application>named-xfer</application>, and copy it into the sandbox:</para>
 
 	      <screen>&prompt.root; <userinput>cd /usr/src/lib/libisc</userinput>
 &prompt.root; <userinput>make cleandir && make cleandir && make depend && make all</userinput>
 &prompt.root; <userinput>cd /usr/src/lib/libbind</userinput>
 &prompt.root; <userinput>make cleandir && make cleandir && make depend && make all</userinput>
 &prompt.root; <userinput>cd /usr/src/libexec/named-xfer</userinput>
 &prompt.root; <userinput>make cleandir && make cleandir && make depend && make NOSHARED=yes all</userinput>
 &prompt.root; <userinput>cp named-xfer /etc/namedb/bin && chmod 555 /etc/namedb/bin/named-xfer</userinput><co id="clean-cruft"></screen>
 
 	  <para>After your statically linked
 	    <command>named-xfer</command> is installed some cleaning up
 	    is required, to avoid leaving stale copies of libraries or
 	    programs in your source tree:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/src/lib/libisc</userinput>
 &prompt.root; <userinput>make cleandir</userinput>
 &prompt.root; <userinput>cd /usr/src/lib/libbind</userinput>
 &prompt.root; <userinput>make cleandir</userinput>
 &prompt.root; <userinput>cd /usr/src/libexec/named-xfer</userinput>
 &prompt.root; <userinput>make cleandir</userinput></screen>
 
 	  <calloutlist>
 	    <callout arearefs="clean-cruft">
 	      <para>This step has been reported to fail occasionally.  If this
 		happens to you, then issue the command:</para>
 
 	      <screen>&prompt.root; <userinput>cd /usr/src && make cleandir && make cleandir</userinput></screen>
 
 	      <para>and delete your <filename>/usr/obj</filename> tree:</para>
 
 	      <screen>&prompt.root; <userinput>rm -fr /usr/obj && mkdir /usr/obj</userinput></screen>
 
 		<para>This will clean out any <quote>cruft</quote> from your
 		  source tree, and retrying the steps above should then work.</para>
 	    </callout>
 	  </calloutlist>
 
 	  <para>If you are running &os; version 4.9-RELEASE or later,
 	    then the copy of <command>named-xfer</command> in
 	    <filename>/usr/libexec</filename> is statically linked by
 	    default, and you can simply use &man.cp.1; to copy it into
 	    your sandbox.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Make a <filename>dev/null</filename> that
 	    <application>named</application> can see and write to:</para>
 
 	  <screen>&prompt.root; <userinput>cd /etc/namedb/dev && mknod null c 2 2</userinput>
 &prompt.root; <userinput>chmod 666 null</userinput></screen>
 	</listitem>
 
 	<listitem>
 	  <para>Symlink <filename> /var/run/ndc</filename> to
 	    <filename>/etc/namedb/var/run/ndc</filename>:</para>
 
 	  <screen>&prompt.root; <userinput>ln -sf /etc/namedb/var/run/ndc /var/run/ndc</userinput></screen>
 
 	  <note>
 	    <para>This simply avoids having to specify the
 	      <option>-c</option> option to &man.ndc.8; every time you
 	      run it.  Since the contents of
 	      <filename>/var/run</filename> are deleted on boot, it may
 	      be useful to add this command to
 	      <username>root</username>'s &man.crontab.5;, using the
 	      <option>@reboot</option> option.</para>
 	  </note>
 
 	</listitem>
 
 	<listitem>
 
         <indexterm><primary>syslog</primary></indexterm>
         <indexterm><primary>log files</primary>
 	  <secondary>named</secondary></indexterm>
 
 	  <para>Configure &man.syslogd.8; to create an extra
 	    <devicename>log</devicename> socket that
 	    <application>named</application> can write to.  To do this,
 	    add <literal>-l /etc/namedb/dev/log</literal> to the
 	    <varname>syslogd_flags</varname> variable in
 	    <filename>/etc/rc.conf</filename>.</para>
 	</listitem>
 
 	<listitem>
 
           <indexterm><primary><command>chroot</command></primary></indexterm>
 
 	  <para>Arrange to have <application>named</application> start
 	    and <command>chroot</command> itself to the sandbox by
 	    adding the following to
 	    <filename>/etc/rc.conf</filename>:</para>
 
 	  <programlisting>named_enable="YES"
 named_flags="-u bind -g bind -t /etc/namedb /etc/named.conf"</programlisting>
 
 	  <note>
 	    <para>Note that the configuration file
 	    <replaceable>/etc/named.conf</replaceable> is denoted by a full
 	    pathname <emphasis>relative to the sandbox</emphasis>, i.e. in
 	    the line above, the file referred to is actually
 	    <filename>/etc/namedb/etc/named.conf</filename>.</para>
 	  </note>
 	</listitem>
       </itemizedlist>
 
       <para>The next step is to edit
 	<filename>/etc/namedb/etc/named.conf</filename> so that
 	<application>named</application> knows which zones to load and
 	where to find them on the disk.  There follows a commented
 	example (anything not specifically commented here is no
 	different from the setup for a DNS server not running in a
 	sandbox):</para>
 
 	<programlisting>options {
         directory "/";<co id="directory">
         named-xfer "/bin/named-xfer";<co id="named-xfer">
         version "";		// Don't reveal BIND version
         query-source address * port 53;
 };
 // ndc control socket
 controls {
         unix "/var/run/ndc" perm 0600 owner 0 group 0;
 };
 // Zones follow:
 zone "localhost" IN {
         type master;
         file "master/named.localhost";<co id="master">
         allow-transfer { localhost; };
         notify no;
 };
 zone "0.0.127.in-addr.arpa" IN {
         type master;
         file "master/localhost.rev";
         allow-transfer { localhost; };
         notify no;
 };
 zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.int" {
 	type master;
 	file "master/localhost-v6.rev";
 	allow-transfer { localhost; };
 	notify no;
 };
 zone "." IN {
         type hint;
         file "master/named.root";
 };
 zone "private.example.net" in {
         type master;
         file "master/private.example.net.db";
 	allow-transfer { 192.168.10.0/24; };
 };
 zone "10.168.192.in-addr.arpa" in {
         type slave;
         masters { 192.168.10.2; };
         file "slave/192.168.10.db";<co id="slave">
 };</programlisting>
 
       <calloutlist>
 	<callout arearefs="directory">
 	  <para>The
 	    <literal>directory</literal> statement is specified as
 	    <filename>/</filename>, since all files that
 	    <application>named</application> needs are within this
 	    directory (recall that this is equivalent to a
 	    <quote>normal</quote> user's
 	    <filename>/etc/namedb</filename>).</para>
 	</callout>
 
 	<callout arearefs="named-xfer">
 	  <para>Specifies the full path
 	    to the <command>named-xfer</command> binary (from
 	    <application>named</application>'s frame of reference).  This
 	    is necessary since <application>named</application> is
 	    compiled to look for <command>named-xfer</command> in
 	    <filename>/usr/libexec</filename> by default.</para>
 	</callout>
 	<callout arearefs="master"><para>Specifies the filename (relative
 	  to the <literal>directory</literal> statement above) where
 	  <application>named</application> can find the zone file for this
 	  zone.</para>
 	</callout>
 	<callout arearefs="slave"><para>Specifies the filename
 	    (relative to the <literal>directory</literal> statement above)
 	    where <application>named</application> should write a copy of
 	    the zone file for this zone after successfully transferring it
 	    from the master server.  This is why we needed to change the
 	    ownership of the directory <filename>slave</filename> to
 	    <groupname>bind</groupname> in the setup stages above.</para>
 	</callout>
       </calloutlist>
 
       <para>After completing the steps above, either reboot your
 	server or restart &man.syslogd.8; and start &man.named.8;, making
 	sure to use the new options specified in
 	<varname>syslogd_flags</varname> and
 	<varname>named_flags</varname>.  You should now be running a
 	sandboxed copy of <application>named</application>!</para>
 
     </sect2>
 
     <sect2>
       <title>Security</title>
 
       <para>Although BIND is the most common implementation of DNS,
         there is always the issue of security.  Possible and
         exploitable security holes are sometimes found.
       </para>
 
       <para>
         It is a good idea to read <ulink
         url="http://www.cert.org/">CERT</ulink>'s security advisories and
 	to subscribe to the &a.security-notifications;
         to stay up to date with the current Internet and FreeBSD security
         issues.
       </para>
 
       <tip><para>If a problem arises, keeping sources up to date and
         having a fresh build of <application>named</application> would
         not hurt.</para></tip>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
 
       <para>BIND/<application>named</application> manual pages:
       &man.ndc.8; &man.named.8; &man.named.conf.5;</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><ulink
 	      url="http://www.isc.org/products/BIND/">Official ISC BIND
 	      Page</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	  url="http://www.nominum.com/getOpenSourceResource.php?id=6">
 	  BIND FAQ</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink url="http://www.oreilly.com/catalog/dns4/">O'Reilly
          DNS and BIND 4th Edition</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="ftp://ftp.isi.edu/in-notes/rfc1034.txt">RFC1034
 	      - Domain Names - Concepts and Facilities</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="ftp://ftp.isi.edu/in-notes/rfc1035.txt">RFC1035
 	      - Domain Names - Implementation and Specification</ulink></para>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="network-bind9">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Rhodes</surname>
 	  <contrib>Written by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title><acronym>BIND</acronym>9 and &os;</title>
 
 <!-- This section is here to get users up with BIND9 configurations!  It
   does not cover the terminology, theoretical discussion (why run a name
   server) or the further reading which is still in the previous section.
   I did things this way to avoid repetition of content and obviously we
   cannot just remove the previous section since other supported releases
   use it.  When the previous section is removed then those comments
   should be moved here.  // Tom Rhodes -->
 
     <indexterm><primary>bind9</primary>
       <secondary>setting up</secondary></indexterm>
 
     <para>The release of &os;&nbsp;5.3 brought the
       <acronym>BIND</acronym>9 <acronym>DNS</acronym> server software
       into the distribution.  New security features, a new file system
       layout and automated &man.chroot.8; configuration came with the
       import.  This section has been written in two parts, the first
       will discuss new features and their configuration; the latter
       will cover upgrades to aid in move to &os;&nbsp;5.3.  From this
       moment on, the server will be referred to simply as
       &man.named.8; in place of <acronym>BIND</acronym>.  This section
       skips over the terminology described in the previous section as
       well as some of the theoretical discussions; thus, it is
       recommended that the previous section be consulted before reading
       any further here.</para>
 
     <para>Configuration files for <application>named</application> currently
       reside in
       <filename class="directory">/var/named/etc/namedb/</filename> and
       will need modification before use.  This is where most of the
       configuration will be performed.</para>
 
     <sect2>
       <title>Configuration of a Master Zone</title>
 
       <para>To configure a master zone visit
 	<filename class="directory">/var/named/etc/namedb/</filename>
 	and run the following command:</para>
 
       <screen>&prompt.root; <userinput>sh make-localhost</userinput></screen>
 
       <para>If all went well a new file should exist in the
 	<filename class="directory">master</filename> directory.  The
 	filenames should be <filename>localhost.rev</filename> for
 	the local domain name and <filename>localhost-v6.rev</filename>
 	for <acronym>IPv6</acronym> configurations.  As the default
 	configuration file, configuration for its use will already
 	be present in the <filename>named.conf</filename> file.</para>
     </sect2>
 
     <sect2>
       <title>Configuration of a Slave Zone</title>
 
       <para>Configuration for extra domains or sub domains may be
 	done properly by setting them as a slave zone.  In most cases,
 	the <filename>master/localhost.rev</filename> file could just be
 	copied over into the <filename class="directory">slave</filename>
 	directory and modified.  Once completed, the files need
 	to be properly added in <filename>named.conf</filename> such
 	as in the following configuration for
 	<hostid role="domainname">example.com</hostid>:</para>
 
       <programlisting>zone "example.com" {
         type slave;
         file "slave/example.com";
         masters {
                 10.0.0.1;
         };
 };
 
 zone "0.168.192.in-addr.arpa" {
         type slave;
         file "slave/0.168.192.in-addr.arpa";
         masters {
                 10.0.0.1;
         };
 };</programlisting>
 
       <para>Note well that in this example, the master
 	<acronym>IP</acronym> address is the primary domain server
 	from which the zones are transferred; it does not necessary serve
 	as <acronym>DNS</acronym> server itself.</para>
     </sect2>
 
     <sect2>
       <title>System Initialization Configuration</title>
 
       <para>In order for the <application>named</application> daemon to start
 	when the system is booted, the following option must be present
 	in the <filename>rc.conf</filename> file:</para>
 
       <programlisting>named_enable="YES"</programlisting>
 
       <para>While other options exist, this is the bare minimal
 	requirement.  Consult the &man.rc.conf.5; manual page for
 	a list of the other options.  If nothing is entered in the
 	<filename>rc.conf</filename> file then <application>named</application>
 	may be started on the command line by invoking:</para>
 
       <screen>&prompt.root; <userinput>/etc/rc.d/named start</userinput></screen>
     </sect2>
 
     <sect2>
       <title><acronym>BIND</acronym>9 Security</title>
 
       <para>While &os; automatically drops <application>named</application>
 	into a &man.chroot.8; environment; there are several other
 	security mechanisms in place which could help to lure off
 	possible <acronym>DNS</acronym> service attacks.</para>
 
       <sect3>
 	<title>Query Access Control Lists</title>
 
 	<para>A query access control list can be used to restrict
 	  queries against the zones.  The configuration works by
 	  defining the network inside of the <literal>acl</literal>
 	  token and then listing <acronym>IP</acronym> addresses in
 	  the zone configuration.  To permit domains to query the
 	  example host, just define it like this:</para>
 
 	<programlisting>acl "example.com" {
         192.168.0.0/24;
 };
 
 zone "example.com" {
         type slave;
         file "slave/example.com";
         masters {
                 10.0.0.1;
         };
 	allow-query { example.com; };
 };
 
 zone "0.168.192.in-addr.arpa" {
         type slave;
         file "slave/0.168.192.in-addr.arpa";
         masters {
                 10.0.0.1;
         };
 	allow-query { example.com; };
 };</programlisting>
       </sect3>
 
       <sect3>
 	<title>Restrict Version</title>
 
 	<para>Permitting version lookups on the <acronym>DNS</acronym>
 	  server could be opening the doors for an attacker.  A
 	  malicious user may use this information to hunt up known
 	  exploits or bugs to utilize against the host.  A false version
 	  string can be placed the <literal>options</literal> section of
 	  <filename>named.conf</filename>:</para>
 
 	<programlisting>options {
         directory       "/etc/namedb";
         pid-file        "/var/run/named/pid";
         dump-file       "/var/dump/named_dump.db";
         statistics-file "/var/stats/named.stats";
 	version		"None of your business";</programlisting>
       </sect3>
 <!-- Here is where I stopped for now
       <sect3>
         <title>Authentication</title>
 
 	<para> ... </para>
 
 -->
     </sect2>
   </sect1>
 
 
   <sect1 id="network-apache">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Murray</firstname>
 	  <surname>Stokely</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Apache HTTP Server</title>
 
-    <indexterm><primary>web server</primary>
+    <indexterm><primary>web servers</primary>
       <secondary>setting up</secondary></indexterm>
     <indexterm><primary>Apache</primary></indexterm>
 
     <sect2>
       <title>Overview</title>
 
       <para>&os; is used to run some of the busiest web sites in the
         world.  The majority of web servers on the Internet are using
         the <application>Apache HTTP Server</application>.
         <application>Apache</application> software packages should be
         included on your FreeBSD installation media.  If you did not
         install <application>Apache</application> when you first
         installed FreeBSD, then you can install it from the <filename
         role="package">www/apache13</filename> or <filename
         role="package">www/apache2</filename> port.</para>
 
       <para>Once <application>Apache</application> has been installed
         successfully, it must be configured.</para>
 
       <note><para>This section covers version 1.3.X of the
         <application>Apache HTTP Server</application> as that is the
         most widely used version for &os;.  <application>Apache&nbsp;2.X</application> introduces many
         new technologies but they are not discussed here.  For more
         information about <application>Apache&nbsp;2.X</application>, please see <ulink
         url="http://httpd.apache.org/"></ulink>.</para></note>
 
     </sect2>
 
     <sect2>
       <title>Configuration</title>
 
       <indexterm><primary>Apache</primary>
 	<secondary>configuration file</secondary></indexterm>
 
       <para>The main <application>Apache HTTP Server</application> configuration file is
 	installed as
 	<filename>/usr/local/etc/apache/httpd.conf</filename> on &os;.
 	This file is a typical &unix; text configuration file with
 	comment lines beginning with the <literal>#</literal>
 	character.  A comprehensive description of all possible
 	configuration options is outside the scope of this book, so
 	only the most frequently modified directives will be described
 	here.</para>
 
       <variablelist>
 	<varlistentry>
 	  <term><literal>ServerRoot "/usr/local"</literal></term>
 
 	  <listitem>
 	    <para>This specifies the default directory hierarchy for
 	    the <application>Apache</application> installation.  Binaries are stored in the
 	    <filename class="directory">bin</filename> and 
 	    <filename class="directory">sbin</filename> subdirectories
 	    of the server root, and configuration files are stored in
 	    <filename class="directory">etc/apache</filename>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>ServerAdmin you@your.address</literal></term>
 
 	  <listitem>
 	    <para>The address to which problems with the server should
 	      be emailed.  This address appears on some
 	      server-generated pages, such as error documents.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>ServerName www.example.com</literal></term>
 
 	  <listitem>
 	    <para><literal>ServerName</literal> allows you to set a host name which is
 	      sent back to clients for your server if it is different
 	      to the one that the host is configured with (i.e., use <hostid>www</hostid>
 	      instead of the host's real name).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>DocumentRoot "/usr/local/www/data"</literal></term>
 
 	  <listitem>
 	    <para><literal>DocumentRoot</literal>: The directory out of which you will
 	      serve your documents. By default, all requests are taken
 	      from this directory, but symbolic links and aliases may
 	      be used to point to other locations.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
       <para>It is always a good idea to make backup copies of your
 	<application>Apache</application> configuration file before making changes.  Once you are
 	satisfied with your initial configuration you are ready to
 	start running <application>Apache</application>.</para>
 
 <!-- sect3 for performance tuning directives?  maxservers minservers -->
 <!-- etc..?? -->
 
 <!-- Advanced configuration section.
 
 Performance tuning directives.
 
 Log file format -->
 
     </sect2>
 
     <sect2>
       <title>Running <application>Apache</application></title>
 
       <indexterm><primary>Apache</primary>
 	<secondary>starting or stopping</secondary></indexterm>
 
       <para><application>Apache</application> does not run from the
         <application>inetd</application> super server as many other
         network servers do.  It is configured to run standalone for
         better performance for incoming HTTP requests from client web
         browsers.  A shell script wrapper is included to make
         starting, stopping, and restarting the server as simple as
         possible.  To start up <application>Apache</application> for
         the first time, just run:</para>
 
       <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl start</userinput></screen>
 
       <para>You can stop the server at any time by typing :</para>
 
       <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl stop</userinput></screen>
 
       <para>After making changes to the configuration file for any
       reason, you will need to restart the server:</para>
 
       <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl restart</userinput></screen>
 
       <para>To restart <application>Apache</application> without
 	aborting current connections, run:</para>
 
       <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl graceful</userinput></screen>
 
       <para>Additional information available at
 	&man.apachectl.8; manual page.</para>
 
       <para>To launch <application>Apache</application> at system
         startup, add the following line to
         <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>apache_enable="YES"</programlisting>
 
       <para>If you would like to supply additional command line
 	options for the <application>Apache</application>
 	<command>httpd</command> program started at system boot, you
 	may specify them with an additional line in
 	<filename>rc.conf</filename>:</para>
 
       <programlisting>apache_flags=""</programlisting>
 
       <para>Now that the web server is running, you can view your web
         site by pointing a web browser to
         <literal>http://localhost/</literal>.  The default web page
         that is displayed is
         <filename>/usr/local/www/data/index.html</filename>.</para>
 
     </sect2>
 
     <sect2>
       <title>Virtual Hosting</title>
 
       <para><application>Apache</application> supports two different
 	types of Virtual Hosting. The first method is Name-based
 	Virtual Hosting. Name-based virtual hosting uses the clients
 	HTTP/1.1 headers to figure out the hostname. This allows many
 	different domains to share the same IP address.</para>
 
       <para>To setup <application>Apache</application> to use
         Name-based Virtual Hosting add an entry like the following to
         your <filename>httpd.conf</filename>:</para>
 
       <programlisting>NameVirtualHost *</programlisting>
 
       <para>If your webserver was named <hostid role="fqdn">www.domain.tld</hostid> and
         you wanted to setup a virtual domain for
         <hostid role="fqdn">www.someotherdomain.tld</hostid> then you would add
         the following entries to
         <filename>httpd.conf</filename>:</para>
 
       <screen>&lt;VirtualHost *&gt;
 ServerName www.domain.tld
 DocumentRoot /www/domain.tld
 &lt;VirtualHost&gt;
 
 &lt;VirtualHost *&gt;
 ServerName www.someotherdomain.tld
 DocumentRoot /www/someotherdomain.tld
 &lt;/VirtualHost&gt;</screen>
 
       <para>Replace the addresses with the addresses you want to use
         and the path to the documents with what you are using.</para>
 
       <para>For more information about setting up virtual hosts,
         please consult the official <application>Apache</application>
         documentation at: <ulink
         url="http://httpd.apache.org/docs/vhosts/"></ulink></para>
 
     </sect2>
 
     <sect2>
       <title>Apache Modules</title>
 
       <indexterm><primary>Apache</primary>
 	<secondary>modules</secondary></indexterm>
 
       <para>There are many different <application>Apache</application> modules available to add
         functionality to the basic server.  The FreeBSD Ports
         Collection provides an easy way to install
         <application>Apache</application> together with some of the
         more popular add-on modules.</para>
 
       <sect3>
         <title>mod_ssl</title>
 
-	<indexterm><primary>web server</primary>
+	<indexterm><primary>web servers</primary>
           <secondary>secure</secondary></indexterm>
 	<indexterm><primary>SSL</primary></indexterm>
 	<indexterm><primary>cryptography</primary></indexterm>
 
         <para>The <application>mod_ssl</application> module uses the OpenSSL library to provide
           strong cryptography via the Secure Sockets Layer (SSL v2/v3)
           and Transport Layer Security (TLS v1) protocols.  This
           module provides everything necessary to request a signed
           certificate from a trusted certificate signing authority so
           that you can run a secure web server on &os;.</para>
 
 	<para>If you have not yet installed
 	  <application>Apache</application>, then a version of <application>Apache</application>
 	  1.3.X that includes <application>mod_ssl</application> may be installed with the <filename
 	  role="package">www/apache13-modssl</filename> port.  SSL
 	  support is also available for <application>Apache&nbsp;2.X</application> in the
 	  <filename role="package">www/apache2</filename> port,
 	  where it is enabled by default.</para>
 
 <!-- XXX add more information about configuring mod_ssl here. -->
 <!-- Generating keys, getting the key signed, setting up your secure -->
 <!-- web server! -->
       </sect3>
 
       <sect3>
         <title>mod_perl</title>
 
 	<indexterm><primary>Perl</primary></indexterm>
 
         <para>The <application>Apache</application>/Perl integration project brings together the
 	  full power of the Perl programming language and the <application>Apache
 	  HTTP Server</application>.  With the <application>mod_perl</application> module it is possible to
 	  write <application>Apache</application> modules entirely in Perl.  In addition, the
 	  persistent interpreter embedded in the server avoids the
 	  overhead of starting an external interpreter and the penalty
 	  of Perl start-up time.</para>
 
 	<para>If you have not yet installed
 	  <application>Apache</application>, then a version of <application>Apache</application>
 	  that includes <application>mod_perl</application> may be installed with the <filename
 	  role="package">www/apache13-modperl</filename> port.</para>
       </sect3>
 
       <sect3>
         <title>PHP</title>
 
 	<indexterm><primary>PHP</primary></indexterm>
 
         <para>PHP, which stands for <quote>PHP: Hypertext
 	  Preprocessor</quote> is a widely-used Open Source
 	  general-purpose scripting language that is especially suited
 	  for Web development and can be embedded into HTML.  Its
 	  syntax draws upon C, &java;, and Perl, and is easy to learn.
 	  The main goal of the language is to allow web developers to
 	  write dynamically generated webpages quickly, but you can do
 	  much more with PHP.</para>
 
 	<para>PHP may be installed from the <filename
 	  role="package">lang/php5</filename> port.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="network-ftp">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Murray</firstname>
 	  <surname>Stokely</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>File Transfer Protocol (FTP)</title>
 
     <indexterm><primary>FTP servers</primary></indexterm>
 
     <sect2>
       <title>Overview</title>
 
       <para>The File Transfer Protocol (FTP) provides users with a
 	simple way to transfer files to and from an <acronym
 	role="File Transfer Protocol">FTP</acronym> server.  &os;
 	includes <acronym role="File Transfer Protocol">FTP</acronym>
 	server software, <application>ftpd</application>, in the base
 	system.  This makes setting up and administering an <acronym
 	role="File Transfer Protocol">FTP</acronym> server on FreeBSD
 	very straightforward.</para>
     </sect2>
 
     <sect2>
       <title>Configuration</title>
 
       <para>The most important configuration step is deciding which
 	accounts will be allowed access to the FTP server.  A normal
 	FreeBSD system has a number of system accounts used for
 	various daemons, but unknown users should not be allowed to
 	log in with these accounts.  The
 	<filename>/etc/ftpusers</filename> file is a list of users
 	disallowed any FTP access.  By default, it includes the
 	aforementioned system accounts, but it is possible to add
 	specific users here that should not be allowed access to
 	FTP.</para>
 
       <para>You may want to restrict the access of some users without
 	preventing them completely from using FTP.  This can be
 	accomplished with the <filename>/etc/ftpchroot</filename>
 	file.  This file lists users and groups subject to FTP access
 	restrictions.  The &man.ftpchroot.5; manual page has all of
 	the details so it will not be described in detail here.</para>
 
+      <indexterm>
+	<primary>FTP</primary>
+	<secondary>anonymous</secondary>
+      </indexterm>
+
       <para>If you would like to enable anonymous FTP access to your
 	server, then you must create a user named
 	<username>ftp</username> on your &os; system.  Users will then
 	be able to log on to your FTP server with a username of
 	<username>ftp</username> or <username>anonymous</username> and
 	with any password (by convention an email address for the user
 	should be used as the password).  The FTP server will call
 	&man.chroot.2; when an anonymous user logs in, to restrict
 	access to only the home directory of the
 	<username>ftp</username> user.</para>
 
       <para>There are two text files that specify welcome messages to
 	be displayed to FTP clients.  The contents of the file
 	<filename>/etc/ftpwelcome</filename> will be displayed to
 	users before they reach the login prompt.  After a successful
 	login, the contents of the file
 	<filename>/etc/ftpmotd</filename> will be displayed.  Note
 	that the path to this file is relative to the login environment, so the
 	file <filename>~ftp/etc/ftpmotd</filename> would be displayed
 	for anonymous users.</para>
 
       <para>Once the FTP server has been configured properly, it must
         be enabled in <filename>/etc/inetd.conf</filename>.  All that
         is required here is to remove the comment symbol
         <quote>#</quote> from in front of the existing
         <application>ftpd</application> line :</para>
 
       <programlisting>ftp	stream	tcp	nowait	root	/usr/libexec/ftpd	ftpd -l</programlisting>
 
       <para>As explained in <xref linkend="network-inetd-hangup">, a
         HangUP Signal must be sent to <application>inetd</application>
         after this configuration file is changed.</para>
 
       <para>You can now log on to your FTP server by typing:</para>
 
       <screen>&prompt.user; <userinput>ftp localhost</userinput></screen>
 
     </sect2>
 
     <sect2>
       <title>Maintaining</title>
 
       <indexterm><primary>syslog</primary></indexterm>
       <indexterm><primary>log files</primary>
 	<secondary>FTP</secondary></indexterm>
 
       <para>The <application>ftpd</application> daemon uses
         &man.syslog.3; to log messages.  By default, the system log
         daemon will put messages related to FTP in the
         <filename>/var/log/xferlog</filename> file.  The location of
         the FTP log can be modified by changing the following line in
         <filename>/etc/syslog.conf</filename>:</para>
 
       <programlisting>ftp.info      /var/log/xferlog</programlisting>
 
+      <indexterm>
+	<primary>FTP</primary>
+	<secondary>anonymous</secondary>
+      </indexterm>
+
       <para>Be aware of the potential problems involved with running
         an anonymous FTP server.  In particular, you should think
         twice about allowing anonymous users to upload files.  You may
         find that your FTP site becomes a forum for the trade of
         unlicensed commercial software or worse.  If you do need to
         allow anonymous FTP uploads, then you should set up the
         permissions so that these files can not be read by other
         anonymous users until they have been reviewed.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="network-samba">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Murray</firstname>
 	  <surname>Stokely</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>File and Print Services for &microsoft.windows; clients (Samba)</title>
 
     <indexterm><primary>Samba server</primary></indexterm>
     <indexterm><primary>Microsoft Windows</primary></indexterm>
     <indexterm>
       <primary>file server</primary>
       <secondary>Windows clients</secondary>
     </indexterm>
     <indexterm>
       <primary>print server</primary>
       <secondary>Windows clients</secondary>
     </indexterm>
 
     <sect2>
       <title>Overview</title>
 
       <para><application>Samba</application> is a popular open source
         software package that provides file and print services for
         &microsoft.windows; clients.  Such clients can connect to and
         use FreeBSD filespace as if it was a local disk drive, or
         FreeBSD printers as if they were local printers.</para>
 
       <para><application>Samba</application> software packages should
         be included on your FreeBSD installation media.  If you did
         not install <application>Samba</application> when you first
         installed FreeBSD, then you can install it from the <filename
         role="package">net/samba3</filename> port or package.</para>
 
 <!-- mention LDAP, Active Directory, WinBIND, ACL, Quotas, PAM, .. -->
 
     </sect2>
 
     <sect2>
       <title>Configuration</title>
 
       <para>A default <application>Samba</application> configuration
         file is installed as
         <filename>/usr/local/etc/smb.conf.default</filename>.  This
         file must be copied to
         <filename>/usr/local/etc/smb.conf</filename> and customized
         before <application>Samba</application> can be used.</para>
 
       <para>The <filename>smb.conf</filename> file contains runtime
         configuration information for
         <application>Samba</application>, such as definitions of the
         printers and <quote>filesystem shares</quote> that you would
         like to share with &windows; clients.  The
         <application>Samba</application> package includes a web based
         tool called <application>swat</application> which provides a
         simple way of configuring the <filename>smb.conf</filename>
         file.</para>
 
       <sect3>
 	<title>Using the Samba Web Administration Tool (SWAT)</title>
 
 	<para>The Samba Web Administration Tool (SWAT) runs as a
 	  daemon from <application>inetd</application>.  Therefore, the
 	  following line in <filename>/etc/inetd.conf</filename>
 	  should be uncommented before <application>swat</application> can be
 	  used to configure <application>Samba</application>:</para>
 
 	<programlisting>swat   stream  tcp     nowait/400      root    /usr/local/sbin/swat</programlisting>
         <para>As explained in <xref linkend="network-inetd-hangup">, a
           HangUP Signal must be sent to
           <application>inetd</application> after this configuration
           file is changed.</para>
 
 	<para>Once <application>swat</application> has been enabled in
 	  <filename>inetd.conf</filename>, you can use a browser to
 	  connect to <ulink url="http://localhost:901"></ulink>.  You will
 	  first have to log on with the system <username>root</username> account.</para>
 
 <!-- XXX screenshots go here, loader is creating them -->
 
 	<para>Once you have successfully logged on to the main
 	  <application>Samba</application> configuration page, you can
 	  browse the system documentation, or begin by clicking on the
 	  <guimenu>Globals</guimenu> tab.  The <guimenu>Globals</guimenu> section corresponds to the
 	  variables that are set in the <literal>[global]</literal>
 	  section of
 	  <filename>/usr/local/etc/smb.conf</filename>.</para>
       </sect3>
 
       <sect3>
 	<title>Global Settings</title>
 
 	<para>Whether you are using <application>swat</application> or
 	  editing <filename>/usr/local/etc/smb.conf</filename>
 	  directly, the first directives you are likely to encounter
 	  when configuring <application>Samba</application>
 	  are:</para>
 
         <variablelist>
 	  <varlistentry>
 	    <term><literal>workgroup</literal></term>
 
 	    <listitem>
 	      <para>NT Domain-Name or Workgroup-Name for the computers
 	        that will be accessing this server.</para>
 	    </listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>netbios name</literal></term>
 	    <indexterm><primary>NetBIOS</primary></indexterm>
 
 	    <listitem>
 	      <para>This sets the NetBIOS name by which a <application>Samba</application> server
 		is known. By default it is the same as the first
 		component of the host's DNS name.</para>
 	    </listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>server string</literal></term>
 
 	    <listitem>
 	      <para>This sets the string that will be displayed with
 		the <command>net view</command> command and some other
 		networking tools that seek to display descriptive text
 		about the server.</para>
 	    </listitem>
 	  </varlistentry>
         </variablelist>
       </sect3>
 
       <sect3>
 	<title>Security Settings</title>
 
 	<para>Two of the most important settings in
 	  <filename>/usr/local/etc/smb.conf</filename> are the
 	  security model chosen, and the backend password format for
 	  client users.  The following directives control these
 	  options:</para>
 
         <variablelist>
 	  <varlistentry>
 	    <term><literal>security</literal></term>
 
 	    <listitem>
 	      <para>The two most common options here are
 	        <literal>security = share</literal> and <literal>security
 	        = user</literal>.  If your clients use usernames that
 	        are the same as their usernames on your &os; machine
 	        then you will want to use user level security.  This
 	        is the default security policy and it requires clients
 	        to first log on before they can access shared
 	        resources.</para>
 
 	      <para>In share level security, client do not need to log
 	        onto the server with a valid username and password
 	        before attempting to connect to a shared resource.
 	        This was the default security model for older versions
 	        of <application>Samba</application>.</para>
 	    </listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>passdb backend</literal></term>
 
 	    <indexterm><primary>NIS+</primary></indexterm>
 	    <indexterm><primary>LDAP</primary></indexterm>
 	    <indexterm><primary>SQL database</primary></indexterm>
 
 	    <listitem>
 	      <para><application>Samba</application> has several
 	        different backend authentication models.  You can
 	        authenticate clients with LDAP, NIS+, a SQL database,
 	        or a modified password file.  The default
 	        authentication method is <literal>smbpasswd</literal>,
 	        and that is all that will be covered here.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
 	<para>Assuming that the default <literal>smbpasswd</literal>
 	  backend is used, the
 	  <filename>/usr/local/private/smbpasswd</filename> file must
 	  be created to allow <application>Samba</application> to
 	  authenticate clients.  If you would like to give all of
 	  your &unix; user accounts access from &windows; clients, use the
 	  following command:</para>
 
 	<screen>&prompt.root; <userinput>grep -v "^#" /etc/passwd | make_smbpasswd &gt; /usr/local/private/smbpasswd</userinput>
 &prompt.root; <userinput>chmod 600 /usr/local/private/smbpasswd</userinput></screen>
 
 	<para>Please see the <application>Samba</application>
 	  documentation for additional information about configuration
 	  options.  With the basics outlined here, you should have
 	  everything you need to start running
 	  <application>Samba</application>.</para>
       </sect3>
 
     </sect2>
     <sect2>
       <title>Starting <application>Samba</application></title>
 
       <para>To enable <application>Samba</application> when your
         system boots, add the following line to
         <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>samba_enable="YES"</programlisting>
 
       <para>You can then start <application>Samba</application> at any
         time by typing:</para>
 
       <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/samba.sh start</userinput>
 Starting SAMBA: removing stale tdbs :
 Starting nmbd.
 Starting smbd.</screen>
 
       <para><application>Samba</application> actually consists of
         three separate daemons.  You should see that both the
         <application>nmbd</application> and <application>smbd</application> daemons
         are started by the <filename>samba.sh</filename> script.  If
         you enabled winbind name resolution services in
         <filename>smb.conf</filename>, then you will also see that
         the <application>winbindd</application> daemon is started.</para>
 
       <para>You can stop <application>Samba</application> at any time
         by typing :</para>
 
       <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/samba.sh stop</userinput></screen>
 
       <para><application>Samba</application> is a complex software
         suite with functionality that allows broad integration with
         &microsoft.windows; networks.  For more information about
         functionality beyond the basic installation described here,
         please see <ulink url="http://www.samba.org"></ulink>.</para>
     </sect2>
 
   </sect1>
 
   <sect1 id="network-ntp">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Hukins</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Clock Synchronization with NTP</title>
 
     <indexterm><primary>NTP</primary></indexterm>
 
     <sect2>
       <title>Overview</title>
 
       <para>Over time, a computer's clock is prone to drift.  The
 	Network Time Protocol (NTP) is one way to ensure your clock stays
 	accurate.</para>
 
       <para>Many Internet services rely on, or greatly benefit from,
 	computers' clocks being accurate.  For example, a web server
 	may receive requests to send a file if it has been modified since a
 	certain time.  In a local area network environment, it is
 	essential that computers sharing files from the same file
 	server have synchronized clocks so that file timestamps stay
 	consistent.  Services such as &man.cron.8; also rely on
 	an accurate system clock to run commands at the specified
 	times.</para>
 
       <indexterm>
 	<primary>NTP</primary>
 	<secondary>ntpd</secondary>
       </indexterm>
       <para>FreeBSD ships with the &man.ntpd.8; <acronym role="Network
 	Time Protocol">NTP</acronym> server which can be used to query
 	other <acronym role="Network Time Protocol">NTP</acronym>
 	servers to set the clock on your machine or provide time
 	services to others.</para>
     </sect2>
 
     <sect2>
       <title>Choosing Appropriate NTP Servers</title>
 
       <indexterm>
 	<primary>NTP</primary>
 	<secondary>choosing servers</secondary>
       </indexterm>
 
       <para>In order to synchronize your clock, you will need to find
 	one or more <acronym role="Network Time
 	Protocol">NTP</acronym> servers to use.  Your network
 	administrator or ISP may have set up an NTP server for this
 	purpose&mdash;check their documentation to see if this is the
 	case.  There is an <ulink
 	url="http://ntp.isc.org/bin/view/Servers/WebHome">online
 	list of publicly accessible NTP servers</ulink> which you can
 	use to find an NTP server near to you.  Make sure you are
 	aware of the policy for any servers you choose, and ask for
 	permission if required.</para>
 
       <para>Choosing several unconnected NTP servers is a good idea in
 	case one of the servers you are using becomes unreachable or
 	its clock is unreliable.  &man.ntpd.8; uses the responses it
 	receives from other servers intelligently&mdash;it will favor
 	unreliable servers less than reliable ones.</para>
     </sect2>
 
     <sect2>
       <title>Configuring Your Machine</title>
 
       <indexterm>
 	<primary>NTP</primary>
 	<secondary>configuration</secondary>
       </indexterm>
 
       <sect3>
 	<title>Basic Configuration</title>
 	<indexterm><primary>ntpdate</primary></indexterm>
 
 	<para>If you only wish to synchronize your clock when the
 	  machine boots up, you can use &man.ntpdate.8;.  This may be
 	  appropriate for some desktop machines which are frequently
 	  rebooted and only require infrequent synchronization, but
 	  most machines should run &man.ntpd.8;.</para>
 
 	<para>Using &man.ntpdate.8; at boot time is also a good idea
 	  for machines that run &man.ntpd.8;.  The &man.ntpd.8;
 	  program changes the clock gradually, whereas &man.ntpdate.8;
 	  sets the clock, no matter how great the difference between a
 	  machine's current clock setting and the correct time.</para>
 
 	<para>To enable &man.ntpdate.8; at boot time, add
 	  <literal>ntpdate_enable="YES"</literal> to
 	  <filename>/etc/rc.conf</filename>.  You will also need to
 	  specify all servers you wish to synchronize with and any
 	  flags to be passed to &man.ntpdate.8; in
 	  <varname>ntpdate_flags</varname>.</para>
       </sect3>
 
       <sect3>
 	<indexterm>
 	  <primary>NTP</primary>
 	  <secondary>ntp.conf</secondary>
 	</indexterm>
 
 	<title>General Configuration</title>
 
 	<para>NTP is configured by the
 	  <filename>/etc/ntp.conf</filename> file in the format
 	  described in &man.ntp.conf.5;.  Here is a simple
 	  example:</para>
 
 	<programlisting>server ntplocal.example.com prefer
 server timeserver.example.org
 server ntp2a.example.net
 
 driftfile /var/db/ntp.drift</programlisting>
 
 	<para>The <literal>server</literal> option specifies which
 	  servers are to be used, with one server listed on each line.
 	  If a server is specified with the <literal>prefer</literal>
 	  argument, as with <hostid
 	  role="fqdn">ntplocal.example.com</hostid>, that server is
 	  preferred over other servers.  A response from a preferred
 	  server will be discarded if it differs significantly from
 	  other servers' responses, otherwise it will be used without
 	  any consideration to other responses.  The
 	  <literal>prefer</literal> argument is normally used for NTP
 	  servers that are known to be highly accurate, such as those
 	  with special time monitoring hardware.</para>
 
 	<para>The <literal>driftfile</literal> option specifies which
 	  file is used to store the system clock's frequency offset.
 	  The &man.ntpd.8; program uses this to automatically
 	  compensate for the clock's natural drift, allowing it to
 	  maintain a reasonably correct setting even if it is cut off
 	  from all external time sources for a period of time.</para>
 
 	<para>The <literal>driftfile</literal> option specifies which
 	  file is used to store information about previous responses
 	  from the NTP servers you are using.  This file contains
 	  internal information for NTP.  It should not be modified by
 	  any other process.</para>
       </sect3>
 
       <sect3>
 	<title>Controlling Access to Your Server</title>
 
 	<para>By default, your NTP server will be accessible to all
 	  hosts on the Internet.  The <literal>restrict</literal>
 	  option in <filename>/etc/ntp.conf</filename> allows you to
 	  control which machines can access your server.</para>
 
 	<para>If you want to deny all machines from accessing your NTP
 	  server, add the following line to
 	  <filename>/etc/ntp.conf</filename>:</para>
 
         <programlisting>restrict default ignore</programlisting>
 
         <para>If you only want to allow machines within your own
 	  network to synchronize their clocks with your server, but
 	  ensure they are not allowed to configure the server or used
 	  as peers to synchronize against, add</para>
 
         <programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting>
 
 	<para>instead, where <hostid role="ipaddr">192.168.1.0</hostid> is
 	  an IP address on your network and <hostid
 	  role="netmask">255.255.255.0</hostid> is your network's
 	  netmask.</para>
 
 	<para><filename>/etc/ntp.conf</filename> can contain multiple
 	  <literal>restrict</literal> options.  For more details, see
 	  the <literal>Access Control Support</literal> subsection of
 	  &man.ntp.conf.5;.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Running the NTP Server</title>
 
       <para>To ensure the NTP server is started at boot time, add the
 	line <literal>ntpd_enable="YES"</literal> to
 	<filename>/etc/rc.conf</filename>.  If you wish to pass
 	additional flags to &man.ntpd.8;, edit the
 	<varname>ntpd_flags</varname> parameter in
 	<filename>/etc/rc.conf</filename>.</para>
 
       <para>To start the server without rebooting your machine, run
 	<command>ntpd</command> being sure to specify any additional
 	parameters from <varname>ntpd_flags</varname> in
 	<filename>/etc/rc.conf</filename>.  For example:</para>
 
       <screen>&prompt.root; <userinput>ntpd -p /var/run/ntpd.pid</userinput></screen>
 
       <note>
 	<para>Under &os;&nbsp;4.X,
 	  you have to replace every instance of <literal>ntpd</literal>
 	  with <literal>xntpd</literal> in the options above.</para></note>
     </sect2>
 
     <sect2>
       <title>Using ntpd with a Temporary Internet
 	Connection</title>
 
       <para>The &man.ntpd.8; program does not need a permanent
 	connection to the Internet to function properly.  However, if
 	you have a temporary connection that is configured to dial out
 	on demand, it is a good idea to prevent NTP traffic from
 	triggering a dial out or keeping the connection alive.  If you
 	are using user PPP, you can use <literal>filter</literal>
 	directives in <filename>/etc/ppp/ppp.conf</filename>.  For
 	example:</para>
 
       <programlisting> set filter dial 0 deny udp src eq 123
  # Prevent NTP traffic from initiating dial out
  set filter dial 1 permit 0 0
  set filter alive 0 deny udp src eq 123
  # Prevent incoming NTP traffic from keeping the connection open
  set filter alive 1 deny udp dst eq 123
  # Prevent outgoing NTP traffic from keeping the connection open
  set filter alive 2 permit 0/0 0/0</programlisting>
 
       <para>For more details see the <literal>PACKET
 	FILTERING</literal> section in &man.ppp.8; and the examples in
 	<filename>/usr/share/examples/ppp/</filename>.</para>
 
       <note>
 	<para>Some Internet access providers block low-numbered ports,
 	  preventing NTP from functioning since replies never
 	  reach your machine.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Further Information</title>
 
       <para>Documentation for the NTP server can be found in
 	<filename>/usr/share/doc/ntp/</filename> in HTML
 	format.</para>
     </sect2>
   </sect1>
 
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 <!--  LocalWords:  config mnt www -->
diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
index bd343f551f..a3bd259165 100644
--- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
@@ -1,4817 +1,4817 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="security">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Matthew</firstname>
 	<surname>Dillon</surname>
 	<contrib>Much of this chapter has been taken from the
 	security(7) manual page by </contrib>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Security</title>
   <indexterm><primary>security</primary></indexterm>
 
   <sect1 id="security-synopsis">
     <title>Synopsis</title>
 
     <para>This chapter will provide a basic introduction to system security
       concepts, some general good rules of thumb, and some advanced topics
       under &os;.  A lot of the topics covered here can be applied
       to system and Internet security in general as well.  The Internet
       is no longer a <quote>friendly</quote> place in which everyone
       wants to be your kind neighbor.  Securing your system is imperative
       to protect your data, intellectual property, time, and much more
       from the hands of hackers and the like.</para>
 
     <para>&os; provides an array of utilities and mechanisms to ensure
       the integrity and security of your system and network.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Basic system security concepts, in respect to &os;.</para>
       </listitem>
 
       <listitem>
 	<para>About the various crypt mechanisms available in &os;,
 	  such as <acronym>DES</acronym> and <acronym>MD5</acronym>.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up one-time password authentication.</para>
       </listitem>
 
       <listitem>
 	<para>How to configure <acronym>TCP</acronym> Wrappers for use
 	  with <command>inetd</command>.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up <application>KerberosIV</application> on &os;
 	  releases prior to 5.0.</para>
       </listitem>
 
       <listitem>
 	<para>How to set up <application>Kerberos5</application> on
 	  post &os; 5.0 releases.</para>
       </listitem>
 
       <listitem>
 	<para>How to configure IPsec and create a <acronym>VPN</acronym> between
 	&os;/&windows; machines.</para>
       </listitem>
      
       <listitem>
 	<para>How to configure and use <application>OpenSSH</application>, &os;'s <acronym>SSH</acronym>
 	  implementation.</para>
       </listitem>
 
       <listitem>
 	<para>What file system <acronym>ACL</acronym>s are and how to use them.</para>
       </listitem>
 
       <listitem>
 	<para>How to utilize the &os; security advisories
 	  publications.</para>
       </listitem>
 
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Understand basic &os; and Internet concepts.</para>
       </listitem>
     </itemizedlist>
 
     <para>Additional security topics are covered throughout this book.
       For example, Mandatory Access Control is discussed in <xref
       linkend="mac"> and Internet Firewalls are discussed in <xref
       linkend="firewalls">.</para>
   </sect1>
 
   <sect1 id="security-intro">
     <title>Introduction</title>
 
     <para>Security is a function that begins and ends with the system
       administrator.  While all BSD &unix; multi-user systems have some
       inherent security, the job of building and maintaining additional
       security mechanisms to keep those users <quote>honest</quote> is
       probably one of the single largest undertakings of the sysadmin.
       Machines are only as secure as you make them, and security concerns
       are ever competing with the human necessity for convenience.  &unix;
       systems, in general, are capable of running a huge number of
       simultaneous processes and many of these processes operate as
       servers &mdash; meaning that external entities can connect and talk
       to them.  As yesterday's mini-computers and mainframes become
       today's desktops, and as computers become networked and
       internetwork, security becomes an even bigger issue.</para>
 
     <para>Security is best implemented through a layered
       <quote>onion</quote> approach.  In a nutshell, what you want to do is
       to create as many layers of security as are convenient and then
       carefully monitor the system for intrusions.  You do not want to
       overbuild your security or you will interfere with the detection
       side, and detection is one of the single most important aspects of
       any security mechanism.  For example, it makes little sense to set
       the <literal>schg</literal> flag (see &man.chflags.1;) on every
       system binary because
       while this may temporarily protect the binaries, it prevents an
       attacker who has broken in from making an easily detectable change
       that may result in your security mechanisms not detecting the attacker
       at all.</para>
 
     <para>System security also pertains to dealing with various forms of
       attack, including attacks that attempt to crash, or otherwise make a
       system unusable, but do not attempt to compromise the
       <username>root</username> account (<quote>break root</quote>).
       Security concerns
       can be split up into several categories:</para>
 
     <orderedlist>
       <listitem>
 	<para>Denial of service attacks.</para>
       </listitem>
 
       <listitem>
 	<para>User account compromises.</para>
       </listitem>
 
       <listitem>
 	<para>Root compromise through accessible servers.</para>
       </listitem>
 
       <listitem>
 	<para>Root compromise via user accounts.</para>
       </listitem>
 
       <listitem>
 	<para>Backdoor creation.</para>
       </listitem>
     </orderedlist>
 
     <indexterm>
       <primary>DoS attacks</primary>
       <see>Denial of Service (DoS)</see>
     </indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>DoS attacks</secondary>
       <see>Denial of Service (DoS)</see>
     </indexterm>
     <indexterm><primary>Denial of Service (DoS)</primary></indexterm>
 
     <para>A denial of service attack is an action that deprives the
       machine of needed resources.  Typically, DoS attacks are
       brute-force mechanisms that attempt to crash or otherwise make a
       machine unusable by overwhelming its servers or network stack.  Some
       DoS attacks try to take advantage of bugs in the networking
       stack to crash a machine with a single packet.  The latter can only
       be fixed by applying a bug fix to the kernel.  Attacks on servers
       can often be fixed by properly specifying options to limit the load
       the servers incur on the system under adverse conditions.
       Brute-force network attacks are harder to deal with.  A
       spoofed-packet attack, for example, is nearly impossible to stop,
       short of cutting your system off from the Internet.  It may not be
       able to take your machine down, but it can saturate your
       Internet connection.</para>
 
     <indexterm>
       <primary>security</primary>
       <secondary>account compromises</secondary>
     </indexterm>
 
     <para>A user account compromise is even more common than a DoS
       attack.  Many sysadmins still run standard 
       <application>telnetd</application>, <application>rlogind</application>,
       <application>rshd</application>,
       and <application>ftpd</application> servers on their machines.
       These servers, by default, do
       not operate over encrypted connections.  The result is that if you
       have any moderate-sized user base, one or more of your users logging
       into your system from a remote location (which is the most common
       and convenient way to login to a system) will have his or her
       password sniffed.  The attentive system admin will analyze his
       remote access logs looking for suspicious source addresses even for
       successful logins.</para>
 
     <para>One must always assume that once an attacker has access to a
       user account, the attacker can break <username>root</username>.
       However, the reality is that in a well secured and maintained system,
       access to a user account does not necessarily give the attacker
       access to <username>root</username>.  The distinction is important
       because without access to <username>root</username> the attacker
       cannot generally hide his tracks and may, at best, be able to do
       nothing more than mess with the user's files, or crash the machine.
       User account compromises are very common because users tend not to
       take the precautions that sysadmins take.</para>
 
     <indexterm>
       <primary>security</primary>
       <secondary>backdoors</secondary>
     </indexterm>
 
     <para>System administrators must keep in mind that there are
       potentially many ways to break <username>root</username> on a machine.
       The attacker may know the <username>root</username> password,
       the attacker may find a bug in a root-run server and be able
       to break <username>root</username> over a network
       connection to that server, or the attacker may know of a bug in
       a suid-root program that allows the attacker to break
       <username>root</username> once he has broken into a user's account.
       If an attacker has found a way to break <username>root</username>
       on a machine, the attacker may not have a need
       to install a backdoor.  Many of the <username>root</username> holes
       found and closed to date involve a considerable amount of work
       by the attacker to cleanup after himself, so most attackers install
       backdoors.  A backdoor provides the attacker with a way to easily
       regain <username>root</username> access to the system, but it
       also gives the smart system administrator a convenient way
       to detect the intrusion.
       Making it impossible for an attacker to install a backdoor may
       actually be detrimental to your security, because it will not
       close off the hole the attacker found to break in the first
       place.</para>
 
 
     <para>Security remedies should always be implemented with a
       multi-layered <quote>onion peel</quote> approach and can be
       categorized as follows:</para>
 
     <orderedlist>
       <listitem>
 	<para>Securing <username>root</username> and staff accounts.</para>
       </listitem>
 
       <listitem>
 	<para>Securing <username>root</username>&ndash;run servers
 	  and suid/sgid binaries.</para>
       </listitem>
 
       <listitem>
 	<para>Securing user accounts.</para>
       </listitem>
 
       <listitem>
 	<para>Securing the password file.</para>
       </listitem>
 
       <listitem>
 	<para>Securing the kernel core, raw devices, and
 	  file systems.</para>
       </listitem>
 
       <listitem>
 	<para>Quick detection of inappropriate changes made to the
 	  system.</para>
       </listitem>
 
       <listitem>
 	<para>Paranoia.</para>
       </listitem>
     </orderedlist>
 
     <para>The next section of this chapter will cover the above bullet
       items in greater depth.</para>
   </sect1>
 
   <sect1 id="securing-freebsd">
     <title>Securing &os;</title>
     <indexterm>
       <primary>security</primary>
       <secondary>securing &os;</secondary>
     </indexterm>
 
     <note>
       <title>Command vs. Protocol</title>
       <para>Throughout this document, we will use
        <application>bold</application> text to refer to an
        application, and a <command>monospaced</command> font to refer
        to specific commands.  Protocols will use a normal font.  This
        typographical distinction is useful for instances such as ssh,
        since it is
        a protocol as well as command.</para>
     </note>
 
     <para>The sections that follow will cover the methods of securing your
       &os; system that were mentioned in the <link
         linkend="security-intro">last section</link> of this chapter.</para>
 
     <sect2 id="securing-root-and-staff">
       <title>Securing the <username>root</username> Account and
 	Staff Accounts</title>
       <indexterm>
         <primary><command>su</command></primary>
       </indexterm>
 
       <para>First off, do not bother securing staff accounts if you have
 	not secured the <username>root</username> account.
 	Most systems have a password assigned to the <username>root</username>
 	account.  The first thing you do is assume
 	that the password is <emphasis>always</emphasis> compromised.
 	This does not mean that you should remove the password.  The
 	password is almost always necessary for console access to the
 	machine.  What it does mean is that you should not make it
 	possible to use the password outside of the console or possibly
 	even with the &man.su.1; command.  For example, make sure that
 	your ptys are specified as being insecure in the
 	<filename>/etc/ttys</filename> file so that direct
 	<username>root</username> logins
 	via <command>telnet</command> or <command>rlogin</command> are
 	disallowed.  If using other login services such as
         <application>sshd</application>, make sure that direct
 	<username>root</username> logins are disabled there as well.
 	You can do this by editing
         your <filename>/etc/ssh/sshd_config</filename> file, and making
         sure that <literal>PermitRootLogin</literal> is set to
         <literal>NO</literal>.  Consider every access method &mdash;
         services such as FTP often fall through the cracks.
 	Direct <username>root</username> logins should only be allowed
 	via the system console.</para>
       <indexterm>
         <primary><groupname>wheel</groupname></primary>
       </indexterm>
 
       <para>Of course, as a sysadmin you have to be able to get to
 	<username>root</username>, so we open up a few holes.
 	But we make sure these holes require additional password
 	verification to operate.  One way to make <username>root</username>
 	accessible is to add appropriate staff accounts to the
 	<groupname>wheel</groupname> group (in
 	<filename>/etc/group</filename>).  The staff members placed in the
 	<groupname>wheel</groupname> group are allowed to
 	<command>su</command> to <username>root</username>.
 	You should never give staff
 	members native <groupname>wheel</groupname> access by putting them in the
 	<groupname>wheel</groupname> group in their password entry.  Staff
 	accounts should be placed in a <groupname>staff</groupname> group, and
 	then added to the <groupname>wheel</groupname> group via the
 	<filename>/etc/group</filename> file.  Only those staff members
 	who actually need to have <username>root</username> access
 	should be placed in the
 	<groupname>wheel</groupname> group.  It is also possible, when using
 	an authentication method such as Kerberos, to use Kerberos'
 	<filename>.k5login</filename> file in the <username>root</username>
 	account to allow a &man.ksu.1; to <username>root</username>
 	without having to place anyone at all in the
 	<groupname>wheel</groupname> group.  This may be the better solution
 	since the <groupname>wheel</groupname> mechanism still allows an
 	intruder to break <username>root</username> if the intruder
 	has gotten hold of your
 	password file and can break into a staff account.  While having
 	the <groupname>wheel</groupname> mechanism is better than having
 	nothing at all, it is not necessarily the safest option.</para>
 
       <!-- XXX:
 	This will need updating depending on the outcome of PR bin/71147.
 	Personally I know what I'd like to see, which puts this in definite
 	need of a rewrite, but we'll have to wait and see.  ceri@
       -->
 
       <para>An indirect way to secure staff accounts, and ultimately
         <username>root</username> access is to use an alternative
 	login access method and
         do what is known as <quote>starring</quote> out the encrypted
         password for the staff accounts.  Using the &man.vipw.8;
         command, one can replace each instance of an encrypted password
         with a single <quote><literal>*</literal></quote> character.
 	This command will update the <filename>/etc/master.passwd</filename>
 	file and user/password database to disable password-authenticated
         logins.</para>
 
       <para>A staff account entry such as:</para>
 
       <programlisting>foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>
 
       <para>Should be changed to this:</para>
 
       <programlisting>foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>
 
       <para>This change will prevent normal logins from occurring,
         since the encrypted password will never match
         <quote><literal>*</literal></quote>.  With this done,
 	staff members must use
         another mechanism to authenticate themselves such as
         &man.kerberos.1; or &man.ssh.1; using a public/private key
         pair.  When using something like Kerberos, one generally must
         secure the machines which run the Kerberos servers and your
         desktop workstation.  When using a public/private key pair
         with ssh, one must generally secure
         the machine used to login <emphasis>from</emphasis> (typically
         one's workstation).  An additional layer of protection can be
         added to the key pair by password protecting the key pair when
         creating it with &man.ssh-keygen.1;.  Being able to
         <quote>star</quote> out the passwords for staff accounts also
         guarantees that staff members can only login through secure
         access methods that you have set up.  This forces all staff
         members to use secure, encrypted connections for all of their
         sessions, which closes an important hole used by many
         intruders: sniffing the network from an unrelated,
         less secure machine.</para>
 
       <para>The more indirect security mechanisms also assume that you are
 	logging in from a more restrictive server to a less restrictive
 	server.  For example, if your main box is running all sorts of
 	servers, your workstation should not be running any.  In order for
 	your workstation to be reasonably secure you should run as few
 	servers as possible, up to and including no servers at all, and
 	you should run a password-protected screen blanker.  Of course,
 	given physical access to a workstation an attacker can break any
 	sort of security you put on it.  This is definitely a problem that
 	you should consider, but you should also consider the fact that the
 	vast majority of break-ins occur remotely, over a network, from
 	people who do not have physical access to your workstation or
 	servers.</para>
       <indexterm><primary>KerberosIV</primary></indexterm>
 
       <para>Using something like Kerberos also gives you the ability to
 	disable or change the password for a staff account in one place,
 	and have it immediately affect all the machines on which the staff
 	member may have an account.  If a staff member's account gets
 	compromised, the ability to instantly change his password on all
 	machines should not be underrated.  With discrete passwords,
 	changing a password on N machines can be a mess.  You can also
 	impose re-passwording restrictions with Kerberos:  not only can a
 	Kerberos ticket be made to timeout after a while, but the Kerberos
 	system can require that the user choose a new password after a
 	certain period of time (say, once a month).</para>
     </sect2>
 
     <sect2>
       <title>Securing Root-run Servers and SUID/SGID Binaries</title>
 
       <indexterm>
         <primary><command>ntalk</command></primary>
       </indexterm>
       <indexterm>
         <primary><command>comsat</command></primary>
       </indexterm>
       <indexterm>
         <primary><command>finger</command></primary>
       </indexterm>
       <indexterm>
         <primary>sandboxes</primary>
       </indexterm>
       <indexterm>
         <primary><application>sshd</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>telnetd</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>rshd</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>rlogind</application></primary>
       </indexterm>
 
       <para>The prudent sysadmin only runs the servers he needs to, no
 	more, no less.  Be aware that third party servers are often the
 	most bug-prone.  For example, running an old version of
 	<application>imapd</application> or
 	<application>popper</application> is like giving a universal
 	<username>root</username> ticket out to the entire world.
 	Never run a server that you have not checked out carefully.
 	Many servers do not need to be run as <username>root</username>.
 	For example, the <application>ntalk</application>,
 	<application>comsat</application>, and
 	<application>finger</application> daemons can be run in special
 	user <firstterm>sandboxes</firstterm>.  A sandbox is not perfect,
 	unless you go through a large amount of trouble, but the onion
 	approach to security still stands: If someone is able to break
 	in through a server running in a sandbox, they still have to
 	break out of the sandbox.  The more layers the attacker must
 	break through, the lower the likelihood of his success.  Root
 	holes have historically been found in virtually every server
 	ever run as <username>root</username>, including basic system servers.
 	If you are running a machine through which people only login via
 	<application>sshd</application> and never login via
 	<application>telnetd</application> or
 	<application>rshd</application> or
 	<application>rlogind</application>, then turn off those
 	services!</para>
       
       <para>&os; now defaults to running
 	<application>ntalkd</application>,
 	<application>comsat</application>, and
 	<application>finger</application> in a sandbox.  Another program
 	which may be a candidate for running in a sandbox is &man.named.8;.
 	<filename>/etc/defaults/rc.conf</filename> includes the arguments
 	necessary to run <application>named</application> in a sandbox in a
 	commented-out form.  Depending on whether you are installing a new
 	system or upgrading an existing system, the special user accounts
 	used by these sandboxes may not be installed.  The prudent
 	sysadmin would research and implement sandboxes for servers
 	whenever possible.</para>
       <indexterm>
         <primary><application>sendmail</application></primary>
       </indexterm>
 
       <para>There are a number of other servers that typically do not run
 	in sandboxes: <application>sendmail</application>,
 	<application>popper</application>,
 	<application>imapd</application>, <application>ftpd</application>,
 	and others.  There are alternatives to some of these, but
 	installing them may require more work than you are willing to
 	perform (the convenience factor strikes again).  You may have to
 	run these servers as <username>root</username> and rely on other
 	mechanisms to detect break-ins that might occur through them.</para>
 
       <para>The other big potential <username>root</username> holes in a
 	system are the
 	suid-root and sgid binaries installed on the system.  Most of
 	these binaries, such as <application>rlogin</application>, reside
 	in <filename>/bin</filename>, <filename>/sbin</filename>,
 	<filename>/usr/bin</filename>, or <filename>/usr/sbin</filename>.
 	While nothing is 100% safe, the system-default suid and sgid
 	binaries can be considered reasonably safe.  Still,
 	<username>root</username> holes are occasionally found in these
 	binaries.  A <username>root</username> hole was found in
 	<literal>Xlib</literal> in 1998 that made
 	<application>xterm</application> (which is typically suid)
 	vulnerable.  It is better to be safe than sorry and the prudent
 	sysadmin will restrict suid binaries, that only staff should run,
 	to a special group that only staff can access, and get rid of
 	(<command>chmod 000</command>) any suid binaries that nobody uses.
 	A server with no display generally does not need an
 	<application>xterm</application> binary.  Sgid binaries can be
 	almost as dangerous.  If an intruder can break an sgid-kmem binary,
 	the intruder might be able to read <filename>/dev/kmem</filename>
 	and thus read the encrypted password file, potentially compromising
 	any passworded account.  Alternatively an intruder who breaks
 	group <literal>kmem</literal> can monitor keystrokes sent through
 	ptys, including ptys used by users who login through secure
 	methods.  An intruder that breaks the <groupname>tty</groupname>
 	group can write to
 	almost any user's tty.  If a user is running a terminal program or
 	emulator with a keyboard-simulation feature, the intruder can
 	potentially generate a data stream that causes the user's terminal
 	to echo a command, which is then run as that user.</para>
     </sect2>
 
     <sect2 id="secure-users">
       <title>Securing User Accounts</title>
 
       <para>User accounts are usually the most difficult to secure.  While
 	you can impose Draconian access restrictions on your staff and
 	<quote>star</quote> out their passwords, you may not be able to
 	do so with any general user accounts you might have.  If you do
 	have sufficient control, then you may win out and be able to secure
 	the user accounts properly.  If not, you simply have to be more
 	vigilant in your monitoring of those accounts.  Use of
 	ssh and Kerberos for user accounts is
 	more problematic, due to the extra administration and technical
 	support required, but still a very good solution compared to a
 	crypted password file.</para>
     </sect2>
 
     <sect2>
       <title>Securing the Password File</title>
 
       <para>The only sure fire way is to <literal>*</literal> out as many
 	passwords as you can and use ssh or
 	Kerberos for access to those accounts.  Even though the encrypted
 	password file (<filename>/etc/spwd.db</filename>) can only be read
 	by <username>root</username>, it may be possible for an intruder
 	to obtain read access to that file even if the attacker cannot
 	obtain root-write access.</para>
 
       <para>Your security scripts should always check for and report
 	changes to the password file (see the <link
 	  linkend="security-integrity">Checking file integrity</link> section
 	below).</para>
     </sect2>
 
     <sect2>
       <title>Securing the Kernel Core, Raw Devices, and
 	File systems</title>
 
       <para>If an attacker breaks <username>root</username> he can do
         just about anything, but
 	there are certain conveniences.  For example, most modern kernels
 	have a packet sniffing device driver built in.  Under &os; it
 	is called the <devicename>bpf</devicename> device.  An intruder
 	will commonly attempt to run a packet sniffer on a compromised
 	machine.  You do not need to give the intruder the capability and
 	most systems do not have the need for the
 	<devicename>bpf</devicename> device compiled in.</para>
 
       <indexterm>
         <primary><command>sysctl</command></primary>
       </indexterm>
       <para>But even if you turn off the <devicename>bpf</devicename>
 	device, you still have
 	<filename>/dev/mem</filename> and 
 	<filename>/dev/kmem</filename>
 	to worry about.  For that matter, the intruder can still write to
 	raw disk devices.  Also, there is another kernel feature called
 	the module loader, &man.kldload.8;.  An enterprising intruder can
 	use a KLD module to install his own <devicename>bpf</devicename>
 	device, or other sniffing
 	device, on a running kernel.  To avoid these problems you have to
 	run the kernel at a higher secure level, at least securelevel 1.
 	The securelevel can be set with a <command>sysctl</command> on
 	the <varname>kern.securelevel</varname> variable.  Once you have
 	set the securelevel to 1, write access to raw devices will be
 	denied and special <command>chflags</command> flags,
 	such as <literal>schg</literal>,
 	will be enforced.  You must also ensure that the
 	<literal>schg</literal> flag is set on critical startup binaries,
 	directories, and script files &mdash; everything that gets run up
 	to the point where the securelevel is set.  This might be overdoing
 	it, and upgrading the system is much more difficult when you
 	operate at a higher secure level.  You may compromise and run the
 	system at a higher secure level but not set the
 	<literal>schg</literal> flag for every system file and directory
 	under the sun.  Another possibility is to simply mount
 	<filename>/</filename> and <filename>/usr</filename> read-only.
 	It should be noted that being too Draconian in what you attempt to
 	protect may prevent the all-important detection of an
 	intrusion.</para>
     </sect2>
 
     <sect2 id="security-integrity">
       <title>Checking File Integrity: Binaries, Configuration Files,
 	Etc.</title>
 
       <para>When it comes right down to it, you can only protect your core
 	system configuration and control files so much before the
 	convenience factor rears its ugly head.  For example, using
 	<command>chflags</command> to set the <literal>schg</literal> bit
 	on most of the files in <filename>/</filename> and
 	<filename>/usr</filename> is probably counterproductive, because
 	while it may protect the files, it also closes a detection window.
 	The last layer of your security onion is perhaps the most
 	important &mdash; detection.  The rest of your security is pretty
 	much useless (or, worse, presents you with a false sense of
 	safety) if you cannot detect potential incursions.  Half the job
 	of the onion is to slow down the attacker, rather than stop him, in
 	order to give the detection side of the equation a chance to catch
 	him in the act.</para>
 
       <para>The best way to detect an incursion is to look for modified,
 	missing, or unexpected files.  The best way to look for modified
 	files is from another (often centralized) limited-access system.
 	Writing your security scripts on the extra-secure limited-access
 	system makes them mostly invisible to potential attackers, and this
 	is important.  In order to take maximum advantage you generally
 	have to give the limited-access box significant access to the
 	other machines in the business, usually either by doing a
 	read-only NFS export of the other machines to the limited-access
 	box, or by setting up ssh key-pairs to
 	allow the limited-access box to ssh to
 	the other machines.  Except for its network traffic, NFS is the
 	least visible method &mdash; allowing you to monitor the
 	file systems on each client box virtually undetected.  If your
 	limited-access server is connected to the client boxes through a
 	switch, the NFS method is often the better choice.  If your
 	limited-access server is connected to the client boxes through a
 	hub, or through several layers of routing, the NFS method may be
 	too insecure (network-wise) and using
 	ssh may be the better choice even with
 	the audit-trail tracks that ssh
 	lays.</para>
 
       <para>Once you give a limited-access box, at least read access to the
 	client systems it is supposed to monitor, you must write scripts
 	to do the actual monitoring.  Given an NFS mount, you can write
 	scripts out of simple system utilities such as &man.find.1; and
 	&man.md5.1;.  It is best to physically md5 the client-box files
 	at least once a day, and to test control files such as those
 	found in <filename>/etc</filename> and
 	<filename>/usr/local/etc</filename> even more often.  When
 	mismatches are found, relative to the base md5 information the
 	limited-access machine knows is valid, it should scream at a
 	sysadmin to go check it out.  A good security script will also
 	check for inappropriate suid binaries and for new or deleted files
 	on system partitions such as <filename>/</filename> and
 	<filename>/usr</filename>.</para>
 
       <para>When using ssh rather than NFS,
 	writing the security script is much more difficult.   You
 	essentially have to <command>scp</command> the scripts to the client 
 	box in order to
 	run them, making them visible, and for safety you also need to
 	<command>scp</command> the binaries (such as find) that those
 	scripts use.  The <application>ssh</application> client on the
 	client box may already be compromised.  All in all, using
 	ssh may be necessary when running over
 	insecure links, but it is also a lot harder to deal with.</para>
 
       <para>A good security script will also check for changes to user and
 	staff members access configuration files:
 	<filename>.rhosts</filename>, <filename>.shosts</filename>,
 	<filename>.ssh/authorized_keys</filename> and so forth&hellip;
 	files that might fall outside the purview of the
 	<literal>MD5</literal> check.</para>
 
       <para>If you have a huge amount of user disk space, it may take too
 	long to run through every file on those partitions.  In this case,
 	setting mount flags to disallow suid binaries and devices on those
 	partitions is a good idea.  The <literal>nodev</literal> and
 	<literal>nosuid</literal> options (see &man.mount.8;) are what you
 	want to look into.  You should probably scan them anyway, at least
 	once a week, since the object of this layer is to detect a break-in
 	whether or not the break-in is effective.</para>
 
       <para>Process accounting (see &man.accton.8;) is a relatively
 	low-overhead feature of the operating system which might help
 	as a post-break-in evaluation mechanism.  It is especially
 	useful in tracking down how an intruder has actually broken into
 	a system, assuming the file is still intact after the break-in
 	occurs.</para>
 
       <para>Finally, security scripts should process the log files, and the
 	logs themselves should be generated in as secure a manner as
 	possible &mdash; remote syslog can be very useful.  An intruder
 	tries to cover his tracks, and log files are critical to the
 	sysadmin trying to track down the time and method of the initial
 	break-in.  One way to keep a permanent record of the log files is
 	to run the system console to a serial port and collect the
 	information on a continuing basis through a secure machine
 	monitoring the consoles.</para>
     </sect2>
 
     <sect2>
       <title>Paranoia</title>
 
       <para>A little paranoia never hurts.  As a rule, a sysadmin can add
 	any number of security features, as long as they do not affect
 	convenience, and can add security features that
 	<emphasis>do</emphasis> affect convenience with some added thought.
 	Even more importantly, a security administrator should mix it up a
 	bit &mdash; if you use recommendations such as those given by this
 	document verbatim, you give away your methodologies to the
 	prospective attacker who also has access to this document.</para>
     </sect2>
 
     <sect2>
       <title>Denial of Service Attacks</title>
       <indexterm><primary>Denial of Service (DoS)</primary></indexterm>
 
       <para>This section covers Denial of Service attacks.  A DoS attack
 	is typically a packet attack.  While there is not much you can do
 	about modern spoofed packet attacks that saturate your network,
 	you can generally limit the damage by ensuring that the attacks
 	cannot take down your servers.</para>
 
       <orderedlist>
 	<listitem>
 	  <para>Limiting server forks.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Limiting springboard attacks (ICMP response attacks, ping
 	    broadcast, etc.).</para>
 	</listitem>
 
 	<listitem>
 	  <para>Kernel Route Cache.</para>
 	</listitem>
       </orderedlist>
 
       <para>A common DoS attack is against a forking server that attempts
 	to cause the server to eat processes, file descriptors, and memory,
 	until the machine dies.  <application>inetd</application>
 	(see &man.inetd.8;) has several
 	options to limit this sort of attack.  It should be noted that
 	while it is possible to prevent a machine from going down, it is
 	not generally possible to prevent a service from being disrupted
 	by the attack.  Read the <application>inetd</application> manual
 	page carefully and pay
 	specific attention to the <option>-c</option>, <option>-C</option>,
 	and <option>-R</option> options.  Note that spoofed-IP attacks
 	will circumvent the <option>-C</option> option to 
 	<application>inetd</application>, so
 	typically a combination of options must be used.  Some standalone
 	servers have self-fork-limitation parameters.</para>
 
       <para><application>Sendmail</application> has its
 	<option>-OMaxDaemonChildren</option> option, which tends to work
 	much better than trying to use sendmail's load limiting options
 	due to the load lag.  You should specify a
 	<literal>MaxDaemonChildren</literal> parameter, when you start
 	<application>sendmail</application>, high enough to handle your
 	expected load, but not so high that the computer cannot handle that
 	number of <application>sendmails</application> without falling on
 	its face.  It is also prudent to run sendmail in queued mode
 	(<option>-ODeliveryMode=queued</option>) and to run the daemon
 	(<command>sendmail -bd</command>) separate from the queue-runs
 	(<command>sendmail -q15m</command>).  If you still want real-time
 	delivery you can run the queue at a much lower interval, such as
 	<option>-q1m</option>, but be sure to specify a reasonable
 	<literal>MaxDaemonChildren</literal> option for
 	<emphasis>that</emphasis> sendmail to prevent cascade failures.</para>
 
       <para><application>Syslogd</application> can be attacked directly
 	and it is strongly recommended that you use the <option>-s</option>
 	option whenever possible, and the <option>-a</option> option
 	otherwise.</para>
 
       <para>You should also be fairly careful with connect-back services
-	such as <application>tcpwrapper</application>'s reverse-identd,
+	such as <application>TCP Wrapper</application>'s reverse-identd,
 	which can be attacked directly.  You generally do not want to use
 	the reverse-ident feature of
-	<application>tcpwrappers</application> for this reason.</para>
+	<application>TCP Wrapper</application> for this reason.</para>
 
       <para>It is a very good idea to protect internal services from
 	external access by firewalling them off at your border routers.
 	The idea here is to prevent saturation attacks from outside your
 	LAN, not so much to protect internal services from network-based
 	<username>root</username> compromise.
 	Always configure an exclusive firewall, i.e.,
 	<quote>firewall everything <emphasis>except</emphasis> ports A, B,
 	C, D, and M-Z</quote>.  This way you can firewall off all of your
 	low ports except for certain specific services such as
 	<application>named</application> (if you are primary for a zone),
 	<application>ntalkd</application>,
 	<application>sendmail</application>, and other Internet-accessible
 	services.  If you try to configure the firewall the other way
 	&mdash; as an inclusive or permissive firewall, there is a good
 	chance that you will forget to <quote>close</quote> a couple of
 	services, or that you will add a new internal service and forget
 	to update the firewall.  You can still open up the high-numbered
 	port range on the firewall, to allow permissive-like operation,
 	without compromising your low ports.  Also take note that &os;
 	allows you to control the range of port numbers used for dynamic
 	binding, via the various <varname>net.inet.ip.portrange</varname>
 	<command>sysctl</command>'s (<command>sysctl -a | fgrep
 	portrange</command>), which can also ease the complexity of your
 	firewall's configuration.  For example, you might use a normal
 	first/last range of 4000 to 5000, and a hiport range of 49152 to
 	65535, then block off everything under 4000 in your firewall
 	(except for certain specific Internet-accessible ports, of
 	course).</para>
 
       <indexterm><primary>ICMP_BANDLIM</primary></indexterm>
 
       <para>Another common DoS attack is called a springboard attack
 	&mdash; to attack a server in a manner that causes the server to
 	generate responses which overloads the server, the local
 	network, or some other machine.  The most common attack of this
 	nature is the <emphasis>ICMP ping broadcast attack</emphasis>.
 	The attacker spoofs ping packets sent to your LAN's broadcast
 	address with the source IP address set to the actual machine they
 	wish to attack.  If your border routers are not configured to
 	stomp on ping's to broadcast addresses, your LAN winds up
 	generating sufficient responses to the spoofed source address to
 	saturate the victim, especially when the attacker uses the same
 	trick on several dozen broadcast addresses over several dozen
 	different networks at once.  Broadcast attacks of over a hundred
 	and twenty megabits have been measured.  A second common
 	springboard attack is against the ICMP error reporting system.
 	By constructing packets that generate ICMP error responses, an
 	attacker can saturate a server's incoming network and cause the
 	server to saturate its outgoing network with ICMP responses.  This
 	type of attack can also crash the server by running it out of
 	mbuf's, especially if the server cannot drain the ICMP responses
 	it generates fast enough.  The &os; kernel has a new kernel
 	compile option called <option>ICMP_BANDLIM</option>
 	which limits the effectiveness
 	of these sorts of attacks.  The last major class of springboard
 	attacks is related to certain internal 
 	<application>inetd</application> services such as the
 	udp echo service.  An attacker simply spoofs a UDP packet with the
 	source address being server A's echo port, and the destination
 	address being server B's echo port, where server A and B are both
 	on your LAN.  The two servers then bounce this one packet back and
 	forth between each other.  The attacker can overload both servers
 	and their LANs simply by injecting a few packets in this manner.
 	Similar problems exist with the internal 
 	<application>chargen</application> port.  A
 	competent sysadmin will turn off all of these inetd-internal test
 	services.</para>
 
       <para>Spoofed packet attacks may also be used to overload the kernel
 	route cache.  Refer to the <varname>net.inet.ip.rtexpire</varname>,
 	<varname>rtminexpire</varname>, and <varname>rtmaxcache</varname>
 	<command>sysctl</command> parameters.  A spoofed packet attack
 	that uses a random source IP will cause the kernel to generate a
 	temporary cached route in the route table, viewable with
 	<command>netstat -rna | fgrep W3</command>.  These routes
 	typically timeout in 1600 seconds or so.  If the kernel detects
 	that the cached route table has gotten too big it will dynamically
 	reduce the <varname>rtexpire</varname> but will never decrease it 
 	to less than <varname>rtminexpire</varname>.  There are two 
 	problems:</para>
 	
       <orderedlist>
 	<listitem>
 	  <para>The kernel does not react quickly enough when a lightly
 	    loaded server is suddenly attacked.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>The <varname>rtminexpire</varname> is not low enough for
 	    the kernel to survive a sustained attack.</para>
 	</listitem>
       </orderedlist>
       
       <para>If your servers are connected to the Internet via a T3 or
         better, it may be prudent to manually override both
 	<varname>rtexpire</varname> and <varname>rtminexpire</varname>
 	via &man.sysctl.8;.  Never set either parameter to zero (unless
 	you want to crash the machine).  Setting both
 	parameters to 2 seconds should be sufficient to protect the route
 	table from attack.</para>
     </sect2>
 
     <sect2>
       <title>Access Issues with Kerberos and SSH</title>
       <indexterm><primary><command>ssh</command></primary></indexterm>
       <indexterm><primary>KerberosIV</primary></indexterm>
 
       <para>There are a few issues with both Kerberos and
 	ssh that need to be addressed if
 	you intend to use them.  Kerberos V is an excellent
 	authentication protocol, but there are bugs in the kerberized
 	<application>telnet</application> and
 	<application>rlogin</application> applications that make them
 	unsuitable for dealing with binary streams.  Also, by default
 	Kerberos does not encrypt a session unless you use the
 	<option>-x</option> option.  <application>ssh</application>
 	encrypts everything by default.</para>
 
       <para>ssh works quite well in every
 	respect except that it forwards encryption keys by default.  What
 	this means is that if you have a secure workstation holding keys
 	that give you access to the rest of the system, and you
 	ssh to an insecure machine, your keys
 	are usable.  The actual keys themselves are not exposed, but
 	ssh installs a forwarding port for the
 	duration of your login, and if an attacker has broken
 	<username>root</username> on the
 	insecure machine he can utilize that port to use your keys to gain
 	access to any other machine that your keys unlock.</para>
 
       <para>We recommend that you use ssh in
 	combination with Kerberos whenever possible for staff logins.
 	<application>ssh</application> can be compiled with Kerberos
 	support.  This reduces your reliance on potentially exposed
 	ssh keys while at the same time
 	protecting passwords via Kerberos.  ssh
 	keys should only be used for automated tasks from secure machines
 	(something that Kerberos is unsuited to do).  We also recommend that
 	you either turn off key-forwarding in the
 	ssh configuration, or that you make use
 	of the <literal>from=IP/DOMAIN</literal> option that
 	ssh allows in its
 	<filename>authorized_keys</filename> file to make the key only
 	usable to entities logging in from specific machines.</para>
     </sect2>
   </sect1>
 
   <sect1 id="crypt">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Bill</firstname>
 	  <surname>Swingle</surname>
 	  <contrib>Parts rewritten and updated by </contrib>
 	</author>
       </authorgroup>
       <!-- 21 Mar 2000 -->
     </sect1info>
 
     <title>DES, MD5, and Crypt</title>
     <indexterm>
       <primary>security</primary>
       <secondary>crypt</secondary>
     </indexterm>
 
     <indexterm><primary>crypt</primary></indexterm>
     <indexterm><primary>DES</primary></indexterm>
     <indexterm><primary>MD5</primary></indexterm>
 
     <para>Every user on a &unix; system has a password associated with
       their account.  It seems obvious that these passwords need to be
       known only to the user and the actual operating system.  In
       order to keep these passwords secret, they are encrypted with
       what is known as a <quote>one-way hash</quote>, that is, they can
       only be easily encrypted but not decrypted.  In other words, what
       we told you a moment ago was obvious is not even true:  the
       operating system itself does not <emphasis>really</emphasis> know
       the password.  It only knows the <emphasis>encrypted</emphasis>
       form of the password.  The only way to get the
       <quote>plain-text</quote> password is by a brute force search of the
       space of possible passwords.</para>
 
     <para>Unfortunately the only secure way to encrypt passwords when
       &unix; came into being was based on DES, the Data Encryption
       Standard.  This was not such a problem for users resident in
       the US, but since the source code for DES could not be exported
       outside the US, &os; had to find a way to both comply with 
       US law and retain compatibility with all the other &unix;
       variants that still used DES.</para>
 
     <para>The solution was to divide up the encryption libraries 
       so that US users could install the DES libraries and use
       DES but international users still had an encryption method
       that could be exported abroad.  This is how &os; came to
       use MD5 as its default encryption method.  MD5 is believed to
       be more secure than DES, so installing DES is offered primarily
       for compatibility reasons.</para>
 
     <sect2>
       <title>Recognizing Your Crypt Mechanism</title>
 
       <para>Before &os;&nbsp;4.4 <filename>libcrypt.a</filename> was a
 	symbolic link pointing to the library which was used for
 	encryption. &os; 4.4 changed <filename>libcrypt.a</filename> to
 	provide a configurable password authentication hash library.
 	Currently the library supports DES, MD5 and Blowfish hash
 	functions.  By default &os; uses MD5 to encrypt
 	passwords.</para>
 
       <para>It is pretty easy to identify which encryption method 
 	&os; is set up to use.  Examining the encrypted passwords in
 	the <filename>/etc/master.passwd</filename> file is one way.
 	Passwords encrypted with the MD5 hash are longer than those
 	encrypted with the DES hash and also begin with the characters
 	<literal>&dollar;1&dollar;</literal>.  Passwords starting with
 	<literal>&dollar;2a&dollar;</literal> are encrypted with the
 	Blowfish hash function.  DES password strings do not
 	have any particular identifying characteristics, but they are
 	shorter than MD5 passwords, and are coded in a 64-character
 	alphabet which does not include the <literal>&dollar;</literal>
 	character, so a relatively short string which does not begin with
 	a dollar sign is very likely a DES password.</para>
 
       <para>The password format used for new passwords is controlled
 	by the <literal>passwd_format</literal> login capability in
 	<filename>/etc/login.conf</filename>, which takes values of
 	<literal>des</literal>, <literal>md5</literal> or
 	<literal>blf</literal>.  See the &man.login.conf.5; manual page
 	for more information about login capabilities.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="one-time-passwords">
     <title>One-time Passwords</title>
     <indexterm><primary>one-time passwords</primary></indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>one-time passwords</secondary>
     </indexterm>
 
     <para>S/Key is a one-time password scheme based on a one-way hash
       function.  &os; uses the MD4 hash for compatibility but other
       systems have used MD5 and DES-MAC.  S/Key has been part of the
       &os; base system since version 1.1.5 and is also used on a
       growing number of other operating systems.  S/Key is a registered
       trademark of Bell Communications Research, Inc.</para>
 
     <para>From version 5.0 of &os;, S/Key has been replaced with
       the functionally equivalent OPIE (One-time Passwords In
       Everything).  OPIE uses the MD5 hash by default.</para>
 
     <para>There are three different sorts of passwords which we will discuss
       below.  The first is your usual &unix; style or
       Kerberos password; we will call this a <quote>&unix; password</quote>.
       The second sort is the one-time password which is generated by the
       S/Key <command>key</command> program or the OPIE
       &man.opiekey.1; program and accepted by the
       <command>keyinit</command> or &man.opiepasswd.1; programs
       and the login prompt; we will
       call this a <quote>one-time password</quote>.  The final sort of
       password is the secret password which you give to the
       <command>key</command>/<command>opiekey</command> programs (and
       sometimes the
       <command>keyinit</command>/<command>opiepasswd</command> programs)
       which it uses to generate
       one-time passwords; we will call it a <quote>secret password</quote>
       or just unqualified <quote>password</quote>.</para>
 
     <para>The secret password does not have anything to do with your &unix;
       password; they can be the same but this is not recommended.  S/Key
       and OPIE secret passwords are not limited to 8 characters like old
       &unix; passwords<footnote><para>Under &os; the standard login
       password may be up to 128 characters in length.</para></footnote>,
       they can be as long as you like.  Passwords of six or
       seven word long phrases are fairly common.  For the most part, the
       S/Key or OPIE system operates completely independently of the &unix;
       password system.</para>
 
     <para>Besides the password, there are two other pieces of data that
       are important to S/Key and OPIE.  One is what is known as the
       <quote>seed</quote> or <quote>key</quote>, consisting of two letters
       and five digits.  The other is what is called the <quote>iteration
       count</quote>, a number between 1 and 100.  S/Key creates the
       one-time password by concatenating the seed and the secret password,
       then applying the MD4/MD5 hash as many times as specified by the
       iteration count and turning the result into six short English words.
       These six English words are your one-time password.  The
       authentication system (primarily PAM) keeps
       track of the last one-time password used, and the user is
       authenticated if the hash of the user-provided password is equal to
       the previous password.  Because a one-way hash is used it is
       impossible to generate future one-time passwords if a successfully
       used password is captured; the iteration count is decremented after
       each successful login to keep the user and the login program in
       sync.  When the iteration count gets down to 1, S/Key and OPIE must be
       reinitialized.</para>
 
     <para>There are three programs involved in each system
       which we will discuss below.  The <command>key</command> and
       <command>opiekey</command> programs accept an iteration
       count, a seed, and a secret password, and generate a one-time
       password or a consecutive list of one-time passwords.  The
       <command>keyinit</command> and <command>opiepasswd</command>
       programs are used to initialize S/Key and OPIE respectively,
       and to change passwords, iteration counts, or seeds; they
       take either a secret passphrase, or an iteration count,
       seed, and one-time password.  The <command>keyinfo</command>
       and <command>opieinfo</command> programs examine the
       relevant credentials files (<filename>/etc/skeykeys</filename> or
       <filename>/etc/opiekeys</filename>) and print out the invoking user's
       current iteration count and seed.</para>
 
     <para>There are four different sorts of operations we will cover.  The
       first is using <command>keyinit</command> or
       <command>opiepasswd</command> over a secure connection to set up
       one-time-passwords for the first time,  or to change your password
       or seed.  The second operation is using <command>keyinit</command>
       or <command>opiepasswd</command> over an insecure connection, in
       conjunction with <command>key</command> or <command>opiekey</command>
       over a secure connection,  to do the same.  The third is using
       <command>key</command>/<command>opiekey</command> to log in over
       an insecure connection.  The fourth is using <command>key</command>
       or <command>opiekey</command> to generate a number of keys which
       can be written down or printed out to carry with you when going to
       some location without secure connections to anywhere.</para>
 
     <sect2>
       <title>Secure Connection Initialization</title>
 
       <para>To initialize S/Key for the first time, change your password,
 	or change your seed while logged in over a secure connection
 	(e.g. on the console of a machine or via <application>ssh</application>), use the
 	<command>keyinit</command> command without any parameters while
 	logged in as yourself:</para>
 
       <screen>&prompt.user; <userinput>keyinit</userinput>
 Adding unfurl:
 Reminder - Only use this method if you are directly connected.
 If you are using telnet or rlogin exit with no password and use keyinit -s.
 Enter secret password: 
 Again secret password: 
 
 ID unfurl s/key is 99 to17757
 DEFY CLUB PRO NASH LACE SOFT</screen>
 
       <para>For OPIE, <command>opiepasswd</command> is used instead:</para>
 
       <screen>&prompt.user; <userinput>opiepasswd -c</userinput>
 [grimreaper] ~ $ opiepasswd -f -c
 Adding unfurl:
 Only use this method from the console; NEVER from remote. If you are using
 telnet, xterm, or a dial-in, type ^C now or exit with no password.
 Then run opiepasswd without the -c parameter.
 Using MD5 to compute responses.
 Enter new secret pass phrase:
 Again new secret pass phrase:
 ID unfurl OTP key is 499 to4268
 MOS MALL GOAT ARM AVID COED
 </screen>
 
       <para>At the <prompt>Enter new secret pass phrase:</prompt> or
         <prompt>Enter secret password:</prompt> prompts, you
 	should enter a password or phrase.  Remember, this is not the
 	password that you will use to login with, this is used to generate
 	your one-time login keys.  The <quote>ID</quote> line gives the
 	parameters of your particular instance: your login name, the
         iteration count, and seed.  When logging in the system
 	will remember these parameters and present them back to you so you
 	do not have to remember them.  The last line gives the particular
 	one-time password which corresponds to those parameters and your
 	secret password; if you were to re-login immediately, this
 	one-time password is the one you would use.</para>
     </sect2>
 
     <sect2>
       <title>Insecure Connection Initialization</title>
       
       <para>To initialize or change your secret password over an
 	insecure connection, you will need to already have a secure
 	connection to some place where you can run <command>key</command>
         or <command>opiekey</command>; this might be in the form of a
 	desk accessory on a &macintosh;, or a shell prompt on a machine you
 	trust.  You will also need to make up an iteration count (100 is
 	probably a good value), and you may make up your own seed or use a
 	randomly-generated one.  Over on the insecure connection (to the
 	machine you are initializing), use the <command>keyinit
 	-s</command> command:</para>
 
       <screen>&prompt.user; <userinput>keyinit -s</userinput>
 Updating unfurl:
 Old key: to17758
 Reminder you need the 6 English words from the key command.
 Enter sequence count from 1 to 9999: <userinput>100</userinput>
 Enter new key [default to17759]: 
 s/key 100 to 17759
 s/key access password:
 s/key access password:<userinput>CURE MIKE BANE HIM RACY GORE</userinput>
 </screen>
 
       <para>For OPIE, you need to use <command>opiepasswd</command>:</para>
 
       <screen>&prompt.user; <userinput>opiepasswd</userinput>
 
 Updating unfurl:
 You need the response from an OTP generator.
 Old secret pass phrase:
         otp-md5 498 to4268 ext
         Response: GAME GAG WELT OUT DOWN CHAT
 New secret pass phrase:
         otp-md5 499 to4269
         Response: LINE PAP MILK NELL BUOY TROY
 
 ID mark OTP key is 499 gr4269
 LINE PAP MILK NELL BUOY TROY
 </screen>
 
       <para>To accept the default seed (which the
 	<command>keyinit</command> program confusingly calls a
 	<literal>key</literal>), press <keycap>Return</keycap>.
 	Then before entering an
 	access password, move over to your secure connection or S/Key desk
 	accessory, and give it the same parameters:</para>
 
       <screen>&prompt.user; <userinput>key 100 to17759</userinput>
 Reminder - Do not use this program while logged in via telnet or rlogin.
 Enter secret password: <userinput>&lt;secret password&gt;</userinput>
 CURE MIKE BANE HIM RACY GORE</screen>
 
       <para>Or for OPIE:</para>
 
       <screen>&prompt.user; <userinput>opiekey 498 to4268</userinput>
 Using the MD5 algorithm to compute response.
 Reminder: Don't use opiekey from telnet or dial-in sessions.
 Enter secret pass phrase:
 GAME GAG WELT OUT DOWN CHAT
 </screen>
 
       <para>Now switch back over to the insecure connection, and copy the
 	one-time password generated over to the relevant program.</para>
     </sect2>
 
     <sect2>
       <title>Generating a Single One-time Password</title>
 
       <para>Once you have initialized S/Key or OPIE, when you login you will be 
 	presented with a prompt like this:</para>
 
 <screen>&prompt.user; <userinput>telnet example.com</userinput>
 Trying 10.0.0.1...
 Connected to example.com
 Escape character is '^]'.
 
 FreeBSD/i386 (example.com) (ttypa)
 
 login: <userinput>&lt;username&gt;</userinput>
 s/key 97 fw13894
 Password: </screen>
 
       <para>Or for OPIE:</para>
 
 <screen>&prompt.user; <userinput>telnet example.com</userinput>
 Trying 10.0.0.1...
 Connected to example.com
 Escape character is '^]'.
 
 FreeBSD/i386 (example.com) (ttypa)
 
 login: <userinput>&lt;username&gt;</userinput>
 otp-md5 498 gr4269 ext
 Password: </screen>
 
       <para>As a side note, the S/Key and OPIE prompts have a useful feature
 	(not shown here): if you press <keycap>Return</keycap>
 	at the password prompt, the
 	prompter will turn echo on, so you can see what you are
 	typing.  This can be extremely useful if you are attempting to
 	type in a password by hand, such as from a printout.</para>
 
       <indexterm><primary>MS-DOS</primary></indexterm>
       <indexterm><primary>Windows</primary></indexterm>
       <indexterm><primary>MacOS</primary></indexterm>
 
       <para>At this point you need to generate your one-time password to
 	answer this login prompt.  This must be done on a trusted system
 	that you can run <command>key</command> or
         <command>opiekey</command> on.  (There are versions of these for DOS,
 	&windows; and &macos; as well.) They need both the iteration count and
 	the seed as command line options.  You can cut-and-paste these
         right from the login prompt on the machine that you are logging
         in to.</para>
 
       <para>On the trusted system:</para>
 
       <screen>&prompt.user; <userinput>key 97 fw13894</userinput>
 Reminder - Do not use this program while logged in via telnet or rlogin.
 Enter secret password: 
 WELD LIP ACTS ENDS ME HAAG</screen>
 
       <para>For OPIE:</para>
 
       <screen>&prompt.user; <userinput>opiekey 498 to4268</userinput>
 Using the MD5 algorithm to compute response.
 Reminder: Don't use opiekey from telnet or dial-in sessions.
 Enter secret pass phrase:
 GAME GAG WELT OUT DOWN CHAT</screen>
 
       <para>Now that you have your one-time password you can continue
 	logging in:</para>
 
       <screen>login: <userinput>&lt;username&gt;</userinput>
 s/key 97 fw13894
 Password: <userinput>&lt;return to enable echo&gt;</userinput>
 s/key 97 fw13894
 Password [echo on]: WELD LIP ACTS ENDS ME HAAG
 Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ... </screen>
 
     </sect2>
 
     <sect2>
       <title>Generating Multiple One-time Passwords</title>
 
       <para>Sometimes you have to go places where you do not have
 	access to a trusted machine or secure connection.  In this case,
 	it is possible to use the <command>key</command> and
 	<command>opiekey</command> commands to
 	generate a number of one-time passwords beforehand to be printed
 	out and taken with you.  For example:</para>
 
       <screen>&prompt.user; <userinput>key -n 5 30 zz99999</userinput>
 Reminder - Do not use this program while logged in via telnet or rlogin.
 Enter secret password: <userinput>&lt;secret password&gt;</userinput>
 26: SODA RUDE LEA LIND BUDD SILT 
 27: JILT SPY DUTY GLOW COWL ROT  
 28: THEM OW COLA RUNT BONG SCOT  
 29: COT MASH BARR BRIM NAN FLAG  
 30: CAN KNEE CAST NAME FOLK BILK</screen>
 
       <para>Or for OPIE:</para>
 
       <screen>&prompt.user; <userinput>opiekey -n 5 30 zz99999</userinput>
 Using the MD5 algorithm to compute response.
 Reminder: Don't use opiekey from telnet or dial-in sessions.
 Enter secret pass phrase: <userinput>&lt;secret password&gt;</userinput>
 26: JOAN BORE FOSS DES NAY QUIT
 27: LATE BIAS SLAY FOLK MUCH TRIG
 28: SALT TIN ANTI LOON NEAL USE
 29: RIO ODIN GO BYE FURY TIC
 30: GREW JIVE SAN GIRD BOIL PHI</screen>
 
       <para>The <option>-n 5</option> requests five keys in sequence, the
 	<option>30</option> specifies what the last iteration number
 	should be.  Note that these are printed out in
 	<emphasis>reverse</emphasis> order of eventual use.  If you are
 	really paranoid, you might want to write the results down by hand;
 	otherwise you can cut-and-paste into <command>lpr</command>.  Note
 	that each line shows both the iteration count and the one-time
 	password; you may still find it handy to scratch off passwords as
 	you use them.</para>
     </sect2>
 
     <sect2>
       <title>Restricting Use of &unix; Passwords</title>
 
       <para>S/Key can place restrictions on the use of &unix; passwords based
 	on the host name, user name, terminal port, or IP address of a
 	login session.  These restrictions can be found in the
 	configuration file <filename>/etc/skey.access</filename>.  The
 	&man.skey.access.5; manual page has more information on the complete
 	format of the file and also details some security cautions to be
 	aware of before depending on this file for security.</para>
 
       <para>If there is no <filename>/etc/skey.access</filename> file
 	(this is the default on &os; 4.X systems), then all users will
 	be allowed to use &unix; passwords.  If the file exists, however,
 	then all users will be required to use S/Key unless explicitly
 	permitted to do otherwise by configuration statements in the
 	<filename>skey.access</filename> file.  In all cases, &unix;
 	passwords are permitted on the console.</para>
 
       <para>Here is a sample <filename>skey.access</filename> configuration
 	file which illustrates the three most common sorts of configuration
 	statements:</para>
 
       <programlisting>permit internet 192.168.0.0 255.255.0.0
 permit user fnord
 permit port ttyd0</programlisting>
 
       <para>The first line (<literal>permit internet</literal>) allows
 	users whose IP source address (which is vulnerable to spoofing)
 	matches the specified value and mask, to use &unix; passwords.  This
 	should not be considered a security mechanism, but rather, a means
 	to remind authorized users that they are using an insecure network
 	and need to use S/Key for authentication.</para>
 
       <para>The second line (<literal>permit user</literal>) allows the
 	specified username, in this case <username>fnord</username>, to use
 	&unix; passwords at any time.  Generally speaking, this should only
 	be used for people who are either unable to use the
 	<command>key</command> program, like those with dumb terminals, or
 	those who are ineducable.</para>
 
       <para>The third line (<literal>permit port</literal>) allows all
 	users logging in on the specified terminal line to use &unix;
 	passwords; this would be used for dial-ups.</para>
 
       <para>OPIE can restrict the use of &unix; passwords based on the IP
 	address of a login session just like S/Key does.  The relevant file
 	is <filename>/etc/opieaccess</filename>, which is present by default
 	on &os; 5.0 and newer systems.  Please check &man.opieaccess.5;
 	for more information on this file and which security considerations
 	you should be aware of when using it.</para>
 	
       <para>Here is a sample <filename>opieaccess</filename> file:</para>
 
       <programlisting>permit 192.168.0.0 255.255.0.0</programlisting>
 
       <para>This line allows users whose IP source address (which is
 	vulnerable to spoofing) matches the specified value and mask,
 	to use &unix; passwords at any time.</para>
 	
       <para>If no rules in <filename>opieaccess</filename> are matched,
 	the default is to deny non-OPIE logins.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="tcpwrappers">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Rhodes</surname>
 	  <contrib>Written by: </contrib>
 	</author>
       </authorgroup>
     </sect1info>
 
     <indexterm><primary>TCP Wrappers</primary></indexterm>
       
     <title>TCP Wrappers</title>
 
     <para>Anyone familiar with &man.inetd.8; has probably heard
       of <acronym>TCP</acronym> Wrappers at some point.  But few
       individuals seem to fully comprehend its usefulness in a
       network environment.  It seems that everyone wants to
       install a firewall to handle network connections.  While a
       firewall has a wide variety of uses, there are some things
       that a firewall not handle such as sending text back to the
       connection originator.  The <acronym>TCP</acronym> software
       does this and much more.  In the next few sections many of
       the <acronym>TCP</acronym> Wrappers features will be discussed,
       and, when applicable, example configuration lines will be
       provided.</para>
 
     <para>The <acronym>TCP</acronym> Wrappers software extends the
       abilities of <command>inetd</command> to provide support for
       every server daemon under its control.  Using this method it
       is possible to provide logging support, return messages to
       connections, permit a daemon to only accept internal connections,
       etc.  While some of these features can be provided by implementing
       a firewall, this will add not only an extra layer of protection
       but go beyond the amount of control a firewall can
       provide.</para>
 
     <para>The added functionality of <acronym>TCP</acronym> Wrappers
       should not be considered a replacement for a good firewall.
       <acronym>TCP</acronym> Wrappers can be used in conjunction
       with a firewall or other security enhancements though and
       it can serve nicely as an extra layer of protection
       for the system.</para>
 
     <para>Since this is an extension to the configuration of
       <command>inetd</command>, the reader is expected have
       read the <link linkend="network-inetd">inetd configuration</link>
       section.</para>
 
     <note>
       <para>While programs run by &man.inetd.8; are not exactly
 	<quote>daemons</quote>, they have traditionally been called
 	daemons.  This is the term we will use in this section too.</para>
     </note>
 
     <sect2>
       <title>Initial Configuration</title>
 
       <para>The only requirement of using <acronym>TCP</acronym>
 	Wrappers in &os; is to ensure the <command>inetd</command>
 	server is started from <filename>rc.conf</filename> with the
 	<option>-Ww</option> option; this is the default setting.  Of
 	course,	proper configuration of
 	<filename>/etc/hosts.allow</filename> is also expected, but
 	&man.syslogd.8; will throw messages in the system logs in
 	these cases.</para>
 
       <note>
 	<para>Unlike other implementations of <acronym>TCP</acronym>
 	  Wrappers, the use of <filename>hosts.deny</filename> has
 	  been deprecated.  All configuration options should be placed
 	  in <filename>/etc/hosts.allow</filename>.</para>
       </note>
 
       <para>In the simplest configuration, daemon connection policies
 	are set to either be permitted or blocked depending on the
 	options in <filename>/etc/hosts.allow</filename>.  The default
 	configuration in &os; is to allow a connection to every daemon
 	started with <command>inetd</command>.  Changing this will be
 	discussed only after the basic configuration is covered.</para>
 
       <para>Basic configuration usually takes the form of
 	<literal>daemon : address : action</literal>.  Where
 	<literal>daemon</literal> is the daemon name which
 	<command>inetd</command> started.  The
 	<literal>address</literal> can be a valid hostname, an
 	<acronym>IP</acronym> address or an IPv6 address enclosed in
 	brackets ([&nbsp;]).  The action field can be either allow
 	or deny	to grant or deny access appropriately.  Keep in mind
 	that configuration works off a first rule match semantic,
 	meaning that the configuration file is scanned in ascending
 	order for a matching rule.  When a match is found the rule
 	is applied and the search process will halt.</para>
 
       <para>Several other options exist but they will be explained
 	in a later section.  A simple configuration line may easily be
 	constructed from that information alone.  For example, to
 	allow <acronym>POP</acronym>3 connections via the
 	<filename role="package">mail/qpopper</filename> daemon,
 	the following lines should be appended to
 	<filename>hosts.allow</filename>:</para>
 
       <programlisting># This line is required for POP3 connections:
 qpopper : ALL : allow</programlisting>
 
       <para>After adding this line, <command>inetd</command> will need
 	restarted.  This can be accomplished by use of the &man.kill.1;
 	command, or with the <parameter>restart</parameter> parameter
 	with <filename>/etc/rc.d/inetd</filename>.</para>
       </sect2>
 
       <sect2>
         <title>Advanced Configuration</title>
 
       <para><acronym>TCP</acronym> Wrappers has advanced
 	options too; they will allow for more control over the
 	way connections are handled.  In some cases it may be
 	a good idea to return a comment to certain hosts or
 	daemon connections.  In other cases, perhaps a log file
 	should be recorded or an email sent to the administrator.
 	Other situations may require the use of a service for local
 	connections only.  This	is all possible through the use of
 	configuration options known as <literal>wildcards</literal>,
 	expansion characters and external command execution.  The
 	next two sections are written to cover these situations.</para>
 	
       <sect3>
 	<title>External Commands</title>
 
 	<para>Suppose that a situation occurs where a connection
 	  should be denied yet a reason should be sent to the
 	  individual who attempted to establish that connection.  How
 	  could it be done?  That action can be made possible by
 	  using the <option>twist</option> option.  When a connection
 	  attempt is made, <option>twist</option> will be called to
 	  execute a shell command or script.  An example already exists
 	  in the <filename>hosts.allow</filename> file:</para>
 
 	<programlisting># The rest of the daemons are protected.
 ALL : ALL \
         : severity auth.info \
         : twist /bin/echo "You are not welcome to use %d from %h."</programlisting>
 
 	<para>This example shows that the message,
 	  <quote>You are not allowed to use <literal>daemon</literal>
 	  from <literal>hostname</literal>.</quote> will be returned
 	  for any daemon not previously configured in the access file.
 	  This is extremely useful for sending a reply back to the
 	  connection initiator right after the established connection
 	  is dropped.  Note that any message returned
 	  <emphasis>must</emphasis> be wrapped in quote
 	  <literal>"</literal> characters; there are no exceptions to
 	  this rule.</para>
 
 	<warning>
 	  <para>It may be possible to launch a denial of service attack
 	    on the server if an attacker, or group of attackers could
 	    flood these daemons with connection requests.</para>
 	</warning>
 
 	<para>Another possibility is to use the <option>spawn</option>
 	  option in these cases.  Like <option>twist</option>, the
 	  <option>spawn</option> implicitly denies the connection and
 	  may be used to run external shell commands or scripts.
 	  Unlike <option>twist</option>, <option>spawn</option> will
 	  not send a reply back to the individual who established the
 	  connection.  For an example, consider the following
 	  configuration line:</para>
 
 	<programlisting># We do not allow connections from example.com:
 ALL : .example.com \
 	: spawn (/bin/echo %a from %h attempted to access %d &gt;&gt; \
 	  /var/log/connections.log) \
 	: deny</programlisting>
 
 	<para>This will deny all connection attempts from the
 	  <hostid role="fqdn">*.example.com</hostid> domain;
 	  simultaneously logging the hostname, <acronym>IP</acronym>
 	  address and the daemon which they attempted to access in the
 	  <filename>/var/log/connections.log</filename> file.</para>
 
 	<para>Aside from the already explained substitution characters
 	  above, e.g. %a, a few others exist.  See the
 	  &man.hosts.access.5; manual page for the complete list.</para>
       </sect3>
 
       <sect3>
 	<title>Wildcard Options</title>
 
 	<para>Thus far the <literal>ALL</literal> example has been used
 	  continuously throughout the examples.  Other options exist
 	  which could extend the functionality a bit further.  For
 	  instance, <literal>ALL</literal> may be used to match every
 	  instance of either a daemon, domain or an
 	  <acronym>IP</acronym> address. Another wildcard available is
 	  <literal>PARANOID</literal> which may be used to match any
 	  host which provides an <acronym>IP</acronym> address that may
 	  be forged.  In other words, <literal>paranoid</literal> may
 	  be used to define an action to be taken whenever a connection
 	  is made from an <acronym>IP</acronym> address that differs
 	  from its hostname.  The following example may shed some more
 	  light on this discussion:</para>
 
 	<programlisting># Block possibly spoofed requests to sendmail:
 sendmail : PARANOID : deny</programlisting>
 
 	<para>In that example all connection requests to
 	  <command>sendmail</command> which have an
 	  <acronym>IP</acronym> address that varies from its hostname
 	  will be denied.</para>
 
 	<caution>
 	  <para>Using the <literal>PARANOID</literal> may severely
 	    cripple servers if the client or server has a broken
 	    <acronym>DNS</acronym> setup.  Administrator discretion
 	    is advised.</para>
 	</caution>
 
 	<para>To learn more about wildcards and their associated
 	  functionality, see the &man.hosts.access.5; manual
 	  page.</para>
 
 	<para>Before any of the specific configuration lines above will
 	  work, the first configuration line should be commented out
 	  in <filename>hosts.allow</filename>.  This was noted at the
 	  beginning of this section.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="kerberosIV">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Mark</firstname>
 	  <surname>Murray</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Mark</firstname>
 	  <surname>Dapoz</surname>
 	  <contrib>Based on a contribution by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title><application>KerberosIV</application></title>
 
     <para>Kerberos is a network add-on system/protocol that allows users to
       authenticate themselves through the services of a secure server.
       Services such as remote login, remote copy, secure inter-system file
       copying and other high-risk tasks are made considerably safer and more
       controllable.</para>
 
     <para>The following instructions can be used as a guide on how to set up
       Kerberos as distributed for &os;. However, you should refer to the
       relevant manual pages for a complete description.</para>
 
     <sect2>
       <title>Installing <application>KerberosIV</application></title>
 
       <indexterm><primary>MIT</primary></indexterm>
       <indexterm>
 	<primary>KerberosIV</primary>
 	<secondary>installing</secondary>
       </indexterm>
       <para>Kerberos is an optional component of &os;.  The easiest
         way to install this software is by selecting the <literal>krb4</literal> or
         <literal>krb5</literal> distribution in <application>sysinstall</application>
         during the initial installation of &os;. This will install
         the <quote>eBones</quote> (KerberosIV) or <quote>Heimdal</quote> (Kerberos5)
         implementation of Kerberos.  These implementations are
         included because they are developed outside the USA/Canada and
         were thus available to system owners outside those countries
         during the era of restrictive export controls on cryptographic
         code from the USA.</para>
 
       <para>Alternatively, the MIT implementation of Kerberos is
         available from the ports collection as
         <filename role="package">security/krb5</filename>.</para>
     </sect2>
 
     <sect2>
       <title>Creating the Initial Database</title>
       
       <para>This is done on the Kerberos server only.  First make sure that
 	you do not have any old Kerberos databases around.  You should change
 	to the directory <filename>/etc/kerberosIV</filename> and check that
 	only the following files are present:</para>
 	  
       <screen>&prompt.root; <userinput>cd /etc/kerberosIV</userinput>
 &prompt.root; <userinput>ls</userinput>
 README		krb.conf        krb.realms</screen>
 	  
       <para>If any additional files (such as <filename>principal.*</filename>
 	or <filename>master_key</filename>) exist, then use the
 	<command>kdb_destroy</command> command to destroy the old Kerberos
 	database, or if Kerberos is not running, simply delete the extra
 	files.</para>
 	  
       <para>You should now edit the <filename>krb.conf</filename> and
 	<filename>krb.realms</filename> files to define your Kerberos realm.
 	In this case the realm will be <literal>EXAMPLE.COM</literal> and the
 	server is <hostid role="fqdn">grunt.example.com</hostid>.  We edit
 	or create the <filename>krb.conf</filename> file:</para>
 	  
       <screen>&prompt.root; <userinput>cat krb.conf</userinput>
 EXAMPLE.COM
 EXAMPLE.COM grunt.example.com admin server
 CS.BERKELEY.EDU okeeffe.berkeley.edu
 ATHENA.MIT.EDU kerberos.mit.edu
 ATHENA.MIT.EDU kerberos-1.mit.edu
 ATHENA.MIT.EDU kerberos-2.mit.edu
 ATHENA.MIT.EDU kerberos-3.mit.edu
 LCS.MIT.EDU kerberos.lcs.mit.edu
 TELECOM.MIT.EDU bitsy.mit.edu
 ARC.NASA.GOV trident.arc.nasa.gov</screen>
 	  
       <para>In this case, the other realms do not need to be there.  They are
 	here as an example of how a machine may be made aware of multiple
 	realms.  You may wish to not include them for simplicity.</para>
 	  
       <para>The first line names the realm in which this system works.  The
 	other lines contain realm/host entries.  The first item on a line is a
 	realm, and the second is a host in that realm that is acting as a
 	<quote>key distribution center</quote>.  The words <literal>admin
 	  server</literal> following a host's name means that host also
 	provides an administrative database server.  For further explanation
 	of these terms, please consult the Kerberos manual pages.</para>
 	  
       <para>Now we have to add <hostid role="fqdn">grunt.example.com</hostid>
 	to the <literal>EXAMPLE.COM</literal> realm and also add an entry to
 	put all hosts in the <hostid role="domainname">.example.com</hostid>
 	domain in the <literal>EXAMPLE.COM</literal> realm.  The
 	<filename>krb.realms</filename> file would be updated as
 	follows:</para>
 	  
       <screen>&prompt.root; <userinput>cat krb.realms</userinput>
 grunt.example.com EXAMPLE.COM
 .example.com EXAMPLE.COM
 .berkeley.edu CS.BERKELEY.EDU
 .MIT.EDU ATHENA.MIT.EDU
 .mit.edu ATHENA.MIT.EDU</screen>
 	  
       <para>Again, the other realms do not need to be there.  They are here as
 	an example of how a machine may be made aware of multiple realms.  You
 	may wish to remove them to simplify things.</para>
 	  
       <para>The first line puts the <emphasis>specific</emphasis> system into
 	the named realm.  The rest of the lines show how to default systems of
 	a particular subdomain to a named realm.</para>
 	  
       <para>Now we are ready to create the database.  This only needs to run
 	on the Kerberos server (or Key Distribution Center).  Issue the
 	<command>kdb_init</command> command to do this:</para>
 	  
       <screen>&prompt.root; <userinput>kdb_init</userinput>
 <prompt>Realm name [default  ATHENA.MIT.EDU ]:</prompt> <userinput>EXAMPLE.COM</userinput>
 You will be prompted for the database Master Password.
 It is important that you NOT FORGET this password.
 		
 <prompt>Enter Kerberos master key:</prompt> </screen>
 	  
       <para>Now we have to save the key so that servers on the local machine
 	can pick it up.  Use the <command>kstash</command> command to do
 	this:</para>
 	
       <screen>&prompt.root; <userinput>kstash</userinput>
 	      
 <prompt>Enter Kerberos master key:</prompt>
 
 Current Kerberos master key version is 1.
 
 Master key entered. BEWARE!</screen>
 	
       <para>This saves the encrypted master password in
 	<filename>/etc/kerberosIV/master_key</filename>.</para>
     </sect2>
     
     <sect2>
       <title>Making It All Run</title>
 	
       <indexterm>
 	<primary>KerberosIV</primary>
 	<secondary>initial startup</secondary>
       </indexterm>
 
       <para>Two principals need to be added to the database for
 	<emphasis>each</emphasis> system that will be secured with Kerberos.
 	Their names are <literal>kpasswd</literal> and <literal>rcmd</literal>.
 	These two principals are made for each system, with the instance being
 	the name of the individual system.</para>
 	  
       <para>These daemons, <application>kpasswd</application> and
 	<application>rcmd</application> allow other systems to change Kerberos
 	passwords and run commands like &man.rcp.1;,
 	&man.rlogin.1; and &man.rsh.1;.</para>
 	  
       <para>Now let us add these entries:</para>
 	    
       <screen>&prompt.root; <userinput>kdb_edit</userinput>
 Opening database...
 
 <prompt>Enter Kerberos master key:</prompt>
 
 Current Kerberos master key version is 1.
 
 Master key entered.  BEWARE!
 Previous or default values are in [brackets] ,
 enter return to leave the same, or new value.
 
 <prompt>Principal name:</prompt> <userinput>passwd</userinput>
 <prompt>Instance:</prompt> <userinput>grunt</userinput>
 
 &lt;Not found&gt;, <prompt>Create [y] ?</prompt> <userinput>y</userinput>
 
 Principal: passwd, Instance: grunt, kdc_key_ver: 1
 <prompt>New Password:</prompt>                    &lt;---- enter RANDOM here
 Verifying password
 
 <prompt>New Password:</prompt> &lt;---- enter RANDOM here
 
 <prompt>Random password [y] ?</prompt> <userinput>y</userinput>
 
 Principal's new key version = 1
 <prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
 <prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt>
 <prompt>Attributes [ 0 ] ?</prompt>
 Edit O.K.
 <prompt>Principal name:</prompt> <userinput>rcmd</userinput>
 <prompt>Instance:</prompt> <userinput>grunt</userinput>
 
 &lt;Not found&gt;, <prompt>Create [y] ?</prompt>
 
 Principal: rcmd, Instance: grunt, kdc_key_ver: 1
 <prompt>New Password:</prompt>		&lt;---- enter RANDOM here
 Verifying password
 
 <prompt>New Password:</prompt>           &lt;---- enter RANDOM here
 
 <prompt>Random password [y] ?</prompt>
 
 Principal's new key version = 1
 <prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
 <prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt>
 <prompt>Attributes [ 0 ] ?</prompt>
 Edit O.K.
 <prompt>Principal name:</prompt>         &lt;---- null entry here will cause an exit</screen>
     </sect2>
 
     <sect2>
       <title>Creating the Server File</title>
       
       <para>We now have to extract all the instances which define the
 	services on each machine.  For this we use the
 	<command>ext_srvtab</command> command.  This will create a file
 	which must be copied or moved <emphasis>by secure
 	  means</emphasis> to each Kerberos client's
 	<filename>/etc/kerberosIV</filename> directory.  This file must
 	be present on each server and client, and is crucial to the
 	operation of Kerberos.</para>
 	  
 	  
       <screen>&prompt.root; <userinput>ext_srvtab grunt</userinput>
 <prompt>Enter Kerberos master key:</prompt>
 		
 Current Kerberos master key version is 1.
 
 Master key entered. BEWARE!
 Generating 'grunt-new-srvtab'....</screen>
 	  
       <para>Now, this command only generates a temporary file which must be
 	renamed to <filename>srvtab</filename> so that all the servers can pick
 	it up.  Use the &man.mv.1; command to move it into place on
 	the original system:</para>
 	  
       <screen>&prompt.root; <userinput>mv grunt-new-srvtab srvtab</userinput></screen>
 	  
       <para>If the file is for a client system, and the network is not deemed
 	safe, then copy the
 	<filename><replaceable>client</replaceable>-new-srvtab</filename> to
 	removable media and transport it by secure physical means.  Be sure to
 	rename it to <filename>srvtab</filename> in the client's
 	<filename>/etc/kerberosIV</filename> directory, and make sure it is
 	mode 600:</para>
 	  
       <screen>&prompt.root; <userinput>mv grumble-new-srvtab srvtab</userinput>
 &prompt.root; <userinput>chmod 600 srvtab</userinput></screen>
     </sect2>
     
     <sect2>
       <title>Populating the Database</title>
       
       <para>We now have to add some user entries into the database.  First
 	let us create an entry for the user <username>jane</username>.  Use the
 	<command>kdb_edit</command> command to do this:</para>
 	  
       <screen>&prompt.root; <userinput>kdb_edit</userinput>
 Opening database...
 
 <prompt>Enter Kerberos master key:</prompt>
 
 Current Kerberos master key version is 1.
 
 Master key entered.  BEWARE!
 Previous or default values are in [brackets] ,
 enter return to leave the same, or new value.
 
 <prompt>Principal name:</prompt> <userinput>jane</userinput>
 <prompt>Instance:</prompt>
 
 &lt;Not found&gt;, <prompt>Create [y] ?</prompt> <userinput>y</userinput>
 
 Principal: jane, Instance: , kdc_key_ver: 1
 <prompt>New Password:</prompt>                &lt;---- enter a secure password here
 Verifying password
 
 <prompt>New Password:</prompt>                &lt;---- re-enter the password here
 Principal's new key version = 1
 <prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
 <prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt>
 <prompt>Attributes [ 0 ] ?</prompt>
 Edit O.K.
 <prompt>Principal name:</prompt>		   &lt;---- null entry here will cause an exit</screen>
     </sect2>
 
     <sect2>
       <title>Testing It All Out</title>
       
       <para>First we have to start the Kerberos daemons.  Note that if you
 	have correctly edited your <filename>/etc/rc.conf</filename> then this
 	will happen automatically when you reboot.  This is only necessary on
 	the Kerberos server.  Kerberos clients will automatically get what
 	they need from the <filename>/etc/kerberosIV</filename>
 	directory.</para>
 	  
       <screen>&prompt.root; <userinput>kerberos &amp;</userinput>
 Kerberos server starting
 Sleep forever on error
 Log file is /var/log/kerberos.log
 Current Kerberos master key version is 1.
 
 Master key entered. BEWARE!
 
 Current Kerberos master key version is 1
 Local realm: EXAMPLE.COM
 &prompt.root; <userinput>kadmind -n &amp;</userinput>
 KADM Server KADM0.0A initializing
 Please do not use 'kill -9' to kill this job, use a
 regular kill instead
 
 Current Kerberos master key version is 1.
 
 Master key entered.  BEWARE!</screen>
 	  
       <para>Now we can try using the <command>kinit</command> command to get a
 	ticket for the ID <username>jane</username> that we created
 	above:</para>
 	  
       <screen>&prompt.user; <userinput>kinit jane</userinput>
 MIT Project Athena (grunt.example.com)
 Kerberos Initialization for "jane"
 <prompt>Password:</prompt> </screen>
 	  
       <para>Try listing the tokens using <command>klist</command> to see if we
 	really have them:</para>
 	  
       <screen>&prompt.user; <userinput>klist</userinput>
 Ticket file:    /tmp/tkt245
 Principal:      jane@EXAMPLE.COM
 
   Issued           Expires          Principal
 Apr 30 11:23:22  Apr 30 19:23:22  krbtgt.EXAMPLE.COM@EXAMPLE.COM</screen>
 	  
       <para>Now try changing the password using &man.passwd.1; to
 	check if the <application>kpasswd</application> daemon can get 
 	authorization to the Kerberos database:</para>
 	  
       <screen>&prompt.user; <userinput>passwd</userinput>
 realm EXAMPLE.COM
 <prompt>Old password for jane:</prompt>
 <prompt>New Password for jane:</prompt>
 Verifying password
 <prompt>New Password for jane:</prompt>
 Password changed.</screen>
     </sect2>
 
     <sect2>
       <title>Adding <command>su</command> Privileges</title>
       
       <para>Kerberos allows us to give <emphasis>each</emphasis> user
 	who needs <username>root</username> privileges their own
 	<emphasis>separate</emphasis> &man.su.1; password.
 	We could now add an ID which is authorized to
 	&man.su.1; to <username>root</username>.  This is
 	controlled by having an instance of <username>root</username>
 	associated with a principal.  Using <command>kdb_edit</command>
 	we can create the entry <literal>jane.root</literal> in the
 	Kerberos database:</para>
 	  
       <screen>&prompt.root; <userinput>kdb_edit</userinput>
 Opening database...
 
 <prompt>Enter Kerberos master key:</prompt>
 
 Current Kerberos master key version is 1.
 
 Master key entered.  BEWARE!
 Previous or default values are in [brackets] ,
 enter return to leave the same, or new value.
 
 <prompt>Principal name:</prompt> <userinput>jane</userinput>
 <prompt>Instance:</prompt> <userinput>root</userinput>
 
 &lt;Not found&gt;, Create [y] ? y
 
 Principal: jane, Instance: root, kdc_key_ver: 1
 <prompt>New Password:</prompt>                    &lt;---- enter a SECURE password here
 Verifying password
 
 <prompt>New Password:</prompt>    	 	 &lt;---- re-enter the password here
 
 Principal's new key version = 1
 <prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
 <prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> <userinput>12</userinput> &lt;--- Keep this short!
 <prompt>Attributes [ 0 ] ?</prompt>
 Edit O.K.
 <prompt>Principal name:</prompt>		         &lt;---- null entry here will cause an exit</screen>
 	  
       <para>Now try getting tokens for it to make sure it works:</para>
       
       <screen>&prompt.root; <userinput>kinit jane.root</userinput>
 MIT Project Athena (grunt.example.com)
 Kerberos Initialization for "jane.root"
 <prompt>Password:</prompt></screen>
 	  
       <para>Now we need to add the user to <username>root</username>'s
 	  <filename>.klogin</filename> file:</para>
 	  
       <screen>&prompt.root; <userinput>cat /root/.klogin</userinput>
 jane.root@EXAMPLE.COM</screen>
 	  
       <para>Now try doing the &man.su.1;:</para>
 	  
       <screen>&prompt.user; <userinput>su</userinput>
 <prompt>Password:</prompt></screen>
 	  
       <para>and take a look at what tokens we have:</para>
 	  
       <screen>&prompt.root; <userinput>klist</userinput>
 Ticket file:	/tmp/tkt_root_245
 Principal:      jane.root@EXAMPLE.COM
 
   Issued           Expires          Principal
 May  2 20:43:12  May  3 04:43:12  krbtgt.EXAMPLE.COM@EXAMPLE.COM</screen>
     </sect2>
 
     <sect2>
       <title>Using Other Commands</title>
       
       <para>In an earlier example, we created a principal called
 	<literal>jane</literal> with an instance <literal>root</literal>.
 	This was based on a user with the same name as the principal, and this
 	is a Kerberos default; that a
 	<literal>&lt;principal&gt;.&lt;instance&gt;</literal> of the form
 	<literal>&lt;username&gt;.</literal><username>root</username> will allow
 	that <literal>&lt;username&gt;</literal> to &man.su.1; to
 	<username>root</username> if the necessary entries are in the
 	<filename>.klogin</filename> file in <username>root</username>'s
 	home directory:</para>
 	  
       <screen>&prompt.root; <userinput>cat /root/.klogin</userinput>
 jane.root@EXAMPLE.COM</screen>
       
       <para>Likewise, if a user has in their own home directory lines of the
 	form:</para>
       
       <screen>&prompt.user; <userinput>cat ~/.klogin</userinput>
 jane@EXAMPLE.COM
 jack@EXAMPLE.COM</screen>
 	  
       <para>This allows anyone in the <literal>EXAMPLE.COM</literal> realm
 	who has authenticated themselves as <username>jane</username> or
 	<username>jack</username> (via <command>kinit</command>, see above)
 	to access to <username>jane</username>'s
 	account or files on this system (<hostid>grunt</hostid>) via
 	&man.rlogin.1;, &man.rsh.1; or
 	&man.rcp.1;.</para>
 	  
       <para>For example, <username>jane</username> now logs into another system using
 	Kerberos:</para>
 	  
 	    <screen>&prompt.user; <userinput>kinit</userinput>
 MIT Project Athena (grunt.example.com)
 <prompt>Password:</prompt>
 &prompt.user; <userinput>rlogin grunt</userinput>
 Last login: Mon May  1 21:14:47 from grumble
 Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
         The Regents of the University of California.   All rights reserved.
 
 FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
 	  
       <para>Or <username>jack</username> logs into <username>jane</username>'s account on the same machine
 	(<username>jane</username> having
 	set up the <filename>.klogin</filename> file as above, and the person
 	in charge of Kerberos having set up principal
 	<emphasis>jack</emphasis> with a null instance):</para>
 	  
       <screen>&prompt.user; <userinput>kinit</userinput>
 &prompt.user; <userinput>rlogin grunt -l jane</userinput>
 MIT Project Athena (grunt.example.com)
 <prompt>Password:</prompt>
 Last login: Mon May  1 21:16:55 from grumble
 Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
         The Regents of the University of California.   All rights reserved.
 FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
     </sect2>
   </sect1>
 
   <sect1 id="kerberos5">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tillman</firstname>
 	  <surname>Hodgson</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Mark</firstname>
 	  <surname>Murray</surname>
 	  <contrib>Based on a contribution by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title><application>Kerberos5</application></title>
 
     <para>Every &os; release beyond &os;-5.1 includes support
       only for <application>Kerberos5</application>.  Hence
       <application>Kerberos5</application> is the only version
       included, and its configuration is similar in many aspects
       to that of <application>KerberosIV</application>.  The following
       information only applies to
       <application>Kerberos5</application> in post &os;-5.0
       releases.  Users who wish to use the
       <application>KerberosIV</application> package may install the
       <filename role="package">security/krb4</filename> port.</para>
 
     <para><application>Kerberos</application> is a network add-on
       system/protocol that allows users to authenticate themselves
       through the services of a secure server.  Services such as remote
       login, remote copy, secure inter-system file copying and other
       high-risk tasks are made considerably safer and more
       controllable.</para>
 
     <para><application>Kerberos</application> can be described as an
       identity-verifying proxy system.  It can also be described as a
       trusted third-party authentication system.
       <application>Kerberos</application> provides only one
       function &mdash; the secure authentication of users on the network.
       It does not provide authorization functions (what users are
       allowed to do) or auditing functions (what those users did).
       After a client and server have used
       <application>Kerberos</application> to prove their identity, they
       can also encrypt all of their communications to assure privacy
       and data integrity as they go about their business.</para>
 
     <para>Therefore it is highly recommended that
       <application>Kerberos</application> be used with other security
       methods which provide authorization and audit services.</para>
 
     <para>The following instructions can be used as a guide on how to set
       up <application>Kerberos</application> as distributed for &os;.
       However, you should refer to the relevant manual pages for a complete
       description.</para>
 
     <para>For purposes of demonstrating a <application>Kerberos</application>
       installation, the various name spaces will be handled as follows:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The <acronym>DNS</acronym> domain (<quote>zone</quote>)
 	  will be example.org.</para>
       </listitem>
 
       <listitem>
 	<para>The <application>Kerberos</application> realm will be
 	  EXAMPLE.ORG.</para>
       </listitem>
     </itemizedlist>
 
     <note>
       <para>Please use real domain names when setting up
 	<application>Kerberos</application> even if you intend to run
 	it internally.  This avoids <acronym>DNS</acronym> problems
 	and assures inter-operation with other
 	<application>Kerberos</application> realms.</para>
     </note>
 
     <sect2>
       <title>History</title>
       <indexterm>
 	<primary>Kerberos5</primary>
 	<secondary>history</secondary>
       </indexterm>
 
       <para><application>Kerberos</application> was created by
 	<acronym>MIT</acronym> as a solution to network security problems.
 	The <application>Kerberos</application> protocol uses strong
 	cryptography so that a client can prove its identity to a server
 	(and vice versa) across an insecure network connection.</para>
 
       <para><application>Kerberos</application> is both the name of a
 	network authentication protocol and an adjective to describe
 	programs that implement the program
 	(<application>Kerberos</application> telnet, for example).  The
 	current version of the protocol is version 5, described in
 	<acronym>RFC</acronym>&nbsp;1510.</para>
 
       <para>Several free implementations of this protocol are available,
 	covering a wide range of operating systems.  The Massachusetts
 	Institute of Technology (<acronym>MIT</acronym>), where
 	<application>Kerberos</application> was originally developed,
 	continues to develop their <application>Kerberos</application>
 	package.  It is commonly used in the <acronym>US</acronym>
 	as a cryptography product, as such it
 	has historically been affected by <acronym>US</acronym> export
 	regulations.  The <acronym>MIT</acronym>
 	<application>Kerberos</application> is available as a port
 	(<filename role="package">security/krb5</filename>).  Heimdal
 	<application>Kerberos</application> is another version 5
 	implementation, and was explicitly developed outside of the
 	<acronym>US</acronym> to avoid export
 	regulations (and is thus often included in non-commercial &unix;
 	variants).  The Heimdal <application>Kerberos</application>
 	distribution is available as a port
 	(<filename role="package">security/heimdal</filename>), and a
 	minimal installation of it is included in the base &os;
 	install.</para>
 
     <para>In order to reach the widest audience, these instructions assume
 	the use of the Heimdal distribution included in &os;.</para>
 
     </sect2>
 
     <sect2>
       <title>Setting up a Heimdal <acronym>KDC</acronym></title>
       <indexterm>
 	<primary>Kerberos5</primary>
 	<secondary>Key Distribution Center</secondary>
       </indexterm>
 
       <para>The Key Distribution Center (<acronym>KDC</acronym>) is the
 	centralized authentication service that
 	<application>Kerberos</application> provides &mdash; it is the
 	computer that issues <application>Kerberos</application> tickets.
 	The <acronym>KDC</acronym> is considered <quote>trusted</quote> by
 	all other computers in the <application>Kerberos</application>
 	realm, and thus has heightened security concerns.</para>
 
     <para>Note that while running the <application>Kerberos</application>
 	server requires very few computing resources, a dedicated machine
 	acting only as a <acronym>KDC</acronym> is recommended for security
 	reasons.</para>
 
     <para>To begin setting up a <acronym>KDC</acronym>, ensure that your
 	<filename>/etc/rc.conf</filename> file contains the correct
 	settings to act as a <acronym>KDC</acronym> (you may need to adjust
 	paths to reflect your own system):</para>
 
     <programlisting>kerberos5_server_enable="YES"
 kadmind5_server_enable="YES"
 kerberos_stash="YES"</programlisting>
 
       <note>
 	<para>The <option>kerberos_stash</option> is only available in
 	  &os; 4.X.</para>
       </note>
 
       <para>Next we will set up your <application>Kerberos</application>
 	config file, <filename>/etc/krb5.conf</filename>:</para>
 
       <programlisting>[libdefaults]
     default_realm = EXAMPLE.ORG
 [realms]
     EXAMPLE.ORG = {
         kdc = kerberos.example.org
         admin_server = kerberos.example.org
     }
 [domain_realm]
     .example.org = EXAMPLE.ORG</programlisting>
 
       <para>Note that this <filename>/etc/krb5.conf</filename> file implies
 	that your <acronym>KDC</acronym> will have the fully-qualified
 	hostname of <hostid role="fqdn">kerberos.example.org</hostid>.
 	You will need to add a CNAME (alias) entry to your zone file to
 	accomplish this if your <acronym>KDC</acronym> has a different
 	hostname.</para>
 
       <note>
 	<para>For large networks with a properly configured
 	  <acronym>BIND</acronym> <acronym>DNS</acronym> server, the
 	  above example could be trimmed to:</para>
 
 	<programlisting>[libdefaults]
       default_realm = EXAMPLE.ORG</programlisting>
 
 	<para>With the following lines being appended to the
 	  <hostid role="fqdn">example.org</hostid> zonefile:</para>
 
 	<programlisting>_kerberos._udp      IN  SRV     01 00 88 kerberos.example.org.
 _kerberos._tcp      IN  SRV     01 00 88 kerberos.example.org.
 _kpasswd._udp       IN  SRV     01 00 464 kerberos.example.org.
 _kerberos-adm._tcp  IN  SRV     01 00 749 kerberos.example.org.
 _kerberos           IN  TXT     EXAMPLE.ORG.</programlisting></note>
 
       <note>
         <para>For clients to be able to find the
           <application>Kerberos</application> services, you
           <emphasis>must</emphasis> have either a fully configured
           <filename>/etc/krb5.conf</filename> or a miminally configured
           <filename>/etc/krb5.conf</filename> <emphasis>and</emphasis> a
           properly configured DNS server.</para>
       </note>
 
       <para>Next we will create the <application>Kerberos</application>
 	database.  This database contains the keys of all principals encrypted
 	with a master password.  You are not
 	required to remember this password, it will be stored in a file
 	(<filename>/var/heimdal/m-key</filename>).  To create the master
 	key, run <command>kstash</command> and enter a password.</para>
 
       <para>Once the master key has been created, you can initialize the
 	database using the <command>kadmin</command> program with the
 	<literal>-l</literal> option (standing for <quote>local</quote>).
 	This option instructs <command>kadmin</command> to modify the
 	database files directly rather than going through the
 	<command>kadmind</command> network service.  This handles the
 	chicken-and-egg problem of trying to connect to the database
 	before it is created.  Once you have the <command>kadmin</command>
 	prompt, use the <command>init</command> command to create your
 	realms initial database.</para>
 
       <para>Lastly, while still in <command>kadmin</command>, create your
 	first principal using the <command>add</command> command.  Stick
 	to the defaults options for the principal for now, you can always
 	change them later with the <command>modify</command> command.
 	Note that you can use the <literal>?</literal> command at any
 	prompt to see the available options.</para>
 
       <para>A sample database creation session is shown below:</para>
 
       <screen>&prompt.root; <userinput>kstash</userinput>
 Master key: <userinput>xxxxxxxx</userinput>
 Verifying password - Master key: <userinput>xxxxxxxx</userinput>
 
 &prompt.root; <userinput>kadmin -l</userinput>
 kadmin> <userinput>init EXAMPLE.ORG</userinput>
 Realm max ticket life [unlimited]:
 kadmin> <userinput>add tillman</userinput>
 Max ticket life [unlimited]:
 Max renewable life [unlimited]:
 Attributes []:
 Password: <userinput>xxxxxxxx</userinput>
 Verifying password - Password: <userinput>xxxxxxxx</userinput></screen>
 
       <para>Now it is time to start up the <acronym>KDC</acronym> services.
 	Run <command>/etc/rc.d/kerberos start</command> and
 	<command>/etc/rc.d/kadmind start</command> to bring up the
 	services.  Note that you won't have any kerberized daemons running
 	at this point but you should be able to confirm the that the
 	<acronym>KDC</acronym> is functioning by obtaining and listing a
 	ticket for the principal (user) that you just created from the
 	command-line of the <acronym>KDC</acronym> itself:</para>
 
       <screen>&prompt.user; <userinput>k5init <replaceable>tillman</replaceable></userinput>
 tillman@EXAMPLE.ORG's Password:
 
 &prompt.user; <userinput>k5list</userinput>
 Credentials cache: FILE:<filename>/tmp/krb5cc_500</filename>
 	Principal: tillman@EXAMPLE.ORG
 
   Issued           Expires          Principal
 Aug 27 15:37:58  Aug 28 01:37:58  krbtgt/EXAMPLE.ORG@EXAMPLE.ORG</screen>
 
       </sect2>
 
       <sect2>
 	<title><application>Kerberos</application> enabling a server with
 	  Heimdal services</title>
 
         <indexterm>
 	  <primary>Kerberos5</primary>
 	  <secondary>enabling services</secondary>
         </indexterm>
 
 	<para>First, we need a copy of the <application>Kerberos</application>
 	  configuration file, <filename>/etc/krb5.conf</filename>.  To do
 	  so, simply copy it over to the client computer from the
 	  <acronym>KDC</acronym> in a secure fashion (using network utilities,
 	  such as &man.scp.1;, or physically via a
 	  floppy disk).</para>
 
 	<para>Next you need a <filename>/etc/krb5.keytab</filename> file.
 	  This is the major difference between a server providing
 	  <application>Kerberos</application> enabled daemons and a
 	  workstation &mdash; the server must have a
 	  <filename>keytab</filename> file.  This file
 	  contains the servers host key, which allows it and the
 	  <acronym>KDC</acronym> to verify each others identity.  It
 	  must be transmitted to the server in a secure fashion, as the
 	  security of the server can be broken if the key is made public.
 	  This explicitly means that transferring it via a clear text
 	  channel, such as <acronym>FTP</acronym>, is a very bad idea.</para>
 
 	<para>Typically, you transfer to the <filename>keytab</filename>
 	  to the server using the <command>kadmin</command> program.
 	  This is handy because you also need to create the host principal
 	  (the <acronym>KDC</acronym> end of the
 	  <filename>krb5.keytab</filename>) using
 	  <command>kadmin</command>.</para>
 
 	<para>Note that you must have already obtained a ticket and that this
 	  ticket must be allowed to use the <command>kadmin</command>
 	  interface in the <filename>kadmind.acl</filename>.  See the section
 	  titled <quote>Remote administration</quote> in the Heimdal info
 	  pages (<command>info heimdal</command>) for details on designing
 	  access control lists.  If you do not want to enable remote
 	  <command>kadmin</command> access, you can simply securely connect
 	  to the <acronym>KDC</acronym> (via local console,
 	  &man.ssh.1; or <application>Kerberos</application>
 	  &man.telnet.1;) and perform administration locally
 	  using <command>kadmin -l</command>.</para>
 
 	<para>After installing the <filename>/etc/krb5.conf</filename> file,
 	  you can use <command>kadmin</command> from the
 	  <application>Kerberos</application> server.  The
 	  <command>add --random-key</command> command will let you add the
 	  servers host principal, and the <command>ext</command> command
 	  will allow you to extract the servers host principal to its own
 	  keytab.  For example:</para>
 
 	<screen>&prompt.root; <userinput>kadmin</userinput>
 kadmin><userinput> add --random-key host/myserver.example.org</userinput>
 Max ticket life [unlimited]:
 Max renewable life [unlimited]:
 Attributes []:
 kadmin><userinput> ext host/myserver.example.org</userinput>
 kadmin><userinput> exit</userinput></screen>
 
 	<para>Note that the <command>ext</command> command (short for
 	  <quote>extract</quote>) stores the extracted key in
 	  <filename>/etc/krb5.keytab</filename> by default.</para>
 
 	<para>If you do not have <command>kadmind</command> running on the
 	  <acronym>KDC</acronym> (possibly for security reasons) and thus
 	  do not have access to <command>kadmin</command> remotely, you
 	  can add the host principal
 	  (<username>host/myserver.EXAMPLE.ORG</username>) directly on the
 	  <acronym>KDC</acronym> and then extract it to a temporary file
 	  (to avoid over-writing the <filename>/etc/krb5.keytab</filename>
 	  on the <acronym>KDC</acronym>) using something like this:</para>
 
 	<screen>&prompt.root; <userinput>kadmin</userinput>
 kadmin><userinput> ext --keytab=/tmp/example.keytab host/myserver.example.org</userinput>
 kadmin><userinput> exit</userinput></screen>
 
 	<para>You can then securely copy the keytab to the server
 	  computer (using <command>scp</command> or a floppy, for
 	  example).  Be sure to specify a non-default keytab name
 	  to avoid over-writing the keytab on the
 	  <acronym>KDC</acronym>.</para>
 
 	<para>At this point your server can communicate with the
 	  <acronym>KDC</acronym> (due to its <filename>krb5.conf</filename>
 	  file) and it can prove its own identity (due to the
 	  <filename>krb5.keytab</filename> file).  It is now ready for
 	  you to enable some <application>Kerberos</application> services.
 	  For this example we will enable the <command>telnet</command>
 	  service by putting a line like this into your
 	  <filename>/etc/inetd.conf</filename> and then restarting the
 	  &man.inetd.8; service with
 	  <command>/etc/rc.d/inetd restart</command>:</para>
 
 	<programlisting>telnet    stream  tcp     nowait  root    /usr/libexec/telnetd  telnetd -a user</programlisting>
 
 	<para>The critical bit is that the <command>-a</command>
 	  (for authentication) type is set to user.  Consult the
 	  &man.telnetd.8; manual page for more details.</para>
 
       </sect2>
 
       <sect2>
 	<title><application>Kerberos</application> enabling a client with Heimdal</title>
 
 	<indexterm>
 	  <primary>Kerberos5</primary>
 	  <secondary>configure clients</secondary>
 	</indexterm>
 
 	<para>Setting up a client computer is almost trivially easy.  As
 	  far as <application>Kerberos</application> configuration goes,
 	  you only need the <application>Kerberos</application>
 	  configuration file, located at <filename>/etc/krb5.conf</filename>.
 	  Simply securely copy it over to the client computer from the
 	  <acronym>KDC</acronym>.</para>
 
 	<para>Test your client computer by attempting to use
 	  <command>kinit</command>, <command>klist</command>, and
 	  <command>kdestroy</command> from the client to obtain, show, and
 	  then delete a ticket for the principal you created above.  You
 	  should also be able to use <application>Kerberos</application>
 	  applications to connect to <application>Kerberos</application>
 	  enabled servers, though if that does not work and obtaining a
 	  ticket does the problem is likely with the server and not with
 	  the client or the <acronym>KDC</acronym>.</para>
 
 	<para>When testing an application like <command>telnet</command>,
 	  try using a packet sniffer (such as &man.tcpdump.1;)
 	  to confirm that your password is not sent in the clear.  Try
 	  using <command>telnet</command> with the <literal>-x</literal>
 	  option, which encrypts the entire data stream (similar to
 	  <command>ssh</command>).</para>
 
 	<para>The core <application>Kerberos</application> client applications
 	  (traditionally named <command>kinit</command>,
 	  <command>klist</command>, <command>kdestroy</command>, and
 	  <command>kpasswd</command>) are installed in
 	  the base &os; install. Note that &os; versions prior to 5.0
 	  renamed them to <command>k5init</command>,
 	  <command>k5list</command>, <command>k5destroy</command>,
 	  <command>k5passwd</command>, and <command>k5stash</command>
 	  (though it is typically only used once).</para>
 
 	<para>Various non-core <application>Kerberos</application> client
 	  applications are also installed by default.  This is where the
 	  <quote>minimal</quote> nature of the base Heimdal installation is
 	  felt: <command>telnet</command> is the only
 	  <application>Kerberos</application> enabled service.</para>
 
 	<para>The Heimdal port adds some of the missing client applications:
 	  <application>Kerberos</application> enabled versions of
 	  <command>ftp</command>, <command>rsh</command>,
 	  <command>rcp</command>, <command>rlogin</command>, and a few
 	  other less common programs. The <acronym>MIT</acronym> port also
 	  contains a full suite of <application>Kerberos</application>
 	  client applications.</para>
 
       </sect2>
 
       <sect2>
 	<title>User configuration files: <filename>.k5login</filename> and <filename>.k5users</filename></title>
 
 	<indexterm>
 	  <primary>Kerberos5</primary>
 	  <secondary>user configuration files</secondary>
 	</indexterm>
 
 	<para>Users within a realm typically have their
 	  <application>Kerberos</application> principal (such as
 	  <username>tillman@EXAMPLE.ORG</username>) mapped to a local
 	  user account (such as a local account named
 	  <username>tillman</username>).  Client applications such as
 	  <command>telnet</command> usually do not require a user name
 	  or a principal.</para>
 
 	<para>Occasionally, however, you want to grant access to a local
 	  user account to someone who does not have a matching
 	  <application>Kerberos</application> principal.  For example,
 	  <username>tillman@EXAMPLE.ORG</username> may need access to the
 	  local user account <username>webdevelopers</username>.  Other
 	  principals may also need access to that local account.</para>
 
 	<para>The <filename>.k5login</filename> and
 	  <filename>.k5users</filename> files, placed in a users home
 	  directory, can be used similar to a powerful combination of
 	  <filename>.hosts</filename> and <filename>.rhosts</filename>,
 	  solving this problem. For example, if a
 	  <filename>.k5login</filename> with the following
 	  contents:</para>
 
 	<screen>tillman@example.org
 jdoe@example.org</screen>
 
 	<para>Were to be placed into the home directory of the local user
 	  <username>webdevelopers</username> then both principals listed
 	  would have access to that account without requiring a shared
 	  password.</para>
 
 	<para>Reading the manual pages for these commands is recommended.
 	  Note that the <command>ksu</command> manual page covers
 	  <filename>.k5users</filename>.</para>
 
       </sect2>
 
       <sect2>
 	<title><application>Kerberos</application> Tips, Tricks, and Troubleshooting</title>
 
 	<indexterm>
 	  <primary>Kerberos5</primary>
 	  <secondary>troubleshooting</secondary>
 	</indexterm>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>When using either the Heimdal or <acronym>MIT</acronym>
 	      <application>Kerberos</application> ports ensure that your
 	      <envar>PATH</envar> environment variable lists the
 	      <application>Kerberos</application> versions of the client
 	      applications before the system versions.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Do all the computers in your realm have synchronized
 	      time settings?  If not, authentication may fail.
 	      <xref linkend="network-ntp"> describes how to synchronize
 	      clocks using <acronym>NTP</acronym>.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><acronym>MIT</acronym> and Heimdal inter-operate nicely.
 	      Except for <command>kadmin</command>, the protocol for
 	      which is not standardized.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you change your hostname, you also need to change your
 	      <username>host/</username> principal and update your keytab.
 	      This also applies to special keytab entries like the
 	      <username>www/</username> principal used for Apache's
 	      <filename role="package">www/mod_auth_kerb</filename>.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>All hosts in your realm must be resolvable (both forwards
 	      and reverse) in <acronym>DNS</acronym> (or
 	      <filename>/etc/hosts</filename> as a minimum).  CNAMEs
 	      will work, but the A and PTR records must be correct and in
 	      place. The error message isn't very intuitive:
 	      <errorname>Kerberos5 refuses authentication because Read req
 	      failed: Key table entry not found</errorname>.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Some operating systems that may being acting as clients
 	      to your <acronym>KDC</acronym> do not set the permissions
 	      for <command>ksu</command> to be setuid
 	      <username>root</username>.  This means that
 	      <command>ksu</command> does not work, which is a good
 	      security idea but annoying. This is not a
 	      <acronym>KDC</acronym> error.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>With <acronym>MIT</acronym>
 	      <application>Kerberos</application>, if you want to allow a
 	      principal to have a ticket life longer than the default ten
 	      hours, you must use <command>modify_principal</command> in
 	      <command>kadmin</command> to change the maxlife of both the
 	      principal in question and the <username>krbtgt</username>
 	      principal.  Then the principal can use the
 	      <literal>-l</literal> option with <command>kinit</command>
 	      to request a ticket with a longer lifetime.</para>
 	  </listitem>
 
 	  <listitem>
 	    <note><para>If you run a packet sniffer on your
 	      <acronym>KDC</acronym> to add in troubleshooting and then
 	      run <command>kinit</command> from a workstation, you will
 	      notice that your <acronym>TGT</acronym> is sent
 	      immediately upon running <command>kinit</command> &mdash;
 	      even before you type your password!  The explanation is
 	      that the <application>Kerberos</application> server freely
 	      transmits a <acronym>TGT</acronym> (Ticket Granting
 	      Ticket) to any unauthorized request;  however, every
 	      <acronym>TGT</acronym> is encrypted in a key derived from
 	      the user's password.  Therefore, when a user types their
 	      password it is not being sent to the <acronym>KDC</acronym>,
 	      it is being used to decrypt the <acronym>TGT</acronym> that
 	      <command>kinit</command> already obtained. If the decryption
 	      process results in a valid ticket with a valid time stamp,
 	      the user has valid <application>Kerberos</application>
 	      credentials.  These credentials include a session key for
 	      establishing secure communications with the
 	      <application>Kerberos</application> server in the future, as
 	      well as the actual ticket-granting ticket, which is actually
 	      encrypted with the <application>Kerberos</application>
 	      server's own key.  This second layer of encryption is
 	      unknown to the user, but it is what allows the
 	      <application>Kerberos</application> server to verify
 	      the authenticity of each <acronym>TGT</acronym>.</para></note>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you want to use long ticket lifetimes (a week, for
 	      example) and you are using <application>OpenSSH</application>
 	      to connect to the machine where your ticket is stored, make
 	      sure that <application>Kerberos</application>
 	      <option>TicketCleanup</option> is set to <literal>no</literal>
 	      in your <filename>sshd_config</filename> or else your tickets
 	      will be deleted when you log out.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Remember that host principals can have a longer ticket
 	      lifetime as well.  If your user principal has a lifetime of a
 	      week but the host you are connecting to has a lifetime of nine
 	      hours, you will have an expired host principal in your cache
 	      and the ticket cache will not work as expected.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>When setting up a <filename>krb5.dict</filename> file to
 	    prevent specific bad passwords from being used (the manual page
 	    for <command>kadmind</command> covers this briefly), remember
 	    that it only applies to principals that have a password policy
 	    assigned to them.  The <filename>krb5.dict</filename> files
 	    format is simple: one string per line.  Creating a symbolic
 	    link to <filename>/usr/share/dict/words</filename> might be
 	    useful.</para>
 	  </listitem>
         </itemizedlist>
 
       </sect2>
 
       <sect2>
 	<title>Differences with the <acronym>MIT</acronym> port</title>
 
 	<para>The major difference between the <acronym>MIT</acronym>
 	  and Heimdal installs relates to the <command>kadmin</command>
 	  program which has a different (but equivalent) set of commands
 	  and uses a different protocol.  This has a large implications
 	  if your <acronym>KDC</acronym> is <acronym>MIT</acronym> as you
 	  will not be able to use the Heimdal <command>kadmin</command>
 	  program to administer your <acronym>KDC</acronym> remotely
 	  (or vice versa, for that matter).</para>
 
 	<para>The client applications may also take slightly different
 	  command line options to accomplish the same tasks.  Following
 	  the instructions on the <acronym>MIT</acronym>
 	  <application>Kerberos</application> web site
 	  (<ulink url="http://web.mit.edu/Kerberos/www/"></ulink>)
 	  is recommended. Be careful of path issues: the
 	  <acronym>MIT</acronym> port installs into
 	  <filename>/usr/local/</filename> by default, and the
 	  <quote>normal</quote> system applications may be run instead
 	  of <acronym>MIT</acronym> if your <envar>PATH</envar>
 	  environment variable lists the system directories first.</para>
 
 	<note><para>With the <acronym>MIT</acronym>
 	  <filename role="package">security/krb5</filename> port
 	  that is provided by &os;, be sure to read the
 	  <filename>/usr/local/share/doc/krb5/README.FreeBSD</filename>
 	  file installed by the port if you want to understand why logins
 	  via <command>telnetd</command> and <command>klogind</command>
 	  behave somewhat oddly.  Most importantly, correcting the
 	  <quote>incorrect permissions on cache file</quote> behavior
 	  requires that the <command>login.krb5</command> binary be used
 	  for authentication so that it can properly change ownership for
 	  the forwarded credentials.</para></note>
 
       </sect2>
 
       <sect2>
 	<title>Mitigating limitations found in <application>Kerberos</application></title>
 
 	<indexterm>
 	  <primary>Kerberos5</primary>
 	  <secondary>limitations and shortcomings</secondary>
 	</indexterm>
 
 	<sect3>
 	 <title><application>Kerberos</application> is an all-or-nothing approach</title>
 
 	  <para>Every service enabled on the network must be modified to
 	    work with <application>Kerberos</application> (or be otherwise
 	    secured against network attacks) or else the users credentials
 	    could be stolen and re-used.  An example of this would be
 	    <application>Kerberos</application> enabling all remote shells
 	    (via <command>rsh</command> and <command>telnet</command>, for
 	    example) but not converting the <acronym>POP3</acronym> mail
 	    server which sends passwords in plain text.</para>
 
 	</sect3>
 
 	<sect3>
 	  <title><application>Kerberos</application> is intended for single-user workstations</title>
 
 	  <para>In a multi-user environment,
 	    <application>Kerberos</application> is less secure.
 	    This is because it stores the tickets in the
 	    <filename>/tmp</filename> directory, which is readable by all
 	    users.  If a user is sharing a computer with several other
 	    people simultaneously (i.e. multi-user), it is possible that
 	    the user's tickets can be stolen (copied) by another
 	    user.</para>
 
 	  <para>This can be overcome with the <literal>-c</literal>
 	    filename command-line option or (preferably) the
 	    <envar>KRB5CCNAME</envar> environment variable, but this
 	    is rarely done. In principal, storing the ticket in the users
 	    home directory and using simple file permissions can mitigate
 	    this problem.</para>
 
 	</sect3>
 
 	<sect3>
 	  <title>The KDC is a single point of failure</title>
 
 	  <para>By design, the <acronym>KDC</acronym> must be as secure as
 	    the master password database is contained on it.  The
 	    <acronym>KDC</acronym> should have absolutely no other
 	    services running on it and should be physically secured.  The
 	    danger is high because <application>Kerberos</application>
 	    stores all passwords encrypted with the same key (the
 	    <quote>master</quote> key), which in turn is stored as a file
 	    on the <acronym>KDC</acronym>.</para>
 
 	  <para>As a side note, a compromised master key is not quite as
 	    bad as one might normally fear.  The master key is only used
 	    to encrypt the <application>Kerberos</application> database
 	    and as a seed for the random number generator.  As long as
 	    access to your <acronym>KDC</acronym> is secure, an attacker
 	    cannot do much with the master key.</para>
 
 	  <para>Additionally, if the <acronym>KDC</acronym> is unavailable
 	    (perhaps due to a denial of service attack or network problems)
 	    the network services are unusable as authentication can not be
 	    performed, a recipe for a denial-of-service attack.  This can
 	    alleviated with multiple <acronym>KDC</acronym>s (a single
 	    master and one or more slaves) and with careful implementation
 	    of secondary or fall-back authentication
 	    (<acronym>PAM</acronym> is excellent for this).</para>
 
 	</sect3>
 
 	<sect3>
 	  <title><application>Kerberos</application> Shortcomings</title>
 
 	  <para><application>Kerberos</application> allows users, hosts
 	    and services to authenticate between themselves.  It does not
 	    have a mechanism to authenticate the <acronym>KDC</acronym>
 	    to the users, hosts or services.  This means that a trojanned
 	    <command>kinit</command> (for example) could record all user
 	    names and passwords.  Something like
 	    <filename role="package">security/tripwire</filename> or
 	    other file system integrity checking tools can alleviate
 	    this.</para>
 
 	</sect3>
       </sect2>
 
       <sect2>
 	<title>Resources and further information</title>
 
 	<indexterm>
 	  <primary>Kerberos5</primary>
 	  <secondary>external resources</secondary>
 	</indexterm>
 
 	<itemizedlist>
 	  <listitem>
 	  <para><ulink
 	    url="http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html">
 	    The <application>Kerberos</application> FAQ</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink url="http://web.mit.edu/Kerberos/www/dialogue.html">Designing
 	    an Authentication System: a Dialog in Four Scenes</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">RFC 1510,
 	    The <application>Kerberos</application> Network Authentication Service
 	    (V5)</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink url="http://web.mit.edu/Kerberos/www/"><acronym>MIT</acronym>
 	    <application>Kerberos</application> home page</ulink></para>
 	</listitem>
 
 	<listitem>
 	<para><ulink url="http://www.pdc.kth.se/heimdal/">Heimdal
 	  <application>Kerberos</application> home page</ulink></para>
 	</listitem>
 
 	</itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="openssl">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Rhodes</surname>
 	  <contrib>Written by: </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>OpenSSL</title>
     <indexterm>
       <primary>security</primary>
       <secondary>OpenSSL</secondary>
     </indexterm>
 
     <para>One feature that many users overlook is the
       <application>OpenSSL</application> toolkit included
       in &os;.  <application>OpenSSL</application> provides an
       encryption transport layer on top of the normal communications
       layer; thus allowing it to be intertwined with many network
       applications and services.</para>
 
     <para>Some uses of <application>OpenSSL</application> may include
       encrypted authentication of mail clients, web based transactions
       such as credit card payments and more.  Many ports such as
       <filename role="package">www/apache13-ssl</filename>, and
       <filename role="package">mail/sylpheed-claws</filename>
       will offer compilation support for building with
       <application>OpenSSL</application>.</para>
 
     <note>
       <para>In most cases the ports collection will attempt to build
 	the <filename role="package">security/openssl</filename> port
 	unless the <makevar>WITH_OPENSSL_BASE</makevar> make variable
 	is explicitly set to <quote>yes</quote>.</para>
     </note>
 
     <para>The version of <application>OpenSSL</application> included
       in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3),
       Transport Layer Security v1 (TLSv1) network security protocols
       and can be used as a general cryptographic library.</para>
 
     <note>
       <para>While <application>OpenSSL</application> supports the
 	<acronym>IDEA</acronym> algorithm, it is disabled by default
 	due to United States patents.  To use it, the license should
 	be reviewed and, if the restrictions are acceptable, the
 	<makevar>MAKE_IDEA</makevar> variable must be set in
 	<filename>make.conf</filename>.</para>
     </note>
 
     <para>One of the most common uses of
       <application>OpenSSL</application> is to provide certificates for
       use with software applications.  These certificates ensure
       that the credentials of the company or individual are valid
       and not fraudulent.  If the certificate in question has
       not been verified by one of the several <quote>Certificate Authorities</quote>,
       or <acronym>CA</acronym>s, a warning is usually produced.  A
       Certificate Authority is a company, such as <ulink url="www.verisign.com">VeriSign</ulink>, which will
       sign certificates in order to validate credentials of individuals
       or companies.  This process has a cost associated with it and
       is definitely not a requirement for using certificates; however,
       it can put some of the more paranoid users at ease.</para>
 
     <sect2>
       <title>Generating Certificates</title>
 
       <indexterm>
 	<primary>OpenSSL</primary>
 	<secondary>certificate generation</secondary>
       </indexterm>
 
       <para>To generate a certificate, the following command is
 	available:</para>
 
       <screen>&prompt.root; <userinput>openssl req -new -nodes -out req.pem -keyout cert.pem</userinput>
 Generating a 1024 bit RSA private key
 ................++++++
 .......................................++++++
 writing new private key to 'cert.pem'
 -----
 You are about to be asked to enter information that will be incorporated
 into your certificate request.
 What you are about to enter is what is called a Distinguished Name or a DN.
 There are quite a few fields but you can leave some blank
 For some fields there will be a default value,
 If you enter '.', the field will be left blank.
 -----
 Country Name (2 letter code) [AU]:<userinput><replaceable>US</replaceable></userinput>
 State or Province Name (full name) [Some-State]:<userinput><replaceable>PA</replaceable></userinput>
 Locality Name (eg, city) []:<userinput><replaceable>Pittsburgh</replaceable></userinput>
 Organization Name (eg, company) [Internet Widgits Pty Ltd]:<userinput><replaceable>My Company</replaceable></userinput>
 Organizational Unit Name (eg, section) []:<userinput><replaceable>Systems Administrator</replaceable></userinput>
 Common Name (eg, YOUR name) []:<userinput><replaceable>localhost.example.org</replaceable></userinput>
 Email Address []:<userinput><replaceable>trhodes@FreeBSD.org</replaceable></userinput>
 
 Please enter the following 'extra' attributes
 to be sent with your certificate request
 A challenge password []:<userinput><replaceable>SOME PASSWORD</replaceable></userinput>
 An optional company name []:<userinput><replaceable>Another Name</replaceable></userinput></screen>
 
       <para>Notice the response directly after the
 	<quote>Common Name</quote> prompt shows a domain name.
 	This prompt requires a server name to be entered for
 	verification purposes; placing anything	but a domain name
 	would yield a useless certificate.  Other options, for
 	instance expire time, alternate encryption algorithms, etc.
 	are available.  A complete list may be obtained by viewing
 	the &man.openssl.1; manual page.</para>
 
       <para>A <filename>cert.pem</filename> file should now exist in
 	the directory which the aforementioned command was issued.  This
 	is the certificate which may be sent to any
 	<acronym>CA</acronym> for signing.</para>
 
       <para>In cases where a signature from a <acronym>CA</acronym> is
 	not required, a self signed certificate can be created.  First,
 	generate the <acronym>RSA</acronym> key:</para>
 
       <screen>&prompt.root; <userinput>openssl dsaparam -rand -genkey -out
 <filename>myRSA.key</filename> 1024</userinput></screen>
 	
 	<para>Next, generate the <acronym>CA</acronym> key:</para>
 
       <screen>&prompt.root; <userinput>openssl gendsa -des3 -out \
 <filename>myca.key</filename> <filename>myRSA.key</filename></userinput></screen>
 
       <para>Use this key to create the certificate:</para>
 
       <screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key \
 <filename>myca.key</filename> -out <filename>new.crt</filename></userinput></screen>
 
       <para>Two new files should appear in the directory: a certificate
 	authority signature file, <filename>myca.key</filename> and the
 	certificate itself, <filename>new.crt</filename>.  These should
 	be placed in a directory, preferably under
 	<filename class="directory">/etc</filename>, which is readable
 	only by <username>root</username>.  Permissions of 0700 should be fine for this and
 	they can be set with the <command>chmod</command>
 	utility.</para>
     </sect2>
 
     <sect2>
       <title>Using Certificates, an Example</title>
 
       <para>So what can these files do?  A good use would be to
 	encrypt connections to the <application>Sendmail</application>
 	<acronym>MTA</acronym>.  This would dissolve the use of clear
 	text authentication for users who send mail via the local
 	<acronym>MTA</acronym>.</para>
 
       <note>
 	<para>This is not the best use in the world as some
 	  <acronym>MUA</acronym>s will present the user with an
 	  error if they have not installed the certificate locally.
 	  Refer to the documentation included with the software for
 	  more information on certificate installation.</para>
       </note>
 
       <para>The following lines should be placed inside the
 	local <filename>.mc</filename> file:</para>
 
       <programlisting>dnl SSL Options
 define(`confCACERT_PATH',`/etc/certs')dnl
 define(`confCACERT',`/etc/certs/new.crt')dnl
 define(`confSERVER_CERT',`/etc/certs/new.crt')dnl
 define(`confSERVER_KEY',`/etc/certs/myca.key')dnl
 define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting>
 
       <para>Where <filename class="directory">/etc/certs/</filename>
 	is the directory to be used for storing the certificate
 	and key files locally.  The last few requirements are a rebuild
 	of the local <filename>.cf</filename> file.  This is easily
 	achieved by typing <command>make</command>
 	<parameter>install</parameter> within the
 	<filename class="directory">/etc/mail</filename>
 	directory.  Follow that up with <command>make</command>
 	<parameter>restart</parameter> which should start the
 	<application>Sendmail</application> daemon.</para>
 
       <para>If all went well there will be no error messages in the
 	<filename>/var/log/maillog</filename> file and
 	<application>Sendmail</application> will show up in the process
 	list.</para>
 
       <para>For a simple test, simply connect to the mail server
 	using the &man.telnet.1; utility:</para>
 
       <screen>&prompt.root; <userinput>telnet <replaceable>example.com</replaceable> 25</userinput>
 Trying 192.0.34.166...
 Connected to <hostid role="fqdn">example.com</hostid>.
 Escape character is '^]'.
 220 <hostid role="fqdn">example.com</hostid> ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT)
 <userinput>ehlo <replaceable>example.com</replaceable></userinput>
 250-example.com Hello example.com [192.0.34.166], pleased to meet you
 250-ENHANCEDSTATUSCODES
 250-PIPELINING
 250-8BITMIME
 250-SIZE
 250-DSN
 250-ETRN
 250-AUTH LOGIN PLAIN
 250-STARTTLS
 250-DELIVERBY
 250 HELP
 <userinput>quit</userinput>
 221 2.0.0 <hostid role="fqdn">example.com</hostid> closing connection
 Connection closed by foreign host.</screen>
 
       <para>If the <quote>STARTTLS</quote> line appears in the output
 	then everything is working correctly.</para>
     </sect2>
   </sect1>
 
   <sect1 id="ipsec">
     <sect1info>
       <authorgroup>
         <author>
   	  <firstname>Nik</firstname>
 	  <surname>Clayton</surname>
 	  <affiliation>
 	    <address><email>nik@FreeBSD.org</email></address>
           </affiliation>
           <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
 
     <title>VPN over IPsec</title>
     <para>Creating a VPN between two networks, separated by the
       Internet, using FreeBSD gateways.</para>
  
     <sect2>
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Hiten M.</firstname>
             <surname>Pandya</surname>
 	    <affiliation>
 	      <address><email>hmp@FreeBSD.org</email></address>
 	    </affiliation>
 	    <contrib>Written by </contrib>
 	  </author>
 	</authorgroup>
       </sect2info>
 
       <title>Understanding IPsec</title>
 
       <para>This section will guide you through the process of setting
 	up IPsec, and to use it in an environment which consists of
 	FreeBSD and <application>&microsoft.windows; 2000/XP</application>
 	machines, to make them communicate securely.  In order to set up
 	IPsec, it is necessary that you are familiar with the concepts
 	of building a custom kernel (see
 	<xref linkend="kernelconfig">).</para>
     
       <para><emphasis>IPsec</emphasis> is a protocol which sits on top
 	of the Internet Protocol (IP) layer.  It allows two or more
 	hosts to communicate in a secure manner (hence the name).  The
 	FreeBSD IPsec <quote>network stack</quote> is based on the
 	<ulink url="http://www.kame.net/">KAME</ulink> implementation,
 	which has support for both protocol families, IPv4 and
 	IPv6.</para>
 
       <note>
         <para>FreeBSD 5.X contains a <quote>hardware
         accelerated</quote> IPsec stack, known as <quote>Fast
         IPsec</quote>, that was obtained from OpenBSD.  It employs
         cryptographic hardware (whenever possible) via the
         &man.crypto.4; subsystem to optimize the performance of IPsec.
         This subsystem is new, and does not support all the features
         that are available in the KAME version of IPsec.  However, in
         order to enable hardware-accelerated IPsec, the following
         kernel option has to be added to your kernel configuration
         file:</para>
 
         <screen>
 options	  FAST_IPSEC  # new IPsec (cannot define w/ IPSEC)
         </screen>
 
         <para> Note, that it is not currently possible to use the
 	  <quote>Fast IPsec</quote> subsystem in lue with the KAME
 	  implementation of IPsec.  Consult the &man.fast.ipsec.4;
 	  manual page for more information.</para>
 
       </note>
   
       <para>IPsec consists of two sub-protocols:</para>
 
       <itemizedlist>
         <listitem>
           <para><emphasis>Encapsulated Security Payload
 	      (ESP)</emphasis>, protects the IP packet data from third
 	    party interference, by encrypting the contents using
 	    symmetric cryptography algorithms (like Blowfish,
 	    3DES).</para>
         </listitem>
         <listitem>
           <para><emphasis>Authentication Header (AH)</emphasis>,
 	    protects the IP packet header from third party interference
 	    and spoofing, by computing a cryptographic checksum and
 	    hashing the IP packet header fields with a secure hashing
 	    function.  This is then followed by an additional header
 	    that contains the hash, to allow the information in the
 	    packet to be authenticated.</para>
         </listitem>
       </itemizedlist>
       
       <para><acronym>ESP</acronym> and <acronym>AH</acronym> can
 	either be used together or separately, depending on the
 	environment.</para>
       
       <para>IPsec can either be used to directly encrypt the traffic
 	between two hosts (known as <emphasis>Transport
 	  Mode</emphasis>); or to build <quote>virtual tunnels</quote>
 	between two subnets, which could be used for secure
 	communication between two corporate networks (known as
 	<emphasis>Tunnel Mode</emphasis>).  The latter is more commonly
 	known as a <emphasis>Virtual Private Network (VPN)</emphasis>.
 	The &man.ipsec.4; manual page should be consulted for detailed
 	information on the IPsec subsystem in FreeBSD.</para>
       
       <para>To add IPsec support to your kernel, add the following
 	options to your kernel configuration file:</para>
       
       <screen>
 options   IPSEC        #IP security
 options   IPSEC_ESP    #IP security (crypto; define w/ IPSEC)
       </screen>
 
       <para>If IPsec debugging support is desired, the following
 	kernel option should also be added:</para>
 
       <screen>
 options   IPSEC_DEBUG  #debug for IP security
       </screen>
     </sect2>
 
     <sect2>
       <title>The Problem</title>
  
       <para>There is no standard for what constitutes a VPN.  VPNs can
 	be implemented using a number of different technologies, each of
 	which have their own strengths and weaknesses.  This section
 	presents a scenario, and the strategies used for implementing a
 	VPN for this scenario.</para>
     </sect2>
     
     <sect2> 
       <title>The Scenario: Two networks, connected to the Internet, to
         behave as one</title>
       
       <para>The premise is as follows:</para>
       
       <itemizedlist>
         <listitem>
           <para>You have at least two sites</para>
         </listitem>
         <listitem>
           <para>Both sites are using IP internally</para>
         </listitem>
         <listitem>
           <para>Both sites are connected to the Internet, through a
             gateway that is running FreeBSD.</para>
         </listitem>
         <listitem>
           <para>The gateway on each network has at least one public IP
             address.</para>
         </listitem>
         <listitem>
           <para>The internal addresses of the two networks can be
             public or private IP addresses, it doesn't matter.  You can
             be running NAT on the gateway machine if necessary.</para>
         </listitem>
         <listitem>
           <para>The internal IP addresses of the two networks
             <emphasis>do not collide</emphasis>.  While I expect it is
             theoretically possible to use a combination of VPN
             technology and NAT to get this to work, I expect it to be a
             configuration nightmare.</para>
         </listitem>
       </itemizedlist>
       
       <para>If you find that you are trying to connect two networks,
         both of which, internally, use the same private IP address range
         (e.g. both of them use <hostid
         role="ipaddr">192.168.1.x</hostid>), then one of the networks will
         have to be renumbered.</para>
  
       <para>The network topology might look something like this:</para>
  
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="security/ipsec-network" align="center">
 	</imageobject>
 
 	<textobject>
 <literallayout class="monospaced">Network #1            [ Internal Hosts ]    Private Net, 192.168.1.2-254
                       [   Win9x/NT/2K  ]
                       [      UNIX      ]
                                |
                                |
                         .---[fxp1]---.      Private IP, 192.168.1.1
                         |   FreeBSD  |
                         `---[fxp0]---'      Public IP, A.B.C.D
                                |
                                |
                       -=-=- Internet -=-=-
                                |
                                |
                         .---[fxp0]---.      Public IP, W.X.Y.Z
                         |   FreeBSD  |
                         `---[fxp1]---'      Private IP, 192.168.2.1
                                |
                                |
 Network #2            [ Internal Hosts ]
                       [   Win9x/NT/2K  ]    Private Net, 192.168.2.2-254
                       [      UNIX      ]</literallayout>
 	</textobject>
       </mediaobject>
  
       <para>Notice the two public IP addresses.  I'll use the letters to
         refer to them in the rest of this article.  Anywhere you see those
         letters in this article, replace them with your own public IP
         addresses.  Note also that internally, the two gateway
         machines have .1 IP addresses, and that the two networks have
         different private IP addresses (<hostid
         role="ipaddr">192.168.1.x</hostid> and <hostid
         role="ipaddr">192.168.2.x</hostid> respectively).  All the
         machines on the private networks have been configured to use the
         <hostid role="ipaddr">.1</hostid> machine as their default
         gateway.</para>
  
       <para>The intention is that, from a network point of view, each
         network should view the machines on the other network as though
         they were directly attached the same router -- albeit a slightly
         slow router with an occasional tendency to drop packets.</para>
  
       <para>This means that (for example), machine <hostid
         role="ipaddr">192.168.1.20</hostid> should be able to run</para>
  
       <programlisting>ping 192.168.2.34</programlisting>
  
       <para>and have it work, transparently.  &windows; machines should
         be able to see the machines on the other network, browse file
         shares, and so on, in exactly the same way that they can browse
         machines on the local network.</para>
  
       <para>And the whole thing has to be secure.  This means that
         traffic between the two networks has to be encrypted.</para>
  
       <para>Creating a VPN between these two networks is a multi-step
         process.  The stages are as follows:</para>
  
       <orderedlist>
         <listitem>
           <para>Create a <quote>virtual</quote> network link between the two
             networks, across the Internet.  Test it, using tools like
             &man.ping.8;, to make sure it works.</para>
         </listitem>
  
         <listitem>
           <para>Apply security policies to ensure that traffic between
             the two networks is transparently encrypted and decrypted as
             necessary.  Test this, using tools like &man.tcpdump.1;, to
             ensure that traffic is encrypted.</para>
         </listitem>
 
         <listitem>
           <para>Configure additional software on the FreeBSD gateways,
             to allow &windows; machines to see one another across the
             VPN.</para>
         </listitem>
       </orderedlist>
 
     <sect3>
       <title>Step 1: Creating and testing a <quote>virtual</quote>
         network link</title>
  
       <para>Suppose that you were logged in to the gateway machine on
         network #1 (with public IP address <hostid
         role="ipaddr">A.B.C.D</hostid>, private IP address <hostid
         role="ipaddr">192.168.1.1</hostid>), and you ran <command>ping
         192.168.2.1</command>, which is the private address of the machine
         with IP address <hostid role="ipaddr">W.X.Y.Z</hostid>.  What
         needs to happen in order for this to work?</para>
 
       <orderedlist>
         <listitem>
           <para>The gateway machine needs to know how to reach <hostid
             role="ipaddr">192.168.2.1</hostid>.  In other words, it needs
             to have a route to <hostid
             role="ipaddr">192.168.2.1</hostid>.</para>
         </listitem>
         <listitem>
           <para>Private IP addresses, such as those in the <hostid
             role="ipaddr">192.168.x</hostid> range are not supposed to
             appear on the Internet at large.  Instead, each packet you
             send to <hostid role="ipaddr">192.168.2.1</hostid> will need
             to be wrapped up inside another packet.  This packet will need
             to appear to be from <hostid role="ipaddr">A.B.C.D</hostid>,
             and it will have to be sent to <hostid
             role="ipaddr">W.X.Y.Z</hostid>.  This process is called
             <firstterm>encapsulation</firstterm>.</para>
         </listitem>
         <listitem>
           <para>Once this packet arrives at <hostid
             role="ipaddr">W.X.Y.Z</hostid> it will need to
             <quote>unencapsulated</quote>, and delivered to <hostid
             role="ipaddr">192.168.2.1</hostid>.</para>
 	</listitem>
       </orderedlist>
  
       <para>You can think of this as requiring a <quote>tunnel</quote>
         between the two networks.  The two <quote>tunnel mouths</quote> are the IP
         addresses <hostid role="ipaddr">A.B.C.D</hostid> and <hostid
         role="ipaddr">W.X.Y.Z</hostid>, and the tunnel must be told the
         addresses of the private IP addresses that will be allowed to pass
         through it.  The tunnel is used to transfer traffic with private
         IP addresses across the public Internet.</para>
  
       <para>This tunnel is created by using the generic interface, or
         <devicename>gif</devicename> devices on FreeBSD.  As you can
         imagine, the <devicename>gif</devicename> interface on each
         gateway host must be configured with four IP addresses; two for
         the public IP addresses, and two for the private IP
         addresses.</para>
  
       <para>Support for the gif device must be compiled in to the
         &os; kernel on both machines.  You can do this by adding the
         line:</para>
  
       <programlisting>pseudo-device gif</programlisting>
  
       <para>to the kernel configuration files on both machines, and
         then compile, install, and reboot as normal.</para>
  
       <para>Configuring the tunnel is a two step process.  First the
         tunnel must be told what the outside (or public) IP addresses
         are, using &man.gifconfig.8;.  Then the private IP addresses must be
         configured using &man.ifconfig.8;.</para>
 
       <note>
 	<para>In &os;&nbsp;5.X, the functionality provided by the
 	  &man.gifconfig.8; utility has been merged into 
 	  &man.ifconfig.8;.</para></note>
  
       <para>On the gateway machine on network #1 you would run the
         following two commands to configure the tunnel.</para>
  
       <programlisting>gifconfig gif0 A.B.C.D W.X.Y.Z
 ifconfig gif0 inet 192.168.1.1 192.168.2.1 netmask 0xffffffff
       </programlisting>
  
       <para>On the other gateway machine you run the same commands,
         but with the order of the IP addresses reversed.</para>
  
       <programlisting>gifconfig gif0 W.X.Y.Z A.B.C.D
 ifconfig gif0 inet 192.168.2.1 192.168.1.1 netmask 0xffffffff
       </programlisting>
  
       <para>You can then run:</para>
  
       <programlisting>gifconfig gif0</programlisting>
  
       <para>to see the configuration.  For example, on the network #1
         gateway, you would see this:</para>
  
       <screen>&prompt.root; <userinput>gifconfig gif0</userinput>
 gif0: flags=8011&lt;UP,POINTTOPOINT,MULTICAST&gt; mtu 1280
 inet 192.168.1.1 --&gt; 192.168.2.1 netmask 0xffffffff
 physical address inet A.B.C.D --&gt; W.X.Y.Z
       </screen>
  
       <para>As you can see, a tunnel has been created between the
         physical addresses <hostid role="ipaddr">A.B.C.D</hostid> and
         <hostid role="ipaddr">W.X.Y.Z</hostid>, and the traffic allowed
         through the tunnel is that between <hostid
         role="ipaddr">192.168.1.1</hostid> and <hostid
         role="ipaddr">192.168.2.1</hostid>.</para>
  
       <para>This will also have added an entry to the routing table
         on both machines, which you can examine with the command <command>netstat -rn</command>.
         This output is from the gateway host on network #1.</para>
  
       <screen>&prompt.root; <userinput>netstat -rn</userinput>
 Routing tables
  
 Internet:
 Destination      Gateway       Flags    Refs    Use    Netif  Expire
 ...
 192.168.2.1      192.168.1.1   UH        0        0    gif0
 ...
       </screen>
  
       <para>As the <quote>Flags</quote> value indicates, this is a
         host route, which means that each gateway knows how to reach the
         other gateway, but they do not know how to reach the rest of
         their respective networks.  That problem will be fixed
         shortly.</para>
  
       <para>It is likely that you are running a firewall on both
         machines.  This will need to be circumvented for your VPN
         traffic.  You might want to allow all traffic between both
         networks, or you might want to include firewall rules that
         protect both ends of the VPN from one another.</para>
  
       <para>It greatly simplifies testing if you configure the
         firewall to allow all traffic through the VPN.  You can always
         tighten things up later.  If you are using &man.ipfw.8; on the
         gateway machines then a command like</para>
 
       <programlisting>ipfw add 1 allow ip from any to any via gif0</programlisting>
  
       <para>will allow all traffic between the two end points of the
         VPN, without affecting your other firewall rules.  Obviously
         you will need to run this command on both gateway hosts.</para>
  
       <para>This is sufficient to allow each gateway machine to ping
         the other.  On <hostid role="ipaddr">192.168.1.1</hostid>, you
         should be able to run</para>
  
       <programlisting>ping 192.168.2.1</programlisting>
  
       <para>and get a response, and you should be able to do the same
         thing on the other gateway machine.</para>
  
       <para>However, you will not be able to reach internal machines
         on either network yet.  This is because of the routing --
         although the gateway machines know how to reach one another,
         they do not know how to reach the network behind each one.</para>
  
       <para>To solve this problem you must add a static route on each
         gateway machine.  The command to do this on the first gateway
         would be:</para>
  
       <programlisting>route add 192.168.2.0 192.168.2.1 netmask 0xffffff00
       </programlisting>
  
       <para>This says <quote>In order to reach the hosts on the
         network <hostid role="ipaddr">192.168.2.0</hostid>, send the
         packets to the host <hostid
         role="ipaddr">192.168.2.1</hostid></quote>.  You will need to
         run a similar command on the other gateway, but with the
         <hostid role="ipaddr">192.168.1.x</hostid> addresses
         instead.</para>
  
       <para>IP traffic from hosts on one network will now be able to
         reach hosts on the other network.</para>
  
       <para>That has now created two thirds of a VPN between the two
         networks, in as much as it is <quote>virtual</quote> and it is a
         <quote>network</quote>.  It is not private yet.  You can test
         this using &man.ping.8; and &man.tcpdump.1;.  Log in to the
         gateway host and run</para>
  
       <programlisting>tcpdump dst host 192.168.2.1</programlisting>
 
       <para>In another log in session on the same host run</para>
 
       <programlisting>ping 192.168.2.1</programlisting>
  
       <para>You will see output that looks something like this:</para>
  
       <programlisting>
 16:10:24.018080 192.168.1.1 &gt; 192.168.2.1: icmp: echo request
 16:10:24.018109 192.168.1.1 &gt; 192.168.2.1: icmp: echo reply
 16:10:25.018814 192.168.1.1 &gt; 192.168.2.1: icmp: echo request
 16:10:25.018847 192.168.1.1 &gt; 192.168.2.1: icmp: echo reply
 16:10:26.028896 192.168.1.1 &gt; 192.168.2.1: icmp: echo request
 16:10:26.029112 192.168.1.1 &gt; 192.168.2.1: icmp: echo reply
       </programlisting>
  
       <para>As you can see, the ICMP messages are going back and forth
         unencrypted.  If you had used the <option>-s</option> parameter to
         &man.tcpdump.1; to grab more bytes of data from the packets you
         would see more information.</para>
  
       <para>Obviously this is unacceptable.  The next section will
         discuss securing the link between the two networks so that it
         all traffic is automatically encrypted.</para>
  
       <itemizedlist>
         <title>Summary:</title>
         <listitem>
           <para>Configure both kernels with <quote>pseudo-device
           gif</quote>.</para>
         </listitem>
         <listitem>
           <para>Edit <filename>/etc/rc.conf</filename> on gateway host
             #1 and add the following lines (replacing IP addresses as
             necessary).</para>
           <programlisting>gifconfig_gif0="A.B.C.D W.X.Y.Z"
 ifconfig_gif0="inet 192.168.1.1 192.168.2.1 netmask 0xffffffff"
 static_routes="vpn"
 route_vpn="192.168.2.0 192.168.2.1 netmask 0xffffff00"
           </programlisting>
         </listitem>
 
         <listitem>
           <para>Edit your firewall script
           (<filename>/etc/rc.firewall</filename>, or similar) on both
           hosts, and add</para>
 
           <programlisting>ipfw add 1 allow ip from any to any via gif0</programlisting>
         </listitem>
         <listitem>
           <para>Make similar changes to
             <filename>/etc/rc.conf</filename> on gateway host #2,
             reversing the order of IP addresses.</para>
         </listitem>
       </itemizedlist>
     </sect3>
 
     <sect3>
       <title>Step 2: Securing the link</title>
  
       <para>To secure the link we will be using IPsec.  IPsec provides
         a mechanism for two hosts to agree on an encryption key, and to
         then use this key in order to encrypt data between the two
         hosts.</para>
  
       <para>The are two areas of configuration to be considered here.</para>
  
       <orderedlist>
         <listitem>
           <para>There must be a mechanism for two hosts to agree on the
             encryption mechanism to use.  Once two hosts have agreed on
             this mechanism there is said to be a <quote>security association</quote>
             between them.</para>
         </listitem>
         <listitem>
           <para>There must be a mechanism for specifying which traffic
             should be encrypted.  Obviously, you don't want to encrypt
             all your outgoing traffic -- you only want to encrypt the
             traffic that is part of the VPN.  The rules that you put in
             place to determine what traffic will be encrypted are called
             <quote>security policies</quote>.</para>
          </listitem>
        </orderedlist>
  
        <para>Security associations and security policies are both
          maintained by the kernel, and can be modified by userland
          programs.  However, before you can do this you must configure the
          kernel to support IPsec and the Encapsulated Security Payload
          (ESP) protocol.  This is done by configuring a kernel with:</para>
  
        <programlisting>options IPSEC
 options IPSEC_ESP
        </programlisting>
  
        <para>and recompiling, reinstalling, and rebooting.  As before
          you will need to do this to the kernels on both of the gateway
          hosts.</para>
  
        <para>You have two choices when it comes to setting up security
          associations.  You can configure them by hand between two hosts,
          which entails choosing the encryption algorithm, encryption keys,
          and so forth, or you can use daemons that implement the Internet
          Key Exchange protocol (IKE) to do this for you.</para>
  
        <para>I recommend the latter.  Apart from anything else, it is
          easier to set up.</para>
  
        <para>Editing and displaying security policies is carried out
          using &man.setkey.8;.  By analogy, <command>setkey</command> is
          to the kernel's security policy tables as &man.route.8; is to
          the kernel's routing tables.  <command>setkey</command> can
          also display the current security associations, and to continue
          the analogy further, is akin to <command>netstat -r</command>
          in that respect.</para>
  
        <para>There are a number of choices for daemons to manage
          security associations with FreeBSD.  This article will describe
          how to use one of these, racoon.  racoon is in the FreeBSD ports
          collection, in the security/ category, and is installed in the
          usual way.</para>
  
        <para>racoon must be run on both gateway hosts.  On each host it
          is configured with the IP address of the other end of the VPN,
          and a secret key (which you choose, and must be the same on both
          gateways).</para>
  
        <para>The two daemons then contact one another, confirm that they
          are who they say they are (by using the secret key that you
          configured).  The daemons then generate a new secret key, and use
          this to encrypt the traffic over the VPN.  They periodically
          change this secret, so that even if an attacker were to crack one
          of the keys (which is as theoretically close to unfeasible as it
          gets) it won't do them much good -- by the time they've cracked
          the key the two daemons have chosen another one.</para>
  
        <para>racoon's configuration is stored in
          <filename>${PREFIX}/etc/racoon</filename>.  You should find a
          configuration file there, which should not need to be changed
          too much.  The other component of racoon's configuration,
          which you will need to change, is the <quote>pre-shared
          key</quote>.</para>
  
        <para>The default racoon configuration expects to find this in
          the file <filename>${PREFIX}/etc/racoon/psk.txt</filename>.  It is important to note
          that the pre-shared key is <emphasis>not</emphasis> the key that will be used to
          encrypt your traffic across the VPN link, it is simply a token
          that allows the key management daemons to trust one another.</para>
 
        <para><filename>psk.txt</filename> contains a line for each
          remote site you are dealing with.  In this example, where there
          are two sites, each <filename>psk.txt</filename> file will contain one line (because
          each end of the VPN is only dealing with one other end).</para>
  
        <para>On gateway host #1 this line should look like this:</para>
  
        <programlisting>W.X.Y.Z            secret</programlisting>
  
        <para>That is, the <emphasis>public</emphasis> IP address of the remote end,
          whitespace, and a text string that provides the secret.
          Obviously, you shouldn't use <quote>secret</quote> as your key -- the normal
          rules for choosing a password apply.</para>
  
        <para>On gateway host #2 the line would look like this</para>
  
        <programlisting>A.B.C.D            secret</programlisting>
  
        <para>That is, the public IP address of the remote end, and the
          same secret key.  <filename>psk.txt</filename> must be mode
          <literal>0600</literal> (i.e., only read/write to
          <username>root</username>) before racoon will run.</para>
  
        <para>You must run racoon on both gateway machines.  You will
          also need to add some firewall rules to allow the IKE traffic,
          which is carried over UDP to the ISAKMP (Internet Security Association
          Key Management Protocol) port.  Again, this should be fairly early in
          your firewall ruleset.</para>
  
        <programlisting>ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
        </programlisting>
  
        <para>Once racoon is running you can try pinging one gateway host
          from the other.  The connection is still not encrypted, but
          racoon will then set up the security associations between the two
          hosts -- this might take a moment, and you may see this as a
          short delay before the ping commands start responding.</para>
  
        <para>Once the security association has been set up you can
          view it using &man.setkey.8;.  Run</para>
  
        <programlisting>setkey -D</programlisting>
  
        <para>on either host to view the security association information.</para>
  
        <para>That's one half of the problem.  They other half is setting
          your security policies.</para>
  
        <para>To create a sensible security policy, let's review what's
          been set up so far.  This discussions hold for both ends of the
          link.</para>
  
        <para>Each IP packet that you send out has a header that contains
          data about the packet.  The header includes the IP addresses of
          both the source and destination.  As we already know, private IP
          addresses, such as the <hostid role="ipaddr">192.168.x.y</hostid>
          range are not supposed to appear on the public Internet.
          Instead, they must first be encapsulated inside another packet.
          This packet must have the public source and destination IP
          addresses substituted for the private addresses.</para>
  
        <para>So if your outgoing packet started looking like this:</para>
  
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="security/ipsec-out-pkt" align="center">
 	  </imageobject>
 
 	  <textobject>
 	    <literallayout class="monospaced">
   .----------------------.
   | Src: 192.168.1.1     |
   | Dst: 192.168.2.1     |
   | &lt;other header info&gt;  |
   +----------------------+
   | &lt;packet data&gt;        |
   `----------------------'</literallayout>
 	  </textobject>
 	</mediaobject>
  
        <para>Then it will be encapsulated inside another packet, looking
          something like this:</para>
  
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="security/ipsec-encap-pkt" align="center">
 	  </imageobject>
 
 	  <textobject>
 	    <literallayout class="monospaced">
   .--------------------------.
   | Src: A.B.C.D             |
   | Dst: W.X.Y.Z             |
   | &lt;other header info&gt;      |
   +--------------------------+
   | .----------------------. |
   | | Src: 192.168.1.1     | |
   | | Dst: 192.168.2.1     | |
   | | &lt;other header info&gt;  | |
   | +----------------------+ |
   | | &lt;packet data&gt;        | |
   | `----------------------' |
   `--------------------------'</literallayout>
 	  </textobject>
 	</mediaobject>
  
        <para>This encapsulation is carried out by the
          <devicename>gif</devicename> device.  As
          you can see, the packet now has real IP addresses on the outside,
          and our original packet has been wrapped up as data inside the
          packet that will be put out on the Internet.</para>
  
        <para>Obviously, we want all traffic between the VPNs to be
          encrypted.  You might try putting this in to words, as:</para>
 
        <para><quote>If a packet leaves from <hostid
          role="ipaddr">A.B.C.D</hostid>, and it is destined for <hostid
          role="ipaddr">W.X.Y.Z</hostid>, then encrypt it, using the
          necessary security associations.</quote></para>
  
        <para><quote>If a packet arrives from <hostid
          role="ipaddr">W.X.Y.Z</hostid>, and it is destined for <hostid
          role="ipaddr">A.B.C.D</hostid>, then decrypt it, using the
          necessary security associations.</quote></para>
  
        <para>That's close, but not quite right.  If you did this, all
          traffic to and from <hostid role="ipaddr">W.X.Y.Z</hostid>, even
          traffic that was not part of the VPN, would be encrypted.  That's
          not quite what you want.  The correct policy is as follows</para>
  
        <para><quote>If a packet leaves from <hostid
          role="ipaddr">A.B.C.D</hostid>, and that packet is encapsulating
          another packet, and it is destined for <hostid
          role="ipaddr">W.X.Y.Z</hostid>, then encrypt it, using the
          necessary security associations.</quote></para>
  
        <para><quote>If a packet arrives from <hostid
          role="ipaddr">W.X.Y.Z</hostid>, and that packet is encapsulating
          another packet, and it is destined for <hostid
          role="ipaddr">A.B.C.D</hostid>, then decrypt it, using the
          necessary security associations.</quote></para>
  
        <para>A subtle change, but a necessary one.</para>
  
        <para>Security policies are also set using &man.setkey.8;.
          &man.setkey.8; features a configuration language for defining the
          policy.  You can either enter configuration instructions via
          stdin, or you can use the <option>-f</option> option to specify a
          filename that contains configuration instructions.</para>
  
        <para>The configuration on gateway host #1 (which has the public
          IP address <hostid role="ipaddr">A.B.C.D</hostid>) to force all
          outbound traffic to <hostid role="ipaddr">W.X.Y.Z</hostid> to be
          encrypted is:</para>
  
        <programlisting>
 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;
        </programlisting>
  
        <para>Put these commands in a file (e.g.
        <filename>/etc/ipsec.conf</filename>) and then run</para>
 
        <screen>&prompt.root; <userinput>setkey -f /etc/ipsec.conf</userinput></screen>
  
        <para><option>spdadd</option> tells &man.setkey.8; that we want
          to add a rule to the secure policy database.  The rest of this
          line specifies which packets will match this policy.  <hostid
          role="ipaddr">A.B.C.D/32</hostid> and <hostid
          role="ipaddr">W.X.Y.Z/32</hostid> are the IP addresses and
          netmasks that identify the network or hosts that this policy will
          apply to.  In this case, we want it to apply to traffic between
          these two hosts.  <option>ipencap</option> tells the kernel that
          this policy should only apply to packets that encapsulate other
          packets.  <option>-P out</option> says that this policy applies
          to outgoing packets, and <option>ipsec</option> says that the
          packet will be secured.</para>
  
        <para>The second line specifies how this packet will be
          encrypted.  <option>esp</option> is the protocol that will be
          used, while <option>tunnel</option> indicates that the packet
          will be further encapsulated in an IPsec packet.  The repeated
          use of <hostid role="ipaddr">A.B.C.D</hostid> and <hostid
          role="ipaddr">W.X.Y.Z</hostid> is used to select the security
          association to use, and the final <option>require</option>
          mandates that packets must be encrypted if they match this
          rule.</para>
  
        <para>This rule only matches outgoing packets.  You will need a
          similar rule to match incoming packets.</para>
  
        <programlisting>spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;</programlisting>
  
        <para>Note the <option>in</option> instead of
          <option>out</option> in this case, and the necessary reversal of
          the IP addresses.</para>
  
        <para>The other gateway host (which has the public IP address
          <hostid role="ipaddr">W.X.Y.Z</hostid>) will need similar rules.</para>
  
        <programlisting>spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;</programlisting>
  
        <para>Finally, you need to add firewall rules to allow ESP and
         IPENCAP packets back and forth.  These rules will need to be
         added to both hosts.</para>
  
        <programlisting>ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
        </programlisting>
  
        <para>Because the rules are symmetric you can use the same rules
          on each gateway host.</para>
  
        <para>Outgoing packets will now look something like this:</para>
  
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="security/ipsec-crypt-pkt" align="center">
 	  </imageobject>
 
 	  <textobject>
 	    <literallayout class="monospaced">
   .------------------------------.  --------------------------.
   | Src: A.B.C.D                 |                            |
   | Dst: W.X.Y.Z                 |                            |
   | &lt;other header info&gt;          |                            |  Encrypted
   +------------------------------+                            |  packet.
   | .--------------------------. |  -------------.            |  contents
   | | Src: A.B.C.D             | |               |            |  are
   | | Dst: W.X.Y.Z             | |               |            |  completely
   | | &lt;other header info&gt;      | |               |            |- secure
   | +--------------------------+ |               |  Encap'd   |  from third
   | | .----------------------. | |  -.           |  packet    |  party
   | | | Src: 192.168.1.1     | | |   |  Original |- with real |  snooping
   | | | Dst: 192.168.2.1     | | |   |  packet,  |  IP addr   |
   | | | &lt;other header info&gt;  | | |   |- private  |            |
   | | +----------------------+ | |   |  IP addr  |            |
   | | | &lt;packet data&gt;        | | |   |           |            |
   | | `----------------------' | |  -'           |            |
   | `--------------------------' |  -------------'            |
   `------------------------------'  --------------------------'
 	    </literallayout>
 	  </textobject>
 	</mediaobject>
 
        <para>When they are received by the far end of the VPN they will
          first be decrypted (using the security associations that have
          been negotiated by racoon).  Then they will enter the
          <devicename>gif</devicename> interface, which will unwrap
          the second layer, until you are left with the innermost
          packet, which can then travel in to the inner network.</para>
  
        <para>You can check the security using the same &man.ping.8; test from
          earlier.  First, log in to the
          <hostid role="ipaddr">A.B.C.D</hostid> gateway machine, and
          run:</para>
  
        <programlisting>tcpdump dst host 192.168.2.1</programlisting>
  
        <para>In another log in session on the same host run</para>
  
        <programlisting>ping 192.168.2.1</programlisting>
  
        <para>This time you should see output like the following:</para>
  
        <programlisting>XXX tcpdump output</programlisting>
  
        <para>Now, as you can see, &man.tcpdump.1; shows the ESP packets.  If
          you try to examine them with the <option>-s</option> option you will see
          (apparently) gibberish, because of the encryption.</para>
  
       <para>Congratulations.  You have just set up a VPN between two
         remote sites.</para>
  
       <itemizedlist>
         <title>Summary</title>
         <listitem>
           <para>Configure both kernels with:</para>
  
           <programlisting>options IPSEC
 options IPSEC_ESP
           </programlisting>
         </listitem>
         <listitem>
           <para>Install <filename
             role="package">security/racoon</filename>.  Edit
             <filename>${PREFIX}/etc/racoon/psk.txt</filename> on both
             gateway hosts, adding an entry for the remote host's IP
             address and a secret key that they both know.  Make sure
             this file is mode 0600.</para>
         </listitem>
         <listitem>
           <para>Add the following lines to
             <filename>/etc/rc.conf</filename> on each host:</para>
  
           <programlisting>ipsec_enable="YES"
 ipsec_file="/etc/ipsec.conf"
           </programlisting>
         </listitem>
         <listitem>
           <para>Create an <filename>/etc/ipsec.conf</filename> on each
             host that contains the necessary spdadd lines.  On gateway
             host #1 this would be:</para>
  
           <programlisting>
 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec
   esp/tunnel/A.B.C.D-W.X.Y.Z/require;
 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec
   esp/tunnel/W.X.Y.Z-A.B.C.D/require;
 </programlisting>
  
           <para>On gateway host #2 this would be:</para>
  
 <programlisting>
 spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec
   esp/tunnel/W.X.Y.Z-A.B.C.D/require;
 spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec
   esp/tunnel/A.B.C.D-W.X.Y.Z/require;
 </programlisting>
         </listitem>
         <listitem>
           <para>Add firewall rules to allow IKE, ESP, and IPENCAP
             traffic to both hosts:</para>
  
           <programlisting>
 ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
 ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
 ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
 ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
 ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
 ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
           </programlisting>
         </listitem>
       </itemizedlist>
 
       <para>The previous two steps should suffice to get the VPN up and
         running.  Machines on each network will be able to refer to one
         another using IP addresses, and all traffic across the link will
         be automatically and securely encrypted.</para>
     </sect3> 
     </sect2> 
   </sect1>
 
   <sect1 id="openssh">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Chern</firstname>
 	  <surname>Lee</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<!-- 21 April 2001 -->
       </authorgroup>
     </sect1info>
 
     <title>OpenSSH</title>
     <indexterm><primary>OpenSSH</primary></indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>OpenSSH</secondary>
     </indexterm>
 
     <para><application>OpenSSH</application> is a set of network connectivity tools used to
       access remote machines securely.  It can be used as a direct
       replacement for <command>rlogin</command>,
       <command>rsh</command>, <command>rcp</command>, and
       <command>telnet</command>.  Additionally, any other TCP/IP
       connections can be tunneled/forwarded securely through SSH.
       <application>OpenSSH</application> encrypts all traffic to effectively eliminate eavesdropping,
       connection hijacking, and other network-level attacks.</para>
 
     <para><application>OpenSSH</application> is maintained by the OpenBSD project, and is based
       upon SSH v1.2.12 with all the recent bug fixes and updates.  It
       is compatible with both SSH protocols 1 and 2.  <application>OpenSSH</application> has been
       in the base system since FreeBSD&nbsp;4.0.</para>
 
     <sect2>
       <title>Advantages of Using OpenSSH</title>
   
       <para>Normally, when using &man.telnet.1; or &man.rlogin.1;,
         data is sent over the network in an clear, un-encrypted form.
         Network sniffers anywhere in between the client and server can
         steal your user/password information or data transferred in
         your session.  <application>OpenSSH</application> offers a variety of authentication and
         encryption methods to prevent this from happening.</para>
     </sect2>
 
     <sect2>
       <title>Enabling sshd</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>enabling</secondary>
       </indexterm>
 
       <para>Be sure to make the following addition to your 
         <filename>rc.conf</filename> file:</para>
       <screen>sshd_enable="YES"</screen>
       <para>This will load &man.sshd.8;, the daemon program for <application>OpenSSH</application>,
 	the next time your system initializes.  Alternatively, you can
 	simply run directly the <application>sshd</application> daemon by typing <command>sshd</command> on the command line.</para>
     </sect2>
 
     <sect2>
       <title>SSH Client</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>client</secondary>
       </indexterm>
 
       <para>The &man.ssh.1; utility works similarly to 
         &man.rlogin.1;.</para>
 
       <screen>&prompt.root; <userinput>ssh <replaceable>user@example.com</replaceable></userinput>
 Host key not found from the list of known hosts.
 Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput>
 Host 'example.com' added to the list of known hosts.
 user@example.com's password: <userinput>*******</userinput></screen>
 
       <para>The login will continue just as it would have if a session was
         created using <command>rlogin</command> or
         <command>telnet</command>.  SSH utilizes a key fingerprint
         system for verifying the authenticity of the server when the 
         client connects.  The user is prompted to enter
 	<literal>yes</literal> only when
         connecting for the first time.  Future attempts to login are all
         verified against the saved fingerprint key.  The SSH client
         will alert you if the saved fingerprint differs from the
         received fingerprint on future login attempts.  The fingerprints
         are saved in <filename>~/.ssh/known_hosts</filename>, or
 	<filename>~/.ssh/known_hosts2</filename> for SSH v2
 	fingerprints.</para>
 
       <para>By default, <application>OpenSSH</application> servers are configured to only accept
 	SSH v2 connections.  The client, however, can choose
 	between version 1 and 2.  Version 2 is known to be more robust and
 	secure than its predecessor.</para>
 
       <para>The &man.ssh.1; command can be forced to use either protocol
 	by passing it the <option>-1</option> or <option>-2</option> argument
 	for v1 and v2, respectively.</para>
     </sect2>
     
     <sect2>
       <title>Secure Copy</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>secure copy</secondary>
       </indexterm>
       <indexterm><primary><command>scp</command></primary></indexterm>
 
       <para>The &man.scp.1; command works similarly to
 	&man.rcp.1;; it copies a file to or from a remote machine,
 	except in a secure fashion.</para>
 
       <screen>&prompt.root; <userinput> scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput>
 user@example.com's password: <userinput>*******</userinput>
 COPYRIGHT            100% |*****************************|  4735       
 00:00    
 &prompt.root;</screen>
       <para>Since the fingerprint was already saved for this host in the
         previous example, it is verified when using &man.scp.1;
         here.</para>
 
       <para>The arguments passed to &man.scp.1; are similar
 	to &man.cp.1;, with the file or files in the first
 	argument, and the destination in the second.  Since the file is
 	fetched over the network, through SSH, one or more of the file
 	arguments takes on the form
 	<option>user@host:&lt;path_to_remote_file&gt;</option>.</para>
 
     </sect2>
 
     <sect2>
       <title>Configuration</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>configuration</secondary>
       </indexterm>
 
       <para>The system-wide configuration files for both the
         <application>OpenSSH</application> daemon and client reside
         within the <filename>/etc/ssh</filename> directory.</para>
 
       <para><filename>ssh_config</filename> configures the client 
         settings, while <filename>sshd_config</filename> configures the 
         daemon.</para>
 
       <para>Additionally, the <option>sshd_program</option>
 	(<filename>/usr/sbin/sshd</filename> by default), and
 	<option>sshd_flags</option> <filename>rc.conf</filename>
 	options can provide more levels of configuration.</para>
     </sect2>
 
     <sect2>
       <title>ssh-keygen</title>
 
       <para>Instead of using passwords, &man.ssh-keygen.1; can
         be used to generate RSA keys to authenticate a user:</para>
 
       <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>rsa1</replaceable></userinput>
 Initializing random number generator...
 Generating p:  .++ (distance 66)
 Generating q:  ..............................++ (distance 498)
 Computing the keys...
 Key generation complete.
 Enter file in which to save the key (/home/user/.ssh/identity):
 Enter passphrase:
 Enter the same passphrase again:
 Your identification has been saved in /home/user/.ssh/identity.
 ...</screen>
 
       <para>&man.ssh-keygen.1; will create a public and private
         key pair for use in authentication.  The private key is stored in
         <filename>~/.ssh/identity</filename>, whereas the public key is
         stored in <filename>~/.ssh/identity.pub</filename>.  The public
         key must be placed in <filename>~/.ssh/authorized_keys</filename>
         of the remote machine in order for the setup to work.</para>
 
       <para>This will allow connection to the remote machine based upon
         RSA authentication instead of passwords.</para>
 
       <note><para>The <option>-t rsa1</option> option will create RSA
 	keys for use by SSH protocol version 1.  If you want to use
 	RSA keys with the SSH protocol version 2, you have to use the
 	command <command>ssh-keygen -t rsa</command>.</para></note>
 
       <para>If a passphrase is used in &man.ssh-keygen.1;, the user
         will be prompted for a password each time in order to use the private
         key.</para>
 
       <para>A SSH protocol version 2 DSA key can be created for the same purpose by using
 	the <command>ssh-keygen -t dsa</command> command.
 	This will
 	create a public/private DSA key for use in SSH protocol version 2 sessions only.
 	The public key is stored in <filename>~/.ssh/id_dsa.pub</filename>,
 	while the private key is in <filename>~/.ssh/id_dsa</filename>.</para>
 
       <para>DSA public keys are also placed in
 	<filename>~/.ssh/authorized_keys</filename> on the remote
 	machine.</para>
 
       <para>&man.ssh-agent.1; and &man.ssh-add.1; are 
         utilities used in managing multiple passworded private keys.</para>
 
       <warning><para>The various options and files can be different
 	according to the <application>OpenSSH</application> version you have on your system, to
 	avoid problems you should consult the &man.ssh-keygen.1;
 	manual page.</para></warning>
     </sect2>
 
     <sect2 id="security-ssh-tunneling">
       <title>SSH Tunneling</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>tunneling</secondary>
       </indexterm>
 
       <para><application>OpenSSH</application> has the ability to create a tunnel to encapsulate
         another protocol in an encrypted session.</para>
 
       <para>The following command tells &man.ssh.1; to create a tunnel 
          for <application>telnet</application>:</para>
 
        <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5023:localhost:23 user@foo.example.com</replaceable></userinput>
 &prompt.user;</screen>
 
       <para>The <command>ssh</command> command is used with the
 	following options:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term><option>-2</option></term>
 	  
 	  <listitem>
 	    <para>Forces <command>ssh</command> to use version 2 of
 	      the protocol. (Do not use if you are working with older
 	      SSH servers)</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-N</option></term>
 
 	  <listitem>
 	    <para>Indicates no command, or tunnel only.  If omitted,
 	      <command>ssh</command> would initiate a normal
 	      session.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-f</option></term>
 
 	  <listitem>
 	    <para>Forces <command>ssh</command> to run in the
 	      background.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-L</option></term>
 
 	  <listitem>
 	    <para>Indicates a local tunnel in
 	      <replaceable>localport:remotehost:remoteport</replaceable>
 	      fashion.</para>
 	  </listitem>
 	  </varlistentry>
 
 	<varlistentry>
 	  <term><option>user@foo.example.com</option></term>
 
 	  <listitem>
 	    <para>The remote SSH server.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
 
       <para>An SSH tunnel works by creating a listen socket on
 	<hostid>localhost</hostid> on the specified port.
 	It then forwards any connection received
 	on the local host/port via the SSH connection to the specified
 	remote host and port.</para>
 
       <para>In the example, port <replaceable>5023</replaceable> on
 	<hostid>localhost</hostid> is being forwarded to port
 	<replaceable>23</replaceable> on <hostid>localhost</hostid>
 	of the remote machine.  Since <replaceable>23</replaceable> is <application>telnet</application>,
 	this would create a secure <application>telnet</application> session through an SSH tunnel.</para>
 
       <para>This can be used to wrap any number of insecure TCP
         protocols such as SMTP, POP3, FTP, etc.</para>
 
       <example>
 	<title>Using SSH to Create a Secure Tunnel for SMTP</title>
 
         <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput>
 user@mailserver.example.com's password: <userinput>*****</userinput>
 &prompt.user; <userinput>telnet localhost 5025</userinput>
 Trying 127.0.0.1...
 Connected to localhost.
 Escape character is '^]'.
 220 mailserver.example.com ESMTP</screen>     
 
         <para>This can be used in conjunction with an
           &man.ssh-keygen.1; and additional user accounts to create a
           more seamless/hassle-free SSH tunneling environment.  Keys
           can be used in place of typing a password, and the tunnels
           can be run as a separate user.</para>
       </example>
 
       <sect3>
 	<title>Practical SSH Tunneling Examples</title>
 
 	<sect4>
 	  <title>Secure Access of a POP3 Server</title>
 
 	  <para>At work, there is an SSH server that accepts
 	    connections from the outside.  On the same office network
 	    resides a mail server running a POP3 server.  The network,
 	    or network path between your home and office may or may not
 	    be completely trustable.  Because of this, you need to check
 	    your e-mail in a secure manner.  The solution is to create
 	    an SSH connection to your office's SSH server, and tunnel
 	    through to the mail server.</para>
 
 	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput>
 user@ssh-server.example.com's password: <userinput>******</userinput></screen>
 
 	  <para>When the tunnel is up and running, you can point your
 	    mail client to send POP3 requests to <hostid>localhost</hostid>
 	    port 2110.  A connection here will be forwarded securely across
 	    the tunnel to <hostid>mail.example.com</hostid>.</para>
 	</sect4>
 
 	<sect4>
 	  <title>Bypassing a Draconian Firewall</title>
 
 	  <para>Some network administrators impose extremely draconian
 	    firewall rules, filtering not only incoming connections,
 	    but outgoing connections.  You may be only given access
 	    to contact remote machines on ports 22 and 80 for SSH
 	    and web surfing.</para>
 
 	  <para>You may wish to access another (perhaps non-work
 	    related) service, such as an Ogg Vorbis server to stream
 	    music.  If this Ogg Vorbis server is streaming on some other
 	    port than 22 or 80, you will not be able to access it.</para>
 
 	  <para>The solution is to create an SSH connection to a machine
 	    outside of your network's firewall, and use it to tunnel to
 	    the Ogg Vorbis server.</para>
 
 	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled-system.example.org</replaceable></userinput>
 user@unfirewalled-system.example.org's password: <userinput>*******</userinput></screen>
 
 	  <para>Your streaming client can now be pointed to
 	    <hostid>localhost</hostid> port 8888, which will be
 	    forwarded over to <hostid>music.example.com</hostid> port
 	    8000, successfully evading the firewall.</para>
         </sect4>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
       <para><ulink url="http://www.openssh.com/">OpenSSH</ulink></para>
       <para>&man.ssh.1; &man.scp.1; &man.ssh-keygen.1; 
         &man.ssh-agent.1; &man.ssh-add.1;</para>
       <para>&man.sshd.8; &man.sftp-server.8;</para>
     </sect2>
   </sect1>
 
   <sect1 id="fs-acl">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Rhodes</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <indexterm>
       <primary>ACL</primary>
     </indexterm>
     <title>File System Access Control Lists</title>
 
     <para>In conjunction with file system enhancements like snapshots, FreeBSD 5.0
       and later offers the security of File System Access Control Lists
       (<acronym>ACLs</acronym>).</para>
 
     <para>Access Control Lists extend the standard &unix;
       permission model in a highly compatible (&posix;.1e) way.  This feature
       permits an administrator to make use of and take advantage of a
       more sophisticated security model.</para>
 
     <para>To enable <acronym>ACL</acronym> support for <acronym>UFS</acronym>
       file systems, the following:</para>
 
     <programlisting>options UFS_ACL</programlisting>
 
     <para>must be compiled into the kernel.  If this option has
       not been compiled in, a warning message will be displayed
       when attempting to mount a file system supporting <acronym>ACLs</acronym>.
       This option is included in the <filename>GENERIC</filename> kernel.
       <acronym>ACLs</acronym> rely on extended attributes being enabled on
       the file system.  Extended attributes are natively supported in the next generation
       &unix; file system, <acronym>UFS2</acronym>.</para>
 
     <note><para>A higher level of administrative overhead is required to
       configure extended attributes on <acronym>UFS1</acronym> than on
       <acronym>UFS2</acronym>.  The performance of extended attributes
       on <acronym>UFS2</acronym> is also substantially higher.  As a
       result, <acronym>UFS2</acronym> is generally recommended in preference
       to <acronym>UFS1</acronym> for use with access control lists.</para></note>
 
     <para><acronym>ACLs</acronym> are enabled by the mount-time administrative
       flag, <option>acls</option>, which may be added to <filename>/etc/fstab</filename>.
       The mount-time flag can also be automatically set in a persistent manner using
       &man.tunefs.8; to modify a superblock <acronym>ACLs</acronym> flag in the
       file system header.  In general, it is preferred to use the superblock flag
       for several reasons:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The mount-time <acronym>ACLs</acronym> flag cannot be changed by a
 	remount (&man.mount.8; <option>-u</option>), only by means of a complete
 	&man.umount.8; and fresh &man.mount.8;.  This means that
 	<acronym>ACLs</acronym> cannot be enabled on the root file system after boot.
 	It also means that you cannot change the disposition of a file system once
 	it is in use.</para>
       </listitem>
 
       <listitem>
 	<para>Setting the superblock flag will cause the file system to always be
 	mounted with <acronym>ACLs</acronym> enabled even if there is not an
 	<filename>fstab</filename> entry or if the devices re-order.  This prevents
 	accidental mounting of the file system without <acronym>ACLs</acronym>
 	enabled, which can result in <acronym>ACLs</acronym> being improperly enforced,
 	and hence security problems.</para>
       </listitem>
     </itemizedlist>
 
     <note><para>We may change the <acronym>ACLs</acronym> behavior to allow the flag to
       be enabled without a complete fresh &man.mount.8;, but we consider it desirable to
       discourage accidental mounting without <acronym>ACLs</acronym> enabled, because you
       can shoot your feet quite nastily if you enable <acronym>ACLs</acronym>, then disable
       them, then re-enable them without flushing the extended attributes.  In general, once
       you have enabled <acronym>ACLs</acronym> on a file system, they should not be disabled,
       as the resulting file protections may not be compatible with those intended by the
       users of the system, and re-enabling <acronym>ACLs</acronym> may re-attach the previous
       <acronym>ACLs</acronym> to files that have since had their permissions changed,
       resulting in other unpredictable behavior.</para></note>
       
     <para>File systems with <acronym>ACLs</acronym> enabled will show a <literal>+</literal>
       (plus) sign in their permission settings when viewed.  For example:</para>
 
     <programlisting>drwx------  2 robert  robert  512 Dec 27 11:54 private
 drwxrwx---+ 2 robert  robert  512 Dec 23 10:57 directory1
 drwxrwx---+ 2 robert  robert  512 Dec 22 10:20 directory2
 drwxrwx---+ 2 robert  robert  512 Dec 27 11:57 directory3
 drwxr-xr-x  2 robert  robert  512 Nov 10 11:54 public_html</programlisting>
 
     <para>Here we see that the <filename>directory1</filename>,
       <filename>directory2</filename>, and <filename>directory3</filename>
       directories are all taking advantage of <acronym>ACLs</acronym>.  The
       <filename>public_html</filename> directory is not.</para>
 
     <sect2>
       <title>Making Use of <acronym>ACL</acronym>s</title>
 
       <para>The file system <acronym>ACL</acronym>s can be viewed by the
 	&man.getfacl.1; utility.  For instance, to view the
 	<acronym>ACL</acronym> settings on the <filename>test</filename>
 	file, one would use the command:</para>
 
       <screen>&prompt.user; <userinput>getfacl <filename>test</filename></userinput>
 	#file:test
 	#owner:1001
 	#group:1001
 	user::rw-
 	group::r--
 	other::r--</screen>
 
       <para>To change the <acronym>ACL</acronym> settings on this file,
 	invoke the &man.setfacl.1; utility.  Observe:</para>
 
       <screen>&prompt.user; <userinput>setfacl -k <filename>test</filename></userinput></screen>
 
       <para>The <option>-k</option> flag will remove all of the
 	currently defined <acronym>ACL</acronym>s from a file or file
 	system.  The more preferable method would be to use
 	<option>-b</option> as it leaves the basic fields required for
 	<acronym>ACL</acronym>s to work.</para>
 
       <screen>&prompt.user; <userinput>setfacl -m u:trhodes:rwx,group:web:r--,o::--- <filename>test</filename></userinput></screen>
 
       <para>In the aforementioned command, the <option>-m</option>
 	option was used to modify the default <acronym>ACL</acronym>
 	entries.  Since there were no pre-defined entries, as they were
 	removed by the previous command, this will restore the default
 	options and assign the options listed.  Take care to notice that
 	if you add a user or group which does not exist on the system,
 	an <errorname>Invalid argument</errorname> error will be printed
 	to <devicename>stdout</devicename>.</para>
     </sect2>
   </sect1>
 
   <sect1 id="security-advisories">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Rhodes</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <indexterm>
       <primary>FreeBSD Security Advisories</primary>
     </indexterm>
     <title>&os; Security Advisories</title>
 
     <para>Like many production quality operating systems, &os; publishes
       <quote>Security Advisories</quote>.  These advisories are usually
       mailed to the security lists and noted in the Errata only
       after the appropriate releases have been patched.  This section
       will work to explain what an advisory is, how to understand it,
       and what measures to take in order to patch a system.</para>
 
     <sect2>
       <title>What does an advisory look like?</title>
 
       <para>The &os; security advisories look similar to the one below,
 	taken from the &a.security-notifications.name; mailing list.</para>
 
       <programlisting>=============================================================================
 &os;-SA-XX:XX.UTIL                                     Security Advisory
                                                           The &os; Project
 
 Topic:          denial of service due to some problem<co id="co-topic">
 
 Category:       core<co id="co-category">
 Module:         sys<co id="co-module">
 Announced:      2003-09-23<co id="co-announce">
 Credits:        Person@EMAIL-ADDRESS<co id="co-credit">
 Affects:        All releases of &os;<co id="co-affects">
                 &os; 4-STABLE prior to the correction date
 Corrected:      2003-09-23 16:42:59 UTC (RELENG_4, 4.9-PRERELEASE)
                 2003-09-23 20:08:42 UTC (RELENG_5_1, 5.1-RELEASE-p6)
                 2003-09-23 20:07:06 UTC (RELENG_5_0, 5.0-RELEASE-p15)
                 2003-09-23 16:44:58 UTC (RELENG_4_8, 4.8-RELEASE-p8)
                 2003-09-23 16:47:34 UTC (RELENG_4_7, 4.7-RELEASE-p18)
                 2003-09-23 16:49:46 UTC (RELENG_4_6, 4.6-RELEASE-p21)
                 2003-09-23 16:51:24 UTC (RELENG_4_5, 4.5-RELEASE-p33)
                 2003-09-23 16:52:45 UTC (RELENG_4_4, 4.4-RELEASE-p43)
                 2003-09-23 16:54:39 UTC (RELENG_4_3, 4.3-RELEASE-p39)<co id="co-corrected">
 &os; only:   NO<co id="co-only">
 
 For general information regarding FreeBSD Security Advisories,
 including descriptions of the fields above, security branches, and the
 following sections, please visit
 http://www.FreeBSD.org/security/.
 
 I.   Background<co id="co-backround">
 
 
 II.  Problem Description<co id="co-descript">
 
 
 III. Impact<co id="co-impact">
 
 
 IV.  Workaround<co id="co-workaround">
 
 
 V.   Solution<co id="co-solution">
 
 
 VI.  Correction details<co id="co-details">
 
 
 VII. References<co id="co-ref"></programlisting>
 
 
       <calloutlist>
 	<callout arearefs="co-topic">
 	  <para>The <literal>Topic</literal> field indicates exactly what the problem is.
 	    It is basically an introduction to the current security
 	    advisory and notes the utility with the
 	    vulnerability.</para>
 	</callout>
 
 	<callout arearefs="co-category">
 	  <para>The <literal>Category</literal> refers to the affected part of the system
 	    which may be one of <literal>core</literal>, <literal>contrib</literal>, or <literal>ports</literal>.  The <literal>core</literal>
 	    category means that the vulnerability affects a core
 	    component of the &os; operating system.  The <literal>contrib</literal>
 	    category means that the vulnerability affects software
 	    contributed to the &os; Project, such as
 	    <application>sendmail</application>.  Finally the <literal>ports</literal>
 	    category indicates that the vulnerability affects add on
 	    software available as part of the ports collection.</para>
 	</callout>
 
 	<callout arearefs="co-module">
 	  <para>The <literal>Module</literal> field refers to the component location, for
 	    instance <literal>sys</literal>.  In this example, we see that the module,
 	    <literal>sys</literal>, is affected; therefore, this vulnerability
 	    affects a component used within the kernel.</para>
 	</callout>
 
 	<callout arearefs="co-announce">
 	  <para>The <literal>Announced</literal> field reflects the date said security
 	    advisory was published, or announced to the world.  This
 	    means that the security team has verified that the problem
 	    does exist and that a patch has been committed to the &os;
 	    source code repository.</para>
 	</callout>
 
 	<callout arearefs="co-credit">
 	  <para>The <literal>Credits</literal> field gives credit to the individual or
 	    organization who noticed the vulnerability and reported
 	    it.</para>
 	</callout>
 
 	<callout arearefs="co-affects">
 	  <para>The <literal>Affects</literal> field explains which releases of &os; are
 	    affected by this vulnerability.  For the kernel, a quick
 	    look over the output from <command>ident</command> on the
 	    affected files will help in determining the revision.
 	    For ports, the version number is listed after the port name
 	    in <filename>/var/db/pkg</filename>.  If the system does not
 	    sync with the &os; <acronym>CVS</acronym> repository and rebuild
 	    daily, chances are that it is affected.</para>
 	</callout>
 
 	<callout arearefs="co-corrected">
 	  <para>The <literal>Corrected</literal> field indicates the date, time, time
 	    offset, and release that was corrected.</para>
 	</callout>
 
 	<callout arearefs="co-only">
 	  <para>The <literal>&os; only</literal> field indicates whether this vulnerability
 	    affects just &os;, or if it affects other operating systems
 	    as well.</para>
 	</callout>
 
 	<callout arearefs="co-backround">
 	  <para>The <literal>Background</literal> field gives information on exactly what
 	    the affected utility is.  Most of the time this is why
 	    the utility exists in &os;, what it is used for, and a bit
 	    of information on how the utility came to be.</para>
 	</callout>
 
 	<callout arearefs="co-descript">
 	  <para>The <literal>Problem Description</literal> field explains the security hole
 	    in depth.  This can include information on flawed code, or
 	    even how the utility could be maliciously used to open
 	    a security hole.</para>
 	</callout>
 
 	<callout arearefs="co-impact">
 	  <para>The <literal>Impact</literal> field describes what type of impact the
 	    problem could have on a system.  For example, this could
 	    be anything from a denial of service attack, to extra
 	    privileges available to users, or even giving the attacker
 	    superuser access.</para>
 	</callout>
 
 	<callout arearefs="co-workaround">
 	  <para>The <literal>Workaround</literal> field offers a feasible workaround to
 	    system administrators who may be incapable of upgrading
 	    the system.  This may be due to time constraints, network
 	    availability, or a slew of other reasons.  Regardless,
 	    security should not be taken lightly, and an affected system
 	    should either be patched or the security hole workaround
 	    should be implemented.</para>
 	</callout>
 
 	<callout arearefs="co-solution">
 	  <para>The <literal>Solution</literal> field offers instructions on patching the
 	    affected system.  This is a step by step tested and verified
 	    method for getting a system patched and working
 	    securely.</para>
 	</callout>
 
 	<callout arearefs="co-details">
 	  <para>The <literal>Correction Details</literal> field displays the
 	    <acronym>CVS</acronym> branch or release name with the
 	    periods changed to underscore characters.  It also shows
 	    the revision number of the affected files within each
 	    branch.</para>
 	</callout>
 
 	<callout arearefs="co-ref">
 	  <para>The <literal>References</literal> field usually offers sources of other
 	    information.  This can included web <acronym>URL</acronym>s,
 	    books, mailing lists, and newsgroups.</para>
 	</callout>
       </calloutlist>
     </sect2>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
index 250b661e7e..ba4908807e 100644
--- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
@@ -1,1803 +1,1803 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="x11">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Ken</firstname>
 	<surname>Tom</surname>
 	<contrib>Updated for X.Org's X11 server by </contrib>
       </author>
       <author>
 	<firstname>Marc</firstname>
 	<surname>Fonvieille</surname>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>The X Window System</title>
 
   <sect1 id="x11-synopsis">
     <title>Synopsis</title>
 
     <para>FreeBSD uses X11 to provide users with
       a powerful graphical user interface.  X11
       is an open-source implementation of the X Window System that
       includes both <application>&xorg;</application> and
       <application>&xfree86;</application>.  &os; versions up to and
       including &os;&nbsp;4.10-RELEASE and &os;&nbsp;5.2.1-RELEASE
       will find the default installation to be
       <application>&xfree86;</application>, the X11 server released by
       The &xfree86; Project, Inc.  As of &os;&nbsp;5.3-RELEASE, the
       default and official flavor of X11 was changed to
       <application>&xorg;</application>, the X11 server developed by
       the X.Org Foundation.</para>
 
     <para>This chapter will cover the installation and configuration
       of X11 with emphasis on
       <application>&xorg;</application>.</para>
 
     <para>For more information on the video hardware that X11
       supports, check either the <ulink
       url="http://www.x.org/">&xorg;</ulink> or <ulink
       url="http://www.XFree86.org/">&xfree86;</ulink> web
       sites.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
         <para>The various components of the X Window System, and how they
           interoperate.</para>
       </listitem>
 
       <listitem>
 	<para>How to install and configure X11.</para>
       </listitem>
 
       <listitem>
         <para>How to install and use different window managers.</para>
       </listitem>
 
       <listitem>
 	<para>How to use &truetype; fonts in X11.</para>
       </listitem>
 
       <listitem>
         <para>How to set up your system for graphical logins
           (<application>XDM</application>).</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem><para>Know how to install additional third-party
         software (<xref linkend="ports">).</para></listitem>
     </itemizedlist>
 
     <note>
       <para>This chapter covers the installation and the configuration
 	of both <application>&xorg;</application> and
 	<application>&xfree86;</application> X11 servers.  For the most
 	part, configuration files, commands and syntaxes are identical.
 	In the case where there are differences, both
 	<application>&xorg;</application> and
 	<application>&xfree86;</application> syntaxes will be
 	shown.</para>
     </note>
   </sect1>
 
   <sect1 id="x-understanding">
     <title>Understanding X</title>
 
     <para>Using X for the first time can be somewhat of a shock to someone
       familiar with other graphical environments, such as &microsoft.windows; or
       &macos;.</para>
 
     <para>While it is not necessary to understand all of the details of various
       X components and how they interact, some basic knowledge makes
       it possible to take advantage of X's strengths.</para>
 
     <sect2>
       <title>Why X?</title>
 
       <para>X is not the first window system written for &unix;, but it is the
         most popular of them.  X's original development team had worked on another
         window system prior to writing X.  That system's name was
         <quote>W</quote> (for <quote>Window</quote>).  X was just the next
         letter in the Roman alphabet.</para>
 
       <para>X can be called <quote>X</quote>, <quote>X Window System</quote>,
 	<quote>X11</quote>, and a number of other terms.  You may find
 	that using the term <quote>X Windows</quote> to describe X11
 	can be offensive to some people; for a bit more insight on
 	this, see &man.X.7;.</para>
     </sect2>
 
     <sect2>
       <title>The X Client/Server Model</title>
 
       <para>X was designed from the beginning to be network-centric, and
         adopts a <quote>client-server</quote> model.</para>
 
       <para>In the X model, the
         <quote>X server</quote> runs on the computer that has the keyboard,
         monitor, and mouse attached.  The server's responsibility includes tasks such as managing
         the display, handling input from the keyboard and mouse, and so on.
         Each X application (such as <application>XTerm</application>, or
         <application>&netscape;</application>) is a <quote>client</quote>.  A
         client sends messages to the server such as <quote>Please draw a
           window at these coordinates</quote>, and the server sends back
           messages such as <quote>The user just clicked on the OK
           button</quote>.</para>
 
       <para>In a home or small
         office environment, the X server and the X clients commonly run on
         the same computer.  However, it is perfectly possible to run the X
         server on a less powerful desktop computer, and run X applications
         (the clients) on, say, the powerful and expensive machine that serves
         the office.  In this scenario the communication between the X client
         and server takes place over the network.</para>
 
       <para>This confuses some people, because the X terminology is
         exactly backward to what they expect.  They expect the <quote>X
           server</quote> to be the big powerful machine down the hall, and
         the <quote>X client</quote> to be the machine on their desk.</para>
 
       <para>It is important to remember that the X server is the machine with the monitor and
         keyboard, and the X clients are the programs that display the
         windows.</para>
 
       <para>There is nothing in the protocol that forces the client and
         server machines to be running the same operating system, or even to
         be running on the same type of computer.  It is certainly possible to
         run an X server on &microsoft.windows; or Apple's &macos;, and there are
         various free and commercial applications available that do exactly
         that.</para>
 
       <para>Starting with &os;&nbsp;5.3-RELEASE, the X server that
 	installs with &os; is <application>&xorg;</application>,
         and is available for free, under a
         license very similar to the FreeBSD license.  Commercial X servers for
         FreeBSD are also available.</para>
     </sect2>
 
     <sect2>
       <title>The Window Manager</title>
 
       <para>The X design philosophy is much like the &unix; design philosophy,
         <quote>tools, not policy</quote>.  This means that X does not try to
         dictate how a task is to be accomplished.  Instead, tools are provided
         to the user, and it is the user's responsibility to decide how to use
         those tools.</para>
 
       <para>This philosophy extends to X not dictating what windows should
         look like on screen, how to move them around with the mouse, what
         keystrokes should be used to move between windows (i.e.,
         <keycombo action="simul">
           <keycap>Alt</keycap>
           <keycap>Tab</keycap>
         </keycombo>, in the case of &microsoft.windows;), what the title bars
         on each window should look like, whether or not they have close
         buttons on them, and so on.</para>
 
       <para>Instead, X delegates this responsibility to an application called
         a <quote>Window Manager</quote>.  There are dozens of window
         managers available for X: <application>AfterStep</application>,
         <application>Blackbox</application>, <application>ctwm</application>,
         <application>Enlightenment</application>,
         <application>fvwm</application>, <application>Sawfish</application>,
         <application>twm</application>,
         <application>Window Maker</application>, and more.  Each of these
         window managers provides a different look and feel; some of them
         support <quote>virtual desktops</quote>; some of them allow customized
         keystrokes to manage the desktop; some have a <quote>Start</quote>
         button or similar device; some are <quote>themeable</quote>, allowing
         a complete change of look-and-feel by applying a new theme.  These
         window managers, and many more, are available in the
         <filename>x11-wm</filename> category of the Ports Collection.</para>
 
       <para>In addition, the <application>KDE</application> and
 	<application>GNOME</application> desktop environments both have their
 	own window managers which integrate with the desktop.</para>
 
       <para>Each window manager also has a different configuration mechanism;
         some expect configuration file written by hand, others feature
         GUI tools for most of the configuration tasks; at least one
         (<application>Sawfish</application>) has a configuration file written
         in a dialect of the Lisp language.</para>
 
       <note>
         <title>Focus Policy</title>
 
         <para>Another feature the window manager is responsible for is the
           mouse <quote>focus policy</quote>.  Every windowing system
           needs some means of choosing a window to be actively receiving
           keystrokes, and should visibly indicate which window is active as
           well.</para>
 
         <para>A familiar focus policy is called <quote>click-to-focus</quote>.
           This is the model utilized by &microsoft.windows;, in which a window
           becomes active upon receiving a mouse click.</para>
 
         <para>X does not support any particular focus policy.  Instead, the
           window manager controls which window has the focus at any one time.
           Different window managers will support different focus methods.  All
           of them support click to focus, and the majority of them support
           several others.</para>
 
         <para>The most popular focus policies are:</para>
 
         <variablelist>
           <varlistentry>
             <term>focus-follows-mouse</term>
 
             <listitem>
               <para>The window that is under the mouse pointer is the
                 window that has the focus.  This may not necessarily be
                 the window that is on top of all the other windows.
                 The focus is changed by pointing at another window, there
                 is no need to click in it as well.</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>sloppy-focus</term>
 
             <listitem>
               <para>This policy is a small extension to focus-follows-mouse.
                 With focus-follows-mouse, if the mouse is moved over the
                 root window (or background) then no window has the focus,
                 and keystrokes are simply lost.  With sloppy-focus, focus is
                 only changed when the cursor enters a new window, and not
                 when exiting the current window.</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>click-to-focus</term>
 
             <listitem>
               <para>The active window is selected by mouse click.  The
                 window may then be <quote>raised</quote>, and appear in
                 front of all other windows.  All keystrokes will now be
                 directed to this window, even if the cursor is moved to
                 another window.</para>
             </listitem>
           </varlistentry>
         </variablelist>
 
         <para>Many window managers support other policies, as well as
           variations on these.  Be sure to consult the documentation for
           the window manager itself.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Widgets</title>
 
       <para>The X approach of providing tools and not policy extends to the
         widgets seen on screen in each application.</para>
 
       <para><quote>Widget</quote> is a term for all the items in the user
         interface that can be clicked or manipulated in some way; buttons,
         check boxes, radio buttons, icons, lists, and so on.  &microsoft.windows;
         calls these <quote>controls</quote>.</para>
 
       <para>&microsoft.windows; and Apple's &macos; both have a very rigid widget
         policy.  Application developers are supposed to ensure that their
         applications share a common look and feel.  With X, it was not
         considered sensible to mandate a particular graphical style, or set
         of widgets to adhere to.</para>
 
       <para>As a result, do not expect X applications to have a common
         look and feel.  There are several popular widget sets and
         variations, including the original Athena widget set from MIT,
         <application>&motif;</application> (on which the widget set in
         &microsoft.windows; was modeled, all bevelled edges and three shades of
         grey), <application>OpenLook</application>, and others.</para>
 
       <para>Most newer X applications today will use a modern-looking widget
         set, either Qt, used by <application>KDE</application>, or
         GTK+, used by the
         <application>GNOME</application>
         project.  In this respect, there is some convergence in
         look-and-feel of the &unix; desktop, which certainly makes things
         easier for the novice user.</para>
     </sect2>
   </sect1>
 
   <sect1 id="x-install">
     <title>Installing X11</title>
 
     <para><application>&xorg;</application> or
       <application>&xfree86;</application> may be installed on &os;.
       Beginning with &os;&nbsp;5.3-RELEASE,
       <application>&xorg;</application> is the default X11
       implementation for &os;.  <application>&xorg;</application> is
       the X server of the open source X Window System implementation released by the X.Org
       Foundation.  <application>&xorg;</application> is based on the code of
       <application>&xfree86&nbsp;4.4RC2</application> and X11R6.6.
       The X.Org Foundation released X11R6.7 in April 2004 and
       X11R6.8.1 in September 2004, this latter is the version
       currently available in the &os; ports collection.</para>
 
     <para>To build and install <application>&xorg;</application> from the
       ports collection:</para>
 
     <screen>&prompt.root; <userinput>cd /usr/ports/x11/xorg</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
     <note>
       <para>To build <application>&xorg;</application> in its
 	entirety, be sure to have at least 4&nbsp;GB of free space
 	available.</para>
     </note>
 
     <para>To build and install <application>&xfree86;</application>
       from the ports collection:</para>
 
     <screen>&prompt.root; <userinput>cd /usr/ports/x11/XFree86-4</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
     <para>Alternatively, X11
       can be installed directly from packages.
       Binary packages to use with &man.pkg.add.1; tool are also available for
       X11.  When the remote fetching
       feature of &man.pkg.add.1; is used, the version number of the
       package must be removed.  &man.pkg.add.1; will automatically fetch
       the latest version of the application.</para>
 
     <para>So to fetch and install the package of
       <application>&xorg;</application>, simply type:</para>
 
     <screen>&prompt.root; <userinput>pkg_add -r xorg</userinput></screen>
 
     <para>The <application>&xfree86;&nbsp;4.X</application> package can be
       installed by typing:</para>
 
     <screen>&prompt.root; <userinput>pkg_add -r XFree86</userinput></screen>
 
     <note><para>The examples above will install the complete
       X11 distribution including the
       servers, clients, fonts etc.  Separate packages and ports of X11
       are also
       available.</para></note>
 
     <para>The rest of this chapter will explain how to configure
       X11, and how to set up a productive desktop
       environment.</para>
 
     <sect2 id="x-to-xorg">
       <title>Moving from <application>&xfree86;</application> to
 	<application>&xorg;</application></title>
 
       <para>As with any port, you should check the
 	<filename>/usr/ports/UPDATING</filename> file for changes.
 	Included in this file are instructions for converting your
 	system from <application>&xfree86;</application> to
 	<application>&xorg;</application>.</para>
 
       <para>Use <application>CVSup</application> to update your ports
 	tree prior to attempting any conversion.  You will also need
 	to install <filename
 	role="package">sysutils/portupgrade</filename> prior to
 	converting your X11 installation.</para>
 
       <para>In your <filename>/etc/make.conf</filename> you will need
 	to add the variable <literal>X_WINDOW_SYSTEM=xorg</literal>.
 	This ensures that your system knows which X11 is being used.
 	The older <literal>XFREE86_VERSION</literal> variable has been
 	deprecated and has been replaced with the
 	<literal>X_WINDOW_SYSTEM</literal> variable.</para>
 
       <para>Then, use the following commands:</para>
 
       <screen>&prompt.root; <userinput>pkg_delete -f /var/db/pkg/imake-4* /var/db/pkg/XFree86-*</userinput>
 &prompt.root; <userinput>cd /usr/ports/x11/xorg</userinput>
 &prompt.root; <userinput>make install clean</userinput>
 &prompt.root; <userinput>pkgdb -F</userinput></screen>
 
       <para>The &man.pkgdb.1; command is part of the
 	<application>portupgrade</application> software and will
 	update various package dependencies.</para>
 
       <note>
 	<para>To build <application>&xorg;</application> in its
 	  entirety, be sure to have at least 4&nbsp;GB of free space
 	  available.</para>
       </note>
     </sect2>
   </sect1>
 
   <sect1 id="x-config">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Christopher</firstname>
           <surname>Shumway</surname>
           <contrib>Contributed by </contrib>
           <!-- July 2001 -->
         </author>
       </authorgroup>
     </sect1info>
     <title>X11 Configuration</title>
 
 
     <indexterm><primary>&xfree86;&nbsp;4.X</primary></indexterm>
     <indexterm><primary>&xfree86;</primary></indexterm>
     <indexterm><primary>&xorg;</primary></indexterm>
     <indexterm><primary>X11</primary></indexterm>
 
     <sect2>
       <title>Before Starting</title>
 
       <para>Before configuration of X11
         the following information about the target system is needed:</para>
 
       <itemizedlist>
         <listitem><para>Monitor specifications</para></listitem>
         <listitem><para>Video Adapter chipset</para></listitem>
         <listitem><para>Video Adapter memory</para></listitem>
       </itemizedlist>
 
       <indexterm><primary>horizontal scan rate</primary></indexterm>
       <indexterm><primary>vertical scan rate</primary></indexterm>
 
       <para>The specifications for the monitor are used by
         X11 to determine the resolution and
         refresh rate to run at.  These specifications can usually be
         obtained from the documentation that came with the monitor or from
         the manufacturer's website.  There are two ranges of numbers that
         are needed, the horizontal scan rate and the vertical synchronization
         rate.</para>
 
       <para>The video adapter's chipset defines what driver module
         X11 uses to talk to the graphics
         hardware.  With most chipsets, this can be automatically
         determined, but it is still useful to know in case the automatic
         detection does not work correctly.</para>
 
       <para>Video memory on the graphic adapter determines the
         resolution and color depth which the system can run at.  This is
         important to know so the user knows the limitations of the
         system.</para>
 
     </sect2>
 
     <sect2>
       <title>Configuring X11</title>
 
       <para>Configuration of X11 is
         a multi-step process.  The first step is to build an initial
         configuration file.
         As the super user, simply
         run:</para>
 
       <screen>&prompt.root; <userinput>Xorg -configure</userinput></screen>
 
       <para>In the case of <application>&xfree86;</application>
 	type:</para>
 
       <screen>&prompt.root; <userinput>XFree86 -configure</userinput></screen>
 
       <para>This will generate an
         X11 configuration skeleton file in the
         <filename>/root</filename> directory called
 	<filename>xorg.conf.new</filename> (whether you &man.su.1; or
 	do a direct login affects the inherited supervisor
 	<envar>$HOME</envar> directory variable).
 	For <application>&xfree86;</application>, this configuration
 	file is called  <filename>XF86Config.new</filename>.  The
         X11 program will attempt to probe
         the graphics hardware on the system and write a
         configuration file to load the proper drivers for the detected
         hardware on the target system.</para>
 
       <para>The next step is to test the existing
         configuration to verify that <application>&xorg;</application>
         can work with the graphics
         hardware on the target system.  To perform this task,
         type:</para>
 
       <screen>&prompt.root; <userinput>Xorg -config xorg.conf.new</userinput></screen>
 
       <para><application>&xfree86;</application> users will type:</para>
 
       <screen>&prompt.root; <userinput>XFree86 -xf86config XF86Config.new</userinput></screen>
 
       <para>If a black and grey grid and an X mouse cursor appear,
         the configuration was successful.  To exit the test, just press
         <keycombo action="simul">
           <keycap>Ctrl</keycap>
           <keycap>Alt</keycap>
           <keycap>Backspace</keycap>
         </keycombo> simultaneously.</para>
 
 	<note><para>If the mouse does not work, you will need to first
 	  configure it before proceeding.  See <xref linkend="mouse">
 	  in the &os; install chapter.</para></note>
 
       <indexterm><primary>X11 tuning</primary></indexterm>
 
       <para>Next, tune the <filename>xorg.conf.new</filename> (or <filename>XF86Config.new</filename> if you are running <application>&xfree86;</application>)
         configuration file to taste.  Open the file in a text editor such
         as &man.emacs.1; or &man.ee.1;.  First, add the
         frequencies for the target system's monitor.  These are usually
         expressed as a horizontal and vertical synchronization rate.  These
         values are added to the <filename>xorg.conf.new</filename> file
         under the <literal>"Monitor"</literal> section:</para>
 
       <programlisting>Section "Monitor"
         Identifier   "Monitor0"
         VendorName   "Monitor Vendor"
         ModelName    "Monitor Model"
         HorizSync    30-107
         VertRefresh  48-120
 EndSection</programlisting>
 
       <para>The <literal>HorizSync</literal> and
         <literal>VertRefresh</literal> keywords may be missing in the
         configuration file.  If they are, they need to be added, with
         the correct horizontal synchronization rate placed after the
         <literal>HorizSync</literal> keyword and the vertical
         synchronization rate after the <literal>VertRefresh</literal>
         keyword.  In the example above the target monitor's rates were
         entered.</para>
 
       <para>X allows DPMS (Energy Star) features to be used with capable
         monitors. The &man.xset.1; program controls the time-outs and can force
         standby, suspend, or off modes.  If you wish to enable DPMS features
         for your monitor, you must add the following line to the monitor
         section:</para>
 
       <programlisting>
         Option       "DPMS"</programlisting>
 
       <indexterm>
         <primary><filename>xorg.conf</filename></primary>
       </indexterm>
       <indexterm>
         <primary><filename>XF86Config</filename></primary>
       </indexterm>
 
       <para>While the <filename>xorg.conf.new</filename> (or <filename>XF86Config.new</filename>)
         configuration file is still open in an editor, select
         the default resolution and color depth desired.  This is
         defined in the <literal>"Screen"</literal> section:</para>
 
       <programlisting>Section "Screen"
         Identifier "Screen0"
         Device     "Card0"
         Monitor    "Monitor0"
         DefaultDepth 24
         SubSection "Display"
                 Viewport  0 0
                 Depth     24
                 Modes     "1024x768"
         EndSubSection
 EndSection</programlisting>
 
       <para>The <literal>DefaultDepth</literal> keyword describes
         the color depth to run at by default.  This can be overridden
         with the <option>-depth</option> command line switch to
         &man.Xorg.1; (or &man.XFree86.1;).
         The <literal>Modes</literal> keyword
         describes the resolution to run at for the given color depth.
         Note that only VESA standard modes are supported as defined by
         the target system's graphics hardware.
         In the example above, the default color depth is twenty-four
         bits per pixel.  At this color depth, the accepted resolution is
         1024 by 768
         pixels.</para>
 
       <para>Finally, write the configuration file and test it using
         the test mode given above.</para>
 
       <note>
 	<para>One of the tools available to assist you during
 	  troubleshooting process are the X11 log files, which contain
 	  information on each device that the X11 server attaches to.
 	  <application>&xorg;</application> log file names are in the format
 	  of <filename>/var/log/Xorg.0.log</filename>
 	  (<application>&xfree86;</application> log file names follow the
 	  format of <filename>XFree86.0.log</filename>).  The exact name
 	  of the log can vary from <filename>Xorg.0.log</filename> to
 	  <filename>Xorg.8.log</filename> and so forth.</para>
       </note>
 
       <para>If all is well, the configuration
         file needs to be installed in a common location where
         &man.Xorg.1; (or &man.XFree86.1;)
         can find it.
 	This is typically <filename>/etc/X11/xorg.conf</filename> or
 	<filename>/usr/X11R6/etc/X11/xorg.conf</filename> (for
 	<application>&xfree86;</application> it is called
         <filename>/etc/X11/XF86Config</filename> or
         <filename>/usr/X11R6/etc/X11/XF86Config</filename>).</para>
 
       <screen>&prompt.root; <userinput>cp xorg.conf.new /etc/X11/xorg.conf</userinput></screen>
 
       <para>For <application>&xfree86;</application>:</para>
 
       <screen>&prompt.root; <userinput>cp XF86Config.new /etc/X11/XF86Config</userinput></screen>
 
       <para>The X11 configuration process is now
         complete.  In order to start
         <application>&xfree86;&nbsp;4.X</application> with &man.startx.1;,
         install the <filename role="package">x11/wrapper</filename> port.
 	<application>&xorg;</application> already includes the wrapper
 	code and does not require the installation of the wrapper port.
 	The X11 server may also be started with the use of
         &man.xdm.1;.</para>
 
       <note><para>There is also a graphical configuration tool,
 	&man.xorgcfg.1; (&man.xf86cfg.1; for <application>&xfree86;</application>), that comes with the
 	X11 distribution.  It
 	allows you to interactively define your configuration by choosing
 	the appropriate drivers and settings.  This program can be invoked from the console, by typing the command <command>xorgcfg -textmode</command>.  For more details,
 	refer to the &man.xorgcfg.1; and &man.xf86cfg.1; manual pages.</para>
 
       <para>Alternatively, there is also a tool called &man.xorgconfig.1;
 	(&man.xf86config.1; for <application>&xfree86;</application>),
 	this program is a console utility that is less user friendly,
 	but it may work in situations where the other tools do
 	not.</para></note>
 
     </sect2>
 
     <sect2>
       <title>Advanced Configuration Topics</title>
 
       <sect3>
         <title>Configuration with &intel; i810 Graphics Chipsets</title>
 
         <indexterm><primary>Intel i810 graphic chipset</primary></indexterm>
 
         <para>Configuration with &intel; i810 integrated chipsets
           requires the <devicename>agpgart</devicename>
           AGP programming interface for X11
           to drive the card.  The &man.agp.4; driver is in the
 	  <filename>GENERIC</filename> kernel since releases
 	  4.8-RELEASE and 5.0-RELEASE.  On prior releases, you will
 	  have to add the following line:</para>
 
 	<programlisting>device agp</programlisting>
 
 	<para>in your kernel configuration file and rebuild a new
 	  kernel.  Instead, you may want to load
 	  the <filename>agp.ko</filename> kernel module
           automatically with the &man.loader.8; at boot time.
           For that, simply add this line to
           <filename>/boot/loader.conf</filename>:</para>
 
         <programlisting>agp_load="YES"</programlisting>
 
         <para>Next, if you are running FreeBSD&nbsp;4.X or earlier, a
           device node needs to be created for the
           programming interface.  To create the AGP device node, run
           &man.MAKEDEV.8; in the <filename>/dev</filename>
           directory:</para>
 
         <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV agpgart</userinput></screen>
 
 	<note>
 	  <para>FreeBSD&nbsp;5.X or later will use &man.devfs.5; to allocate
 	    device nodes transparently, therefore the
 	    &man.MAKEDEV.8; step is not required.</para>
 	</note>
 
         <para>This will allow configuration of the hardware as any other
           graphics board.  Note on systems without the &man.agp.4;
 	  driver compiled in the kernel, trying to load the module
 	  with &man.kldload.8; will not work.  This driver has to be
 	  in the kernel at boot time through being compiled in or
 	  using <filename>/boot/loader.conf</filename>.</para>
 
 	<para>If you are using <application>&xfree86;&nbsp;4.1.0</application> (or
 	  later) and messages about unresolved symbols like
           <literal>fbPictureInit</literal> appear, try adding the
           following line after <literal>Driver "i810"</literal> in the
           X11 configuration file:</para>
         <programlisting>Option "NoDDC"</programlisting>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="x-fonts">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Murray</firstname>
           <surname>Stokely</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Using Fonts in X11</title>
 
     <sect2 id="type1">
     <title>Type1 Fonts</title>
     <para>The default fonts that ship with
       X11 are less than ideal for typical
     desktop publishing applications.  Large presentation fonts show up
     jagged and unprofessional looking, and small fonts in
     <application>&netscape;</application> are almost completely unintelligible.
     However, there are several free, high quality Type1 (&postscript;) fonts
     available which can be readily used
     with X11.  For instance, the URW font collection
     (<filename role="package">x11-fonts/urwfonts</filename>) includes
     high quality versions of standard type1 fonts (<trademark class="registered">Times Roman</trademark>,
     <trademark class="registered">Helvetica</trademark>, <trademark class="registered">Palatino</trademark> and others).  The Freefonts collection
     (<filename role="package">x11-fonts/freefonts</filename>) includes
     many more fonts, but most of them are intended for use in
     graphics software such as the <application>Gimp</application>, and are not
     complete enough to serve as screen fonts.  In addition,
     X11 can be configured to use
     &truetype; fonts with a minimum of effort.  For more details on
     this, see the &man.X.7; manual page or the
     <link linkend="truetype">section on &truetype; fonts</link>.</para>
 
     <para>To install the above Type1 font collections from the ports
         collection, run the following commands:</para>
 
     <screen>&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
     <para>And likewise with the freefont or other collections.  To have the X
       server detect these fonts, add an appropriate line to the
       X server configuration file in <filename>/etc/X11/</filename>
       (<filename>xorg.conf</filename> for
       <application>&xorg;</application> and
       <filename>XF86Config</filename> for
       <application>&xfree86;</application>), which reads:</para>
 
       <programlisting>FontPath "/usr/X11R6/lib/X11/fonts/URW/"</programlisting>
 
       <para>Alternatively, at the command line in the X session
         run:</para>
 
       <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/URW</userinput>
 &prompt.user; <userinput>xset fp rehash</userinput></screen>
 
       <para>This will work but will be lost when the X session is closed,
     unless it is added to the startup file (<filename>~/.xinitrc</filename>
     for a normal <command>startx</command> session,
     or <filename>~/.xsession</filename> when logging in through a
     graphical login manager like <application>XDM</application>).
     A third way is to use the new
     <filename>/usr/X11R6/etc/fonts/local.conf</filename> file: see the
     section on <link linkend="antialias">anti-aliasing</link>.
     </para>
     </sect2>
 
     <sect2 id="truetype">
     <title>&truetype; Fonts</title>
 
     <indexterm><primary>TrueType Fonts</primary></indexterm>
     <indexterm><primary>fonts</primary>
       <secondary>TrueType</secondary>
     </indexterm>
 
     <para>Both <application>&xfree86;&nbsp;4.X</application> and <application>&xorg;</application> have built in support
     for rendering &truetype; fonts.  There are two different modules
     that can enable this functionality.  The freetype module is used
     in this example because it is more consistent with the other font
     rendering back-ends.  To enable the freetype module just add the
     following line to the <literal>"Module"</literal> section of the
     <filename>/etc/X11/xorg.conf</filename> or
     <filename>/etc/X11/XF86Config</filename> file.</para>
 
     <programlisting>Load  "freetype"</programlisting>
 
     <para>For <application>&xfree86;&nbsp;3.3.X</application>, a separate
       &truetype; font server is needed.
       <application>Xfstt</application> is commonly used for
       this purpose.  To install <application>Xfstt</application>,
       simply install the port
       <filename role="package">x11-servers/Xfstt</filename>.</para>
 
     <para>Now make a directory for the &truetype; fonts (for example,
       <filename>/usr/X11R6/lib/X11/fonts/TrueType</filename>)
       and copy all of the &truetype; fonts into this directory.  Keep in
       mind that &truetype; fonts cannot be directly taken from a
       &macintosh;; they must be in &unix;/&ms-dos;/&windows; format for use by
       X11.  Once the files have been
       copied into this directory, use
       <application>ttmkfdir</application> to create a
       <filename>fonts.dir</filename> file, so that the X font renderer
       knows that these new files have been installed.
       <command>ttmkfdir</command> is available from the FreeBSD
       Ports Collection as
       <filename role="package">x11-fonts/ttmkfdir</filename>.</para>
 
     <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/TrueType</userinput>
 &prompt.root; <userinput>ttmkfdir &gt; fonts.dir</userinput></screen>
 
     <para>Now add the &truetype; directory to the font
       path.  This is just the same as described above for <link
       linkend="type1">Type1</link> fonts, that is, use</para>
 
     <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/TrueType</userinput>
 &prompt.user; <userinput>xset fp rehash</userinput></screen>
 
     <para>or add a <literal>FontPath</literal> line to the
        <filename>xorg.conf</filename> (or <filename>XF86Config</filename>) file.</para>
 
       <para>That's it.  Now <application>&netscape;</application>,
         <application>Gimp</application>,
         <application>&staroffice;</application>, and all of the other X
         applications should now recognize the installed &truetype;
         fonts.  Extremely small fonts (as with text in a high resolution
         display on a web page) and extremely large fonts (within
         <application>&staroffice;</application>) will look much better
         now.</para>
     </sect2>
 
     <sect2 id="antialias">
     <sect2info>
       <authorgroup>
         <author>
           <firstname>Joe Marcus</firstname>
           <surname>Clarke</surname>
           <contrib>Updated by </contrib>
           <!-- May 2003 -->
         </author>
       </authorgroup>
     </sect2info>
     <title>Anti-Aliased Fonts</title>
 
     <indexterm><primary>anti-aliased fonts</primary></indexterm>
     <indexterm><primary>fonts</primary>
       <secondary>anti-aliased</secondary></indexterm>
 
     <para>Anti-aliasing has been available in X11 since
       <application>&xfree86;</application> 4.0.2.  However, font
       configuration was cumbersome before the introduction of
       <application>&xfree86;</application> 4.3.0.
       Beginning with
       <application>&xfree86;</application> 4.3.0, all fonts in X11
       that are found
       in <filename>/usr/X11R6/lib/X11/fonts/</filename> and
       <filename>~/.fonts/</filename> are automatically 
       made available for anti-aliasing to Xft-aware applications.  Not
       all applications are Xft-aware, but many have received Xft support.
       Examples of Xft-aware applications include Qt 2.3 and higher (the 
       toolkit for the <application>KDE</application> desktop), 
       GTK+ 2.0 and higher (the toolkit for the 
       <application>GNOME</application> desktop), and 
       <application>Mozilla</application> 1.2 and higher.
     </para>
 
     <para>In order to control which fonts are anti-aliased, or to
       configure anti-aliasing properties, create (or edit, if it
       already exists) the file
       <filename>/usr/X11R6/etc/fonts/local.conf</filename>.  Several
       advanced features of the Xft font system can be tuned using
       this file; this section describes only some simple
       possibilities.  For more details, please see
       &man.fonts-conf.5;.</para>
 
     <indexterm><primary>XML</primary></indexterm>
 
     <para>This file must be in XML format.  Pay careful attention to
       case, and make sure all tags are properly closed.  The file
       begins with the usual XML header followed by a DOCTYPE
       definition, and then the <literal>&lt;fontconfig&gt;</literal> tag:</para>
 
     <programlisting>
       &lt;?xml version="1.0"?&gt;
       &lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&gt;
       &lt;fontconfig&gt;
     </programlisting>
 
     <para>As previously stated, all fonts in
       <filename>/usr/X11R6/lib/X11/fonts/</filename> as well as
       <filename>~/.fonts/</filename> are already made available to
       Xft-aware applications.  If you wish to add another directory
       outside of these two directory trees, add a line similar to the
       following to
       <filename>/usr/X11R6/etc/fonts/local.conf</filename>:</para>
 
     <programlisting>&lt;dir&gt;/path/to/my/fonts&lt;/dir&gt;</programlisting>
 
     <para>After adding new fonts, and especially new font directories,
       you should run the following command to rebuild the font
       caches:</para>
 
     <screen>&prompt.root; <userinput>fc-cache -f</userinput></screen>
 
     <para>Anti-aliasing makes borders slightly fuzzy, which makes very
       small text more readable and removes <quote>staircases</quote> from
       large text, but can cause eyestrain if applied to normal text.  To
       exclude font sizes smaller than 14 point from anti-aliasing, include
       these lines:</para>
 
       <programlisting>        &lt;match target="font"&gt;
             &lt;test name="size" compare="less"&gt;
                 &lt;double&gt;14&lt;/double&gt;
             &lt;/test&gt;
             &lt;edit name="antialias" mode="assign"&gt;
                 &lt;bool&gt;false&lt;/bool&gt;
             &lt;/edit&gt;
         &lt;/match&gt;
         &lt;match target="font"&gt;
             &lt;test name="pixelsize" compare="less" qual="any"&gt;
                 &lt;double&gt;14&lt;/double&gt;
             &lt;/test&gt;
             &lt;edit mode="assign" name="antialias"&gt;
                 &lt;bool&gt;false&lt;/bool&gt;
             &lt;/edit&gt;
         &lt;/match&gt;</programlisting>
 
     <indexterm><primary>fonts</primary>
       <secondary>spacing</secondary></indexterm>
 
     <para>Spacing for some monospaced fonts may also be inappropriate
       with anti-aliasing.  This seems to be an issue with
       <application>KDE</application>, in particular.  One possible fix for
       this is to force the spacing for such fonts to be 100.  Add the
       following lines:</para>
 
      <programlisting>       &lt;match target="pattern" name="family"&gt;
            &lt;test qual="any" name="family"&gt;
                &lt;string&gt;fixed&lt;/string&gt;
            &lt;/test&gt;
            &lt;edit name="family" mode="assign"&gt;
                &lt;string&gt;mono&lt;/string&gt;
            &lt;/edit&gt;
         &lt;/match&gt;
         &lt;match target="pattern" name="family"&gt;
             &lt;test qual="any" name="family"&gt;
                 &lt;string&gt;console&lt;/string&gt;
             &lt;/test&gt;
             &lt;edit name="family" mode="assign"&gt;
                 &lt;string&gt;mono&lt;/string&gt;
             &lt;/edit&gt;
         &lt;/match&gt;</programlisting>
 
       <para>(this aliases the other common names for fixed fonts as
         <literal>"mono"</literal>), and then add:</para>
 
       <programlisting>         &lt;match target="pattern" name="family"&gt;
              &lt;test qual="any" name="family"&gt;
                  &lt;string&gt;mono&lt;/string&gt;
              &lt;/test&gt;
              &lt;edit name="spacing" mode="assign"&gt;
                  &lt;int&gt;100&lt;/int&gt;
              &lt;/edit&gt;
          &lt;/match&gt;      </programlisting>
 
       <para>Certain fonts, such as Helvetica, may have a problem when
 	anti-aliased.  Usually this manifests itself as a font that
 	seems cut in half vertically.  At worst, it may cause
 	applications such as <application>Mozilla</application> to
 	crash.  To avoid this, consider adding the following to
 	<filename>local.conf</filename>:</para>
 
       <programlisting>         &lt;match target="pattern" name="family"&gt;
              &lt;test qual="any" name="family"&gt;
                  &lt;string&gt;Helvetica&lt;/string&gt;
              &lt;/test&gt;
              &lt;edit name="family" mode="assign"&gt;
                  &lt;string&gt;sans-serif&lt;/string&gt;
              &lt;/edit&gt;
          &lt;/match&gt;        </programlisting>
 
       <para>Once you have finished editing
         <filename>local.conf</filename> make sure you end the file
         with the <literal>&lt;/fontconfig&gt;</literal> tag.  Not doing this will cause
         your changes to be ignored.</para>
 
        <para>The default font set that comes with 
 	 X11 is not very
          desirable when it comes to anti-aliasing.  A much better
 	 set of default fonts can be found in the 
 	 <filename role="package">x11-fonts/bitstream-vera</filename>
 	 port.  This port will install a
 	 <filename>/usr/X11R6/etc/fonts/local.conf</filename> file
 	 if one does not exist already.  If the file does exist,
 	 the port will create a <filename>/usr/X11R6/etc/fonts/local.conf-vera
 	 </filename> file.  Merge the contents of this file into
 	 <filename>/usr/X11R6/etc/fonts/local.conf</filename>, and the 
 	 Bitstream fonts will automatically replace the default 
 	 X11 Serif, Sans Serif, and Monospaced
 	 fonts.</para>
 
        <para>Finally, users can add their own settings via their personal 
         <filename>.fonts.conf</filename> files.  To do this, each user should 
 	simply create a <filename>~/.fonts.conf</filename>.  This file must 
 	also be in XML format.</para>
 
        <indexterm><primary>LCD screen</primary></indexterm>
        <indexterm><primary>Fonts</primary>
          <secondary>LCD screen</secondary></indexterm>
 
        <para>One last point: with an LCD screen, sub-pixel sampling may be
         desired.  This basically treats the (horizontally separated)
         red, green and blue components separately to improve the horizontal
         resolution; the results can be dramatic.  To enable this, add the
         line somewhere in the <filename>local.conf</filename> file:</para>
 
        <programlisting>
          &lt;match target="font"&gt;
              &lt;test qual="all" name="rgba"&gt;
                  &lt;const&gt;unknown&lt;/const&gt;
              &lt;/test&gt;
              &lt;edit name="rgba" mode="assign"&gt;
                  &lt;const&gt;rgb&lt;/const&gt;
              &lt;/edit&gt;
          &lt;/match&gt;
        </programlisting>
 
        <note><para>Depending on the sort of display,
 	 <literal>rgb</literal> may need to be changed to <literal>bgr</literal>,
 	 <literal>vrgb</literal> or <literal>vbgr</literal>: experiment and
 	 see which works best.</para></note>
 
-       <indexterm><primary>Mozilla</primary></indexterm>
-       <indexterm><primary>web browsers</primary>
-         <secondary>Mozilla</secondary>
-         <see>Mozilla</see></indexterm>
+       <indexterm>
+	 <primary>Mozilla</primary>
+         <secondary>disabling anti-aliased fonts</secondary>
+       </indexterm>
 
        <para>Anti-aliasing should be enabled the next time the X
          server is started.  However, programs must know how to take
          advantage of it.  At present, the Qt toolkit does,
          so the entire <application>KDE</application> environment can
          use anti-aliased fonts (see <xref
          linkend="x11-wm-kde-antialias"> on
          <application>KDE</application> for details).  GTK+ and 
          <application>GNOME</application> can also be made to use 
          anti-aliasing via the <quote>Font</quote> capplet (see <xref
          linkend="x11-wm-gnome-antialias"> for details).  By default,
          <application>Mozilla</application> 1.2 and greater will 
          automatically use anti-aliasing. To disable this, rebuild 
          <application>Mozilla</application> with the
          <makevar>-DWITHOUT_XFT</makevar> flag.</para>
     </sect2>
   </sect1>
 
   <sect1 id="x-xdm">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Seth</firstname>
           <surname>Kingsley</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>The X Display Manager</title>
     <sect2>
       <title>Overview</title>
 
       <indexterm><primary>X Display Manager</primary></indexterm>
       <para>The X Display Manager (<application>XDM</application>) is
         an optional part of the X Window System that is used for login
         session management.  This is useful for several types of
         situations, including minimal <quote>X Terminals</quote>,
         desktops, and large network display
         servers.  Since the X Window System is network and protocol
         independent, there are a wide variety of possible configurations
         for running X clients and servers on different machines
         connected by a network.  <application>XDM</application> provides
         a graphical interface for choosing which display server to
         connect to, and entering authorization information such as a
         login and password combination.</para>
 
       <para>Think of <application>XDM</application> as
         providing the same functionality to the user as the
         &man.getty.8; utility (see <xref linkend="term-config"> for
           details).  That is, it performs system logins to the display
           being connected to and then runs a session manager on behalf of
           the user (usually an X window
           manager).  <application>XDM</application> then waits for this
           program to exit, signaling that the user is done and should be
           logged out of the display.  At this point,
           <application>XDM</application> can display the login and display
           chooser screens for the next user to login.</para>
     </sect2>
 
     <sect2>
       <title>Using XDM</title>
 
       <para>The <application>XDM</application> daemon program is
         located in <filename>/usr/X11R6/bin/xdm</filename>.  This program
         can be run at any time as <username>root</username> and it will
         start managing the X display on the local machine.  If
         <application>XDM</application> is to be run every
         time the machine boots up, a convenient way to do this is by
         adding an entry to <filename>/etc/ttys</filename>.  For more
         information about the format and usage of this file, see <xref
         linkend="term-etcttys">.  There is a line in the default
         <filename>/etc/ttys</filename> file for running the
         <application>XDM</application> daemon on a virtual terminal:</para>
 
       <screen>ttyv8   "/usr/X11R6/bin/xdm -nodaemon"  xterm   off secure</screen>
 
       <para>By default this entry is disabled; in order to enable it
         change field 5 from <literal>off</literal> to
         <literal>on</literal> and restart &man.init.8; using the
         directions in <xref linkend="term-hup">.  The first field, the
         name of the terminal this program will manage, is
         <literal>ttyv8</literal>.  This means that
         <application>XDM</application> will start running on the 9th
         virtual terminal.</para>
     </sect2>
 
     <sect2>
       <title>Configuring XDM</title>
 
       <para>The <application>XDM</application> configuration directory
         is located in <filename>/usr/X11R6/lib/X11/xdm</filename>.  In
         this directory there are several files used to change the
         behavior and appearance of
         <application>XDM</application>.  Typically these files will
         be found:</para>
 
         <informaltable frame="none" pgwide="1">
           <tgroup cols="2">
             <thead>
               <row>
                 <entry>File</entry>
                 <entry>Description</entry>
               </row>
             </thead>
 
             <tbody>
               <row>
                 <entry><filename>Xaccess</filename></entry>
                 <entry>Client authorization ruleset.</entry>
               </row>
 
               <row>
                 <entry><filename>Xresources</filename></entry>
                 <entry>Default X resource values.</entry>
               </row>
 
               <row>
                 <entry><filename>Xservers</filename></entry>
                 <entry>List of remote and local displays to manage.</entry>
               </row>
 
               <row>
                 <entry><filename>Xsession</filename></entry>
                 <entry>Default session script for logins.</entry>
               </row>
 
               <row>
                 <entry><filename>Xsetup_</filename>*</entry>
                 <entry>Script to launch applications before the login
                   interface.</entry>
               </row>
 
               <row>
                 <entry><filename>xdm-config</filename></entry>
                 <entry>Global configuration for all displays running on
                   this machine.</entry>
               </row>
 
               <row>
                 <entry><filename>xdm-errors</filename></entry>
                 <entry>Errors generated by the server program.</entry>
               </row>
 
               <row>
                 <entry><filename>xdm-pid</filename></entry>
                 <entry>The process ID of the currently running XDM.</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
       <para>Also in this directory are a few scripts and programs used
         to set up the desktop when <application>XDM</application> is
         running.  The purpose of each of these files will be briefly
         described.  The exact syntax and usage of all of these files is
         described in &man.xdm.1;.</para>
 
       <para>The default configuration is a simple rectangular login
         window with the hostname of the machine displayed at the top in
         a large font and <quote>Login:</quote> and
         <quote>Password:</quote> prompts below.  This is a good starting
         point for changing the look and feel of
         <application>XDM</application> screens.</para>
 
       <sect3>
         <title>Xaccess</title>
 
         <para>The protocol for connecting to
           <application>XDM</application> controlled displays is called
           the X Display Manager Connection Protocol (XDMCP).  This file
           is a ruleset for controlling XDMCP connections from remote
           machines.  By default, it allows any client to connect, but
           that does not matter unless the <filename>xdm-config</filename>
           is changed to listen for remote connections.</para>
       </sect3>
 
       <sect3>
         <title>Xresources</title>
         <para>This is an application-defaults file for the display
           chooser and the login screens.  This is where the appearance
           of the login program can be modified.  The format is identical
           to the app-defaults file described in the
 	  X11 documentation.</para>
       </sect3>
 
       <sect3>
         <title>Xservers</title>
         <para>This is a list of the remote displays the chooser should
           provide as choices.</para>
       </sect3>
 
       <sect3>
         <title>Xsession</title>
         <para>This is the default session script for
           <application>XDM</application> to run after a user has logged
           in.  Normally each user will have a customized session script
           in <filename>~/.xsession</filename> that overrides this
           script.</para>
       </sect3>
 
       <sect3>
         <title>Xsetup_*</title>
         <para>These will be run automatically before displaying the
           chooser or login interfaces.  There is a script for each
           display being used, named <filename>Xsetup_</filename> followed
           by the local display number (for instance
           <filename>Xsetup_0</filename>).  Typically these scripts will
           run one or two programs in the background such as
           <command>xconsole</command>.</para>
       </sect3>
 
       <sect3>
         <title>xdm-config</title>
         <para>This contains settings in the form of app-defaults
           that are applicable to every display that this installation
           manages.</para>
       </sect3>
 
       <sect3>
         <title>xdm-errors</title>
         <para>This contains the output of the X servers that
           <application>XDM</application> is trying to run.  If a display
           that <application>XDM</application> is trying to start hangs
           for some reason, this is a good place to look for error
           messages.  These messages are also written to the user's
           <filename>~/.xsession-errors</filename> file on a per-session
           basis.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Running a Network Display Server</title>
 
       <para>In order for other clients to connect to the display
         server, edit the access control rules, and enable the connection
         listener.  By default these are set to conservative values.
         To make <application>XDM</application> listen for connections,
         first comment out a line in the <filename>xdm-config</filename>
         file:</para>
 
       <screen>! SECURITY: do not listen for XDMCP or Chooser requests
 ! Comment out this line if you want to manage X terminals with xdm
 DisplayManager.requestPort:     0</screen>
 
       <para>and then restart <application>XDM</application>.  Remember that
         comments in app-defaults files begin with a <quote>!</quote>
         character, not the usual <quote>#</quote>.  More strict
         access controls may be desired.  Look at the example
         entries in <filename>Xaccess</filename>, and refer to the
         &man.xdm.1; manual page.</para>
     </sect2>
 
      <sect2>
         <title>Replacements for XDM</title>
 
         <para>Several replacements for the default
           <application>XDM</application> program exist.  One of them,
           <application>kdm</application> (bundled with
           <application>KDE</application>) is described later in this
           chapter.  The <application>kdm</application> display manager offers many visual
           improvements and cosmetic frills, as well as the
           functionality to allow users to choose their window manager
           of choice at login time.</para>
      </sect2>
   </sect1>
 
   <sect1 id="x11-wm">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Valentino</firstname>
           <surname>Vaschetto</surname>
           <contrib>Contributed by </contrib>
         </author>
         <!-- June 2001 -->
       </authorgroup>
     </sect1info>
 
     <title>Desktop Environments</title>
 
     <para>This section describes the different desktop environments
       available for X on FreeBSD.  A <quote>desktop environment</quote>
       can mean anything ranging from a simple window manager to a
       complete suite of desktop applications, such as
       <application>KDE</application> or <application>GNOME</application>.
     </para>
 
     <sect2 id="x11-wm-gnome">
       <title>GNOME</title>
 
       <sect3 id="x11-wm-gnome-about">
         <title>About GNOME</title>
 
         <indexterm><primary>GNOME</primary></indexterm>
         <para><application>GNOME</application> is a user-friendly
           desktop environment that enables users to easily use and
           configure their computers.  <application>GNOME</application>
           includes a panel (for starting applications and displaying
           status), a desktop (where data and applications can be
           placed), a set of standard desktop tools and applications, and
           a set of conventions that make it easy for applications to
           cooperate and be consistent with each other.  Users of other
           operating systems or environments should feel right at home
           using the powerful graphics-driven environment that
           <application>GNOME</application> provides.  More
 	  information regarding <application>GNOME</application> on
 	  FreeBSD can be found on the <ulink
 	  url="http://www.FreeBSD.org/gnome">FreeBSD GNOME
 	  Project</ulink>'s web site.</para>
       </sect3>
 
       <sect3 id="x11-wm-gnome-install">
         <title>Installing GNOME</title>
 
         <para>The easiest way to install
           <application>GNOME</application> is through the
           <quote>Desktop Configuration</quote> menu during the FreeBSD
 	  installation process as described in <xref
 	  linkend="default-desktop"> of Chapter&nbsp;2.  It can also
           be easily installed from a package or the ports
           collection:</para>
 
         <para>To install the <application>GNOME</application> package
           from the network, simply type:</para>
 
         <screen>&prompt.root; <userinput>pkg_add -r gnome2</userinput></screen>
 
         <para>To build <application>GNOME</application> from source, use
           the ports tree:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
         <para>Once <application>GNOME</application> is installed,
           the X server must be told to start
           <application>GNOME</application> instead of a default window
           manager.  If a custom <filename>.xinitrc</filename> is already in
           place, simply replace the line that starts the current window
           manager with one that starts
           <application>/usr/X11R6/bin/gnome-session</application> instead.
           If nothing special has been done to configuration file,
           then it is enough to simply type:</para>
 
         <screen>&prompt.user; <userinput>echo "/usr/X11R6/bin/gnome-session" &gt; ~/.xinitrc</userinput></screen>
 
         <para>Next, type <command>startx</command>, and the
           <application>GNOME</application> desktop environment will be
           started.</para>
 
         <note><para>If a display manager, like
           <application>XDM</application>, is being used, this will not work.
           Instead, create an executable <filename>.xsession</filename>
           file with the same command in it.  To do this, edit the file
           and replace the existing window manager command with
           <application>/usr/X11R6/bin/gnome-session</application>:
           </para></note>
 
         <screen>&prompt.user; <userinput>echo "#!/bin/sh" > ~/.xsession</userinput>
 &prompt.user; <userinput>echo "/usr/X11R6/bin/gnome-session" >> ~/.xsession</userinput>
 &prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
 
         <para>Another option is to configure the display manager to
           allow choosing the window manager at login time; the section on
           <link linkend="x11-wm-kde-details">KDE details</link>
           explains how to do this for <application>kdm</application>, the
           display manager of <application>KDE</application>.</para>
       </sect3>
 
       <sect3 id="x11-wm-gnome-antialias">
         <title>Anti-aliased Fonts with GNOME</title>
 
         <indexterm><primary>GNOME</primary>
           <secondary>anti-aliased fonts</secondary></indexterm>
 	<para>X11
 	  supports anti-aliasing via its <quote>RENDER</quote> extension.
 	  GTK+ 2.0 and greater (the toolkit used by
 	  <application>GNOME</application>) can make use of this
 	  functionality.  Configuring anti-aliasing is described in
 	  <xref linkend="antialias">.  So, with up-to-date software,
 	  anti-aliasing is possible within the
 	  <application>GNOME</application> desktop.  Just go to
 	  <menuchoice>
 	    <guimenu>Applications</guimenu>
 	    <guisubmenu>Desktop Preferences</guisubmenu>
 	    <guimenuitem>Font</guimenuitem></menuchoice>, and select either
 	  <guibutton>Best shapes</guibutton>, 
 	  <guibutton>Best contrast</guibutton>, or
 	  <guibutton>Subpixel smoothing (LCDs)</guibutton>.  For a
 	  GTK+ application that is not part of the 
 	  <application>GNOME</application> desktop, set the
 	  environment variable <varname>GDK_USE_XFT</varname> to
 	  <literal>1</literal> before launching the program.</para>
       </sect3>
     </sect2>
 
     <sect2 id="x11-wm-kde">
       <title>KDE</title>
 
       <indexterm><primary>KDE</primary></indexterm>
       <sect3 id="x11-wm-kde-about">
         <title>About KDE</title>
 
         <para><application>KDE</application> is an easy to use
           contemporary desktop environment.  Some of the things that
           <application>KDE</application> brings to the user are:</para>
 
         <itemizedlist>
           <listitem>
 	    <para>A beautiful contemporary desktop</para>
 	  </listitem>
 
           <listitem>
 	    <para>A desktop exhibiting complete network transparency</para>
 	  </listitem>
 
           <listitem>
 	    <para>An integrated help system allowing for convenient,
 	      consistent access to help on the use of the
 	      <application>KDE</application> desktop and its
 	      applications</para>
 	  </listitem>
 
           <listitem>
 	    <para>Consistent look and feel of all
               <application>KDE</application> applications</para>
 	  </listitem>
 
           <listitem>
 	    <para>Standardized menu and toolbars, keybindings, color-schemes,
 	      etc.</para>
 	  </listitem>
 
           <listitem>
 	    <para>Internationalization: <application>KDE</application>
               is available in more than 40 languages</para>
 	  </listitem>
 
           <listitem>
 	    <para>Centralized consisted dialog driven desktop
 	      configuration</para>
 	  </listitem>
 
           <listitem>
 	    <para>A great number of useful
               <application>KDE</application> applications</para>
 	  </listitem>
         </itemizedlist>
 
         <para><application>KDE</application> has an office application
           suite based on <application>KDE</application>'s
           <quote>KParts</quote> technology consisting
           of a spread-sheet, a presentation application, an organizer, a
           news client and more.  <application>KDE</application> also
           comes with a web browser called
           <application>Konqueror</application>, which represents
           a solid competitor to other existing web browsers on &unix;
           systems.  More information on <application>KDE</application>
           can be found on the <ulink url="http://www.kde.org/">KDE
           website</ulink>.  For FreeBSD specific information and
 	  resources on <application>KDE</application>, consult
 	  the <ulink url="http://freebsd.kde.org/">FreeBSD-KDE
 	  team</ulink>'s website.</para>
       </sect3>
 
       <sect3 id="x11-wm-kde-install">
         <title>Installing KDE</title>
 
         <para>Just as with <application>GNOME</application> or any
           other desktop environment, the easiest way to install
           <application>KDE</application> is through the <quote>Desktop
           Configuration</quote> menu during the FreeBSD installation
 	  process as described in <xref linkend="default-desktop"> of Chapter
 	  2.  Once again, the software can be easily installed from a package
 	  or from the ports collection:</para>
 
         <para>To install the <application>KDE</application> package
           from the network, simply type:</para>
 
         <screen>&prompt.root; <userinput>pkg_add -r kde</userinput></screen>
 
 	<para>&man.pkg.add.1; will automatically fetch the latest version
 	  of the application.</para>
 
         <para>To build <application>KDE</application> from source,
           use the ports tree:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde3</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
         <para>After <application>KDE</application> has been installed,
           the X server must be told to launch this application
           instead of the default window manager.  This is accomplished
           by editing the <filename>.xinitrc</filename> file:</para>
 
         <screen>&prompt.user; <userinput>echo "exec startkde" &gt; ~/.xinitrc</userinput></screen>
 
 	<para>Now, whenever the X Window System is invoked with
 	  <command>startx</command>,
           <application>KDE</application> will be the desktop.</para>
 
         <para>If a display manager such as
           <application>XDM</application> is being used, the
           configuration is slightly different.  Edit the
           <filename>.xsession</filename> file instead.  Instructions
           for <application>kdm</application> are described later in
           this chapter.</para>
       </sect3>
     </sect2>
 
     <sect2 id="x11-wm-kde-details">
         <title>More Details on KDE</title>
 
         <para>Now that <application>KDE</application> is installed on
           the system, most things can be discovered through the
           help pages, or just by pointing and clicking at various menus.
           &windows; or &mac; users will feel quite at home.</para>
 
         <para>The best reference for <application>KDE</application> is
           the on-line documentation.  <application>KDE</application>
           comes with its own web browser,
           <application>Konqueror</application>, dozens of useful
           applications, and extensive documentation.  The remainder of
           this section discusses the technical items that are
           difficult to learn by random exploration.</para>
 
       <sect3 id="x11-wm-kde-kdm">
         <title>The KDE Display Manager</title>
 
         <indexterm><primary>KDE</primary>
           <secondary>display manager</secondary></indexterm>
         <para>An administrator of a multi-user system may wish to have
           a graphical login screen to welcome users.
           <link linkend="x-xdm">XDM</link> can be
           used, as described earlier.  However,
           <application>KDE</application> includes an
           alternative, <application>kdm</application>, which is designed
           to look more attractive and include more login-time options.
           In particular, users can easily choose (via a menu) which
           desktop environment (<application>KDE</application>,
           <application>GNOME</application>, or something else) to run
           after logging on.</para>
 
         <para>To begin with, run the <application>KDE</application>
           control panel, <command>kcontrol</command>, as
           <username>root</username>.  It is generally considered
           unsafe to run the entire X environment as
           <username>root</username>.  Instead, run the window manager
           as a normal user, open a terminal window (such as
           <filename>xterm</filename> or <application>KDE</application>'s
           <filename>konsole</filename>), become <username>root</username>
           with <userinput>su</userinput> (the user must be in the
           <groupname>wheel</groupname>
           group in <filename>/etc/group</filename> for this), and then
           type <userinput>kcontrol</userinput>.</para>
 
 	<para>Click on the icon on the left marked
 	  <guibutton>System</guibutton>, then on <guibutton>Login
 	  manager</guibutton>.  On the right there are
           various configurable options, which the
           <application>KDE</application> manual will explain in greater
           detail.  Click on <guibutton>sessions</guibutton> on the right.
           Click <guibutton>New type</guibutton> to add various window
           managers and desktop environments.  These are just labels,
           so they can say <application>KDE</application> and
           <application>GNOME</application> rather than
           <application>startkde</application> or
           <application>gnome-session</application>.
           Include a label <literal>failsafe</literal>.</para>
 
         <para>Play with the other menus as well, they are mainly
           cosmetic and self-explanatory.  When you are done, click on
           <guibutton>Apply</guibutton> at the bottom, and quit the
           control center.</para>
 
         <para>To make sure <application>kdm</application> understands
           what the labels (<application>KDE</application>,
           <application>GNOME</application> etc) mean, edit the files used
           by <link linkend="x-xdm">XDM</link>.
           <note><para>In <application>KDE 2.2</application> this has
             changed: <application>kdm</application> now uses its own
             configuration files.  Please see the <application>KDE
             2.2</application> documentation for details.</para>
           </note>
           In a terminal window, as <username>root</username>,
           edit the file
           <filename>/usr/X11R6/lib/X11/xdm/Xsession</filename>.  There is
           a section in the middle like this:</para>
 
 	<screen>case $# in
 1)
         case $1 in
         failsafe)
                 exec xterm -geometry 80x24-0-0
                 ;;
         esac
 esac</screen>
 
         <para>A few lines need to be added to this section.
           Assuming the labels from used were <quote>KDE</quote> and
           <quote>GNOME</quote>,
           use the following:</para>
 
 	<screen>case $# in
 1)
         case $1 in
         kde)
                 exec /usr/local/bin/startkde
                 ;;
         GNOME)
                 exec /usr/X11R6/bin/gnome-session
                 ;;
         failsafe)
                 exec xterm -geometry 80x24-0-0
                 ;;
         esac
 esac</screen>
 
         <para>For the <application>KDE</application>
           login-time desktop background to be honored,
           the following line needs to be added to
           <filename>/usr/X11R6/lib/X11/xdm/Xsetup_0</filename>:</para>
 
         <screen>/usr/local/bin/kdmdesktop</screen>
 
         <para>Now, make sure <application>kdm</application> is listed in
           <filename>/etc/ttys</filename> to be started at the next bootup.
           To do this, simply follow the instructions from the previous
           section on <link linkend="x-xdm">XDM</link> and replace
           references to the <command>/usr/X11R6/bin/xdm</command>
           program with <command>/usr/local/bin/kdm</command>.</para>
       </sect3>
 
       <sect3 id="x11-wm-kde-antialias">
         <title>Anti-aliased Fonts</title>
 
         <indexterm><primary>KDE</primary>
           <secondary>anti-aliased fonts</secondary></indexterm>
         <para>X11
 	  supports anti-aliasing via
 	  its <quote>RENDER</quote> extension, and starting with version 2.3,
 	  Qt (the toolkit used by <application>KDE</application>) supports
 	  this extension.  Configuring this is described in <xref
           linkend="antialias"> on antialiasing X11 fonts.  So, with
           up-to-date software, anti-aliasing is possible on a
           <application>KDE</application> desktop.  Just go to the KDE
 	  menu, go to
 	  <menuchoice>
 	    <guimenu>Preferences</guimenu>
 	    <guisubmenu>Look and Feel</guisubmenu>
 	    <guimenuitem>Fonts</guimenuitem></menuchoice>, and click on the check box
           <guibutton>Use Anti-Aliasing for Fonts and Icons</guibutton>.
           For a Qt application which is not part of
 	  <application>KDE</application>, the environment variable
 	  <varname>QT_XFT</varname> needs to be set to <literal>true</literal>
 	  before starting the program.</para>
 
        </sect3>
      </sect2>
 
      <sect2 id="x11-wm-xfce">
          <title>XFce</title>
        <sect3 id="x11-wm-xfce-about">
          <title>About XFce</title>
 
         <para><application>XFce</application> is a desktop environment
           based on the GTK+
           toolkit used by <application>GNOME</application>, but is much
           more lightweight and meant for those who want a simple,
           efficient desktop which is nevertheless easy to use and
           configure.  Visually, it looks very much like
           <application>CDE</application>, found on commercial &unix;
           systems.  Some of <application>XFce</application>'s features
           are:</para>
 
          <itemizedlist>
            <listitem>
 	     <para>A simple, easy-to-handle desktop</para>
            </listitem>
 
            <listitem>
 	     <para>Fully configurable via mouse, with drag and
                drop, etc </para>
            </listitem>
 
            <listitem>
 	     <para>Main panel similar to <application>CDE</application>, with
 	       menus, applets and applications launchers</para>
            </listitem>
 
            <listitem>
 	     <para>Integrated window manager, file manager, sound manager,
 	       <application>GNOME</application> compliance module, and other
 	       things</para>
            </listitem>
 
            <listitem>
 	     <para>Themeable (since it uses GTK+)</para>
            </listitem>
 
            <listitem>
 	     <para>Fast, light and efficient: ideal for older/slower machines
 	       or machines with memory limitations</para>
            </listitem>
          </itemizedlist>
 
          <para>More information on <application>XFce</application>
           can be found on the <ulink url="http://www.xfce.org/">XFce
             website</ulink>.</para>
        </sect3>
 
        <sect3 id="x11-wm-xfce-install">
          <title>Installing XFce</title>
 
         <para>A binary package for <application>XFce</application>
           exists (at the time of writing).  To install, simply type:</para>
 
         <screen>&prompt.root; <userinput>pkg_add -r xfce4</userinput></screen>
 
         <para>Alternatively, to build from source, use the ports
           collection:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce4</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
         <para>Now, tell the X server to launch
          <application>XFce</application> the next time X is started.
          Simply type this:</para>
 
         <screen>&prompt.user; <userinput>echo "/usr/X11R6/bin/startxfce4" &gt; ~/.xinitrc</userinput></screen>
 
         <para>The next time X is started,
           <application>XFce</application> will be the desktop.
           As before, if a display manager like
           <application>XDM</application> is being used, create an
           <filename>.xsession</filename>, as described in the
           section on <link linkend="x11-wm-gnome">GNOME</link>, but
           with the <filename>/usr/X11R6/bin/startxfce4</filename>
           command; or, configure the display manager to allow
           choosing a desktop at login time, as explained in
           the section on <link linkend="x11-wm-kde-kdm">kdm</link>.</para>
       </sect3>
     </sect2>
   </sect1>
 
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->