diff --git a/en_US.ISO8859-1/articles/contributing/article.sgml b/en_US.ISO8859-1/articles/contributing/article.sgml
index 3f421eb362..8c4b280b79 100644
--- a/en_US.ISO8859-1/articles/contributing/article.sgml
+++ b/en_US.ISO8859-1/articles/contributing/article.sgml
@@ -1,504 +1,504 @@
 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 <!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous
 FreeBSD Entities//EN"> %freebsd;
 <!ENTITY % newsgroups PUBLIC "-//FreeBSD//ENTITIES DocBook Newsgroup Entities//EN"> %newsgroups;
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
 <!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"> %mailing-lists;
 <!ENTITY % not.published "IGNORE">
 ]>
 
 <article>
   <articleinfo>
     <title>Contributing to FreeBSD</title>
     
     <pubdate>$FreeBSD$</pubdate>
     
     <abstract>
       <para>This article describes the different ways in which an
         individual or organization may contribute to the FreeBSD
         Project.</para>
     </abstract>
 
     <authorgroup>
       <author>
 	<firstname>Jordan</firstname>
 	<surname>Hubbard</surname>
 	<contrib>Contributed by </contrib>
       </author>
     </authorgroup>
   </articleinfo>
   
   <indexterm><primary>contributing</primary></indexterm>
 
   <para>So you want to contribute to FreeBSD? That is great!  FreeBSD
     <emphasis>relies</emphasis> on the contributions of its user base
     to survive.  Your contributions are not only appreciated, they are
     vital to FreeBSD's continued growth.</para>
       
   <para>Contrary to what some people might have you believe, you do
     not need to be a hot-shot programmer or a close personal friend of
     the FreeBSD core team to have your contributions accepted.  A
     large and growing number of international contributors, of greatly
     varying ages and areas of technical expertise, develop FreeBSD.
     There is always more work to be done than there are people
     available to do it, and more help is always appreciated.</para>
       
   <para>The FreeBSD project is responsible for an entire operating
     system environment, rather than just a kernel or a few scattered
     utilities.  As such, our <filename>TODO</filename> lists span a
     very wide range of tasks: from documentation, beta testing and
     presentation, to the system installer and highly specialized types
     of kernel development.  People of any skill level, in almost any
     area, can almost certainly help the project.</para>
       
   <para>Commercial entities engaged in FreeBSD-related enterprises are
     also encouraged to contact us.  Do you need a special extension to
     make your product work? You will find us receptive to your
     requests, given that they are not too outlandish.  Are you working
     on a value-added product? Please let us know! We may be able to
     work cooperatively on some aspect of it.  The free software world
     is challenging many existing assumptions about how software is
     developed, sold, and maintained, and we urge you to at least give
     it a second look.</para>
       
   <sect1 id="contrib-what">
     <title>What Is Needed</title>
     
     <para>The following list of tasks and sub-projects represents something of
       an amalgam of the various core team <filename>TODO</filename> lists and
       user requests we have collected over the last couple of months.  Where
       possible, tasks have been ranked by degree of urgency.  If you are
       interested in working on one of the tasks you see here, send mail to the
       coordinator listed by clicking on their names.  If no coordinator has
       been appointed, maybe you would like to volunteer?</para>
 
     <sect2>
       <title>Ongoing Tasks</title>
       
       <para>Most of the tasks listed in the next sections require either a
 	considerable investment of time or an in-depth knowledge of the
 	FreeBSD kernel (or both).  However, there are also many useful tasks
 	which are suitable for <quote>weekend hackers</quote>, or people without
 	programming skills.</para>
       
       <orderedlist>
 	<listitem>
 	  <para>If you run FreeBSD-current and have a good Internet
 	    connection, there is a machine <hostid
 	      role="fqdn">current.FreeBSD.org</hostid> which builds a full
 	    release once a day &mdash; every now and again, try and install
 	    the latest release from it and report any failures in the
 	    process.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Read the freebsd-bugs mailing list.  There might be a
 	    problem you can comment constructively on or with patches you
 	    can test.  Or you could even try to fix one of the problems
 	    yourself.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Read through the FAQ and Handbook periodically.  If anything
 	    is badly explained, out of date or even just completely wrong, let
 	    us know.  Even better, send us a fix (SGML is not difficult to
 	    learn, but there is no objection to ASCII submissions).</para>
 	</listitem>
 
 	<listitem>
 	  <para>Help translate FreeBSD documentation into your native language
 	    (if not already available) &mdash; just send an email to &a.doc;
 	    asking if anyone is working on it.  Note that you are not
 	    committing yourself to translating every single FreeBSD document
 	    by doing this &mdash; in fact, the documentation most in need of
 	    translation is the installation instructions.</para>
 	</listitem>
 
 	<listitem>
-	  <para>Read the freebsd-questions mailing list and &ng.misc
+	  <para>Read the freebsd-questions mailing list and &ng.misc;
 	    occasionally (or even regularly).  It can be very satisfying to
 	    share your expertise and help people solve their problems;
 	    sometimes you may even learn something new yourself! These forums
 	    can also be a source of ideas for things to work on.</para>
 	</listitem>
 
 	<listitem>
 	  <para>If you know of any bug fixes which have been successfully
 	    applied to -current but have not been merged into -stable after a
 	    decent interval (normally a couple of weeks), send the committer a
 	    polite reminder.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Move contributed software to <filename>src/contrib</filename>
 	    in the source tree.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Make sure code in <filename>src/contrib</filename> is up to
 	    date.</para>
 	</listitem>
 	      
 	<listitem>
 	  <para>Build the source tree (or just part of it) with extra warnings
 	    enabled and clean up the warnings.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Fix warnings for ports which do deprecated things like
 	    using <function>gets()</function> or including
 	    <filename>malloc.h</filename>.</para>
 	</listitem>
 
 	<listitem>
 	  <para>If you have contributed any ports, send your patches back to
 	    the original author (this will make your life easier when they
 	    bring out the next version)</para>
 	</listitem>
 
 	<listitem>
 	  <para>Suggest further tasks for this list!</para>
 	</listitem>
       </orderedlist>
     </sect2>
 
     <sect2>
       <title>Work through the PR Database</title>
 
       <indexterm><primary>problem reports database</primary></indexterm>
       <para>The <ulink
 	  url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD PR
 	  list</ulink> shows all the current active problem reports and
 	requests for enhancement that have been submitted by FreeBSD users.
 	Look through the open PRs, and see if anything there takes your
 	interest.  Some of these might be very simple tasks, that just need an
 	extra pair of eyes to look over them and confirm that the fix in the
 	PR is a good one.  Others might be much more complex.</para>
 
       <para>Start with the PRs that have not been assigned to anyone else, but
 	if one them is assigned to someone else, but it looks like something
 	you can handle, email the person it is assigned to and ask if you can
 	work on it&mdash;they might already have a patch ready to be tested,
 	or further ideas that you can discuss with them.</para>
     </sect2>
   </sect1>
   
   <sect1 id="contrib-how">
     <title>How to Contribute</title>
     
     <para>Contributions to the system generally fall into one or more of the
       following 6 categories:</para>
 
     <sect2 id="contrib-general">
       <title>Bug Reports and General Commentary</title>
       
       <para>An idea or suggestion of <emphasis>general</emphasis> technical
 	interest should be mailed to the &a.hackers;.  Likewise, people with
 	an interest in such things (and a tolerance for a
 	<emphasis>high</emphasis> volume of mail!) may subscribe to the
 	hackers mailing list by sending mail to &a.majordomo;.  See <ulink
 	url="../../books/handbook/eresources.html#ERESOURCES-MAIL">The
 	FreeBSD Handbook</ulink> for more information
 	about this and other mailing lists.</para>
 	  
       <para>If you find a bug or are submitting a specific change, please
 	report it using the &man.send-pr.1; program or its <ulink
 	  url="../../../../send-pr.html">WEB-based
 	  equivalent</ulink>.  Try to fill-in each field of the bug report.
 	Unless they exceed 65KB, include any patches directly in the report.
 	If the patch is suitable to be applied to the source tree put
 	<literal>[PATCH]</literal> in the synopsis of the report.
 	When including patches, <emphasis>do not</emphasis> use cut-and-paste
 	because cut-and-paste turns tabs into spaces and makes them unusable.
 	Consider compressing patches and using &man.uuencode.1; if they exceed
 	20KB.  Upload very large submissions to <ulink
 	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming/">ftp.FreeBSD.org:/pub/FreeBSD/incoming/</ulink>.</para>
 	  
       <para>After filing a report, you should receive confirmation along with
 	a tracking number.  Keep this tracking number so that you can update
 	us with details about the problem by sending mail to
 	<email>bug-followup@FreeBSD.org</email>.  Use the number as the
 	message subject, e.g.  <literal>"Re: kern/3377"</literal>.  Additional
 	information for any bug report should be submitted this way.</para>
 	  
       <para>If you do not receive confirmation in a timely fashion (3 days to
 	a week, depending on your email connection) or are, for some reason,
 	unable to use the &man.send-pr.1; command, then you may ask
 	someone to file it for you by sending mail to the &a.bugs;.</para>
 
       <para>See also <ulink
   	URL="../../articles/problem-reports/article.html">this
   	article</ulink> on how to write good problem reports.</para>
     </sect2>
     
     <sect2>
       <title>Changes to the Documentation</title>
       
       <indexterm><primary>documentation submissions</primary></indexterm>
       <para>Changes to the documentation are overseen by the &a.doc;.  Send
 	submissions and changes (even small ones are welcome!) using
 	<command>send-pr</command> as described in <link
 	  linkend="contrib-general">Bug Reports and General
 	  Commentary</link>.</para>
     </sect2>
     
     <sect2>
       <title>Changes to Existing Source Code</title>
       
       <indexterm><primary>FreeBSD-current</primary></indexterm>
       <para>An addition or change to the existing source code is a somewhat
 	trickier affair and depends a lot on how far out of date you are with
 	the current state of the core FreeBSD development. There is a special
 	on-going release of FreeBSD known as <quote>FreeBSD-current</quote>
 	which is made available in a variety of ways for the convenience of
 	developers working actively on the system. See <ulink url="
 	../../books/handbook/current-stable.html">The
 	FreeBSD Handbook</ulink> for more
 	information about getting and using FreeBSD-current.</para>
 	  
       <para>Working from older sources unfortunately means that your changes
 	may sometimes be too obsolete or too divergent for easy re-integration
 	into FreeBSD.  Chances of this can be minimized somewhat by
 	subscribing to the &a.announce; and the &a.current; lists, where
 	discussions on the current state of the system take place.</para>
 	  
       <para>Assuming that you can manage to secure fairly up-to-date sources
 	to base your changes on, the next step is to produce a set of diffs to
 	send to the FreeBSD maintainers.  This is done with the &man.diff.1;
 	command, with the <quote>context diff</quote> form
 	being preferred.  For example:</para>
       
       <indexterm>
         <primary><command>diff</command></primary>
       </indexterm>
       <para>
 	<screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen>
 
 	or
 
 	<screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen>
 	    
 	would generate such a set of context diffs for the given source file
 	or directory hierarchy.  See the man page for &man.diff.1; for more
 	details.</para>
 	  
       <para>Once you have a set of diffs (which you may test with the
 	  &man.patch.1; command), you should submit them for inclusion with
 	FreeBSD.  Use the &man.send-pr.1; program as described in <link
 	  linkend="contrib-general">Bug Reports and General Commentary</link>.
 	<emphasis>Do not</emphasis> just send the diffs to the &a.hackers; or
 	they will get lost! We greatly appreciate your submission (this is a
 	volunteer project!); because we are busy, we may not be able to
 	address it immediately, but it will remain in the PR database until we
 	do.  Indicate your submission by including <literal>[PATCH]</literal>
 	in the synopsis of the report.</para>
 
       <indexterm>
         <primary><command>uuencode</command></primary>
       </indexterm>
       <para>If you feel it appropriate (e.g. you have added, deleted, or
 	renamed files), bundle your changes into a <command>tar</command> file
 	and run the &man.uuencode.1; program on it.  Shar archives are also
 	welcome.</para>
 
       <para>If your change is of a potentially sensitive nature, e.g. you are
 	unsure of copyright issues governing its further distribution or you
 	are simply not ready to release it without a tighter review first,
 	then you should send it to &a.core; directly rather than submitting it
 	with &man.send-pr.1;.  The core mailing list reaches a much smaller
 	group of people who do much of the day-to-day work on FreeBSD.  Note
 	that this group is also <emphasis>very busy</emphasis> and so you
 	  should only send mail to them where it is truly necessary.</para>
 	  
       <para>Please refer to &man.intro.9; and &man.style.9; style for
 	some information on coding style. We would appreciate it if you
         were at least aware of this information before submitting
 	code.</para>
     </sect2>
     
     <sect2>
       <title>New Code or Major Value-Added Packages</title>
       
       <para>In the case of a significant contribution of a large body
 	work, or the addition of an important new feature to FreeBSD, it
 	becomes almost always necessary to either send changes as uuencoded
 	tar files or upload them to a web or FTP site for other people to
 	access.  If you do not have access to a web or FTP site, ask on an
 	appropriate FreeBSD mailing list for someone to host the changes for
 	you.</para>
 	  
       <para>When working with large amounts of code, the touchy subject of
 	copyrights also invariably comes up.  Acceptable copyrights for code
 	included in FreeBSD are:</para>
 	  
       <orderedlist>
   <indexterm><primary>BSD copyright</primary></indexterm>
 	<listitem>
 	  <para>The BSD copyright.  This copyright is most preferred due to
 	    its <quote>no strings attached</quote> nature and general
 	    attractiveness to commercial enterprises.  Far from discouraging
 	    such commercial use, the FreeBSD Project actively encourages such
 	    participation by commercial interests who might eventually be
 	    inclined to invest something of their own into FreeBSD.</para>
 	</listitem>
 
   <indexterm><primary>GPL</primary><see>GNU General Public License</see></indexterm>
   <indexterm><primary>GNU General Public License</primary></indexterm>
 	<listitem>
 	  <para>The GNU General Public License, or <quote>GPL</quote>.
 	    This license is not quite as popular with us due to the amount
 	    of extra effort demanded of anyone using the code for
 	    commercial purposes, but given the sheer quantity of GPL'd code
 	    we currently require (compiler, assembler, text formatter, etc)
 	    it would be silly to refuse additional contributions under this
 	    license.  Code under the GPL also goes into a different part of
 	    the tree, that being <filename>/sys/gnu</filename> or
 	    <filename>/usr/src/gnu</filename>, and is therefore easily
 	    identifiable to anyone for whom the GPL presents a
 	    problem.</para>
 	</listitem>
       </orderedlist>
       
       <para>Contributions coming under any other type of copyright must be
 	carefully reviewed before their inclusion into FreeBSD will be
 	considered.  Contributions for which particularly restrictive
 	commercial copyrights apply are generally rejected, though the authors
 	are always encouraged to make such changes available through their own
 	channels.</para>
 	  
       <para>To place a <quote>BSD-style</quote> copyright on your work, include
 	the following text at the very beginning of every source code file you
 	wish to protect, replacing the text between the <literal>%%</literal>
 	with the appropriate information.</para>
 	    
       <programlisting>Copyright (c) %%proper_years_here%%
         %%your_name_here%%, %%your_state%%  %%your_zip%%.  
 	All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer as
    the first lines of this file unmodified.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
 
 THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT,
 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 	      
         &#36;Id&#36;</programlisting>
 
       <para>For your convenience, a copy of this text can be found in
 	<filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para>
     </sect2>
     
     <sect2>
       <title>Money, Hardware or Internet Access</title>
       
       <para>We are always very happy to accept donations to further the cause
 	of the FreeBSD Project and, in a volunteer effort like ours, a little
 	can go a long way! Donations of hardware are also very important to
 	expanding our list of supported peripherals since we generally lack
 	the funds to buy such items ourselves.</para>
 	  
       <sect3>
 	<title><anchor id="donations">Donating Funds</title>
 
 	<para>The FreeBSD Foundation is a non-profit, tax-exempt
 	  foundation established to further the goals of the FreeBSD
 	  Project.  As a 501(c)3 entity, the Foundation is generally
 	  exempt from US federal income tax as well as Colorado
 	  State income tax.  Donations to a tax-exempt entity are
 	  often deductible from taxable federal income.</para>
 
 	<para>Donations may be sent in check form to:
 	  <address>
 	    The FreeBSD Foundation
 	    <street>7321 Brockway Dr.</street>
 	    <city>Boulder</city>, <state>CO</state> <postcode>80303</postcode>
 	    <country>USA</country>
 	  </address>
 	</para>
 
 	<para>The FreeBSD Foundation is now able to accept donations
 	  through the web with PayPal.  To place a donation, please
 	  visit the Foundation <ulink
 	  url="http://www.freebsdfoundation.org">web
 	  site</ulink>.</para>
 
 	<para>More information about the FreeBSD Foundation can be
 	  found in <ulink
 	  url="http://people.freebsd.org/~jdp/foundation/announcement.html">The
 	  FreeBSD Foundation -- an Introduction</ulink>.  To contact
 	  the Foundation by email, write to
 	  <email>bod@FreeBSDFoundation.org</email>.</para>
       </sect3>
       
       <sect3>
 	<title>Donating Hardware</title>
   <indexterm><primary>donations</primary></indexterm>
 
 	<para>Donations of hardware in any of the 3 following categories are
 	  also gladly accepted by the FreeBSD Project:</para>
 	    
 	<itemizedlist>
 	  <listitem>
 	    <para>General purpose hardware such as disk drives, memory or
 	      complete systems should be sent to the FreeBSD, Inc. address
 	      listed in the <emphasis>donating funds</emphasis>
 	      section.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>Hardware for which ongoing compliance testing is desired.
 	      We are currently trying to put together a testing lab of all
 	      components that FreeBSD supports so that proper regression
 	      testing can be done with each new release.  We are still lacking
 	      many important pieces (network cards, motherboards, etc) and if
 	      you would like to make such a donation, please contact &a.dg;
 	      for information on which items are still required.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>Hardware currently unsupported by FreeBSD for which you
 	      would like to see such support added.  Please contact the
 	      &a.core; before sending such items as we will need to find a
 	      developer willing to take on the task before we can accept
 	      delivery of new hardware.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Donating Internet Access</title>
 
 	<para>We can always use new mirror sites for FTP, WWW or
 	  <command>cvsup</command>.  If you would like to be such a mirror,
 	  please contact the &a.hubs; for more information.</para>
       </sect3>
     </sect2>
   </sect1>
   
 </article>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      End:
 -->
diff --git a/en_US.ISO8859-1/articles/contributors/article.sgml b/en_US.ISO8859-1/articles/contributors/article.sgml
index 2636cb2975..c1bd0f7aa9 100644
--- a/en_US.ISO8859-1/articles/contributors/article.sgml
+++ b/en_US.ISO8859-1/articles/contributors/article.sgml
@@ -1,7330 +1,7330 @@
 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
 <!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//EN">
 %teams;
 <!ENTITY % not.published "IGNORE">
 ]>
 
 <!--
 	NOTE TO NEW COMMITERS: Core and committers lists are sorted in
 	alphabetical order by last name. Please keep in mind that fact while
 	adding your entitity to the list of developers.
 -->
 
 <article>
   <articleinfo>
     <title>Contributors to FreeBSD</title>
 
     <pubdate>$FreeBSD$</pubdate>
 
     <abstract>
       <para>This article lists individuals and organizations who have
       made a contribution to FreeBSD.</para>
     </abstract>
   </articleinfo>
 
   <sect1 id="donors">
     <title>Donors Gallery</title>
 
     <para>The FreeBSD Project is indebted to the following donors and would
       like to publicly thank them here!</para>
 
     <itemizedlist>
       <listitem>
 	<para><emphasis>Contributors to the central server
 	    project:</emphasis></para>
 
 	<para>The following individuals and businesses made it possible for
 	  the FreeBSD Project to build a new central server machine to
 	  eventually replace <hostid role="fqdn">freefall.FreeBSD.org</hostid>
 	  by donating the following items:</para>
 
 	<itemizedlist>
 	  <listitem>
-	    <para>&a.mbarkah and his employer, <ulink
+	    <para>&a.mbarkah; and his employer, <ulink
 		url="http://www.hemi.com/"> Hemisphere Online</ulink>,
 		donated a <emphasis>Pentium Pro (P6) 200MHz CPU</emphasis>
 	    </para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.asacomputers.com/">ASA
 		Computers</ulink> donated a <emphasis>Tyan 1662
 		motherboard</emphasis>.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Joe McGuckin <email>joe@via.net</email> of <ulink
 		url="http://www.via.net/">ViaNet Communications</ulink> donated
 	      a <emphasis>Kingston ethernet controller.</emphasis></para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Jack O'Neill <email>jack@diamond.xtalwind.net</email>
 	      donated an <emphasis>NCR 53C875 SCSI controller
 		card</emphasis>.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Ulf Zimmermann <email>ulf@Alameda.net</email> of <ulink
 		url="http://www.Alameda.net/">Alameda Networks</ulink> donated
 	      <emphasis>128MB of memory</emphasis>, a <emphasis>4 Gb disk
 		drive and the case.</emphasis></para>
 	  </listitem>
 	</itemizedlist>
       </listitem>
 
       <listitem>
 	<para><emphasis>Direct funding:</emphasis></para>
 
 	<para>The following individuals and businesses have generously
 	  contributed direct funding to the project:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>Annelise Anderson
 	      <email>ANDRSN@HOOVER.STANFORD.EDU</email></para>
 	  </listitem>
 
 	  <listitem>
 	    <para>&a.dillon;</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.bluemountain.com/">Blue Mountain
 		Arts</ulink></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.epilogue.com/">Epilogue Technology
 		Corporation</ulink></para>
 	  </listitem>
 
 	  <listitem>
 	    <para>&a.sef;</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.gta.com/">Global Technology
 		Associates, Inc</ulink></para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Don Scott Wilde</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Gianmarco Giovannelli
 	      <email>gmarco@masternet.it</email></para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Josef C. Grosch <email>joeg@truenorth.org</email></para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Robert T. Morris</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>&a.chuckr;</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Kenneth P. Stox <email>ken@stox.sa.enteract.com</email> of
 	      <ulink url="http://www.imagescape.com/">Imaginary Landscape,
 		LLC.</ulink></para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Dmitry S. Kohmanyuk <email>dk@dog.farm.org</email></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.cdrom.co.jp/">Laser5</ulink> of Japan
 	      (a portion of the profits from sales of their various FreeBSD
 	      CDROMs).</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.mmjp.or.jp/fuki/">Fuki Shuppan
 		Publishing Co.</ulink> donated a portion of their profits from
 	      <emphasis>Hajimete no FreeBSD</emphasis> (FreeBSD, Getting
 	      started) to the FreeBSD and XFree86 projects.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.ascii.co.jp/">ASCII Corp.</ulink>
 	      donated a portion of their profits from several FreeBSD-related
 	      books to the FreeBSD project.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.yokogawa.co.jp/">Yokogawa Electric
 		Corp</ulink> has generously donated significant funding to the
 	      FreeBSD project.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.buffnet.net/">BuffNET</ulink></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.pacificsolutions.com/">Pacific
 		Solutions</ulink></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.siemens.de/">Siemens AG</ulink>
             via Andre Albsmeier
             <email>andre.albsmeier@mchp.siemens.de</email></para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Chris Silva <email>ras@interaccess.com</email></para>
 	  </listitem>
 
 	</itemizedlist>
       </listitem>
 
       <listitem>
 	<para><emphasis>Hardware contributors:</emphasis></para>
 
 	<para>The following individuals and businesses have generously
 	  contributed hardware for testing and device driver
 	  development/support:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>BSDi for providing the Pentium P5-90 and
 	      486/DX2-66 EISA/VL systems that are being used for our
 	      development work, to say nothing of the network access and other
 	      donations of hardware resources.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.compaq.com">Compaq</ulink>
 	      donated 3 AlphaStation DS10s to the FreeBSD Project.
 	      These machines are currently being used for toolchain
 	      and release engineering work on the FreeBSD / Alpha
 	      platform.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>TRW Financial Systems, Inc. provided 130 PCs, three 68 GB
 	      file servers, twelve Ethernets, two routers and an ATM switch for
 	      debugging the diskless code.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Dermot McDonnell donated the Toshiba XM3401B CDROM drive
 	      currently used in freefall.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Chuck Robey <email>chuckr@glue.umd.edu</email> contributed
 	      his floppy tape streamer for experimental work.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Larry Altneu <email>larry@ALR.COM</email>, and &a.wilko;,
 	      provided Wangtek and Archive QIC-02 tape drives in order to
 	      improve the <devicename>wt</devicename> driver.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Ernst Winter <email>ewinter@lobo.muc.de</email> contributed
 	      a 2.88 MB floppy drive to the project.  This will hopefully
 	      increase the pressure for rewriting the floppy disk driver.
 	    </para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.tekram.com/">Tekram
 		Technologies</ulink> sent one each of their DC-390, DC-390U
 	      and DC-390F FAST and ULTRA SCSI host adapter cards for
 	      regression testing of the NCR and AMD drivers with their cards.
 	      They are also to be applauded for making driver sources for free
 	      operating systems available from their  FTP server <ulink
 		url="ftp://ftp.tekram.com/scsi/FreeBSD/">ftp://ftp.tekram.com/scsi/FreeBSD/</ulink>.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Larry M. Augustin contributed not only a
 	      Symbios Sym8751S SCSI card, but also a set of data books,
 	      including one about the forthcoming Sym53c895 chip with Ultra-2
 	      and LVD support, and the latest programming manual with
 	      information on how to safely use the advanced features of the
 	      latest  Symbios SCSI chips. Thanks a lot!</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Christoph Kukulies <email>kuku@FreeBSD.org</email> donated
 	      an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver
 	      development.</para>
 	  </listitem>
 	</itemizedlist>
       </listitem>
 
       <listitem>
 	<para><emphasis>Special contributors:</emphasis></para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><ulink url="http://www.osd.bsdi.com/">BSDi</ulink> (formerly Walnut Creek CDROM)
 	      has donated almost more than we can say (see the History
 	      section of the <ulink url="../../books/handbook/index.html">FreeBSD Handbook</ulink> for more details).
 	      In particular, we would like to thank them for the original
 	      hardware used for <hostid
 		role="fqdn">freefall.FreeBSD.org</hostid>, our primary
 	      development machine, and for <hostid
 		role="fqdn">thud.FreeBSD.org</hostid>, a testing and build
 	      box.  We are also indebted to them for funding various
 	      contributors over the years and providing us with unrestricted
 	      use of their T1 connection to the Internet.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The <ulink url="http://www.interface-business.de/">interface
 		business GmbH, Dresden</ulink> has been patiently supporting
 	      &a.joerg; who has often preferred FreeBSD work over paid work, and
 	      used to fall back to their (quite expensive) EUnet Internet
 	      connection whenever his private connection became too slow or
 	      flaky to work with it...</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.bsdi.com/">Berkeley Software Design,
 		Inc.</ulink> has contributed their DOS emulator code to the
 	      remaining BSD world, which is used in the
 	      <emphasis>doscmd</emphasis> command.</para>
 	  </listitem>
 	</itemizedlist>
       </listitem>
     </itemizedlist>
   </sect1>
 
 <!--- XXX top level "staff" group vs additional contributors
   <title>FreeBSD Project Staff</title>
 
   <para>The FreeBSD Project is managed and operated by the following groups of
     people:</para>
 -->
 
   <sect1 id="staff-core">
     <title>The FreeBSD Core Team</title>
 
     <para>The FreeBSD core team constitutes the project's <quote>Board of
       Directors</quote>, responsible for deciding the project's overall goals
       and direction as well as managing <link linkend="staff-who">specific
 	areas</link> of the FreeBSD project landscape.</para>
 
     <para>(in alphabetical order by last name):</para>
 
     <itemizedlist>
       <listitem>
 	<para>&a.dg;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jkh;</para>
       </listitem>
 
       <listitem>
 	<para>&a.grog;</para>
       </listitem>
 
       <listitem>
 	<para>&a.imp;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dfr;</para>
       </listitem>
 
       <listitem>
 	<para>&a.msmith;</para>
       </listitem>
 
       <listitem>
 	<para>&a.rwatson;</para>
       </listitem>
 
       <listitem>
 	<para>&a.peter;</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
 <!--
 	This list is sorted by last name, not by entity or tenure.
 -->
 
   <sect1 id="staff-committers">
     <title>The FreeBSD Developers</title>
 
     <para>These are the people who have commit privileges and do the
       engineering work on the FreeBSD source tree.  All core team members are
       also developers.</para>
 
     <para>(in alphabetical order by last name):</para>
 
     <itemizedlist>
       <listitem>
 	<para>&a.akiyama;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jmas;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ambrisko;</para>
       </listitem>
 
       <listitem>
 	<para>&a.will;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ugen;</para>
       </listitem>
 
       <listitem>
 	<para>&a.toshi;</para>
       </listitem>
 
       <listitem>
 	<para>&a.babkin;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dbaker;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jhb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dmlb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mike;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mbarkah;</para>
       </listitem>
 
       <listitem>
 	<para>&a.rvb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dougb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.tobez;</para>
       </listitem>
 
       <listitem>
 	<para>&a.stb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.pb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.abial;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.nbm;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mbr;</para>
       </listitem>
 
       <listitem>
 	<para>&a.torstenb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jmb;</para>
       </listitem>
 
       <listitem>
 	<para>&a.wilko;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jake;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dburr;</para>
       </listitem>
 
       <listitem>
 	<para>&a.adrian;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dwcjr;</para>
       </listitem>
 
       <listitem>
 	<para>&a.charnier;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jon;</para>
       </listitem>
 
       <listitem>
 	<para>&a.luoqi;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ache;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ejc;</para>
       </listitem>
 
       <listitem>
 	<para>&a.kjc;</para>
       </listitem>
 
       <listitem>
 	<para>&a.cjh;</para>
       </listitem>
 
       <listitem>
 	<para>&a.cjc;</para>
       </listitem>
 
       <listitem>
         <para>&a.nik;</para>
       </listitem>
 
       <listitem>
 	<para>&a.archie;</para>
       </listitem>
 
       <listitem>
 	<para>&a.chris;</para>
       </listitem>
 
       <listitem>
 	<para>&a.alc;</para>
       </listitem>
 
       <listitem>
 	<para>&a.cracauer;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dec;</para>
       </listitem>
 
       <listitem>
 	<para>&a.pds;</para>
       </listitem>
 
       <listitem>
 	<para>&a.adam;</para>
       </listitem>
 
       <listitem>
         <para>&a.davidc;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ceri;</para>
       </listitem>
 
       <listitem>
 	<para>&a.brooks;</para>
       </listitem>
 
       <listitem>
 	<para>&a.bsd;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jwd;</para>
       </listitem>
 
       <listitem>
 	<para>&a.pdeuskar;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dillon;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mdodd;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dd;</para>
       </listitem>
 
       <listitem>
 	<para>&a.iedowse;</para>
       </listitem>
 
       <listitem>
 	<para>&a.robert;</para>
       </listitem>
 
       <listitem>
 	<para>&a.gad;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dufault;</para>
       </listitem>
 
       <listitem>
 	<para>&a.uhclem;</para>
       </listitem>
 
       <listitem>
 	<para>&a.tegge;</para>
       </listitem>
 
       <listitem>
 	<para>&a.deischen;</para>
       </listitem>
 
       <listitem>
 	<para>&a.eivind;</para>
       </listitem>
 
       <listitem>
 	<para>&a.julian;</para>
       </listitem>
 
       <listitem>
 	<para>&a.rse;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ue;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ru;</para>
       </listitem>
 
       <listitem>
 	<para>&a.se;</para>
       </listitem>
 
       <listitem>
 	<para>&a.bde;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jasone;</para>
       </listitem>
 
       <listitem>
 	<para>&a.sef;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jedgar;</para>
       </listitem>
 
       <listitem>
 	<para>&a.green;</para>
       </listitem>
 
       <listitem>
 	<para>&a.fenner;</para>
       </listitem>
 
       <listitem>
 	<para>&a.lioux;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jfieber;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jfitz;</para>
       </listitem>
 
       <listitem>
 	<para>&a.petef;</para>
       </listitem>
 
       <listitem>
 	<para>&a.scrappy;</para>
       </listitem>
 
       <listitem>
 	<para>&a.lars;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dirk;</para>
       </listitem>
 
       <listitem>
 	<para>&a.sf;</para>
       </listitem>
 
       <listitem>
 	<para>&a.shige;</para>
       </listitem>
 
       <listitem>
 	<para>&a.billf;</para>
       </listitem>
 
       <listitem>
 	<para>&a.furuta;</para>
       </listitem>
 
       <listitem>
 	<para>&a.gallatin;</para>
       </listitem>
 
       <listitem>
 	<para>&a.patrick;</para>
       </listitem>
 
       <listitem>
 	<para>&a.tg;</para>
       </listitem>
 
       <listitem>
 	<para>&a.gibbs;</para>
       </listitem>
 
       <listitem>
 	<para>&a.brandon;</para>
       </listitem>
 
       <listitem>
 	<para>&a.gioria;</para>
       </listitem>
 
       <listitem>
 	<para>&a.graichen;</para>
       </listitem>
 
       <listitem>
 	<para>&a.cg;</para>
       </listitem>
 
       <listitem>
 	<para>&a.rgrimes;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jmg;</para>
       </listitem>
 
       <listitem>
 	<para>&a.znerd;</para>
       </listitem>
 
       <listitem>
 	<para>&a.hanai;</para>
       </listitem>
 
       <listitem>
 	<para>&a.roger;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mharo;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dannyboy;</para>
       </listitem>
 
       <listitem>
 	<para>&a.thepish;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jhay;</para>
       </listitem>
 
       <listitem>
 	<para>&a.sheldonh;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mikeh;</para>
       </listitem>
 
       <listitem>
 	<para>&a.helbig;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ghelmer;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mux;</para>
       </listitem>
 
       <listitem>
 	<para>&a.erich;</para>
       </listitem>
 
       <listitem>
 	<para>&a.chm;</para>
       </listitem>
 
       <listitem>
 	<para>&a.nhibma;</para>
       </listitem>
 
       <listitem>
 	<para>&a.flathill;</para>
       </listitem>
 
       <listitem>
 	<para>&a.orion;</para>
       </listitem>
 
       <listitem>
 	<para>&a.pho;</para>
       </listitem>
 
       <listitem>
 	<para>&a.horikawa;</para>
       </listitem>
 
       <listitem>
 	<para>&a.hosokawa;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jeh;</para>
       </listitem>
 
       <listitem>
 	<para>&a.hsu;</para>
       </listitem>
 
       <listitem>
 	<para>&a.foxfair;</para>
       </listitem>
 
       <listitem>
 	<para>&a.tom;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mph;</para>
       </listitem>
 
       <listitem>
 	<para>&a.imura;</para>
       </listitem>
 
       <listitem>
 	<para>&a.shin;</para>
       </listitem>
 
       <listitem>
 	<para>&a.itojun;</para>
       </listitem>
 
       <listitem>
 	<para>&a.iwasaki;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mjacob;</para>
       </listitem>
 
       <listitem>
 	<para>&a.keith;</para>
       </listitem>
 
       <listitem>
 	<para>&a.gj;</para>
       </listitem>
 
       <listitem>
 	<para>&a.trevor;</para>
       </listitem>
 
       <listitem>
 	<para>&a.phk;</para>
       </listitem>
 
       <listitem>
 	<para>&a.tomsoft;</para>
       </listitem>
 
       <listitem>
 	<para>&a.joe;</para>
       </listitem>
 
       <listitem>
 	<para>&a.cokane;</para>
       </listitem>
 
       <listitem>
 	<para>&a.kato;</para>
       </listitem>
 
       <listitem>
 	<para>&a.kris;</para>
       </listitem>
 
       <listitem>
 	<para>&a.keramida;</para>
       </listitem>
 
       <listitem>
 	<para>&a.fjoe;</para>
       </listitem>
 
       <listitem>
 	<para>&a.kiri;</para>
       </listitem>
 
       <listitem>
 	<para>&a.andreas;</para>
       </listitem>
 
       <listitem>
 	<para>&a.lkoeller;</para>
       </listitem>
 
       <listitem>
 	<para>&a.motoyuki;</para>
       </listitem>
 
       <listitem>
 	<para>&a.maxim;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jkoshy;</para>
       </listitem>
 
       <listitem>
 	<para>&a.kuriyama;</para>
       </listitem>
 
       <listitem>
 	<para>&a.alex;</para>
       </listitem>
 
       <listitem>
         <para>&a.chern;</para>
       </listitem>
 
       <listitem>
 	<para>&a.reg;</para>
       </listitem>
 
       <listitem>
 	<para>&a.netchild;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jlemon;</para>
       </listitem>
 
       <listitem>
 	<para>&a.truckman;</para>
       </listitem>
 
       <listitem>
         <para>&a.pat;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ijliao;</para>
       </listitem>
 
       <listitem>
 	<para>&a.lile;</para>
       </listitem>
 
       <listitem>
 	<para>&a.clive;</para>
       </listitem>
 
       <listitem>
 	<para>&a.kevlo;</para>
       </listitem>
 
       <listitem>
 	<para>&a.scottl;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ade;</para>
       </listitem>
 
       <listitem>
         <para>&a.mwlucas;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jmacd;</para>
       </listitem>
 
       <listitem>
 	<para>&a.smace;</para>
       </listitem>
 
       <listitem>
 	<para>&a.bmah;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jmallett;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dwmalone;</para>
       </listitem>
 
       <listitem>
 	<para>&a.nobutaka;</para>
       </listitem>
 
       <listitem>
 	<para>&a.matusita;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mckay;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mckusick;</para>
       </listitem>
 
       <listitem>
 	<para>&a.eric;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ken;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dinoex;</para>
       </listitem>
 
       <listitem>
 	<para>&a.hm;</para>
       </listitem>
 
       <listitem>
 	<para>&a.sanpei;</para>
       </listitem>
 
       <listitem>
 	<para>&a.bmilekic;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mita;</para>
       </listitem>
 
       <listitem>
 	<para>&a.non;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jim;</para>
       </listitem>
 
       <listitem>
 	<para>&a.marcel;</para>
       </listitem>
 
       <listitem>
 	<para>&a.amorita;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dan;</para>
       </listitem>
 
       <listitem>
 	<para>&a.tmm;</para>
       </listitem>
 
       <listitem>
 	<para>&a.amurai;</para>
       </listitem>
 
       <listitem>
 	<para>&a.markm;</para>
       </listitem>
 
       <listitem>
 	<para>&a.rich;</para>
       </listitem>
 
       <listitem>
 	<para>&a.knu;</para>
       </listitem>
 
       <listitem>
 	<para>&a.nakai;</para>
       </listitem>
 
       <listitem>
 	<para>&a.max;</para>
       </listitem>
 
       <listitem>
 	<para>&a.yoichi;</para>
       </listitem>
 
       <listitem>
 	<para>&a.newton;</para>
       </listitem>
 
       <listitem>
         <para>&a.anders;</para>
       </listitem>
 
       <listitem>
 	<para>&a.rnordier;</para>
       </listitem>
 
       <listitem>
 	<para>&a.davidn;</para>
       </listitem>
 
       <listitem>
 	<para>&a.obrien;</para>
       </listitem>
 
       <listitem>
 	<para>&a.danny;</para>
       </listitem>
 
       <listitem>
 	<para>&a.okazaki;</para>
       </listitem>
 
       <listitem>
 	<para>&a.olgeni;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ljo;</para>
       </listitem>
 
       <listitem>
 	<para>&a.onoe;</para>
       </listitem>
 
       <listitem>
 	<para>&a.marko;</para>
       </listitem>
 
       <listitem>
 	<para>&a.gpalmer;</para>
       </listitem>
 
       <listitem>
 	<para>&a.fsmp;</para>
       </listitem>
 
       <listitem>
 	<para>&a.smpatel;</para>
       </listitem>
 
       <listitem>
 	<para>&a.cp;</para>
       </listitem>
 
       <listitem>
 	<para>&a.wpaul;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mp;</para>
       </listitem>
 
       <listitem>
 	<para>&a.alfred;</para>
       </listitem>
 
       <listitem>
         <para>&a.roam;</para>
       </listitem>
 
       <listitem>
 	<para>&a.wes;</para>
       </listitem>
 
       <listitem>
 	<para>&a.cpiazza;</para>
       </listitem>
 
       <listitem>
 	<para>&a.pirzyk;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jdp;</para>
       </listitem>
 
       <listitem>
 	<para>&a.bp;</para>
       </listitem>
 
       <listitem>
 	<para>&a.rpratt;</para>
       </listitem>
 
       <listitem>
 	<para>&a.steve;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mpp;</para>
       </listitem>
 
       <listitem>
 	<para>&a.markp;</para>
       </listitem>
 
       <listitem>
 	<para>&a.darrenr;</para>
       </listitem>
 
       <listitem>
 	<para>&a.csgr;</para>
       </listitem>
 
       <listitem>
 	<para>&a.greid;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mr;</para>
       </listitem>
 
       <listitem>
         <para>&a.arr;</para>
       </listitem>
 
       <listitem>
 	<para>&a.martin;</para>
       </listitem>
 
       <listitem>
 	<para>&a.benno;</para>
       </listitem>
 
       <listitem>
 	<para>&a.luigi;</para>
       </listitem>
 
       <listitem>
 	<para>&a.paul;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jeff;</para>
       </listitem>
 
       <listitem>
 	<para>&a.roberto;</para>
       </listitem>
 
       <listitem>
 	<para>&a.chuckr;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jesusr;</para>
       </listitem>
 
       <listitem>
 	<para>&a.guido;</para>
       </listitem>
 
       <listitem>
 	<para>&a.groudier;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dima;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ps;</para>
       </listitem>
 
       <listitem>
 	<para>&a.sada;</para>
       </listitem>
 
       <listitem>
 	<para>&a.hrs;</para>
       </listitem>
 
       <listitem>
 	<para>&a.wsanchez;</para>
       </listitem>
 
       <listitem>
 	<para>&a.nsayer;</para>
       </listitem>
 
       <listitem>
 	<para>&a.sos;</para>
       </listitem>
 
       <listitem>
 	<para>&a.wosch;</para>
       </listitem>
 
       <listitem>
 	<para>&a.cy;</para>
       </listitem>
 
       <listitem>
 	<para>&a.schweikh;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dick;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jseger;</para>
       </listitem>
 
       <listitem>
 	<para>&a.gshapiro;</para>
       </listitem>
 
       <listitem>
 	<para>&a.shiba;</para>
       </listitem>
 
       <listitem>
 	<para>&a.tshiozak;</para>
       </listitem>
 
       <listitem>
 	<para>&a.simokawa;</para>
       </listitem>
 
       <listitem>
 	<para>&a.vanilla;</para>
       </listitem>
 
       <listitem>
 	<para>&a.silby;</para>
       </listitem>
 
       <listitem>
 	<para>&a.shafeeq;</para>
       </listitem>
 
       <listitem>
 	<para>&a.demon;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jesper;</para>
       </listitem>
 
       <listitem>
 	<para>&a.skv;</para>
       </listitem>
 
       <listitem>
 	<para>&a.msmith;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ben;</para>
       </listitem>
 
       <listitem>
 	<para>&a.nsouch;</para>
       </listitem>
 
       <listitem>
 	<para>&a.des;</para>
       </listitem>
 
       <listitem>
 	<para>&a.sobomax;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dcs;</para>
       </listitem>
 
       <listitem>
 	<para>&a.brian;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mks;</para>
       </listitem>
 
       <listitem>
 	<para>&a.stark;</para>
       </listitem>
 
       <listitem>
 	<para>&a.murray;</para>
       </listitem>
 
       <listitem>
 	<para>&a.sumikawa;</para>
       </listitem>
 
       <listitem>
 	<para>&a.gsutter;</para>
       </listitem>
 
       <listitem>
 	<para>&a.unfurl;</para>
       </listitem>
 
       <listitem>
 	<para>&a.nyan;</para>
       </listitem>
 
       <listitem>
 	<para>&a.tanimura;</para>
       </listitem>
 
       <listitem>
 	<para>&a.taoka;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mtaylor;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dt;</para>
       </listitem>
 
       <listitem>
 	<para>&a.mi;</para>
       </listitem>
 
       <listitem>
 	<para>&a.yar;</para>
       </listitem>
 
       <listitem>
 	<para>&a.cwt;</para>
       </listitem>
 
       <listitem>
 	<para>&a.pst;</para>
       </listitem>
 
       <listitem>
 	<para>&a.uch;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ume;</para>
       </listitem>
 
       <listitem>
 	<para>&a.semenu;</para>
       </listitem>
 
       <listitem>
 	<para>&a.rv;</para>
       </listitem>
 
       <listitem>
 	<para>&a.hoek;</para>
       </listitem>
 
       <listitem>
 	<para>&a.logo;</para>
       </listitem>
 
       <listitem>
 	<para>&a.nectar;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jayanth;</para>
       </listitem>
 
       <listitem>
         <para>&a.wjv;</para>
       </listitem>
 
       <listitem>
         <para>&a.bean;</para>
       </listitem>
 
       <listitem>
 	<para>&a.swallace;</para>
       </listitem>
 
       <listitem>
 	<para>&a.ticso;</para>
       </listitem>
 
       <listitem>
 	<para>&a.takawata;</para>
       </listitem>
 
       <listitem>
 	<para>&a.naddy;</para>
       </listitem>
 
       <listitem>
 	<para>&a.assar;</para>
       </listitem>
 
       <listitem>
 	<para>&a.dwhite;</para>
       </listitem>
 
       <listitem>
 	<para>&a.nate;</para>
       </listitem>
 
       <listitem>
 	<para>&a.wollman;</para>
       </listitem>
 
       <listitem>
         <para>&a.keichii;</para>
       </listitem>
 
       <listitem>
 	<para>&a.joerg;</para>
       </listitem>
 
       <listitem>
 	<para>&a.kbyanc;</para>
       </listitem>
 
       <listitem>
 	<para>&a.yokota;</para>
       </listitem>
 
       <listitem>
 	<para>&a.andy;</para>
       </listitem>
 
       <listitem>
 	<para>&a.zarzycki;</para>
       </listitem>
 
       <listitem>
 	<para>&a.phantom;</para>
       </listitem>
 
       <listitem>
 	<para>&a.jmz;</para>
       </listitem>
 
     </itemizedlist>
   </sect1>
 
   <sect1 id="staff-doc">
 
 
     <title>The FreeBSD Documentation Project</title>
 
     <para>The <ulink url="../../../../docproj/index.html">FreeBSD
 	Documentation Project</ulink> is responsible for a number of different
       services, each service being run by an individual and his
       <emphasis>deputies</emphasis> (if any):</para>
 
     <variablelist>
       <varlistentry>
 	<term>Documentation Project Architect</term>
 
 	<listitem>
 	  <para>&a.nik;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Handbook Editor</term>
 
 	<listitem>
 	  <para>&a.jim;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>FAQ Editor</term>
 
 	<listitem>
 	  <para>&a.faq;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>News Editor</term>
 
 	<listitem>
 	  <para>&a.jim;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>In the Press Editor</term>
 
 	<listitem>
 	  <para>&a.jkoshy;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>FreeBSD Really-Quick NewsLetter Editor</term>
 
 	<listitem>
 	  <para>Chris Coleman <email>chrisc@vmunix.com</email></para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Gallery Editor</term>
 
 	<listitem>
 	  <para>&a.phantom;</para>
 	</listitem>
       </varlistentry>
 
 <![ %not.published; [
 
       <varlistentry>
 	<term>Commercial Editor</term>
 
 	<listitem>
 	  <para>nobody yet</para>
 	</listitem>
       </varlistentry>
 
 ]]>
 
       <varlistentry>
 	<term>User Groups Editor</term>
 
 	<listitem>
 	  <para>&a.grog;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>FreeBSD Projects and Tasklist Editor</term>
 
 	<listitem>
 	  <para>&a.asmodai;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>FreeBSD Java Project</term>
 
 	<listitem>
 	  <para>&a.patrick;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>LinuxDoc to DocBook conversion</term>
 
 	<listitem>
 	  <para>&a.nik;</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
   <sect1 id="staff-who">
     <title>Who is Responsible for What</title>
 
     <variablelist>
       <varlistentry>
 	<term><ulink
 	    url="../../../../docproj/index.html">Documentation
 	    Project Manager</ulink></term>
 
 	<listitem>
 	  <para>&a.nik;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>CVSup Mirror Site Coordinator</term>
 
 	<listitem>
 	  <para>&a.jdp;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Internationalization</term>
 
 	<listitem>
 	  <para>&a.ache;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Postmaster</term>
 
 	<listitem>
 	  <para>&a.jmb;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><ulink url="../releng/index.html">Release
 		Coordination</ulink></term>
 
 	<listitem>
 	  <para>&a.re; headed by &a.murray;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Public Relations &amp; Corporate Liaison</term>
 
 	<listitem>
 	  <para>&a.jkh;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><ulink url="../../../../security/index.html">Security
 	    Officers</ulink></term>
 
 	<listitem>
 	  <para>&a.security-officer; headed by &a.nectar;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><ulink url="../../../../support.html#cvs">Source
 	    Repository Managers</ulink></term>
 
 	<listitem>
 	  <para>Principal: &a.peter;</para>
 
 	  <para>Assistants: &a.markm;, &a.joe;</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
         <term>Website Management</term>
 
         <listitem>
           <para>&a.www;</para>
         </listitem>
       </varlistentry>
           
       <varlistentry>
 	<term><ulink url="../../../../ports/index.html">Ports
 	    Manager</ulink></term>
 
 	<listitem>
 	  <para>&a.portmgr;</para>
 
 	  <para>which includes:</para>
 
 	  <para>&a.ade;,</para>
 	  <para>&a.asami;,</para>
 	  <para>&a.kris;,</para>
 	  <para>&a.sobomax;,</para>
 	  <para>&a.steve;,</para>
 	  <para>&a.will;</para>
 
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Standards</term>
 
 	<listitem>
 	  <para>&a.wollman;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>XFree86 Project, Inc. Liaison</term>
 
 	<listitem>
 	  <para>&a.rich;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><ulink url="../../../../support.html#gnats">GNATS
 	    Administrator</ulink></term>
 
 	<listitem>
 	  <para>&a.steve;</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
         <term>Bugmeister</term>
 
 	<listitem>
 	  <para>&a.des;</para>
 	</listitem>
       </varlistentry>
 
     </variablelist>
   </sect1>
 
   <sect1 id="contrib-corealumni">
     <title>Core Team Alumni</title>
 
     <indexterm><primary>core team</primary></indexterm>
     <para>The following people were members of the FreeBSD core team during
       the periods indicated.  We thank them for their past efforts in the
       service of the FreeBSD project.</para>
 
     <para><emphasis>In rough chronological order:</emphasis></para>
 
     <itemizedlist>
       <listitem>
-	<para>&a.asami (1993 - 2001)</para>
+	<para>&a.asami; (1993 - 2001)</para>
       </listitem>
 
       <listitem>
-	<para>&a.ache (1993 - 2000)</para>
+	<para>&a.ache; (1993 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.jmb (1993 - 2000)</para>
+	<para>&a.jmb; (1993 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.bde (1992 - 2000)</para>
+	<para>&a.bde; (1992 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.gibbs (1993 - 2000)</para>
+	<para>&a.gibbs; (1993 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.rich (1994 - 2000)</para>
+	<para>&a.rich; (1994 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.phk (1992 - 2000)</para>
+	<para>&a.phk; (1992 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.gpalmer (1993 - 2000)</para>
+	<para>&a.gpalmer; (1993 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.sos (1993 - 2000)</para>
+	<para>&a.sos; (1993 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.wollman (1993 - 2000)</para>
+	<para>&a.wollman; (1993 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.joerg (1995 - 2000)</para>
+	<para>&a.joerg; (1995 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.jdp (1997 - 2000)</para>
+	<para>&a.jdp; (1997 - 2000)</para>
       </listitem>
 
       <listitem>
-	<para>&a.guido (1995 - 1999)</para>
+	<para>&a.guido; (1995 - 1999)</para>
       </listitem>
 
       <listitem>
 	<para>John Dyson (1993 - 1998)</para>
       </listitem>
 
       <listitem>
-	<para>&a.nate (1992 - 1996)</para>
+	<para>&a.nate; (1992 - 1996)</para>
       </listitem>
 
       <listitem>
-	<para>&a.rgrimes (1992 - 1995)</para>
+	<para>&a.rgrimes; (1992 - 1995)</para>
       </listitem>
 
       <listitem>
 	<para>Andreas Schulz (1992 - 1995)</para>
       </listitem>
 
       <listitem>
-	<para>&a.csgr (1993 - 1995)</para>
+	<para>&a.csgr; (1993 - 1995)</para>
       </listitem>
 
       <listitem>
-	<para>&a.paul (1992 - 1995)</para>
+	<para>&a.paul; (1992 - 1995)</para>
       </listitem>
 
       <listitem>
-	<para>&a.smace (1993 - 1994)</para>
+	<para>&a.smace; (1993 - 1994)</para>
       </listitem>
 
       <listitem>
 	<para>Andrew Moore (1993 - 1994)</para>
       </listitem>
 
       <listitem>
 	<para>Christoph Robitschko (1993 - 1994)</para>
       </listitem>
 
       <listitem>
 	<para>J. T. Conklin (1992 - 1993)</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="contrib-develalumni">
     <title>Development Team Alumni</title>
 
     <indexterm><primary>development team</primary></indexterm>
     <para>The following people were members of the FreeBSD development team
       during the periods indicated.  We thank them for their past efforts
       in the service of the FreeBSD project.</para>
 
     <para><emphasis>In rough chronological order:</emphasis></para>
 
     <itemizedlist>
       <listitem>
         <para>&a.issei; (2000 - 2002)</para>
       </listitem>
       <listitem>
 	<para>&a.asmodai; (1999 - 2001)</para>
       </listitem>
       <listitem>
-        <para>&a.tedm (???? - 2000)</para>
+        <para>&a.tedm; (???? - 2000)</para>
       </listitem>
       <listitem>
-        <para>&a.karl (???? - 2000)</para>
+        <para>&a.karl; (???? - 2000)</para>
       </listitem>
       <listitem>
         <para>Gary Clark II (1993 - 2000)</para>
       </listitem>
       <listitem>
         <para>James Raynard (???? - 2000)</para>
       </listitem>
       <listitem>
-        <para>&a.jgreco (???? - 1999)</para>
+        <para>&a.jgreco; (???? - 1999)</para>
       </listitem>
       <listitem>
         <para>Andreas Schulz (???? - 1999)</para>
       </listitem>
       <listitem>
         <para>Jamil Weatherby (1997 - 1999)</para>
       </listitem>
       <listitem>
         <para>meganm (???? - 1998)</para>
       </listitem>
       <listitem>
         <para>John Dyson (???? - 1998)</para>
       </listitem>
       <listitem>
         <para>Amancio Hasty (1997 - 1998)</para>
       </listitem>
       <listitem>
         <para>Drew Derbyshire (1997 - 1998)</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="contrib-derived">
     <title>Derived Software Contributors</title>
 
     <para>This software was originally derived from William F. Jolitz's 386BSD
       release 0.1, though almost none of the original 386BSD specific code
       remains.  This software has been essentially re-implemented from the
       4.4BSD-Lite release provided by the Computer Science Research Group
       (CSRG) at the University of California, Berkeley and associated academic
       contributors.</para>
 
     <para>There are also portions of NetBSD and OpenBSD that have been
       integrated into FreeBSD as well, and we would therefore like to thank
       all the contributors to NetBSD and OpenBSD for their work.</para>
   </sect1>
 
   <sect1 id="contrib-additional">
     <title>Additional FreeBSD Contributors</title>
 
     <para>(in alphabetical order by first name):</para>
 
     <itemizedlist>
       <listitem>
 	<para>ABURAYA Ryushirou <email>rewsirow@ff.iij4u.or.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>AMAGAI Yoshiji <email>amagai@nue.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Aaron Bornstein <email>aaronb@j51.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Aaron Smith <email>aaron@mutex.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Achim Patzner <email>ap@noses.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Ada T Lim <email>ada@bsd.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Adam Baran <email>badam@mw.mil.pl</email></para>
       </listitem>
 
       <listitem>
 	<para>Adam Glass <email>glass@postgres.berkeley.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Adam Herzog <email>adam@herzogdesigns.com</email></para>
       </listitem>
 
       <listitem>
         <para>Adam Kranzel <email>adam@alameda.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Adam McDougall <email>mcdouga9@egr.msu.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Adam Strohl <email>troll@digitalspark.net</email></para>
       </listitem>
 
       <listitem>
 	<para>Adam Weinberger <email>monkey@crackula.com</email></para>
       </listitem>
 
       <listitem>
         <para>Adoal Xu <email>adoal@iname.com</email></para>
       </listitem>
 
       <listitem>
         <para>Adrian Colley <email>aecolley@ois.ie</email></para>
       </listitem>
 
       <listitem>
         <para>Adrian Hall <email>ahall@mirapoint.com</email></para>
       </listitem>
 
       <listitem>
         <para>Adrian Mariano <email>adrian@cam.cornell.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Adrian Steinmann <email>ast@marabu.ch</email></para>
       </listitem>
 
       <listitem>
         <para>Adrian T. Filipi-Martin
 	  <email>atf3r@agate.cs.virginia.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Ajit Thyagarajan <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Akira SAWADA <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Akira Watanabe
 	  <email>akira@myaw.ei.meisei-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Akito Fujita <email>fujita@zoo.ncl.omron.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Alain Kalker
 	  <email>A.C.P.M.Kalker@student.utwente.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Alan Bawden <email>alan@curry.epilogue.com</email></para>
       </listitem>
 
       <listitem>
         <para>Alan Eldridge <email>alane@geeksrus.net</email></para>
       </listitem>
 
       <listitem>
         <para>Alec Wolman <email>wolman@cs.washington.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Aled Morris <email>aledm@routers.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Aleksandr A Babaylov <email>.@babolo.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Alex G. Bulushev <email>bag@demos.su</email></para>
       </listitem>
 
       <listitem>
         <para>Alex D. Chen
 	  <email>dhchen@Canvas.dorm7.nccu.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Alex Le Heux <email>alexlh@funk.org</email></para>
       </listitem>
 
       <listitem>
         <para>Alex Kapranoff <email>kappa@zombie.antar.bryansk.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Alex Perel <email>veers@disturbed.net</email></para>
       </listitem>
 
       <listitem>
         <para>Alex Semenyaka <email>alex@rinet.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Alex Varju <email>varju@webct.com</email></para>
       </listitem>
 
       <listitem>
         <para>Alex Zepeda <email>garbanzo@hooked.net</email></para>
       </listitem>
 
       <listitem>
         <para>Alexander B. Povolotsky <email>tarkhil@mgt.msk.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Alexander Gelfenbain <email>mail@gelf.com</email></para>
       </listitem>
 
       <listitem>
         <para>Alexandre Peixoto
           <email>alexandref@tcoip.com.br</email></para>
       </listitem>
 
       <listitem>
         <para>Alexandre Snarskii <email>snar@paranoia.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Alexey V. Neyman <email>alex.neyman@auriga.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Alistair G. Crooks <email>agc@uts.amdahl.com</email></para>
       </listitem>
 
       <listitem>
         <para>Allan Bowhill <email>bowhill@bowhill.vservers.com</email></para>
       </listitem>
 
       <listitem>
         <para>Allan Saddi <email>asaddi@philosophysw.com</email></para>
       </listitem>
 
       <listitem>
         <para>Allen Campbell <email>allenc@verinet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Amakawa Shuhei <email>amakawa@hoh.t.u-tokyo.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Amancio Hasty <email>hasty@star-gate.com</email></para>
       </listitem>
 
       <listitem>
         <para>Amir Farah <email>amir@comtrol.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Amir Shalem <email>amir@boom.org.il</email></para>
       </listitem>
 
       <listitem>
         <para>Amy Baron <email>amee@beer.org</email></para>
       </listitem>
 
       <listitem>
         <para>The Anarcat <email>beaupran@iro.umontreal.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Anatoly A. Orehovsky <email>tolik@mpeks.tomsk.su</email></para>
       </listitem>
 
       <listitem>
         <para>Anatoly Vorobey <email>mellon@pobox.com</email></para>
       </listitem>
 
       <listitem>
         <para>Anders Andersson <email>anders@codefactory.se</email></para>
       </listitem>
 
       <listitem>
         <para>Anders Thulin <email>Anders.X.Thulin@telia.se</email></para>
       </listitem>
 
       <listitem>
         <para>Andras Olah <email>olah@cs.utwente.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Andre Albsmeier
 	  <email>Andre.Albsmeier@mchp.siemens.de</email></para>
       </listitem>
 
       <listitem>
         <para>Andre Goeree <email>abgoeree@uwnet.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Andre Oppermann <email>andre@pipeline.ch</email></para>
       </listitem>
 
       <listitem>
         <para>Andreas Haakh <email>ah@alman.robin.de</email></para>
       </listitem>
 
       <listitem>
         <para>Andreas Kohout <email>shanee@rabbit.augusta.de</email></para>
       </listitem>
 
       <listitem>
         <para>Andreas Lohr <email>andreas@marvin.RoBIN.de</email></para>
       </listitem>
 
       <listitem>
         <para>Andreas Schulz <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Andreas Wetzel <email>mickey@deadline.snafu.de</email></para>
       </listitem>
 
       <listitem>
         <para>Andreas Wrede <email>andreas@planix.com</email></para>
       </listitem>
 
       <listitem>
         <para>Andres Vega Garcia <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew Atrens <email>atreand@statcan.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew Boothman <email>andrew@cream.org</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew Gillham <email>gillham@andrews.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew Gordon <email>andrew.gordon@net-tel.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew J. Korty <email>ajk@purdue.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew P. Lentvorski <email>bsder@allcaps.org</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew L. Moore <email>alm@mclink.com</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew L. Neporada <email>andrew@chg.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew McRae <email>amcrae@cisco.com</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew Stevenson <email>andrew@ugh.net.au</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew Timonin <email>tim@pool1.convey.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew V. Stesin <email>stesin@elvisti.kiev.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Andrew Webster <email>awebster@dataradio.com</email></para>
       </listitem>
 
       <listitem>
         <para>Andrey Novikov <email>andrey@novikov.com</email></para>
       </listitem>
 
       <listitem>
         <para>Andrey Simonenko <email>simon@comsys.ntu-kpi.kiev.ua</email></para>
       </listitem>
 
       <listitem>
 	<para>Andrey Tchoritch <email>andy@venus.sympad.net</email></para>
       </listitem>
 
       <listitem>
         <para>Andy Farkas <email>andyf@speednet.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Andy Sparrow <email>spadger@best.com</email></para>
       </listitem>
 
       <listitem>
         <para>Andy Valencia <email>ajv@csd.mot.com</email></para>
       </listitem>
 
       <listitem>
         <para>Andy Whitcroft <email>andy@sarc.city.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Angel Todorov <email>todorov_bg@gmx.net</email></para>
       </listitem>
 
       <listitem>
         <para>Angelo Turetta <email>ATuretta@stylo.it</email></para>
       </listitem>
 
       <listitem>
         <para>Anthony C. Chavez <email>magus@xmission.com</email></para>
       </listitem>
 
       <listitem>
         <para>Anthony Yee-Hang Chan <email>yeehang@netcom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Anton N. Bruesov <email>antonz@library.ntu-kpi.kiev.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Anton Voronin <email>anton@urc.ac.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Antti Kaipila <email>anttik@iki.fi</email></para>
       </listitem>
 
       <listitem>
 	<para>arci <email>vega@sophia.inria.fr</email></para>
       </listitem>
 
       <listitem>
         <para>Are Bryne <email>are.bryne@communique.no</email></para>
       </listitem>
 
       <listitem>
         <para>Ari Suutari <email>ari@suutari.iki.fi</email></para>
       </listitem>
 
       <listitem>
 	<para>Arindum Mukerji <email>rmukerji@execpc.com</email></para>
       </listitem>
 
       <listitem>
         <para>Arjan de Vet <email>devet@IAEhv.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Arne Henrik Juul <email>arnej@Lise.Unit.NO</email></para>
       </listitem>
 
       <listitem>
         <para>Arun Sharma <email>adsharma@sharmas.dhs.org</email></para>
       </listitem>
 
       <listitem>
         <para>Arnaud S. Launay <email>asl@launay.org</email></para>
       </listitem>
 
       <listitem>
         <para>Ashley Penney <email>ashp@unloved.org</email></para>
       </listitem>
 
       <listitem>
         <para>Ask Bjoern Hansen <email>ask@valueclick.com</email></para>
       </listitem>
 
       <listitem>
         <para>Atsushi Furuta <email>furuta@sra.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Atsushi Murai <email>amurai@spec.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Atushi Sakauchi <email>sakauchi@yamame.to</email></para>
       </listitem>
 
       <listitem>
         <para>Bakul Shah <email>bvs@bitblocks.com</email></para>
       </listitem>
 
       <listitem>
         <para>Barry Bierbauch <email>pivrnec@vszbr.cz</email></para>
       </listitem>
 
       <listitem>
         <para>Barry Lustig <email>barry@ictv.com</email></para>
       </listitem>
 
       <listitem>
         <para>Ben Hutchinson <email>benhutch@xfiles.org.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Ben Jackson <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Ben Walter <email>bwalter@itachi.swcp.com</email></para>
       </listitem>
 
       <listitem>
         <para>Benjamin Lewis <email>bhlewis@gte.net</email></para>
       </listitem>
 
       <listitem>
         <para>Berend de Boer <email>berend@pobox.com</email></para>
       </listitem>
 
       <listitem>
         <para>Bernd Rosauer <email>br@schiele-ct.de</email></para>
       </listitem>
 
       <listitem>
         <para>Bill Kish <email>kish@osf.org</email></para>
       </listitem>
 
       <listitem>
         <para>Bill Trost <email>trost@cloud.rain.com</email></para>
       </listitem>
 
       <listitem>
         <para>Blaz Zupan <email>blaz@amis.net</email></para>
       </listitem>
 
       <listitem>
         <para>Bob Van Valzah <email>Bob@whitebarn.com</email></para>
       </listitem>
 
       <listitem>
         <para>Bob Wilcox <email>bob@obiwan.uucp</email></para>
       </listitem>
 
       <listitem>
         <para>Bob Willcox <email>bob@luke.pmr.com</email></para>
       </listitem>
 
       <listitem>
         <para>Boris Staeblow <email>balu@dva.in-berlin.de</email></para>
       </listitem>
 
       <listitem>
         <para>Boyd Faulkner <email>faulkner@mpd.tandem.com</email></para>
       </listitem>
 
       <listitem>
         <para>Boyd R. Faulkner <email>faulkner@asgard.bga.com</email></para>
       </listitem>
 
       <listitem>
         <para>Brad Chapman <email>chapmanb@arches.uga.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Brad Hendrickse <email>bradh@uunet.co.za</email></para>
       </listitem>
 
       <listitem>
         <para>Brad Karp <email>karp@eecs.harvard.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Bradley Dunn <email>bradley@dunn.org</email></para>
       </listitem>
 
       <listitem>
         <para>Brad Jones <email>brad@kazrak.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Brandon Fosdick <email>bfoz@glue.umd.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Brandon Gillespie <email>brandon@roguetrader.com</email></para>
       </listitem>
 
       <listitem>
         <para>Bill Lloyd <email>wlloyd@mpd.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Brent J. Nordquist <email>bjn@visi.com</email></para>
       </listitem>
 
       <listitem>
         <para>Brett Lymn <email>blymn@mulga.awadi.com.AU</email></para>
       </listitem>
 
       <listitem>
         <para>Brett Taylor
 	  <email>brett@peloton.runet.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Brian Campbell <email>brianc@pobox.com</email></para>
       </listitem>
 
       <listitem>
         <para>Brian Clapper <email>bmc@willscreek.com</email></para>
       </listitem>
 
       <listitem>
         <para>Brian Cully <email>shmit@kublai.com</email></para>
       </listitem>
 
       <listitem>
         <para>Brian Handy
 	  <email>handy@lambic.space.lockheed.com</email></para>
       </listitem>
 
       <listitem>
         <para>Brian Litzinger <email>brian@MediaCity.com</email></para>
       </listitem>
 
       <listitem>
         <para>Brian McGovern <email>bmcgover@cisco.com</email></para>
       </listitem>
 
       <listitem>
         <para>Brian Moore <email>ziff@houdini.eecs.umich.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Brian R. Haug <email>haug@conterra.com</email></para>
       </listitem>
 
       <listitem>
         <para>Brian Tao <email>taob@risc.org</email></para>
       </listitem>
 
       <listitem>
         <para>Brion Moss <email>brion@queeg.com</email></para>
       </listitem>
 
       <listitem>
         <para>Bruce Albrecht <email>bruce@zuhause.mn.org</email></para>
       </listitem>
 
       <listitem>
         <para>Bruce Gingery <email>bgingery@gtcs.com</email></para>
       </listitem>
 
       <listitem>
         <para>Bruce J. Keeler <email>loodvrij@gridpoint.com</email></para>
       </listitem>
 
       <listitem>
         <para>Bruce Murphy <email>packrat@iinet.net.au</email></para>
       </listitem>
 
       <listitem>
         <para>Bruce Walter <email>walter@fortean.com</email></para>
       </listitem>
 
       <listitem>
         <para>Carey Jones <email>mcj@acquiesce.org</email></para>
       </listitem>
 
       <listitem>
         <para>Carl Fongheiser <email>cmf@netins.net</email></para>
       </listitem>
 
       <listitem>
         <para>Carl Mascott <email>cmascott@world.std.com</email></para>
       </listitem>
 
       <listitem>
         <para>Casper <email>casper@acc.am</email></para>
       </listitem>
 
       <listitem>
         <para>Castor Fu <email>castor@geocast.com</email></para>
       </listitem>
 
       <listitem>
         <para>Chain Lee <email>chain@110.net</email></para>
       </listitem>
 
       <listitem>
         <para>Charles Hannum <email>mycroft@ai.mit.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Charles Henrich <email>henrich@msu.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Charles Mott <email>cmott@scientech.com</email></para>
       </listitem>
 
       <listitem>
         <para>Charles Owens <email>owensc@enc.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Chet Ramey <email>chet@odin.INS.CWRU.Edu</email></para>
       </listitem>
 
       <listitem>
         <para>Chia-liang Kao <email>clkao@CirX.ORG</email></para>
       </listitem>
 
       <listitem>
         <para>Chiharu Shibata <email>chi@bd.mbn.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Chip Norkus <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Chris Csanady <email>cc@tarsier.ca.sandia.gov</email></para>
       </listitem>
 
       <listitem>
         <para>Chris Dabrowski <email>chris@vader.org</email></para>
       </listitem>
 
       <listitem>
         <para>Chris Dillon <email>cdillon@wolves.k12.mo.us</email></para>
       </listitem>
 
       <listitem>
         <para>Chris Shenton
 	  <email>cshenton@angst.it.hq.nasa.gov</email></para>
       </listitem>
 
       <listitem>
         <para>&a.cshumway;</para>
       </listitem>
 
       <listitem>
         <para>Chris Stenton <email>jacs@gnome.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Chris Timmons <email>skynyrd@opus.cts.cwu.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Chris Torek <email>torek@ee.lbl.gov</email></para>
       </listitem>
 
       <listitem>
         <para>Christian Gusenbauer
 	  <email>cg@fimp01.fim.uni-linz.ac.at</email></para>
       </listitem>
 
       <listitem>
         <para>Christian Haury <email>Christian.Haury@sagem.fr</email></para>
       </listitem>
 
       <listitem>
         <para>Christoph P. Kukulies <email>kuku@FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Christoph Robitschko
 	  <email>chmr@edvz.tu-graz.ac.at</email></para>
       </listitem>
 
       <listitem>
         <para>Christoph Weber-Fahr
 	  <email>wefa@callcenter.systemhaus.net</email></para>
       </listitem>
 
       <listitem>
         <para>Christopher G. Demetriou
 	  <email>cgd@postgres.berkeley.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Christopher N. Harrell <email>cnh@ivmg.net</email></para>
       </listitem>
 
       <listitem>
         <para>Christopher Preston <email>rbg@gayteenresource.org</email></para>
       </listitem>
 
       <listitem>
         <para>Christopher T. Johnson
 	  <email>cjohnson@neunacht.netgsi.com</email></para>
       </listitem>
 
       <listitem>
         <para>Chrisy Luke <email>chrisy@flix.net</email></para>
       </listitem>
 
       <listitem>
         <para>Chuck Hein <email>chein@cisco.com</email></para>
       </listitem>
 
       <listitem>
         <para>Cliff Rowley <email>dozprompt@onsea.com</email></para>
       </listitem>
 
       <listitem>
         <para>Colman Reilly <email>careilly@tcd.ie</email></para>
       </listitem>
 
       <listitem>
         <para>Conrad Sabatier <email>conrads@home.com</email></para>
       </listitem>
 
       <listitem>
         <para>Coranth Gryphon <email>gryphon@healer.com</email></para>
       </listitem>
 
       <listitem>
         <para>Cornelis van der Laan
 	  <email>nils@guru.ims.uni-stuttgart.de</email></para>
       </listitem>
 
       <listitem>
         <para>Cove Schneider <email>cove@brazil.nbn.com</email></para>
       </listitem>
 
       <listitem>
         <para>Craig Leres <email>leres@ee.lbl.gov</email></para>
       </listitem>
 
       <listitem>
         <para>Craig Loomis <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Craig Metz <email>cmetz@inner.net</email></para>
       </listitem>
 
       <listitem>
         <para>Craig Spannring <email>cts@internetcds.com</email></para>
       </listitem>
 
       <listitem>
         <para>Craig Struble <email>cstruble@vt.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Cristian Ferretti <email>cfs@riemann.mat.puc.cl</email></para>
       </listitem>
 
       <listitem>
         <para>Curt Mayer <email>curt@toad.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Cyrille Lefevre <email>clefevre@citeweb.net</email></para>
       </listitem>
 
       <listitem>
         <para>Cyrus Rahman <email>cr@jcmax.com</email></para>
       </listitem>
 
       <listitem>
         <para>Dai Ishijima <email>ishijima@tri.pref.osaka.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Daisuke Watanabe <email>NU7D-WTNB@asahi-net.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Damian Hamill <email>damian@cablenet.net</email></para>
       </listitem>
 
       <listitem>
         <para>Dan Cross <email>tenser@spitfire.ecsel.psu.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Dan Langille <email>dan@freebsddiary.org</email></para>
       </listitem>
 
       <listitem>
         <para>Dan Lukes <email>dan@obluda.cz</email></para>
       </listitem>
 
       <listitem>
         <para>Dan Nelson <email>dnelson@emsphone.com</email></para>
       </listitem>
 
       <listitem>
         <para>Dan Papasian <email>bugg@bugg.strangled.net</email></para>
       </listitem>
 
       <listitem>
         <para>Dan Piponi <email>wmtop@tanelorn.demon.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Dan Walters <email>hannibal@cyberstation.net</email></para>
       </listitem>
 
       <listitem>
         <para>Daniel Hagan
 	  <email>dhagan@acm.vt.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Daniel O'Connor <email>doconnor@gsoft.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Daniel Poirot <email>poirot@aio.jsc.nasa.gov</email></para>
       </listitem>
 
       <listitem>
         <para>Daniel Rock <email>rock@cs.uni-sb.de</email></para>
       </listitem>
 
       <listitem>
         <para>Daniel W. McRobb <email>dwm@caimis.com</email></para>
       </listitem>
 
       <listitem>
         <para>Danny Egen <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Danny Howard <email>dannyman@toldme.com</email></para>
       </listitem>
 
       <listitem>
         <para>Danny J. Zerkel <email>dzerkel@phofarm.com</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Adkins <email>adkin003@tc.umn.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Andersen <email>angio@aros.net</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Blizzard <email>dblizzar@sprynet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Bodenstab <email>imdave@synet.net</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Chapeskie <email>dchapes@ddm.on.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Cornejo <email>dave@dogwood.com</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Edmondson <email>davided@sco.com</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Glowacki <email>dglo@ssec.wisc.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Marquardt <email>marquard@austin.ibm.com</email></para>
       </listitem>
 
       <listitem>
         <para>Dave Tweten <email>tweten@FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>David A. Adkins <email>adkin003@tc.umn.edu</email></para>
       </listitem>
 
       <listitem>
         <para>David A. Bader <email>dbader@eece.unm.edu</email></para>
       </listitem>
 
       <listitem>
         <para>David Borman <email>dab@bsdi.com</email></para>
       </listitem>
 
       <listitem>
         <para>David Bremner <email>bremner@unb.ca</email></para>
       </listitem>
 
       <listitem>
         <para>David Dawes <email>dawes@XFree86.org</email></para>
       </listitem>
 
       <listitem>
         <para>David Filo <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>David Holland <email>dholland@eecs.harvard.edu</email></para>
       </listitem>
 
       <listitem>
         <para>David Holloway <email>daveh@gwythaint.tamis.com</email></para>
       </listitem>
 
       <listitem>
         <para>David Horwitt <email>dhorwitt@ucsd.edu</email></para>
       </listitem>
 
       <listitem>
         <para>David Hovemeyer <email>daveho@infocom.com</email></para>
       </listitem>
 
       <listitem>
         <para>David Jones <email>dej@qpoint.torfree.net</email></para>
       </listitem>
 
       <listitem>
         <para>David Kelly <email>dkelly@tomcat1.tbe.com</email></para>
       </listitem>
 
       <listitem>
         <para>David Kulp <email>dkulp@neomorphic.com</email></para>
       </listitem>
 
       <listitem>
         <para>David L. Nugent <email>davidn@blaze.net.au</email></para>
       </listitem>
 
       <listitem>
         <para>David Leonard <email>d@scry.dstc.edu.au</email></para>
       </listitem>
 
       <listitem>
         <para>David Muir Sharnoff <email>muir@idiom.com</email></para>
       </listitem>
 
       <listitem>
         <para>David S. Miller <email>davem@jenolan.rutgers.edu</email></para>
       </listitem>
 
       <listitem>
         <para>David Sugar <email>dyfet@gnu.org</email></para>
       </listitem>
 
       <listitem>
         <para>David Wolfskill <email>david@catwhisker.org</email></para>
       </listitem>
 
       <listitem>
 	<para>David Yeske <email>dyeske@yahoo.com</email></para>
       </listitem>
 
       <listitem>
         <para>Dean Gaudet <email>dgaudet@arctic.org</email></para>
       </listitem>
 
       <listitem>
         <para>Dean Huxley <email>dean@fsa.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Denis Fortin <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Denis Shaposhnikov <email>dsh@vlink.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Dennis Glatting
 	  <email>dennis.glatting@software-munitions.com</email></para>
       </listitem>
 
       <listitem>
         <para>Denton Gentry <email>denny1@home.com</email></para>
       </listitem>
 
       <listitem>
 	<para>der Mouse <email>mouse@Collatz.McRCIM.McGill.EDU</email></para>
       </listitem>
 
       <listitem>
         <para>Derek Inksetter <email>derek@saidev.com</email></para>
       </listitem>
 
       <listitem>
         <para>DI. Christian Gusenbauer
 	  <email>cg@scotty.edvz.uni-linz.ac.at</email></para>
       </listitem>
 
       <listitem>
         <para>Diane Bruce <email>db@db.net</email></para>
       </listitem>
 
       <listitem>
         <para>Dirk Keunecke <email>dk@panda.rhein-main.de</email></para>
       </listitem>
 
       <listitem>
         <para>Dirk Nehrling <email>nerle@pdv.de</email></para>
       </listitem>
 
       <listitem>
         <para>Dishanker Rajakulendren <email>draj@oceanfree.net</email></para>
       </listitem>
 
       <listitem>
         <para>Dmitry A. Yanko <email>fm@astral.ntu-kpi.kiev.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Dmitry Karasik <email>dmitry@karasik.eu.org</email></para>
       </listitem>
 
       <listitem>
         <para>Dmitry Khrustalev <email>dima@xyzzy.machaon.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Dmitry Kohmanyuk <email>dk@farm.org</email></para>
       </listitem>
 
       <listitem>
         <para>Dmitry Morozovsky <email>marck@rinet.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Dom Mitchell <email>dom@myrddin.demon.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Domas Mituzas <email>midom@dammit.lt</email></para>
       </listitem>
 
       <listitem>
         <para>Dominik Brettnacher <email>domi@saargate.de</email></para>
       </listitem>
 
       <listitem>
 	<para>Dominik Rothert <email>dr@domix.de</email></para>
       </listitem>
 
       <listitem>
         <para>Don Croyle <email>croyle@gelemna.ft-wayne.in.us</email></para>
       </listitem>
 
       <listitem>
         <para>Donn Miller <email>dmmiller@cvzoom.net</email></para>
       </listitem>
 
       <listitem>
         <para>Dan Pelleg <email>dpelleg+unison@cs.cmu.edu</email></para>
       </listitem>
 
       <listitem>
         <para>&a.whiteside;</para>
       </listitem>
 
       <listitem>
         <para>Don Morrison <email>dmorrisn@u.washington.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Don Yuniskis <email>dgy@rtd.com</email></para>
       </listitem>
 
       <listitem>
         <para>Donald Maddox <email>dmaddox@conterra.com</email></para>
       </listitem>
 
       <listitem>
         <para>Douglas Carmichael <email>dcarmich@mcs.com</email></para>
       </listitem>
 
       <listitem>
         <para>Douglas Crosher <email>dtc@scrooge.ee.swin.oz.au</email></para>
       </listitem>
 
       <listitem>
         <para>Drew Derbyshire <email>ahd@kew.com</email></para>
       </listitem>
 
       <listitem>
         <para>Dustin Sallings <email>dustin@spy.net</email></para>
       </listitem>
 
       <listitem>
         <para>Eckart "Isegrim" Hofmann
 	  <email>Isegrim@Wunder-Nett.org</email></para>
       </listitem>
 
       <listitem>
         <para>Ed Gold
 	  <email>vegold01@starbase.spd.louisville.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Ed Hudson <email>elh@p5.spnet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Edward Chuang <email>edwardc@firebird.org.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Edward Wang <email>edward@edcom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Edwin Groothus <email>edwin@mavetju.org</email></para>
       </listitem>
 
       <listitem>
         <para>Edwin Mons <email>e@ik.nu</email></para>
       </listitem>
 
       <listitem>
 	<para>Ege Rekk <email>aagero@aage.priv.no</email></para>
       </listitem>
 
       <listitem>
         <para>Eiji-usagi-MATSUmoto <email>usagi@clave.gr.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Eike Bernhardt <email>eike.bernhardt@gmx.de</email></para>
       </listitem>
 
       <listitem>
         <para>ELISA Font Project</para>
       </listitem>
 
       <listitem>
         <para>Elmar Bartel
 	  <email>bartel@informatik.tu-muenchen.de</email></para>
       </listitem>
 
       <listitem>
         <para>Eoin Lawless <email>eoin@maths.tcd.ie</email></para>
       </listitem>
 
       <listitem>
         <para>Eric A. Griff <email>eric@talesfromthereal.com</email></para>
       </listitem>
 
       <listitem>
         <para>Eric Blood <email>eblood@cs.unr.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Eric D. Futch <email>efutch@nyct.net</email></para>
       </listitem>
 
       <listitem>
         <para>Eric J. Haug <email>ejh@slustl.slu.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Eric J. Schwertfeger <email>eric@cybernut.com</email></para>
       </listitem>
 
       <listitem>
         <para>Eric L. Hernes <email>erich@lodgenet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Eric P. Scott <email>eps@sirius.com</email></para>
       </listitem>
 
       <listitem>
         <para>Eric Sprinkle <email>eric@ennovatenetworks.com</email></para>
       </listitem>
 
       <listitem>
         <para>Erich Stefan Boleyn <email>erich@uruk.org</email></para>
       </listitem>
 
       <listitem>
         <para>Erich Zigler <email>erich@tacni.net</email></para>
       </listitem>
 
       <listitem>
         <para>Erik H. Bakke <email>erikhb@bgnett.no</email></para>
       </listitem>
 
       <listitem>
         <para>Erik E. Rantapaa <email>rantapaa@math.umn.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Erik H. Moe <email>ehm@cris.com</email></para>
       </listitem>
 
       <listitem>
         <para>Ernst Winter <email>ewinter@lobo.muc.de</email></para>
       </listitem>
 
       <listitem>
 	<para>Espen Skoglund <email>esk@ira.uka.de</email></para>
       </listitem>
 
       <listitem>
         <para>Eugene M. Kim <email>astralblue@usa.net</email></para>
       </listitem>
 
       <listitem>
         <para>Eugene Radchenko <email>genie@qsar.chem.msu.su</email></para>
       </listitem>
 
       <listitem>
 	<para>Eugeny Kuzakov <email>CoreDumped@coredumped.null.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Evan Champion <email>evanc@synapse.net</email></para>
       </listitem>
 
       <listitem>
 	<para>Fanying Jen <email>fanying@fynet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Faried Nawaz <email>fn@Hungry.COM</email></para>
       </listitem>
 
       <listitem>
         <para>Flemming Jacobsen <email>fj@batmule.dk</email></para>
       </listitem>
 
       <listitem>
         <para>Fong-Ching Liaw <email>fong@juniper.net</email></para>
       </listitem>
 
       <listitem>
         <para>Francis M J Hsieh <email>mjshieh@life.nthu.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Francisco Reyes <email>fjrm@yahoo.com</email></para>
       </listitem>
 
       <listitem>
         <para>Frank Bartels <email>knarf@camelot.de</email></para>
       </listitem>
 
       <listitem>
         <para>Frank Chen Hsiung Chan
 	  <email>frankch@waru.life.nthu.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Frank Durda IV <email>uhclem@nemesis.lonestar.org</email></para>
       </listitem>
 
       <listitem>
         <para>Frank MacLachlan <email>fpm@n2.net</email></para>
       </listitem>
 
       <listitem>
         <para>Frank Nobis <email>fn@Radio-do.de</email></para>
       </listitem>
 
       <listitem>
         <para>Frank ten Wolde <email>franky@pinewood.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Frank van der Linden <email>frank@fwi.uva.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Frank Volf <email>volf@oasis.IAEhv.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Fred Cawthorne <email>fcawth@jjarray.umn.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Fred Gilham <email>gilham@csl.sri.com</email></para>
       </listitem>
 
       <listitem>
         <para>Fred Templin <email>templin@erg.sri.com</email></para>
       </listitem>
 
       <listitem>
         <para>Frederick Earl Gray <email>fgray@rice.edu</email></para>
       </listitem>
 
       <listitem>
         <para>FUJIMOTO Kensaku
 	  <email>fujimoto@oscar.elec.waseda.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>FURUSAWA Kazuhisa
 	  <email>furusawa@com.cs.osakafu-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Fuyuhiko Maruyama <email>fuyuhik8@is.titech.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>&a.stanislav;</para>
       </listitem>
 
       <listitem>
         <para>Gabor Kincses <email>gabor@acm.org</email></para>
       </listitem>
 
       <listitem>
         <para>Gabor Zahemszky <email>zgabor@CoDe.hu</email></para>
       </listitem>
 
       <listitem>
         <para>Gareth McCaughan <email>gjm11@dpmms.cam.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para>
       </listitem>
 
       <listitem>
         <para>Gary Howland <email>gary@hotlava.com</email></para>
       </listitem>
 
       <listitem>
         <para>Gary J. <email>garyj@rks32.pcs.dec.com</email></para>
       </listitem>
 
       <listitem>
         <para>Gary Kline <email>kline@thought.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Gary W. Swearingen <email>swear@aa.net</email></para>
       </listitem>
 
       <listitem>
         <para>Gaspar Chilingarov <email>nightmar@lemming.acc.am</email></para>
       </listitem>
 
       <listitem>
         <para>Gea-Suan Lin <email>gsl@tpts4.seed.net.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Gene Raytsin <email>pal@paladin7.net</email></para>
       </listitem>
 
       <listitem>
         <para>Geoff Rehmet <email>csgr@alpha.ru.ac.za</email></para>
       </listitem>
 
       <listitem>
         <para>Georg Wagner <email>georg.wagner@ubs.com</email></para>
       </listitem>
 
       <listitem>
         <para>Gerald Pfeifer <email>pfeifer@dbai.tuwien.ac.at</email></para>
       </listitem>
 
       <listitem>
 	<para>Gianlorenzo Masini <email>masini@uniroma3.it</email></para>
       </listitem>
 
       <listitem>
         <para>Gianmarco Giovannelli
 	  <email>gmarco@giovannelli.it</email></para>
       </listitem>
 
       <listitem>
         <para>Gil Kloepfer Jr. <email>gil@limbic.ssdl.com</email></para>
       </listitem>
 
       <listitem>
         <para>Gilad Rom <email>rom_glsa@ein-hashofet.co.il</email></para>
       </listitem>
 
       <listitem>
         <para>Giles Lean <email>giles@nemeton.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Ginga Kawaguti
 	  <email>ginga@amalthea.phys.s.u-tokyo.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Glen Foster <email>gfoster@gfoster.com</email></para>
       </listitem>
 
       <listitem>
         <para>Glenn Johnson <email>gljohns@bellsouth.net</email></para>
       </listitem>
 
       <listitem>
         <para>Godmar Back <email>gback@facility.cs.utah.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Goran Hammarback <email>goran@astro.uu.se</email></para>
       </listitem>
 
       <listitem>
         <para>Gord Matzigkeit <email>gord@enci.ucalgary.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Gordon Greeff <email>gvg@uunet.co.za</email></para>
       </listitem>
 
       <listitem>
         <para>Graham Wheeler <email>gram@cdsec.com</email></para>
       </listitem>
 
       <listitem>
         <para>Greg A. Woods <email>woods@zeus.leitch.com</email></para>
       </listitem>
 
       <listitem>
         <para>Greg Ansley <email>gja@ansley.com</email></para>
       </listitem>
 
       <listitem>
         <para>Greg Lewis <email>glewis@eyesbeyond.com</email></para>
       </listitem>
 
       <listitem>
         <para>Greg Robinson <email>greg@rosevale.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Greg Troxel <email>gdt@ir.bbn.com</email></para>
       </listitem>
 
       <listitem>
         <para>Greg Ungerer <email>gerg@stallion.oz.au</email></para>
       </listitem>
 
       <listitem>
         <para>Gregory Bond <email>gnb@itga.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Gregory D. Moncreaff
 	  <email>moncrg@bt340707.res.ray.com</email></para>
       </listitem>
 
       <listitem>
         <para>Guy Harris <email>guy@netapp.com</email></para>
       </listitem>
 
       <listitem>
         <para>HAMADA Naoki <email>hamada@astec.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Hammurabi Mendes <email>hmendes_br@yahoo.com</email></para>
       </listitem>
 
       <listitem>
         <para>Hannu Savolainen <email>hannu@voxware.pp.fi</email></para>
       </listitem>
 
       <listitem>
         <para>Hans Huebner <email>hans@artcom.de</email></para>
       </listitem>
 
       <listitem>
         <para>Hans Petter Bieker <email>zerium@webindex.no</email></para>
       </listitem>
 
       <listitem>
         <para>Hans Zuidam <email>hans@brandinnovators.com</email></para>
       </listitem>
 
       <listitem>
         <para>Harlan Stenn <email>Harlan.Stenn@pfcs.com</email></para>
       </listitem>
 
       <listitem>
         <para>Harold Barker <email>hbarker@dsms.com</email></para>
       </listitem>
 
       <listitem>
         <para>Harry Newton <email>harry_newton@telinco.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Havard Eidnes
 	  <email>Havard.Eidnes@runit.sintef.no</email></para>
       </listitem>
 
       <listitem>
         <para>Heath Nielson <email>heath@cs.byu.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Heikki Suonsivu <email>hsu@cs.hut.fi</email></para>
       </listitem>
 
       <listitem>
         <para>Heiko W. Rupp <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Helmut F. Wirth <email>hfwirth@ping.at</email></para>
       </listitem>
 
       <listitem>
         <para>Henrik Vestergaard Draboel
 	  <email>hvd@terry.ping.dk</email></para>
       </listitem>
 
       <listitem>
         <para>Herb Peyerl <email>hpeyerl@NetBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Hideaki Ohmon <email>ohmon@tom.sfc.keio.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Hidekazu Kuroki <email>hidekazu@cs.titech.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Hideki Yamamoto <email>hyama@acm.org</email></para>
       </listitem>
 
       <listitem>
         <para>Hideyuki Suzuki
 	  <email>hideyuki@sat.t.u-tokyo.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Hirayama Issei <email>iss@mail.wbs.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Hiroaki Sakai <email>sakai@miya.ee.kagu.sut.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Hiroharu Tamaru <email>tamaru@ap.t.u-tokyo.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Hironori Ikura <email>hikura@kaisei.org</email></para>
       </listitem>
 
       <listitem>
         <para>Hiroshi Nishikawa <email>nis@pluto.dti.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Hiroya Tsubakimoto <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>HIYAMA Takeshi <email>gibbon@cocoa.freemail.ne.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Holger Lamm <email>holger@eit.uni-kl.de</email></para>
       </listitem>
 
       <listitem>
         <para>Holger Veit <email>Holger.Veit@gmd.de</email></para>
       </listitem>
 
       <listitem>
         <para>Holm Tiffe <email>holm@geophysik.tu-freiberg.de</email></para>
       </listitem>
 
       <listitem>
         <para>HONDA Yasuhiro
 	  <email>honda@kashio.info.mie-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Horance Chou
 	  <email>horance@freedom.ie.cycu.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Horihiro Kumagai <email>kuma@jp.FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>HOSOBUCHI Noriyuki <email>hoso@buchi.tama.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>HOTARU-YA <email>hotaru@tail.net</email></para>
       </listitem>
 
       <listitem>
         <para>Hr.Ladavac <email>lada@ws2301.gud.siemens.co.at</email></para>
       </listitem>
 
       <listitem>
         <para>Hubert Feyrer <email>hubertf@NetBSD.ORG</email></para>
       </listitem>
 
       <listitem>
         <para>Hugh F. Mahon <email>hugh@nsmdserv.cnd.hp.com</email></para>
       </listitem>
 
       <listitem>
         <para>Hugh Mahon <email>h_mahon@fc.hp.com</email></para>
       </listitem>
 
       <listitem>
         <para>Hung-Chi Chu <email>hcchu@r350.ee.ntu.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Hye-Shik Chang <email>perky@fallin.lv</email></para>
       </listitem>
 
       <listitem>
         <para>Ian Holland <email>ianh@tortuga.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Ian Struble <email>ian@broken.net</email></para>
       </listitem>
 
       <listitem>
         <para>Ian Vaudrey <email>i.vaudrey@bigfoot.com</email></para>
       </listitem>
 
       <listitem>
         <para>Igor Khasilev <email>igor@jabber.paco.odessa.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Igor Pokrovsky <email>tiamat@telegraph.spb.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Igor Roshchin <email>str@giganda.komkon.org</email></para>
       </listitem>
 
       <listitem>
         <para>Igor Serikov <email>bt@turtle.pangeatech.com</email></para>
       </listitem>
 
       <listitem>
         <para>Igor Sviridov <email>siac@ua.net</email></para>
       </listitem>
 
       <listitem>
         <para>Igor Vinokurov <email>igor@zynaps.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Ikuo Nakagawa <email>ikuo@isl.intec.co.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Ilia Chipitsine <email>ilia@jane.cgu.chel.su</email></para>
       </listitem>
 
       <listitem>
         <para>Ilya V. Komarov <email>mur@lynx.ru</email></para>
       </listitem>
 
       <listitem>
         <para>IMAI Takeshi <email>take-i@ceres.dti.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>IMAMURA Tomoaki
 	  <email>tomoak-i@is.aist-nara.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Itsuro Saito <email>saito@miv.t.u-tokyo.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>IWASHITA Yoji <email>shuna@pop16.odn.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>J. Bryant <email>jbryant@argus.flash.net</email></para>
       </listitem>
 
       <listitem>
         <para>J. David Lowe <email>lowe@saturn5.com</email></para>
       </listitem>
 
       <listitem>
         <para>J. Han <email>hjh@photino.com</email></para>
       </listitem>
 
       <listitem>
         <para>J. Hawk <email>jhawk@MIT.EDU</email></para>
       </listitem>
 
       <listitem>
         <para>J.T. Conklin <email>jtc@cygnus.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jack <email>jack@zeus.xtalwind.net</email></para>
       </listitem>
 
       <listitem>
         <para>Jacob Bohn Lorensen <email>jacob@jblhome.ping.mk</email></para>
       </listitem>
 
       <listitem>
         <para>Jagane D Sundar <email>jagane@netcom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jake Hamby <email>jehamby@anobject.com</email></para>
       </listitem>
 
       <listitem>
         <para>James Clark <email>jjc@jclark.com</email></para>
       </listitem>
 
       <listitem>
         <para>James D. Stewart <email>jds@c4systm.com</email></para>
       </listitem>
 
       <listitem>
         <para>James da Silva <email>jds@cs.umd.edu</email></para>
       </listitem>
 
       <listitem>
         <para>James Jegers <email>jimj@miller.cs.uwm.edu</email></para>
       </listitem>
 
       <listitem>
         <para>James Raynard
 	  <email>fhackers@jraynard.demon.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>James T. Liu <email>jtliu@phlebas.rockefeller.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Jamie Heckford <email>jamie@jamiesdomain.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Jan Conard
 	  <email>charly@fachschaften.tu-muenchen.de</email></para>
       </listitem>
 
       <listitem>
         <para>Jan Jungnickel <email>Jan@Jungnickel.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jan Koum <email>jkb@FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Jan L. Peterson <email>jlp@flipdog.com</email></para>
       </listitem>
 
       <listitem>
         <para>Janick Taillandier
 	  <email>Janick.Taillandier@ratp.fr</email></para>
       </listitem>
 
       <listitem>
         <para>Janusz Kokot <email>janek@gaja.ipan.lublin.pl</email></para>
       </listitem>
 
       <listitem>
         <para>Jarle Greipsland <email>jarle@idt.unit.no</email></para>
       </listitem>
 
       <listitem>
         <para>Jason DiCioccio <email>geniusj@ods.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jason Garman <email>init@risen.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jason Harris <email>jharris@widomaker.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Jason R. Mastaler
 	  <email>jason-freebsd@mastaler.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jason Thorpe <email>thorpej@NetBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jason Wright <email>jason@OpenBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jason Young
 	  <email>doogie@forbidden-donut.anet-stl.com</email></para>
       </listitem>
 
       <listitem>
         <para>Javier Martin Rueda <email>jmrueda@diatel.upm.es</email></para>
       </listitem>
 
       <listitem>
         <para>Jay Fenlason <email>hack@datacube.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jay Krell <email>jay.krell@cornell.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Jaye Mathisen <email>mrcpu@cdsnet.net</email></para>
       </listitem>
 
       <listitem>
         <para>Jean-Sebastien Roy <email>js@jeannot.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jean-Yves Lefort <email>jylefort@brutele.be</email></para>
       </listitem>
 
       <listitem>
         <para>Jeff Bartig <email>jeffb@doit.wisc.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Jeff Brown <email>jabrown@caida.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jeff Forys <email>jeff@forys.cranbury.nj.us</email></para>
       </listitem>
 
       <listitem>
         <para>Jeff Kletsky <email>Jeff@Wagsky.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jeff Palmer <email>scorpio@drkshdw.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jeffrey Evans <email>evans@scnc.k12.mi.us</email></para>
       </listitem>
 
       <listitem>
         <para>Jeffrey Wheat <email>jeff@cetlink.net</email></para>
       </listitem>
 
       <listitem>
         <para>Jeremy Allison <email>jallison@whistle.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jeremy Chadwick <email>yoshi@parodius.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jeremy Chatfield <email>jdc@xinside.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jeremy Karlson <email>karlj000@unbc.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Jeremy Prior <email>unknown</email></para>
       </listitem>
 
       <listitem>
 	<para>Jeremy Shaffner <email>jeremy@external.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jesse McConnell <email>jesse@cylant.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jesse Rosenstock <email>jmr@ugcs.caltech.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Jian-Da Li <email>jdli@csie.nctu.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Babb <email>babb@FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Binkley <email>jrb@cs.pdx.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Bloom <email>bloom@acm.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Carroll <email>jim@carroll.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Flowers <email>jflowers@ezo.net</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Leppek <email>jleppek@harris.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Lowe <email>james@cs.uwm.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Mattson <email>jmattson@sonic.net</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Mercer <email>jim@komodo.reptiles.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Sloan <email>odinn@atlantabiker.net</email></para>
       </listitem>
 
       <listitem>
         <para>Jim Wilson <email>wilson@moria.cygnus.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jimbo Bahooli
 	  <email>griffin@blackhole.iceworld.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jin Guojun <email>jin@george.lbl.gov</email></para>
       </listitem>
 
       <listitem>
         <para>Joachim Kuebart <email>kuebart@mathematik.uni-ulm.de</email></para>
       </listitem>
 
       <listitem>
         <para>Joao Carlos Mendes Luis <email>jonny@jonny.eng.br</email></para>
       </listitem>
 
       <listitem>
         <para>Jochen Pohl <email>jpo.drs@sni.de</email></para>
       </listitem>
 
       <listitem>
         <para>Joe "Marcus" Clarke <email>marcus@marcuscom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Joe Abley <email>jabley@automagic.org</email></para>
       </listitem>
 
       <listitem>
         <para>Joe Halpin <email>joe.halpin@attbi.com</email></para>
       </listitem>
 
       <listitem>
         <para>Joe Jih-Shian Lu <email>jslu@dns.ntu.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Joe Orthoefer <email>j_orthoefer@tia.net</email></para>
       </listitem>
 
       <listitem>
         <para>Joe Traister <email>traister@mojozone.org</email></para>
       </listitem>
 
       <listitem>
         <para>Joel Faedi <email>Joel.Faedi@esial.u-nancy.fr</email></para>
       </listitem>
 
       <listitem>
         <para>Joel Ray Holveck <email>joelh@gnu.org</email></para>
       </listitem>
 
       <listitem>
         <para>Joel Sutton <email>jsutton@bbcon.com.au</email></para>
       </listitem>
 
       <listitem>
 	<para>Jordan DeLong <email>fracture@allusion.net</email></para>
       </listitem>
 
       <listitem>
 	<para>Joseph Scott <email>joseph@randomnetworks.com</email></para>
       </listitem>
 
       <listitem>
         <para>Johan Granlund <email>johan@granlund.nu</email></para>
       </listitem>
 
       <listitem>
         <para>Johan Karlsson <email>k@numeri.campus.luth.se</email></para>
       </listitem>
 
       <listitem>
         <para>Johan Larsson <email>johan@moon.campus.luth.se</email></para>
       </listitem>
 
       <listitem>
         <para>Johann Tonsing <email>jtonsing@mikom.csir.co.za</email></para>
       </listitem>
 
       <listitem>
         <para>Johannes 5 Joemann <email>joemann@beefree.free.de</email></para>
       </listitem>
 
       <listitem>
         <para>Johannes Helander <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Johannes Stille <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>John Beckett <email>jbeckett@southern.edu</email></para>
       </listitem>
 
       <listitem>
         <para>John Beukema <email>jbeukema@hk.super.net</email></para>
       </listitem>
 
       <listitem>
         <para>John Brezak <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>John Capo <email>jc@irbs.com</email></para>
       </listitem>
 
       <listitem>
         <para>John F. Woods <email>jfw@jfwhome.funhouse.com</email></para>
       </listitem>
 
       <listitem>
         <para>John Goerzen
 	  <email>jgoerzen@alexanderwohl.complete.org</email></para>
       </listitem>
 
       <listitem>
         <para>John Heidemann <email>johnh@isi.edu</email></para>
       </listitem>
 
       <listitem>
         <para>John Hood <email>cgull@owl.org</email></para>
       </listitem>
 
       <listitem>
         <para>John Kohl <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>John Lind <email>john@starfire.mn.org</email></para>
       </listitem>
 
       <listitem>
         <para>John Mackin <email>john@physiol.su.oz.au</email></para>
       </listitem>
 
       <listitem>
         <para>John Merryweather Cooper <email>jmcoopr@webmail.bmi.net</email></para>
       </listitem>
 
       <listitem>
         <para>John P <email>johnp@lodgenet.com</email></para>
       </listitem>
 
       <listitem>
         <para>John Perry <email>perry@vishnu.alias.net</email></para>
       </listitem>
 
       <listitem>
         <para>John Preisler <email>john@vapornet.com</email></para>
       </listitem>
 
       <listitem>
         <para>John Reynolds <email>jjreynold@home.com</email></para>
       </listitem>
 
       <listitem>
         <para>John Rochester <email>jr@cs.mun.ca</email></para>
       </listitem>
 
       <listitem>
         <para>John Sadler <email>john_sadler@alum.mit.edu</email></para>
       </listitem>
 
       <listitem>
         <para>John Saunders <email>john@pacer.nlc.net.au</email></para>
       </listitem>
 
       <listitem>
         <para>John Wehle <email>john@feith.com</email></para>
       </listitem>
 
       <listitem>
         <para>John Woods <email>jfw@eddie.mit.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Johny Mattsson <email>lonewolf@flame.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jon Morgan <email>morgan@terminus.trailblazer.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jonathan Belson <email>jon@witchspace.com</email></para>
       </listitem>
 
       <listitem>
         <para>Jonathan H N Chin <email>jc254@newton.cam.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Jonathan Hanna
 	  <email>jh@pc-21490.bc.rogers.wave.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Jonathan Pennington <email>john@coastalgeology.org</email></para>
       </listitem>
 
       <listitem>
         <para>Jorge Goncalves <email>j@bug.fe.up.pt</email></para>
       </listitem>
 
       <listitem>
         <para>Jorge M. Goncalves <email>ee96199@tom.fe.up.pt</email></para>
       </listitem>
 
       <listitem>
         <para>Jos Backus <email>jbackus@plex.nl</email></para>
       </listitem>
 
       <listitem>
 	<para>Jose Marques <email>jose@nobody.org</email></para>
       </listitem>
 
       <listitem>
         <para>Josef Grosch
 	  <email>jgrosch@superior.mooseriver.com</email></para>
       </listitem>
 
       <listitem>
         <para>Joseph Stein <email>joes@wstein.com</email></para>
       </listitem>
 
       <listitem>
         <para>Josh Gilliam <email>josh@quick.net</email></para>
       </listitem>
 
       <listitem>
         <para>Josh Tiefenbach <email>josh@ican.net</email></para>
       </listitem>
 
       <listitem>
 	<para>Jostein Trondal <email>jostein.trondal@sikkerhet.no</email></para>
       </listitem>
 
       <listitem>
         <para>Juergen Lock <email>nox@jelal.hb.north.de</email></para>
       </listitem>
 
       <listitem>
         <para>Juha Inkari <email>inkari@cc.hut.fi</email></para>
       </listitem>
 
       <listitem>
         <para>Jukka A. Ukkonen <email>jau@iki.fi</email></para>
       </listitem>
 
       <listitem>
         <para>Julian Assange <email>proff@suburbia.net</email></para>
       </listitem>
 
       <listitem>
         <para>Julian Coleman <email>j.d.coleman@ncl.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>&a.jhs;</para>
       </listitem>
 
       <listitem>
         <para>Julian Jenkins <email>kaveman@magna.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Junichi Satoh <email>junichi@jp.FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Junji SAKAI <email>sakai@jp.FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Junya WATANABE <email>junya-w@remus.dti.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Justas <email>justas@mbank.lv</email></para>
       </listitem>
 
       <listitem>
         <para>Justin Stanford <email>jus@security.za.net</email></para>
       </listitem>
 
       <listitem>
         <para>K.Higashino <email>a00303@cc.hc.keio.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Kai Vorma <email>vode@snakemail.hut.fi</email></para>
       </listitem>
 
       <listitem>
         <para>Kaleb S. Keithley <email>kaleb@ics.com</email></para>
       </listitem>
 
       <listitem>
         <para>Kaneda Hiloshi <email>vanitas@ma3.seikyou.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Kang-ming Liu <email>gugod@gugod.org</email></para>
       </listitem>
 
       <listitem>
         <para>Kapil Chowksey <email>kchowksey@hss.hns.com</email></para>
       </listitem>
 
       <listitem>
         <para>Karl Denninger <email>karl@mcs.com</email></para>
       </listitem>
 
       <listitem>
         <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para>
       </listitem>
 
       <listitem>
         <para>Karl Lehenbauer <email>karl@NeoSoft.com</email></para>
       </listitem>
 
       <listitem>
 	<para>KATO Tsuguru <email>tkato@prontomail.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Kawanobe Koh <email>kawanobe@st.rim.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Kees Jan Koster <email>kjk1@ukc.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Keith Bostic <email>bostic@bostic.com</email></para>
       </listitem>
 
       <listitem>
         <para>Keith E. Walker <email>kew@icehouse.net</email></para>
       </listitem>
 
 	<listitem>
         <para>Keith Moore <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Keith Sklower <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Ken Hornstein <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Ken Key <email>key@cs.utk.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Ken Mayer <email>kmayer@freegate.com</email></para>
       </listitem>
 
       <listitem>
         <para>Kenji Saito <email>marukun@mx2.nisiq.net</email></para>
       </listitem>
 
       <listitem>
         <para>Kenji Tomita <email>tommyk@da2.so-net.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Kenneth Furge <email>kenneth.furge@us.endress.com</email></para>
       </listitem>
 
       <listitem>
         <para>Kenneth Monville <email>desmo@bandwidth.org</email></para>
       </listitem>
 
       <listitem>
         <para>Kenneth R. Westerback <email>krw@tcn.net</email></para>
       </listitem>
 
       <listitem>
         <para>Kenneth Stailey <email>kstailey@gnu.ai.mit.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Kent Talarico <email>kent@shipwreck.tsoft.net</email></para>
       </listitem>
 
       <listitem>
         <para>Kent Vander Velden <email>graphix@iastate.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Kentaro Inagaki <email>JBD01226@niftyserve.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Kevin Bracey <email>kbracey@art.acorn.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Kevin Day <email>toasty@dragondata.com</email></para>
       </listitem>
 
       <listitem>
         <para>Kevin Lahey <email>kml@nas.nasa.gov</email></para>
       </listitem>
 
       <listitem>
         <para>Kevin Meltzer <email>perlguy@perlguy.com</email></para>
       </listitem>
 
       <listitem>
         <para>Kevin Street <email>street@iname.com</email></para>
       </listitem>
 
       <listitem>
         <para>Kevin Van Maren <email>vanmaren@fast.cs.utah.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Killer <email>killer@prosalg.no</email></para>
       </listitem>
 
       <listitem>
         <para>Kim Scarborough <email>sluggo@unknown.nu</email></para>
       </listitem>
 
       <listitem>
         <para>Kimura Fuyuki <email>fuyuki@mj.0038.net</email></para>
       </listitem>
 
       <listitem>
         <para>Kiril Mitev <email>kiril@ideaglobal.com</email></para>
       </listitem>
 
       <listitem>
         <para>Kiroh HARADA <email>kiroh@kh.rim.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Klaus Herrmann <email>klaus.herrmann@gmx.net</email></para>
       </listitem>
 
       <listitem>
         <para>Klaus Klein <email>kleink@layla.inka.de</email></para>
       </listitem>
 
       <listitem>
         <para>Klaus-J. Wolf <email>Yanestra@t-online.de</email></para>
       </listitem>
 
       <listitem>
         <para>Koichi Sato <email>copan@ppp.fastnet.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Konrad Heuer <email>kheuer@gwdu60.gwdg.de</email></para>
       </listitem>
 
       <listitem>
         <para>Konstantin Chuguev <email>Konstantin.Chuguev@dante.org.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Kostya Lukin <email>lukin@okbmei.msk.su</email></para>
       </listitem>
 
       <listitem>
         <para>Kouichi Hirabayashi <email>kh@mogami-wire.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Kris Dow <email>kris@vilnya.demon.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>KUNISHIMA Takeo <email>kunishi@c.oka-pu.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Kurt D. Zeilenga <email>Kurt@Boolean.NET</email></para>
       </listitem>
 
       <listitem>
         <para>Kurt Olsen <email>kurto@tiny.mcs.usu.edu</email></para>
       </listitem>
 
       <listitem>
         <para>L. Jonas Olsson
 	  <email>ljo@ljo-slip.DIALIN.CWRU.Edu</email></para>
       </listitem>
 
       <listitem>
         <para>Larry Altneu <email>larry@ALR.COM</email></para>
       </listitem>
 
       <listitem>
         <para>Lars Bernhardsson <email>lab@fnurt.net</email></para>
       </listitem>
 
       <listitem>
         <para>Lars K&ouml;ller
 	  <email>Lars.Koeller@Uni-Bielefeld.DE</email></para>
       </listitem>
 
       <listitem>
         <para>Laurence Lopez <email>lopez@mv.mv.com</email></para>
       </listitem>
 
       <listitem>
         <para>Lauri Watts <email>lauri@kde.org</email></para>
       </listitem>
 
       <listitem>
         <para>Lee Cremeans <email>lcremean@tidalwave.net</email></para>
       </listitem>
 
       <listitem>
         <para>Leo Kim <email>leo@florida.sarang.net</email></para>
       </listitem>
 
       <listitem>
         <para>Leo Serebryakov <email>lev@serebryakov.spb.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Liang Tai-hwa
 	  <email>avatar@www.mmlab.cse.yzu.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Lon Willett <email>lon%softt.uucp@math.utah.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Louis A. Mamakos <email>louie@TransSys.COM</email></para>
       </listitem>
 
       <listitem>
         <para>Louis Mamakos <email>loiue@TransSys.com</email></para>
       </listitem>
 
       <listitem>
         <para>Lowell Gilbert <email>lowell@world.std.com</email></para>
       </listitem>
 
       <listitem>
         <para>Lucas James <email>Lucas.James@ldjpc.apana.org.au</email></para>
       </listitem>
 
       <listitem>
         <para>Lyndon Nerenberg <email>lyndon@orthanc.ab.ca</email></para>
       </listitem>
 
       <listitem>
         <para>M. L. Dodson <email>bdodson@scms.utmb.EDU</email></para>
       </listitem>
 
       <listitem>
         <para>M.C. Wong <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Magnus Enbom <email>dot@tinto.campus.luth.se</email></para>
       </listitem>
 
       <listitem>
         <para>Mahesh Neelakanta <email>mahesh@gcomm.com</email></para>
       </listitem>
 
       <listitem>
         <para>Makoto WATANABE
 	  <email>watanabe@zlab.phys.nagoya-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Makoto YAMAKURA <email>makoto@pinpott.spnet.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Malte Lance <email>malte.lance@gmx.net</email></para>
       </listitem>
 
       <listitem>
         <para>Manu Iyengar
 	  <email>iyengar@grunthos.pscwa.psca.com</email></para>
       </listitem>
 
       <listitem>
         <para>Marc Frajola <email>marc@dev.com</email></para>
       </listitem>
 
       <listitem>
         <para>Marc Ramirez <email>mrami@mramirez.sy.yale.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Marc Slemko <email>marcs@znep.com</email></para>
       </listitem>
 
       <listitem>
         <para>Marc van Kempen <email>wmbfmk@urc.tue.nl</email></para>
       </listitem>
 
       <listitem>
 	<para>Marc van Woerkom <email>van.woerkom@netcologne.de</email></para>
       </listitem>
 
       <listitem>
 	<para>Marcin Cieslak <email>saper@system.pl</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Andrews <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Cammidge <email>mark@gmtunx.ee.uct.ac.za</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Diekhans <email>markd@grizzly.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Huizer <email>xaa@stack.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Mark J. Taylor <email>mtaylor@cybernet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Knight <email>markk@knigma.org</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Krentel <email>krentel@rice.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Mayo <email>markm@vmunix.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Thompson <email>thompson@tgsoft.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Tinguely <email>tinguely@plains.nodak.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Treacy <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Mark Valentine <email>mark@thuvia.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Markus Holmberg <email>saska@acc.umu.se</email></para>
       </listitem>
 
       <listitem>
         <para>Martin Birgmeier <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Martin Blapp <email>blapp@attic.ch</email></para>
       </listitem>
 
       <listitem>
         <para>Martin Hinner <email>mhi@linux.gyarab.cz</email></para>
       </listitem>
 
       <listitem>
         <para>Martin Ibert <email>mib@ppe.bb-data.de</email></para>
       </listitem>
 
       <listitem>
         <para>Martin Kammerhofer <email>dada@sbox.tu-graz.ac.at</email></para>
       </listitem>
 
       <listitem>
         <para>Martin Karlsson <email>martin.karlsson@visit.se</email></para>
       </listitem>
 
       <listitem>
         <para>Martin Matuska <email>matuska@wu-wien.ac.at</email></para>
       </listitem>
 
       <listitem>
 	<para>Martin Minkus <email>diskiller@cnbinc.com</email></para>
       </listitem>
 
       <listitem>
         <para>Martin Renters <email>martin@tdc.on.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Martti Kuparinen
 	  <email>martti.kuparinen@ericsson.com</email></para>
       </listitem>
 
       <listitem>
         <para>Masachika ISHIZUKA
 	  <email>ishizuka@isis.min.ntt.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Masahiro Sekiguchi
 	  <email>seki@sysrap.cs.fujitsu.co.jp</email></para>
       </listitem>
 
       <listitem>
          <para>Masahiro TAKEMURA
            <email>mastake@msel.t.u-tokyo.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Masanobu Saitoh <email>msaitoh@spa.is.uec.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Masanori Kanaoka <email>kana@saijo.mke.mei.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Masanori Kiriake <email>seiken@ARGV.AC</email></para>
       </listitem>
 
       <listitem>
         <para>Masatoshi TAMURA
 	  <email>tamrin@shinzan.kuee.kyoto-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Mats Lofkvist <email>mal@algonet.se</email></para>
       </listitem>
 
       <listitem>
         <para>Matt Bartley <email>mbartley@lear35.cytex.com</email></para>
       </listitem>
 
       <listitem>
         <para>Matt Heckaman <email>matt@LUCIDA.QC.CA</email></para>
       </listitem>
 
       <listitem>
         <para>Matt Thomas <email>matt@3am-software.com</email></para>
       </listitem>
 
       <listitem>
         <para>Matt White <email>mwhite+@CMU.EDU</email></para>
       </listitem>
 
       <listitem>
         <para>Matthew C. Mead <email>mmead@Glock.COM</email></para>
       </listitem>
 
       <listitem>
         <para>Matthew Cashdollar <email>mattc@rfcnet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Matthew Emmerton <email>root@gabby.gsicomp.on.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Matthew Flatt <email>mflatt@cs.rice.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Matthew Fuller <email>fullermd@futuresouth.com</email></para>
       </listitem>
 
       <listitem>
         <para>Matthew Stein <email>matt@bdd.net</email></para>
       </listitem>
 
       <listitem>
         <para>Matthew West <email>mwest@uct.ac.za</email></para>
       </listitem>
 
       <listitem>
         <para>Matthias Pfaller <email>leo@dachau.marco.de</email></para>
       </listitem>
 
       <listitem>
         <para>Matthias Scheler <email>tron@netbsd.org</email></para>
       </listitem>
 
       <listitem>
         <para>Matthias Sch&uuml;ndeh&uuml;tte
 	  <email>msch@snafu.de</email></para>
       </listitem>
 
       <listitem>
         <para>Mattias Gronlund
 	  <email>Mattias.Gronlund@sa.erisoft.se</email></para>
       </listitem>
 
       <listitem>
         <para>Mattias Pantzare <email>pantzer@ludd.luth.se</email></para>
       </listitem>
 
       <listitem>
         <para>Maurice Castro
 	  <email>maurice@planet.serc.rmit.edu.au</email></para>
       </listitem>
 
       <listitem>
         <para>Max Euston <email>meuston@jmrodgers.com</email></para>
       </listitem>
 
       <listitem>
         <para>Maxim Bolotin <email>max@rsu.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Micha Class
 	  <email>michael_class@hpbbse.bbn.hp.com</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Alyn Miller <email>malyn@strangeGizmo.com</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Lyngb&oslash;l <email>michael@lyngbol.dk</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Butler <email>imb@scgt.oz.au</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Butschky <email>butsch@computi.erols.com</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Clay <email>mclay@weareb.org</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Galassi <email>nerd@percival.rain.com</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Hancock <email>michaelh@cet.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Hohmuth <email>hohmuth@inf.tu-dresden.de</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Perlman <email>canuck@caam.rice.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Petry <email>petry@netwolf.NetMasters.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Michael Sardo <email>jaeger16@yahoo.com</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Searle <email>searle@longacre.demon.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Schout <email>mschout@gkg.net</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Urban <email>murban@tznet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Michael Vasilenko <email>acid@stu.cn.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Michal Listos <email>mcl@Amnesiac.123.org</email></para>
       </listitem>
 
       <listitem>
         <para>Michal Pasternak <email>doc@lublin.t1.pl</email></para>
       </listitem>
 
       <listitem>
         <para>Michio Karl Jinbo
 	  <email>karl@marcer.nagaokaut.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Miguel Angel Sagreras
 	  <email>msagre@cactus.fi.uba.ar</email></para>
       </listitem>
 
       <listitem>
         <para>Miguel Mendez <email>flynn@energyhq.homeip.net</email></para>
       </listitem>
 
       <listitem>
         <para>Mihoko Tanaka <email>m_tonaka@pa.yokogawa.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Mika Nystrom <email>mika@cs.caltech.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Mikael Hybsch <email>micke@dynas.se</email></para>
       </listitem>
 
       <listitem>
         <para>Mikael Karpberg
 	  <email>karpen@ocean.campus.luth.se</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Bristow <email>mike@urgle.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Del <email>repenting@hotmail.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Durian <email>durian@plutotech.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Durkin <email>mdurkin@tsoft.sf-bay.org</email></para>
       </listitem>
 
       <listitem>
         <para>Mike E. Matsnev <email>mike@azog.cs.msu.su</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Evans <email>mevans@candle.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Futerko <email>mike@LITech.lviv.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Grupenhoff <email>kashmir@umiacs.umd.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Harding <email>mvh@ix.netcom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Hibler <email>mike@marker.cs.utah.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Karels <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Mike McGaughey <email>mmcg@cs.monash.edu.au</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Meyer <email>mwm@mired.org</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Mitchell <email>mitchell@ref.tfs.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Murphy <email>mrm@alpharel.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Peck <email>mike@binghamton.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Sherwood <email>mike@fate.com</email></para>
       </listitem>
 
       <listitem>
         <para>Mike Spengler <email>mks@msc.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Mikhail A. Sokolov <email>mishania@demos.su</email></para>
       </listitem>
 
       <listitem>
         <para>Ming-I Hseh <email>PA@FreeBSD.ee.Ntu.edu.TW</email></para>
       </listitem>
 
       <listitem>
 	<para>Mitsuru Yoshida <email>mitsuru@riken.go.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Monte Mitzelfelt <email>monte@gonefishing.org</email></para>
       </listitem>
 
       <listitem>
         <para>Morgan Davis <email>root@io.cts.com</email></para>
       </listitem>
 
       <listitem>
         <para>MOROHOSHI Akihiko <email>moro@race.u-tokyo.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Mostyn Lewis <email>mostyn@mrl.com</email></para>
       </listitem>
 
       <listitem>
         <para>Motomichi Matsuzaki <email>mzaki@e-mail.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Motoyuki Kasahara <email>m-kasahr@sra.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>N.G.Smith <email>ngs@sesame.hensa.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Nadav Eiron <email>nadav@barcode.co.il</email></para>
       </listitem>
 
       <listitem>
         <para>NAGAO Tadaaki <email>nagao@cs.titech.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>NAKAJI Hiroyuki
 	  <email>nakaji@tutrp.tut.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>NAKAMURA Kazushi <email>nkazushi@highway.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>NAKAMURA Motonori
 	  <email>motonori@econ.kyoto-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>NAKATA, Maho <email>chat95@mbox.kyoto-inet.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Nanbor Wang <email>nw1@cs.wustl.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Naofumi Honda
 	  <email>honda@Kururu.math.sci.hokudai.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Narvi <email>narvi@haldjas.folklore.ee</email></para>
       </listitem>
 
       <listitem>
         <para>Nathan Dorfman <email>nathan@rtfm.net</email></para>
       </listitem>
 
       <listitem>
         <para>Neal Fachan <email>kneel@ishiboo.com</email></para>
       </listitem>
 
       <listitem>
         <para>Niall Smart <email>rotel@indigo.ie</email></para>
       </listitem>
 
       <listitem>
 	<para>Nicholas Esborn <email>nick@netdot.net</email></para>
       </listitem>
 
       <listitem>
         <para>Nick Barnes <email>Nick.Barnes@pobox.com</email></para>
       </listitem>
 
       <listitem>
         <para>Nick Handel <email>nhandel@NeoSoft.com</email></para>
       </listitem>
 
       <listitem>
         <para>Nick Hilliard <email>nick@foobar.org</email></para>
       </listitem>
 
       <listitem>
         <para>Nick Johnson <email>freebsd@spatula.net</email></para>
       </listitem>
 
       <listitem>
         <para>Nick Williams <email>njw@cs.city.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Nickolay N. Dudorov <email>nnd@itfs.nsk.su</email></para>
       </listitem>
 
       <listitem>
         <para>NIIMI Satoshi <email>sa2c@and.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Niklas Hallqvist <email>niklas@filippa.appli.se</email></para>
       </listitem>
 
       <listitem>
         <para>Nils M. Holm <email>nmh@t3x.org</email></para>
       </listitem>
 
       <listitem>
         <para>Nisha Talagala <email>nisha@cs.berkeley.edu</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>adrian@virginia.edu</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>alex@elvisti.kiev.ua</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>anto@netscape.net</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>bobson@egg.ics.nitch.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>bovynf@awe.be</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>burg@is.ge.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>chris@gnome.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>colsen@usa.net</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>coredump@nervosa.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>dannyman@arh0300.urh.uiuc.edu</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>davids@SECNET.COM</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>derek@free.org</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>devet@adv.IAEhv.nl</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>djv@bedford.net</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>dvv@sprint.net</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>enami@ba2.so-net.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>flash@eru.tubank.msk.su</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>flash@hway.ru</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>fn@pain.csrv.uidaho.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>No Name <email>frf@xocolatl.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>gclarkii@netport.neosoft.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>gordon@sheaky.lonestar.org</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>graaf@iae.nl</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>greg@greg.rim.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>grossman@cygnus.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>gusw@fub46.zedat.fu-berlin.de</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>hfir@math.rochester.edu</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>hnokubi@yyy.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>iaint@css.tuu.utas.edu.au</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>invis@visi.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>ishisone@sra.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>iverson@lionheart.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>jpt@magic.net</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>junker@jazz.snu.ac.kr</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>k-sugyou@ccs.mt.nec.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>kenji@reseau.toyonaka.osaka.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>kfurge@worldnet.att.net</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>lh@aus.org</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>lhecking@nmrc.ucc.ie</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>mrgreen@mame.mu.oz.au</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>nakagawa@jp.FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>ohki@gssm.otsuka.tsukuba.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>owaki@st.rim.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>pechter@shell.monmouth.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>pete@pelican.pelican.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>pritc003@maroon.tc.umn.edu</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>risner@stdio.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>roman@rpd.univ.kiev.ua</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>root@ns2.redline.ru</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>root@uglabgw.ug.cs.sunysb.edu</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>stephen.ma@jtec.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>sumii@is.s.u-tokyo.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>takas-su@is.aist-nara.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>tamone@eig.unige.ch</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>tjevans@raleigh.ibm.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>tony-o@iij.ad.jp amurai@spec.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>torii@tcd.hitachi.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>uenami@imasy.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>uhlar@netlab.sk</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>vode@hut.fi</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>wlloyd@mpd.ca</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>wlr@furball.wellsfargo.com</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>wmbfmk@urc.tue.nl</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>yamagata@nwgpc.kek.jp</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>ziggy@ryan.org</email></para>
       </listitem>
 
       <listitem>
         <para>No Name <email>ZW6T-KND@j.asahi-net.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Nobuhiro Yasutomi <email>nobu@psrc.isac.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Nobuyuki Koganemaru
 	  <email>kogane@koganemaru.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>NOKUBI Hirotaka <email>h-nokubi@yyy.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Norio Suzuki <email>nosuzuki@e-mail.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Noritaka Ishizumi <email>graphite@jp.FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Noriyuki Soda <email>soda@sra.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Oddbjorn Steffensen <email>oddbjorn@tricknology.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Oh Junseon <email>hollywar@mail.holywar.net</email></para>
       </listitem>
 
       <listitem>
         <para>Olaf Wagner <email>wagner@luthien.in-berlin.de</email></para>
       </listitem>
 
       <listitem>
         <para>Oleg Semyonov <email>os@altavista.net</email></para>
       </listitem>
 
       <listitem>
         <para>Oleg Sharoiko <email>os@rsu.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Oleg V. Volkov <email>rover@lglobus.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Olexander Kunytsa <email>kunia@wolf.istc.kiev.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Oliver Braun <email>obraun@informatik.unibw-muenchen.de</email></para>
       </listitem>
 
       <listitem>
         <para>Oliver Breuninger <email>ob@seicom.NET</email></para>
       </listitem>
 
       <listitem>
         <para>Oliver Friedrichs <email>oliver@secnet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Oliver Fromme
 	  <email>oliver.fromme@heim3.tu-clausthal.de</email></para>
       </listitem>
 
       <listitem>
         <para>Oliver Helmling
 	  <email>oliver.helmling@stud.uni-bayreuth.de</email></para>
       </listitem>
 
       <listitem>
         <para>Oliver Laumann
 	  <email>net@informatik.uni-bremen.de</email></para>
       </listitem>
 
       <listitem>
         <para>Oliver Lehmann
 	  <email>Kai_Allard_Liao@gmx.de</email></para>
       </listitem>
 
       <listitem>
         <para>Oliver Oberdorf <email>oly@world.std.com</email></para>
       </listitem>
 
       <listitem>
         <para>Olivier Tharan <email>olive@oban.frmug.org</email></para>
       </listitem>
 
       <listitem>
         <para>Olof Johansson <email>offe@ludd.luth.se</email></para>
       </listitem>
 
       <listitem>
         <para>Osokin Sergey aka oZZ <email>ozz@FreeBSD.org.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Pace Willisson <email>pace@blitz.com</email></para>
       </listitem>
 
       <listitem>
         <para>Paco Rosich <email>rosich@modico.eleinf.uv.es</email></para>
       </listitem>
 
       <listitem>
         <para>Palle Girgensohn <email>girgen@partitur.se</email></para>
       </listitem>
 
       <listitem>
         <para>Parag Patel <email>parag@cgt.com</email></para>
       </listitem>
 
       <listitem>
         <para>Pascal Pederiva <email>pascal@zuo.dec.com</email></para>
       </listitem>
 
       <listitem>
         <para>Pasvorn Boonmark <email>boonmark@juniper.net</email></para>
       </listitem>
 
       <listitem>
 	<para>Patrick Alken <email>cosine@ellipse.mcs.drexel.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Patrick Bihan-Faou <email>patrick@mindstep.com</email></para>
       </listitem>
 
       <listitem>
         <para>Patrick Hausen <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Patrick Seal <email>patseal@hyperhost.net</email></para>
       </listitem>
 
       <listitem>
         <para>Paul Antonov <email>apg@demos.su</email></para>
       </listitem>
 
       <listitem>
         <para>Paul F. Werkowski <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Paul Fox <email>pgf@foxharp.boston.ma.us</email></para>
       </listitem>
 
       <listitem>
         <para>Paul Koch <email>koch@thehub.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Paul Kranenburg <email>pk@NetBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Paul M. Lambert <email>plambert@plambert.net</email></para>
       </listitem>
 
       <listitem>
         <para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para>
       </listitem>
 
       <listitem>
         <para>Paul Popelka <email>paulp@uts.amdahl.com</email></para>
       </listitem>
 
       <listitem>
         <para>Paul S. LaFollette, Jr. <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Paul Sandys <email>myj@nyct.net</email></para>
       </listitem>
 
       <listitem>
         <para>Paul T. Root <email>proot@horton.iaces.com</email></para>
       </listitem>
 
       <listitem>
         <para>Paul Vixie <email>paul@vix.com</email></para>
       </listitem>
 
       <listitem>
         <para>Paolo Flag <email>flag@gufi.org</email></para>
       </listitem>
 
       <listitem>
         <para>Paulo Menezes <email>paulo@isr.uc.pt</email></para>
       </listitem>
 
       <listitem>
         <para>Paulo Menezes <email>pm@dee.uc.pt</email></para>
       </listitem>
 
       <listitem>
         <para>Pedro A M Vazquez <email>vazquez@IQM.Unicamp.BR</email></para>
       </listitem>
 
       <listitem>
         <para>Pedro Giffuni <email>giffunip@asme.org</email></para>
       </listitem>
 
       <listitem>
         <para>Per Wigren <email>wigren@home.se</email></para>
       </listitem>
 
       <listitem>
         <para>Pete Bentley <email>pete@demon.net</email></para>
       </listitem>
 
       <listitem>
         <para>Peter Childs <email>pjchilds@imforei.apana.org.au</email></para>
       </listitem>
 
       <listitem>
         <para>Peter Cornelius <email>pc@inr.fzk.de</email></para>
       </listitem>
 
       <listitem>
         <para>Peter Haight <email>peterh@prognet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Peter Jeremy <email>peter.jeremy@alcatel.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Peter M. Chen <email>pmchen@eecs.umich.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Peter Much <email>peter@citylink.dinoex.sub.org</email></para>
       </listitem>
 
       <listitem>
         <para>Peter Olsson <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Peter Philipp <email>pjp@bsd-daemon.net</email></para>
       </listitem>
 
       <listitem>
         <para>Peter Stubbs <email>PETERS@staidan.qld.edu.au</email></para>
       </listitem>
 
       <listitem>
 	<para>Peter van Heusden <email>pvh@wfeet.za.net</email></para>
       </listitem>
 
       <listitem>
         <para>Phil Maker <email>pjm@cs.ntu.edu.au</email></para>
       </listitem>
 
       <listitem>
         <para>Phil Sutherland
 	  <email>philsuth@mycroft.dialix.oz.au</email></para>
       </listitem>
 
       <listitem>
         <para>Phil Taylor <email>phil@zipmail.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Philip Musumeci <email>philip@rmit.edu.au</email></para>
       </listitem>
 
       <listitem>
         <para>Philippe Lefebvre <email>nemesis@balistik.net</email></para>
       </listitem>
 
       <listitem>
         <para>Pierre Y. Dampure <email>pierre.dampure@k2c.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Pius Fischer <email>pius@ienet.com</email></para>
       </listitem>
 
       <listitem>
         <para>Pomegranate <email>daver@flag.blackened.net</email></para>
       </listitem>
 
       <listitem>
         <para>Powerdog Industries
 	  <email>kevin.ruddy@powerdog.com</email></para>
       </listitem>
 
       <listitem>
         <para>Priit J&auml;rv <email>priit@cc.ttu.ee</email></para>
       </listitem>
 
       <listitem>
         <para>R Joseph Wright <email>rjoseph@mammalia.org</email></para>
       </listitem>
 
       <listitem>
         <para>R. Kym Horsell</para>
       </listitem>
 
       <listitem>
         <para>Radoslav Vasilev <email>rvasilev@uni-svishtov.bg</email></para>
       </listitem>
 
       <listitem>
         <para>Ralf Friedl <email>friedl@informatik.uni-kl.de</email></para>
       </listitem>
 
       <listitem>
         <para>Randal S. Masutani <email>randal@comtest.com</email></para>
       </listitem>
 
       <listitem>
         <para>Randall Hopper <email>rhh@ct.picker.com</email></para>
       </listitem>
 
       <listitem>
         <para>Randall W. Dean <email>rwd@osf.org</email></para>
       </listitem>
 
       <listitem>
         <para>Randy Bush <email>rbush@bainbridge.verio.net</email></para>
       </listitem>
 
       <listitem>
         <para>Rasmus Kaj <email>kaj@Raditex.se</email></para>
       </listitem>
 
       <listitem>
         <para>Reinier Bezuidenhout
 	  <email>rbezuide@mikom.csir.co.za</email></para>
       </listitem>
 
       <listitem>
         <para>Remy Card <email>Remy.Card@masi.ibp.fr</email></para>
       </listitem>
 
       <listitem>
         <para>Ricardas Cepas <email>rch@richard.eu.org</email></para>
       </listitem>
 
       <listitem>
         <para>Riccardo Veraldi <email>veraldi@cs.unibo.it</email></para>
       </listitem>
 
       <listitem>
         <para>Rich Wood <email>rich@FreeBSD.org.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Richard Henderson <email>richard@atheist.tamu.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Richard Hwang <email>rhwang@bigpanda.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Richard Kiss <email>richard@homemail.com</email></para>
       </listitem>
 
       <listitem>
         <para>Richard J Kuhns <email>rjk@watson.grauel.com</email></para>
       </listitem>
 
       <listitem>
         <para>Richard M. Neswold
 	  <email>rneswold@enteract.com</email></para>
       </listitem>
 
       <listitem>
         <para>Richard Seaman, Jr. <email>dick@tar.com</email></para>
       </listitem>
 
       <listitem>
         <para>Richard Stallman <email>rms@gnu.ai.mit.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Richard Straka <email>straka@user1.inficad.com</email></para>
       </listitem>
 
       <listitem>
         <para>Richard Tobin <email>richard@cogsci.ed.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Richard Wackerbarth <email>rkw@Dataplex.NET</email></para>
       </listitem>
 
       <listitem>
         <para>Richard Winkel <email>rich@math.missouri.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Richard Wiwatowski <email>rjwiwat@adelaide.on.net</email></para>
       </listitem>
 
       <listitem>
         <para>Rick Macklem <email>rick@snowhite.cis.uoguelph.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Rick Macklin <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Rob Austein <email>sra@epilogue.com</email></para>
       </listitem>
 
       <listitem>
         <para>Rob Mallory <email>rmallory@qualcomm.com</email></para>
       </listitem>
 
       <listitem>
         <para>Rob Snow <email>rsnow@txdirect.net</email></para>
       </listitem>
 
       <listitem>
         <para>Robert Crowe <email>bob@speakez.com</email></para>
       </listitem>
 
       <listitem>
         <para>Robert D. Thrush <email>rd@phoenix.aii.com</email></para>
       </listitem>
 
       <listitem>
         <para>Robert Eckardt
 	  <email>roberte@MEP.Ruhr-Uni-Bochum.de</email></para>
       </listitem>
 
       <listitem>
         <para>Robert P Ricci <email>ricci@cs.utah.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Robert Sanders <email>rsanders@mindspring.com</email></para>
       </listitem>
 
       <listitem>
         <para>Robert Sexton <email>robert@kudra.com</email></para>
       </listitem>
 
       <listitem>
         <para>Robert Shady <email>rls@id.net</email></para>
       </listitem>
 
       <listitem>
         <para>Robert Swindells <email>swindellsr@genrad.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Robert Withrow <email>witr@rwwa.com</email></para>
       </listitem>
 
       <listitem>
         <para>Robert Yoder <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Robin Carey
 	  <email>robin@mailgate.dtc.rankxerox.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Rod Taylor <email>rod@idiotswitch.org</email></para>
       </listitem>
 
       <listitem>
         <para>Roger Hardiman <email>roger@cs.strath.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Roland Jesse <email>jesse@cs.uni-magdeburg.de</email></para>
       </listitem>
 
       <listitem>
         <para>Roman Shterenzon <email>roman@xpert.com</email></para>
       </listitem>
 
       <listitem>
         <para>Ron Bickers <email>rbickers@intercenter.net</email></para>
       </listitem>
 
       <listitem>
         <para>Ron Lenk <email>rlenk@widget.xmission.com</email></para>
       </listitem>
 
       <listitem>
         <para>Ronald Kuehn <email>kuehn@rz.tu-clausthal.de</email></para>
       </listitem>
 
       <listitem>
         <para>Rudolf Cejka <email>cejkar@fit.vutbr.cz</email></para>
       </listitem>
 
       <listitem>
         <para>Ruslan Belkin <email>rus@home2.UA.net</email></para>
       </listitem>
 
       <listitem>
         <para>Ruslan Shevchenko <email>rssh@cam.grad.kiev.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Russell L. Carter <email>rcarter@pinyon.org</email></para>
       </listitem>
 
       <listitem>
         <para>Russell Vincent <email>rv@groa.uct.ac.za</email></para>
       </listitem>
 
       <listitem>
         <para>Ryan Younce <email>ryany@pobox.com</email></para>
       </listitem>
 
       <listitem>
         <para>Ryuichiro IMURA <email>imura@af.airnet.ne.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Sakai Hiroaki <email>sakai@miya.ee.kagu.sut.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Sakari Jalovaara <email>sja@tekla.fi</email></para>
       </listitem>
 
       <listitem>
         <para>Sam Hartman <email>hartmans@mit.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Samuel Lam <email>skl@ScalableNetwork.com</email></para>
       </listitem>
 
       <listitem>
         <para>Samuel Tardieu <email>sam@inf.enst.fr</email></para>
       </listitem>
 
       <listitem>
         <para>Samuele Zannoli <email>zannoli@cs.unibo.it</email></para>
       </listitem>
 
       <listitem>
 	<para>Sander Janssen <email>janssen@rendo.dekooi.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Sander Vesik <email>sander@haldjas.folklore.ee</email></para>
       </listitem>
 
       <listitem>
         <para>Sandro Sigala <email>ssigala@globalnet.it</email></para>
       </listitem>
 
       <listitem>
         <para>SANETO Takanori <email>sanewo@strg.sony.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>SASAKI Shunsuke <email>ele@pop17.odn.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Sascha Blank <email>blank@fox.uni-trier.de</email></para>
       </listitem>
 
       <listitem>
         <para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para>
       </listitem>
 
       <listitem>
         <para>Satoh Junichi <email>junichi@astec.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>SAWADA Mizuki <email>miz@qb3.so-net.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Scot Elliott <email>scot@poptart.org</email></para>
       </listitem>
 
       <listitem>
         <para>Scot W. Hetzel <email>hetzels@westbend.net</email></para>
       </listitem>
 
       <listitem>
         <para>Scott A. Kenney <email>saken@rmta.ml.org</email></para>
       </listitem>
 
       <listitem>
         <para>Scott A. Moberly <email>smoberly@xavier.dyndns.org</email></para>
       </listitem>
 
       <listitem>
         <para>Scott Blachowicz
 	  <email>scott.blachowicz@seaslug.org</email></para>
       </listitem>
 
       <listitem>
         <para>Scott Burris <email>scott@pita.cns.ucla.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Scott Hazen Mueller <email>scott@zorch.sf-bay.org</email></para>
       </listitem>
 
       <listitem>
         <para>Scott Michel <email>scottm@cs.ucla.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Scott Mitchel <email>scott@uk.FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Scott Reynolds <email>scott@clmqt.marquette.mi.us</email></para>
       </listitem>
 
       <listitem>
         <para>Sebastian Strollo <email>seb@erix.ericsson.se</email></para>
       </listitem>
 
       <listitem>
         <para>Serge V. Vakulenko <email>vak@zebub.msk.su</email></para>
       </listitem>
 
       <listitem>
         <para>Sergei Chechetkin <email>csl@whale.sunbay.crimea.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Sergei S. Laskavy <email>laskavy@pc759.cs.msu.su</email></para>
       </listitem>
 
       <listitem>
         <para>Sergey Gershtein <email>sg@mplik.ru</email></para>
       </listitem>
 
       <listitem>
 	<para>Sergey Kosyakov <email>ks@itp.ac.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Sergey N. Vorokov <email>serg@tmn.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Sergey Potapov <email>sp@alkor.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Sergey Samoyloff <email>gonza@techline.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Sergey Shkonda <email>serg@bcs.zp.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Sergey V.Dorokhov <email>svd@kbtelecom.nalnet.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Sergio Lenzi <email>lenzi@bsi.com.br</email></para>
       </listitem>
 
       <listitem>
         <para>Shaun Courtney <email>shaun@emma.eng.uct.ac.za</email></para>
       </listitem>
 
       <listitem>
         <para>Shawn M. Carey <email>smcarey@mailbox.syr.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Shell Hung <email>shell@shellhung.org</email></para>
       </listitem>
 
       <listitem>
         <para>Shigio Yamaguchi <email>shigio@tamacom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Shinya Esu <email>esu@yk.rim.or.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Shinya FUJIE <email>fujie@tk.elec.waseda.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Shuichi Tanaka <email>stanaka@bb.mbn.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Simon <email>simon@masi.ibp.fr</email></para>
       </listitem>
 
       <listitem>
         <para>Simon Burge <email>simonb@telstra.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Simon Dick <email>simond@irrelevant.org</email></para>
       </listitem>
 
       <listitem>
         <para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email></para>
       </listitem>
 
       <listitem>
         <para>Simon Marlow <email>simonm@dcs.gla.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Simon Shapiro <email>shimon@simon-shapiro.org</email></para>
       </listitem>
 
       <listitem>
         <para>Sin'ichiro MIYATANI <email>siu@phaseone.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email></para>
       </listitem>
 
       <listitem>
         <para>Soochon Radee <email>slr@mitre.org</email></para>
       </listitem>
 
       <listitem>
         <para>Soren Dayton <email>csdayton@midway.uchicago.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Soren Dossing <email>sauber@netcom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Soren S. Jorvang <email>soren@wheel.dk</email></para>
       </listitem>
 
       <listitem>
         <para>Stefan Bethke <email>stb@hanse.de</email></para>
       </listitem>
 
       <listitem>
         <para>Stefan Eggers <email>seggers@semyam.dinoco.de</email></para>
       </listitem>
 
       <listitem>
         <para>Stefan Moeding <email>s.moeding@ndh.net</email></para>
       </listitem>
 
       <listitem>
         <para>Stefan Petri <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Stefan `Sec` Zehl <email>sec@42.org</email></para>
       </listitem>
 
       <listitem>
         <para>Steinar Haug <email>sthaug@nethelp.no</email></para>
       </listitem>
 
       <listitem>
         <para>Stephane E. Potvin <email>sepotvin@videotron.ca</email></para>
       </listitem>
 
       <listitem>
         <para>Stephane Legrand <email>stephane@lituus.fr</email></para>
       </listitem>
 
       <listitem>
         <para>Stephen Clawson
 	  <email>sclawson@marker.cs.utah.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Stephen F. Combs <email>combssf@salem.ge.com</email></para>
       </listitem>
 
       <listitem>
         <para>Stephen Farrell <email>stephen@farrell.org</email></para>
       </listitem>
 
       <listitem>
         <para>Stephen Hocking <email>sysseh@devetir.qld.gov.au</email></para>
       </listitem>
 
       <listitem>
         <para>Stephen J. Roznowski <email>sjr@home.net</email></para>
       </listitem>
 
       <listitem>
         <para>Stephen McKay <email>syssgm@devetir.qld.gov.au</email></para>
       </listitem>
 
       <listitem>
         <para>Stephen Melvin <email>melvin@zytek.com</email></para>
       </listitem>
 
       <listitem>
         <para>Steve Bauer <email>sbauer@rock.sdsmt.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Steve Coltrin <email>spcoltri@unm.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Steve Deering <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Steve Gerakines <email>steve2@genesis.tiac.net</email></para>
       </listitem>
 
       <listitem>
         <para>Steve Gericke <email>steveg@comtrol.com</email></para>
       </listitem>
 
       <listitem>
         <para>Steve Piette <email>steve@simon.chi.il.US</email></para>
       </listitem>
 
       <listitem>
         <para>Steve Schwarz <email>schwarz@alpharel.com</email></para>
       </listitem>
 
       <listitem>
         <para>Steven Enderle <email>panic@subphase.de</email></para>
       </listitem>
 
       <listitem>
         <para>Steven G. Kargl
 	  <email>kargl@troutmask.apl.washington.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Steven H. Samorodin <email>samorodi@NUXI.com</email></para>
       </listitem>
 
       <listitem>
         <para>Steven McCanne <email>mccanne@cs.berkeley.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Steven Plite <email>splite@purdue.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Steven Wallace <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Stijn Hoop <email>stijn@win.tue.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Stuart Henderson
 	  <email>stuart@internationalschool.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Sue Blake <email>sue@welearn.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Sugimoto Sadahiro <email>ixtl@komaba.utmc.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>SUGIMURA Takashi <email>sugimura@jp.FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Sugiura Shiro <email>ssugiura@duo.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Sujal Patel <email>smpatel@wam.umd.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Sungman Cho <email>smcho@tsp.korea.ac.kr</email></para>
       </listitem>
 
       <listitem>
         <para>Sune Stjerneby <email>stjerneby@usa.net</email></para>
       </listitem>
 
       <listitem>
         <para>SURANYI Peter
 	  <email>suranyip@jks.is.tsukuba.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Suzuki Yoshiaki
 	  <email>zensyo@ann.tama.kawasaki.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Svein Skogen
           <email>tds@dmnshq.net</email></para>
       </listitem>
 
       <listitem>
         <para>Sybolt de Boer <email>bolt@xs4all.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Tadashi Kumano <email>kumano@strl.nhk.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Taguchi Takeshi <email>taguchi@tohoku.iij.ad.jp</email></para>
       </listitem>
 
       <listitem>
         <para>TAKAHASHI Kaoru <email>kaoru@kaisei.org</email></para>
       </listitem>
 
       <listitem>
         <para>Takahiro Yugawa <email>yugawa@orleans.rim.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Takashi Mega <email>mega@minz.org</email></para>
       </listitem>
 
       <listitem>
         <para>Takashi Uozu <email>j1594016@ed.kagu.sut.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Takayuki Ariga <email>a00821@cc.hc.keio.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Takeru NAIKI <email>naiki@bfd.es.hokudai.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Takeshi Amaike <email>amaike@iri.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Takeshi MUTOH <email>mutoh@info.nara-k.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Takeshi Ohashi
 	  <email>ohashi@mickey.ai.kyutech.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Takeshi WATANABE
 	  <email>watanabe@crayon.earth.s.kobe-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Takuya SHIOZAKI
 	  <email>tshiozak@makino.ise.chuo-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Tatoku Ogaito <email>tacha@tera.fukui-med.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Tatsuya Kudoh <email>cdr@cosmonet.org</email></para>
       </listitem>
 
       <listitem>
         <para>Ted Buswell <email>tbuswell@mediaone.net</email></para>
       </listitem>
 
       <listitem>
         <para>Ted Faber <email>faber@isi.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Ted Lemon <email>mellon@isc.org</email></para>
       </listitem>
 
       <listitem>
         <para>Terry Lambert <email>terry@lambert.org</email></para>
       </listitem>
 
       <listitem>
         <para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Teruaki Ata <email>PFA03027@nifty.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Tetsuya Furukawa <email>tetsuya@secom-sis.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Theo de Raadt <email>deraadt@OpenBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas <email>thomas@mathematik.uni-Bremen.de</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas D. Dean <email>tomdean@ix.netcom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas David Rivers <email>rivers@dignus.com</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas E. Zander <email>rriggs@f113.hadiko.de</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas G. McWilliams <email>tgm@netcom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas Graichen
 	  <email>graichen@omega.physik.fu-berlin.de</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas K&ouml;nig
 	  <email>Thomas.Koenig@ciw.uni-karlsruhe.de</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas Ptacek <email>unknown</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas Quinot <email>thomas@cuivre.fr.eu.org</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas A. Stephens <email>tas@stephens.org</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas Stromberg <email>tstrombe@rtci.com</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas Valentino Crimi
 	  <email>tcrimi+@andrew.cmu.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Thomas Wintergerst <email>thomas@lemur.nord.de</email></para>
       </listitem>
 
       <listitem>
         <para>&THORN;&oacute;r&eth;ur &Iacute;varsson
 	  <email>totii@est.is</email></para>
       </listitem>
 
       <listitem>
         <para>Thierry Thomas <email>tthomas@mail.dotcom.fr</email></para>
       </listitem>
 
       <listitem>
         <para>Timothy Jensen <email>toast@blackened.com</email></para>
       </listitem>
 
       <listitem>
         <para>Tim J. Robbins <email>tim@robbins.dropbear.id.au</email></para>
       </listitem>
 
       <listitem>
         <para>Tim Kientzle <email>kientzle@netcom.com</email></para>
       </listitem>
 
       <listitem>
         <para>Tim Singletary
 	  <email>tsingle@sunland.gsfc.nasa.gov</email></para>
       </listitem>
 
       <listitem>
         <para>Tim Wilkinson <email>tim@sarc.city.ac.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Timo J. Rinne <email>tri@iki.fi</email></para>
       </listitem>
 
       <listitem>
         <para>Tobias Reifenberger <email>treif@mayn.de</email></para>
       </listitem>
 
       <listitem>
         <para>Todd Miller <email>millert@openbsd.org</email></para>
       </listitem>
 
       <listitem>
         <para>Tom <email>root@majestix.cmr.no</email></para>
       </listitem>
 
       <listitem>
         <para>Tom <email>tom@sdf.com</email></para>
       </listitem>
 
       <listitem>
         <para>Tom Gray - DCA <email>dcasba@rain.org</email></para>
       </listitem>
 
       <listitem>
         <para>Tom Jobbins <email>tom@tom.tj</email></para>
       </listitem>
 
       <listitem>
         <para>Tom Pusateri <email>pusateri@juniper.net</email></para>
       </listitem>
 
       <listitem>
         <para>Tom Rhodes <email>darklogik@pittgoth.com</email></para>
       </listitem>
 
       <listitem>
         <para>Tom Rush <email>tarush@mindspring.com</email></para>
       </listitem>
 
       <listitem>
         <para>Tom Samplonius <email>tom@misery.sdf.com</email></para>
       </listitem>
 
       <listitem>
         <para>Tomohiko Kurahashi
 	  <email>kura@melchior.q.t.u-tokyo.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Tony Kimball <email>alk@Think.COM</email></para>
       </listitem>
 
       <listitem>
         <para>Tony Li <email>tli@jnx.com</email></para>
       </listitem>
 
       <listitem>
         <para>Tony Lynn <email>wing@cc.nsysu.edu.tw</email></para>
       </listitem>
 
       <listitem>
 	<para>Tony Maher <email>tonym@biolateral.com.au</email></para>
       </listitem>
 
       <listitem>
         <para>Torbjorn Granlund <email>tege@matematik.su.se</email></para>
       </listitem>
 
       <listitem>
         <para>Toshihiko SHIMOKAWA <email>toshi@tea.forus.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Toshihiro Kanda <email>candy@kgc.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Toshiomi Moriki
 	  <email>Toshiomi.Moriki@ma1.seikyou.ne.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Trefor S. <email>trefor@flevel.co.uk</email></para>
       </listitem>
 
       <listitem>
         <para>Trenton Schulz <email>twschulz@cord.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Trevor Blackwell <email>tlb@viaweb.com</email></para>
       </listitem>
 
       <listitem>
         <para>Udo Schweigert <email>ust@cert.siemens.de</email></para>
       </listitem>
 
       <listitem>
         <para>Ugo Paternostro <email>paterno@dsi.unifi.it</email></para>
       </listitem>
 
       <listitem>
         <para>Ulf Kieber <email>kieber@sax.de</email></para>
       </listitem>
 
       <listitem>
         <para>Ulli Linzen <email>ulli@perceval.camelot.de</email></para>
       </listitem>
 
       <listitem>
         <para>URATA Shuichiro <email>s-urata@nmit.tmg.nec.co.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Uwe Arndt <email>arndt@mailhost.uni-koblenz.de</email></para>
       </listitem>
 
       <listitem>
         <para>Uwe Pierau <email>uwe.pierau@tu-clausthal.de</email></para>
       </listitem>
 
       <listitem>
         <para>Vadim Belman <email>voland@catpipe.net</email></para>
       </listitem>
 
       <listitem>
         <para>Vadim Chekan <email>vadim@gc.lviv.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Vadim Kolontsov <email>vadim@tversu.ac.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Vadim Mikhailov <email>mvp@braz.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Valentin Nechayev <email>netch@lucky.net</email></para>
       </listitem>
 
       <listitem>
         <para>Van Jacobson <email>van@ee.lbl.gov</email></para>
       </listitem>
 
       <listitem>
         <para>Vasily V. Grechishnikov
 	  <email>bazilio@ns1.ied-vorstu.ac.ru</email></para>
       </listitem>
 
       <listitem>
         <para>Vasim Valejev <email>vasim@uddias.diaspro.com</email></para>
       </listitem>
 
       <listitem>
         <para>Vassili Tchersky <email>vt@bsd-fr.org</email></para>
       </listitem>
 
       <listitem>
         <para>Vernon J. Schryver <email>vjs@mica.denver.sgi.com</email></para>
       </listitem>
 
       <listitem>
         <para>Veselin Slavov <email>vess@btc.net</email></para>
       </listitem>
 
       <listitem>
         <para>Vic Abell <email>abe@cc.purdue.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Ville Eerola <email>ve@sci.fi</email></para>
       </listitem>
 
       <listitem>
         <para>Vince Valenti <email>vince@blue-box.net</email></para>
       </listitem>
 
       <listitem>
         <para>Vincent Poy <email>vince@venus.gaianet.net</email></para>
       </listitem>
 
       <listitem>
         <para>Vincenzo Capuano
 	  <email>VCAPUANO@vmprofs.esoc.esa.de</email></para>
       </listitem>
 
       <listitem>
         <para>Virgil Champlin <email>champlin@pa.dec.com</email></para>
       </listitem>
 
       <listitem>
         <para>Vladimir A. Jakovenko
 	  <email>vovik@ntu-kpi.kiev.ua</email></para>
       </listitem>
 
       <listitem>
         <para>Vladimir Kushnir <email>kushn@mail.kar.net</email></para>
       </listitem>
 
       <listitem>
         <para>Vladimir Savichev <email>vlad@ariel.phys.wesleyan.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Vsevolod Lobko <email>seva@alex-ua.com</email></para>
       </listitem>
 
       <listitem>
         <para>W. Gerald Hicks <email>wghicks@bellsouth.net</email></para>
       </listitem>
 
       <listitem>
         <para>W. Richard Stevens <email>rstevens@noao.edu</email></para>
       </listitem>
 
       <listitem>
         <para>Walt Howard <email>howard@ee.utah.edu</email></para>
       </listitem>
 
       <listitem>
        <para>Walt M. Shandruk <email>walt@erudition.net</email</para>
       </listitem>
 
       <listitem>
         <para>Warren Toomey <email>wkt@csadfa.cs.adfa.oz.au</email></para>
       </listitem>
 
       <listitem>
         <para>Wayne Scott <email>wscott@ichips.intel.com</email></para>
       </listitem>
 
       <listitem>
         <para>Werner Griessl
 	  <email>werner@btp1da.phy.uni-bayreuth.de</email></para>
       </listitem>
 
       <listitem>
         <para>Wes Santee <email>wsantee@wsantee.oz.net</email></para>
       </listitem>
 
       <listitem>
         <para>Wietse Venema <email>wietse@wzv.win.tue.nl</email></para>
       </listitem>
 
       <listitem>
         <para>Wiljo Heinen <email>wiljo@freeside.ki.open.de</email></para>
       </listitem>
 
       <listitem>
         <para>Willem Jan Withagen <email>wjw@surf.IAE.nl</email></para>
       </listitem>
 
       <listitem>
         <para>William Jolitz <email>withheld</email></para>
       </listitem>
 
       <listitem>
         <para>William Liao <email>william@tale.net</email></para>
       </listitem>
 
       <listitem>
         <para>Wojtek Pilorz
 	  <email>wpilorz@celebris.bdk.lublin.pl</email></para>
       </listitem>
 
       <listitem>
         <para>Wolfgang Helbig <email>helbig@ba-stuttgart.de</email></para>
       </listitem>
 
       <listitem>
         <para>Wolfgang Solfrank <email>ws@tools.de</email></para>
       </listitem>
 
       <listitem>
         <para>Wolfgang Stanglmeier <email>wolf@FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
         <para>Wu Ching-hong <email>woju@FreeBSD.ee.Ntu.edu.TW</email></para>
       </listitem>
 
       <listitem>
         <para>&a.wylie;</para>
       </listitem>
 
       <listitem>
         <para>Yannis Kotsinos <email>zookie@med.auth.gr</email></para>
       </listitem>
 
       <listitem>
         <para>Yarema <email>yds@ingress.com</email></para>
       </listitem>
 
       <listitem>
         <para>Yaroslav Terletsky <email>ts@polynet.lviv.ua</email></para>
       </listitem>
 
       <listitem>
 	<para>Yasuhiro Fukama <email>yasuf@big.or.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yasuhito FUTATSUKI <email>futatuki@fureai.or.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Yen-Ming Lee <email>leeym@bsd.ce.ntu.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Yen-Shuo Su <email>yssu@CCCA.NCTU.edu.tw</email></para>
       </listitem>
 
       <listitem>
 	<para>Yin-Jieh Chen <email>yinjieh@Crazyman.Dorm13.NCTU.edu.tw</email></para>
       </listitem>
 
       <listitem>
         <para>Yixin Jin <email>yjin@rain.cs.ucla.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Yoichi Asai <email>yatt@msc.biglobe.ne.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yonatan Bokovza <email>Yonatan@xpert.com</email>
       </listitem>
 
       <listitem>
 	<para>Yoshiaki Uchikawa <email>yoshiaki@kt.rim.or.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yoshihiko SARUMRU <email>mistral@imasy.or.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yoshihisa NAKAGAWA
 	  <email>y-nakaga@ccs.mt.nec.co.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yoshikazu Goto <email>gotoh@ae.anritsu.co.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yoshimasa Ohnishi
 	  <email>ohnishi@isc.kyutech.ac.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yoshishige Arai <email>ryo2@on.rim.or.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yuichi MATSUTAKA <email>matutaka@osa.att.ne.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yujiro MIYATA
 	  <email>miyata@bioele.nuee.nagoya-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
         <para>Yu-Shun Wang <email>yushunwa@isi.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Yusuke Nawano <email>azuki@azkey.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Yuu Yashiki <email>s974123@cc.matsuyama-u.ac.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yuuki SAWADA <email>mami@whale.cc.muroran-it.ac.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yuuichi Narahara <email>aconitum@po.teleway.ne.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para>
       </listitem>
 
       <listitem>
 	<para>Yves Fonk <email>yves@cpcoup5.tn.tudelft.nl</email></para>
       </listitem>
 
       <listitem>
 	<para>Yves Fonk <email>yves@dutncp8.tn.tudelft.nl</email></para>
       </listitem>
 
       <listitem>
 	<para>Zach Heilig <email>zach@gaffaneys.com</email></para>
       </listitem>
 
       <listitem>
         <para>Zach Zurflu <email>zach@pabst.bendnet.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Zahemszhky Gabor <email>zgabor@code.hu</email></para>
       </listitem>
 
       <listitem>
 	<para>Zhong Ming-Xun <email>zmx@mail.CDPA.nsysu.edu.tw</email></para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="contrib-386bsd">
     <title>386BSD Patch Kit Patch Contributors</title>
 
     <para>(in alphabetical order by first name):</para>
 
     <itemizedlist>
       <listitem>
 	<para>Adam Glass <email>glass@postgres.berkeley.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Adrian Hall <email>ahall@mirapoint.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Andrey A. Chernov <email>ache@astral.msk.su</email></para>
       </listitem>
 
       <listitem>
 	<para>Andrew Herbert <email>andrew@werple.apana.org.au</email></para>
       </listitem>
 
       <listitem>
 	<para>Andrew Moore <email>alm@netcom.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Andy Valencia <email>ajv@csd.mot.com</email>
 	  <email>jtk@netcom.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Arne Henrik Juul <email>arnej@Lise.Unit.NO</email></para>
       </listitem>
 
       <listitem>
 	<para>Bakul Shah <email>bvs@bitblocks.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Barry Lustig <email>barry@ictv.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Bob Wilcox <email>bob@obiwan.uucp</email></para>
       </listitem>
 
       <listitem>
 	<para>Branko Lankester</para>
       </listitem>
 
       <listitem>
 	<para>Brett Lymn <email>blymn@mulga.awadi.com.AU</email></para>
       </listitem>
 
       <listitem>
 	<para>Charles Hannum <email>mycroft@ai.mit.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Chris G. Demetriou
 	  <email>cgd@postgres.berkeley.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Chris Torek <email>torek@ee.lbl.gov</email></para>
       </listitem>
 
       <listitem>
 	<para>Christoph Robitschko
 	  <email>chmr@edvz.tu-graz.ac.at</email></para>
       </listitem>
 
       <listitem>
 	<para>Daniel Poirot <email>poirot@aio.jsc.nasa.gov</email></para>
       </listitem>
 
       <listitem>
 	<para>Dave Burgess <email>burgess@hrd769.brooks.af.mil</email></para>
       </listitem>
 
       <listitem>
 	<para>Dave Rivers <email>rivers@ponds.uucp</email></para>
       </listitem>
 
       <listitem>
 	<para>David Dawes <email>dawes@physics.su.OZ.AU</email></para>
       </listitem>
 
       <listitem>
 	<para>David Greenman <email>dg@Root.COM</email></para>
       </listitem>
 
       <listitem>
 	<para>Eric J. Haug <email>ejh@slustl.slu.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Felix Gaehtgens
 	  <email>felix@escape.vsse.in-berlin.de</email></para>
       </listitem>
 
       <listitem>
 	<para>Frank Maclachlan <email>fpm@crash.cts.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Gary A. Browning <email>gab10@griffcd.amdahl.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Gary Howland <email>gary@hotlava.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Geoff Rehmet <email>csgr@alpha.ru.ac.za</email></para>
       </listitem>
 
       <listitem>
 	<para>Goran Hammarback <email>goran@astro.uu.se</email></para>
       </listitem>
 
       <listitem>
 	<para>Guido van Rooij <email>guido@gvr.org</email></para>
       </listitem>
 
       <listitem>
         <para>Guy Antony Halse <email>guy@rucus.ru.ac.za</email></para>
       </listitem>
 
       <listitem>
 	<para>Guy Harris <email>guy@auspex.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Havard Eidnes
 	  <email>Havard.Eidnes@runit.sintef.no</email></para>
       </listitem>
 
       <listitem>
 	<para>Herb Peyerl <email>hpeyerl@novatel.cuc.ab.ca</email></para>
       </listitem>
 
       <listitem>
 	<para>Holger Veit <email>Holger.Veit@gmd.de</email></para>
       </listitem>
 
       <listitem>
 	<para>Ishii Masahiro, R. Kym Horsell</para>
       </listitem>
 
       <listitem>
 	<para>J.T. Conklin <email>jtc@cygnus.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Jagane D Sundar <email>jagane@netcom.com</email></para>
       </listitem>
 
       <listitem>
 	<para>James Clark <email>jjc@jclark.com</email></para>
       </listitem>
 
       <listitem>
 	<para>James Jegers <email>jimj@miller.cs.uwm.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>James W. Dolter</para>
       </listitem>
 
       <listitem>
 	<para>James da Silva <email>jds@cs.umd.edu</email> et al</para>
       </listitem>
 
       <listitem>
 	<para>Jay Fenlason <email>hack@datacube.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Jim Wilson <email>wilson@moria.cygnus.com</email></para>
       </listitem>
 
       <listitem>
 	<para>J&ouml;rg Lohse
 	  <email>lohse@tech7.informatik.uni-hamburg.de</email></para>
       </listitem>
 
       <listitem>
 	<para>J&ouml;rg Wunsch
 	  <email>joerg_wunsch@uriah.heep.sax.de</email></para>
       </listitem>
 
       <listitem>
 	<para>John Dyson</para>
       </listitem>
 
       <listitem>
 	<para>John Woods <email>jfw@eddie.mit.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Jordan K. Hubbard <email>jkh@whisker.hubbard.ie</email></para>
       </listitem>
 
       <listitem>
 	<para>Julian Elischer <email>julian@dialix.oz.au</email></para>
       </listitem>
 
       <listitem>
 	<para>Julian Stacey <email>jhs@FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Karl Lehenbauer <email>karl@NeoSoft.com</email>
 	  <email>karl@one.neosoft.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Keith Bostic <email>bostic@toe.CS.Berkeley.EDU</email></para>
       </listitem>
 
       <listitem>
 	<para>Ken Hughes</para>
       </listitem>
 
       <listitem>
 	<para>Kent Talarico <email>kent@shipwreck.tsoft.net</email></para>
       </listitem>
 
       <listitem>
 	<para>Kevin Lahey <email>kml%rokkaku.UUCP@mathcs.emory.edu</email>
 	  <email>kml@mosquito.cis.ufl.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Konstantinos Konstantinidis <email>kkonstan@duth.gr</email></para>
       </listitem>
 
       <listitem>
 	<para>Marc Frajola <email>marc@dev.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Mark Tinguely <email>tinguely@plains.nodak.edu</email>
 	  <email>tinguely@hookie.cs.ndsu.NoDak.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Martin Renters <email>martin@tdc.on.ca</email></para>
       </listitem>
 
       <listitem>
 	<para>Michael Clay <email>mclay@weareb.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Michael Galassi <email>nerd@percival.rain.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Mike Durkin <email>mdurkin@tsoft.sf-bay.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Naoki Hamada <email>nao@tom-yam.or.jp</email></para>
       </listitem>
 
       <listitem>
 	<para>Nate Williams <email>nate@bsd.coe.montana.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Nick Handel <email>nhandel@NeoSoft.com</email>
 	  <email>nick@madhouse.neosoft.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Pace Willisson <email>pace@blitz.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Paul Kranenburg <email>pk@cs.few.eur.nl</email></para>
       </listitem>
 
       <listitem>
 	<para>Paul Mackerras <email>paulus@cs.anu.edu.au</email></para>
       </listitem>
 
       <listitem>
 	<para>Paul Popelka <email>paulp@uts.amdahl.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Peter da Silva <email>peter@NeoSoft.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Phil Sutherland
 	  <email>philsuth@mycroft.dialix.oz.au</email></para>
       </listitem>
 
       <listitem>
 	<para>Poul-Henning Kamp <email>phk@FreeBSD.org</email></para>
       </listitem>
 
       <listitem>
 	<para>Ralf Friedl <email>friedl@informatik.uni-kl.de</email></para>
       </listitem>
 
       <listitem>
 	<para>Rick Macklem <email>root@snowhite.cis.uoguelph.ca</email></para>
       </listitem>
 
       <listitem>
 	<para>Robert D. Thrush <email>rd@phoenix.aii.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Rodney W. Grimes <email>rgrimes@cdrom.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Sascha Wildner <email>swildner@channelz.GUN.de</email></para>
       </listitem>
 
       <listitem>
 	<para>Scott Burris <email>scott@pita.cns.ucla.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Scott Reynolds <email>scott@clmqt.marquette.mi.us</email></para>
       </listitem>
 
       <listitem>
 	<para>Seamus Venasse <email>svenasse@polaris.ca</email></para>
       </listitem>
 
       <listitem>
 	<para>Sean Eric Fagan <email>sef@kithrup.com</email></para>
       </listitem>
 
       <listitem>
 	<para>Simon J Gerraty <email>sjg@melb.bull.oz.au</email>
 	  <email>sjg@zen.void.oz.au</email></para>
       </listitem>
 
       <listitem>
 	<para>Stephen McKay <email>syssgm@devetir.qld.gov.au</email></para>
       </listitem>
 
       <listitem>
 	<para>Terry Lambert <email>terry@icarus.weber.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Terry Lee <email>terry@uivlsi.csl.uiuc.edu</email></para>
       </listitem>
 
       <listitem>
 	<para>Tor Egge <email>Tor.Egge@idi.ntnu.no</email></para>
       </listitem>
 
       <listitem>
 	<para>Warren Toomey <email>wkt@csadfa.cs.adfa.oz.au</email></para>
       </listitem>
 
       <listitem>
 	<para>Wiljo Heinen <email>wiljo@freeside.ki.open.de</email></para>
       </listitem>
 
       <listitem>
 	<para>William Jolitz <email>withheld</email></para>
       </listitem>
 
       <listitem>
 	<para>Wolfgang Solfrank <email>ws@tools.de</email></para>
       </listitem>
 
       <listitem>
 	<para>Wolfgang Stanglmeier <email>wolf@dentaro.GUN.de</email></para>
       </listitem>
 
       <listitem>
 	<para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para>
       </listitem>
     </itemizedlist>
   </sect1>
 </article>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      End:
 -->
diff --git a/en_US.ISO8859-1/articles/diskless-x/article.sgml b/en_US.ISO8859-1/articles/diskless-x/article.sgml
index ec16577767..b87180798f 100644
--- a/en_US.ISO8859-1/articles/diskless-x/article.sgml
+++ b/en_US.ISO8859-1/articles/diskless-x/article.sgml
@@ -1,349 +1,349 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 ]>
 
 <article>
   <articleinfo>
     <title>Diskless X Server: a how to guide</title>
     
     <authorgroup>
       <author>
 	<firstname>Jerry</firstname>
 	<surname>Kendall</surname>
 	<affiliation>
 	  <address>
 	    <email>jerry@kcis.com</email>
 	  </address>
 	</affiliation>
       </author></authorgroup>
     
     <pubdate>28-December-1996</pubdate>
     
     <copyright>
       <year>1996</year>
       <holder>Jerry Kendall</holder>
     </copyright>
     
     <abstract>
       <para>With the help of some friends on the FreeBSD-hackers list, I have
 	been able to create a diskless X terminal.  The creation of the X
 	terminal required first creating a diskless system with minimal
 	utilities mounted via NFS.  These same steps were used to create 2
 	separate diskless systems.  The first is <hostid
 	  role="fqdn">altair.example.com</hostid>.  A diskless X terminal that I
 	run on my old 386DX-40.  It has a 340Meg hard disk but, I did not want
 	to change it.  So, it boots from <hostid
 	  role="fqdn">antares.example.com</hostid> across a Ethernet.  The second
 	system is a 486DX2-66.  I setup a diskless FreeBSD (complete) that
 	uses no local disk.  The server in that case is a Sun 670MP running
 	SunOS 4.1.3.  The same setup configuration was needed for both.</para>
       
       <para>I am sure that there is stuff that needs to be added
 	to this.  Please send me any comments.</para>
     </abstract>
   </articleinfo>
   
   <sect1>
     <title>Creating the boot floppy (On the diskless system)</title>
     
     <para>Since the network boot loaders will not work with some of the TSR's
       and such that MS-DOS uses, it is best to create a dedicated boot floppy
       or, if you can, create an MS-DOS menu that will (via the
       <filename>config.sys</filename>/<filename>autoexec.bat</filename> files)
       ask what configuration to load when the system starts.  The later is the
       method that I use and it works great. My MS-DOS (6.x) menu is
       below.</para>
     
     <example>
       <title><filename>config.sys</filename></title>
 
       <programlisting>[menu]
 menuitem=normal, normal
 menuitem=unix, unix
 [normal]
 ....
 normal config.sys stuff
 ...
 [unix]</programlisting>
     </example>
 
     <example>
       <title><filename>autoexec.bat</filename></title>
 
       <programlisting>@ECHO OFF
 goto %config%
 
 :normal
 ...
 normal autoexec.bat stuff
 ...
 goto end
 
 :unix
 cd \netboot
 nb8390.com
 
 :end</programlisting>
     </example>
   </sect1>
   
   <sect1>
     <title>Getting the network boot programs (On the server)</title>
     
     <para>Compile the <quote>net-boot</quote> programs that are located in
       <filename>/usr/src/sys/i386/boot/netboot</filename>.  You should read
       the comments at the top of the <filename>Makefile</filename>.  Adjust as
       required.  Make a backup of the original in case it gets foobar'd.  When
       the build is done, there should be 2 MS-DOS executables,
       <filename>nb8390.com</filename> and <filename>nb3c509.com</filename>.
       One of these two programs will be what you need to run on the diskless
       server.  It will load the kernel from the boot server.  At this point,
       put both programs on the MS-DOS boot floppy created earlier.</para>
   </sect1>
   
   <sect1>
     <title>Determine which program to run (On the diskless system)</title>
     
     <para>If you know the chipset that your Ethernet adapter uses, this is
       easy.  If you have the NS8390 chipset, or a NS8390 based chipset, use
       <filename>nb8390.com</filename>.  If you have a 3Com 509 based chipset,
       use the <filename>nb3C509.com</filename> boot program.  If you are not
       sure which you have, try using one, if it says <errorname>No adapter
 	found</errorname>, try the other.  Beyond that, you are pretty much on
       your own.</para>
   </sect1>
 
   <sect1>
     <title>Booting across the network</title>
     
     <para>Boot the diskless system with out any config.sys/autoexec.bat
       files.  Try running the boot program for your Ethernet adapter.</para>
 
     <para>My Ethernet adapter is running in WD8013 16bit mode so I run
       <filename>nb8390.com</filename></para>
     
     <screen><prompt>C:&gt;</prompt> <userinput>cd \netboot</userinput>
-<prompt>C:&gt</prompt> <userinput>nb8390</userinput>
+<prompt>C:&gt;</prompt> <userinput>nb8390</userinput>
 
 <prompt>Boot from Network (Y/N) ?</prompt>  <userinput>Y</userinput>
 
 BOOTP/TFTP/NFS bootstrap loader     ESC for menu
 
 Searching for adapter..
 WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66
 
 Searching for server...</screen>
 
     <para>At this point, my diskless system is trying to find a machine to act
       as a boot server.  Make note of the <literal>addr</literal> line above,
       you will need this number later.  Reset the diskless system and modify
       your <filename>config.sys</filename> and
       <filename>autoexec.bat</filename> files to do these steps automatically
       for you.  Perhaps in a menu.  If you had to run
       <command>nb3c509.com</command> instead of <command>nb8390.com</command>
       the output is the same as above.  If you got <errorname>No adapter
 	found</errorname> at the <literal>Searching for adapter...</literal>
       message, verify that you did indeed set the compile time defines in the
       <filename>Makefile</filename> correctly.</para>
   </sect1>
   
   <sect1>
     <title>Allowing systems to boot across the network (On the server)</title>
     
     <para>Make sure the <filename>/etc/inetd.conf</filename> file has entries
       for tftp and bootps. Mine are listed below:</para>
     
     <programlisting>tftp	dgram	udp	wait	nobody	/usr/libexec/tftpd	tftpd /tftpboot
 #
 # Additions by who ever you are
 bootps  dgram  udp  wait  root  /usr/libexec/bootpd bootpd /etc/bootptab</programlisting>
     
     <para>If you have to change the <filename>/etc/inetd.conf</filename> file,
       send a <literal>HUP</literal> signal to inetd.  To do this, get the
       process ID of inetd with <command>ps -ax | grep inetd | grep -v
 	grep</command>.  Once you have it, send it a <literal>HUP</literal> signal.  Do this by
       <command>kill -HUP &lt;pid&gt;</command>.  This will force inetd to
       re-read its config file.</para>
 
     <para>Did you remember to note the <literal>addr</literal> line from the
       output of the boot loader on the diskless system? Guess what, here is
       where you need it.</para>
 
     <para>Add an entry to <literal>/etc/bootptab</literal> (maybe creating the
       file).  It should be laid out identical to this:</para>
 
     <programlisting>altair:\
         :ht=ether:\
         :ha=004001432666:\
         :sm=255.255.255.0:\
         :hn:\
         :ds=199.246.76.1:\
         :ip=199.246.76.2:\
         :gw=199.246.76.1:\
         :vm=rfc1048:</programlisting>
     
     <para>The lines are as follows:</para>
 
     <informaltable frame="none">
       <tgroup cols="2">
 	<tbody>
 	  <row>
 	    <entry><literal>altair</literal></entry>
 	    <entry>the diskless systems name without the domain name.</entry>
 	  </row>
 
 	  <row>
 	    <entry><literal>ht=ether</literal></entry>
 	    <entry>the hardware type of <quote>ethernet</quote>.</entry>
 	  </row>
 
 	  <row>
 	    <entry><literal>ha=004001432666</literal></entry>
 	    <entry>the hardware address (the number noted above).</entry>
 	  </row>
 
 	  <row>
 	    <entry><literal>sm=255.255.255.0</literal></entry>
 	    <entry>the subnet mask.</entry>
 	  </row>
 
 	  <row>
 	    <entry><literal>hn</literal></entry>
 	    <entry>tells server to send client's hostname to the
 	      client.</entry>
 	  </row>
 
 	  <row>
 	    <entry><literal>ds=199.246.76.1</literal></entry>
 	    <entry>tells the client who the domain server is.</entry>
 	  </row>
 
 	  <row>
 	    <entry><literal>ip=199.246.76.2</literal></entry>
 	    <entry>tells the client what its IP address is.</entry>
 	  </row>
 
 	  <row>
 	    <entry><literal>gw=199.246.76.1</literal></entry>
 	    <entry>tells the client what the default gateway is.</entry>
 	  </row>
 
 	  <row>
 	    <entry><literal>vm=...</literal></entry>
 	    <entry>just leave it there.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
 
     <note>
       <para>Be sure to setup the IP addresses correctly, the addresses above
 	are my own.</para>
     </note>
 
     <para>Create the directory <filename>/tftpboot</filename> on the server it will contain the
       configuration files for the diskless systems that the server will serve.
       These files will be named <filename>cfg.<replaceable>ip</replaceable></filename> where <replaceable>ip</replaceable> is the IP
       address of the diskless system.  The config file for <hostid>altair</hostid> is
       <filename>/tftpboot/cfg.199.246.76.2</filename>.  The contents is:</para>
 
     <programlisting>rootfs 199.246.76.1:/DiskLess/rootfs/altair
 hostname altair.example.com</programlisting>
 
     <para>The line <literal>hostname altair.example.com</literal> simply tells
       the diskless system what its fully qualified domain name is.</para>
 
     <para>The line <literal>rootfs
 	199.246.76.1:/DiskLess/rootfs/altair</literal> tells the diskless
       system where its NFS mountable root filesystem is located.</para>
 
     <note>
       <para>The NFS mounted root filesystem will be mounted <emphasis>read
 	  only</emphasis>.</para>
     </note>
     
     <para>The hierarchy for the diskless system can be re-mounted allowing
       read-write operations if required.</para>
     
     <para>I use my spare 386DX-40 as a dedicated X terminal.</para>
 
     <para>The hierarchy for <hostid>altair</hostid> is:</para>
 
     <literallayout>/
 /bin
 /etc
 /tmp
 /sbin
 /dev
 /dev/fd
 /usr
 /var
 /var/run</literallayout>
 
     <para>The actual list of files is:</para>
 
     <screen>-r-xr-xr-x  1 root  wheel  779984 Dec 11 23:44 ./kernel
 -r-xr-xr-x  1 root    bin  299008 Dec 12 00:22 ./bin/sh
 -rw-r--r--  1 root  wheel     499 Dec 15 15:54 ./etc/rc
 -rw-r--r--  1 root  wheel    1411 Dec 11 23:19 ./etc/ttys
 -rw-r--r--  1 root  wheel     157 Dec 15 15:42 ./etc/hosts
 -rw-r--r--  1 root    bin    1569 Dec 15 15:26 ./etc/XF86Config.altair
 -r-x------  1 bin     bin  151552 Jun 10  1995 ./sbin/init
 -r-xr-xr-x  1 bin     bin  176128 Jun 10  1995 ./sbin/ifconfig
 -r-xr-xr-x  1 bin     bin  110592 Jun 10  1995 ./sbin/mount_nfs
 -r-xr-xr-x  1 bin     bin  135168 Jun 10  1995 ./sbin/reboot
 -r-xr-xr-x  1 root    bin   73728 Dec 13 22:38 ./sbin/mount
 -r-xr-xr-x  1 root  wheel    1992 Jun 10  1995 ./dev/MAKEDEV.local
 -r-xr-xr-x  1 root  wheel   24419 Jun 10  1995 ./dev/MAKEDEV</screen>
     
     <para>Do not forget to run <command>MAKEDEV all</command> in the
       <filename>dev</filename> directory.</para>
 
     <para>My <filename>/etc/rc</filename> for <hostid>altair</hostid>
       is:</para>
 
 <programlisting>#!/bin/sh
 #
 PATH=/bin:/
 export PATH
 #
 # configure the localhost
 /sbin/ifconfig lo0 127.0.0.1
 #
 # configure the ethernet card
 /sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00
 #
 # mount the root filesystem via NFS
 /sbin/mount antares:/DiskLess/rootfs/altair /
 #
 # mount the /usr filesystem via NFS
 /sbin/mount antares:/DiskLess/usr /usr
 #
 /usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1
 #
 # Reboot after X exits
 /sbin/reboot
 #
 # We blew up....
 exit 1</programlisting>
 
     <para>Any comments and all questions welcome.</para>
   </sect1>
 </article>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      End:
 -->
diff --git a/en_US.ISO8859-1/articles/mh/article.sgml b/en_US.ISO8859-1/articles/mh/article.sgml
index 3e75a4a36b..dde181f088 100644
--- a/en_US.ISO8859-1/articles/mh/article.sgml
+++ b/en_US.ISO8859-1/articles/mh/article.sgml
@@ -1,763 +1,763 @@
 <!-- $FreeBSD$ -->
 <!-- FreeBSD Documentation Project -->
 
 <!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN">
 <article>
   <articleinfo>
     <title>An MH Primer</title>
 
     <authorgroup>
       <author>
 	<firstname>Matt</firstname>
 
 	<surname>Midboe</surname>
 
 	<affiliation>
 	  <address>
 	    <email>matt@garply.com</email>
 	  </address>
 	</affiliation>
       </author>
     </authorgroup>
 
     <pubdate>v1.0, 16 January 1996</pubdate>
 
     <abstract>
       <para>This document contains an introduction to using MH on
 	FreeBSD</para>
     </abstract>
   </articleinfo>
 
   <sect1 id="mhintro">
     <title>Introduction</title>
 
     <para>MH started back in 1977 at the RAND Corporation, where the
       initial philosophies behind MH were developed. MH is not so much
       a monolithic email program but a philosophy about how best to
       develop tools for reading email. The MH developers have done a
       great job adhering to the <acronym>KISS</acronym> principle: Keep It
       Simple Stupid.  Rather than have one large program for reading,
       sending and handling email they have written specialized
       programs for each part of your email life. One might liken MH to
       the specialization that one finds in insects and nature. Each
       tool in MH does one thing, and does it very well.</para>
 
     <para>Beyond just the various tools that one uses to handle their
       email MH has done an excellent job keeping the configuration of
       each of these tools consistent and uniform. In fact, if you are
       not quite sure how something is supposed to work or what the
       arguments for some command are supposed to be then you can
       generally guess and be right.  Each MH command is consistent
       about how it handles reading the configuration files and how it
       takes arguments on the command line.  One useful thing to
       remember is that you can always add a <option>-help</option> to
       the command to have it display the options for that
       command.</para>
 
     <para>The first thing that you need to do is to make sure that you
       have installed the MH package on your FreeBSD machine. If you
       installed from CDROM you should be able to execute the following
       to load mh:
 
       <informalexample>
 	<screen>&prompt.root; <userinput>pkg_add /cdrom/packages/mh-6.8.3.tgz</userinput></screen>
       </informalexample>
 
       You will notice that it created a <filename>/usr/local/lib/mh</filename>
       directory for you as well as adding several binaries to the
       <filename>/usr/local/bin</filename> directory. If you would prefer to
       compile it yourself then you can anonymous ftp it from <ulink
 	URL="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink
 	URL="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para>
 
     <para>This primer is not a full comprehensive explanation of how
       MH works. This is just intended to get you started on the road
       to happier, faster mail reading. You should read the man pages
       for the various commands. Also you might want to read the <ulink
 	URL="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also
       you can read the <ulink
 	URL="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mh-faq/part1/faq.html">FAQ
 	for MH</ulink>. The best resource for MH is the O'Reilly and
       Associates book written by Jerry Peek.</para>
   </sect1>
 
   <sect1>
     <title>Reading Mail</title>
 
     <para>This section covers how to use <command>inc</command>,
       <command>show</command>, <command>scan</command>, <command>next</command>,
       <command>prev</command>, <command>rmm</command>, <command>rmf</command>, and
       <command>msgchk</command>.  One of the best things about MH is the
       consistent interface between programs. A few things to keep in
       mind when using these commands is how to specify message lists.
       In the case of <command>inc</command> this does not really make any
       sense but with commands like <command>show</command> it is useful to
       know. </para>
 
     <para>A message list can consist of something like <parameter>23
 	20 16</parameter> which will act on messages 23, 20 and 16. This is
       fairly simple but you can do more useful things like
       <parameter>23-30</parameter> which will act on all the messages between
       23 and 30. You can also specify something like
       <parameter>cur:10</parameter> which will act on the current message and
       the next 9 messages. The <parameter>cur</parameter>, <parameter>last</parameter>,
       and <parameter>first</parameter> messages are special messages that refer
       to the current, last or first message in the folder.</para>
 
     <sect2 id="inc">
       <title><command>inc</command>, <command>msgchk</command>&mdash;read in your
 	new email or check it</title>
 
       <para>If you just type in <userinput>inc</userinput> and hit
 	<keycap>return</keycap> you will be well on your way to getting
 	started with MH. The first time you run <command>inc</command> it
 	will setup your account to use all the MH defaults and ask you
 	about creating a Mail directory. If you have mail waiting to
 	be downloaded you will see something that looks like:</para>
 
       <informalexample>
 	<screen>  29  01/15 Doug White         Re: Another Failed to boot problem&lt;&lt;On Mon, 15 J
   30  01/16 "Jordan K. Hubbar  Re: FBSD 2.1&lt;&lt;&gt; Do you want a library instead of
   31  01/16 Bruce Evans        Re: location of bad144 table&lt;&lt;&gt;&gt; &gt;It would appea
   32  01/16 "Jordan K. Hubbar  Re: video is up&lt;&lt;&gt; Anyway, mrouted won't run, ev
   33  01/16 Michael Smith      Re: FBSD 2.1&lt;&lt;Nate Williams stands accused of sa</screen>
       </informalexample>
 
       <para>This is the same thing you will see from a
 	<command>scan</command> (see <xref linkend="scan">). If you just run
 	<command>inc</command> with no arguments it will look on your
 	computer for email that is supposed to be coming to
 	you.</para>
 
       <para>A lot of people like to use POP for grabbing their email.
 	MH can do POP to grab your email. You will need to give
 	<command>inc</command> a few command line arguments.</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>inc -host mail.pop.org -user <replaceable>username</replaceable> -norpop</userinput></screen>
       </informalexample>
 
       <para>That tells <command>inc</command> to go to
 	<parameter>mail.pop.org</parameter> to download your email, and that
 	your username on their system is <replaceable>username</replaceable>. The
 	<option>-norpop</option> option tells <command>inc</command> to use
 	plain POP3 for downloading your email. MH has support for a
 	few different dialects of POP. More than likely you will never
 	ever need to use them though. While you can do more complex
 	things with inc such as audit files and scan format files this
 	will get you going.</para>
 
       <para>The <command>msgchk</command> command is used to get information
 	on whether or not you have new email. <command>msgchk</command> takes
 	the same <option>-host</option> and <option>-user</option>
 	options that <command>inc</command> takes.</para>
     </sect2>
 
     <sect2 id="show">
       <title><command>show</command>, <command>next</command> and
 	<command>prev</command>&mdash;displaying and moving through
 	email</title>
 
       <para><command>show</command> is to show a letter in your current
 	folder.  Like <command>inc</command>, <command>show</command> is a fairly
 	straightforward command. If you just type <userinput>show</userinput>
 	and hit <keycap>return</keycap> then it displays the current
 	message. You can also give specific message numbers to
 	show:</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>show 32 45 56</userinput></screen>
       </informalexample>
 
       <para>This would display message numbers 32, 45 and 56 right
 	after each other. Unless you change the default behavior
 	<command>show</command> basically just does a <command>more</command> on the
 	email message.</para>
 
       <para><command>next</command> is used to move onto the next message and
 	<command>prev</command> will go to the previous message. Both
 	commands have an implied <command>show</command> command so that when
 	you go to the next message it automatically displays
 	it.</para>
     </sect2>
 
     <sect2 id="scan">
       <title><command>scan</command>&mdash;shows you a scan of your
 	messages</title>
 
       <para><command>scan</command> will display a brief listing of the
 	messages in your current folder. This is an example of what
 	the <command>scan</command> command will give you.</para>
 
       <informalexample>
 	<screen>  30+ 01/16 Jordan K. Hubbar   Re: FBSD 2.1&lt;&lt;&gt; Do you want a library instead of
   31  01/16 Bruce Evans        Re: location of bad144 table&lt;&lt;&gt;&gt; &gt;It would appea
   32  01/16 Jordan K. Hubbar   Re: video is up&lt;&lt;&gt; Anyway, mrouted won't run, ev
   33  01/16 Michael Smith      Re: FBSD 2.1&lt;&lt;Nate Williams stands accused of sa</screen>
       </informalexample>
 
       <para>Like just about everything in MH this display is very
 	configurable.  This is the typical default display. It gives
 	you the message number, the date on the email, the sender, the
 	subject line, and a sentence fragment from the very beginning
 	of the email if it can fit it. The <literal>+</literal> means that
 	message is the current message, so if you do a
 	<command>show</command> it will display that message.</para>
 
       <para>One useful option for scan is the
 	<option>-reverse</option> option. This will list your messages
 	with the highest message number first and lowest message
 	number last. Another useful option with <command>scan</command> is to
 	have it read from a file. If you want to scan your incoming
 	mailbox on FreeBSD without having to <command>inc</command> it you
 	can do <command>scan -file
 	  /var/mail/<replaceable>username</replaceable></command>. This can be used
 	with any file that is in the <database>mbox</database> format.</para>
     </sect2>
 
     <sect2 id="rmm">
       <title><command>rmm</command> and <command>rmf</command>&mdash;remove the
 	current message or folder</title>
 
       <para><command>rmm</command> is used to remove a mail message. The
 	default is typically to not actually remove the message but to
 	rename the file to one that is ignored by the MH commands. You
 	will periodically need to go through and physically delete the
 	<quote>removed</quote> messages.</para>
 
       <para>The <command>rmf</command> command is used to remove folders.
 	This does not just rename the files but actually removes the
 	from the hard drive so you should be careful when you use this
 	command.</para>
     </sect2>
 
     <sect2 id="samplereading">
       <title>A typical session of reading with MH</title>
 
       <para>The first thing that you will want to do is
 	<command>inc</command> your new mail. So at a shell prompt just type
 	in <command>inc</command> and hit <keycap>return</keycap>.</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>inc</userinput>
 Incorporating new mail into inbox...
 
   36+ 01/19 Stephen L. Lange   Request...&lt;&lt;Please remove me as contact for pind
   37  01/19 Matt Thomas        Re: kern/950: Two PCI bridge chips fail (multipl
   38  01/19 Amancio Hasty Jr   Re: FreeBSD and VAT&lt;&lt;&gt;&gt;&gt; Bill Fenner said: &gt; In 
 &prompt.user;</screen>
       </informalexample>
 
       <para>This shows you the new email that has been added to your
 	mailbox. So the next thing to do is <command>show</command> the email
 	and move around.</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>show</userinput>
 Received: by sashimi.wwa.com (Smail3.1.29.1 #2)
         id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST
 Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST)
 From: "Stephen L. Lange" &lt;stvlange@wwa.com&gt;
 To: matt@garply.com
 Subject: Request...
 Message-Id: &lt;Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com&gt;
 Mime-Version: 1.0
 Content-Type: TEXT/PLAIN; charset=US-ASCII
 
 
 Please remove me as contact for pindat.com
 
 &prompt.user; <userinput>rmm</userinput>
 &prompt.user; <userinput>next</userinput>
 Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8
 .6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT
 Message-Id: &lt;199601191756.RAA24416@whydos.lkg.dec.com&gt;
 X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro
 tocol
 To: hsu@clinet.fi
 Cc: hackers@FreeBSD.org
 Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet 
  boards) 
 In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100."
              &lt;199601182318.AA11772@Sysiphos&gt; 
 X-Mailer: exmh version 1.5omega 10/6/94
 Date: Fri, 19 Jan 1996 17:56:40 +0000
 From: Matt Thomas &lt;matt@lkg.dec.com&gt;
 Sender: owner-hackers@FreeBSD.org
 Precedence: bulk
 
 
 This is due to a typo in pcireg.h (to
 which I am probably the guilty party).</screen>
       </informalexample>
 
       <para>The <command>rmm</command> removed the current message and the
 	<command>next</command> command moved me on to the next message.  Now
 	if I wanted to look at ten most recent messages so I could
 	read one of them here is what I would do:</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>scan last:10</userinput>
   26  01/16 maddy              Re: Testing some stuff&lt;&lt;yeah, well, Trinity has 
   27  01/17 Automatic digest   NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19
   28  01/17 Evans A Criswell   Re: Hey dude&lt;&lt;&gt;From matt@tempest.garply.com Tue 
   29  01/16 Karl Heuer         need configure/make volunteers&lt;&lt;The FSF is looki
   30  01/18 Paul Stephanouk    Re: [alt.religion.scientology] Raw Meat (humor)&lt;
   31  01/18 Bill Lenherr       Re: Linux NIS Solaris&lt;&lt;--- On Thu, 18 Jan 1996 1
   34  01/19 John Fieber        Re: Stuff for the email section?&lt;&lt;On Fri, 19 Jan
   35  01/19 support@foo.garpl  [garply.com #1138] parlor&lt;&lt;Hello. This is the Ne
   37+ 01/19 Matt Thomas        Re: kern/950: Two PCI bridge chips fail (multipl
   38  01/19 Amancio Hasty Jr   Re: FreeBSD and VAT&lt;&lt;&gt;&gt;&gt; Bill Fenner said: &gt; In 
 &prompt.user;</screen>
       </informalexample>
 
       <para>Then if I wanted to read message number 27 I would do a
 	<userinput>show 27</userinput> and it would be displayed. As you can
 	probably tell from this sample session MH is pretty easy to
 	use and looking through emails and displaying them is fairly
 	intuitive and easy.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Folders and Mail Searching</title>
 
     <para>Anybody who gets lots of email definitely wants to be able
       to prioritize, stamp, brief, de-brief, and number their emails
       in a variety of different ways. MH can do this better than just
       about anything. One thing that we have not really talked about is
       the concept of folders. You have undoubtedly come across the
       folders concept using other email programs. MH has folders too.
       MH can even do sub-folders of a folder. One thing you should
       keep in mind with MH is that when you ran <command>inc</command> for
       the first time and it asked you if it could create a
       <filename>Mail</filename> directory it began storing everything in that
       directory. If you look at that directory you will find a
       directory named <filename>inbox</filename>. The <filename>inbox</filename>
       directory houses all of your incoming mail that has not been
       thrown anywhere else.</para>
 
     <para>Whenever you create a new folder a new directory is going to
       be created underneath your MH <filename>Mail</filename> directory, and
       messages in that folder are going to be stored in that
       directory.  When new email comes in that new email is thrown
       into your <filename>inbox</filename> directory with a file name that is
       equivalent to the message number.  So even if you did not have
       any of the MH tools to read your email you could still use
       standard Unix commands to munge around in those directories and
       just more your files. It is this simplicity that really gives you
       a lot of power with what you can do with your email.</para>
 
     <para>Just as you can use message lists like <parameter>23 16
 	42</parameter> with most MH commands there is a folder option you can
       specify with just about every MH command. If you do a
       <command>scan +freebsd</command> it will scan your <filename>freebsd</filename>
       folder, and your current folder will be changed to
       <filename>freebsd</filename>. If you do a <command>show +freebsd 23 16
 	42</command>, <command>show</command> is going to switch to your
       <filename>freebsd</filename> folder and display messages 23, 16 and 42.
       So remember that <option>+<replaceable>folder</replaceable></option> syntax. You
       will need to make sure you use it to make commands process
       different folders. Remember you default folder for mail is
       <filename>inbox</filename> so doing a <command>folder +inbox</command> should
       always get you back to your mail. Of course, in MH's infinite
       flexibility this can be changed but most places have probably
       left it as <command>inbox</command>.</para>
 
     <sect2>
       <title><command>pick</command>&mdash;search email that matches certain
 	criteria</title>
 
       <para><command>pick</command> is one of the more complex commands in
 	the MH system. So you might want to read the
 	<citerefentry><refentrytitle>pick</refentrytitle><manvolnum>1</manvolnum></citerefentry> man
 	page for a more thorough understanding. At its simplest level
 	you can do something like</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>pick -search pci</userinput>
 15
 42
 55
 56
 57</screen>
       </informalexample>
 
       <para>This will tell <command>pick</command> to look through every
 	single line in every message in your current folder and tell
 	you which message numbers it found the word <literal>pci</literal>
 	in. You can then <command>show</command> those messages and read them
 	if you wish or <command>rmm</command> them. You would have to specify
 	something like <command>show 15 42 55-57</command> to display them
 	though. A slightly more useful thing to do is this:</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>pick -search pci -seq pick</userinput>
 5 hits
 &prompt.user; <userinput>show pick</userinput></screen>
       </informalexample>
 
       <para>This will show you the same messages you just did not have
 	to work as hard to do it. The <option>-seq</option> option is
 	really an abbreviation of <option>-sequence</option> and
 	<command>pick</command> is just a sequence which contains the message
 	numbers that matched. You can use sequences with just about
 	any MH command. So you could have done an <command>rmm pick</command>
 	and all those messages would be removed instead. You sequence
 	can be named anything. If you run pick again it will overwrite
 	the old sequence if you use the same name.</para>
 
       <para>Doing a <command>pick -search</command> can be a bit more
 	time consuming than just searching for message from someone,
 	or to someone. So <command>pick</command> allows you to use the
 	following predefined search criteria:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term><option>-to</option></term>
 
 	  <listitem>
 	    <para>search based upon who the message is to</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-cc</option></term>
 
 	  <listitem>
 	    <para>search based on who is in the cc list</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-from</option></term>
 
 	  <listitem>
 	    <para>search for who sent the message</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-subject</option></term>
 
 	  <listitem>
 	    <para>search for emails with this subject</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-date</option></term>
 
 	  <listitem>
 	    <para>find emails with a matching dat</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>--<replaceable>component</replaceable></option></term>
 
 	  <listitem>
 	    <para>search for any other component in the header. (i.e.
 	      <option>--reply-to</option> to find all emails with a certain
 	      reply-to in the header)</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
   
       <para>This allows you to do things like
 
 	<informalexample>
 	  <screen>&prompt.user; <userinput>pick -to freebsd-hackers@FreeBSD.org -seq hackers</userinput></screen>
 	</informalexample>
 
 	to get a list of all the email send to the FreeBSD hackers
 	mailing list. <command>pick</command> also allows you to group these
 	criteria in different ways using the following options:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>&hellip; <option>-and</option> &hellip;</para>
 	</listitem>
 
 	<listitem>
-	  <para>&hellip; <option>-or</option> &hellip</para>
+	  <para>&hellip; <option>-or</option> &hellip;</para>
 	</listitem>
 
 	<listitem>
 	  <para><option>-not</option> &hellip;</para>
 	</listitem>
 
 	<listitem>
 	  <para><option>-lbrace</option> &hellip;
 	    <option>-rbrace</option></para>
 	</listitem>
       </itemizedlist>
 
       <para>These commands allow you to do things like</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>pick -to freebsd-hackers -or -cc freebsd-hackers</userinput></screen>
       </informalexample>
 
       <para>That will grab all the email in your inbox that was sent
 	to freebsd-hackers or cc'd to that list. The brace options
 	allow you to group search criteria together. This is sometimes
 	very necessary as in the following example</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>pick -lbrace -to freebsd-hackers -and 
   -not -cc freebsd-questions -rbrace -and -subject pci</userinput></screen>
       </informalexample>
 
       <para>Basically this says <quote>pick (to freebsd-hackers and
 	  not cc'd on freebsd-questions) and the subject is
 	  pci</quote>.  It should look through your folder and find
 	all messages sent to the freebsd-hackers list that are not cc'd
 	to the freebsd-questions list that contain something on pci in
 	the subject line. Ordinarily you might have to worry about
 	something called operator precedence. Remember in math how you
 	evaluate from left to right and you do multiplication and
 	division first and addition and subtraction second? MH has the
 	same type of rules for <command>pick</command>. It is fairly complex
 	so you might want to study the man page. This document is just
 	to help you get acquainted with MH.</para>
     </sect2>
 
     <sect2>
       <title><command>folder</command>, <command>folders</command>,
 	<command>refile</command>&mdash;three useful programs for folder
 	maintenance</title>
 
       <para>There are three programs which are primarily just for
 	manipulating your folders. The <command>folder</command> program is
 	used to switch between folders, pack them, and list them. At
 	its simplest level you can do a <command>folder
 	+<replaceable>newfolder</replaceable></command> and you will be switched into
 	<replaceable>newfolder</replaceable>. From there on out all your MH
 	commands like <command>comp</command>, <command>repl</command>,
 	<command>scan</command>, and <command>show</command> will act on that
 	<command>newfolder</command> folder.</para>
 
       <para>Sometimes when you are reading and deleting messages you
 	will develop <quote>holes</quote> in your folders. If you do a
 	<command>scan</command> you might just see messages 34, 35, 36, 43,
 	55, 56, 57, 80. If you do a <command>folder -pack</command>
 	this will renumber all your messages so that there are no
 	holes. It does not actually delete any messages though. So you
 	may need to periodically go through and physically delete
 	<command>rmm</command>'d messages.</para>
 
       <para>If you need statistics on your folders you can do a
 	<command>folders</command> or <command>folder -all</command> to list
 	all your folders, how many messages they have, what the
 	current message is in each one and so on. This line of stats
 	it displays for all your folders is the same one you get when
 	you change to a folder with <command>folder +foldername</command>. A
 	<command>folders</command> command looks like this:</para>
 
       <informalexample>
 	<screen>                Folder      # of messages (  range  ); cur  msg  (other files)
               announce  has    1 message  (   1-   1).
                 drafts  has   no messages.
              f-hackers  has   43 messages (   1-  43).
            f-questions  has   16 messages (   1-  16).
                  inbox+ has   35 messages (   1-  38); cur=  37.
                  lists  has    8 messages (   1-   8).
              netfuture  has    1 message  (   1-   1).
                    out  has   31 messages (   1-  31).
               personal  has    6 messages (   1-   6).
                   todo  has   58 messages (   1-  58); cur=   1.
 
                      TOTAL=  199 messages in 13 folders.</screen>
       </informalexample>
   
       <para>The <command>refile</command> command is what you use to move
 	messages between folders. When you do something like
 	<command>refile 23 +netfuture</command> message number 23 is moved
 	into the <filename>netfuture</filename> folder. You could also do
 	something like <command>refile 23 +netfuture/latest</command> which
 	would put message number 23 in a subfolder called
 	<filename>latest</filename> under the <filename>netfuture</filename> folder.
 	If you want to keep a message in the current folder and link
 	it you can do a <command>refile -link 23 +netfuture</command>
 	which would keep 23 in your current <filename>inbox</filename> but
 	also list in your <filename>netfuture</filename> folder. You are
 	probably beginning to realize some of the really powerful
 	things you can do with MH.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Sending Mail</title>
 
     <para>Email is a two way street for most people so you want to be
       able to send something back. The way MH handles sending mail can
       be a bit difficult to follow at first, but it allows for
       incredible flexibility. The first thing MH does is to copy a
       components file into your outgoing email. A components file is
       basically a skeleton email letter with stuff like the To: and
       Subject: headers already in it.  You are then sent into your
       editor where you fill in the header information and then type
       the body of your message below the dashed lines in the message.
       Then to the <command>whatnow</command> program. When you are at the
       <prompt>What now?</prompt> prompt you can tell it to
       <command>send</command>, <command>list</command>, <command>edit</command>,
       <command>edit</command>, <command>push</command>, and <command>quit</command>. Most
       of these commands are self-explanatory. So the message sending
       process involves copying a component file, editing your email,
       and then telling the <command>whatnow</command> program what to do with
       your email.</para>
 
     <sect2>
       <title><command>comp</command>, <command>forw</command>,
 	<command>reply</command>&mdash;compose, forward or reply to a message
 	to someone</title>
 
       <para>The <command>comp</command> program has a few useful command line
 	options. The most important one to know right now is the
 	<option>-editor</option> option. When MH is installed the
 	default editor is usually a program called
 	<command>prompter</command> which comes with MH. It is not a very
 	exciting editor and basically just gets the job done. So when
 	you go to compose a message to someone you might want to use
 	<command>comp -editor /usr/bin/vi</command> or <command>comp -editor
 	/usr/local/bin/pico</command> instead. Once you have run
 	<emphasis>comp</emphasis> you are in your editor and you see
 	something that looks like this:</para>
 
       <informalexample>
 	<screen>To:
 cc:
 Subject:
 --------</screen>
       </informalexample>
 
       <para>You need to put the person you are sending the mail to
 	after the <literal>To:</literal> line. It works the same way for the
 	other headers also, so you would need to put your subject
 	after the <literal>Subject:</literal> line. Then you would just put
 	the body of your message after the dashed lines. It may seem a
 	bit simplistic since a lot of email programs have special
 	requesters that ask you for this information but there really
 	is no point to that. Plus this really gives you excellent
 	flexibility.</para>
 
       <informalexample>
 	<screen>To:<userinput>freebsd-rave@FreeBSD.org</userinput>
 cc:
 Subject:<userinput>And on the 8th day God created the FreeBSD core team</userinput>
 --------
 <userinput>Wow this is an amazing operating system. Thanks!</userinput></screen>
       </informalexample>
 
       <para>You can now save this message and exit your editor. You
 	will see the <prompt>What now?</prompt> prompt and you can type in
 	<userinput>send</userinput> or <userinput>s</userinput> and hit
 	<keycap>return</keycap>. Then the FreeBSD core team will receive
 	their just rewards. As I mentioned earlier you can also use
 	other commands, for example <command>quit</command> if you do not want
 	to send the message.</para>
 
       <para>The <command>forw</command> command is stunningly similar. The
 	big difference being that the message you are forwarding is
 	automatically included in the outgoing message. When you run
 	<command>forw</command> it will forward your current message. You can
 	always tell it to forward something else by doing something
 	like <command>forw 23</command> and then message number 23 will be
 	put in your outgoing message instead of the current message.
 	Beyond those small differences <command>forw</command> functions
 	exactly the same as <command>comp</command>. You go through the exact
 	same message sending process.</para>
 
       <para>The <command>repl</command> command will reply to whatever your
 	current message is, unless you give it a different message to
 	reply to. <command>repl</command> will do its best to go ahead and
 	fill in some of the email headers already. So you will notice
 	that the <literal>To:</literal> header already has the address of the
 	recipient in there. Also the <literal>Subject:</literal> line will
 	already be filled in.  You then go about the normal message
 	composition process and you are done. One useful command line
 	option to know here is the <option>-cc</option> option. You
 	can use <parameter>all</parameter>, <parameter>to</parameter>, <parameter>cc</parameter>,
 	<parameter>me</parameter> after the <option>-cc</option> option to have
 	<command>repl</command> automatically add the various addresses to
 	the cc list in the message. You have probably noticed that the
 	original message is not included. This is because most MH
 	setups are configured to do this from the start.</para>
     </sect2>
 
     <sect2>
       <title><filename>components</filename>, and
 	<filename>replcomps</filename>&mdash;components files for
 	<command>comp</command> and <command>repl</command></title>
 
       <para>The <filename>components</filename> file is usually in
 	<filename>/usr/local/lib/mh</filename>. You can copy that file
 	into your MH Mail directory and edit to contain what you want
 	it to contain. It is a fairly basic file. You have various
 	email headers at the top, a dashed line and then nothing. The
 	<command>comp</command> command just copies this
 	<filename>components</filename> file and then edits it. You can add
 	any kind of valid RFC822 header you want. For instance you
 	could have something like this in your <filename>components</filename>
 	file:</para>
 
       <informalexample>
 	<screen>To:
 Fcc: out
 Subject:
 X-Mailer: MH 6.8.3
 X-Home-Page: http://www.FreeBSD.org/
 -------</screen>
       </informalexample>
 
       <para>MH would then copy this components file and throw you into
 	your editor. The <filename>components</filename> file is fairly
 	simple.  If you wanted to have a signature on those messages
 	you would just put your signature in that
 	<filename>components</filename> file.</para>
 
       <para>The <filename>replcomps</filename> file is a bit more complex. The
 	default <filename>replcomps</filename> looks like this:</para>
 
       <informalexample>
 	<screen>%(lit)%(formataddr %&lt;{reply-to}%?{from}%?{sender}%?{return-path}%&gt;)\
 %&lt;(nonnull)%(void(width))%(putaddr To: )\n%&gt;\
 %(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\
 %&lt;(nonnull)%(void(width))%(putaddr cc: )\n%&gt;\
 %&lt;{fcc}Fcc: %{fcc}\n%&gt;\
 %&lt;{subject}Subject: Re: %{subject}\n%&gt;\
 %&lt;{date}In-reply-to: Your message of "\
 %&lt;(nodate{date})%{date}%|%(pretty{date})%&gt;."%&lt;{message-id}
              %{message-id}%&gt;\n%&gt;\
 --------</screen>
       </informalexample>
 
       <para>It is in the same basic format as the
 	<filename>components</filename> file but it contains quite a few extra
 	formatting codes. The <literal>%(lit)</literal> command makes room
 	for the address. The <literal>%(formataddr</literal> is a function
 	that returns a proper email address. The next part is
 	<literal>%&lt;</literal> which means if and the
 	<literal>{reply-to}</literal> means the reply-to field in the
 	original message. So that might be translated this way:</para>
 
       <informalexample>
 	<screen>%&lt;<emphasis remap=bf>if</emphasis> {reply-to} <emphasis remap=bf>the original message has a reply-to</emphasis> 
 then give that to formataddr, %? <emphasis remap=bf>else</emphasis> {from} <emphasis remap=bf>take the
 from address</emphasis>, %? <emphasis remap=bf>else</emphasis> {sender} <emphasis remap=bf>take the sender address</emphasis>, %?
 <emphasis remap=bf>else</emphasis> {return-path} <emphasis remap=bf>take the return-path from the original
 message</emphasis>, %&gt; <emphasis remap=bf>endif</emphasis>.</screen>
       </informalexample>
   
       <para>As you can tell MH formatting can get rather involved. You
 	can probably decipher what most of the other functions and
 	variables mean. All of the information on writing these format
 	strings is in the MH-Format man page. The really nice thing is
 	that once you have built your customized
 	<filename>replcomps</filename> file you will not need to touch it again.
 	No other email program really gives you the power and
 	flexibility that MH gives you.</para>
     </sect2>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/articles/multi-os/article.sgml b/en_US.ISO8859-1/articles/multi-os/article.sgml
index a40b7c76b0..fb8eb035f7 100644
--- a/en_US.ISO8859-1/articles/multi-os/article.sgml
+++ b/en_US.ISO8859-1/articles/multi-os/article.sgml
@@ -1,741 +1,741 @@
 <!-- $FreeBSD$ -->
 <!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN">
 <article>
   <articleinfo>
     <title>Installing and Using FreeBSD With Other Operating Systems</title>
 
     <authorgroup>
       <author>
 	<firstname>Jay</firstname>
 
 	<surname>Richmond</surname>
 
 	<affiliation>
 	  <address>
 	    <email>jayrich@sysc.com</email>
 	  </address>
 	</affiliation>
       </author>
     </authorgroup>
 
     <pubdate>6 August 1996</pubdate>
 
     <abstract>
       <para>This document discusses how to make FreeBSD coexist nicely
 	with other popular operating systems such as Linux, MS-DOS,
 	OS/2, and Windows 95.  Special thanks to: Annelise Anderson
 	<email>andrsn@stanford.edu</email>, Randall Hopper
 	<email>rhh@ct.picker.com</email>, and Jordan K. Hubbard
 	<email>jkh@time.cdrom.com</email></para>
     </abstract>
   </articleinfo>
 
   <sect1>
     <title>Overview</title>
 
     <para>Most people can not fit these operating systems together
       comfortably without having a larger hard disk, so special
       information on large EIDE drives is included.  Because there are
       so many combinations of possible operating systems and hard disk
       configurations, the <xref linkend="ch5"> section may be of the
       most use to you.  It contains descriptions of specific working
       computer setups that use multiple operating systems.</para>
 
     <para>This document assumes that you have already made room on
       your hard disk for an additional operating system.  Any time you
       repartition your hard drive, you run the risk of destroying the
       data on the original partitions.  However, if your hard drive is
       completely occupied by DOS, you might find the FIPS utility
       (included on the FreeBSD CDROM in the
       <filename>\TOOLS</filename> directory or via <ulink
 	URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/">ftp</ulink>)
       useful.  It lets you repartition your hard disk without
       destroying the data already on it.  There is also a commercial
       program available called Partition Magic, which lets you size
       and delete partitions without consequence.</para>
   </sect1>
 
   <sect1 id="ch2">
     <title>Overview of Boot Managers</title>
 
     <para>These are just brief descriptions of some of the different
       boot managers you may encounter.  Depending on your computer
       setup, you may find it useful to use more than one of them on
       the same system.</para>
 
     <variablelist>
       <varlistentry>
 	<term>Boot Easy</term>
 
 	<listitem>
 	  <para>This is the default boot manager used with FreeBSD.
 	    It has the ability to boot most anything, including BSD,
 	    OS/2 (HPFS), Windows 95 (FAT and FAT32), and Linux.
 	    Partitions are selected with the function keys.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>OS/2 Boot Manager</term>
 
 	<listitem>
 	  <para>This will boot FAT, HPFS, FFS (FreeBSD), and EXT2
 	    (Linux).  It will also boot FAT32 partitions.  Partitions
 	    are selected using arrow keys.  The OS/2 Boot Manager is
 	    the only one to use its own separate partition, unlike the
 	    others which use the master boot record (MBR).  Therefore,
 	    it must be installed below the 1024th cylinder to avoid
 	    booting problems.  It can boot Linux using LILO when it is
 	    part of the boot sector, not the MBR.  Go to <ulink
 	      URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux
 	      HOWTOs</ulink> on the World Wide Web for more
 	    information on booting Linux with OS/2's boot
 	    manager.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>OS-BS</term>
 
 	<listitem>
 	  <para>This is an alternative to Boot Easy.  It gives you more
 	    control over the booting process, with the ability to set
 	    the default partition to boot and the booting timeout.
 	    The beta version of this programs allows you to boot by
 	    selecting the OS with your arrow keys.  It is included on
 	    the FreeBSD CD in the <filename>\TOOLS</filename>
 	    directory, and via <ulink
 	      URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/">ftp</ulink>.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>LILO, or LInux LOader</term>
 
 	<listitem>
 	  <para>This is a limited boot manager.  It will boot FreeBSD,
 	    though some customization work is required in the LILO
 	    configuration file.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <note id="fat32">
       <title>About FAT32</title>
 
       <para>FAT32 is the replacement to the FAT filesystem included in
 	Microsoft's OEM SR2 Beta release, which started replacing FAT
 	on computers pre-loaded with Windows 95 towards the
 	end of 1996.  It converts the normal FAT file system and
 	allows you to use smaller cluster sizes for larger hard
 	drives.  FAT32 also modifies the traditional FAT boot sector
 	and allocation table, making it incompatible with some boot
 	managers.</para>
     </note>
   </sect1>
 
   <sect1 id="ch3">
     <title>A Typical Installation</title>
 
     <para>Let's say I have two large EIDE hard drives, and I want to
       install FreeBSD, Linux, and Windows 95 on them.</para>
 
     <para>Here is how I might do it using these hard disks:</para>
 
     <itemizedlist>
       <listitem>
 	<para><filename>/dev/wd0</filename> (first physical hard disk)</para>
       </listitem>
 
       <listitem>
 	<para><filename>/dev/wd1</filename> (second hard disk)</para>
       </listitem>
     </itemizedlist>
 
     <para>Both disks have 1416 cylinders.</para>
 
     <procedure>
       <step>
 	<para>I boot from a MS-DOS or Windows 95 boot disk that
 	  contains the <filename>FDISK.EXE</filename> utility and make a small
 	  50 meg primary partition (35-40 for Windows 95, plus a
 	  little breathing room) on the first disk.  Also create a
 	  larger partition on the second hard disk for my Windows
 	  applications and data.</para>
 	</step>
 
       <step>
 	<para>I reboot and install Windows 95 (easier said than done)
 	  on the <filename>C:</filename> partition.</para>
       </step>
 
       <step>
 	<para>The next thing I do is install Linux.  I am not sure
 	  about all the distributions of Linux, but slackware includes
 	  LILO (see <xref linkend="ch2">).  When I am partitioning out
 	  my hard disk with Linux <command>fdisk</command>, I would
 	  put all of Linux on the first drive (maybe 300 megs for a
 	  nice root partition and some swap space).</para>
       </step>
 
       <step>
 	<para>After I install Linux, and are prompted about installing
 	  LILO, make SURE that I install it on the boot sector of my
 	  root Linux partition, not in the MBR (master boot
 	  record).</para>
       </step>
 
       <step>
 	<para>The remaining hard disk space can go to FreeBSD.  I also
 	  make sure that my FreeBSD root slice does not go beyond the
 	  1024th cylinder.  (The 1024th cylinder is 528 megs into the
 	  disk with our hypothetical 720MB disks).  I will use the
 	  rest of the hard drive (about 270 megs) for the
 	  <filename>/usr</filename> and <filename>/</filename> slices if I wish.  The
 	  rest of the second hard disk (size depends on the amount of
 	  my Windows application/data partition that I created in step
 	  1 can go to the <filename>/usr/src</filename> slice and swap
 	  space.</para>
       </step>
 
       <step>
 	<para>When viewed with the Windows 95 <command>fdisk</command>
 	  utility, my hard drives should now look something like this:
 
 	  <screen>---------------------------------------------------------------------
 
                   Display Partition Information
 
 Current fixed disk drive: 1
 
 Partition  Status  Type  Volume_Label  Mbytes  System  Usage
 C: 1          A   PRI DOS                50    FAT**     7%
    2          A   Non-DOS (Linux)       300             43%
 
 Total disk space is  696 Mbytes (1 Mbyte = 1048576 bytes)
 
 Press Esc to continue
 
 ---------------------------------------------------------------------
 
                   Display Partition Information
 
 Current fixed disk drive: 2
 
 Partition  Status  Type  Volume_Label  Mbytes  System  Usage
 D: 1          A   PRI DOS                420   FAT**    60%
 
 Total disk space is  696 Mbytes (1 Mbyte = 1048576 bytes)
 
 Press Esc to continue
 
 ---------------------------------------------------------------------</screen>
 	  ** May say FAT16 or FAT32 if you are using the OEM SR2
 	  update.  See <xref linkend="ch2">).</para>
       </step>
 
       <step>
 	<para>Install FreeBSD.  I make sure to boot with my first hard
 	  disk set at <quote>NORMAL</quote> in the BIOS.  If it is not,
 	  I will have the enter my true disk geometry at boot time (to
 	  get this, boot Windows 95 and consult Microsoft Diagnostics
 	  (<filename>MSD.EXE</filename>), or check your BIOS) with the
 	  parameter <literal>hd0=1416,16,63</literal> where
 	  <replaceable>1416</replaceable> is the number of cylinders on my hard
 	  disk, <replaceable>16</replaceable> is the number of heads per track,
 	  and <replaceable>63</replaceable> is the number of sectors per track on
 	  the drive.</para>
       </step>
 
       <step>
 	<para>When partitioning out the hard disk, I make sure to
 	  install Boot Easy on the first disk.  I do not worry about
 	  the second disk, nothing is booting off of it.</para>
       </step>
 
       <step>
 	<para>When I reboot, Boot Easy should recognize my three
 	  bootable partitions as DOS (Windows 95), Linux, and BSD
 	  (FreeBSD).</para>
       </step>
     </procedure>
   </sect1>
 
   <sect1 id="ch4">
     <title>Special Considerations</title>
 
     <para>Most operating systems are very picky about where and how
       they are placed on the hard disk.  Windows 95 and DOS need to be
       on the first primary partition on the first hard disk.  OS/2 is
       the exception.  It can be installed on the first or second disk
       in a primary or extended partition.  If you are not sure, keep
       the beginning of the bootable partitions below the 1024th
       cylinder.</para>
 
     <para>If you install Windows 95 on an existing BSD system, it will
       <quote>destroy</quote> the MBR, and you will have to reinstall your
       previous boot manager.  Boot Easy can be reinstalled by using
       the BOOTINST.EXE utility included in the \TOOLS directory on the
       CDROM, and via <ulink
 	URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/">ftp</ulink>.
       You can also re-start the installation process and go to the
       partition editor.  From there, mark the FreeBSD partition as
       bootable, select Boot Manager, and then type W to (W)rite out
       the information to the MBR.  You can now reboot, and Boot Easy
       should then recognize Windows 95 as DOS.</para>
 
     <para>Please keep in mind that OS/2 can read FAT and HPFS
       partitions, but not FFS (FreeBSD) or EXT2 (Linux) partitions.
       Likewise, Windows 95 can only read and write to FAT and FAT32
       (see <xref linkend="ch2">) partitions.  FreeBSD can read most
       file systems, but currently cannot read HPFS partitions.  Linux
       can read HPFS partitions, but can not write to them.  Recent
       versions of the Linux kernel (2.x) can read and write to Windows
       95 VFAT partitions (VFAT is what gives Windows 95 long file
       names - it is pretty much the same as FAT).  Linux can read and
       write to most file systems.  Got that?  I hope so.</para>
   </sect1>
 
   <sect1 id="ch5">
     <title>Examples</title>
 
     <para><emphasis>(section needs work, please send your example to
 	<email>jayrich@sysc.com</email>)</emphasis>.</para>
 
     <para>FreeBSD+Win95:  If you installed FreeBSD after Windows 95,
       you should see <literal>DOS</literal> on the Boot Easy menu.  This is
       Windows 95.  If you installed Windows 95 after FreeBSD, read
       <xref linkend="ch4"> above.  As long as your hard disk does not
       have 1024 cylinders you should not have a problem booting.  If
       one of your partitions goes beyond the 1024th cylinder however,
       and you get messages like <errorname>invalid system disk</errorname>
       under DOS (Windows 95) and FreeBSD will not boot, try looking
       for a setting in your BIOS called <quote>&gt; 1024 cylinder
 	support</quote> or <quote>NORMAL/LBA</quote> mode.  DOS may need LBA
       (Logical Block Addressing) in order to boot correctly.  If the
       idea of switching BIOS settings every time you boot up does not
       appeal to you, you can boot FreeBSD through DOS via the
       <filename>FBSDBOOT.EXE</filename> utility on the CD (It should find your
       FreeBSD partition and boot it.)</para>
 
     <para>FreeBSD+OS/2+Win95:  Nothing new here.  OS/2's boot manger
       can boot all of these operating systems, so that should not be a
       problem.</para>
 
     <para>FreeBSD+Linux: You can also use Boot Easy to boot both
       operating systems.</para>
 
     <para>FreeBSD+Linux+Win95:  (see <xref linkend="ch3">)</para>
   </sect1>
 
   <sect1 id="sources">
     <title>Other Sources of Help</title>
 
     <para>There are many <ulink
 	URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux
 	HOW-TOs</ulink> that deal with multiple operating systems on
       the same hard disk.</para>
 
     <para>The <ulink
 	URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+DOS+Win95+OS2.html">Linux+DOS+Win95+OS2
 	mini-HOWTO</ulink> offers help on configuring the OS/2 boot
       manager, and the <ulink
 	URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+FreeBSD.html">Linux+FreeBSD
 	mini-HOWTO</ulink> might be interesting as well.  The <ulink
 	URL="http://www.in.net/~jkatz/win95/Linux-HOWTO.html">Linux-HOWTO</ulink>
       is also helpful.</para>
 <![ IGNORE [
 <!-- dead link -->
     <para>The <ulink
 	URL="http://www.dorsai.org/~dcl/publications/NTLDR_Hacking">NT
 	Loader Hacking Guide</ulink> provides good information on
       multibooting Windows NT, '95, and DOS with other operating
       systems.</para>
 ]]>
     <para>And Hale Landis's <quote>How It Works</quote> document pack contains some
       good info on all sorts of disk geometry and booting related
       topics.  You can find it at
       <ulink
 	URL="ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip">ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip</ulink>.</para>
 
     <para>Finally, do not overlook FreeBSD's kernel documentation on
       the booting procedure, available in the kernel source
       distribution (it unpacks to <ulink
 	URL="file:/usr/src/sys/i386/boot/biosboot/README.386BSD">file:/usr/src/sys/i386/boot/biosboot/README.386BSD</ulink>.</para>
   </sect1>
 
   <sect1>
     <title>Technical Details</title>
 
     <para><emphasis>(Contributed by Randall Hopper,
 	<email>rhh@ct.picker.com</email>)</emphasis></para>
 
     <para>This section attempts to give you enough basic information
       about your hard disks and the disk booting process so that you
       can troubleshoot most problems you might encounter when getting
       set up to boot several operating systems.  It starts in pretty
       basic terms, so you may want to skim down in this section until
       it begins to look unfamiliar and then start reading.</para>
 
     <sect2>
       <title>Disk Primer</title>
 
       <para>Three fundamental terms are used to describe the location
 	of data on your hard disk: Cylinders, Heads, and Sectors.
 	It is not particularly important to know what these terms
 	relate to except to know that, together, they identify where
 	data is physically on your disk.</para>
 
       <para>Your disk has a particular number of cylinders, number of
 	heads, and number of sectors per cylinder-head (a
 	cylinder-head also known nown as a track).  Collectively this
 	information defines the <quote>physical disk geometry</quote> for your hard
 	disk.  There are typically 512 bytes per sector, and 63
 	sectors per track, with the number of cylinders and heads
 	varying widely from disk to disk.  Thus you can figure the
 	number of bytes of data that will fit on your own disk by
 	calculating:</para>
 
 	<informalexample>
 	  <para>(# of cylinders) &times; (# heads) &times; (63
 	    sectors/track) &times; (512 bytes/sect)</para>
 	</informalexample>
 
       <para>For example, on my 1.6 Gig Western Digital AC31600 EIDE hard
 	disk, that is:</para>
 
 	<informalexample>
 	  <para>(3148 cyl) &times; (16 heads) &times; (63
-	    sectors/track) &times (512 bytes/sect)</para>
+	    sectors/track) &times; (512 bytes/sect)</para>
 	</informalexample>
 
       <para>which is 1,624,670,208 bytes, or around 1.6 Gig.</para>
 
       <para>You can find out the physical disk geometry (number of
 	cylinders, heads, and sectors/track counts) for your hard
 	disks using ATAID or other programs off the net.  Your hard
 	disk probably came with this information as well.  Be careful
 	though: if you are using BIOS LBA (see <xref
 	  linkend="limits">), you can not use just any program to get
 	the physical geometry.  This is because many programs (e.g.
 	<filename>MSD.EXE</filename> or FreeBSD fdisk) do not identify the
 	physical disk geometry; they instead report the
 	<firstterm>translated geometry</firstterm> (virtual numbers from using
 	LBA).  Stay tuned for what that means.</para>
 
       <para>One other useful thing about these terms.  Given 3
 	numbers&mdash;a cylinder number, a head number, and a
 	sector-within-track number&mdash;you identify a specific
 	absolute sector (a 512 byte block of data) on your disk.
 	Cylinders and Heads are numbered up from 0, and Sectors are
 	numbered up from 1.</para>
 
       <para>For those that are interested in more technical details,
 	information on disk geometry, boot sectors, BIOSes, etc. can
 	be found all over the net.  Query Lycos, Yahoo, etc. for
 	<literal>boot sector</literal> or <literal>master boot record</literal>.
 	Among the useful info you will find are Hale Landis's
 	<citetitle>How It Works</citetitle> document pack.  See the <xref
 	  linkend="sources"> section for a few pointers to this
 	pack.</para>
 
       <para>Ok, enough terminology.  We are talking about booting
 	here.</para>
     </sect2>
 
     <sect2 id="booting">
       <title>The Booting Process</title>
 
       <para>On the first sector of your disk (Cyl 0, Head 0, Sector 1)
 	lives the Master Boot Record (MBR).  It contains a map of your
 	disk.  It identifies up to 4 <firstterm>partitions</firstterm>, each of
 	which is a contiguous chunk of that disk.  FreeBSD calls
 	partitions <firstterm>slices</firstterm> to avoid confusion with its
 	own partitions, but we will not do that here.  Each partition can
 	contain its own operating system.</para>
 
       <para>Each partition entry in the MBR has a <firstterm>Partition
 	  ID</firstterm>, a <firstterm>Start Cylinder/Head/Sector</firstterm>, and an
 	<firstterm>End Cylinder/Head/Sector</firstterm>.  The Partition ID
 	tells what type of partition it is (what OS) and the Start/End
 	tells where it is.  <xref linkend="tbl-pid"> lists a
 	smattering of some common Partition IDs.</para>
 
       <table id="tbl-pid">
 	<title>Partition IDs</title>
 
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>ID (hex)</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>01</entry>
 	      <entry>Primary DOS12 (12-bit FAT)</entry>
 	    </row>
 
 	    <row>
 	      <entry>04</entry>
 	      <entry>Primary DOS16 (16-bit FAT)</entry>
 	    </row>
 
 	    <row>
 	      <entry>05</entry>
 	      <entry>Extended DOS</entry>
 	    </row>
 
 	    <row>
 	      <entry>06</entry>
 	      <entry>Primary big DOS (&gt; 32MB)</entry>
 	    </row>
 
 	    <row>
 	      <entry>0A</entry>
 	      <entry>OS/2</entry>
 	    </row>
 
 	    <row>
 	      <entry>83</entry>
 	      <entry>Linux (EXT2FS)</entry>
 	    </row>
 
 	    <row>
 	      <entry>A5</entry>
 	      <entry>FreeBSD, NetBSD, 386BSD (UFS)</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
       <para>Note that not all partitions are bootable (e.g. Extended
 	DOS).  Some are&mdash;some are not.  What makes a partition
 	bootable is the configuration of the <firstterm>Partition Boot
 	  Sector</firstterm> that exists at the beginning of each
 	partition.</para>
 
       <para>When you configure your favorite boot manager, it looks up
 	the entries in the MBR partition tables of all your hard disks
 	and lets you name the entries in that list.  Then when you
 	boot, the boot manager is invoked by special code in the
 	Master Boot Sector of the first probed hard disk on your
 	system.  It looks at the MBR partition table entry
 	corresponding to the partition choice you made, uses the Start
 	Cylinder/Head/Sector information for that partition, loads up
 	the Partition Boot Sector for that partition, and gives it
 	control.  That Boot Sector for the partition itself contains
 	enough information to start loading the operating system on
 	that partition.</para>
 
       <para>One thing we just brushed past that is important to know.
 	All of your hard disks have MBRs.  However, the one that is
 	important is the one on the disk that is first probed by the
 	BIOS.  If you have only IDE hard disks, its the first IDE disk
 	(e.g. primary disk on first controller).  Similarly for SCSI
 	only systems.  If you have both IDE and SCSI hard disks
 	though, the IDE disk is typically probed first by the BIOS, so
 	the first IDE disk is the first probed disk.  The boot manager
 	you will install will be hooked into the MBR on this first
 	probed hard disk that we have just described.</para>
     </sect2>
 
     <sect2 id="limits">
       <title>Booting Limitations and Warnings</title>
 
       <para>Now the interesting stuff that you need to watch out
 	for.</para>
 
       <sect3>
 	<title>The dreaded 1024 cylinder limit and how BIOS LBA helps</title>
 
 	<para>The first part of the booting process is all done
 	  through the BIOS, (if that is a new term to you, the BIOS is
 	  a software chip on your system motherboard which provides
 	  startup code for your computer).  As such, this first part
 	  of the process is subject to the limitations of the BIOS
 	  interface.</para>
 
 	<para>The BIOS interface used to read the hard disk during
 	  this period (INT 13H, Subfunction 2) allocates 10 bits to
 	  the Cylinder Number, 8 bits to the Head Number, and 6 bits
 	  to the Sector Number.  This restricts users of this
 	  interface (i.e. boot managers hooked into your disk's MBR as
 	  well as OS loaders hooked into the Boot Sectors) to the
 	  following limits:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>1024 cylinders, max</para>
 	</listitem>
 
 	<listitem>
 	  <para>256 heads, max</para>
 	</listitem>
 
 	<listitem>
 	  <para>64 sectors/track, max (actually 63, <literal>0</literal>
 	    is not available)</para>
 	</listitem>
       </itemizedlist>
 
 	<para>Now big hard disks have lots of cylinders but not a lot
 	  of heads, so invariably with big hard disks the number of
 	  cylinders is greater than 1024.  Given this and the BIOS
 	  interface as is, you can not boot off just anywhere on your
 	  hard disk.  The boot code (the boot manager and the OS
 	  loader hooked into all bootable partitions' Boot Sectors)
 	  has to reside below cylinder 1024.  In fact, if your hard
 	  disk is typical and has 16 heads, this equates to:</para>
 
 	<informalexample>
 	  <para>1024 cyl/disk &times; 16 heads/disk &times; 63
 	    sect/(cyl-head) &times; 512 bytes/sector</para>
 	</informalexample>
 
 	<para>which is around the often-mentioned 528MB limit.</para>
 
 	<para>This is where BIOS LBA (Logical Block Addressing) comes
 	  in.  BIOS LBA gives the user of the BIOS API calls access to
 	  physical cylinders above 1024 though the BIOS interfaces by
 	  redefining a cylinder.  That is, it remaps your cylinders
 	  and heads, making it appear through the BIOS as though the
 	  disk has fewer cylinders and more heads than it actually
 	  does.  In other words, it takes advantage of the fact that
 	  hard disks have relatively few heads and lots of cylinders
 	  by shifting the balance between number of cylinders and
 	  number of heads so that both numbers lie below the
 	  above-mentioned limits (1024 cylinders, 256 heads).</para>
 
 	<para>With BIOS LBA, the hard disk size limitation is
 	  virtually removed (well, pushed up to 8 Gigabytes anyway).
 	  If you have an LBA BIOS, you can put FreeBSD or any OS
 	  anywhere you want and not hit the 1024 cylinder
 	  limit.</para>
 
 	<para>To use my 1.6 Gig Western Digital as an example again,
 	  its physical geometry is:</para>
 
 	<informalexample>
 	  <para>(3148 cyl, 16 heads, 63 sectors/track, 512
 	    bytes/sector)</para>
 	</informalexample>
 
 	<para>However, my BIOS LBA remaps this to:</para>
 
 	<informalexample>
 	  <para>(787 cyl, 64 heads, 63 sectors/track, 512
 	    bytes/sector)</para>
 	</informalexample>
 
 	<para>giving the same effective size disk, but with cylinder
 	  and head counts within the BIOS API's range (Incidentally, I
 	  have both Linux and FreeBSD existing on one of my hard disks
 	  above the 1024th physical cylinder, and both operating
 	  systems boot fine, thanks to BIOS LBA).</para>
       </sect3>
 
       <sect3>
 	<title>Boot Managers and Disk Allocation</title>
 
 	<para>Another gotcha to watch out when installing boot
 	  managers is allocating space for your boot manager.  It is
 	  best to be aware of this issue up front to save yourself
 	  from having to reinstall one or more of your OSs.</para>
 
 	<para>If you followed the discussion in <xref
 	    linkend="booting"> about the Master Boot Sector (where the
 	  MBR is), Partition Boot Sectors, and the booting process,
 	  you may have been wondering just exactly where on your hard
 	  disk that nifty boot manager is going to live.  Well, some
 	  boot managers are small enough to fit entirely within the
 	  Master Boot Sector (Cylinder 0, Head 0, Sector 0) along with
 	  the partition table.  Others need a bit more room and
 	  actually extend a few sectors past the Master Boot Sector in
 	  the Cylinder 0 Head 0 track, since that is typically
 	  free&hellip;typically.</para>
 
 	<para>That is the catch.  Some operating systems (FreeBSD
 	  included) let you start their partitions right after the
 	  Master Boot Sector at Cylinder 0, Head 0, Sector 2 if you
 	  want.  In fact, if you give FreeBSD's sysinstall a disk with
 	  an empty chunk up front or the whole disk empty, that is
 	  where it will start the FreeBSD partition by default (at least
 	  it did when I fell into this trap).  Then when you go to
 	  install your boot manager, if it is one that occupies a few
 	  extra sectors after the MBR, it will overwrite the front of
 	  the first partition's data.  In the case of FreeBSD, this
 	  overwrites the disk label, and renders your FreeBSD
 	  partition unbootable.</para>
 
 	<para>The easy way to avoid this problem (and leave yourself
 	  the flexibility to try different boot managers later) is
 	  just to always leave the first full track on your disk
 	  unallocated when you partition your disk.  That is, leave
 	  the space from Cylinder 0, Head 0, Sector 2 through Cylinder
 	  0, Head 0, Sector 63 unallocated, and start your first
 	  partition at Cylinder 0, Head 1, Sector 1.  For what it is
 	  worth, when you create a DOS partition at the front of your
 	  disk, DOS leaves this space open by default (this is why
 	  some boot managers assume it is free).  So creating a DOS
 	  partition up at the front of your disk avoids this problem
 	  altogether.  I like to do this myself, creating 1 Meg DOS
 	  partition up front, because it also avoids my primary DOS
 	  drive letters shifting later when I repartition.</para>
 
 	<para>For reference, the following boot managers use the
 	  Master Boot Sector to store their code and data:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>OS-BS 1.35</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Boot Easy</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>LILO</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>These boot managers use a few additional sectors after
 	  the Master Boot Sector:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>OS-BS 2.0 Beta 8 (sectors 2-5)</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>OS/2's boot manager</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>What if your machine will not boot?</title>
 
 	<para>At some point when installing boot managers, you might
 	  leave the MBR in a state such that your machine will not boot.
 	  This is unlikely, but possible when re-FDISKing underneath
 	  an already-installed boot manager.</para>
 
 	<para>If you have a bootable DOS partition on your disk, you
 	  can boot off a DOS floppy, and run:</para>
 
 	<informalexample>
 	  <screen>A:\> <userinput>FDISK /MBR</userinput></screen>
 	</informalexample>
 
 	<para>to put the original, simple DOS boot code back into the
 	  system.  You can then boot DOS (and DOS only) off the hard
 	  drive.  Alternatively, just re-run your boot manager
 	  installation program off a bootable floppy.</para>
       </sect3>
     </sect2>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/articles/releng/article.sgml b/en_US.ISO8859-1/articles/releng/article.sgml
index 269515f0b7..dd005616fb 100644
--- a/en_US.ISO8859-1/articles/releng/article.sgml
+++ b/en_US.ISO8859-1/articles/releng/article.sgml
@@ -1,892 +1,892 @@
 <!--
      The FreeBSD Documentation Project
 -->
 
 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY branches.ascii SYSTEM "branches.ascii">
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
 <!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//EN">
 %teams;
 <!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
 %mailing-lists;
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 <!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
 %freebsd;
 <!ENTITY art.re.pkgs '<ulink url="../releng-packages/article.html">The Release Engineering of Third Party Packages</ulink>'>
 ]>
 
 <article>
   <title>FreeBSD Release Engineering</title>
   <articleinfo>
 
     <!-- This paper was presented at BSDCon Europe in Brighton, UK on
          November 11, 2001 -->
     <confgroup>
       <confdates>November 2001</confdates>
       <conftitle>BSDCon Europe</conftitle>
     </confgroup>
 
     <authorgroup>
       <author>
         <firstname>Murray</firstname>
         <surname>Stokely</surname>
         <authorblurb>
           <para>I've been involved in the development of FreeBSD based products
           since 1997 at Walnut Creek CDROM, BSDi, and now Wind River Systems.
           FreeBSD 4.4 was the first official release of FreeBSD that I played
           a significant part in.</para>
         </authorblurb>
         <affiliation>
           <address><email>murray@FreeBSD.org</email>
           <otheraddr><ulink
           url="http://www.FreeBSD.org/~murray">http://www.FreeBSD.org/~murray</ulink></otheraddr>
           </address>
         </affiliation>
       </author>
     </authorgroup>
 
     <pubdate>$FreeBSD$</pubdate>
     <abstract>
       <para>This paper describes the approach used by the FreeBSD
         release engineering team to make production quality releases
         of the FreeBSD Operating System.  It details the methodology
         used for the release of FreeBSD 4.4 and describes the tools
         available for those interested in producing customized FreeBSD
         releases for corporate rollouts or commercial
         productization.</para>
     </abstract>
 
   </articleinfo>
   
 <!-- Introduction -->
 <sect1 id="introduction">
   <title>Introduction</title>
 
   <para>The development of FreeBSD is a very open process.  FreeBSD is
     comprised of contributions from thousands of people around the
     world.  The FreeBSD Project provides anonymous
     <acronym>CVS</acronym>[1] access to the general public so that
     others can have access to log messages, diffs (patches) between
     development branches, and other productivity enhancements that
     formal source code management provides.  This has been a huge help
     in attracting more talented developers to FreeBSD.  However, I
     think everyone would agree that chaos would soon manifest if write
     access was opened up to everyone on the Internet.  Therefore only
     a <quote>select</quote> group of nearly 300 people are given write
     access to the <acronym>CVS</acronym> repository.  These
     <emphasis>committers[6]</emphasis> are responsible for the bulk of
     FreeBSD development.  An elected <emphasis>core-team[7]</emphasis>
     of very senior developers provides some level of direction over
     the project.</para>
   
   <para>The rapid pace of <systemitem
     class="osname">FreeBSD</systemitem> development leaves little time
     for polishing the development system into a production quality
     release.  To solve this dilemma, development continues on two
     parallel tracks.  The main development branch is the
     <emphasis>HEAD</emphasis> or <emphasis>trunk</emphasis> of our CVS
     tree, known as <quote>FreeBSD-CURRENT</quote> or
     <quote>-CURRENT</quote> for short.</para>
   
   <para>A more stable branch is maintained, known as
     <quote>FreeBSD-STABLE</quote> or <quote>-STABLE</quote> for short.
     Both branches live in a master CVS repository in California and
     are replicated via <application
     class="software">CVSup</application>[2] to mirrors all over the
     world.  FreeBSD-CURRENT[8] is the <quote>bleeding-edge</quote> of
     FreeBSD development where all new changes first enter the system.
     FreeBSD-STABLE is the development branch from which major releases
     are made.  Changes go into this branch at a different pace, and
     with general assumption that they have first gone into
     FreeBSD-CURRENT and have been thoroughly tested by our user
     community.</para>
   
   <para>In the interim period between releases, nightly snapshots are
     built automatically by the FreeBSD Project build machines and made
     available for download from <systemitem
     class="resource">ftp://stable.FreeBSD.org/</systemitem>.  The
     widespread availability of binary release snapshots, and the
     tendency of our user community to keep up with -STABLE development
     with CVSup and <quote><command>make</command>
     <MakeTarget>world</MakeTarget></quote>[8] helps to keep
     FreeBSD-STABLE in a very reliable condition even before the
     quality assurance activities ramp up pending a major
     release.</para>
   
   <para>Bug reports and feature requests are continuously submitted by
     users throughout the release cycle.  Problems reports are entered into our
     <application class="software">GNATS</application>[9] database
-    through email, the &man.send-pr.1 application, or via the web
+    through email, the &man.send-pr.1; application, or via the web
     interface provided at <ulink
     url="http://www.FreeBSD.org/send-pr.html"></ulink>
     In addition to the multitude of different technical mailing lists
     about FreeBSD, the &a.qa; provides a forum for discussing the finer
     points of <quote>release-polishing</quote>.</para>
   
   <para>To service our most conservative users, individual release
     branches were introduced with FreeBSD 4.3.
     These release branches are created shortly before a final release
     is made.  After the release goes out, only the most critical
     security fixes and additions are merged onto the release branch.
     In addition to source updates via CVS, binary patchkits are
     available to keep systems on the <emphasis>RELENG_4_3 </emphasis>
     and <emphasis>RELENG_4_4</emphasis> branches updated.</para>
   
   <para><link linkend="release-proc">Section 2</link> discusses the
     different phases of the release engineering process leading up to
     the actual system build and <link linkend="release-build">section
     3</link> describes the actual build process.  <link
     linkend="extensibility">Section 4</link> describes how the base
     release may be extended by third parties and <link
     linkend="lessons-learned">section 5</link> details some of the
     lessons learned through the release of FreeBSD 4.4.  Finally,
     <link linkend="future">section 6</link> presents future directions
     of development.</para>
 </sect1>
 
 <!-- Release Process -->
 <sect1 id="release-proc">
   <title>Release Process</title>
 
   <para>New releases of FreeBSD are released from the -STABLE branch
     at approximately four month intervals.  The FreeBSD release
     process begins to ramp up 45 days before the anticipated release
     date when the release engineer sends an email to the development
     mailing lists to remind developers that they only have 15 days to
     integrate new changes before the code freeze.  During this time,
     many developers perform what have become know as <quote>MFC
     sweeps</quote>.  <acronym>MFC</acronym> stands for <quote>Merge
     From CURRENT</quote> and it describes the process of merging a
     tested change from our -CURRENT development branch to our -STABLE
     branch.</para>
   
   <sect2>
     <title>Code Review</title>
 
     <para>Thirty days before the anticipated release, the source
       repository enters a <quote>code slush</quote>.  During this
       time, all commits to the -STABLE branch must be approved by the
       &a.re;.  The kinds of changes that are allowed during this 15 day
       period include:</para>
     
     <itemizedlist>
       <listitem>
         <para>Bug fixes.</para>
       </listitem>
       
       <listitem>
         <para>Documentation updates.</para>
       </listitem>
       
       <listitem>
         <para>Security-related fixes of any kind.</para>
       </listitem>
       
       <listitem>
         <para>Minor changes to device drivers, such as adding new Device
         IDs.</para>
       </listitem>
       
       <listitem>
         <para>Any additional change that the release engineering team feels
         is justified, given the potential risk.</para>
       </listitem>
     </itemizedlist>
     
     <para>After the first 15 days of the code slush, a
       <emphasis>release candidate</emphasis> is released for
       widespread testing and the code enters a <quote>code
       freeze</quote> where it becomes much harder to justify new
       changes to the system unless a serious bug-fix or security issue
       is involved.  During the code freeze, at least one release
       candidate is released per week, until the final release is
       ready.  During the days leading to the final release, the
       release engineering team is in constant communication with the
       security-officer team, the documentation maintainers, and the
       port maintainers, to ensure that all of the
       different components required for a successful release are
       available.</para>
   </sect2>
   
   <sect2>
     <title>Final Release Checklist</title>
 
     <para>When several release candidates have been made available for
       widespread testing and all major issues have been resolved, the
       final release <quote>polishing</quote> can begin.</para>
     
     <sect3>
       <title>Creating the Release Branch</title>
 
       <para>As described in the introduction, the <literal>RELENG_X_Y</literal> release
         branch is a relatively new addition to our release engineering
         methodology.  The first step in creating this branch is to
         ensure that you are working with the newest version of the
         <literal>RELENG_X</literal> sources that you want to branch
         <emphasis>from</emphasis>.</para>
       
       <screen>/usr/src&prompt.root; <userinput>cvs up -rRELENG_4 -P -d</userinput></screen>
       
       <para>The next step is to create a branch point
         <emphasis>tag</emphasis>, so that diffs against the start of
         the branch are easier with CVS:</para>
       
       <screen>/usr/src&prompt.root; <userinput>cvs rtag -rRELENG_4 RELENG_4_4_BP src</userinput></screen>
       
       <para>And then a new branch tag is created with:</para>
       
       <screen>/usr/src&prompt.root; <userinput>cvs rtag -b -rRELENG_4_4_BP RELENG_4_4 src</userinput></screen>
       
       <note>
         <para><emphasis>The <literal>RELENG_*</literal> tags are
           restricted for use by the CVS-meisters and release
           engineers.</emphasis></para>
       </note>
       
       <sidebar>
         <para>A <quote><emphasis>tag</emphasis></quote> is CVS
         vernacular for a label that identifies the source at a specific point
         in time.  By tagging the tree, we ensure that future release builders
         will always be able to use the same source we used to create the 
         official FreeBSD Project releases.</para>
       </sidebar>
       
       <mediaobject>
         <imageobject>
           <imagedata fileref="branches" align="center"> 
         </imageobject>
 
         <textobject>
           <literallayout>
           &branches.ascii;
           </literallayout>
         </textobject>
     
         <textobject>
           <phrase>FreeBSD Development Branches</phrase> 
         </textobject>
       </mediaobject>
 
     </sect3>
     
     <sect3 id="versionbump">
       <title>Bumping up the Version Number</title>
 
       <para>Before the final release can be tagged, built, and
         released, the following files need to be modified to reflect
         the correct version of FreeBSD:</para>
 
       <itemizedlist>
         <listitem>
           <para><filename>doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
           </filename></para>
         </listitem>
 
         <listitem>
           <para><filename>doc/share/sgml/freebsd.ent</filename></para>
         </listitem>
 
         <listitem>
           <para><filename>src/Makefile.inc</filename></para>
         </listitem>
 
         <listitem>
           <para><filename>src/UPDATING</filename></para>
         </listitem>
 
         <listitem>
           <para><filename>src/gnu/usr.bin/groff/tmac/mdoc.local</filename></para>
         </listitem>
 
         <listitem>
           <para><filename>src/release/Makefile</filename></para>
         </listitem>
       
         <listitem>
           <para><filename>src/release/doc/en_US.ISO8859-1/share/sgml/release.dsl</filename></para>
         </listitem>
       
         <listitem>
           <para><filename>src/release/doc/share/examples/Makefile.relnotesng</filename></para>
         </listitem>
       
         <listitem>
           <para><filename>src/release/doc/share/sgml/release.ent</filename></para>
         </listitem>
       
         <listitem>
           <para><filename>src/sys/conf/newvers.sh</filename></para>
         </listitem>
       
         <listitem>
           <para><filename>src/sys/sys/param.h</filename></para>
         </listitem>
       
         <listitem>
           <para><filename>www/en/releases/*</filename></para>
         </listitem>
 
         <listitem>
           <para><filename>www/en/docs.sgml</filename></para>
         </listitem>
 
       </itemizedlist>
     
       <para>The release notes and errata files also need to be adjusted for the
       new release (on the release branch) and truncated appropriately 
       (on the stable/current branch):</para>
     
       <itemizedlist>
         <listitem>
           <para><filename>src/release/doc/en_US.ISO8859-1/relnotes/common/new.sgml
           </filename></para>
         </listitem>
       
         <listitem>
           <para><filename>src/release/doc/en_US.ISO8859-1/errata/article.sgml
           </filename></para>
         </listitem>
       </itemizedlist>
 
       <para><application>Sysinstall</application> should be updated to note 
         the number of available ports and the amount of disk space required
 	for the Ports Collection.  This information is currently kept in 
 	<filename>src/release/sysinstall/dist.c</filename>.</para>
     </sect3>
     
     <sect3>
       <title>Creating Release Tags</title>
 
       <para>When the final release is ready, the following command
         will create the <literal>RELENG_4_4_0_RELEASE</literal>
         tag.</para>
       
       <screen>
       /usr/src&prompt.root; <userinput>cvs rtag -rRELENG_4_4 RELENG_4_4_0_RELEASE src</userinput>
       </screen>
       
       <para>The Documentation and Ports managers are responsible for
         tagging the respective trees with the <literal>RELEASE_4_4_0</literal>
         tag.</para>
       
       <para>Occasionally, a last minute fix may be required
         <emphasis>after</emphasis> the final tags have been created.
         In practice this isn't a problem, since <acronym>CVS</acronym>
         allows tags to be manipulated with <command>cvs
         tag -d <replaceable>tagname filename</replaceable></command>.
         It is very important that any last minute changes be tagged
         appropriately as part of the release.  FreeBSD releases must
         always be reproduceable.  Local hacks in the release
         engineer's environment are not acceptable.</para>
     </sect3>
   </sect2>
 </sect1>
 
 <!-- Release Building -->
 <sect1 id="release-build">
   <title>Release Building</title>
 
   <para>FreeBSD <quote>releases</quote> can be built by anyone with a
     fast machine and access to a source repository. (That should be
     everyone, since we offer anonymous CVS! See The Handbook for
     details.).  The <emphasis>only</emphasis> special requirement is
     that the <devicename>vn</devicename> (<emphasis>On -CURRENT, this
     device has been replaced by the new <devicename>md</devicename>
     memory disk driver </emphasis>.)  device must be available. If the
     device is not loaded into your kernel, then the kernel module
     should be automatically loaded when &man.vnconfig.8; is executed
     during the boot media creation phase.  All of the tools necessary
     to build a release are available from the CVS repository in
     <filename>src/release</filename>.  These tools aim to provide a
     consistent way to build FreeBSD releases.  A complete release can
     actually be built with only a single command, including the
     creation of <acronym>ISO</acronym> images suitable for burning to
     CDROM, installation floppies, and an FTP install directory.  This
     command is aptly named <quote><command>make
     release</command></quote>.</para>
   
   <sect2>
     <title><quote>make release</quote></title>
 
     <para>To successfully build a release, you must first populate
       <filename>/usr/obj</filename> by running <quote><command>make
       world</command></quote> or simply
       <quote><command>make
       buildworld</command></quote>. The release
       target requires several variables be set properly to build a
       release:</para>
     
     <itemizedlist>
       <listitem>
         <para><makevar>CHROOTDIR</makevar> - The directory to be used as the
         chroot environment for the entire release build.</para>
       </listitem>
       
       <listitem>
         <para><makevar>BUILDNAME</makevar> - The name of the release to be
         built.</para>
       </listitem>
       
       <listitem>
         <para><makevar>CVSROOT</makevar> - The location of a CVS Repository.
         </para>
       </listitem>
       
       <listitem>
         <para><makevar>RELEASETAG</makevar> - The CVS tag corresponding to the
         release you would like to build.</para>
       </listitem>    
     </itemizedlist>
     
      <para>If you do not already have access to a local CVS
        repository, then you may mirror one with <ulink
        url="http://www.FreeBSD.org/handbook/synching.html#CVSUP">CVSup</ulink>.
        The supplied supfile,
        <filename>/usr/share/examples/cvsup/cvs-supfile</filename>, is
        a useful starting point for mirroring the CVS
        repository.</para>
 
      <para>If <makevar>RELEASETAG</makevar> is omitted, then the
        release will be built from the HEAD (a.k.a. -CURRENT) branch.
        Releases built from this branch are normally referred to as
        <quote>-CURRENT snapshots</quote>.</para>
 
      <para>There are many other variables available to customize the
        release build. Most of these variables are documented at the
        top of <filename>src/release/Makefile</filename>. The exact
        command used to build the official FreeBSD 4.4 (x86) release
        was:</para>
      
      <screen><command>make <literal>release CHROOTDIR=/local3/release \
        BUILDNAME=4.4-RELEASE \
        CVSROOT=/host/cvs/usr/home/ncvs \
        RELEASETAG=RELENG_4_4_0_RELEASE</literal>
        </command>
      </screen>
 
      <para>The release Makefile can be broken down into several distinct
        steps.</para>
      
     <itemizedlist>
       <listitem>
         <para>Creation of a sanitized system environment in a separate 
 	directory hierarchy with <quote><command>make 
 	<literal>installworld</literal></command></quote>.
         </para>
       </listitem>
       
       <listitem>
         <para>Checkout from CVS of a clean version of the system source, 
         documentation, and ports into the release build hierarchy.</para>
       </listitem>
       
       <listitem>
         <para>Population of <filename>/etc</filename> and 
         <filename>/dev</filename> in the chrooted
         environment.</para>
       </listitem>
       
       <listitem>
         <para>chroot into the release build hierarchy, to make it harder for 
         the outside environment to taint this build.</para>
       </listitem>
       
       <listitem>
         <para><quote><command>make world</command></quote> 
         in the chrooted environment.</para>
       </listitem>
       
       <listitem>
         <para>Build of Kerberos-related binaries.</para>
       </listitem>
       
       <listitem>
         <para>Build <quote><filename>GENERIC</filename></quote> kernel.</para>
       </listitem>
       
       <listitem>
         <para>Creation of a staging directory tree where the binary 
         distributions will be built and packaged.</para>
       </listitem>
       
       <listitem>
         <para>Build and installation of the documentation toolchain needed to 
         convert the documentation source (SGML) into HTML and text documents 
         that will accompany the release.</para>
       </listitem>
       
       <listitem>
         <para>Build and installation of the actual documentation 
         (user manuals, tutorials, release notes, hardware compatibility lists, 
         and so on.)</para>
       </listitem>
       
       <listitem>
         <para>Build of the <quote>crunched</quote> binaries used for 
         installation floppies.</para>
       </listitem>
       
       <listitem>
         <para>Package up distribution tarballs of the binaries and sources.
         </para>
       </listitem>
       
       <listitem>
         <para>Create the boot media and a <quote>fixit</quote> floppy.</para>
       </listitem>
       
       <listitem>
         <para>Create FTP installation hierarchy.</para>
       </listitem>
       
       <listitem>
         <para><emphasis>(optionally)</emphasis> Create ISO images for 
         CDROM/DVD media.</para>
       </listitem>
     </itemizedlist>
 
     <para>For more information about the release build infrastructure,
       please see &man.release.7;.</para>
 
   </sect2>
   
   <sect2>
     <title>Building XFree86</title>
 
     <para>XFree86 is an important component for many desktop users.
       The easiest way to build XFree86 is to use the
       <filename>src/release/scripts/X11/build_x.sh</filename> script.
       This script requires that XFree86 and Tcl/Tk already be
       installed on the build host.  After compiling the necessary X
       servers, the script will package all of the files into tarballs
       that &man.sysinstall.8; expects to find in the
       <filename>XF86336</filename> directory of the installation
       media.</para>
 
     <note><para>It is important to remove any site-specific settings
       from <filename>/etc/make.conf</filename>.  For example, it would
       be unwise to distribute binaries that were built on a system
       with <varname>CPUTYPE</varname> set to a specific
       processor.</para></note>
     
   </sect2>
 
   <sect2>
     <title>Contributed Software (<quote>ports</quote>)</title>
 
     <para>The <ulink url="http://www.FreeBSD.org/ports">FreeBSD Ports
       collection</ulink> is a collection of over &os.numports;
       third-party software packages available for FreeBSD. The &a.portmgr;
       is responsible for maintaining a consistent ports tree that can be used
       to create the binary packages that accompany official FreeBSD
       releases.</para>
 
     <para>The release engineering activities for our collection of
       third-party packages is beyond the scope of this document.  A
       separate article, &art.re.pkgs;, covers this topic
       in depth.</para>
 
   </sect2>
   
   <sect2>
     <title>Release ISOs</title>
 
     <para>Starting with FreeBSD 4.4, the FreeBSD Project decided to
       release all four ISO images that were previously sold on the
       <emphasis>BSDi/Wind River Systems/FreeBSD Mall</emphasis>
       <quote>official</quote> CDROM distributions. Each of the four
       discs must contain a <filename>README.TXT</filename> file that
       explains the contents of the disc, a
       <filename>CDROM.INF</filename> file that provides meta-data for
       the disc so that &man.sysinstall.8; can validate and use the
       contents, and a <filename>filename.txt</filename> file that
       provides a manifest for the disc. This
       <emphasis>manifest</emphasis> can be created with a simple
       command:</para>
     
     <screen>/stage/cdrom&prompt.root; <userinput>find . -type f | sed -e 's/\^.\///' | sort > filename.txt</userinput></screen>
     
     <para>The specific requirements of each CD are outlined below.</para>
     
     <sect3>
       <title>Disc 1</title>
 
       <para>The first disc is almost completely created by
         <quote><command>make
         <literal>release</literal></command></quote>. The only changes
         that should be made to the disc1 directory are the addition of
         a <filename>tools</filename> directory, <application
         class="software">XFree86</application>, and as many popular
         third party software packages as will fit on the disc. The
         <filename>tools</filename> directory contains software that allow users to create
         installation floppies from other operating systems. This disc
         should be made bootable so that users of modern PCs do not
         need to create installation floppy disks.</para>
       
       <para>If an alternate version of XFree86 is to be provided, then
         &man.sysinstall.8; must be updated to reflect the new location
         and installation instructions. The relevant code is contained
         in <filename>src/release/sysinstall</filename> on -STABLE or
         <filename>src/usr.sbin/sysinstall</filename> on
         -CURRENT. Specifically, the files <filename>dist.c</filename>,
         <filename>menus.c</filename>, and
         <filename>config.c</filename> will need to be updated.</para>
     </sect3>
     
     <sect3>
       <title>Disc 2</title>
 
       <para>The second disc is also largely created by <quote>make
         release</quote>. This disc contains a <quote>live
         filesystem</quote> that can be used from &man.sysinstall.8; to
         troubleshoot a FreeBSD installation. This disc should be
         bootable and should also contain a compressed copy of the CVS
         repository in the <filename>CVSROOT</filename> directory and
         commercial software demos in the <filename>commerce</filename>
         directory.</para>
     </sect3>
     
     <sect3>
       <title>Discs 3 and 4</title>
 
       <para>The remaining two discs contain additional software
         packages for FreeBSD. The packages should be clustered so that
         a package and all of its <emphasis>dependencies</emphasis> are
         included on the same disc.  More information about the
         creation of these discs is provided in the &art.re.pkgs;
         article.</para>
     </sect3>
   </sect2>
 </sect1>
 
 <!-- Extensibility -->
 <sect1 id="extensibility">
   <title>Extensibility</title>
 
   <para>Although FreeBSD forms a complete operating system, there is
     nothing that forces you to use the system exactly as we have
     packaged it up for distribution. We have tried to design the
     system to be as extensible as possible so that it can serve as a
     platform that other commercial products can be built on top
     of. The only <quote>rule</quote> we have about this is that if you
     are going to distribute FreeBSD with non-trivial changes, we
     encourage you to document your enhancements! The FreeBSD community
     can only help support users of the software we provide. We
     certainly encourage innovation in the form of advanced
     installation and administration tools, for example, but we can't
     be expected to answer questions about it.</para>
   
   <sect2>
     <title>Creating Customized Boot floppies</title>
 
     <para>Many sites have complex requirements that may require
       additional kernel modules or userland tools be added to the
       installation floppies.  The <quote>quick and dirty</quote> way
       to accomplish this would be to modify the staging directory of
       an existing <quote>make release</quote> build hierarchy:</para>
     
     <itemizedlist>
       <listitem>
         <para>Apply patches or add additional files inside the chroot
           release build directory.</para>
       </listitem>
       
       <listitem>
         <para><command>rm 
         ${CHROOTDIR}/usr/obj/usr/src/release/release.[48]</command></para>
       </listitem>
       
       <listitem>
         <para>rebuild &man.sysinstall.8;, the kernel, or whatever
           parts of the system your change affected.</para>
       </listitem>
       
       <listitem>
         <para><command>chroot ${CHROOTDIR} ./mk release.4
         </command></para>
       </listitem>
       
       <listitem>
         <para><command>chroot ${CHROOTDIR} ./mk release.8
         </command></para>
       </listitem>
     </itemizedlist>
     
     <para>New release floppies will be located in
       <filename>${CHROOTDIR}/R/stage/floppies</filename>.</para>
     
     <para>Alternatively, the
       <quote><filename>boot.flp</filename></quote> make
       target can be called, or the filesystem
       creating script,
       <filename>src/release/scripts/doFS.sh</filename>, may be invoked
       directly.</para>
     
     <para>Local patches may also be supplied to the release build by
       defining the <makevar>LOCAL_PATCH</makevar> variable in <quote>make
       release</quote>.
     </para>
   </sect2>
   
   <sect2>
     <title>Scripting <command>sysinstall</command></title>
 
     <para>The FreeBSD system installation and configuration tool,
-      &man.sysinstall.8, can be scripted to provide automated installs
+      &man.sysinstall.8;, can be scripted to provide automated installs
       for large sites. This functionality can be used in conjunction
       with Intel's PXE[13] to bootstrap systems from the network, or
       via custom boot floppies with a sysinstall script.  An example
       sysinstall script is available in the CVS tree as
       <filename>src/release/sysinstall/install.cfg</filename>.</para>
   </sect2>
 </sect1>
 
 <!-- Lessons Learned -->
 <sect1 id="lessons-learned">
   <title>Lessons Learned from FreeBSD 4.4</title>
 
   <para>The release engineering process for 4.4 formally began on
     August 1st, 2001. After that date all commits to the
     <literal>RELENG_4</literal> branch of FreeBSD had to be explicitly
     approved by the &a.re;.  The first
     release candidate for the x86 architecture was released on August
     16, followed by 4 more release candidates leading up to the final
     release on September 18th.  The security officer was very involved
     in the last week of the process as several security issues were
     found in the earlier release candidates. A total of over
     <emphasis>500</emphasis> emails were sent to the &a.re; in
     little over a month.</para>
   
   <para>Our user community has made it very clear that the security
     and stability of a FreeBSD release should not be sacrificed for
     any self-imposed deadlines or target release dates.  The FreeBSD
     Project has grown tremendously over its lifetime and the need for
     standardized release engineering procedures has never been more
     apparent. This will become even more important as FreeBSD is
     ported to new platforms.</para>
 </sect1>
 
 <!-- Future Directions -->
 <sect1 id="future">
   <title>Future Directions</title>
 
   <para>It is imperative for our release engineering activities to
     scale with our growing userbase. Along these lines we are working
     very hard to document the procedures involved in producing FreeBSD
     releases.</para>
   
   <itemizedlist>
     <listitem>
       <para><emphasis>Parallelism</emphasis> - Certain portions of the
         release build are actually <quote>embarrassingly
         parallel</quote>.  Most of the tasks are very I/O intensive,
         so multiple high-speed disk drives is actually important that
         multiple processors in speeding up the <quote>make
         release</quote> process.  If multiple disks are used for
         different hierarchies in the <emphasis>chroot</emphasis>
         environment, then the CVS checkout of the ports and doc trees
         can be happening simultaneously to the <quote>make
         <literal>world</literal></quote> on another disk.  Using a
         <acronym>RAID</acronym> solution (hardware or software) can
         significantly decrease the overall build time.</para>
     </listitem>
       
     <listitem>
       <para><emphasis>Cross-building releases</emphasis> - Building
         IA-64 or Alpha release on x86 hardware? <quote>make
         TARGET=ia64 release</quote>.
       </para>
     </listitem>
     
     <listitem>
       <para><emphasis>Regression Testing</emphasis> - We need better
         automated correctness testing for FreeBSD.</para>
     </listitem>
       
     <listitem>
       <para><emphasis>Installation Tools</emphasis> - Our installation
         program has long since outlived its intended life span.
         Several projects are under development to provide a more
         advanced installation mechanism.  One of the most promising is
         the libh project[5] which aims to provided an intelligent new
         package framework and GUI installation program.</para>
     </listitem>
   </itemizedlist>
   
 </sect1>
 
 <!-- Acknowledgements -->
 <sect1 id="ackno">
 <title>Acknowledgements</title>
 
   <para>I would like to thank Jordan Hubbard for giving me the
     opportunity to take some on some of the release engineering
     responsibilities for FreeBSD 4.4 and also for all of his work
     throughout the years making FreeBSD what it is today.  Of course
     the release wouldn't have been possible without all of the
     release-related work done by &a.asami;, &a.steve;, &a.bmah;, &a.nik;,
     &a.obrien;, &a.kris;, &a.jhb; and the rest of the FreeBSD development
     community.  I would also like to thank &a.rgrimes;, &a.phk;, and others
     who worked on the release engineering tools in the very early days
     of FreeBSD.  This article was influenced by release engineering
     documents from the CSRG[14], the NetBSD Project[11], and John
     Baldwin's proposed release engineering process notes[12].</para>
 </sect1>
 
 <!-- Reference / Biblio Section -->
 <sect1 id="biblio">
   <title>References</title>
   <para>[1] CVS - Concurrent Versions System 
   <ulink url="http://www.cvshome.org"></ulink></para>
   
   <para>[2] CVSup - The CVS-Optimized General Purpose Network File Distribution
   System <ulink url="http://www.polstra.com/projects/freeware/CVSup"></ulink>
   </para>
   
   <para>[3] <ulink url="http://bento.FreeBSD.org"></ulink></para>
   
   <para>[4] FreeBSD Ports Collection 
   <ulink url="http://www.FreeBSD.org/ports"></ulink></para>
   
   <para>[5] The libh Project 
   <ulink url="http://www.FreeBSD.org/projects/libh.html"></ulink></para>
   
   <para>[6] FreeBSD Committers <ulink 
   url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/staff-committers.html"></ulink>
   </para>
   
   <para>[7] FreeBSD Core-Team 
   <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/staff-core.html"></ulink></para>
   
   <para>[8] FreeBSD Handbook 
   <ulink url="http://www.FreeBSD.org/handbook"></ulink>
   </para>
   
   <para>[9] GNATS: The GNU Bug Tracking System
   <ulink url="http://www.gnu.org/software/gnats"></ulink>
   </para>
   
   <para>[10] FreeBSD PR Statistics
   <ulink url="http://www.FreeBSD.org/prstats/index.html"></ulink></para>
   
   <para>[11] NetBSD Developer Documentation: Release Engineering 
   <ulink url="http://www.NetBSD.org/developers/releng/index.html"></ulink>
   </para>
   
   <para>[12] John Baldwin's FreeBSD Release Engineering Proposal 
   <ulink url="http://people.FreeBSD.org/~jhb/docs/releng.txt"></ulink>
   </para>
   
   <para>[13] PXE Jumpstart Guide 
   <ulink 
   url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/pxe/index.html"></ulink>
   </para>
   
   <para>[14] Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: 
   <ulink url="http://docs.freebsd.org/doc/papers/releng.html">
 <emphasis>The Release Engineering of 4.3BSD</emphasis></ulink>
   </para>
 </sect1>
 </article>
diff --git a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
index 377baa357b..d65c161379 100644
--- a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
@@ -1,1587 +1,1587 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="ipv6">
   <title>IPv6 Internals</title>
 
   <sect1 id="ipv6-implementation">
     <title>IPv6/IPsec Implementation</title>
 
     <para><emphasis>Contributed by &a.shin;, 5 March
         2000.</emphasis></para>
 
     <para>This section should explain IPv6 and IPsec related implementation
     internals.  These functionalities are derived from <ulink
     url="http://www.kame.net/">KAME project</ulink></para>
 
     <sect2 id="ipv6details">
       <title>IPv6</title>
 
       <sect3>
         <title>Conformance</title>
 
         <para>The IPv6 related functions conforms, or tries to conform to
 	the latest set of IPv6 specifications.  For future reference we list
 	some of the relevant documents below (<emphasis>NOTE</emphasis>: this
 	is not a complete list - this is too hard to maintain...).</para>
 
         <para>For details please refer to specific chapter in the document,
 	RFCs, man pages, or comments in the source code.</para>
 
         <para>Conformance tests have been performed on the KAME STABLE kit
         at TAHI project.  Results can be viewed at <ulink
 	url="http://www.tahi.org/report/KAME/">http://www.tahi.org/report/KAME/
 	</ulink>.  We also attended Univ. of New Hampshire IOL tests (<ulink
 	url="http://www.iol.unh.edu/">http://www.iol.unh.edu/</ulink>) in the
 	past, with our past snapshots.</para>
 
         <itemizedlist>
           <listitem>
 	    <para>RFC1639: FTP Operation Over Big Address Records
 	    (FOOBAR)</para>
 	    <itemizedlist>
 	      <listitem>
 	        <para>RFC2428 is preferred over RFC1639.  FTP clients will
 		first try RFC2428, then RFC1639 if failed.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem> 
 
           <listitem>
 	    <para>RFC1886: DNS Extensions to support IPv6</para>
 	  </listitem>
 
           <listitem>
 	    <para>RFC1933: Transition Mechanisms for IPv6 Hosts and
 	    Routers</para>
 	    <itemizedlist>
               <listitem>
 	        <para>IPv4 compatible address is not supported.</para>
 	      </listitem>
               <listitem>
 	        <para>automatic tunneling (described in 4.3 of this RFC) is not
 		supported.</para>
 	      </listitem>
               <listitem>
 	        <para>&man.gif.4; interface implements IPv[46]-over-IPv[46]
 		tunnel in a generic way, and it covers "configured tunnel"
 		described in the spec.  See <link linkend="gif">23.5.1.5</link>
 		in this document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
             <para>RFC1981: Path MTU Discovery for IPv6</para>
           </listitem>
 
           <listitem>
             <para>RFC2080: RIPng for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
                 <para>usr.sbin/route6d support this.</para>
               </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
             <para>RFC2292: Advanced Sockets API for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>For supported library functions/kernel APIs, see
 		<filename>sys/netinet6/ADVAPI</filename>.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2362: Protocol Independent Multicast-Sparse
 	    Mode (PIM-SM)</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>RFC2362 defines packet formats for PIM-SM.
 		<filename>draft-ietf-pim-ipv6-01.txt</filename> is
 		written based on this.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2373: IPv6 Addressing Architecture</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>supports node required addresses, and conforms to
 		the scope requirement.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2374: An IPv6 Aggregatable Global Unicast Address
 	    Format</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>supports 64-bit length of Interface ID.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2375: IPv6 Multicast Address Assignments</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>Userland applications use the well-known addresses
 		assigned in the RFC.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2428: FTP Extensions for IPv6 and NATs</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>RFC2428 is preferred over RFC1639.  FTP clients will
 		first try RFC2428, then RFC1639 if failed.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2460: IPv6 specification</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2461: Neighbor discovery for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="neighbor-discovery">23.5.1.2</link>
 		in this document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2462: IPv6 Stateless Address Autoconfiguration</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="ipv6-pnp">23.5.1.4</link> in this
 		document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2463: ICMPv6 for IPv6 specification</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="icmpv6">23.5.1.9</link> in this
 		document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2464: Transmission of IPv6 Packets over Ethernet
 	    Networks</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2465: MIB for IPv6: Textual Conventions and General
 	    Group</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>Necessary statistics are gathered by the kernel.  Actual
 		IPv6 MIB support is provided as a patchkit for ucd-snmp.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2466: MIB for IPv6: ICMPv6 group</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>Necessary statistics are gathered by the kernel.  Actual
 		IPv6 MIB support is provided as patchkit for ucd-snmp.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2467: Transmission of IPv6 Packets over FDDI
 	    Networks</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2497: Transmission of IPv6 packet over ARCnet
 	    Networks</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2553: Basic Socket Interface Extensions for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>IPv4 mapped address (3.7) and special behavior of IPv6
 		wildcard bind socket (3.8) are supported.  See <link
 		linkend="ipv6-wildcard-socket">23.5.1.12</link>
 		in this document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2675: IPv6 Jumbograms</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="ipv6-jumbo">23.5.1.7</link> in
 		this document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2710: Multicast Listener Discovery for IPv6</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2711: IPv6 router alert option</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-ipngwg-router-renum-08</filename>: Router
 	    renumbering for IPv6</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-ipngwg-icmp-namelookups-02</filename>:
 	    IPv6 Name Lookups Through ICMP</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-ipngwg-icmp-name-lookups-03</filename>:
 	    IPv6 Name Lookups Through ICMP</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-pim-ipv6-01.txt</filename>:
 	    PIM for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>&man.pim6dd.8; implements dense mode.  &man.pim6sd.8;
 		implements sparse mode.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-itojun-ipv6-tcp-to-anycast-00</filename>:
 	    Disconnecting TCP connection toward IPv6 anycast address</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-yamamoto-wideipv6-comm-model-00</filename>
 	    </para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="ipv6-sas">23.5.1.6</link> in this
 		document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-ipngwg-scopedaddr-format-00.txt
 	    </filename>: An Extension of Format for IPv6 Scoped
 	    Addresses</para>
           </listitem>
         </itemizedlist>
       </sect3>
 
       <sect3 id="neighbor-discovery">
         <title>Neighbor Discovery</title>
 
         <para>Neighbor Discovery is fairly stable.  Currently Address
 	Resolution, Duplicated Address Detection, and Neighbor Unreachability
 	Detection are supported.  In the near future we will be adding Proxy
 	Neighbor Advertisement support in the kernel and Unsolicited Neighbor
 	Advertisement transmission command as admin tool.</para>
 
         <para>If DAD fails, the address will be marked "duplicated" and
 	message will be generated to syslog (and usually to console).  The
 	"duplicated" mark can be checked with &man.ifconfig.8;.  It is
 	administrators' responsibility to check for and recover from DAD
 	failures.  The behavior should be improved in the near future.</para>
 
         <para>Some of the network driver loops multicast packets back to itself,
         even if instructed not to do so (especially in promiscuous mode).
         In such cases DAD may fail, because DAD engine sees inbound NS packet
         (actually from the node itself) and considers it as a sign of duplicate.
         You may want to look at #if condition marked "heuristics" in
         sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
         fragment in "heuristics" section is not spec conformant).</para>
 
         <para>Neighbor Discovery specification (RFC2461) does not talk about
 	neighbor cache handling in the following cases:</para>
 
 	<orderedlist>
           <listitem>
 	    <para>when there was no neighbor cache entry, node
 	    received unsolicited RS/NS/NA/redirect packet without
 	    link-layer address</para>
           </listitem>
           <listitem>
             <para>neighbor cache handling on medium without link-layer
 	    address (we need a neighbor cache entry for IsRouter bit)</para>
           </listitem>
 	</orderedlist>
 
         <para>For first case, we implemented workaround based on discussions
 	on IETF ipngwg mailing list.  For more details, see the comments in
 	the source code and email thread started from (IPng 7155), dated
 	Feb 6 1999.</para>
 
         <para>IPv6 on-link determination rule (RFC2461) is quite different
 	from assumptions in BSD network code.  At this moment, no on-link
 	determination rule is supported where default router list is empty
 	(RFC2461, section 5.2, last sentence in 2nd paragraph - note that
 	the spec misuse the word "host" and "node" in several places in
 	the section).</para>
 
         <para>To avoid possible DoS attacks and infinite loops, only 10
 	options on ND packet is accepted now.  Therefore, if you have 20
 	prefix options attached to RA, only the first 10 prefixes will be
 	recognized.  If this troubles you, please ask it on FREEBSD-CURRENT
 	mailing list and/or modify nd6_maxndopt in
 	<filename>sys/netinet6/nd6.c</filename>.  If there are high demands
 	we may provide sysctl knob for the variable.</para>
       </sect3>
      
       <sect3 id="ipv6-scope-index">
         <title>Scope Index</title>
 
 	<para>IPv6 uses scoped addresses.  Therefore, it is very important to
 	specify scope index (interface index for link-local address, or
 	site index for site-local address) with an IPv6 address.  Without
 	scope index, scoped IPv6 address is ambiguous to the kernel, and
 	kernel will not be able to determine the outbound interface for a
 	packet.</para>
 
 	<para>Ordinary userland applications should use advanced API
 	(RFC2292) to specify scope index, or interface index.  For similar
 	purpose, sin6_scope_id member in sockaddr_in6 structure is defined
 	in RFC2553.  However, the semantics for sin6_scope_id is rather vague.
 	If you care about portability of your application, we suggest you to
 	use advanced API rather than sin6_scope_id.</para>
 
 	<para>In the kernel, an interface index for link-local scoped address is
 	embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address.  For
 	example, you may see something like:
 	</para>
 
 	<screen>	fe80:1::200:f8ff:fe01:6317
 	</screen>
 
 	<para>in the routing table and interface address structure (struct
 	in6_ifaddr).  The address above is a link-local unicast address
 	which belongs to a network interface whose interface identifier is 1.
 	The embedded index enables us to identify IPv6 link local
 	addresses over multiple interfaces effectively and with only a
 	little code change.</para>
 
 	<para>Routing daemons and configuration programs, like &man.route6d.8;
 	and &man.ifconfig.8;, will need to manipulate the "embedded" scope
 	index.  These programs use routing sockets and ioctls (like
 	SIOCGIFADDR_IN6) and the kernel API will return IPv6 addresses with
 	2nd 16bit-word filled in.  The APIs are for manipulating kernel
 	internal structure.  Programs that use these APIs have to be prepared
 	about differences in kernels anyway.</para>
 
 	<para>When you specify scoped address to the command line, NEVER write
 	the embedded form (such as ff02:1::1 or fe80:2::fedc).  This is not
 	supposed to work.  Always use standard form, like ff02::1 or
 	fe80::fedc, with command line option for specifying interface (like
 	<command>ping6 -I ne0 ff02::1</command>).  In general, if a command
 	does not have command line option to specify outgoing interface, that
 	command is not ready to accept scoped address.  This may seem to be
 	opposite from IPv6's premise to support "dentist office" situation.
 	We believe that specifications need some improvements for this.</para>
 
 	<para>Some of the userland tools support extended numeric IPv6 syntax,
 	as documented in
 	<filename>draft-ietf-ipngwg-scopedaddr-format-00.txt</filename>.  You
 	can specify outgoing link, by using name of the outgoing interface
 	like "fe80::1%ne0".  This way you will be able to specify link-local
 	scoped address without much trouble.</para>
 
 	<para>To use this extension in your program, you will need to use
 	&man.getaddrinfo.3;, and &man.getnameinfo.3; with NI_WITHSCOPEID.
 	The implementation currently assumes 1-to-1 relationship between a
 	link and an interface, which is stronger than what specs say.</para>
       </sect3>
 
       <sect3 id="ipv6-pnp">
 	<title>Plug and Play</title>
 
 	<para>Most of the IPv6 stateless address autoconfiguration is implemented
 	in the kernel.  Neighbor Discovery functions are implemented in the
 	kernel as a whole.  Router Advertisement (RA) input for hosts is
 	implemented in the kernel.  Router Solicitation (RS) output for
 	endhosts, RS input for routers, and RA output for routers are
 	implemented in the userland.</para>
 
         <sect4>
 	  <title>Assignment of link-local, and special addresses</title>
 
  	  <para>IPv6 link-local address is generated from IEEE802 address
 	  (Ethernet MAC address).  Each of interface is assigned an IPv6
 	  link-local address automatically, when the interface becomes up
 	  (IFF_UP).  Also, direct route for the link-local address is added
 	  to routing table.</para>
 
 	  <para>Here is an output of netstat command:</para>
 
 <screen>Internet6:
 Destination                   Gateway                   Flags      Netif Expire
 fe80:1::%ed0/64               link#1                    UC          ed0
 fe80:2::%ep0/64               link#2                    UC          ep0</screen>
 
 	  <para>Interfaces that has no IEEE802 address (pseudo interfaces
 	  like tunnel interfaces, or ppp interfaces) will borrow IEEE802
 	  address from other interfaces, such as Ethernet interfaces,
 	  whenever possible.  If there is no IEEE802 hardware attached,
 	  last-resort pseudorandom value, which is from MD5(hostname), will
 	  be used as source of link-local address.  If it is not suitable
 	  for your usage, you will need to configure the link-local address
 	  manually.</para>
 
 	  <para>If an interface is not capable of handling IPv6 (such as
 	  lack of multicast support), link-local address will not be
 	  assigned to that interface.  See section 2 for details.</para>
 
 	  <para>Each interface joins the solicited multicast address and the
 	  link-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317
 	  and ff02::1, respectively, on the link the interface is attached).
 	  In addition to a link-local address, the loopback address (::1)
 	  will be assigned to the loopback interface.  Also, ::1/128 and
 	  ff01::/32 are automatically added to routing table, and loopback
 	  interface joins node-local multicast group ff01::1.</para>
         </sect4>
 
         <sect4>
 	  <title>Stateless address autoconfiguration on hosts</title>
 
 	  <para>In IPv6 specification, nodes are separated into two categories:
 	  <emphasis>routers</emphasis> and <emphasis>hosts</emphasis>.  Routers
 	  forward packets addressed to others, hosts does not forward the
 	  packets.  net.inet6.ip6.forwarding defines whether this node is
 	  router or host (router if it is 1, host if it is 0).</para>
 
 	  <para>When a host hears Router Advertisement from the router, a host
 	  may autoconfigure itself by stateless address autoconfiguration.
 	  This behavior can be controlled by net.inet6.ip6.accept_rtadv (host
 	  autoconfigures itself if it is set to 1).  By autoconfiguration,
 	  network address prefix for the receiving interface (usually global
 	  address prefix) is added.  Default route is also configured.
 	  Routers periodically generate Router Advertisement packets.  To
 	  request an adjacent router to generate RA packet, a host can
 	  transmit Router Solicitation.  To generate a RS packet at any time,
 	  use the <emphasis>rtsol</emphasis> command.  &man.rtsold.8; daemon is
 	  also available.  &man.rtsold.8; generates Router Solicitation whenever
 	  necessary, and it works great for nomadic usage (notebooks/laptops).
 	  If one wishes to ignore Router Advertisements, use sysctl to set
 	  net.inet6.ip6.accept_rtadv to 0.</para>
 
 	  <para>To generate Router Advertisement from a router, use the
-	  &man.rtadvd.8 daemon.</para>
+	  &man.rtadvd.8; daemon.</para>
 
 	  <para>Note that, IPv6 specification assumes the following items, and
 	  nonconforming cases are left unspecified:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>Only hosts will listen to router advertisements</para>
 	    </listitem>
 	    <listitem>
 	      <para>Hosts have single network interface (except loopback)</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv
 	  on routers, or multi-interface host.  A misconfigured node can
 	  behave strange (nonconforming configuration allowed for those who
 	  would like to do some experiments).</para>
 
 	  <para>To summarize the sysctl knob:</para>
 
         <screen>	accept_rtadv	forwarding	role of the node
 	---		---		---
 	0		0		host (to be manually configured)
 	0		1		router
 	1		0		autoconfigured host
 					(spec assumes that host has single
 					interface only, autoconfigured host
 					with multiple interface is
 					out-of-scope)
 	1		1		invalid, or experimental
 					(out-of-scope of spec)</screen>
 
 	  <para>RFC2462 has validation rule against incoming RA prefix
 	  information option, in 5.5.3 (e).  This is to protect hosts from
 	  malicious (or misconfigured) routers that advertise very short
 	  prefix lifetime.  There was an update from Jim Bound to ipngwg
 	  mailing list (look for "(ipng 6712)" in the archive) and it is
 	  implemented Jim's update.</para>
 
 	  <para>See <link linkend="neighbor-discovery">23.5.1.2</link> in
 	  the document for relationship between DAD and
 	  autoconfiguration.</para>
         </sect4>
       </sect3>
 
       <sect3 id="gif">
 	<title>Generic tunnel interface</title>
 
 	<para>GIF (Generic InterFace) is a pseudo interface for configured
 	tunnel.  Details are described in &man.gif.4;.  Currently</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>v6 in v6</para>
 	  </listitem>
 	  <listitem>
 	    <para>v6 in v4</para>
 	  </listitem>
 	  <listitem>
 	    <para>v4 in v6</para>
 	  </listitem>
 	  <listitem>
 	    <para>v4 in v4</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>are available.  Use &man.gifconfig.8; to assign physical (outer)
 	source and destination address to gif interfaces.  Configuration that
 	uses same address family for inner and outer IP header (v4 in v4, or
 	v6 in v6) is dangerous.  It is very easy to configure interfaces and
 	routing tables to perform infinite level of tunneling.
 	<emphasis>Please be warned</emphasis>.</para>
 
 	<para>gif can be configured to be ECN-friendly.  See <link
 	linkend="ipsec-ecn">23.5.4.5</link> for ECN-friendliness of
 	tunnels, and &man.gif.4; for how to configure.</para>
 
 	<para>If you would like to configure an IPv4-in-IPv6 tunnel with gif
 	interface, read &man.gif.4; carefully.  You will need to
 	remove IPv6 link-local address automatically assigned to the gif
 	interface.</para>
       </sect3>
 
       <sect3 id="ipv6-sas">
 	<title>Source Address Selection</title>
 
 	<para>Current source selection rule is scope oriented (there are some
 	exceptions - see below).  For a given destination, a source IPv6
 	address is selected by the following rule:</para>
 
 	<orderedlist>
 	  <listitem>
   	    <para>If the source address is explicitly specified by
 	    the user (e.g.  via the advanced API), the specified address
 	    is used.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If there is an address assigned to the outgoing
 	    interface (which is usually determined by looking up the
 	    routing table) that has the same scope as the destination
 	    address, the address is used.</para>
 
 	    <para>This is the most typical case.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If there is no address that satisfies the above
 	    condition, choose a global address assigned to one of
 	    the interfaces on the sending node.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If there is no address that satisfies the above condition,
 	    and destination address is site local scope, choose a site local
 	    address assigned to one of the interfaces on the sending node.
 	    </para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If there is no address that satisfies the above condition,
 	    choose the address associated with the routing table entry for the
 	    destination.  This is the last resort, which may cause scope
 	    violation.</para>
 	  </listitem>
 	</orderedlist>
 
 	<para>For instance, ::1 is selected for ff01::1,
 	fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b (note
 	that embedded interface index - described in <link
 	linkend="ipv6-scope-index">23.5.1.3</link> - helps us
 	choose the right source address.  Those embedded indices will not
 	be on the wire).  If the outgoing interface has multiple address for
 	the scope, a source is selected longest match basis (rule 3).  Suppose
 	3ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
 	are given to the outgoing interface.  3ffe:501:808:1:200:f8ff:fe01:6317
 	is chosen as the source for the destination 3ffe:501:800::1.</para>
 
 	<para>Note that the above rule is not documented in the IPv6 spec.
 	It is considered "up to implementation" item.  There are some cases
 	where we do not use the above rule.  One example is connected TCP
 	session, and we use the address kept in tcb as the source.  Another
 	example is source address for Neighbor Advertisement.  Under the spec
 	(RFC2461 7.2.2) NA's source should be the target address of the
 	corresponding NS's target.  In this case we follow the spec rather
 	than the above longest-match rule.</para>
 
 	<para>For new connections (when rule 1 does not apply), deprecated
 	addresses (addresses with preferred lifetime = 0) will not be chosen
 	as source address if other choices are available.  If no other choices
 	are available, deprecated address will be used as a last resort.  If
 	there are multiple choice of deprecated addresses, the above scope
 	rule will be used to choose from those deprecated addresses.  If you
 	would like to prohibit the use of deprecated address for some reason,
 	configure net.inet6.ip6.use_deprecated to 0.  The issue related to
 	deprecated address is described in RFC2462 5.5.4 (NOTE: there is
 	some debate underway in IETF ipngwg on how to use "deprecated"
 	address).</para>
       </sect3>
 
       <sect3 id="ipv6-jumbo">
 	<title>Jumbo Payload</title>
 
 	<para>The Jumbo Payload hop-by-hop option is implemented and can
 	be used to send IPv6 packets with payloads longer than 65,535 octets.
 	But currently no physical interface whose MTU is more than 65,535 is
 	supported, so such payloads can be seen only on the loopback
 	interface (i.e. lo0).</para>
 
 	<para>If you want to try jumbo payloads, you first have to reconfigure
 	the kernel so that the MTU of the loopback interface is more than
 	65,535 bytes; add the following to the kernel configuration file:</para>
 
 	<para><literal>
 	  options		"LARGE_LOMTU"		#To test jumbo payload
 	</literal></para>
 
 	<para>and recompile the new kernel.</para>
 
 	<para>Then you can test jumbo payloads by the &man.ping6.8; command
 	with -b and -s options.  The -b option must be specified to enlarge
 	the size of the socket buffer and the -s option specifies the length
 	of the packet, which should be more than 65,535.  For example,
 	type as follows:</para>
 
 	<para><userinput>
 	  &prompt.user; <command>ping6 -b 70000 -s 68000 ::1</command>
 	</userinput></para>
 
 	<para>The IPv6 specification requires that the Jumbo Payload option
 	must not be used in a packet that carries a fragment header.  If
 	this condition is broken, an ICMPv6 Parameter Problem message must
 	be sent to the sender.  specification is followed, but you cannot
 	usually see an ICMPv6 error caused by this requirement.</para>
 
 	<para>When an IPv6 packet is received, the frame length is checked and
 	compared to the length specified in the payload length field of the
 	IPv6 header or in the value of the Jumbo Payload option, if any.  If
 	the former is shorter than the latter, the packet is discarded and
 	statistics are incremented. You can see the statistics as output of
 	&man.netstat.8; command with `-s -p ip6' option:</para>
 
 	<screen>	  &prompt.user; <command>netstat -s -p ip6</command>
 	  ip6:
 		(snip)
 		1 with data size < data length</screen>
 
 	<para>So, kernel does not send an ICMPv6 error unless the erroneous
 	packet is an actual Jumbo Payload, that is, its packet size is more
 	than 65,535 bytes.  As described above, currently no physical interface
 	with such a huge MTU is supported, so it rarely returns an
 	ICMPv6 error.</para>
 
 	<para>TCP/UDP over jumbogram is not supported at this moment.  This
 	is because we have no medium (other than loopback) to test this.
 	Contact us if you need this.</para>
 
 	<para>IPsec does not work on jumbograms.  This is due to some
 	specification twists in supporting AH with jumbograms (AH header
 	size influences payload length, and this makes it real hard to
 	authenticate inbound packet with jumbo payload option as well as AH).
 	</para>
 
 	<para>There are fundamental issues in *BSD support for jumbograms.
 	We would like to address those, but we need more time to finalize
 	these.  To name a few:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>mbuf pkthdr.len field is typed as "int" in 4.4BSD, so
 	    it will not hold jumbogram with len &gt; 2G on 32bit architecture
 	    CPUs.  If we would like to support jumbogram properly, the field
 	    must be expanded to hold 4G + IPv6 header + link-layer header.
 	    Therefore, it must be expanded to at least int64_t
 	    (u_int32_t is NOT enough).</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>We mistakingly use "int" to hold packet length in many
 	    places.  We need to convert them into larger integral type.
 	    It needs a great care, as we may experience overflow during
 	    packet length computation.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>We mistakingly check for ip6_plen field of IPv6 header
 	    for packet payload length in various places.  We should be
 	    checking mbuf pkthdr.len instead.  ip6_input() will perform
 	    sanity check on jumbo payload option on input, and we can
 	    safely use mbuf pkthdr.len afterwards.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>TCP code needs a careful update in bunch of places, of
 	    course.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Loop prevention in header processing</title>
 
 	<para>IPv6 specification allows arbitrary number of extension headers
 	to be placed onto packets.  If we implement IPv6 packet processing
 	code in the way BSD IPv4 code is implemented, kernel stack may
 	overflow due to long function call chain.  sys/netinet6 code
 	is carefully designed to avoid kernel stack overflow.  Because of
 	this, sys/netinet6 code defines its own protocol switch
 	structure, as "struct ip6protosw" (see
 	<filename>netinet6/ip6protosw.h</filename>).  There is no such
 	update to IPv4 part (sys/netinet) for compatibility, but small
 	change is added to its pr_input() prototype. So "struct ipprotosw"
 	is also defined.  Because of this, if you receive IPsec-over-IPv4
 	packet with massive number of IPsec headers, kernel stack may blow
 	up.  IPsec-over-IPv6 is okay.  (Off-course, for those all IPsec
 	headers to be processed, each such IPsec header must pass each
 	IPsec check. So an anonymous attacker will not be able to do such an
 	attack.)</para>
       </sect3>
 
       <sect3 id="icmpv6">
 	<title>ICMPv6</title>
 
 	<para>After RFC2463 was published, IETF ipngwg has decided to
 	disallow ICMPv6 error packet against ICMPv6 redirect, to prevent
 	ICMPv6 storm on a network medium.  This is already implemented
 	into the kernel.</para>
       </sect3>
 
       <sect3>
 	<title>Applications</title>
 
 	<para>For userland programming, we support IPv6 socket API as
 	specified in RFC2553, RFC2292 and upcoming Internet drafts.</para>
 
 	<para>TCP/UDP over IPv6 is available and quite stable.  You can
 	enjoy &man.telnet.1;, &man.ftp.1;, &man.rlogin.1;, &man.rsh.1;,
-	&man.ssh.1, etc.  These applications are protocol independent.
+	&man.ssh.1;, etc.  These applications are protocol independent.
 	That is, they automatically chooses IPv4 or IPv6 according to DNS.
 	</para>
       </sect3>
 
       <sect3>
 	<title>Kernel Internals</title>
 
 	<para>While ip_forward() calls ip_output(), ip6_forward() directly
 	calls if_output() since routers must not divide IPv6 packets into
 	fragments.</para>
 
 	<para>ICMPv6 should contain the original packet as long as possible
 	up to 1280.  UDP6/IP6 port unreach, for instance, should contain
 	all extension headers and the *unchanged* UDP6 and IP6 headers.
 	So, all IP6 functions except TCP never convert network byte
 	order into host byte order, to save the original packet.</para>
 
 	<para>tcp_input(), udp6_input() and icmp6_input() can not assume that
 	IP6 header is preceding the transport headers due to extension
 	headers.  So, in6_cksum() was implemented to handle packets whose IP6
 	header and transport header is not continuous.  TCP/IP6 nor UDP6/IP6
 	header structures do not exist for checksum calculation.</para>
 
 	<para>To process IP6 header, extension headers and transport headers
 	easily, network drivers are now required to store packets in one
 	internal mbuf or one or more external mbufs.  A typical old driver
 	prepares two internal mbufs for 96 - 204 bytes data, however, now
 	such packet data is stored in one external mbuf.</para>
 
 	<para><command>netstat -s -p ip6</command> tells you whether or not
 	your driver conforms such requirement.  In the following example,
 	"cce0" violates the requirement. (For more information, refer to
 	Section 2.)</para>
 
 	<screen>Mbuf statistics:
                 317 one mbuf
                 two or more mbuf::
                         lo0 = 8
 			cce0 = 10
                 3282 one ext mbuf
                 0 two or more ext mbuf
 	</screen>
 
 	<para>Each input function calls IP6_EXTHDR_CHECK in the beginning to
 	check if the region between IP6 and its header is continuous.
 	IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has M_LOOP flag,
 	that is, the packet comes from the loopback interface.  m_pullup()
 	is never called for packets coming from physical network interfaces.
 	</para>
 
 	<para>Both IP and IP6 reassemble functions never call m_pullup().</para>
       </sect3>
 
       <sect3 id="ipv6-wildcard-socket">
 	<title>IPv4 mapped address and IPv6 wildcard socket</title>
 
 	<para>RFC2553 describes IPv4 mapped address (3.7) and special behavior
 	of IPv6 wildcard bind socket (3.8).  The spec allows you to:</para>
 	<itemizedlist>
 	  <listitem>
 	    <para>Accept IPv4 connections by AF_INET6 wildcard bind
 	    socket.</para>
 	  </listitem>
 	  <listitem>
 	    <para>Transmit IPv4 packet over AF_INET6 socket by using
 	    special form of the address like ::ffff:10.1.1.1.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>but the spec itself is very complicated and does not specify
 	how the socket layer should behave.  Here we call the former one
 	"listening side" and the latter one "initiating side", for
 	reference purposes.</para>
 
 	<para>You can perform wildcard bind on both of the address families,
 	on the same port.</para>
 
 	<para>The following table show the behavior of FreeBSD 4.x.</para>
 
 	<screen>listening side          initiating side
                 (AF_INET6 wildcard      (connection to ::ffff:10.1.1.1)
                 socket gets IPv4 conn.)
                 ---                     ---
 FreeBSD 4.x     configurable            supported
                 default: enabled
 	</screen>
 
 	<para>The following sections will give you more details, and how you can
 	configure the behavior.</para>
 
 	<para>Comments on listening side:</para>
 
 	<para>It looks that RFC2553 talks too little on wildcard bind issue,
 	especially on the port space issue, failure mode and relationship
 	between AF_INET/INET6 wildcard bind.  There can be several separate
 	interpretation for this RFC which conform to it but behaves differently.
 	So, to implement portable application you should assume nothing
 	about the behavior in the kernel.  Using &man.getaddrinfo.3; is the
 	safest way.  Port number space and wildcard bind issues were discussed
 	in detail on ipv6imp mailing list, in mid March 1999 and it looks
 	that there is no concrete consensus (means, up to implementers).
 	You may want to check the mailing list archives.</para>
 
 	<para>If a server application would like to accept IPv4 and IPv6
 	connections, there will be two alternatives.</para>
 
 	<para>One is using AF_INET and AF_INET6 socket (you will need two
 	sockets).  Use &man.getaddrinfo.3; with AI_PASSIVE into ai_flags,
 	and &man.socket.2; and &man.bind.2; to all the addresses returned.
 	By opening multiple sockets, you can accept connections onto the
 	socket with proper address family.  IPv4 connections will be
 	accepted by AF_INET socket, and IPv6 connections will be accepted
 	by AF_INET6 socket.</para>
 
 	<para>Another way is using one AF_INET6 wildcard bind socket.  Use
 	&man.getaddrinfo.3; with AI_PASSIVE into ai_flags and with
 	AF_INET6 into ai_family, and set the 1st argument hostname to
 	NULL. And &man.socket.2; and &man.bind.2; to the address returned.
 	(should be IPv6 unspecified addr).  You can accept either of IPv4
 	and IPv6 packet via this one socket.</para>
 
 	<para>To support only IPv6 traffic on AF_INET6 wildcard binded socket
 	portably, always check the peer address when a connection is made
 	toward AF_INET6 listening socket.  If the address is IPv4 mapped
 	address, you may want to reject the connection.  You can check the
 	condition by using IN6_IS_ADDR_V4MAPPED() macro.</para>
 
 	<para>To resolve this issue more easily, there is system dependent
 	&man.setsockopt.2; option, IPV6_BINDV6ONLY, used like below.</para>
 
 	<screen>	int on;
 
 	setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
 		   (char *)&amp;on, sizeof (on)) < 0));
 	</screen>
 
 	<para>When this call succeed, then this socket only receive IPv6
 	packets.</para>
 
 	<para>Comments on initiating side:</para>
 
 	<para>Advise to application implementers: to implement a portable
 	IPv6 application (which works on multiple IPv6 kernels), we believe
 	that the following is the key to the success:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>NEVER hardcode AF_INET nor AF_INET6.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use &man.getaddrinfo.3; and &man.getnameinfo.3;
 	    throughout the system.  Never use gethostby*(), getaddrby*(),
 	    inet_*() or getipnodeby*(). (To update existing applications
 	    to be IPv6 aware easily, sometime getipnodeby*() will be
 	    useful. But if possible, try to rewrite the code to use
 	    &man.getaddrinfo.3; and &man.getnameinfo.3;.)</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you would like to connect to destination, use
 	    &man.getaddrinfo.3; and try all the destination returned,
 	    like &man.telnet.1; does.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Some of the IPv6 stack is shipped with buggy
 	    &man.getaddrinfo.3;.  Ship a minimal working version with
 	    your application and use that as last resort.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>If you would like to use AF_INET6 socket for both IPv4 and
 	IPv6 outgoing connection, you will need to use &man.getipnodebyname.3;.
 	When you would like to update your existing application to be IPv6
 	aware with minimal effort, this approach might be chosen. But please
 	note that it is a temporal solution, because &man.getipnodebyname.3;
 	itself is not recommended as it does not handle scoped IPv6 addresses
 	at all.  For IPv6 name resolution, &man.getaddrinfo.3; is the
 	preferred API. So you should rewrite your application to use
 	&man.getaddrinfo.3;, when you get the time to do it.</para>
 
 	<para>When writing applications that make outgoing connections,
 	story goes much simpler if you treat AF_INET and AF_INET6 as totally
 	separate address family.  {set,get}sockopt issue goes simpler,
 	DNS issue will be made simpler.  We do not recommend you to rely
 	upon IPv4 mapped address.</para>
 
 	<sect4>
 	  <title>unified tcp and inpcb code</title>
 
 	  <para>FreeBSD 4.x uses shared tcp code between IPv4 and IPv6
 	  (from sys/netinet/tcp*) and separate udp4/6 code.  It uses
 	  unified inpcb structure.</para>
 
 	  <para>The platform can be configured to support IPv4 mapped address.
 	  Kernel configuration is summarized as follows:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>By default, AF_INET6 socket will grab IPv4
 	      connections in certain condition, and can initiate
 	      connection to IPv4 destination embedded in IPv4 mapped
 	      IPv6 address.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>You can disable it on entire system with sysctl like
 	      below.</para>
 
 	      <para>
 	        <command>sysctl net.inet6.ip6.mapped_addr=0</command>
 	      </para>
 
 	    </listitem>
 	  </itemizedlist>
 
 	  <sect5>
 	    <title>listening side</title>
 
 	    <para>Each socket can be configured to support special AF_INET6
 	    wildcard bind (enabled by default).  You can disable it on
 	    each socket basis with &man.setsockopt.2; like below.</para>
 
 	<screen>	int on;
 
 	setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
 		   (char *)&amp;on, sizeof (on)) < 0));
 	</screen>
 
 	    <para>Wildcard AF_INET6 socket grabs IPv4 connection if and only
 	    if the following conditions are satisfied:</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para>there is no AF_INET socket that matches the IPv4
 		connection</para>
 	      </listitem>
 
 	      <listitem>
 		<para>the AF_INET6 socket is configured to accept IPv4
 		traffic, i.e.  getsockopt(IPV6_BINDV6ONLY) returns 0.</para>
 	      </listitem>
 	    </itemizedlist>
 
 	    <para>There is no problem with open/close ordering.</para>
 	  </sect5>
 
 	  <sect5>
 	    <title>initiating side</title>
 
 	    <para>FreeBSD 4.x supports outgoing connection to IPv4 mapped
 	    address (::ffff:10.1.1.1), if the node is configured to support
 	    IPv4 mapped address.</para>
 	  </sect5>
 	</sect4>
       </sect3>
 
       <sect3>
 	<title>sockaddr_storage</title>
 
 	<para>When RFC2553 was about to be finalized, there was discussion on
 	how struct sockaddr_storage members are named.  One proposal is to
 	prepend "__" to the members (like "__ss_len") as they should not be
 	touched.  The other proposal was not to prepend it (like "ss_len")
 	as we need to touch those members directly.  There was no clear
 	consensus on it.</para>
 
 	<para>As a result, RFC2553 defines struct sockaddr_storage as
 	follows:</para>
 
 	<screen>	struct sockaddr_storage {
 		u_char	__ss_len;	/* address length */
 		u_char	__ss_family;	/* address family */
 		/* and bunch of padding */
 	};
 	</screen>
 
 	<para>On the contrary, XNET draft defines as follows:</para>
 
 	<screen>	struct sockaddr_storage {
 		u_char	ss_len;		/* address length */
 		u_char	ss_family;	/* address family */
 		/* and bunch of padding */
 	};
 	</screen>
 
 	<para>In December 1999, it was agreed that RFC2553bis should pick
 	the latter (XNET) definition.</para>
 
 	<para>Current implementation conforms to XNET definition, based on
 	RFC2553bis discussion.</para>
 
 	<para>If you look at multiple IPv6 implementations, you will be able
 	to see both definitions.  As an userland programmer, the most
 	portable way of dealing with it is to:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>ensure ss_family and/or ss_len are available on the
 	    platform, by using GNU autoconf,</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>have -Dss_family=__ss_family to unify all occurrences
 	    (including header file) into __ss_family, or</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>never touch __ss_family.  cast to sockaddr * and use sa_family
 	    like:</para>
 
 	    <screen>	struct sockaddr_storage ss;
 	family = ((struct sockaddr *)&amp;ss)->sa_family
 	    </screen>
 
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Network Drivers</title>
 
       <para>Now following two items are required to be supported by standard
       drivers:</para>
 
       <orderedlist>
         <listitem>
           <para>mbuf clustering requirement. In this stable release, we
           changed MINCLSIZE into MHLEN+1 for all the operating systems
           in order to make all the drivers behave as we expect.</para>
         </listitem>
 
         <listitem>
           <para>multicast.  If &man.ifmcstat.8; yields no multicast group for
           a interface, that interface has to be patched.</para>
         </listitem>
       </orderedlist>
    
       <para>If any of the drivers do not support the requirements, then
       the drivers can not be used for IPv6 and/or IPsec communication.  If
       you find any problem with your card using IPv6/IPsec, then, please
       report it to the &a.bugs;.</para>
 
       <para>(NOTE: In the past we required all PCMCIA drivers to have a
       call to in6_ifattach().  We have no such requirement any more)</para>
     </sect2>
 
     <sect2>
 	<title>Translator</title>
 
 	<para>We categorize IPv4/IPv6 translator into 4 types:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><emphasis>Translator A</emphasis> --- It is used in the early
 	    stage of transition to make it possible to establish a
 	    connection from an IPv6 host in an IPv6 island to an IPv4 host
 	    in the IPv4 ocean.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><emphasis>Translator B</emphasis> --- It is used in the early
 	    stage of transition to make it possible to establish a connection
 	    from an IPv4 host in the IPv4 ocean to an IPv6 host in an
 	    IPv6 island.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><emphasis>Translator C</emphasis> --- It is used in the late
 	    stage of transition to make it possible to establish a
 	    connection from an IPv4 host in an IPv4 island to an IPv6 host
 	    in the IPv6 ocean.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><emphasis>Translator D</emphasis> --- It is used in the late
 	    stage of transition to make it possible to establish a
 	    connection from an IPv6 host in the IPv6 ocean to an IPv4 host
 	    in an IPv4 island.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>TCP relay translator for category A is supported.  This is called
 	"FAITH".  We also provide IP header translator for category A.
 	(The latter is not yet put into FreeBSD 4.x yet.)</para>
 
       <sect3>
 	<title>FAITH TCP relay translator</title>
 
 	<para>FAITH system uses TCP relay daemon called &man.faithd.8; helped
 	by the kernel.  FAITH will reserve an IPv6 address prefix, and relay
 	TCP connection toward that prefix to IPv4 destination.</para>
 
 	<para>For example, if the reserved IPv6 prefix is
 	3ffe:0501:0200:ffff::, and the IPv6 destination for TCP connection
 	is 3ffe:0501:0200:ffff::163.221.202.12, the connection will be
 	relayed toward IPv4 destination 163.221.202.12.</para>
 
 	<screen>	destination IPv4 node (163.221.202.12)
 	  ^
 	  | IPv4 tcp toward 163.221.202.12
 	FAITH-relay dual stack node
 	  ^
 	  | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
 	source IPv6 node
 	</screen>
   
 	<para>&man.faithd.8; must be invoked on FAITH-relay dual stack
 	node.</para>
 
 	<para>For more details, consult
 	<filename>src/usr.sbin/faithd/README</filename></para>
       </sect3>
     </sect2>
 
     <sect2 id="ipsec-implementation">
       <title>IPsec</title>
 
       <para>IPsec is mainly organized by three components.</para>
 
       <orderedlist>
 	<listitem>
 	  <para>Policy Management</para>
 	</listitem>
 
 	<listitem>
 	  <para>Key Management</para>
 	</listitem>
 
 	<listitem>
 	  <para>AH and ESP handling</para>
 	</listitem>
       </orderedlist>
 
       <sect3>
 	<title>Policy Management</title>
 
 	<para>The kernel implements experimental policy management code.
 	There are two way to manage security policy.  One is to configure
 	per-socket policy using &man.setsockopt.2;.  In this cases, policy
 	configuration is described in &man.ipsec.set.policy.3;.  The other
 	is to configure kernel packet filter-based policy using PF_KEY
 	interface, via &man.setkey.8;.</para>
 
 	<para>The policy entry is not re-ordered with its
 	indexes, so the order of entry when you add is very significant.</para>
       </sect3>
 
       <sect3>
 	<title>Key Management</title>
 
 	<para>The key management code implemented in this kit (sys/netkey)
 	is a home-brew PFKEY v2 implementation.  This conforms to RFC2367.
 	</para>
 
 	<para>The home-brew IKE daemon, "racoon" is included in the
 	kit (kame/kame/racoon).  Basically you will need to run racoon as
 	daemon, then setup a policy to require keys (like
 	<command>ping -P 'out ipsec esp/transport//use'</command>).
 	The kernel will contact racoon daemon as necessary to exchange
 	keys.</para>
       </sect3>
 
       <sect3>
 	<title>AH and ESP handling</title>
 
 	<para>IPsec module is implemented as "hooks" to the standard IPv4/IPv6
 	processing.  When sending a packet, ip{,6}_output() checks if ESP/AH
 	processing is required by checking if a matching SPD (Security
 	Policy Database) is found.  If ESP/AH is needed,
 	{esp,ah}{4,6}_output() will be called and mbuf will be updated
 	accordingly.  When a packet is received, {esp,ah}4_input() will be
 	called based on protocol number, i.e. (*inetsw[proto])().
 	{esp,ah}4_input() will decrypt/check authenticity of the packet,
 	and strips off daisy-chained header and padding for ESP/AH.  It is
 	safe to strip off the ESP/AH header on packet reception, since we
 	will never use the received packet in "as is" form.</para>
 
 	<para>By using ESP/AH, TCP4/6 effective data segment size will be
 	affected by extra daisy-chained headers inserted by ESP/AH.  Our
 	code takes care of the case.</para>
 
 	<para>Basic crypto functions can be found in directory "sys/crypto".
 	ESP/AH transform are listed in {esp,ah}_core.c with wrapper functions.
 	If you wish to add some algorithm, add wrapper function in
 	{esp,ah}_core.c, and add your crypto algorithm code into
 	sys/crypto.</para>
 
 	<para>Tunnel mode is partially supported in this release, with the
 	following restrictions:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>IPsec tunnel is not combined with GIF generic tunneling
 	    interface.  It needs a great care because we may create an
 	    infinite loop between ip_output() and tunnelifp->if_output().
 	    Opinion varies if it is better to unify them, or not.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>MTU and Don't Fragment bit (IPv4) considerations need more
 	    checking, but basically works fine.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Authentication model for AH tunnel must be revisited.
 	    We will need to improve the policy management engine,
 	    eventually.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Conformance to RFCs and IDs</title>
 
 	<para>The IPsec code in the kernel conforms (or, tries to conform)
 	to the following standards:</para>
 
     	<para>"old IPsec" specification documented in
 	<filename>rfc182[5-9].txt</filename></para>
     
     	<para>"new IPsec" specification documented in
 	<filename>rfc240[1-6].txt</filename>,
 	<filename>rfc241[01].txt</filename>, <filename>rfc2451.txt</filename>
 	and <filename>draft-mcdonald-simple-ipsec-api-01.txt</filename>
 	(draft expired, but you can take from <ulink
 	url="ftp://ftp.kame.net/pub/internet-drafts/">
 	ftp://ftp.kame.net/pub/internet-drafts/</ulink>).
 	(NOTE: IKE specifications, <filename>rfc241[7-9].txt</filename> are
 	implemented in userland, as "racoon" IKE daemon)</para>
 
 	<para>Currently supported algorithms are:</para>
 	<itemizedlist>
 	  <listitem>
 	    <para>old IPsec AH</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>null crypto checksum (no document, just for
 		debugging)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed MD5 with 128bit crypto checksum
 		(<filename>rfc1828.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed SHA1 with 128bit crypto checksum
 		(no document)</para>
 	      </listitem>
 	      <listitem>
 		<para>HMAC MD5 with 128bit crypto checksum
 		(<filename>rfc2085.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>HMAC SHA1 with 128bit crypto checksum
 		(no document)</para>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 
 	  <listitem>
             <para>old IPsec ESP</para>
 	    <itemizedlist>
 	      <listitem>
 	        <para>null encryption (no document, similar to
 		<filename>rfc2410.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 	        <para>DES-CBC mode (<filename>rfc1829.txt</filename>)</para>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 
 	  <listitem>
 	    <para>new IPsec AH</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>null crypto checksum (no document,
 		just for debugging)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed MD5 with 96bit crypto checksum
 		(no document)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed SHA1 with 96bit crypto checksum
 		(no document)</para>
 	      </listitem>
 	      <listitem>
 		<para>HMAC MD5 with 96bit crypto checksum
 		(<filename>rfc2403.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>HMAC SHA1 with 96bit crypto checksum
 		(<filename>rfc2404.txt</filename>)</para>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 
 	  <listitem>
             <para>new IPsec ESP</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>null encryption
 		(<filename>rfc2410.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>DES-CBC with derived IV
 		(<filename>draft-ietf-ipsec-ciph-des-derived-01.txt</filename>,
 		draft expired)</para>
 	      </listitem>
 	      <listitem>
 		<para>DES-CBC with explicit IV
 		(<filename>rfc2405.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>3DES-CBC with explicit IV
 		(<filename>rfc2451.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>BLOWFISH CBC
 		(<filename>rfc2451.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>CAST128 CBC
 		(<filename>rfc2451.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>RC5 CBC
 		(<filename>rfc2451.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>each of the above can be combined with:</para>
 	 	<itemizedlist>
 		  <listitem>
 	    	    <para>ESP authentication with HMAC-MD5(96bit)</para>
 		  </listitem>
 		  <listitem>
 	            <para>ESP authentication with HMAC-SHA1(96bit)</para>
 		  </listitem>
 	        </itemizedlist>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 	</itemizedlist>
 
 	<para>The following algorithms are NOT supported:</para>
 	<itemizedlist>
 	  <listitem>
 
 	    <para>old IPsec AH</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para>HMAC MD5 with 128bit crypto checksum + 64bit
 		replay prevention (<filename>rfc2085.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed SHA1 with 160bit crypto checksum + 32bit padding
 		(<filename>rfc1852.txt</filename>)</para>
 	      </listitem>
 	    </itemizedlist>
 
 	  </listitem>
 	</itemizedlist>
 
 	<para>IPsec (in kernel) and IKE (in userland as "racoon") has been
 	tested at several interoperability test events, and it is known to
 	interoperate with many other implementations well.  Also, current
 	IPsec implementation as quite wide coverage for IPsec crypto
 	algorithms documented in RFC (we cover algorithms without intellectual
 	property issues only).</para>
       </sect3>
 
       <sect3 id="ipsec-ecn">
 	<title>ECN consideration on IPsec tunnels</title>
 
 	<para>ECN-friendly IPsec tunnel is supported as described in
 	<filename>draft-ipsec-ecn-00.txt</filename>.</para>
 
 	<para>Normal IPsec tunnel is described in RFC2401.  On encapsulation,
 	IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
 	IP header to outer IP header.  On decapsulation outer IP header
 	will be simply dropped.  The decapsulation rule is not compatible
 	with ECN, since ECN bit on the outer IP TOS/traffic class field will be
 	lost.</para>
 
 	<para>To make IPsec tunnel ECN-friendly, we should modify encapsulation
 	and decapsulation procedure.  This is described in <ulink
 	url="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt">
 	http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</ulink>,
 	chapter 3.</para>
 
 	<para>IPsec tunnel implementation can give you three behaviors, by
 	setting net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some
 	value:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>RFC2401: no consideration for ECN (sysctl value -1)</para>
 	  </listitem>
 	  <listitem>
 	    <para>ECN forbidden (sysctl value 0)</para>
 	  </listitem>
 	  <listitem>
 	    <para>ECN allowed (sysctl value 1)</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>Note that the behavior is configurable in per-node manner,
 	not per-SA manner (draft-ipsec-ecn-00 wants per-SA configuration,
 	but it looks too much for me).</para>
 
 	<para>The behavior is summarized as follows (see source code for
 	more detail):</para>
 
 	<screen>
                 encapsulate                     decapsulate
                 ---                             ---
 RFC2401         copy all TOS bits               drop TOS bits on outer
                 from inner to outer.            (use inner TOS bits as is)
 
 ECN forbidden   copy TOS bits except for ECN    drop TOS bits on outer
                 (masked with 0xfc) from inner   (use inner TOS bits as is)
                 to outer.  set ECN bits to 0.
 
 ECN allowed     copy TOS bits except for ECN    use inner TOS bits with some
                 CE (masked with 0xfe) from      change.  if outer ECN CE bit
                 inner to outer.                 is 1, enable ECN CE bit on
                 set ECN CE bit to 0.            the inner.
 
 	</screen>
 
 	<para>General strategy for configuration is as follows:</para>
 	<itemizedlist>
 	  <listitem>
 	    <para>if both IPsec tunnel endpoint are capable of ECN-friendly
 	    behavior, you should better configure both end to <quote>ECN allowed</quote>
 	    (sysctl value 1).</para>
 	  </listitem>
 	  <listitem>
             <para>if the other end is very strict about TOS bit, use "RFC2401"
             (sysctl value -1).</para>
 	  </listitem>
 	  <listitem>
 	    <para>in other cases, use "ECN forbidden" (sysctl value 0).</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>The default behavior is "ECN forbidden" (sysctl value 0).</para>
 
 	<para>For more information, please refer to:</para>
 
 	<para><ulink
 	url="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt">
 	http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</ulink>,
 	RFC2481 (Explicit Congestion Notification),
 	src/sys/netinet6/{ah,esp}_input.c</para>
 
 	<para>(Thanks goes to Kenjiro Cho <email>kjc@csl.sony.co.jp</email>
 	for detailed analysis)</para>
       </sect3>
 
       <sect3>
 	<title>Interoperability</title>
 
 	<para>Here are (some of) platforms that KAME code have tested
 	IPsec/IKE interoperability in the past.  Note that both ends may
 	have modified their implementation, so use the following list just
 	for reference purposes.</para>
 
 	<para>Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure),
 	Ericsson ACC, FreeS/WAN, HITACHI, IBM AIX, IIJ, Intel,
 	Microsoft WinNT, NIST (linux IPsec + plutoplus), Netscreen, OpenBSD,
 	RedCreek, Routerware, SSH, Secure Computing, Soliton, Toshiba,
 	VPNet, Yamaha RT100i</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/developers-handbook/sockets/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.sgml
index 322af6e79e..30e5a767aa 100644
--- a/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.sgml
@@ -1,1779 +1,1779 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="sockets">
   <title>Sockets</title>
 
   <para><emphasis>This chapter was written by
     &a.stanislav;</emphasis></para>
 
   <sect1 id="sockets-synopsis">
     <title>Synopsis</title>
  
     <para><acronym>BSD</acronym> sockets take interprocess
       communications to a new level. It is no longer necessary for the
       communicating processes to run on the same machine. They still
       <emphasis>can</emphasis>, but they do not have to.</para>
 
     <para>Not only do these processes not have to run on the same
       machine, they do not have to run under the same operating
       system. Thanks to <acronym>BSD</acronym> sockets, your FreeBSD
       software can smoothly cooperate with a program running on a
       Macintosh, another one running on a Sun workstation, yet another
       one running under Windows 2000, all connected with an
       Ethernet-based local area network.</para>
 
     <para>But your software can equally well cooperate with processes
       running in another building, or on another continent, inside a
       submarine, or a space shuttle.</para>
 
     <para>It can also cooperate with processes that are not part of a
       computer (at least not in the strict sense of the word), but of
       such devices as printers, digital cameras, medical equipment.
       Just about anything capable of digital communications.</para>
 
   </sect1>
 
   <sect1 id="sockets-diversity">
     <title>Networking and Diversity</title>
 
     <para>We have already hinted on the <emphasis>diversity</emphasis>
       of networking. Many different systems have to talk to each
       other. And they have to speak the same language. They also have
       to <emphasis>understand</emphasis> the same language the same
       way.</para>
 
     <para>People often think that <emphasis>body language</emphasis>
       is universal. But it is not. Back in my early teens, my father
       took me to Bulgaria. We were sitting at a table in a park in
       Sofia, when a vendor approached us trying to sell us some
       roasted almonds.</para>
 
     <para>I had not learned much Bulgarian by then, so, instead of
       saying no, I shook my head from side to side, the
       <quote>universal</quote> body language for
       <emphasis>no</emphasis>. The vendor quickly started serving us
       some almonds.</para>
 
     <para>I then remembered I had been told that in Bulgaria shaking
       your head sideways meant <emphasis>yes</emphasis>. Quickly, I
       started nodding my head up and down. The vendor noticed, took
       his almonds, and walked away. To an uninformed observer, I did
       not change the body language: I continued using the language of
       shaking and nodding my head. What changed was the
       <emphasis>meaning</emphasis> of the body language. At first, the
       vendor and I interpreted the same language as having completely
       different meaning. I had to adjust my own interpretation of that
       language so the vendor would understand.</para>
 
     <para>It is the same with computers: The same symbols may have
       different, even outright opposite meaning. Therefore, for
       two computers to understand each other, they must not only
       agree on the same <emphasis>language</emphasis>, but on the
       same <emphasis>interpretation</emphasis> of the language.
       </para>
   </sect1>
 
   <sect1 id="sockets-protocols">
     <title>Protocols</title>
 
     <para>While various programming languages tend to have complex
       syntax and use a number of multi-letter reserved words (which
       makes them easy for the human programmer to understand), the
       languages of data communications tend to be very terse. Instead
       of multi-byte words, they often use individual
       <emphasis>bits</emphasis>.  There is a very convincing reason
       for it: While data travels <emphasis>inside</emphasis> your
       computer at speeds approaching the speed of light, it often
       travels considerably slower between two computers.</para>
 
     <para>Because the languages used in data communications are so
       terse, we usually refer to them as
       <emphasis>protocols</emphasis> rather than languages.</para>
 
     <para>As data travels from one computer to another, it always uses
       more than one protocol. These protocols are
       <emphasis>layered</emphasis>.  The data can be compared to the
       inside of an onion: You have to peel off several layers of
       <quote>skin</quote> to get to the data.  This is best
       illustrated with a picture:</para>
       
     <mediaobject>
       <imageobject>
         <imagedata fileref="sockets/layers">
       </imageobject>
        
       <textobject>
         <literallayout class="monospaced">+----------------+
 |    Ethernet    |
 |+--------------+|
 ||      IP      ||
 ||+------------+||
 |||     TCP    |||
 |||+----------+|||
 ||||   HTTP   ||||
 ||||+--------+||||
 |||||   PNG  |||||
 |||||+------+|||||
 |||||| Data ||||||
 |||||+------+|||||
 ||||+--------+||||
 |||+----------+|||
 ||+------------+||
 |+--------------+|
 +----------------+</literallayout>
       </textobject>
        
       <textobject>
         <phrase>Protocol Layers</phrase>
       </textobject>
     </mediaobject>
 
     <para>In this example, we are trying to get an image from a web
       page we are connected to via an Ethernet.</para>
       
     <para>The image consists of raw data, which is simply a sequence
       of <acronym>RGB</acronym> values that our software can process,
       i.e., convert into an image and display on our monitor.</para>
       
     <para>Alas, our software has no way of knowing how the raw data is
       organized: Is it a sequence of <acronym>RGB</acronym> values, or
       a sequence of grayscale intensities, or perhaps of
       <acronym>CMYK</acronym> encoded colors? Is the data represented
       by 8-bit quanta, or are they 16 bits in size, or perhaps 4 bits?
       How many rows and columns does the image consist of? Should
       certain pixels be transparent?</para>
       
     <para>I think you get the picture...</para>
       
     <para>To inform our software how to handle the raw data, it is
       encoded as a <acronym>PNG</acronym> file. It could be a
       <acronym>GIF</acronym>, or a <acronym>JPEG</acronym>, but it is
       a <acronym>PNG</acronym>.</para>
       
     <para>And <acronym>PNG</acronym> is a protocol.</para>
       
     <para>At this point, I can hear some of you yelling,
       <emphasis><quote>No, it is not! It is a file
       format!</quote></emphasis></para>
 
     <para>Well, of course it is a file format. But from the
       perspective of data communications, a file format is a protocol:
       The file structure is a <emphasis>language</emphasis>, a terse
       one at that, communicating to our <emphasis>process</emphasis>
       how the data is organized. Ergo, it is a
       <emphasis>protocol</emphasis>.</para>
 
     <para>Alas, if all we received was the <acronym>PNG</acronym>
       file, our software would be facing a serious problem: How is it
       supposed to know the data is representing an image, as opposed
       to some text, or perhaps a sound, or what not? Secondly, how is
       it supposed to know the image is in the <acronym>PNG</acronym>
       format as opposed to <acronym>GIF</acronym>, or
       <acronym>JPEG</acronym>, or some other image format?</para>
 
     <para>To obtain that information, we are using another protocol:
       <acronym>HTTP</acronym>. This protocol can tell us exactly that
       the data represents an image, and that it uses the
       <acronym>PNG</acronym> protocol. It can also tell us some other
       things, but let us stay focused on protocol layers here.
       </para>
 
     <para>So, now we have some data wrapped in the <acronym>PNG</acronym>
       protocol, wrapped in the <acronym>HTTP</acronym> protocol.
       How did we get it from the server?</para>
 
     <para>By using <acronym>TCP/IP</acronym> over Ethernet, that is
       how.  Indeed, that is three more protocols. Instead of
       continuing inside out, I am now going to talk about Ethernet,
       simply because it is easier to explain the rest that way.</para>
 
     <para>Ethernet is an interesting system of connecting computers in
       a <emphasis>local area network</emphasis>
       (<acronym>LAN</acronym>).  Each computer has a <emphasis>network
       interface card</emphasis> (<acronym>NIC</acronym>), which has a
       unique 48-bit <acronym>ID</acronym> called its
       <emphasis>address</emphasis>. No two Ethernet
       <acronym>NIC</acronym>s in the world have the same address.
       </para>
 
     <para>These <acronym>NIC</acronym>s are all connected with each
       other. Whenever one computer wants to communicate with another
       in the same Ethernet <acronym>LAN</acronym>, it sends a message
       over the network. Every <acronym>NIC</acronym> sees the
       message. But as part of the Ethernet
       <emphasis>protocol</emphasis>, the data contains the address of
       the destination <acronym>NIC</acronym> (among other things). So,
       only one of all the network interface cards will pay attention
       to it, the rest will ignore it.</para>
 
     <para>But not all computers are connected to the same
       network. Just because we have received the data over our
       Ethernet does not mean it originated in our own local area
       network. It could have come to us from some other network (which
       may not even be Ethernet based) connected with our own network
       via the Internet.</para>
 
     <para>All data is transfered over the Internet using
       <acronym>IP</acronym>, which stands for <emphasis>Internet
       Protocol</emphasis>. Its basic role is to let us know where in
       the world the data has arrived from, and where it is supposed to
       go to. It does not <emphasis>guarantee</emphasis> we will
       receive the data, only that we will know where it came from
       <emphasis>if</emphasis> we do receive it.</para>
 
     <para>Even if we do receive the data, <acronym>IP</acronym> does
       not guarantee we will receive various chunks of data in the same
       order the other computer has sent it to us. So, we can receive
       the center of our image before we receive the upper left corner
       and after the lower right, for example.</para>
 
     <para>It is <acronym>TCP</acronym> (<emphasis>Transmission Control
       Protocol</emphasis>) that asks the sender to resend any lost
       data and that places it all into the proper order.</para>
 
     <para>All in all, it took <emphasis>five</emphasis> different
       protocols for one computer to communicate to another what an
       image looks like.  We received the data wrapped into the
       <acronym>PNG</acronym> protocol, which was wrapped into the
       <acronym>HTTP</acronym> protocol, which was wrapped into the
       <acronym>TCP</acronym> protocol, which was wrapped into the
       <acronym>IP</acronym> protocol, which was wrapped into the
       <acronym>Ethernet</acronym> protocol.</para>
 
     <para>Oh, and by the way, there probably were several other
       protocols involved somewhere on the way. For example, if our
       <acronym>LAN</acronym> was connected to the Internet through a
       dial-up call, it used the <acronym>PPP</acronym> protocol over
       the modem which used one (or several) of the various modem
       protocols, et cetera, et cetera, et cetera...</para>
 
     <para>As a developer you should be asking by now,
       <emphasis><quote>How am I supposed to handle it
       all?</quote></emphasis></para>
 
     <para>Luckily for you, you are <emphasis>not</emphasis> supposed
       to handle it all. You <emphasis>are</emphasis> supposed to
       handle some of it, but not all of it. Specifically, you need not
       worry about the physical connection (in our case Ethernet and
       possibly <acronym>PPP</acronym>, etc). Nor do you need to handle
       the Internet Protocol, or the Transmission Control
       Protocol.</para>
 
     <para>In other words, you do not have to do anything to receive
       the data from the other computer. Well, you do have to
       <emphasis>ask</emphasis> for it, but that is almost as simple as
       opening a file.</para>
 
     <para>Once you have received the data, it is up to you to figure
       out what to do with it. In our case, you would need to
       understand the <acronym>HTTP</acronym> protocol and the
       <acronym>PNG</acronym> file structure.</para>
 
     <para>To use an analogy, all the internetworking protocols become
       a gray area: Not so much because we do not understand how it
       works, but because we are no longer concerned about it. The
       sockets interface takes care of this gray area for us:</para>
 
     <mediaobject>
       <imageobject>
         <imagedata fileref="sockets/slayers">
       </imageobject>
        
       <textobject>
         <literallayout class="monospaced">+----------------+
 |xxxxEthernetxxxx|
 |+--------------+|
 ||xxxxxxIPxxxxxx||
 ||+------------+||
 |||xxxxxTCPxxxx|||
 |||+----------+|||
 ||||   HTTP   ||||
 ||||+--------+||||
 |||||   PNG  |||||
 |||||+------+|||||
 |||||| Data ||||||
 |||||+------+|||||
 ||||+--------+||||
 |||+----------+|||
 ||+------------+||
 |+--------------+|
 +----------------+</literallayout>
       </textobject>
        
       <textobject>
         <phrase>Sockets Covered Protocol Layers</phrase>
       </textobject>
     </mediaobject>
 
     <para>We only need to understand any protocols that tell us how to
       <emphasis>interpret the data</emphasis>, not how to
       <emphasis>receive</emphasis> it from another process, nor how to
       <emphasis>send</emphasis> it to another process.</para>
 
   </sect1>
 
   <sect1 id="sockets-model">
     <title>The Sockets Model</title>
 
     <para><acronym>BSD</acronym> sockets are built on the basic Unix
       model: <emphasis>Everything is a file.</emphasis> In our
       example, then, sockets would let us receive an <emphasis>HTTP
       file</emphasis>, so to speak. It would then be up to us to
       extract the <emphasis><acronym>PNG</acronym> file</emphasis>
       from it.
       </para>
 
     <para>Because of the complexity of internetworking, we cannot just
       use the <function role="syscall">open</function> system call, or
       the <function>open()</function> C function. Instead, we need to
       take several steps to <quote>opening</quote> a socket.</para>
 
     <para>Once we do, however, we can start treating the
       <emphasis>socket</emphasis> the same way we treat any
       <emphasis>file descriptor</emphasis>: We can
       <function>read</function> from it, <function>write</function> to
       it, <function>pipe</function> it, and, eventually,
       <function>close</function> it.</para>
 
   </sect1>
 
   <sect1 id="sockets-essential-functions">
     <title>Essential Socket Functions</title>
 
     <para>While FreeBSD offers different functions to work with
       sockets, we only <emphasis>need</emphasis> four to
       <quote>open</quote> a socket.  And in some cases we only need
       two.</para>
 
     <sect2 id="sockets-client-server">
       <title>The Client-Server Difference</title>
 
       <para>Typically, one of the ends of a socket-based data
         communication is a <emphasis>server</emphasis>, the other is a
         <emphasis>client</emphasis>.</para>
 
       <sect3 id="sockets-common-elements">
         <title>The Common Elements</title>
 
         <sect4 id="sockets-socket">
 	  <title><function>socket</function></title>
 
 	  <para>The one function used by both, clients and servers, is
 	    &man.socket.2;. It is declared this way:</para>
 
 <programlisting>
 int socket(int domain, int type, int protocol);
 </programlisting>
 
           <para>The return value is of the same type as that of
 	    <function>open</function>, an integer. FreeBSD allocates
 	    its value from the same pool as that of file handles.
 	    That is what allows sockets to be treated the same way as
 	    files.</para>
 
 	  <para>The <varname>domain</varname> argument tells the
 	    system what <emphasis>protocol family</emphasis> you want
 	    it to use. Many of them exist, some are vendor specific,
 	    others are very common. They are declared in
 	    <filename>sys/socket.h</filename>.</para>
 
 	  <para>Use <constant>PF_INET</constant> for
 	    <acronym>UDP</acronym>, <acronym>TCP</acronym> and other
 	    Internet protocols (<acronym>IP</acronym>v4).</para>
 
 	  <para>Five values are defined for the
 	    <varname>type</varname> argument, again, in
 	    <filename>sys/socket.h</filename>.  All of them start with
 	    <quote><constant>SOCK_</constant></quote>.  The most
 	    common one is <constant>SOCK_STREAM</constant>, which
 	    tells the system you are asking for a <emphasis>reliable
 	    stream delivery service</emphasis> (which is
 	    <acronym>TCP</acronym> when used with
 	    <constant>PF_INET</constant>).</para>
 
 	  <para>If you asked for <constant>SOCK_DGRAM</constant>, you
 	    would be requesting a <emphasis>connectionless datagram
 	    delivery service</emphasis> (in our case,
 	    <acronym>UDP</acronym>).</para>
 
 	  <para>If you wanted to be in charge of the low-level
 	    protocols (such as <acronym>IP</acronym>), or even network
 	    interfaces (e.g., the Ethernet), you would need to specify
 	    <constant>SOCK_RAW</constant>.</para>
 
 	  <para>Finally, the <varname>protocol</varname> argument
 	    depends on the previous two arguments, and is not always
 	    meaningful.  In that case, use <constant>0</constant> for
 	    its value.</para>
 
 	  <note id="sockets-unconnected">
 	    <title>The Unconnected Socket</title>
 
 	    <para>Nowhere, in the <function>socket</function> function
 	      have we specified to what other system we should be
 	      connected.  Our newly created socket remains
 	      <emphasis>unconnected</emphasis>.</para>
 
 	    <para>This is on purpose: To use a telephone analogy, we
 	      have just attached a modem to the phone line. We have
 	      neither told the modem to make a call, nor to answer if
 	      the phone rings.</para>
 	  </note>
 
 	</sect4>
 
         <sect4 id="sockets-sockaddr">
 	  <title><varname>sockaddr</varname></title>
 
 	  <para>Various functions of the sockets family expect the
  	    address of (or pointer to, to use C terminology) a small
  	    area of the memory. The various C declarations in the
  	    <filename>sys/socket.h</filename> refer to it as
  	    <varname>struct sockaddr</varname>. This structure is
  	    declared in the same file:</para>
 
 <programlisting>
 /*
  * Structure used by kernel to store most
  * addresses.
  */
 struct sockaddr {
 	u_char		sa_len;		/* total length */
 	sa_family_t	sa_family;	/* address family */
 	char		sa_data[14];	/* actually longer; address value */
 };
 #define	SOCK_MAXADDRLEN	255		/* longest possible addresses */
 </programlisting>
 
           <para>Please note the <emphasis>vagueness</emphasis> with
 	    which the <varname>sa_data</varname> field is declared,
 	    just as an array of <constant>14</constant> bytes, with
 	    the comment hinting there can be more than
 	    <constant>14</constant> of them.</para>
 
 	  <para>This vagueness is quite deliberate. Sockets is a very
 	    powerful interface. While most people perhaps think of it
 	    as nothing more than the Internet interface&mdash;and most
 	    applications probably use it for that
 	    nowadays&mdash;sockets can be used for just about
 	    <emphasis>any</emphasis> kind of interprocess
 	    communications, of which the Internet (or, more precisely,
 	    <acronym>IP</acronym>) is only one.</para>
 
 	  <para>The <filename>sys/socket.h</filename> refers to the
 	    various types of protocols sockets will handle as
 	    <emphasis>address families</emphasis>, and lists them
 	    right before the definition of
 	    <varname>sockaddr</varname>:</para>
 
 <programlisting>
 /*
  * Address families.
  */
 #define	AF_UNSPEC	0		/* unspecified */
 #define	AF_LOCAL	1		/* local to host (pipes, portals) */
 #define	AF_UNIX		AF_LOCAL	/* backward compatibility */
 #define	AF_INET		2		/* internetwork: UDP, TCP, etc. */
 #define	AF_IMPLINK	3		/* arpanet imp addresses */
 #define	AF_PUP		4		/* pup protocols: e.g. BSP */
 #define	AF_CHAOS	5		/* mit CHAOS protocols */
 #define	AF_NS		6		/* XEROX NS protocols */
 #define	AF_ISO		7		/* ISO protocols */
 #define	AF_OSI		AF_ISO
 #define	AF_ECMA		8		/* European computer manufacturers */
 #define	AF_DATAKIT	9		/* datakit protocols */
 #define	AF_CCITT	10		/* CCITT protocols, X.25 etc */
 #define	AF_SNA		11		/* IBM SNA */
 #define AF_DECnet	12		/* DECnet */
 #define AF_DLI		13		/* DEC Direct data link interface */
 #define AF_LAT		14		/* LAT */
 #define	AF_HYLINK	15		/* NSC Hyperchannel */
 #define	AF_APPLETALK	16		/* Apple Talk */
 #define	AF_ROUTE	17		/* Internal Routing Protocol */
 #define	AF_LINK		18		/* Link layer interface */
 #define	pseudo_AF_XTP	19		/* eXpress Transfer Protocol (no AF) */
 #define	AF_COIP		20		/* connection-oriented IP, aka ST II */
 #define	AF_CNT		21		/* Computer Network Technology */
 #define pseudo_AF_RTIP	22		/* Help Identify RTIP packets */
 #define	AF_IPX		23		/* Novell Internet Protocol */
 #define	AF_SIP		24		/* Simple Internet Protocol */
 #define	pseudo_AF_PIP	25		/* Help Identify PIP packets */
 #define	AF_ISDN		26		/* Integrated Services Digital Network*/
 #define	AF_E164		AF_ISDN		/* CCITT E.164 recommendation */
 #define	pseudo_AF_KEY	27		/* Internal key-management function */
 #define	AF_INET6	28		/* IPv6 */
 #define	AF_NATM		29		/* native ATM access */
 #define	AF_ATM		30		/* ATM */
 #define pseudo_AF_HDRCMPLT 31		/* Used by BPF to not rewrite headers
 					 * in interface output routine
 					 */
 #define	AF_NETGRAPH	32		/* Netgraph sockets */
 
 #define	AF_MAX		33
 </programlisting>
 
           <para>The one used for <acronym>IP</acronym> is
 	    <symbol>AF_INET</symbol>.  It is a symbol for the constant
 	    <constant>2</constant>.</para>
 
 	  <para>It is the <emphasis>address family</emphasis> listed
 	    in the <varname>sa_family</varname> field of
 	    <varname>sockaddr</varname> that decides how exactly the
 	    vaguely named bytes of <varname>sa_data</varname> will be
 	    used.</para>
 
 	  <para>Specifically, whenever the <emphasis>address
 	    family</emphasis> is <symbol>AF_INET</symbol>, we can use
 	    <varname>struct sockaddr_in</varname> found in
 	    <filename>netinet/in.h</filename>, wherever
 	    <varname>sockaddr</varname> is expected:</para>
 
 <programlisting>
 /*
  * Socket address, internet style.
  */
 struct sockaddr_in {
 	u_char	sin_len;
 	u_char	sin_family;
 	u_short	sin_port;
 	struct	in_addr sin_addr;
 	char	sin_zero[8];
 };
 </programlisting>
 
           <para>We can visualize its organization this way:</para>
 
           <mediaobject>
            <imageobject>
              <imagedata fileref="sockets/sain">
            </imageobject>
        
            <textobject>
              <literallayout class="monospaced">        0        1        2       3
    +--------+--------+-----------------+
  0 |    0   | Family |       Port      |
    +--------+--------+-----------------+
  4 |             IP Address            |
    +-----------------------------------+
  8 |                 0                 |
    +-----------------------------------+
 12 |                 0                 |
    +-----------------------------------+</literallayout>
            </textobject>
        
            <textobject>
              <phrase>sockaddr_in</phrase>
            </textobject>
          </mediaobject>
 
           <para>The three important fields are
 	    <varname>sin_family</varname>, which is byte 1 of the
 	    structure, <varname>sin_port</varname>, a 16-bit value
 	    found in bytes 2 and 3, and <varname>sin_addr</varname>, a
 	    32-bit integer representation of the <acronym>IP</acronym>
 	    address, stored in bytes 4-7.</para>
 
 	  <para>Now, let us try to fill it out. Let us assume we are
 	    trying to write a client for the
 	    <emphasis>daytime</emphasis> protocol, which simply states
 	    that its server will write a text string representing the
 	    current date and time to port 13. We want to use
 	    <acronym>TCP/IP</acronym>, so we need to specify
 	    <constant>AF_INET</constant> in the address family
 	    field. <constant>AF_INET</constant> is defined as
 	    <constant>2</constant>. Let us use the
 	    <acronym>IP</acronym> address of <hostid
 	    role="ipaddr">192.43.244.18</hostid>, which is the time
 	    server of US federal government (<hostid
 	    role="domainname">time.nist.gov</hostid>).</para>
 
           <mediaobject>
             <imageobject>
               <imagedata fileref="sockets/sainfill">
             </imageobject>
        
             <textobject>
               <literallayout class="monospaced">        0        1        2       3
    +--------+--------+-----------------+
  0 |    0   |   2    |        13       |
    +-----------------+-----------------+
  4 |           192.43.244.18           |
    +-----------------------------------+
  8 |                 0                 |
    +-----------------------------------+
 12 |                 0                 |
    +-----------------------------------+</literallayout>
             </textobject>
        
             <textobject>
               <phrase>Specific example of sockaddr_in</phrase>
             </textobject>
           </mediaobject>
 
           <para>By the way the <varname>sin_addr</varname> field is
  	    declared as being of the <varname>struct in_addr</varname>
  	    type, which is defined in
  	    <filename>netinet/in.h</filename>:</para>
 
 <programlisting>
 /*
  * Internet address (a structure for historical reasons)
  */
 struct in_addr {
 	in_addr_t s_addr;
 };
 </programlisting>
 
           <para>In addition, <varname>in_addr_t</varname> is a 32-bit
             integer.</para>
 
 	  <para>The <hostid role="ipaddr">192.43.244.18</hostid> is
 	    just a convenient notation of expressing a 32-bit integer
 	    by listing all of its 8-bit bytes, starting with the
 	    <emphasis>most significant</emphasis> one.</para>
 
           <para>So far, we have viewed <varname>sockaddr</varname> as
 	    an abstraction.  Our computer does not store
 	    <varname>short</varname> integers as a single 16-bit
 	    entity, but as a sequence of 2 bytes. Similarly, it stores
 	    32-bit integers as a sequence of 4 bytes.</para>
 
           <para>Suppose we coded something like this:</para>
 
 <programlisting>
 	sa.sin_family      = AF_INET;
 	sa.sin_port        = 13;
 	sa.sin_addr.s_addr = (((((192 << 8) | 43) << 8) | 244) << 8) | 18;
 </programlisting>
 
           <para>What would the result look like?</para>
 
 	  <para>Well, that depends, of course. On a Pentium, or other
 	    x86, based computer, it would look like this:</para>
 
           <mediaobject>
             <imageobject>
               <imagedata fileref="sockets/sainlsb">
             </imageobject>
        
             <textobject>
               <literallayout class="monospaced">        0        1        2       3
    +--------+--------+--------+--------+
  0 |    0   |   2    |   13   |   0    |
    +--------+--------+--------+--------+
  4 |   18   |  244   |   43   |  192   |
    +-----------------------------------+
  8 |                 0                 |
    +-----------------------------------+
 12 |                 0                 |
    +-----------------------------------+</literallayout>
             </textobject>
        
             <textobject>
               <phrase>sockaddr_in on an Intel system</phrase>
             </textobject>
           </mediaobject>
 
           <para>On a different system, it might look like this:
 	    </para>
 
           <mediaobject>
             <imageobject>
               <imagedata fileref="sockets/sainmsb">
             </imageobject>
        
             <textobject>
               <literallayout class="monospaced">        0        1        2       3
    +--------+--------+--------+--------+
  0 |    0   |   2    |    0   |   13   |
    +--------+--------+--------+--------+
  4 |   192  |   43   |   244  |   18   |
    +-----------------------------------+
  8 |                 0                 |
    +-----------------------------------+
 12 |                 0                 |
    +-----------------------------------+</literallayout>
             </textobject>
        
             <textobject>
               <phrase>sockaddr_in on an MSB system</phrase>
             </textobject>
           </mediaobject>
 
 	  <para>And on a PDP it might look different yet. But the
 	    above two are the most common ways in use today.</para>
 
 	  <para>Ordinarily, wanting to write portable code,
 	    programmers pretend that these differences do not
 	    exist. And they get away with it (except when they code in
 	    assembly language). Alas, you cannot get away with it that
 	    easily when coding for sockets.</para>
 
 	  <para>Why?</para>
 
 	  <para>Because when communicating with another computer, you
 	    usually do not know whether it stores data <emphasis>most
 	    significant byte</emphasis> (<acronym>MSB</acronym>) or
 	    <emphasis>least significant byte</emphasis>
 	    (<acronym>LSB</acronym>) first.</para>
 
 	  <para>You might be wondering, <emphasis><quote>So, will
 	    sockets not handle it for me?</quote></emphasis></para>
 
 	  <para>It will not.</para>
 
 	  <para>While that answer may surprise you at first, remember
  	    that the general sockets interface only understands the
  	    <varname>sa_len</varname> and <varname>sa_family</varname>
  	    fields of the <varname>sockaddr</varname> structure. You
  	    do not have to worry about the byte order there (of
  	    course, on FreeBSD <varname>sa_family</varname> is only 1
  	    byte anyway, but many other Unix systems do not have
  	    <varname>sa_len</varname> and use 2 bytes for
  	    <varname>sa_family</varname>, and expect the data in
  	    whatever order is native to the computer).</para>
 
 	  <para>But the rest of the data is just
 	    <varname>sa_data[14]</varname> as far as sockets
 	    goes. Depending on the <emphasis>address
 	    family</emphasis>, sockets just forwards that data to its
 	    destination.</para>
 
 	  <para>Indeed, when we enter a port number, it is because we
 	    want the other computer to know what service we are asking
 	    for. And, when we are the server, we read the port number
 	    so we know what service the other computer is expecting
 	    from us. Either way, sockets only has to forward the port
 	    number as data. It does not interpret it in any way.</para>
 
 	  <para>Similarly, we enter the <acronym>IP</acronym> address
 	    to tell everyone on the way where to send our data
 	    to. Sockets, again, only forwards it as data.</para>
 
 	  <para>That is why, we (the <emphasis>programmers</emphasis>,
 	    not the <emphasis>sockets</emphasis>) have to distinguish
 	    between the byte order used by our computer and a
 	    conventional byte order to send the data in to the other
 	    computer.</para>
 
 	  <para>We will call the byte order our computer uses the
 	    <emphasis>host byte order</emphasis>, or just the
 	    <emphasis>host order</emphasis>.</para>
 
 	  <para>There is a convention of sending the multi-byte data
 	    over <acronym>IP</acronym>
 	    <emphasis><acronym>MSB</acronym> first</emphasis>.  This,
 	    we will refer to as the <emphasis>network byte
 	    order</emphasis>, or simply the <emphasis>network
 	    order</emphasis>.</para>
 
 	  <para>Now, if we compiled the above code for an Intel based
 	    computer, our <emphasis>host byte order</emphasis> would
 	    produce:</para>
 
 	  <mediaobject>
 	    <imageobject>
               <imagedata fileref="sockets/sainlsb">
             </imageobject>
        
             <textobject>
               <literallayout class="monospaced">        0        1        2       3
    +--------+--------+--------+--------+
  0 |    0   |   2    |   13   |   0    |
    +--------+--------+--------+--------+
  4 |   18   |  244   |   43   |  192   |
    +-----------------------------------+
  8 |                 0                 |
    +-----------------------------------+
 12 |                 0                 |
    +-----------------------------------+</literallayout>
             </textobject>
        
             <textobject>
               <phrase>Host byte order on an Intel system</phrase>
             </textobject>
           </mediaobject>
 
           <para>But the <emphasis>network byte order</emphasis>
  	    requires that we store the data <acronym>MSB</acronym>
  	    first:</para>
 
           <mediaobject>
             <imageobject>
               <imagedata fileref="sockets/sainmsb">
             </imageobject>
        
             <textobject>
               <literallayout class="monospaced">        0        1        2       3
    +--------+--------+--------+--------+
  0 |    0   |   2    |    0   |   13   |
    +--------+--------+--------+--------+
  4 |   192  |   43   |   244  |   18   |
    +-----------------------------------+
  8 |                 0                 |
    +-----------------------------------+
 12 |                 0                 |
    +-----------------------------------+</literallayout>
             </textobject>
        
             <textobject>
               <phrase>Network byte order</phrase>
             </textobject>
           </mediaobject>
 
           <para>Unfortunately, our <emphasis>host order</emphasis> is
 	    the exact opposite of the <emphasis>network
 	    order</emphasis>.</para>
 
 	  <para>We have several ways of dealing with it. One would be
 	    to <emphasis>reverse</emphasis> the values in our code:
 	    </para>
 
 <programlisting>
 	sa.sin_family      = AF_INET;
 	sa.sin_port        = 13 << 8;
 	sa.sin_addr.s_addr = (((((18 << 8) | 244) << 8) | 43) << 8) | 192;
 </programlisting>
 
            <para>This will <emphasis>trick</emphasis> our compiler
 	     into storing the data in the <emphasis>network byte
 	     order</emphasis>. In some cases, this is exactly the way
 	     to do it (e.g., when programming in assembly
 	     language). In most cases, however, it can cause a
 	     problem.</para>
 
 	   <para>Suppose, you wrote a sockets-based program in C. You
 	     know it is going to run on a Pentium, so you enter all
 	     your constants in reverse and force them to the
 	     <emphasis>network byte order</emphasis>. It works
 	     well.</para>
 
            <para>Then, some day, your trusted old Pentium becomes a
 	     rusty old Pentium.  You replace it with a system whose
 	     <emphasis>host order</emphasis> is the same as the
 	     <emphasis>network order</emphasis>. You need to recompile
 	     all your software. All of your software continues to
 	     perform well, except the one program you wrote.</para>
 
 	   <para>You have since forgotten that you had forced all of
 	     your constants to the opposite of the <emphasis>host
 	     order</emphasis>. You spend some quality time tearing out
 	     your hair, calling the names of all gods you ever heard
 	     of (and some you made up), hitting your monitor with a
 	     nerf bat, and performing all the other traditional
 	     ceremonies of trying to figure out why something that has
 	     worked so well is suddenly not working at all.</para>
 
 	   <para>Eventually, you figure it out, say a couple of swear
 	     words, and start rewriting your code.</para>
 
 	   <para>Luckily, you are not the first one to face the
 	     problem. Someone else has created the &man.htons.3; and
 	     &man.htonl.3; C functions to convert a
 	     <varname>short</varname> and <varname>long</varname>
 	     respectively from the <emphasis>host byte
 	     order</emphasis> to the <emphasis>network byte
 	     order</emphasis>, and the &man.ntohs.3; and &man.ntohl.3;
 	     C functions to go the other way.</para>
 
 	   <para>On <emphasis><acronym>MSB</acronym>-first</emphasis>
 	     systems these functions do nothing. On
 	     <emphasis><acronym>LSB</acronym>-first</emphasis> systems
 	     they convert values to the proper order.</para>
 
 	   <para>So, regardless of what system your software is
 	     compiled on, your data will end up in the correct order
 	     if you use these functions.</para>
 
 	 </sect4>
 
       </sect3>
 
       <sect3 id="sockets-client-functions">
         <title>Client Functions</title>
 
         <para>Typically, the client initiates the connection to the
 	  server. The client knows which server it is about to call:
 	  It knows its <acronym>IP</acronym> address, and it knows the
 	  <emphasis>port</emphasis> the server resides at. It is akin
 	  to you picking up the phone and dialing the number (the
 	  <emphasis>address</emphasis>), then, after someone answers,
 	  asking for the person in charge of wingdings (the
 	  <emphasis>port</emphasis>).</para>
 
         <sect4 id="sockets-connect">
           <title><function>connect</function></title>
 
           <para>Once a client has created a socket, it needs to
 	    connect it to a specific port on a remote system. It uses
 	    &man.connect.2;:</para>
 
 <programlisting>
 int connect(int s, const struct sockaddr *name, socklen_t namelen);
 </programlisting>
 
           <para>The <varname>s</varname> argument is the socket, i.e.,
 	    the value returned by the <function>socket</function>
 	    function. The <varname>name</varname> is a pointer to
 	    <varname>sockaddr</varname>, the structure we have talked
 	    about extensively. Finaly, <varname>namelen</varname>
 	    informs the system how many bytes are in our
 	    <varname>sockaddr</varname> structure.</para>
 
           <para>If <function>connect</function> is successful, it
 	    returns <constant>0</constant>. Otherwise it returns
 	    <constant>-1</constant> and stores the error code in
 	    <varname>errno</varname>.</para>
 
           <para>There are many reasons why
 	    <function>connect</function> may fail.  For example, with
 	    an attempt to an Internet connection, the
 	    <acronym>IP</acronym> address may not exist, or it may be
 	    down, or just too busy, or it may not have a server
 	    listening at the specified port. Or it may outright
 	    <emphasis>refuse</emphasis> any request for specific
 	    code.</para>
 
 	</sect4>
 
         <sect4 id="sockets-first-client">
           <title>Our First Client</title>
 
 	  <para>We now know enough to write a very simple client, one
 	    that will get current time from <hostid
 	    role="ipaddr">192.43.244.18</hostid> and print it to
 	    <devicename>stdout</devicename>.</para>
 
 <programlisting>
 /*
  * daytime.c
  *
  * Programmed by G. Adam Stanislav
  */
 #include &lt;stdio.h&gt;
 #include &lt;sys/types.h&gt;
 #include &lt;sys/socket.h&gt;
 #include &lt;netinet/in.h&gt;
 
 int main() {
   register int s;
   register int bytes;
   struct sockaddr_in sa;
   char buffer[BUFSIZ+1];
 
   if ((s = socket(PF_INET, SOCK_STREAM, 0)) &lt; 0) {
     perror("socket");
     return 1;
   }
 
   bzero(&amp;sa, sizeof sa);
 
   sa.sin_family = AF_INET;
   sa.sin_port = htons(13);
   sa.sin_addr.s_addr = htonl((((((192 &lt;&lt; 8) | 43) &lt;&lt; 8) | 244) &lt;&lt; 8) | 18);
   if (connect(s, (struct sockaddr *)&amp;sa, sizeof sa) &lt; 0) {
     perror("connect");
     close(s);
     return 2;
   }
 
   while ((bytes = read(s, buffer, BUFSIZ)) > 0)
     write(1, buffer, bytes);
 
   close(s);
   return 0;
 }
 </programlisting>
 
           <para>Go ahead, enter it in your editor, save it as
 	    <filename>daytime.c</filename>, then compile and run
 	    it:</para>
 
 <screen>&prompt.user; <userinput>cc -O3 -o daytime daytime.c</userinput>
 &prompt.user; <userinput>./daytime</userinput>
 
 52079 01-06-19 02:29:25 50 0 1 543.9 UTC(NIST) * 
 &prompt.user;</screen>
 
           <para>In this case, the date was June 19, 2001, the time was
 	    02:29:25 <acronym>UTC</acronym>. Naturally, your results
 	    will vary.</para>
 
 	</sect4>
 
       </sect3>
 
       <sect3 id="sockets-server-functions">
         <title>Server Functions</title>
 
         <para>The typical server does not initiate the
 	  connection. Instead, it waits for a client to call it and
 	  request services. It does not know when the client will
 	  call, nor how many clients will call. It may be just sitting
 	  there, waiting patiently, one moment, The next moment, it
 	  can find itself swamped with requests from a number of
 	  clients, all calling in at the same time.</para>
 
 	<para>The sockets interface offers three basic functions to
 	  handle this.</para>
 
         <sect4 id="sockets-bind">
           <title><function>bind</function></title>
 
           <para>Ports are like extensions to a phone line: After you
 	    dial a number, you dial the extension to get to a specific
 	    person or department.</para>
 
 	  <para>There are 65535 <acronym>IP</acronym> ports, but a
 	    server usually processes requests that come in on only one
 	    of them. It is like telling the phone room operator that
 	    we are now at work and available to answer the phone at a
 	    specific extension. We use &man.bind.2; to tell sockets
 	    which port we want to serve.</para>
 
 <programlisting>
 int bind(int s, const struct sockaddr *addr, socklen_t addrlen);
 </programlisting>
 
           <para>Beside specifying the port in <varname>addr</varname>,
 	    the server may include its <acronym>IP</acronym>
 	    address. However, it can just use the symbolic constant
 	    <symbol>INADDR_ANY</symbol> to indicate it will serve all
 	    requests to the specified port regardless of what its
 	    <acronym>IP</acronym> address is. This symbol, along with
 	    several similar ones, is declared in
 	    <filename>netinet/in.h</filename></para>
 
 <programlisting>
 #define	INADDR_ANY		(u_int32_t)0x00000000
 </programlisting>
 
           <para>Suppose we were writing a server for the
 	    <emphasis>daytime</emphasis> protocol over
 	    <acronym>TCP</acronym>/<acronym>IP</acronym>. Recall that
 	    it uses port 13. Our <varname>sockaddr_in</varname>
 	    structure would look like this:</para>
 
           <mediaobject>
             <imageobject>
               <imagedata fileref="sockets/sainserv">
             </imageobject>
        
             <textobject>
               <literallayout class="monospaced">        0        1        2       3
    +--------+--------+--------+--------+
  0 |    0   |   2    |    0   |   13   |
    +--------+--------+--------+--------+
  4 |                 0                 |
    +-----------------------------------+
  8 |                 0                 |
    +-----------------------------------+
 12 |                 0                 |
    +-----------------------------------+</literallayout>
             </textobject>
        
             <textobject>
               <phrase>Example Server sockaddr_in</phrase>
             </textobject>
           </mediaobject>
         </sect4>
 
         <sect4 id="sockets-listen">
           <title><function>listen</function></title>
 
           <para>To continue our office phone analogy, after you have
 	    told the phone central operator what extension you will be
 	    at, you now walk into your office, and make sure your own
 	    phone is plugged in and the ringer is turned on. Plus, you
 	    make sure your call waiting is activated, so you can hear
 	    the phone ring even while you are talking to someone.</para>
 
           <para>The server ensures all of that with the &man.listen.2;
             function.</para>
 
 <programlisting>
 int listen(int s, int backlog);
 </programlisting>
 
           <para>In here, the <varname>backlog</varname> variable tells
 	    sockets how many incoming requests to accept while you are
 	    busy processing the last request. In other words, it
 	    determines the maximum size of the queue of pending
 	    connections.</para>
 
         </sect4>
 
         <sect4 id="sockets-accept">
           <title><function>accept</function></title>
 
           <para>After you hear the phone ringing, you accept the call
 	    by answering the call. You have now established a
 	    connection with your client. This connection remains
 	    active until either you or your client hang up.</para>
 
 	  <para>The server accepts the connection by using the
   	    &man.accept.2; function.</para>
 
 <programlisting>
 int accept(int s, struct sockaddr *addr, socklen_t *addrlen);
 </programlisting>
 
           <para>Note that this time <varname>addrlen</varname> is a
             pointer. This is necessary because in this case it is the
             socket that fills out <varname>addr</varname>, the
             <varname>sockaddr_in</varname> structure.</para>
 
 	  <para>The return value is an integer. Indeed, the
 	    <function>accept</function> returns a <emphasis>new
 	    socket</emphasis>. You will use this new socket to
 	    communicate with the client.</para>
 
           <para>What happens to the old socket? It continues to listen
 	    for more requests (remember the <varname>backlog</varname>
 	    variable we passed to <function>listen</function>?) until
 	    we <function>close</function> it.</para>
 
 	  <para>Now, the new socket is meant only for
 	    communications. It is fully connected. We cannot pass it
 	    to <function>listen</function> again, trying to accept
 	    additional connections.</para>
 
         </sect4>
 
         <sect4 id="sockets-first-server">
           <title>Our First Server</title>
 
 	  <para>Our first server will be somewhat more complex than
 	    our first client was: Not only do we have more sockets
 	    functions to use, but we need to write it as a
 	    daemon.</para>
 
 	  <para>This is best achieved by creating a <emphasis>child
 	    process</emphasis> after binding the port. The main
 	    process then exits and returns control to the
 	    <application>shell</application> (or whatever program
 	    invoked it).</para>
 
 	  <para>The child calls <function>listen</function>, then
 	    starts an endless loop, which accepts a connection, serves
 	    it, and eventually closes its socket.</para>
 
 <programlisting>
 /*
  * daytimed - a port 13 server
  *
  * Programmed by G. Adam Stanislav
  * June 19, 2001
  */
 #include &lt;stdio.h&gt;
 #include &lt;time.h&gt;
 #include &lt;unistd.h&gt;
 #include &lt;sys/types.h&gt;
 #include &lt;sys/socket.h&gt;
 #include &lt;netinet/in.h&gt;
 
 #define BACKLOG 4
 
 int main() {
     register int s, c;
     int b;
     struct sockaddr_in sa;
     time_t t;
     struct tm *tm;
     FILE *client;
 
     if ((s = socket(PF_INET, SOCK_STREAM, 0)) &lt; 0) {
         perror("socket");
         return 1;
     }
 
     bzero(&amp;sa, sizeof sa);
 
     sa.sin_family = AF_INET;
     sa.sin_port   = htons(13);
 
     if (INADDR_ANY)
         sa.sin_addr.s_addr = htonl(INADDR_ANY);
 
     if (bind(s, (struct sockaddr *)&amp;sa, sizeof sa) < 0) {
         perror("bind");
         return 2;
     }
 
     switch (fork()) {
         case -1:
             perror("fork");
             return 3;
             break;
         default:
             close s;
             return 0;
             break;
         case 0:
             break;
     }
 
     listen(s, BACKLOG);
 
     for (;;) {
         b = sizeof sa;
 
         if ((c = accept(s, (struct sockaddr *)&amp;sa, &amp;b)) &lt; 0) {
             perror("daytimed accept");
             return 4;
         }
 
         if ((client = fdopen(c, "w")) == NULL) {
             perror("daytimed fdopen");
             return 5;
         }
 
         if ((t = time(NULL)) &lt; 0) {
             perror("daytimed time");
 
             return 6;
         }
 
         tm = gmtime(&amp;t);
         fprintf(client, "%.4i-%.2i-%.2iT%.2i:%.2i:%.2iZ\n",
             tm->tm_year + 1900,
             tm->tm_mon + 1,
             tm->tm_mday,
             tm->tm_hour,
             tm->tm_min,
             tm->tm_sec);
 
         fclose(client);
     }
 }
 </programlisting>
 
           <para>We start by creating a socket. Then we fill out the
 	    <varname>sockaddr_in</varname> structure in
 	    <varname>sa</varname>.  Note the conditional use of
 	    <symbol>INADDR_ANY</symbol>:</para>
 
 <programlisting>
     if (INADDR_ANY)
         sa.sin_addr.s_addr = htonl(INADDR_ANY);
 </programlisting>
 
           <para>Its value is <constant>0</constant>. Since we have
 	    just used <function>bzero</function> on the entire
 	    structure, it would be redundant to set it to
 	    <constant>0</constant> again. But if we port our code to
 	    some other system where <symbol>INADDR_ANY</symbol> is
 	    perhaps not a zero, we need to assign it to
 	    <varname>sa.sin_addr.s_addr</varname>. Most modern C
 	    compilers are clever enough to notice that
 	    <symbol>INADDR_ANY</symbol> is a constant. As long as it
 	    is a zero, they will optimize the entire conditional
 	    statement out of the code.</para>
 
 	  <para>After we have called <function>bind</function>
 	    successfully, we are ready to become a
 	    <emphasis>daemon</emphasis>: We use
 	    <function>fork</function> to create a child process. In
 	    both, the parent and the child, the <varname>s</varname>
 	    variable is our socket. The parent process will not need
 	    it, so it calls <function>close</function>, then it
 	    returns <constant>0</constant> to inform its own parent it
 	    had terminated successfully.</para>
 
 	  <para>Meanwhile, the child process continues working in the
 	    background.  It calls <function>listen</function> and sets
 	    its backlog to <constant>4</constant>. It does not need a
 	    large value here because <emphasis>daytime</emphasis> is
 	    not a protocol many clients request all the time, and
 	    because it can process each request instantly anyway.</para>
 
 	  <para>Finally, the daemon starts an endless loop, which
 	    performs the following steps:</para>
 
 	  <procedure>
 	    <step><para> Call <function>accept</function>. It waits
 	      here until a client contacts it. At that point, it
 	      receives a new socket, <varname>c</varname>, which it
 	      can use to communicate with this particular client.
 	      </para></step>
 
             <step><para>It uses the C function
 	      <function>fdopen</function> to turn the socket from a
 	      low-level <emphasis>file descriptor</emphasis> to a
 	      C-style <varname>FILE</varname> pointer. This will allow
 	      the use of <function>fprintf</function> later on.
 	      </para></step>
 
 	    <step><para>It checks the time, and prints it in the
 	      <emphasis><acronym>ISO</acronym> 8601</emphasis> format
 	      to the <varname>client</varname> <quote>file</quote>. It
 	      then uses <function>fclose</function> to close the
 	      file. That will automatically close the socket as well.
 	      </para></step>
 
 	  </procedure>
 
 	  <para>We can <emphasis>generalize</emphasis> this, and use
 	    it as a model for many other servers:</para>
 
           <mediaobject>
             <imageobject>
               <imagedata fileref="sockets/serv">
             </imageobject>
        
             <textobject>
               <literallayout class="monospaced">+-----------------+
 |  Create Socket  |
 +-----------------+
           |
 +-----------------+
 |    Bind Port    |       Daemon Process
 +-----------------+
           |                 +--------+
           +-------------+--&gt;|  Init  |
           |             |   +--------+
 +-----------------+     |         |
 |        Exit     |     |   +--------+
 +-----------------+     |   | Listen |
                         |   +--------+
                         |         |
                         |   +--------+
                         |   | Accept |
                         |   +--------+
                         |         |
                         |   +--------+
                         |   | Serve  |
                         |   +--------+
                         |         |
                         |   +--------+
                         |   | Close  |
                         |&lt;--------+</literallayout>
             </textobject>
        
             <textobject>
               <phrase>Sequential Server</phrase>
             </textobject>
           </mediaobject>
 
           <para>This flowchart is good for <emphasis>sequential
 	    servers</emphasis>, i.e., servers that can serve one
 	    client at a time, just as we were able to with our
 	    <emphasis>daytime</emphasis> server. This is only possible
 	    whenever there is no real <quote>conversation</quote>
 	    going on between the client and the server: As soon as the
 	    server detects a connection to the client, it sends out
 	    some data and closes the connection. The entire operation
 	    may take nanoseconds, and it is finished.</para>
 
 	  <para>The advantage of this flowchart is that, except for
 	    the brief moment after the parent
 	    <function>fork</function>s and before it exits, there is
 	    always only one <emphasis>process</emphasis> active: Our
 	    server does not take up much memory and other system
 	    resources.</para>
 
 	  <para>Note that we have added <emphasis>initialize
 	    daemon</emphasis> in our flowchart. We did not need to
 	    initialize our own daemon, but this is a good place in the
 	    flow of the program to set up any
 	    <function>signal</function> handlers, open any files we
 	    may need, etc.</para>
 
 	  <para>Just about everything in the flow chart can be used
 	    literally on many different servers. The
 	    <emphasis>serve</emphasis> entry is the exception.  We
 	    think of it as a <emphasis><quote>black
 	    box</quote></emphasis>, i.e., something you design
 	    specifically for your own server, and just <quote>plug it
 	    into the rest.</quote></para>
 
 	  <para>Not all protocols are that simple. Many receive a
 	    request from the client, reply to it, then receive another
 	    request from the same client. Because of that, they do not
 	    know in advance how long they will be serving the
 	    client. Such servers usually start a new process for each
 	    client. While the new process is serving its client, the
 	    daemon can continue listening for more connections.</para>
 
 	  <para>Now, go ahead, save the above source code as
 	    <filename>daytimed.c</filename> (it is customary to end
 	    the names of daemons with the letter
 	    <constant>d</constant>). After you have compiled it, try
 	    running it:</para>
 
 <screen>&prompt.user; <userinput>./daytimed</userinput>
 bind: Permission denied
 &prompt.user;</screen>
 
           <para>What happened here? As you will recall, the
 	    <emphasis>daytime</emphasis> protocol uses port 13. But
 	    all ports below 1024 are reserved to the superuser
 	    (otherwise, anyone could start a daemon pretending to
 	    serve a commonly used port, while causing a security
 	    breach).</para>
 
 	  <para>Try again, this time as the superuser:</para>
 
 <screen>&prompt.root; <userinput>./daytimed</userinput>
 &prompt.root;</screen>
 
           <para>What... Nothing? Let us try again:</para>
 
 <screen>&prompt.root; <userinput>./daytimed</userinput>
 
 bind: Address already in use
 &prompt.root;</screen>
 
           <para>Every port can only be bound by one program at a
 	    time. Our first attempt was indeed successful: It started
 	    the child daemon and returned quietly. It is still running
 	    and will continue to run until you either kill it, or any
 	    of its system calls fail, or you reboot the system.</para>
 
 	  <para>Fine, we know it is running in the background. But is
 	    it working?  How do we know it is a proper
 	    <emphasis>daytime</emphasis> server?  Simple:</para>
 
 <screen>&prompt.user; <userinput>telnet localhost 13</userinput>
 
 Trying ::1...
 telnet: connect to address ::1: Connection refused
 Trying 127.0.0.1...
 Connected to localhost.
 Escape character is '^]'.
 2001-06-19T21:04:42Z
 Connection closed by foreign host.
 &prompt.user;</screen>
 
           <para><application>telnet</application> tried the new
 	    <acronym>IP</acronym>v6, and failed. It retried with
 	    <acronym>IP</acronym>v4 and succeeded.  The daemon
 	    works.</para>
 
           <para>If you have access to another Unix system via
 	    <application>telnet</application>, you can use it to test
 	    accessing the server remotely. My computer does not have a
 	    static <acronym>IP</acronym> address, so this is what I
 	    did:</para>
 
 <screen>&prompt.user; <userinput>who</userinput>
 
 whizkid          ttyp0   Jun 19 16:59   (216.127.220.143)
 xxx              ttyp1   Jun 19 16:06   (xx.xx.xx.xx)
 &prompt.user; <userinput>telnet 216.127.220.143 13</userinput>
 
 Trying 216.127.220.143...
 Connected to r47.bfm.org.
 Escape character is '^]'.
 2001-06-19T21:31:11Z
 Connection closed by foreign host.
 &prompt.user;</screen>
 
           <para>Again, it worked. Will it work using the domain name?
 	    </para>
 
 <screen>&prompt.user; <userinput>telnet r47.bfm.org 13</userinput>
 
 Trying 216.127.220.143...
 Connected to r47.bfm.org.
 Escape character is '^]'.
 2001-06-19T21:31:40Z
 Connection closed by foreign host.
 &prompt.user;</screen>
 
           <para>By the way, <application>telnet</application> prints
 	    the <emphasis>Connection closed by foreign host</emphasis>
 	    message after our daemon has closed the socket. This shows
 	    us that, indeed, using
 	    <function>fclose(client);</function> in our code works as
 	    advertised.</para>
 
         </sect4>
 
       </sect3>
 
     </sect2>
 
   </sect1>
 
   <sect1 id="sockets-helper-functions">
     <title>Helper Functions</title>
 
     <para>FreeBSD C library contains many helper functions for sockets
       programming.  For example, in our sample client we hard coded
       the <hostid role="domainname">time.nist.gov</hostid>
       <acronym>IP</acronym> address. But we do not always know the
       <acronym>IP</acronym> address.  Even if we do, our software is
       more flexible if it allows the user to enter the
       <acronym>IP</acronym> address, or even the domain name.
       </para>
 
     <sect2 id="sockets-gethostbyname">
       <title><function>gethostbyname</function></title>
 
       <para>While there is no way to pass the domain name directly to
         any of the sockets functions, the FreeBSD C library comes with
-        the &man.gethostbyname.3 and &man.gethostbyname2.3 functions,
+        the &man.gethostbyname.3; and &man.gethostbyname2.3; functions,
         declared in <filename>netdb.h</filename>.</para>
 
 <programlisting>
 struct hostent * gethostbyname(const char *name);
 struct hostent * gethostbyname2(const char *name, int af);
 </programlisting>
 
       <para>Both return a pointer to the <varname>hostent</varname>
         structure, with much information about the domain. For our
         purposes, the <varname>h_addr_list[0]</varname> field of the
         structure points at <varname>h_length</varname> bytes of the
         correct address, already stored in the <emphasis>network byte
         order</emphasis>.</para>
 
       <para>This allows us to create a much more flexible&mdash;and
         much more useful&mdash;version of our
         <application>daytime</application> program:</para>
 
 <programlisting>
 /*
  * daytime.c
  *
  * Programmed by G. Adam Stanislav
  * 19 June 2001
  */
 #include &lt;stdio.h&gt;
 #include &lt;string.h&gt;
 #include &lt;sys/types.h&gt;
 #include &lt;sys/socket.h&gt;
 #include &lt;netinet/in.h&gt;
 #include &lt;netdb.h&gt;
 
 int main(int argc, char *argv[]) {
   register int s;
   register int bytes;
   struct sockaddr_in sa;
   struct hostent *he;
   char buf[BUFSIZ+1];
   char *host;
 
   if ((s = socket(PF_INET, SOCK_STREAM, 0)) &lt; 0) {
     perror("socket");
     return 1;
   }
 
   bzero(&amp;sa, sizeof sa);
 
   sa.sin_family = AF_INET;
   sa.sin_port = htons(13);
 
   host = (argc &gt; 1) ? (char *)argv[1] : "time.nist.gov";
 
   if ((he = gethostbyname(host)) == NULL) {
     herror(host);
     return 2;
   }
 
   bcopy(he-&gt;h_addr_list[0],&amp;sa.sin_addr, he-&gt;h_length);
 
   if (connect(s, (struct sockaddr *)&amp;sa, sizeof sa) &lt; 0) {
     perror("connect");
     return 3;
   }
 
   while ((bytes = read(s, buf, BUFSIZ)) &gt; 0)
     write(1, buf, bytes);
 
   close(s);
   return 0;
 }
 </programlisting>
 
       <para>We now can type a domain name (or an <acronym>IP</acronym>
         address, it works both ways) on the command line, and the
         program will try to connect to its
         <emphasis>daytime</emphasis> server. Otherwise, it will still
         default to <hostid
         role="domainname">time.nist.gov</hostid>. However, even in
         this case we will use <function>gethostbyname</function>
         rather than hard coding <hostid
         role="ipaddr">192.43.244.18</hostid>. That way, even if its
         <acronym>IP</acronym> address changes in the future, we will
         still find it.</para>
 
       <para>Since it takes virtually no time to get the time from your
         local server, you could run <application>daytime</application>
         twice in a row: First to get the time from <hostid
         role="domainname">time.nist.gov</hostid>, the second time from
         your own system. You can then compare the results and see how
         exact your system clock is:</para>
 
 <screen>&prompt.user; <userinput>daytime ; daytime localhost</userinput>
 
 
 52080 01-06-20 04:02:33 50 0 0 390.2 UTC(NIST) * 
 2001-06-20T04:02:35Z
 &prompt.user;</screen>
 
       <para>As you can see, my system was two seconds ahead of the
         <acronym>NIST</acronym> time.</para>
 
     </sect2>
 
     <sect2 id="sockets-getservbyname">
       <title><function>getservbyname</function></title>
 
       <para>Sometimes you may not be sure what port a certain service
         uses.  The &man.getservbyname.3; function, also declared in
         <filename>netdb.h</filename> comes in very handy in those
         cases:</para>
 
 <programlisting>
 struct servent * getservbyname(const char *name, const char *proto);
 </programlisting>
 
       <para>The <varname>servent</varname> structure contains the
         <varname>s_port</varname>, which contains the proper port,
         already in <emphasis>network byte order</emphasis>.</para>
 
       <para>Had we not known the correct port for the
         <emphasis>daytime</emphasis> service, we could have found it
         this way:</para>
 
 <programlisting>
   struct servent *se;
   ...
   if ((se = getservbyname("daytime", "tcp")) == NULL {
     fprintf(stderr, "Cannot determine which port to use.\n");
     return 7;
   }
   sa.sin_port = se->s_port;
 </programlisting>
 
       <para>You usually do know the port. But if you are developing a
         new protocol, you may be testing it on an unofficial
         port. Some day, you will register the protocol and its port
         (if nowhere else, at least in your
         <filename>/etc/services</filename>, which is where
         <function>getservbyname</function> looks). Instead of
         returning an error in the above code, you just use the
         temporary port number.  Once you have listed the protocol in
         <filename>/etc/services</filename>, your software will find
         its port without you having to rewrite the code.</para>
 
     </sect2>
 
   </sect1>
 
   <sect1 id="sockets-concurrent-servers">
     <title>Concurrent Servers</title>
 
     <para>Unlike a sequential server, a <emphasis>concurrent
       server</emphasis> has to be able to serve more than one client
       at a time. For example, a <emphasis>chat server</emphasis> may
       be serving a specific client for hours&mdash;it cannot wait till
       it stops serving a client before it serves the next one.</para>
 
     <para>This requires a significant change in our flowchart:</para>
 
     <mediaobject>
       <imageobject>
         <imagedata fileref="sockets/serv2">
       </imageobject>
        
       <textobject>
         <literallayout class="monospaced">+-----------------+
 |  Create Socket  |
 +-----------------+
           |
 +-----------------+
 |    Bind Port    |       Daemon Process
 +-----------------+
           |                 +--------+
           +-------------+--&gt;|  Init  |
           |             |   +--------+
 +-----------------+     |         |
 |        Exit     |     |   +--------+
 +-----------------+     |   | Listen |
                         |   +--------+
                         |         |
                         |   +--------+
                         |   | Accept |
                         |   +--------+
                         |         |       +------------------+
                         |         +------&gt;| Close Top Socket |
                         |         |       +------------------+
                         |   +--------+             |
                         |   | Close  |    +------------------+
                         |   +--------+    |     Serve        |
                         |         |       +------------------+
                         |&lt;--------+                |
                                           +------------------+
                                           | Close Acc Socket |
                             +--------+    +------------------+
                             | Signal |             |
                             +--------+    +------------------+
                                           |      Exit        |
                                           +------------------+</literallayout>
       </textobject>
        
       <textobject>
         <phrase>Concurrent Server</phrase>
       </textobject>
     </mediaobject>
 
     <para>We moved the <emphasis>serve</emphasis> from the
       <emphasis>daemon process</emphasis> to its own <emphasis>server
       process</emphasis>. However, because each child process inherits
       all open files (and a socket is treated just like a file), the
       new process inherits not only the <emphasis><quote>accepted
       handle,</quote></emphasis> i.e., the socket returned by the
       <function>accept</function> call, but also the <emphasis>top
       socket</emphasis>, i.e., the one opened by the top process right
       at the beginning.</para>
 
     <para>However, the <emphasis>server process</emphasis> does not
       need this socket and should <function>close</function> it
       immediately. Similarly, the <emphasis>daemon process</emphasis>
       no longer needs the <emphasis>accepted socket</emphasis>, and
       not only should, but <emphasis>must</emphasis>
       <function>close</function> it&mdash;otherwise, it will run out
       of available <emphasis>file descriptors</emphasis> sooner or
       later.</para>
 
     <para>After the <emphasis>server process</emphasis> is done
       serving, it should close the <emphasis>accepted
       socket</emphasis>. Instead of returning to
       <function>accept</function>, it now exits.
       </para>
 
     <para>Under Unix, a process does not really
       <emphasis>exit</emphasis>. Instead, it
       <emphasis>returns</emphasis> to its parent. Typically, a parent
       process <function>wait</function>s for its child process, and
       obtains a return value. However, our <emphasis>daemon
       process</emphasis> cannot simply stop and wait. That would
       defeat the whole purpose of creating additional processes. But
       if it never does <function>wait</function>, its children will
       become <emphasis>zombies</emphasis>&mdash;no longer functional
       but still roaming around.</para>
 
     <para>For that reason, the <emphasis>daemon process</emphasis>
       needs to set <emphasis>signal handlers</emphasis> in its
       <emphasis>initialize daemon</emphasis> phase. At least a
       <symbol>SIGCHLD</symbol> signal has to be processed, so the
       daemon can remove the zombie return values from the system and
       release the system resources they are taking up.</para>
 
     <para>That is why our flowchart now contains a <emphasis>process
       signals</emphasis> box, which is not connected to any other box.
       By the way, many servers also process <symbol>SIGHUP</symbol>,
       and typically interpret as the signal from the superuser that
       they should reread their configuration files. This allows us to
       change settings without having to kill and restart these
       servers.</para>
 
   </sect1>
 
 </chapter>
diff --git a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
index cefec5c0e4..13afe50808 100644
--- a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
@@ -1,2311 +1,2311 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="tools">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>James</firstname>
 	<surname>Raynard</surname>
 	<contrib>Written by </contrib>
       </author>
     </authorgroup>
     <authorgroup>
       <author>
         <firstname>Murray</firstname>
 	<surname>Stokely</surname>
 	<contrib>Modifications for the Developer's Handbook by </contrib>
       </author>
     </authorgroup>
   </chapterinfo>
   <title>Programming Tools</title>
 
   <sect1><title>Synopsis</title>
 
     <para>This chapter is an introduction to using some of the
       programming tools supplied with FreeBSD, although much of it
       will be applicable to many other versions of Unix.  It does
       <emphasis>not</emphasis> attempt to describe coding in any
       detail.  Most of the chapter assumes little or no previous
       programming knowledge, although it is hoped that most
       programmers will find something of value in it.</para>
 
   </sect1>
 
   <sect1><title>Introduction</title>
   
     <para>FreeBSD offers an excellent development environment.
       Compilers for C, C++, and Fortran and an assembler come with the
       basic system, not to mention a Perl interpreter and classic Unix
       tools such as <command>sed</command> and <command>awk</command>.
       If that is not enough, there are many more compilers and
       interpreters in the Ports collection.  FreeBSD is very
       compatible with standards such as <acronym>POSIX</acronym> and
       <acronym>ANSI</acronym> C, as well with its own BSD heritage, so
       it is possible to write applications that will compile and run
       with little or no modification on a wide range of
       platforms.</para>
 
     <para>However, all this power can be rather overwhelming at first
       if you have never written programs on a Unix platform before.
       This document aims to help you get up and running, without
       getting too deeply into more advanced topics.  The intention is
       that this document should give you enough of the basics to be
       able to make some sense of the documentation.</para>
 
     <para>Most of the document requires little or no knowledge of
       programming, although it does assume a basic competence with
       using Unix and a willingness to learn!</para>
 
   </sect1>
 
   <sect1>
     <title>Introduction to Programming</title>
 
     <para>A program is a set of instructions that tell the computer to
       do various things; sometimes the instruction it has to perform
       depends on what happened when it performed a previous
       instruction.  This section gives an overview of the two main
       ways in which you can give these instructions, or
       <quote>commands</quote> as they are usually called.  One way
       uses an <firstterm>interpreter</firstterm>, the other a
       <firstterm>compiler</firstterm>.  As human languages are too
       difficult for a computer to understand in an unambiguous way,
       commands are usually written in one or other languages specially
       designed for the purpose.</para>
 
     <sect2>
       <title>Interpreters</title>
 
       <para>With an interpreter, the language comes as an environment,
 	where you type in commands at a prompt and the environment
 	executes them for you.  For more complicated programs, you can
 	type the commands into a file and get the interpreter to load
 	the file and execute the commands in it.  If anything goes
 	wrong, many interpreters will drop you into a debugger to help
 	you track down the problem.</para>
 
       <para>The advantage of this is that you can see the results of
 	your commands immediately, and mistakes can be corrected
 	readily.  The biggest disadvantage comes when you want to
 	share your programs with someone.  They must have the same
 	interpreter, or you must have some way of giving it to them,
 	and they need to understand how to use it.  Also users may not
 	appreciate being thrown into a debugger if they press the
 	wrong key! From a performance point of view, interpreters can
 	use up a lot of memory, and generally do not generate code as
 	efficiently as compilers.</para>
 
       <para>In my opinion, interpreted languages are the best way to
 	start if you have not done any programming before.  This kind
 	of environment is typically found with languages like Lisp,
 	Smalltalk, Perl and Basic.  It could also be argued that the
 	Unix shell (<command>sh</command>, <command>csh</command>) is itself an
 	interpreter, and many people do in fact write shell
 	<quote>scripts</quote> to help with various
 	<quote>housekeeping</quote> tasks on their machine.  Indeed, part
 	of the original Unix philosophy was to provide lots of small
 	utility programs that could be linked together in shell
 	scripts to perform useful tasks.</para>
     </sect2>
 
     <sect2>
       <title>Interpreters available with FreeBSD</title>
 
       <para>Here is a list of interpreters that are available as
 	<ulink
 	  URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">FreeBSD
 	  packages</ulink>, with a brief discussion of some of the
 	more popular interpreted languages.</para>
 
       <para>To get one of these packages, all you need to do is to
 	click on the hotlink for the package, then run</para>
 
       <screen>&prompt.root; <userinput>pkg_add <replaceable>package name</></userinput></screen>
 
       <para>as root.  Obviously, you will need to have a fully
 	functional FreeBSD 2.1.0 or later system for the package to
 	work!</para>
 
       <variablelist>
 	<varlistentry>
 	  <term><acronym>BASIC</acronym></term>
 
 	  <listitem>
 	    <para>Short for Beginner's All-purpose Symbolic
 	      Instruction Code.  Developed in the 1950s for teaching
 	      University students to program and provided with every
 	      self-respecting personal computer in the 1980s,
 	      <acronym>BASIC</acronym> has been the first programming
 	      language for many programmers.  It is also the foundation
 	      for Visual Basic.</para>
 
 	    <para>The <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/bwbasic.tgz">Bywater
 		Basic Interpreter</ulink> and the <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/pbasic.tgz">Phil
 		Cockroft's Basic Interpreter</ulink> (formerly Rabbit
 	      Basic) are available as <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">FreeBSD
 		packages</ulink>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Lisp</term>
 
 	  <listitem>
 	    <para>A language that was developed in the late 1950s as
 	      an alternative to the <quote>number-crunching</quote>
 	      languages that were popular at the time.  Instead of
 	      being based on numbers, Lisp is based on lists; in fact
 	      the name is short for <quote>List Processing</quote>.
 	      Very popular in <acronym>AI</acronym> (Artificial Intelligence)
 	      circles.</para>
 
 	    <para>Lisp is an extremely powerful and sophisticated
 	      language, but can be rather large and unwieldy.</para>
 
 	    <para>FreeBSD has <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/gcl-2.0.tgz">GNU
 		Common Lisp</ulink> available as a package.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Perl</term>
 
 	  <listitem>
 	    <para>Very popular with system administrators for writing
 	      scripts; also often used on World Wide Web servers for
 	      writing <acronym>CGI</acronym> scripts.</para>
 
 	    <para>Perl is installed as <command>/usr/bin/perl</command> in the
 	      FreeBSD base system.</para>
 
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Scheme</term>
 
 	  <listitem>
 	    <para>A dialect of Lisp that is rather more compact and
 	      cleaner than Common Lisp.  Popular in Universities as it
 	      is simple enough to teach to undergraduates as a first
 	      language, while it has a high enough level of
 	      abstraction to be used in research work.</para>
 
 	    <para>FreeBSD has packages of the <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/elk.tgz">Elk
 		Scheme Interpreter</ulink>, the <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/mit-scheme.tgz">MIT
 		Scheme Interpreter</ulink> and the <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/scm.tgz">SCM
 		Scheme Interpreter</ulink>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Icon</term>
 
 	  <listitem>
 	    <para><ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/icon.tgz">The
 		Icon Programming Language</ulink>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Logo</term>
 
 	  <listitem>
 	    <para><ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/ucblogo.tgz">Brian
 		Harvey's LOGO Interpreter</ulink>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Python</term>
 
 	  <listitem>
 	    <para><ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/python.tgz">The
 		Python Object-Oriented Programming
 		Language</ulink></para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2>
       <title>Compilers</title>
 
       <para>Compilers are rather different.  First of all, you write
 	your code in a file (or files) using an editor.  You then run
 	the compiler and see if it accepts your program.  If it did
 	not compile, grit your teeth and go back to the editor; if it
 	did compile and gave you a program, you can run it either at a
 	shell command prompt or in a debugger to see if it works
 	properly.
 	
 	<footnote>
 	  <para>If you run it in the shell, you may get a core
 	    dump.</para>
 	</footnote></para>
 
       <para>Obviously, this is not quite as direct as using an
 	interpreter.  However it allows you to do a lot of things
 	which are very difficult or even impossible with an
 	interpreter, such as writing code which interacts closely with
 	the operating system&mdash;or even writing your own operating
 	system! It is also useful if you need to write very efficient
 	code, as the compiler can take its time and optimise the code,
 	which would not be acceptable in an interpreter.  And
 	distributing a program written for a compiler is usually more
 	straightforward than one written for an interpreter&mdash;you
 	can just give them a copy of the executable, assuming they
 	have the same operating system as you.</para>
 
       <para>Compiled languages include Pascal, C and C++.  C and C++
 	are rather unforgiving languages, and best suited to more
 	experienced programmers; Pascal, on the other hand, was
 	designed as an educational language, and is quite a good
 	language to start with.  FreeBSD does not include Pascal
 	support in the base system, but the GNU Pascal Compiler (gpc)
 	is available in the ports collection.</para>
 
       <para>As the edit-compile-run-debug cycle is rather tedious when
 	using separate programs, many commercial compiler makers have
 	produced Integrated Development Environments
 	(<acronym>IDE</acronym>s for short).  FreeBSD does not include
 	an IDE in the base system, but <filename role="package">devel/kdevelop</filename> is
 	available in the ports tree and many use
 	<application>Emacs</application> for this purpose.  Using
 	<application>Emacs</application> as an IDE is discussed in
 	<xref linkend="emacs">.</para>
     </sect2>
 
 
   </sect1>
 
 
   <sect1>
     <title>Compiling with <command>cc</command></title>
 
     <para>This section deals only with the GNU compiler for C and C++,
       since that comes with the base FreeBSD system.  It can be
       invoked by either <command>cc</command> or <command>gcc</command>.  The
       details of producing a program with an interpreter vary
       considerably between interpreters, and are usually well covered
       in the documentation and on-line help for the
       interpreter.</para>
 
     <para>Once you have written your masterpiece, the next step is to
       convert it into something that will (hopefully!) run on FreeBSD.
       This usually involves several steps, each of which is done by a
       separate program.</para>
 
     <procedure>
       <step>
 	<para>Pre-process your source code to remove comments and do
 	  other tricks like expanding macros in C.</para>
       </step>
 
       <step>
 	<para>Check the syntax of your code to see if you have obeyed
 	  the rules of the language.  If you have not, it will
 	  complain!</para>
       </step>
 
       <step>
 	<para>Convert the source code into assembly
 	  language&mdash;this is very close to machine code, but still
 	  understandable by humans.  Allegedly.
 
 	  <footnote>
 	    <para>To be strictly accurate, <command>cc</command> converts the
 	      source code into its own, machine-independent
 	      <firstterm>p-code</firstterm> instead of assembly language at
 	      this stage.</para>
 	  </footnote></para>
       </step>
 
       <step>
 	<para>Convert the assembly language into machine
 	  code&mdash;yep, we are talking bits and bytes, ones and
 	  zeros here.</para>
       </step>
 
       <step>
 	<para>Check that you have used things like functions and
 	  global variables in a consistent way.  For example, if you
 	  have called a non-existent function, it will
 	  complain.</para>
       </step>
 
       <step>
 	<para>If you are trying to produce an executable from several
 	  source code files, work out how to fit them all
 	  together.</para>
       </step>
 
       <step>
 	<para>Work out how to produce something that the system's
 	  run-time loader will be able to load into memory and
 	  run.</para>
       </step>
 
       <step>
 	<para>Finally, write the executable on the file system.</para>
       </step>
     </procedure>
 
     <para>The word <firstterm>compiling</firstterm> is often used to refer to
       just steps 1 to 4&mdash;the others are referred to as
       <firstterm>linking</firstterm>.  Sometimes step 1 is referred to as
       <firstterm>pre-processing</firstterm> and steps 3-4 as
       <firstterm>assembling</firstterm>.</para>
 
     <para>Fortunately, almost all this detail is hidden from you, as
       <command>cc</command> is a front end that manages calling all these
       programs with the right arguments for you; simply typing</para>
 
     <screen>&prompt.user; <userinput>cc foobar.c</userinput></screen>
 
     <para>will cause <filename>foobar.c</filename> to be compiled by all the
       steps above.  If you have more than one file to compile, just do
       something like</para>
 
     <screen>&prompt.user; <userinput>cc foo.c bar.c</userinput></screen>
 
     <para>Note that the syntax checking is just that&mdash;checking
       the syntax.  It will not check for any logical mistakes you may
       have made, like putting the program into an infinite loop, or
       using a bubble sort when you meant to use a binary
       sort.
 
       <footnote>
 	<para>In case you did not know, a binary sort is an efficient
 	  way of sorting things into order and a bubble sort
 	  is not.</para>
       </footnote></para>
 
     <para>There are lots and lots of options for <command>cc</command>, which
       are all in the manual page.  Here are a few of the most important
       ones, with examples of how to use them.</para>
 
     <variablelist>
       <varlistentry>
 	<term><option>-o <replaceable>filename</replaceable></option></term>
 
 	<listitem>
 	  <para>The output name of the file.  If you do not use this
 	    option, <command>cc</command> will produce an executable called
 	    <filename>a.out</filename>.
 
 	    <footnote>
 	      <para>The reasons for this are buried in the mists of
 		history.</para>
 	    </footnote></para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc foobar.c</userinput>               <lineannotation>executable is <filename>a.out</filename></lineannotation>
 &prompt.user; <userinput>cc -o foobar foobar.c</userinput>     <lineannotation>executable is <filename>foobar</filename></lineannotation>
 	    </screen>
 	  </informalexample>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-c</option></term>
 	
 	<listitem>
 	  <para>Just compile the file, do not link it.  Useful for toy
 	    programs where you just want to check the syntax, or if
 	    you are using a <filename>Makefile</filename>.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -c foobar.c</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>This will produce an <firstterm>object file</firstterm> (not an
 	    executable) called <filename>foobar.o</filename>.  This
 	    can be linked together with other object files into an
 	    executable.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-g</option></term>
 
 	<listitem>
 	  <para>Create a debug version of the executable.  This makes
 	    the compiler put information into the executable about
 	    which line of which source file corresponds to which
 	    function call.  A debugger can use this information to show
 	    the source code as you step through the program, which is
 	    <emphasis>very</emphasis> useful; the disadvantage is that
 	    all this extra information makes the program much bigger.
 	    Normally, you compile with <option>-g</option> while you
 	    are developing a program and then compile a <quote>release
 	      version</quote> without <option>-g</option> when you are
 	    satisfied it works properly.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -g foobar.c</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>This will produce a debug version of the
 	    program.
 
 	    <footnote>
 	      <para>Note, we did not use the <option>-o</option> flag
 		to specify the executable name, so we will get an
 		executable called <filename>a.out</filename>.
 		Producing a debug version called
 		<filename>foobar</filename> is left as an exercise for
 		the reader!</para>
 	    </footnote></para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-O</option></term>
 
 	<listitem>
 	  <para>Create an optimised version of the executable.  The
 	    compiler performs various clever tricks to try and produce
 	    an executable that runs faster than normal.  You can add a
 	    number after the <option>-O</option> to specify a higher
 	    level of optimisation, but this often exposes bugs in the
 	    compiler's optimiser.  For instance, the version of
 	    <command>cc</command> that comes with the 2.1.0 release of
 	    FreeBSD is known to produce bad code with the
 	    <option>-O2</option> option in some circumstances.</para>
 
 	  <para>Optimisation is usually only turned on when compiling
 	    a release version.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>This will produce an optimised version of
 	    <filename>foobar</filename>.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>The following three flags will force <command>cc</command>
       to check that your code complies to the relevant international
       standard, often referred to as the <acronym>ANSI</acronym>
       standard, though strictly speaking it is an
       <acronym>ISO</acronym> standard.</para>
 
     <variablelist>
       <varlistentry>
 	<term><option>-Wall</option></term>
 
 	<listitem>
 	  <para>Enable all the warnings which the authors of
 	    <command>cc</command> believe are worthwhile.  Despite the
 	    name, it will not enable all the warnings
 	    <command>cc</command> is capable of.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-ansi</option></term>
 
 	<listitem>
 	  <para>Turn off most, but not all, of the
 	    non-<acronym>ANSI</acronym>&nbsp;C features provided by
 	    <command>cc</command>.  Despite the name, it does not
 	    guarantee strictly that your code will comply to the
 	    standard.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-pedantic</option></term>
 
 	<listitem>
 	  <para>Turn off <emphasis>all</emphasis>
 	    <command>cc</command>'s non-<acronym>ANSI</acronym>&nbsp;C
 	    features.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>Without these flags, <command>cc</command> will allow you to
       use some of its non-standard extensions to the standard.  Some
       of these are very useful, but will not work with other
       compilers&mdash;in fact, one of the main aims of the standard is
       to allow people to write code that will work with any compiler
       on any system.  This is known as <firstterm>portable
 	code</firstterm>.</para>
 
     <para>Generally, you should try to make your code as portable as
       possible, as otherwise you may have to completely rewrite the
       program later to get it to work somewhere else&mdash;and who
       knows what you may be using in a few years time?</para>
 
     <informalexample>
       <screen>&prompt.user; <userinput>cc -Wall -ansi -pedantic -o foobar foobar.c</userinput></screen>
     </informalexample>
 
     <para>This will produce an executable <filename>foobar</filename>
       after checking <filename>foobar.c</filename> for standard
       compliance.</para>
 
     <variablelist>
       <varlistentry>
 	<term><option>-l<replaceable>library</replaceable></option></term>
 
 	<listitem>
 	  <para>Specify a function library to be used during when
 	    linking.</para>
 
 	  <para>The most common example of this is when compiling a
 	    program that uses some of the mathematical functions in C.
 	    Unlike most other platforms, these are in a separate
 	    library from the standard C one and you have to tell the
 	    compiler to add it.</para>
 
 	  <para>The rule is that if the library is called
 	    <filename>lib<replaceable>something</replaceable>.a</filename>,
 	    you give <command>cc</command> the argument
 	    <option>-l<replaceable>something</replaceable></option>.
 	    For example, the math library is
 	    <filename>libm.a</filename>, so you give
 	    <command>cc</command> the argument <option>-lm</option>.
 	    A common <quote>gotcha</quote> with the math library is
 	    that it has to be the last library on the command
 	    line.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>This will link the math library functions into
 	    <filename>foobar</filename>.</para>
 
 	  <para>If you are compiling C++ code, you need to add
 	    <option>-lg++</option>, or <option>-lstdc++</option> if
 	    you are using FreeBSD 2.2 or later, to the command line
 	    argument to link the C++ library functions.
 	    Alternatively, you can run <command>c++</command> instead
 	    of <command>cc</command>, which does this for you.
 	    <command>c++</command> can also be invoked as
 	    <command>g++</command> on FreeBSD.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -o foobar foobar.cc -lg++</userinput>     <lineannotation>For FreeBSD 2.1.6 and earlier</lineannotation>
 &prompt.user; <userinput>cc -o foobar foobar.cc -lstdc++</userinput>  <lineannotation>For FreeBSD 2.2 and later</lineannotation>
 &prompt.user; <userinput>c++ -o foobar foobar.cc</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>Each of these will both produce an executable
 	    <filename>foobar</filename> from the C++ source file
 	    <filename>foobar.cc</filename>.  Note that, on Unix
 	    systems, C++ source files traditionally end in
 	    <filename>.C</filename>, <filename>.cxx</filename> or
 	    <filename>.cc</filename>, rather than the
 	    MS-DOS style
 	    <filename>.cpp</filename> (which was already used for
 	    something else).  <command>gcc</command> used to rely on
 	    this to work out what kind of compiler to use on the
 	    source file; however, this restriction no longer applies,
 	    so you may now call your C++ files
 	    <filename>.cpp</filename> with impunity!</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <sect2>
       <title>Common <command>cc</command> Queries and Problems</title>
 
       <qandaset>
 	<qandaentry>
 	  <question>
 	    <para>I am trying to write a program which uses the
 	      <function>sin()</function> function and I get an error
 	      like this.  What does it mean?</para>
 
 	    <informalexample>
 	      <screen>/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment
 	      </screen>
 	    </informalexample>
 	  </question>
 
 	  <answer>
 	    <para>When using mathematical functions like
 	      <function>sin()</function>, you have to tell
 	      <command>cc</command> to link in the math library, like
 	      so:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput>
 	      </screen>
 	    </informalexample>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>All right, I wrote this simple program to practice
 	      using <option>-lm</option>.  All it does is raise 2.1 to
 	      the power of 6.</para>
 
 	    <informalexample>
 	      <programlisting>#include &lt;stdio.h&gt;
 
 int main() {
 	float f;
 
 	f = pow(2.1, 6);
 	printf("2.1 ^ 6 = %f\n", f);
 	return 0;
 }
 	      </programlisting>
 	    </informalexample>
 
 	    <para>and I compiled it as:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>cc temp.c -lm</userinput>
 	      </screen>
 	    </informalexample>
 
 	    <para>like you said I should, but I get this when I run
 	      it:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>./a.out</userinput>
 2.1 ^ 6 = 1023.000000
 	      </screen>
 	    </informalexample>
 
 	    <para>This is <emphasis>not</emphasis> the right answer!
 	      What is going on?</para>
 	  </question>
 
 	  <answer>
 	    <para>When the compiler sees you call a function, it
 	      checks if it has already seen a prototype for it.  If it
 	      has not, it assumes the function returns an
 	      <type>int</type>, which is definitely not what you want
 	      here.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>So how do I fix this?</para>
 	  </question>
 
 	  <answer>
 	    <para>The prototypes for the mathematical functions are in
 	      <filename>math.h</filename>.  If you include this file,
 	      the compiler will be able to find the prototype and it
 	      will stop doing strange things to your
 	      calculation!</para>
 
 	    <informalexample>
 	      <programlisting>#include &lt;math.h&gt;
 #include &lt;stdio.h&gt;
 
 int main() {
 ...
 	      </programlisting>
 	    </informalexample>
 
 	    <para>After recompiling it as you did before, run
 	      it:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>./a.out</userinput>
 2.1 ^ 6 = 85.766121
 	      </screen>
 	    </informalexample>
 
 	    <para>If you are using any of the mathematical functions,
 	      <emphasis>always</emphasis> include
 	      <filename>math.h</filename> and remember to link in the
 	      math library.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>I compiled a file called
 	      <filename>foobar.c</filename> and I cannot find an
 	      executable called <filename>foobar</filename>.  Where's
 	      it gone?</para>
 	  </question>
 
 	  <answer>
 	    <para>Remember, <command>cc</command> will call the
 	      executable <filename>a.out</filename> unless you tell it
 	      differently.  Use the
 	      <option>-o&nbsp;<replaceable>filename</replaceable></option>
 	      option:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>cc -o foobar foobar.c</userinput>
 	      </screen>
 	    </informalexample>
 	  </answer>
 	</qandaentry>
 	
 	<qandaentry>
 	  <question>
 	    <para>OK, I have an executable called
 	      <filename>foobar</filename>, I can see it when I run
 	      <command>ls</command>, but when I type in
 	      <command>foobar</command> at the command prompt it tells
 	      me there is no such file.  Why can it not find
 	      it?</para>
 	  </question>
 
 	  <answer>
 	    <para>Unlike MS-DOS, Unix does not
 	      look in the current directory when it is trying to find
 	      out which executable you want it to run, unless you tell
 	      it to.  Either type <command>./foobar</command>, which
 	      means <quote>run the file called
 		<filename>foobar</filename> in the current
 		directory</quote>, or change your <envar>PATH</envar>
 	      environment
 	      variable so that it looks something like</para>
 
 	    <informalexample>
 	      <screen>bin:/usr/bin:/usr/local/bin:.
 	      </screen>
 	    </informalexample>
 
 	    <para>The dot at the end means <quote>look in the current
 		directory if it is not in any of the
 		others</quote>.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>I called my executable <filename>test</filename>,
 	      but nothing happens when I run it.  What is going
 	      on?</para>
 	  </question>
 
 	  <answer>
 	    <para>Most Unix systems have a program called
 	      <command>test</command> in <filename>/usr/bin</filename>
 	      and the shell is picking that one up before it gets to
 	      checking the current directory.  Either type:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>./test</userinput>
 	      </screen>
 	    </informalexample>
 
 	    <para>or choose a better name for your program!</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>I compiled my program and it seemed to run all right
 	      at first, then there was an error and it said something
 	      about <errorname>core dumped</errorname>.  What does that
 	      mean?</para>
 	  </question>
 
 	  <answer>
 	    <para>The name <firstterm>core dump</firstterm> dates back
 	      to the very early days of Unix, when the machines used
 	      core memory for storing data.  Basically, if the program
 	      failed under certain conditions, the system would write
 	      the contents of core memory to disk in a file called
 	      <filename>core</filename>, which the programmer could
 	      then pore over to find out what went wrong.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Fascinating stuff, but what I am supposed to do
 	      now?</para>
 	  </question>
 
 	  <answer>
 	    <para>Use <command>gdb</command> to analyse the core (see
 	      <xref linkend="debugging">).</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>When my program dumped core, it said something about
 	      a <errorname>segmentation fault</errorname>.  What is
 	      that?</para>
 	  </question>
 
 	  <answer>
 	    <para>This basically means that your program tried to
 	      perform some sort of illegal operation on memory; Unix
 	      is designed to protect the operating system and other
 	      programs from rogue programs.</para>
 
 	    <para>Common causes for this are:</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para>Trying to write to a <symbol>NULL</symbol>
 		  pointer, eg</para>
 
 		<programlisting>char *foo = NULL;
 strcpy(foo, "bang!");
 		</programlisting>
 	      </listitem>
 
 	      <listitem>
 		<para>Using a pointer that has not been initialised,
 		  eg</para>
 
 		<programlisting>char *foo;
 strcpy(foo, "bang!");
 		</programlisting>
 
 		<para>The pointer will have some random value that,
 		  with luck, will point into an area of memory that
 		  is not available to your program and the kernel will
 		  kill your program before it can do any damage.  If
 		  you are unlucky, it will point somewhere inside your
 		  own program and corrupt one of your data structures,
 		  causing the program to fail mysteriously.</para>
 	      </listitem>
 
 	      <listitem>
 		<para>Trying to access past the end of an array,
 		  eg</para>
 
 		<programlisting>int bar[20];
 bar[27] = 6;
 		</programlisting>
 	      </listitem>
 
 	      <listitem>
 		<para>Trying to store something in read-only memory,
 		  eg</para>
 
 		<programlisting>char *foo = "My string";
 strcpy(foo, "bang!");
 		</programlisting>
 
 		<para>Unix compilers often put string literals like
 		  <literal>"My string"</literal> into read-only areas
 		  of memory.</para>
 	      </listitem>
 
 	      <listitem>
 		<para>Doing naughty things with
 		  <function>malloc()</function> and
 		  <function>free()</function>, eg</para>
 
 		<programlisting>char bar[80];
 free(bar);
 		</programlisting>
 
 		<para>or</para>
 
 		<programlisting>char *foo = malloc(27);
 free(foo);
 free(foo);
 		</programlisting>
 	      </listitem>
 	    </itemizedlist>
 
 	    <para>Making one of these mistakes will not always lead to
 	      an error, but they are always bad practice.  Some
 	      systems and compilers are more tolerant than others,
 	      which is why programs that ran well on one system can
 	      crash when you try them on an another.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Sometimes when I get a core dump it says
 	      <errorname>bus error</errorname>.  It says in my Unix
 	      book that this means a hardware problem, but the
 	      computer still seems to be working.  Is this
 	      true?</para>
 	  </question>
 
 	  <answer>
 	    <para>No, fortunately not (unless of course you really do
 	      have a hardware problem&hellip;).  This is usually
 	      another way of saying that you accessed memory in a way
 	      you should not have.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>This dumping core business sounds as though it could
 	      be quite useful, if I can make it happen when I want to.
 	      Can I do this, or do I have to wait until there is an
 	      error?</para>
 	  </question>
 
 	  <answer>
 	    <para>Yes, just go to another console or xterm, do</para>
 
 	    <screen>&prompt.user; <userinput>ps</userinput>
 	    </screen>
 
 	    <para>to find out the process ID of your program, and
 	      do</para>
 
 	    <screen>&prompt.user; <userinput>kill -ABRT <replaceable>pid</replaceable></userinput>
 	    </screen>
 
 	    <para>where
 	      <parameter><replaceable>pid</replaceable></parameter> is
 	      the process ID you looked up.</para>
 
 	    <para>This is useful if your program has got stuck in an
 	      infinite loop, for instance.  If your program happens to
 	      trap <symbol>SIGABRT</symbol>, there are several other
 	      signals which have a similar effect.</para>
 
 	    <para>Alternatively, you can create a core dump from
 	      inside your program, by calling the
 	      <function>abort()</function> function. See the man page
 	      of &man.abort.3; to learn more.</para>
 
             <para>If you want to create a core dump from outside your
               program, but do not want the process to terminate, you
               can use the <command>gcore</command> program. See the
-              man page of &man.gcore.1 for more information.</para>
+              man page of &man.gcore.1; for more information.</para>
 
 	  </answer>
 	</qandaentry>
       </qandaset>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Make</title>
 
     <sect2>
       <title>What is <command>make</command>?</title>
 
       <para>When you are working on a simple program with only one or
 	two source files, typing in</para>
 
       <screen>&prompt.user; <userinput>cc file1.c file2.c</userinput></screen>
 
       <para>is not too bad, but it quickly becomes very tedious when
 	there are several files&mdash;and it can take a while to
 	compile, too.</para>
 
       <para>One way to get around this is to use object files and only
 	recompile the source file if the source code has changed.  So
 	we could have something like:</para>
 
-      <screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> &hellip; <userinput>file37.c</userinput> &hellip</screen>
+      <screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> &hellip; <userinput>file37.c</userinput> &hellip;</screen>
 
       <para>if we had changed <filename>file37.c</filename>, but not any
 	of the others, since the last time we compiled.  This may
 	speed up the compilation quite a bit, but does not solve the
 	typing problem.</para>
 
       <para>Or we could write a shell script to solve the typing
 	problem, but it would have to re-compile everything, making it
 	very inefficient on a large project.</para>
 
       <para>What happens if we have hundreds of source files lying
 	about? What if we are working in a team with other people who
 	forget to tell us when they have changed one of their source
 	files that we use?</para>
 
       <para>Perhaps we could put the two solutions together and write
 	something like a shell script that would contain some kind of
 	magic rule saying when a source file needs compiling.  Now all
 	we need now is a program that can understand these rules, as
 	it is a bit too complicated for the shell.</para>
 
       <para>This program is called <command>make</command>.  It reads
 	in a file, called a <firstterm>makefile</firstterm>, that
 	tells it how different files depend on each other, and works
 	out which files need to be re-compiled and which ones do not.
 	For example, a rule could say something like <quote>if
 	  <filename>fromboz.o</filename> is older than
 	  <filename>fromboz.c</filename>, that means someone must have
 	  changed <filename>fromboz.c</filename>, so it needs to be
 	  re-compiled.</quote> The makefile also has rules telling
 	make <emphasis>how</emphasis> to re-compile the source file,
 	making it a much more powerful tool.</para>
 
       <para>Makefiles are typically kept in the same directory as the
 	source they apply to, and can be called
 	<filename>makefile</filename>, <filename>Makefile</filename>
 	or <filename>MAKEFILE</filename>.  Most programmers use the
 	name <filename>Makefile</filename>, as this puts it near the
 	top of a directory listing, where it can easily be
 	seen.
 
 	<footnote>
 	  <para>They do not use the <filename>MAKEFILE</filename> form
 	    as block capitals are often used for documentation files
 	    like <filename>README</filename>.</para>
 	</footnote></para>
     </sect2>
 
     <sect2>
       <title>Example of using <command>make</command></title>
 
       <para>Here is a very simple make file:</para>
 
       <programlisting>foo: foo.c
 	cc -o foo foo.c</programlisting>
 
       <para>It consists of two lines, a dependency line and a creation
 	line.</para>
 
       <para>The dependency line here consists of the name of the
 	program (known as the <firstterm>target</firstterm>), followed
 	by a colon, then whitespace, then the name of the source file.
 	When <command>make</command> reads this line, it looks to see
 	if <filename>foo</filename> exists; if it exists, it compares
 	the time <filename>foo</filename> was last modified to the
 	time <filename>foo.c</filename> was last modified.  If
 	<filename>foo</filename> does not exist, or is older than
 	<filename>foo.c</filename>, it then looks at the creation line
 	to find out what to do.  In other words, this is the rule for
 	working out when <filename>foo.c</filename> needs to be
 	re-compiled.</para>
 
       <para>The creation line starts with a <token>tab</token> (press
 	the <keycap>tab</keycap> key) and then the command you would
 	type to create <filename>foo</filename> if you were doing it
 	at a command prompt.  If <filename>foo</filename> is out of
 	date, or does not exist, <command>make</command> then executes
 	this command to create it.  In other words, this is the rule
 	which tells make how to re-compile
 	<filename>foo.c</filename>.</para>
 
       <para>So, when you type <userinput>make</userinput>, it will
 	make sure that <filename>foo</filename> is up to date with
 	respect to your latest changes to <filename>foo.c</filename>.
 	This principle can be extended to
 	<filename>Makefile</filename>s with hundreds of
 	targets&mdash;in fact, on FreeBSD, it is possible to compile
 	the entire operating system just by typing <userinput>make
 	  world</userinput> in the appropriate directory!</para>
 
       <para>Another useful property of makefiles is that the targets
 	do not have to be programs.  For instance, we could have a make
 	file that looks like this:</para>
 
       <programlisting>foo: foo.c
 	cc -o foo foo.c
 
 install:
 	cp foo /home/me</programlisting>
 
       <para>We can tell make which target we want to make by
 	typing:</para>
 
       <screen>&prompt.user; <userinput>make <replaceable>target</replaceable></userinput></screen>
 
       <para><command>make</command> will then only look at that target
 	and ignore any others.  For example, if we type
 	<userinput>make foo</userinput> with the makefile above, make
 	will ignore the <maketarget>install</maketarget> target.</para>
 
       <para>If we just type <userinput>make</userinput> on its own,
 	make will always look at the first target and then stop
 	without looking at any others.  So if we typed
 	<userinput>make</userinput> here, it will just go to the
 	<maketarget>foo</maketarget> target, re-compile
 	<filename>foo</filename> if necessary, and then stop without
 	going on to the <maketarget>install</maketarget> target.</para>
 
       <para>Notice that the <maketarget>install</maketarget> target does not
 	actually depend on anything! This means that the command on
 	the following line is always executed when we try to make that
 	target by typing <userinput>make install</userinput>.  In this
 	case, it will copy <filename>foo</filename> into the user's
 	home directory.  This is often used by application makefiles,
 	so that the application can be installed in the correct
 	directory when it has been correctly compiled.</para>
 
       <para>This is a slightly confusing subject to try and explain.
 	If you do not quite understand how <command>make</command>
 	works, the best thing to do is to write a simple program like
 	<quote>hello world</quote> and a make file like the one above
 	and experiment.  Then progress to using more than one source
 	file, or having the source file include a header file.  The
 	<command>touch</command> command is very useful here&mdash;it
 	changes the date on a file without you having to edit
 	it.</para>
     </sect2>
 
     <sect2>
       <title>Make and include-files</title>
 
       <para>C code often starts with a list of files to include, for
 	example stdio.h. Some of these files are system-include
 	files, some of them are from the project you are now working
 	on:
       </para>
 
       <programlisting>#include &lt;stdio.h&gt;
 #include "foo.h"
 
 int main(....</programlisting>
 
       <para>To make sure that this file is recompiled the moment
         <filename>foo.h</filename> is changed, you have to add it in
         your <filename>Makefile</filename>:</para>
 
       <programlisting>foo: foo.c foo.h</programlisting>
 
       <para>The moment your project is getting bigger and you have
 	more and more own include-files to maintain, it will be a
 	pain to keep track of all include files and the files which
 	are depending on it. If you change an include-file but
 	forget to recompile all the files which are depending on
 	it, the results will be devastating. <command>gcc</command>
 	has an option to analyze your files and to produce a list
 	of include-files and their dependencies: <option>-MM</option>.
       </para>
 
       <para>If you add this to your Makefile:</para>
 
       <programlisting>depend:
 	gcc -E -MM *.c &gt; .depend</programlisting>
 
       <para>and run <userinput>make depend</userinput>, the file
 	<filename>.depend</filename> will appear with a list of
 	object-files, C-files and the include-files:</para>
 
       <programlisting>foo.o: foo.c foo.h</programlisting>
 
       <para>If you change <filename>foo.h</filename>, next time
 	you run <command>make</command> all files depending on
 	<filename>foo.h</filename> will be recompiled.</para>
 
       <para>Do not forget to run <command>make depend</command> each
         time you add an include-file to one of your files.</para>
     </sect2>
 
     <sect2>
       <title>FreeBSD Makefiles</title>
 
       <para>Makefiles can be rather complicated to write.  Fortunately,
 	BSD-based systems like FreeBSD come with some very powerful
 	ones as part of the system.  One very good example of this is
 	the FreeBSD ports system.  Here is the essential part of a
 	typical ports <filename>Makefile</filename>:</para>
 
       <programlisting>MASTER_SITES=   ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/
 DISTFILES=      scheme-microcode+dist-7.3-freebsd.tgz
 
 .include &lt;bsd.port.mk&gt;</programlisting>
 
       <para>Now, if we go to the directory for this port and type
 	<userinput>make</userinput>, the following happens:</para>
 
       <procedure>
 	<step>
 	  <para>A check is made to see if the source code for this
 	    port is already on the system.</para>
 	</step>
 
 	<step>
 	  <para>If it is not, an FTP connection to the URL in
 	    <symbol>MASTER_SITES</symbol> is set up to download the
 	    source.</para>
 	</step>
 
 	<step>
 	  <para>The checksum for the source is calculated and compared
 	    it with one for a known, good, copy of the source.  This
 	    is to make sure that the source was not corrupted while in
 	    transit.</para>
 	</step>
 
 	<step>
 	  <para>Any changes required to make the source work on
 	    FreeBSD are applied&mdash;this is known as
 	    <firstterm>patching</firstterm>.</para>
 	</step>
 
 	<step>
 	  <para>Any special configuration needed for the source is
 	    done.  (Many Unix program distributions try to work out
 	    which version of Unix they are being compiled on and which
 	    optional Unix features are present&mdash;this is where
 	    they are given the information in the FreeBSD ports
 	    scenario).</para>
 	</step>
 
 	<step>
 	  <para>The source code for the program is compiled.  In
 	    effect, we change to the directory where the source was
 	    unpacked and do <command>make</command>&mdash;the
 	    program's own make file has the necessary information to
 	    build the program.</para>
 	</step>
 
 	<step>
 	  <para>We now have a compiled version of the program.  If we
 	    wish, we can test it now; when we feel confident about the
 	    program, we can type <userinput>make install</userinput>.
 	    This will cause the program and any supporting files it
 	    needs to be copied into the correct location; an entry is
 	    also made into a <database>package database</database>, so
 	    that the port can easily be uninstalled later if we change
 	    our mind about it.</para>
 	</step>
       </procedure>
 
       <para>Now I think you will agree that is rather impressive for a
 	four line script!</para>
 
       <para>The secret lies in the last line, which tells
 	<command>make</command> to look in the system makefile called
 	<filename>bsd.port.mk</filename>.  It is easy to overlook this
 	line, but this is where all the clever stuff comes
 	from&mdash;someone has written a makefile that tells
 	<command>make</command> to do all the things above (plus a
 	couple of other things I did not mention, including handling
 	any errors that may occur) and anyone can get access to that
 	just by putting a single line in their own make file!</para>
 
       <para>If you want to have a look at these system makefiles,
 	they are in <filename>/usr/share/mk</filename>, but it is
 	probably best to wait until you have had a bit of practice with
 	makefiles, as they are very complicated (and if you do look at
 	them, make sure you have a flask of strong coffee
 	handy!)</para>
     </sect2>
 
     <sect2>
       <title>More advanced uses of <command>make</command></title>
 
       <para><command>Make</command> is a very powerful tool, and can
 	do much more than the simple example above shows.
 	Unfortunately, there are several different versions of
 	<command>make</command>, and they all differ considerably.
 	The best way to learn what they can do is probably to read the
 	documentation&mdash;hopefully this introduction will have
 	given you a base from which you can do this.</para>
 
       <para>The version of make that comes with FreeBSD is the
 	<application>Berkeley make</application>; there is a tutorial
 	for it in <filename>/usr/share/doc/psd/12.make</filename>.  To
 	view it, do</para>
 
       <screen>&prompt.user; <userinput>zmore paper.ascii.gz</userinput></screen>
 
       <para>in that directory.</para>
 
       <para>Many applications in the ports use <application>GNU
 	  make</application>, which has a very good set of
 	<quote>info</quote> pages.  If you have installed any of these
 	ports, <application>GNU make</application> will automatically
 	have been installed as <command>gmake</command>.  It is also
 	available as a port and package in its own right.</para>
 
       <para>To view the info pages for <application>GNU
 	make</application>, you will have to edit the
 	<filename>dir</filename> file in the
 	<filename>/usr/local/info</filename> directory to add an entry
 	for it.  This involves adding a line like</para>
 
       <programlisting> * Make: (make).                 The GNU Make utility.</programlisting>
 
       <para>to the file.  Once you have done this, you can type
 	<userinput>info</userinput> and then select
 	<guimenuitem>make</guimenuitem> from the menu (or in
 	<application>Emacs</application>, do <userinput>C-h
 	  i</userinput>).</para>
     </sect2>
   </sect1>
 
   <sect1 id="debugging">
     <title>Debugging</title>
 
     <sect2>
       <title>The Debugger</title>
 
       <para>The debugger that comes with FreeBSD is called
 	<command>gdb</command> (<application>GNU
 	  debugger</application>).  You start it up by typing</para>
 
       <screen>&prompt.user; <userinput>gdb <replaceable>progname</replaceable></userinput></screen>
 
       <para>although most people prefer to run it inside
 	<application>Emacs</application>.  You can do this by:</para>
 
       <screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput></screen>
 
       <para>Using a debugger allows you to run the program under more
 	controlled circumstances.  Typically, you can step through the
 	program a line at a time, inspect the value of variables,
 	change them, tell the debugger to run up to a certain point
 	and then stop, and so on.  You can even attach to a program
 	that is already running, or load a core file to investigate why
 	the program crashed.  It is even possible to debug the kernel,
 	though that is a little trickier than the user applications
 	we will be discussing in this section.</para>
 
       <para><command>gdb</command> has quite good on-line help, as
 	well as a set of info pages, so this section will concentrate
 	on a few of the basic commands.</para>
 
       <para>Finally, if you find its text-based command-prompt style
 	off-putting, there is a graphical front-end for it (<ulink
 	  URL="../../../../ports/devel.html">xxgdb</ulink>) in the ports
 	collection.</para>
 
       <para>This section is intended to be an introduction to using
 	<command>gdb</command> and does not cover specialised topics
 	such as debugging the kernel.</para>
     </sect2>
 
     <sect2>
       <title>Running a program in the debugger</title>
 
       <para>You will need to have compiled the program with the
 	<option>-g</option> option to get the most out of using
 	<command>gdb</command>.  It will work without, but you will only
 	see the name of the function you are in, instead of the source
 	code.  If you see a line like:</para>
 
       <screen>&hellip; (no debugging symbols found) &hellip;</screen>
 
       <para>when <command>gdb</command> starts up, you will know that
 	the program was not compiled with the <option>-g</option>
 	option.</para>
 
       <para>At the <command>gdb</command> prompt, type
 	<userinput>break main</userinput>.  This will tell the
 	debugger to skip over the preliminary set-up code in the
 	program and start at the beginning of your code.  Now type
 	<userinput>run</userinput> to start the program&mdash;it will
 	start at the beginning of the set-up code and then get stopped
 	by the debugger when it calls <function>main()</function>.
 	(If you have ever wondered where <function>main()</function>
 	gets called from, now you know!).</para>
 
       <para>You can now step through the program, a line at a time, by
 	pressing <command>n</command>.  If you get to a function call,
 	you can step into it by pressing <command>s</command>.  Once
 	you are in a function call, you can return from stepping into a
 	function call by pressing <command>f</command>.  You can also
 	use <command>up</command> and <command>down</command> to take
 	a quick look at the caller.</para>
 
       <para>Here is a simple example of how to spot a mistake in a
 	program with <command>gdb</command>.  This is our program
 	(with a deliberate mistake):</para>
 
       <programlisting>#include &lt;stdio.h&gt;
 
 int bazz(int anint);
 
 main() {
 	int i;
 
 	printf("This is my program\n");
 	bazz(i);
 	return 0;
 }
 
 int bazz(int anint) {
 	printf("You gave me %d\n", anint);
 	return anint;
 }</programlisting>
 
       <para>This program sets <symbol>i</symbol> to be
 	<literal>5</literal> and passes it to a function
 	<function>bazz()</function> which prints out the number we
 	gave it.</para>
 
       <para>When we compile and run the program we get</para>
 
       <screen>&prompt.user; <userinput>cc -g -o temp temp.c</userinput>
 &prompt.user; <userinput>./temp</userinput>
 This is my program
 anint = 4231</screen>
 
       <para>That was not what we expected! Time to see what is going
 	on!</para>
 
       <screen>&prompt.user; <userinput>gdb temp</userinput>
 GDB is free software and you are welcome to distribute copies of it
  under certain conditions; type "show copying" to see the conditions.
 There is absolutely no warranty for GDB; type "show warranty" for details.
 GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
 (gdb) <userinput>break main</userinput>				<lineannotation>Skip the set-up code</lineannotation>
 Breakpoint 1 at 0x160f: file temp.c, line 9.	<lineannotation><command>gdb</command> puts breakpoint at <function>main()</function></lineannotation>
 (gdb) <userinput>run</userinput>					<lineannotation>Run as far as <function>main()</function></lineannotation>
 Starting program: /home/james/tmp/temp		<lineannotation>Program starts running</lineannotation>
 
 Breakpoint 1, main () at temp.c:9		<lineannotation><command>gdb</command> stops at <function>main()</function></lineannotation>
 (gdb) <userinput>n</userinput>						<lineannotation>Go to next line</lineannotation>
 This is my program				<lineannotation>Program prints out</lineannotation>
 (gdb) <userinput>s</userinput>						<lineannotation>step into <function>bazz()</function></lineannotation>
 bazz (anint=4231) at temp.c:17			<lineannotation><command>gdb</command> displays stack frame</lineannotation>
 (gdb)</screen>
 
       <para>Hang on a minute! How did <symbol>anint</symbol> get to be
 	<literal>4231</literal>? Did we not we set it to be
 	<literal>5</literal> in <function>main()</function>? Let's
 	move up to <function>main()</function> and have a look.</para>
 
       <screen>(gdb) <userinput>up</userinput>					<lineannotation>Move up call stack</lineannotation>
 #1  0x1625 in main () at temp.c:11		<lineannotation><command>gdb</command> displays stack frame</lineannotation>
 (gdb) <userinput>p i</userinput>					<lineannotation>Show us the value of <symbol>i</symbol></lineannotation>
 $1 = 4231					<lineannotation><command>gdb</command> displays <literal>4231</literal></lineannotation></screen>
 
       <para>Oh dear! Looking at the code, we forgot to initialise
 	<symbol>i</symbol>.  We meant to put</para>
 
       <programlisting><lineannotation>&hellip;</lineannotation>
 main() {
 	int i;
 
 	i = 5;
 	printf("This is my program\n");
-<lineannotation>&hellip</lineannotation></programlisting>
+<lineannotation>&hellip;</lineannotation></programlisting>
 
       <para>but we left the <literal>i=5;</literal> line out.  As we
 	did not initialise <symbol>i</symbol>, it had whatever number
 	happened to be in that area of memory when the program ran,
 	which in this case happened to be
 	<literal>4231</literal>.</para>
 
       <note>
 	<para><command>gdb</command> displays the stack frame every
 	  time we go into or out of a function, even if we are using
 	  <command>up</command> and <command>down</command> to move
 	  around the call stack.  This shows the name of the function
 	  and the values of its arguments, which helps us keep track
 	  of where we are and what is going on.  (The stack is a
 	  storage area where the program stores information about the
 	  arguments passed to functions and where to go when it
 	  returns from a function call).</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Examining a core file</title>
 
       <para>A core file is basically a file which contains the
 	complete state of the process when it crashed.  In <quote>the
 	  good old days</quote>, programmers had to print out hex
 	listings of core files and sweat over machine code manuals,
 	but now life is a bit easier.  Incidentally, under FreeBSD and
 	other 4.4BSD systems, a core file is called
 	<filename><replaceable>progname</replaceable>.core</filename> instead of just
 	<filename>core</filename>, to make it clearer which program a
 	core file belongs to.</para>
 
       <para>To examine a core file, start up <command>gdb</command> in
 	the usual way.  Instead of typing <command>break</command> or
 	<command>run</command>, type</para>
 
       <screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput></screen>
 
       <para>If you are not in the same directory as the core file,
 	you will have to do <userinput>dir
 	  /path/to/core/file</userinput> first.</para>
 
       <para>You should see something like this:</para>
 
       <screen>&prompt.user; <userinput>gdb a.out</userinput>
 GDB is free software and you are welcome to distribute copies of it
  under certain conditions; type "show copying" to see the conditions.
 There is absolutely no warranty for GDB; type "show warranty" for details.
 GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
 (gdb) <userinput>core a.out.core</userinput>
 Core was generated by `a.out'.
 Program terminated with signal 11, Segmentation fault.
 Cannot access memory at address 0x7020796d.
 #0  0x164a in bazz (anint=0x5) at temp.c:17
 (gdb)</screen>
 
       <para>In this case, the program was called
 	<filename>a.out</filename>, so the core file is called
 	<filename>a.out.core</filename>.  We can see that the program
 	crashed due to trying to access an area in memory that was not
 	available to it in a function called
 	<function>bazz</function>.</para>
 
       <para>Sometimes it is useful to be able to see how a function was
 	called, as the problem could have occurred a long way up the
 	call stack in a complex program.  The <command>bt</command>
 	command causes <command>gdb</command> to print out a
 	back-trace of the call stack:</para>
 
       <screen>(gdb) <userinput>bt</userinput>
 #0  0x164a in bazz (anint=0x5) at temp.c:17
 #1  0xefbfd888 in end ()
 #2  0x162c in main () at temp.c:11
 (gdb)</screen>
 
       <para>The <function>end()</function> function is called when a
 	program crashes; in this case, the <function>bazz()</function>
 	function was called from <function>main()</function>.</para>
     </sect2>
 
     <sect2>
       <title>Attaching to a running program</title>
 
       <para>One of the neatest features about <command>gdb</command>
 	is that it can attach to a program that is already running.  Of
 	course, that assumes you have sufficient permissions to do so.
 	A common problem is when you are stepping through a program
 	that forks, and you want to trace the child, but the debugger
 	will only let you trace the parent.</para>
 
       <para>What you do is start up another <command>gdb</command>,
 	use <command>ps</command> to find the process ID for the
 	child, and do</para>
 
       <screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput></screen>
 
       <para>in <command>gdb</command>, and then debug as usual.</para>
 
       <para><quote>That is all very well,</quote> you are probably
 	thinking, <quote>but by the time I have done that, the child
 	  process will be over the hill and far away</quote>.  Fear
 	not, gentle reader, here is how to do it (courtesy of the
 	<command>gdb</command> info pages):</para>
 
-      <screen><lineannotation>&hellip</lineannotation>
+      <screen><lineannotation>&hellip;</lineannotation>
 if ((pid = fork()) < 0)		/* _Always_ check this */
 	error();
 else if (pid == 0) {		/* child */
 	int PauseMode = 1;
 
 	while (PauseMode)
 		sleep(10);	/* Wait until someone attaches to us */
-	<lineannotation>&hellip</lineannotation>
+	<lineannotation>&hellip;</lineannotation>
 } else {			/* parent */
-	<lineannotation>&hellip</lineannotation></screen>
+	<lineannotation>&hellip;</lineannotation></screen>
 
       <para>Now all you have to do is attach to the child, set
 	<symbol>PauseMode</symbol> to <literal>0</literal>, and wait
 	for the <function>sleep()</function> call to return!</para>
     </sect2>
   </sect1>
 
   <sect1 id="emacs">
     <title>Using Emacs as a Development Environment</title>
 
     <sect2>
       <title>Emacs</title>
 
       <para>Unfortunately, Unix systems do nnot come with the kind of
 	everything-you-ever-wanted-and-lots-more-you-did-not-in-one-gigantic-package
 	integrated development environments that other systems
 	have.
 
 	<footnote>
 	  <para>Some powerful, free IDEs now exist, such as KDevelop
 	    in the ports collection.</para>
 	</footnote>
 
 	However, it is possible to set up your own environment.  It
 	may not be as pretty, and it may not be quite as integrated,
 	but you can set it up the way you want it.  And it is free.
 	And you have the source to it.</para>
 
       <para>The key to it all is Emacs.  Now there are some people who
 	loathe it, but many who love it.  If you are one of the former,
 	I am afraid this section will hold little of interest to you.
 	Also, you will need a fair amount of memory to run it&mdash;I would
 	recommend 8MB in text mode and 16MB in X as the bare minimum
 	to get reasonable performance.</para>
 
       <para>Emacs is basically a highly customisable
 	editor&mdash;indeed, it has been customised to the point where
 	it is more like an operating system than an editor! Many
 	developers and sysadmins do in fact spend practically all
 	their time working inside Emacs, leaving it only to log
 	out.</para>
 
       <para>It is impossible even to summarise everything Emacs can do
 	here, but here are some of the features of interest to
 	developers:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Very powerful editor, allowing search-and-replace on
 	    both strings and regular expressions (patterns), jumping
 	    to start/end of block expression, etc, etc.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Pull-down menus and online help.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Language-dependent syntax highlighting and
 	    indentation.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Completely customisable.</para>
 	</listitem>
 
 	<listitem>
 	  <para>You can compile and debug programs within
 	    Emacs.</para>
 	</listitem>
 
 	<listitem>
 	  <para>On a compilation error, you can jump to the offending
 	    line of source code.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Friendly-ish front-end to the <command>info</command>
 	    program used for reading GNU hypertext documentation,
 	    including the documentation on Emacs itself.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Friendly front-end to <command>gdb</command>, allowing
 	    you to look at the source code as you step through your
 	    program.</para>
 	</listitem>
 
 	<listitem>
 	  <para>You can read Usenet news and mail while your program
 	    is compiling.</para>
 	</listitem>
       </itemizedlist>
 
       <para>And doubtless many more that I have overlooked.</para>
 
       <para>Emacs can be installed on FreeBSD using <ulink
 	  URL="../../../../ports/editors.html">the Emacs
 	  port</ulink>.</para>
 
       <para>Once it is installed, start it up and do <userinput>C-h
 	  t</userinput> to read an Emacs tutorial&mdash;that means
 	hold down the <keycap>control</keycap> key, press
 	<keycap>h</keycap>, let go of the <keycap>control</keycap>
 	key, and then press <keycap>t</keycap>.  (Alternatively, you
 	can you use the mouse to select <guimenuitem>Emacs
 	  Tutorial</guimenuitem> from the <guimenu>Help</guimenu>
 	menu).</para>
 
       <para>Although Emacs does have menus, it is well worth learning
 	the key bindings, as it is much quicker when you are editing
 	something to press a couple of keys than to try and find the
 	mouse and then click on the right place.  And, when you are
 	talking to seasoned Emacs users, you will find they often
 	casually throw around expressions like <quote><literal>M-x
 	    replace-s RET foo RET bar RET</literal></quote> so it is
 	useful to know what they mean.  And in any case, Emacs has far
 	too many useful functions for them to all fit on the menu
 	bars.</para>
 
       <para>Fortunately, it is quite easy to pick up the key-bindings,
 	as they are displayed next to the menu item.  My advice is to
 	use the menu item for, say, opening a file until you
 	understand how it works and feel confident with it, then try
 	doing C-x C-f.  When you are happy with that, move on to
 	another menu command.</para>
 
       <para>If you can not remember what a particular combination of
 	keys does, select <guimenuitem>Describe Key</guimenuitem> from
 	the <guimenu>Help</guimenu> menu and type it in&mdash;Emacs
 	will tell you what it does.  You can also use the
 	<guimenuitem>Command Apropos</guimenuitem> menu item to find
 	out all the commands which contain a particular word in them,
 	with the key binding next to it.</para>
 
       <para>By the way, the expression above means hold down the
 	<keysym>Meta</keysym> key, press <keysym>x</keysym>, release
 	the <keysym>Meta</keysym> key, type
 	<userinput>replace-s</userinput> (short for
 	<literal>replace-string</literal>&mdash;another feature of
 	Emacs is that you can abbreviate commands), press the
 	<keysym>return</keysym> key, type <userinput>foo</userinput>
 	(the string you want replaced), press the
 	<keysym>return</keysym> key, type bar (the string you want to
 	replace <literal>foo</literal> with) and press
 	<keysym>return</keysym> again.  Emacs will then do the
 	search-and-replace operation you have just requested.</para>
 
       <para>If you are wondering what on earth the
 	<keysym>Meta</keysym> key is, it is a special key that many
 	Unix workstations have.  Unfortunately, PC's do not have one,
 	so it is usually the <keycap>alt</keycap> key (or if you are
 	unlucky, the <keysym>escape</keysym> key).</para>
 
       <para>Oh, and to get out of Emacs, do <command>C-x C-c</command>
 	(that means hold down the <keysym>control</keysym> key, press
 	<keysym>x</keysym>, press <keysym>c</keysym> and release the
 	<keysym>control</keysym> key).  If you have any unsaved files
 	open, Emacs will ask you if you want to save them.  (Ignore
 	the bit in the documentation where it says
 	<command>C-z</command> is the usual way to leave
 	Emacs&mdash;that leaves Emacs hanging around in the
 	background, and is only really useful if you are on a system
 	which does not have virtual terminals).</para>
     </sect2>
 
     <sect2>
       <title>Configuring Emacs</title>
 
       <para>Emacs does many wonderful things; some of them are built
 	in, some of them need to be configured.</para>
 
       <para>Instead of using a proprietary macro language for
 	configuration, Emacs uses a version of Lisp specially adapted
 	for editors, known as Emacs Lisp.  This can be quite useful if
 	you want to go on and learn something like Common Lisp, as
 	it is considerably smaller than Common Lisp (although still
 	quite big!).</para>
 
       <para>The best way to learn Emacs Lisp is to download the <ulink
 	  URL="ftp://ftp.gnu.org/old-gnu/emacs/elisp-manual-19-2.4.tar.gz">Emacs
 	  Tutorial</ulink></para>
 
       <para>However, there is no need to actually know any Lisp to get
 	started with configuring Emacs, as I have included a sample
 	<filename>.emacs</filename> file, which should be enough to
 	get you started.  Just copy it into your home directory and
 	restart Emacs if it is already running; it will read the
 	commands from the file and (hopefully) give you a useful basic
 	setup.</para>
     </sect2>
 
     <sect2>
       <title>A sample <filename>.emacs</filename> file</title>
 
       <para>Unfortunately, there is far too much here to explain it in
 	detail; however there are one or two points worth
 	mentioning.</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Everything beginning with a <literal>;</literal> is a comment
 	    and is ignored by Emacs.</para>
 	</listitem>
 
 	<listitem>
 	  <para>In the first line, the
 	    <literal>-*-&nbsp;Emacs-Lisp&nbsp;-*-</literal> is so that
 	    we can edit the <filename>.emacs</filename> file itself
 	    within Emacs and get all the fancy features for editing
 	    Emacs Lisp.  Emacs usually tries to guess this based on
 	    the filename, and may not get it right for
 	    <filename>.emacs</filename>.</para>
 	</listitem>
 
 	<listitem>
 	  <para>The <keysym>tab</keysym> key is bound to an
 	    indentation function in some modes, so when you press the
 	    tab key, it will indent the current line of code.  If you
 	    want to put a <token>tab</token> character in whatever
 	    you are writing, hold the <keysym>control</keysym> key down
 	    while you are pressing the <keysym>tab</keysym> key.</para>
 	</listitem>
 
 	<listitem>
 	  <para>This file supports syntax highlighting for C, C++,
 	    Perl, Lisp and Scheme, by guessing the language from the
 	    filename.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Emacs already has a pre-defined function called
 	    <function>next-error</function>.  In a compilation output
 	    window, this allows you to move from one compilation error
 	    to the next by doing <command>M-n</command>; we define a
 	    complementary function,
 	    <function>previous-error</function>, that allows you to go
 	    to a previous error by doing <command>M-p</command>.  The
 	    nicest feature of all is that <command>C-c C-c</command>
 	    will open up the source file in which the error occurred
 	    and jump to the appropriate line.</para>
 	</listitem>
 
 	<listitem>
 	  <para>We enable Emacs's ability to act as a server, so that
 	    if you are doing something outside Emacs and you want to
 	    edit a file, you can just type in</para>
 
 	  <screen>&prompt.user; <userinput>emacsclient <replaceable>filename</replaceable></userinput>
 	  </screen>
 
 	  <para>and then you can edit the file in your
 	    Emacs!
 
 	    <footnote>
 	      <para>Many Emacs users set their <envar>EDITOR</envar>
 		environment to
 		<literal>emacsclient</literal> so this happens every
 		time they need to edit a file.</para>
 	    </footnote></para>
 	</listitem>
       </itemizedlist>
 
       <example>
 	<title>A sample <filename>.emacs</filename> file</title>
 
 	<programlisting>;; -*-Emacs-Lisp-*-
 
 ;; This file is designed to be re-evaled; use the variable first-time
 ;; to avoid any problems with this.
 (defvar first-time t 
   "Flag signifying this is the first time that .emacs has been evaled")
 
 ;; Meta
 (global-set-key "\M- " 'set-mark-command)
 (global-set-key "\M-\C-h" 'backward-kill-word)
 (global-set-key "\M-\C-r" 'query-replace)
 (global-set-key "\M-r" 'replace-string)
 (global-set-key "\M-g" 'goto-line)
 (global-set-key "\M-h" 'help-command)
 
 ;; Function keys
 (global-set-key [f1] 'manual-entry)
 (global-set-key [f2] 'info)
 (global-set-key [f3] 'repeat-complex-command)
 (global-set-key [f4] 'advertised-undo)
 (global-set-key [f5] 'eval-current-buffer)
 (global-set-key [f6] 'buffer-menu)
 (global-set-key [f7] 'other-window)
 (global-set-key [f8] 'find-file)
 (global-set-key [f9] 'save-buffer)
 (global-set-key [f10] 'next-error)
 (global-set-key [f11] 'compile)
 (global-set-key [f12] 'grep)
 (global-set-key [C-f1] 'compile)
 (global-set-key [C-f2] 'grep)
 (global-set-key [C-f3] 'next-error)
 (global-set-key [C-f4] 'previous-error)
 (global-set-key [C-f5] 'display-faces)
 (global-set-key [C-f8] 'dired)
 (global-set-key [C-f10] 'kill-compilation)
 
 ;; Keypad bindings
 (global-set-key [up] "\C-p")
 (global-set-key [down] "\C-n")
 (global-set-key [left] "\C-b")
 (global-set-key [right] "\C-f")
 (global-set-key [home] "\C-a")
 (global-set-key [end] "\C-e")
 (global-set-key [prior] "\M-v")
 (global-set-key [next] "\C-v")
 (global-set-key [C-up] "\M-\C-b")
 (global-set-key [C-down] "\M-\C-f")
 (global-set-key [C-left] "\M-b")
 (global-set-key [C-right] "\M-f")
 (global-set-key [C-home] "\M-&lt;")
 (global-set-key [C-end] "\M-&gt;")
 (global-set-key [C-prior] "\M-&lt;")
 (global-set-key [C-next] "\M-&gt;")
 
 ;; Mouse
 (global-set-key [mouse-3] 'imenu)
 
 ;; Misc
 (global-set-key [C-tab] "\C-q\t")	; Control tab quotes a tab.
 (setq backup-by-copying-when-mismatch t)
 
 ;; Treat 'y' or &lt;CR&gt; as yes, 'n' as no.
 (fset 'yes-or-no-p 'y-or-n-p)
     (define-key query-replace-map [return] 'act)
     (define-key query-replace-map [?\C-m] 'act)
 
 ;; Load packages
 (require 'desktop)
 (require 'tar-mode)
 
 ;; Pretty diff mode
 (autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t)
 (autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t)
 (autoload 'ediff-files-remote "ediff"
   "Intelligent Emacs interface to diff")
 
 (if first-time
     (setq auto-mode-alist
 	  (append '(("\\.cpp$" . c++-mode)
 		    ("\\.hpp$" . c++-mode)
                     ("\\.lsp$" . lisp-mode)
 		    ("\\.scm$" . scheme-mode)
 		    ("\\.pl$" . perl-mode)
 		    ) auto-mode-alist)))
 
 ;; Auto font lock mode
 (defvar font-lock-auto-mode-list 
   (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode)
   "List of modes to always start in font-lock-mode")
 
 (defvar font-lock-mode-keyword-alist
   '((c++-c-mode . c-font-lock-keywords)
     (perl-mode . perl-font-lock-keywords))
   "Associations between modes and keywords")
 
 (defun font-lock-auto-mode-select ()
   "Automatically select font-lock-mode if the current major mode is
 in font-lock-auto-mode-list"
   (if (memq major-mode font-lock-auto-mode-list) 
       (progn
 	(font-lock-mode t))
     )
   )
 
 (global-set-key [M-f1] 'font-lock-fontify-buffer)
 
 ;; New dabbrev stuff
 ;(require 'new-dabbrev)
 (setq dabbrev-always-check-other-buffers t)
 (setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_")
 (add-hook 'emacs-lisp-mode-hook
 	  '(lambda () 
 	     (set (make-local-variable 'dabbrev-case-fold-search) nil)
 	     (set (make-local-variable 'dabbrev-case-replace) nil)))
 (add-hook 'c-mode-hook
 	  '(lambda () 
 	     (set (make-local-variable 'dabbrev-case-fold-search) nil)
 	     (set (make-local-variable 'dabbrev-case-replace) nil)))
 (add-hook 'text-mode-hook
 	  '(lambda () 
 	     (set (make-local-variable 'dabbrev-case-fold-search) t)
 	     (set (make-local-variable 'dabbrev-case-replace) t)))
 
 ;; C++ and C mode...
 (defun my-c++-mode-hook ()
   (setq tab-width 4)
   (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
   (define-key c++-mode-map "\C-ce" 'c-comment-edit)
   (setq c++-auto-hungry-initial-state 'none)
   (setq c++-delete-function 'backward-delete-char)
   (setq c++-tab-always-indent t)
   (setq c-indent-level 4)
   (setq c-continued-statement-offset 4)
   (setq c++-empty-arglist-indent 4))
 
 (defun my-c-mode-hook ()
   (setq tab-width 4)
   (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent)
   (define-key c-mode-map "\C-ce" 'c-comment-edit)
   (setq c-auto-hungry-initial-state 'none)
   (setq c-delete-function 'backward-delete-char)
   (setq c-tab-always-indent t)
 ;; BSD-ish indentation style
   (setq c-indent-level 4)
   (setq c-continued-statement-offset 4)
   (setq c-brace-offset -4)
   (setq c-argdecl-indent 0)
   (setq c-label-offset -4))
 
 ;; Perl mode
 (defun my-perl-mode-hook ()
   (setq tab-width 4)
   (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
   (setq perl-indent-level 4)
   (setq perl-continued-statement-offset 4))
 
 ;; Scheme mode...
 (defun my-scheme-mode-hook ()
   (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent))
 
 ;; Emacs-Lisp mode...
 (defun my-lisp-mode-hook ()
   (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent)
   (define-key lisp-mode-map "\C-i" 'lisp-indent-line)
   (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp))
 
 ;; Add all of the hooks...
 (add-hook 'c++-mode-hook 'my-c++-mode-hook)
 (add-hook 'c-mode-hook 'my-c-mode-hook)
 (add-hook 'scheme-mode-hook 'my-scheme-mode-hook)
 (add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook)
 (add-hook 'lisp-mode-hook 'my-lisp-mode-hook)
 (add-hook 'perl-mode-hook 'my-perl-mode-hook)
 
 ;; Complement to next-error
 (defun previous-error (n)
   "Visit previous compilation error message and corresponding source code."
   (interactive "p")
   (next-error (- n)))
 
 ;; Misc...
 (transient-mark-mode 1)
 (setq mark-even-if-inactive t)
 (setq visible-bell nil)
 (setq next-line-add-newlines nil)
 (setq compile-command "make")
 (setq suggest-key-bindings nil)
 (put 'eval-expression 'disabled nil)
 (put 'narrow-to-region 'disabled nil)
 (put 'set-goal-column 'disabled nil)
 
 ;; Elisp archive searching
 (autoload 'format-lisp-code-directory "lispdir" nil t)
 (autoload 'lisp-dir-apropos "lispdir" nil t)
 (autoload 'lisp-dir-retrieve "lispdir" nil t)
 (autoload 'lisp-dir-verify "lispdir" nil t)
 
 ;; Font lock mode
 (defun my-make-face (face colour &amp;optional bold)
   "Create a face from a colour and optionally make it bold"
   (make-face face)
   (copy-face 'default face)
   (set-face-foreground face colour)
   (if bold (make-face-bold face))
   )
 
 (if (eq window-system 'x)
     (progn
       (my-make-face 'blue "blue")
       (my-make-face 'red "red")
       (my-make-face 'green "dark green")
       (setq font-lock-comment-face 'blue)
       (setq font-lock-string-face 'bold)
       (setq font-lock-type-face 'bold)
       (setq font-lock-keyword-face 'bold)
       (setq font-lock-function-name-face 'red)
       (setq font-lock-doc-string-face 'green)
       (add-hook 'find-file-hooks 'font-lock-auto-mode-select)
 
       (setq baud-rate 1000000)
       (global-set-key "\C-cmm" 'menu-bar-mode)
       (global-set-key "\C-cms" 'scroll-bar-mode)
       (global-set-key [backspace] 'backward-delete-char)
 					;      (global-set-key [delete] 'delete-char)
       (standard-display-european t)
       (load-library "iso-transl")))
 
 ;; X11 or PC using direct screen writes
 (if window-system
     (progn
       ;;      (global-set-key [M-f1] 'hilit-repaint-command)
       ;;      (global-set-key [M-f2] [?\C-u M-f1])
       (setq hilit-mode-enable-list  
 	    '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode
 		  scheme-mode)
 	    hilit-auto-highlight nil
 	    hilit-auto-rehighlight 'visible
 	    hilit-inhibit-hooks nil
 	    hilit-inhibit-rebinding t)
       (require 'hilit19)
       (require 'paren))
   (setq baud-rate 2400)			; For slow serial connections
   )
 
 ;; TTY type terminal
 (if (and (not window-system) 
 	 (not (equal system-type 'ms-dos)))
     (progn
       (if first-time
 	  (progn
 	    (keyboard-translate ?\C-h ?\C-?)
 	    (keyboard-translate ?\C-? ?\C-h)))))
 
 ;; Under UNIX
 (if (not (equal system-type 'ms-dos))
     (progn
       (if first-time
 	  (server-start))))
 
 ;; Add any face changes here
 (add-hook 'term-setup-hook 'my-term-setup-hook)
 (defun my-term-setup-hook ()
   (if (eq window-system 'pc)
       (progn
 ;;	(set-face-background 'default "red")
 	)))
 
 ;; Restore the "desktop" - do this as late as possible
 (if first-time
     (progn
       (desktop-load-default)
       (desktop-read)))
 
 ;; Indicate that this file has been read at least once
 (setq first-time nil)
 
 ;; No need to debug anything now
 
 (setq debug-on-error nil)
 
 ;; All done
 (message "All done, %s%s" (user-login-name) ".")
 	</programlisting>
       </example>
     </sect2>
 
     <sect2>
       <title>Extending the Range of Languages Emacs Understands</title>
 
       <para>Now, this is all very well if you only want to program in
 	the languages already catered for in the
 	<filename>.emacs</filename> file (C, C++, Perl, Lisp and
 	Scheme), but what happens if a new language called
 	<quote>whizbang</quote> comes out, full of exciting
 	features?</para>
 
       <para>The first thing to do is find out if whizbang comes with
 	any files that tell Emacs about the language.  These usually
 	end in <filename>.el</filename>, short for <quote>Emacs
 	  Lisp</quote>.  For example, if whizbang is a FreeBSD port, we
 	can locate these files by doing</para>
 
       <screen>&prompt.user; <userinput>find /usr/ports/lang/whizbang -name "*.el" -print</userinput></screen>
 
       <para>and install them by copying them into the Emacs site Lisp
 	directory.  On FreeBSD 2.1.0-RELEASE, this is
 	<filename>/usr/local/share/emacs/site-lisp</filename>.</para>
 
       <para>So for example, if the output from the find command
 	was</para>
 
       <screen>/usr/ports/lang/whizbang/work/misc/whizbang.el</screen>
 
       <para>we would do</para>
 
       <screen>&prompt.root; <userinput>cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp</userinput></screen>
 
       <para>Next, we need to decide what extension whizbang source
 	files have.  Let's say for the sake of argument that they all
 	end in <filename>.wiz</filename>.  We need to add an entry to
 	our <filename>.emacs</filename> file to make sure Emacs will
 	be able to use the information in
 	<filename>whizbang.el</filename>.</para>
 
       <para>Find the <symbol>auto-mode-alist entry</symbol> in
 	<filename>.emacs</filename> and add a line for whizbang, such
 	as:</para>
 
       <programlisting><lineannotation>&hellip;</lineannotation>
 ("\\.lsp$" . lisp-mode)
 ("\\.wiz$" . whizbang-mode)
 ("\\.scm$" . scheme-mode)
 <lineannotation>&hellip;</lineannotation></programlisting>
 
       <para>This means that Emacs will automatically go into
 	<function>whizbang-mode</function> when you edit a file ending
 	in <filename>.wiz</filename>.</para>
 
       <para>Just below this, you will find the
 	<symbol>font-lock-auto-mode-list</symbol> entry.  Add
 	<function>whizbang-mode</function> to it like so:</para>
 
       <programlisting>;; Auto font lock mode
 (defvar font-lock-auto-mode-list 
   (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode)
   "List of modes to always start in font-lock-mode")</programlisting>
 
       <para>This means that Emacs will always enable
 	<function>font-lock-mode</function> (ie syntax highlighting)
 	when editing a <filename>.wiz</filename> file.</para>
 
       <para>And that is all that is needed.  If there is anything else
 	you want done automatically when you open up a
 	<filename>.wiz</filename> file, you can add a
 	<function>whizbang-mode hook</function> (see
 	<function>my-scheme-mode-hook</function> for a simple example
 	that adds <function>auto-indent</function>).</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Further Reading</title>
 
     <itemizedlist>
       <listitem>
 	<para>Brian Harvey and Matthew Wright
 	  <emphasis>Simply Scheme</emphasis>
 	  MIT 1994.<!-- <br> -->
 	  ISBN 0-262-08226-8</para>
       </listitem>
 
       <listitem>
 	<para>Randall Schwartz
 	  <emphasis>Learning Perl</emphasis>
 	  O'Reilly 1993<!-- <br> -->
 	  ISBN 1-56592-042-2</para>
       </listitem>
 
       <listitem>
 	<para>Patrick Henry Winston and Berthold Klaus Paul Horn
 	  <emphasis>Lisp (3rd Edition)</emphasis>
 	  Addison-Wesley 1989<!-- <br> -->
 	  ISBN 0-201-08319-1</para>
       </listitem>
 
       <listitem>
 	<para>Brian W. Kernighan and Rob Pike
 	  <emphasis>The Unix Programming Environment</emphasis>
 	  Prentice-Hall 1984<!-- <br> -->
 	  ISBN 0-13-937681-X</para>
       </listitem>
 
       <listitem>
 	<para>Brian W. Kernighan and Dennis M. Ritchie
 	  <emphasis>The C Programming Language (2nd Edition)</emphasis>
 	  Prentice-Hall 1988<!-- <br> -->
 	  ISBN 0-13-110362-8</para>
       </listitem>
 
       <listitem>
 	<para>Bjarne Stroustrup
 	<emphasis>The C++ Programming Language</emphasis>
 	Addison-Wesley 1991<!-- <br> -->
 	ISBN 0-201-53992-6</para>
       </listitem>
 
       <listitem>
 	<para>W. Richard Stevens
 	  <emphasis>Advanced Programming in the Unix Environment</emphasis>
 	  Addison-Wesley 1992<!-- <br> -->
 	  ISBN 0-201-56317-7</para>
       </listitem>
 
       <listitem>
 	<para>W. Richard Stevens
 	  <emphasis>Unix Network Programming</emphasis>
 	  Prentice-Hall 1990<!-- <br> -->
 	  ISBN 0-13-949876-1</para>
       </listitem>
     </itemizedlist>
   </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/faq/book.sgml b/en_US.ISO8859-1/books/faq/book.sgml
index 587f75df00..03dbf4ed90 100644
--- a/en_US.ISO8859-1/books/faq/book.sgml
+++ b/en_US.ISO8859-1/books/faq/book.sgml
@@ -1,12375 +1,12375 @@
 <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 <!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
 %freebsd;
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
 <!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//EN">
 %teams;
 
 <!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN">
 %bookinfo;
 
 <!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
 %mailing-lists;
 
 <!ENTITY bibliography SYSTEM "../../../share/sgml/bibliography.sgml">
 ]>
 
 <book>
   <bookinfo>
     <title>Frequently Asked Questions for FreeBSD 2.X, 3.X and 4.X</title>
 
     <corpauthor>The FreeBSD Documentation Project</corpauthor>
 
     <pubdate>$FreeBSD$</pubdate>
 
     <copyright>
       <year>1995</year>
       <year>1996</year>
       <year>1997</year>
       <year>1998</year>
       <year>1999</year>
       <year>2000</year>
       <year>2001</year>
       <year>2002</year>
       <holder>The FreeBSD Documentation Project</holder>
     </copyright>
 
     &bookinfo.legalnotice;
 
     <abstract>
       <para>This is the FAQ for FreeBSD versions 2.X, 3.X, and 4.X.
         All entries are assumed to be relevant to FreeBSD 2.0.5 and later,
         unless otherwise noted. Any entries with a &lt;XXX&gt; are under
         construction. If you are interested in helping with this project,
         send email to the &a.doc;.  The latest version of this
         document is always available from the <ulink
         URL="../../../../index.html">FreeBSD World Wide Web
         server</ulink>. It may also be downloaded as one large <ulink
         URL="book.html">HTML</ulink> file with HTTP or as plain text,
         postscript, PDF, etc. from the <ulink
         URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP
         server</ulink>. You may also want to <ulink
         URL="../../../../search/index.html">Search the
         FAQ</ulink>.</para>
     </abstract>
   </bookinfo>
 
   <chapter id="introduction">
     <title>Introduction</title>
 
     <para>Welcome to the FreeBSD 2.X-4.X FAQ!</para>
 
     <para>As is usual with Usenet FAQs, this document aims to cover the
       most frequently asked questions concerning the FreeBSD operating
       system (and of course answer them!).  Although originally intended
       to reduce bandwidth and avoid the same old questions being asked
       over and over again, FAQs have become recognized as valuable
       information resources.</para>
 
     <para>Every effort has been made to make this FAQ as informative as
       possible; if you have any suggestions as to how it may be improved,
       please feel free to mail them to the &a.faq;.</para>
 
     <qandaset>
       <qandaentry>
         <question id="what-is-FreeBSD">
           <para>What is FreeBSD?</para>
         </question>
 
         <answer>
          <para>Briefly, FreeBSD is a UN*X-like operating system for
            the i386 and Alpha/AXP platforms based on U.C. Berkeley's
            <quote>4.4BSD-Lite</quote> release, with some
            <quote>4.4BSD-Lite2</quote> enhancements.  It is also based
            indirectly on William Jolitz's port of U.C.  Berkeley's
            <quote>Net/2</quote> to the i386, known as
            <quote>386BSD</quote>, though very little of the 386BSD
            code remains.  A fuller description of what FreeBSD is and
            how it can work for you may be found on the <ulink
            URL="../../../../index.html">FreeBSD home
            page</ulink>.</para>
 
          <para>FreeBSD is used by companies, Internet Service Providers,
            researchers, computer professionals, students and home users
            all over the world in their work, education and recreation.
            See some of them in the <ulink
            URL="../../../../gallery/index.html">FreeBSD
            Gallery</ulink>.</para>
 
          <para>For more detailed information on FreeBSD, please see the
            <ulink URL="../handbook/index.html">FreeBSD
            Handbook</ulink>.</para>
        </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="FreeBSD-goals">
           <para>What is the goal of the FreeBSD Project?</para>
         </question>
 
         <answer>
           <para>The goal of the FreeBSD Project is to provide software
             that may be used for any purpose and without strings attached.
             Many of us have a significant investment in the code (and
             project) and would certainly not mind a little financial
             compensation now and then, but we are definitely not prepared
             to insist on it.  We believe that our first and foremost
             <quote>mission</quote> is to provide code to any and all
             comers, and for whatever purpose, so that the code gets the
             widest possible use and provides the widest possible benefit.
             This is, we believe, one of the most fundamental goals of Free
             Software and one that we enthusiastically support.</para>
 
           <para>That code in our source tree which falls under the
             <ulink url="http://www.FreeBSD.org/copyright/COPYING">GNU
             General Public License (GPL)</ulink> or <ulink
             url="http://www.FreeBSD.org/copyright/COPYING.LIB">GNU
             Library General Public License (LGPL)</ulink> comes with
             slightly more strings attached, though at least on the
             side of enforced access rather than the usual opposite.
             Due to the additional complexities that can evolve in the
             commercial use of GPL software, we do, however, endeavor
             to replace such software with submissions under the more
             relaxed <ulink
             url="http://www.FreeBSD.org/copyright/freebsd-license.html">
             FreeBSD copyright</ulink> whenever possible.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="bsd-license-restrictions">
           <para>Does the FreeBSD license have any restrictions?</para>
         </question>
 
         <answer>
           <para>Yes.  Those restrictions do not control how you use
             the code, merely how you treat the FreeBSD Project itself.
             If you have serious license concerns, read the actual
             <ulink
             url="http://www.FreeBSD.org/copyright/freebsd-license.html">
             license</ulink>.  For the simply curious, the license can
             be summarized like this.</para>
 
           <itemizedlist>
             <listitem>
               <para>Do not claim that you wrote this.</para>
             </listitem>
 
             <listitem>
               <para>Do not sue us if it breaks.</para>
             </listitem>
           </itemizedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="replace-current-OS">
           <para>Can FreeBSD replace my current operating system?</para>
         </question>
 
         <answer>
           <para>For most people, yes.  But this question is not quite
             that cut-and-dried.</para>
 
           <para>Most people do not actually use an operating system.
             They use applications.  The applications are what really
             use the operating system.  FreeBSD is designed to provide
             a robust and full-featured environment for applications.
             It supports a wide variety of web browsers, office suites,
             email readers, graphics programs, programming
             environments, network servers, and just about everything
             else you might want.  Most of these applications can be
             managed through the <ulink
             url="http://www.freebsd.org/ports/">Ports
             Collection</ulink>.</para>
 
           <para>If you need to use an application that is only
             available on one operating system, you simply cannot
             replace that operating system.  Chances are there is a very
             similar application on FreeBSD, however.  If you want a
             solid office or Internet server, a reliable workstation,
             or just the ability to do your job without interruptions,
             FreeBSD will almost certainly do everything you need.
             Many computer users across the world, including both
             novices and experienced UNIX administrators, use FreeBSD
             as their only desktop operating system.</para>
 
           <para>If you are migrating to FreeBSD from some other UNIX
             environment, you already know most of what you need to.
             If your background is in graphic-driven operating systems
             such as Windows and older versions of Mac OS, expect to
             invest additional time learning the UNIX way of doing
             things.  This FAQ and the <ulink
             url="../handbook/index.html">FreeBSD Handbook</ulink> are
             excellent places to start.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="why-called-FreeBSD">
           <para>Why is it called FreeBSD?</para>
         </question>
 
         <answer>
           <itemizedlist>
             <listitem>
               <para>It may be used free of charge, even by commercial
                 users.</para>
             </listitem>
 
             <listitem>
               <para>Full source for the operating system is freely
                 available, and the minimum possible restrictions have
                 been placed upon its use, distribution and incorporation
                 into other work (commercial or non-commercial).</para>
             </listitem>
 
             <listitem>
               <para>Anyone who has an improvement or bug fix is free
                 to submit their code and have it added to the source tree
                 (subject to one or two obvious provisions).</para>
             </listitem>
           </itemizedlist>
 
           <para>It is worth pointing out that the word
             <quote>free</quote> is being used in two ways here, one meaning
             <quote>at no cost</quote>, the other meaning <quote>you can do
             whatever you like</quote>.  Apart from one or two things you
             <emphasis>cannot</emphasis> do with the FreeBSD code, for
             example pretending you wrote it, you really can do whatever you
             like with it.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="latest-version">
           <para>What is the latest version of FreeBSD?</para>
         </question>
 
         <answer>
           <para>Version <ulink
             URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">&rel.current;</ulink>
             is the latest <emphasis>RELEASE</emphasis> version; it was
             released in &rel.current.date;. This is also the latest
             <emphasis>STABLE</emphasis> version.</para>
 
           <para>Briefly, <emphasis>-STABLE</emphasis> is aimed
             at the ISP, corporate user, or any user who wants stability and a
             low change count over the wizzy new features of the latest
             <emphasis>-CURRENT</emphasis> snapshot.  Releases can come
             from either branch, but <emphasis>-CURRENT</emphasis>
             should only be used if you are prepared for its increased volatility (relative to 
             <emphasis>-STABLE</emphasis>, that is).</para>
 
           <para>Releases are made <link linkend="release-freq">every
             few months</link>. While many people stay more up-to-date with
             the FreeBSD sources (see the questions on <link
             linkend="current">FreeBSD-CURRENT</link> and <link
             linkend="stable">FreeBSD-STABLE</link>) than that, doing so
             is more of a commitment, as the sources are a moving
             target.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="current">
           <para>What is FreeBSD-CURRENT?</para>
         </question>
 
         <answer>
           <para><ulink
             URL="../handbook/cutting-edge.html#CURRENT">FreeBSD-CURRENT</ulink>
             is the development version of the operating system, which
             will in due course become 5.0-RELEASE.  As such, it is
             really only of interest to developers working on the
             system and die-hard hobbyists.  See the <ulink
             URL="../handbook/cutting-edge.html#CURRENT">relevant
             section</ulink> in the <ulink
             URL="../handbook/index.html">handbook</ulink> for details
             on running -CURRENT.</para>
 
           <para>If you are not familiar with the operating system or are
             not capable of identifying the difference between a real
             problem and a temporary problem, you should not use
             FreeBSD-CURRENT.  This branch sometimes evolves quite quickly
             and can be un-buildable for a number of days at a time.
             People that use FreeBSD-CURRENT are expected to be able to
             analyze any problems and only report them if they are deemed
             to be mistakes rather than <quote>glitches</quote>. Questions
             such as <quote>make world produces some error about
             groups</quote> on the -CURRENT mailing list may be
             treated with contempt.</para>
 
           <para>Every day, <ulink
             URL="../../../../releases/snapshots.html">snapshot
             </ulink> releases are made based on the current state of the
             -CURRENT and -STABLE branches. Nowadays, distributions of the
             occasional snapshot are now being made available. The goals
             behind each snapshot release are:</para>
 
           <itemizedlist>
             <listitem>
               <para>To test the latest version of the installation
                 software.</para>
             </listitem>
 
             <listitem>
               <para>To give people who would like to run -CURRENT or
                 -STABLE but who do not have the time or bandwidth to
                 follow it on a day-to-day basis an easy way of
                 bootstrapping it onto their systems.</para>
             </listitem>
 
             <listitem>
               <para>To preserve a fixed reference point for the code in
                 question, just in case we break something really badly
                 later.  (Although CVS normally prevents anything horrible
                 like this happening :)</para>
             </listitem>
 
             <listitem>
               <para>To ensure that any new features in need of testing
                 have the greatest possible number of potential
                 testers.</para>
             </listitem>
           </itemizedlist>
 
           <para>No claims are made that any -CURRENT snapshot can be
             considered <quote>production quality</quote> for any purpose.
             If you want to run a stable and fully tested system, you will
             have to stick to full releases, or use the -STABLE
             snapshots.</para>
 
           <para>Snapshot releases are directly available from <ulink
             URL="ftp://current.FreeBSD.org/pub/FreeBSD/">
             ftp://current.FreeBSD.org/pub/FreeBSD/</ulink> for 5.0-CURRENT
             and <ulink URL="ftp://releng4.FreeBSD.org/pub/FreeBSD">
             releng4.FreeBSD.org</ulink> for 4-STABLE snapshots.
             3-STABLE snapshots are not being produced at the time of
             this writing (May 2000).</para>
 
           <para>Snapshots are generated, on the average, once a day for
             all actively developed branches.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="stable">
           <para>What is the FreeBSD-STABLE concept?</para>
         </question>
 
         <answer>
           <para>Back when FreeBSD 2.0.5 was released, we decided to
             branch FreeBSD development into two parts.  One branch was
             named <ulink
             URL="../handbook/current-stable.html#STABLE">-STABLE</ulink>,
             with the intention that only well-tested bug fixes and
             small incremental enhancements would be made to it (for
             Internet Service Providers and other commercial
             enterprises for whom sudden shifts or experimental
             features are quite undesirable).  The other branch was
             <ulink
             URL="../handbook/cutting-edge.html#CURRENT">-CURRENT</ulink>,
             which essentially has been one unbroken line leading
             towards 5.0-RELEASE (and beyond) since 2.0 was
             released. If a little ASCII art would help, this is how it
             looks:</para>
 
           <programlisting>                 2.0
                   |
                   |
                   |  [2.1-STABLE]
  *BRANCH*       2.0.5 -&gt; 2.1 -&gt; 2.1.5 -&gt; 2.1.6 -&gt; 2.1.7.1  [2.1-STABLE ends]
                   |                            (Mar 1997)
                   |
                   |
                   |  [2.2-STABLE]
  *BRANCH*       2.2.1 -&gt; 2.2.2-RELEASE -&gt; 2.2.5 -&gt; 2.2.6 -&gt; 2.2.7 -&gt; 2.2.8 [end]
                   |       (Mar 1997)    (Oct 97) (Apr 98) (Jul 98) (Dec 98)
                   |
                   |
                3.0-SNAPs  (started Q1 1997)
                   |
                   |
                3.0-RELEASE (Oct 1998)
                   |
                   |  [3.0-STABLE]
  *BRANCH*      3.1-RELEASE  (Feb 1999) -&gt; 3.2 -&gt; 3.3 -&gt; 3.4 -&gt; 3.5 -&gt; 3.5.1
                   |                     (May 1999) (Sep 1999) (Dec 1999) (June 2000) (July 2000)
                   |
                   |  [4.0-STABLE]
  *BRANCH*        4.0  (Mar 2000) -&gt; 4.1 -&gt; 4.1.1 -&gt; 4.2 -&gt; 4.3 -&gt; 4.4 -&gt; ... future 4.x releases ...
                   |
                   |              (July 2000)   (Sep 2000)   (Nov 2000)
                  \|/
                   +
           [5.0-CURRENT continues]</programlisting>
 
           <para>The 2.2-STABLE branch was retired with the release of 2.2.8.
             The 3-STABLE branch has ended with the release of 3.5.1, the
             final 3.X release.  The only changes made to either of these
             branches will be, for the most part, security-related bug
             fixes.</para>
 
           <para>4-STABLE is the actively developed -STABLE branch.
             The latest release on the 4-STABLE is
             &rel.current;-RELEASE, which was released in
             &rel.current.date;.</para>
 
           <para>The 5-CURRENT branch is slowly progressing toward
             5.0-RELEASE and beyond.  See <link linkend="current">What
             is FreeBSD-CURRENT?</link> for more information on this
             branch.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="release-freq">
           <para>When are FreeBSD releases made?</para>
         </question>
 
         <answer>
           <para>As a general principle, the FreeBSD core team only release
             a new version of FreeBSD when they believe that there are
             sufficient new features and/or bug fixes to justify one, and
             are satisfied that these new developments have been tested
             sufficiently to avoid compromising the stability of the
             release.  Release dates are generally announced well in
             advance, so that the people working on the system know
             when their projects need to be finished and tested.  
             Many users regard this caution as one of the best
             things about FreeBSD, although 
             waiting for all the latest goodies to reach -STABLE
             can be a little frustrating.</para>
 
           <para>Releases are made about every 4 months on average.</para>
 
           <para>For people who need or want a little more excitement,
             binary snapshots are made every day as discussed above.</para>
          </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="responsible">
           <para>Who is responsible for FreeBSD?</para>
         </question>
 
         <answer>
           <para>The key decisions concerning the FreeBSD project, such
             as the overall direction of the project and who is allowed
             to add code to the source tree, are made by a <ulink
             URL="../../articles/contributors/article.html#STAFF-CORE">core
             team</ulink> of 9 people. There is a much larger team of
             more than 200 <ulink
             URL="../../articles/contributors/article.html#STAFF-COMMITTERS">committers</ulink>
             who are authorized to make changes directly to the FreeBSD
             source tree.</para>
 
           <para>However, most non-trivial changes are discussed in advance
             in the <link linkend="mailing">mailing lists</link>, and there
             are no restrictions on who may take part in the
             discussion.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="where-get">
           <para>Where can I get FreeBSD?</para>
         </question>
 
         <answer>
           <para>Every significant release of FreeBSD is available via
             anonymous FTP from the <ulink
             URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/">
             FreeBSD FTP site</ulink>:</para>
 
           <itemizedlist>
             <listitem>
               <para>For the current 3.X-STABLE release, 3.5.1-RELEASE, see
                 the <ulink
                 URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/3.5.1-RELEASE/">3.5.1-RELEASE directory</ulink>.</para>
             </listitem>
 
             <listitem>
               <para>The current 4-STABLE release, &rel.current;-RELEASE can be
                 found in the <ulink
                 URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">&rel.current;-RELEASE directory</ulink>.</para>
             </listitem>
 
             <listitem>
               <para><ulink
                 URL="ftp://releng4.FreeBSD.org/pub/FreeBSD/">4.X
                 snapshots</ulink> are usually made once a day.</para>
             </listitem>
 
             <listitem>
               <para><ulink
                 URL="ftp://current.FreeBSD.org/pub/FreeBSD/">
                 5.0 Snapshot</ulink> releases are made once a day for the
                 <link linkend="current">-CURRENT</link> branch, these being
                 of service purely to bleeding-edge testers and
                 developers.</para>
             </listitem>
           </itemizedlist>
 
 	  <para>Information about obtaining FreeBSD on CD, DVD, and other
 	    media can be found in <ulink url="../handbook/mirrors.html">the
 	      Handbook</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="access-pr">
           <para>How do I access the Problem Report database?</para>
         </question>
 
         <answer>
           <para>The Problem Report database of all user change requests
             may be queried (or submitted to) by using our web-based PR
             <ulink
             URL="http://www.FreeBSD.org/send-pr.html">submission</ulink>
             and <ulink
             URL="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
             query</ulink>
             interfaces.  The &man.send-pr.1; command can
             also be used to submit problem reports and change requests via
             electronic mail.</para>
 
           <para>Before submitting a problem report, please read <ulink
             URL="../../articles/problem-reports/article.html">Writing
             FreeBSD Problem Reports</ulink>, an article on how to write
             good problem reports.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="become-web-mirror">
           <para>How do I become a FreeBSD Web mirror?</para>
         </question>
 
         <answer>
           <para>There are multiple ways to mirror the Web
             pages.</para>
 
           <itemizedlist>
             <listitem>
               <para>You can retrieve the formatted files from a
                 FreeBSD CVSup server using the application
                 <filename role="package">net/cvsup</filename>.  The file
                 <filename>/usr/share/examples/cvsup/www-supfile</filename>
                 contains an example CVSup configuration file for web
                 mirrors.
               </para>
             </listitem>
 
             <listitem>
               <para>You can download the web site source code from any
                 FreeBSD FTP server using your favorite ftp mirror
                 tool.  Keep in mind that you have to build these
                 sources before publishing them.  Start mirroring at
                 <ulink
                 URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/www">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/www</ulink>.</para>
             </listitem>
           </itemizedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="other-info-sources">
           <para>What other sources of information are there?</para>
         </question>
 
         <answer>
           <para>Please check the <ulink
             url="http://www.FreeBSD.org/docs.html">Documentation</ulink>
             list on the main <ulink
             url="http://www.FreeBSD.org">FreeBSD</ulink> web
             site.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="support">
     <title>Documentation and Support</title>
     
     <qandaset>
       <qandaentry>
 	<question id="books">
 	  <para>What good books are there about FreeBSD?</para>
 	</question>
 	
 	<answer>
 	  <para>The project produces a wide range of documentation, available
 	    from this link: 
 	    <ulink url="http://www.freebsd.org/docs.html">http://www.FreeBSD.org/docs.html</ulink>.  
 	    
 	    In addition, the Bibliography at the end of this FAQ, and the 
 	    one in the Handbook reference other recommended books.</para>
 	</answer>
       </qandaentry>
       
       <qandaentry>
         <question id="doc-formats">
           <para>Is the documentation available in other formats, such as plain
             text (ASCII), or Postscript?</para>
         </question>
 
         <answer>
           <para>Yes.  The documentation is available in a number of
             different formats and compression schemes on the FreeBSD
             FTP site, in the <ulink
             URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">/pub/FreeBSD/doc/</ulink>
             directory.</para>
 
           <para>The documentation is categorized in a number of different
             ways.  These include:</para>
 
           <itemizedlist>
             <listitem>
               <para>The document's name, such as <literal>faq</literal>, or
                 <literal>handbook</literal>.</para>
             </listitem>
 
             <listitem>
               <para>The document's language and encoding.  These are based on
                 the locale names you will find under
                 <filename>/usr/share/locale</filename> on your FreeBSD
                 system.  The current languages and encodings that we have for
                 documentation are as follows:</para>
 
               <informaltable frame="none">
                 <tgroup cols="2">
                   <thead>
                     <row>
                       <entry>Name</entry>
 
                       <entry>Meaning</entry>
                     </row>
                   </thead>
 
                   <tbody>
                     <row>
                       <entry><literal>en_US.ISO8859-1</literal></entry>
 
                       <entry>US English</entry>
                     </row>
 
                     <row>
                       <entry><literal>de_DE.ISO8859-1</literal></entry>
 
                       <entry>German</entry>
                     </row>
 
                     <row>
                       <entry><literal>es_ES.ISO8859-1</literal></entry>
 
                       <entry>Spanish</entry>
                     </row>
 
                     <row>
                       <entry><literal>fr_FR.ISO8859-1</literal></entry>
 
                       <entry>French</entry>
                     </row>
 
                     <row>
                       <entry><literal>ja_JP.eucJP</literal></entry>
 
                       <entry>Japanese (EUC encoding)</entry>
                     </row>
 
                     <row>
                       <entry><literal>ru_RU.KOI8-R</literal></entry>
 
                       <entry>Russian (KOI8-R encoding)</entry>
                     </row>
 
                     <row>
                       <entry><literal>zh_TW.Big5</literal></entry>
 
                       <entry>Chinese (Big5 encoding)</entry>
                     </row>
                   </tbody>
                 </tgroup>
               </informaltable>
 
               <note>
                 <para>Some documents may not be available in all
                   languages.</para>
               </note>
             </listitem>
 
             <listitem>
               <para>The document's format.  We produce the documentation in a
                 number of different output formats to try and make it as
                 flexible as possible.  The current formats are;</para>
 
               <informaltable frame="none">
                 <tgroup cols="2">
                   <thead>
                     <row>
                       <entry>Format</entry>
 
                       <entry>Meaning</entry>
                     </row>
                   </thead>
 
                   <tbody>
                     <row>
                       <entry><literal>html-split</literal></entry>
 
                       <entry>A collection of small, linked, HTML
                         files.</entry>
                     </row>
 
                     <row>
                       <entry><literal>html</literal></entry>
 
                       <entry>One large HTML file containing the entire
                         document</entry>
                     </row>
 
                     <row>
                       <entry><literal>pdb</literal></entry>
 
                       <entry>Palm Pilot database format, for use with the
                         <ulink URL="http://www.iSilo.com/">iSilo</ulink>
                         reader.</entry>
                     </row>
 
                     <row>
                       <entry><literal>pdf</literal></entry>
 
                       <entry>Adobe's Portable Document Format</entry>
                     </row>
 
                     <row>
                       <entry><literal>ps</literal></entry>
 
                       <entry>Postscript</entry>
                     </row>
 
                     <row>
                       <entry><literal>rtf</literal></entry>
 
                       <entry>Microsoft's Rich Text Format<footnote>
                           <para>Page numbers are not automatically updated
                             when loading this format in to Word.  Press
                             <keycombo action="simul"><keycap>CTRL</keycap><keycap>A</keycap></keycombo>,
                             <keycombo action="simul"><keycap>CTRL</keycap><keycap>END</keycap></keycombo>,
                             <keycap>F9</keycap> after loading the document, to
                             update the page numbers.</para>
                         </footnote>
                       </entry>
                     </row>
 
                     <row>
                       <entry><literal>txt</literal></entry>
 
                       <entry>Plain text</entry>
                     </row>
                   </tbody>
                 </tgroup>
               </informaltable>
             </listitem>
 
             <listitem>
               <para>The compression and packaging scheme.  There are three of
                 these currently in use.</para>
 
               <orderedlist>
                 <listitem>
                   <para>Where the format is <literal>html-split</literal>, the
                     files are bundled up using &man.tar.1;.  The resulting
                     <filename>.tar</filename> file is then compressed using
                     the compression schemes detailed in the next point.</para>
                 </listitem>
 
                 <listitem>
                   <para>All the other formats generate one file, called
                     <filename>book.<replaceable>format</replaceable></filename>
                     (i.e., <filename>book.pdb</filename>,
                     <filename>book.html</filename>, and so on).</para>
 
                   <para>These files are then compressed using three
                     compression schemes.</para>
 
                   <informaltable frame="none">
                     <tgroup cols="2">
                       <thead>
                         <row>
                           <entry>Scheme</entry>
 
                           <entry>Description</entry>
                         </row>
                       </thead>
 
                       <tbody>
                         <row>
                           <entry><literal>zip</literal></entry>
 
                           <entry>The Zip format.  If you want to uncompress
                             this on FreeBSD you will need to install the
                             <filename role="package">archivers/unzip</filename> port
                             first.</entry>
                         </row>
 
                         <row>
                           <entry><literal>gz</literal></entry>
 
                           <entry>The GNU Zip format.  Use &man.gunzip.1; to
                             uncompress these files, which is part of
                             FreeBSD.</entry>
                         </row>
 
                         <row>
                           <entry><literal>bz2</literal></entry>
 
                           <entry>The BZip2 format.  Less widespread than the
                             others, but generally gives smaller files.
                             Install the <filename role="package">archivers/bzip2</filename>
                             port to uncompress these files.</entry>
                         </row>
                       </tbody>
                     </tgroup>
                   </informaltable>
 
                   <para>So the Postscript version of the Handbook, compressed
                     using BZip2 will be stored in a file called
                     <filename>book.ps.bz2</filename> in the
                     <filename>handbook/</filename> directory.</para>
                 </listitem>
 
                 <listitem>
                   <para>The formatted documentation is also available as a
                     FreeBSD package, of which more later.</para>
                 </listitem>
               </orderedlist>
             </listitem>
           </itemizedlist>
 
           <para>After choosing the format and compression mechanism that you
             want to download, you must then decide whether or not you want to
             download the document as a FreeBSD
             <emphasis>package</emphasis>.</para>
 
           <para>The advantage of downloading and installing the package is
             that the documentation can then be managed using the normal
             FreeBSD package management comments, such as &man.pkg.add.1; and
             &man.pkg.delete.1;.</para>
 
           <para>If you decide to download and install the package then you
             must know the filename to download.  The documentation-as-packages
             files are stored in a directory called
             <filename>packages</filename>.  Each package file looks like
             <filename><replaceable>document-name</replaceable>.<replaceable>lang</replaceable>.<replaceable>encoding</replaceable>.<replaceable>format</replaceable>.tgz</filename>.</para>
 
           <para>For example, the FAQ, in English, formatted as PDF, is in the
             package called
             <filename>faq.en_US.ISO8859-1.pdf.tgz</filename>.</para>
 
           <para>Knowing this, you can use the following command to install the
             English PDF FAQ package.</para>
 
           <screen>&prompt.root; <userinput>pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO8859-1.pdf.tgz</userinput></screen>
 
           <para>Having done that, you can use &man.pkg.info.1; to determine
             where the file has been installed.</para>
 
           <screen>&prompt.root; <userinput>pkg_info -f faq.en_US.ISO8859-1.pdf</userinput>
 Information for faq.en_US.ISO8859-1.pdf:
 
 Packing list:
         Package name: faq.en_US.ISO8859-1.pdf
         CWD to /usr/share/doc/en_US.ISO8859-1/books/faq
 File: book.pdf
         CWD to .
 File: +COMMENT (ignored)
 File: +DESC (ignored)</screen>
 
           <para>As you can see, <filename>book.pdf</filename> will have been
             installed in to
             <filename>/usr/share/doc/en_US.ISO8859-1/books/faq</filename>.
           </para>
 
           <para>If you do not want to use the packages then you will have to
             download the compressed files yourself, uncompress them, and then
             copy the appropriate documents in to place.</para>
 
           <para>For example, the split HTML version of the FAQ, compressed
             using &man.gzip.1;, can be found in the
             <filename>doc/en_US.ISO8859-1/books/faq/book.html-split.tar.gz</filename>
             file.  To download and uncompress that file you would have to do
             this.</para>
 
           <screen>&prompt.root; <userinput>fetch ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.gz</userinput>
 &prompt.root; <userinput>gzip -d book.html-split.tar.gz</userinput>
 &prompt.root; <userinput>tar xvf book.html-split.tar</userinput></screen>
 
           <para>You will be left with a collection of
             <filename>.html</filename> files.  The main one is called
             <filename>index.html</filename>, which will contain the table of
             contents, introductory material, and links to the other parts of
             the document.  You can then copy or move these to their final
             location as necessary.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="mailing">
           <para>Where do I find info on the FreeBSD mailing lists?</para>
         </question>
 
         <answer>
           <para>You can find full information in the <ulink
             URL="../handbook/eresources.html#ERESOURCES-MAIL">Handbook
             entry on mailing-lists</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="y2k">
           <para>Where do I find the FreeBSD Y2K info?</para>
         </question>
 
         <answer>
           <para>You can find full information in the <ulink
             URL="../../../../y2kbug.html">FreeBSD Y2K
             page</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="newsgroups">
           <para>What FreeBSD news groups are available?</para>
         </question>
 
         <answer>
           <para>You can find full information in the <ulink
             URL="../handbook/eresources-news.html">Handbook entry on
             newsgroups</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="irc">
           <para>Are there FreeBSD IRC (Internet Relay Chat)
             channels?</para>
         </question>
 
         <answer>
           <para>Yes, most major IRC networks host a FreeBSD chat
             channel:</para>
 
           <itemizedlist>
             <listitem>
               <para>Channel <literal>#FreeBSD</literal> on
                 <ulink URL="http://www.efnet.org/index.php">EFNet</ulink>
                 is a FreeBSD forum, but do not go there for tech
                 support or to try and get folks there to help you avoid
                 the pain of reading man pages or doing your own research.
                 It is a chat channel, first and foremost, and topics there
                 are just as likely to involve sex, sports or nuclear
                 weapons as they are FreeBSD.  You Have Been Warned!
                 Available at server <hostid>irc.chat.org</hostid>.</para>
             </listitem>
 
             <listitem>
               <para>Channel <literal>#FreeBSDhelp</literal> on
                 <ulink URL="http://www.efnet.org/index.php">EFNet</ulink>
                 is a channel dedicated to helping FreeBSD users. They
                 are much more sympathetic to questions then
                 <literal>#FreeBSD</literal> is.</para>
             </listitem>
 
             <listitem>
               <para>Channel <literal>#FreeBSD</literal> on
                 <ulink URL="http://www.dal.net/">DALNET</ulink>
                 is available at <hostid>irc.dal.net</hostid> in the
                 US and  <hostid>irc.eu.dal.net</hostid> in Europe.</para>
             </listitem>
 
             <listitem>
               <para>Channel <literal>#FreeBSD</literal> on
                 <ulink URL="http://www.undernet.org/">UNDERNET</ulink>
                 is available at <hostid>us.undernet.org</hostid>
                 in the US and  <hostid>eu.undernet.org</hostid> in Europe.
                 Since it is a help channel, be prepared to read the
                 documents you are referred to.</para>
             </listitem>
 
             <listitem>
               <para>Channel <literal>#FreeBSD</literal> on <ulink
                 url="http://www.hybnet.net/">HybNet</ulink>.  This channel
                 <emphasis>is</emphasis> a help channel.  A list of servers
                 can be found on the <ulink
                 url="http://www.hybnet.net/">HybNet web site</ulink>.</para>
             </listitem>
           </itemizedlist>
 
           <para>Each of these channels are distinct and are not
             connected to each other.  Their chat styles also differ,
             so you may need to try each to find one suited to your
             chat style.  As with <emphasis>all</emphasis> types of IRC
             traffic, if you are easily offended or cannot deal with
             lots of young people (and more than a few older ones)
             doing the verbal equivalent of jello wrestling, do not
             even bother with it.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
 	<question id="training">
 	  <para>Where can I get commercial FreeBSD training and support?</para>
 	</question>
 
 	<answer>
 	  <para>DaemonNews provides commercial training and support for
 	    FreeBSD.  More information can be found at their 
 	    <ulink url="http://www.bsdmall.com/">BSD Mall</ulink> 
 	    site.</para>
 
           <para>The FreeBSD Mall provides commercial FreeBSD support.
             You can get more information at their <ulink
             url="http://www.freebsdmall.com/">web site</ulink>.</para>
 
 	  <para>Any other organizations providing training and support should
 	    contact the project in order to be listed here.</para>
 	</answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter
     id="install">
     <chapterinfo>
       <author>
 	<firstname>Nik</firstname>
 	<surname>Clayton</surname>
 	<affiliation>
 	  <address><email>nik@FreeBSD.org</email></address>
 	</affiliation>
       </author>
     </chapterinfo>
     
     <title>Installation</title>
 
     <qandaset>
       <qandaentry>
         <question id="floppy-download">
           <para>Which file do I download to get FreeBSD?</para>
         </question>
 
         <answer>
           <para>Prior to release 3.1, you only needed one floppy image to
             install FreeBSD, namely <filename>floppies/boot.flp</filename>.
             However, since release 3.1 the Project has added out-of-the-box
             support for a wide variety of hardware, which takes up more
             space.  For 3.x and later you need two floppy images:
             <filename>floppies/kernel.flp</filename> and
             <filename>floppies/mfsroot.flp</filename>. These images need to
             be copied onto floppies by tools like
             <command>fdimage</command> or &man.dd.1;.</para>
 
           <para>If you need to download the distributions yourself (for a
             DOS filesystem install, for instance), below are some
             recommendations for distributions to grab:</para>
 
 
           <itemizedlist>
             <listitem>
               <para>bin/</para>
             </listitem>
 
             <listitem>
               <para>manpages/</para>
             </listitem>
 
             <listitem>
               <para>compat*/</para>
             </listitem>
 
             <listitem>
               <para>doc/</para>
             </listitem>
 
             <listitem>
               <para>src/ssys.*</para>
             </listitem>
           </itemizedlist>
 
 
           <para>Full instructions on this procedure and a little bit more
             about installation issues in general can be found in the
             <ulink URL="../handbook/install.html">Handbook entry on
             installing FreeBSD</ulink>.</para>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="floppy-image-too-large">
           <para>What do I do if the floppy images does not fit on a single
             floppy?</para>
         </question>
 
         <answer>
           <para>A 3.5 inch (1.44MB) floppy can accommodate 1474560 bytes
             of data. The boot image is exactly 1474560 bytes in size.</para>
 
           <para>Common mistakes when preparing the boot floppy are:</para>
 
           <itemizedlist>
             <listitem>
               <para>Not downloading the floppy image in
                 <emphasis>binary</emphasis> mode when using
                 <acronym>FTP</acronym>.</para>
 
 
               <para>Some FTP clients default their transfer mode to
                 <emphasis>ascii</emphasis> and attempt to change any
                 end-of-line characters received to match the conventions
                 used by the client's system. This will almost invariably
                 corrupt the boot image. Check the size of the downloaded
                 boot image: if it is not <emphasis>exactly</emphasis> that
                 on the server, then the download process is suspect.</para>
 
               <para>To workaround: type <emphasis>binary</emphasis> at the
                 FTP command prompt after getting connected to the server
                 and before starting the download of the image.</para>
             </listitem>
 
             <listitem>
               <para>Using the DOS <command>copy</command> command (or
                 equivalent GUI tool) to transfer the boot image to
                 floppy.</para>
 
               <para>Programs like <command>copy</command> will not work as
                 the boot image has been created to be booted into directly.
                 The image has the complete content of the floppy, track for
                 track, and is not meant to be placed on the floppy as a
                 regular file. You have to transfer it to the floppy
                 <quote>raw</quote>, using the low-level tools (e.g.
                 <command>fdimage</command> or <command>rawrite</command>)
                 described in the <ulink
                 URL="../handbook/install.html">installation guide to
                 FreeBSD</ulink>.</para>
             </listitem>
           </itemizedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="install-instructions-location">
           <para>Where are the instructions for installing FreeBSD?</para>
         </question>
 
         <answer>
           <para>Installation instructions can be found in the
             <ulink URL="../handbook/install.html">Handbook entry on installing FreeBSD</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="need-to-run">
           <para>What do I need in order to run FreeBSD?</para>
         </question>
 
         <answer>
           <para>You will need a 386 or better PC, with 5 MB or more of RAM
             and at least 60 MB of hard disk space. It can run with a low
             end MDA graphics card but to run X11R6, a VGA or better video
             card is needed.</para>
 
           <para>See also 
             <xref linkend="hardware"></para>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="four-meg-ram-install">
           <para>I have only 4 MB of RAM. Can I install FreeBSD?</para>
         </question>
 
         <answer>
           <para>FreeBSD 2.1.7 was the last version of FreeBSD that
             could be installed on a 4MB system.  FreeBSD 2.2 and later
             needs at least 5MB to install on a new system.</para>
 
           <para>All versions of FreeBSD will <emphasis>run</emphasis>
             in 4MB of RAM, they just cannot run the installation
             program in 4MB. You can add extra memory for the install
             process, if you like, and then after the system is up and
             running, go back to 4MB. Or you could swap your disk into
             a system which has &gt;4MB, install onto the disk and then
             swap it back.</para>
 
           <para>FreeBSD 2.1.7 will not install with 640 kB base + 3 MB
             extended memory. If your motherboard can remap some of the
             <quote>lost</quote> memory out of the 640kB to 1MB region,
             then you may still be able to get FreeBSD 2.1.7 up.  Try
             to go into your BIOS setup and look for a
             <quote>remap</quote> option.  Enable it.  You may also
             have to disable ROM shadowing.  It may be easier to get 4
             more MB just for the install.  Build a custom kernel with
             only the options you need and then remove the 4MB out.
             You can also install 2.0.5 and then upgrade your system to
             2.1.7 with the <quote>upgrade</quote> option of the 2.1.7
             installation program.</para>
 
           <para>After the installation, if you build a custom kernel,
             it will run in 4 MB. Someone has even successfully booted
             with 2 MB, although the system was almost unusable.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="custom-boot-floppy">
           <para>How can I make my own custom install floppy?</para>
         </question>
 
         <answer>
           <para>Currently there is no way to <emphasis>just</emphasis>
             make a custom install floppy. You have to cut a whole new
             release, which will include your install floppy.</para>
 
           <para>To make a custom release, follow the instructions in the
             <ulink url="../../articles/releng/article.html">Release
             Engineering</ulink> article.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="multiboot">
           <para>Can I have more than one operating system on my PC?</para>
         </question>
 
         <answer>
           <para>Have a look at
             <ulink URL="../../articles/multi-os/index.html">
             the multi-OS page</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="windows-coexist">
           <para>Can Windows 95/98 co-exist with FreeBSD?</para>
         </question>
 
         <answer>
           <para>Install Windows 95/98 first, after that FreeBSD.
             FreeBSD's boot manager will then manage to boot Win95/98 and
             FreeBSD. If you install Windows 95/98 second, it will boorishly
             overwrite your boot manager without even asking. If that
             happens, see the next section.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="win95-damaged-boot-manager">
           <para>Windows 95/98 killed my boot manager!
             How do I get it back?</para>
         </question>
 
         <answer>
           <para>You can reinstall the boot manager FreeBSD comes with in
             one of three ways:</para>
 
           <itemizedlist>
             <listitem>
               <para>Running DOS, go into the tools/ directory of your
                 FreeBSD distribution and look for
                 <filename>bootinst.exe</filename>.  You run it like
                 so:</para>
 
               <screen><prompt>...\TOOLS&gt;</prompt> <userinput>bootinst.exe boot.bin</userinput></screen>
 
               <para>and the boot manager will be reinstalled.</para>
             </listitem>
 
             <listitem>
               <para>Boot the FreeBSD boot floppy again and go to the
                 Custom installation menu item. Choose Partition. Select the
                  drive which used to contain your boot manager (likely the
                  first one) and when you come to the partition editor for
                  it, as the very first thing (e.g. do not make any changes)
                  select (W)rite. This will ask for confirmation, say yes,
                  and when you get the Boot Manager selection prompt, be
                  sure to select <quote>Boot Manager</quote>. This will
                  re-write the boot manager to disk. Now quit out of the
                  installation menu and reboot off the hard disk as
                  normal.</para>
             </listitem>
 
             <listitem>
               <para>Boot the FreeBSD boot floppy (or CDROM) and choose the
                 <quote>Fixit</quote> menu item. Select either the Fixit
                 floppy or CDROM #2 (the <quote>live</quote> file system
                 option) as appropriate and enter the fixit shell. Then
                 execute the following command:</para>
 
               <screen><prompt>Fixit#</prompt> <userinput>fdisk -B -b /boot/boot0 <replaceable>bootdevice</replaceable></userinput></screen>
 
               <para>substituting <replaceable>bootdevice</replaceable> for
                 your real
                 boot device such as <devicename>ad0</devicename> (first IDE
                 disk), <devicename>ad4</devicename> (first IDE disk on
                 auxiliary controller), <devicename>da0</devicename> (first
                 SCSI disk), etc.</para>
             </listitem>
           </itemizedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="boot-on-thinkpad">
           <para>My A, T, or X series IBM Thinkpad locks up when I first
             booted up my FreeBSD installation.  How can I solve this?</para>
         </question>
 
         <answer>
           <para>A bug in early revisions of IBM's BIOS on these machines
             mistakenly identifies the FreeBSD partition as a potential FAT
             suspend-to-disk partition.  When the BIOS tries to parse the
             FreeBSD partition it hangs.</para>
 
           <para>According to IBM<footnote><para>In an e-mail from Keith
                 Frechette
                 <email>kfrechet@us.ibm.com</email>.</para></footnote>, the
             following model/BIOS release numbers incorporate the fix.</para>
 
           <informaltable frame="none">
             <tgroup cols="2">
               <thead>
                 <row>
                   <entry>Model</entry>
                   <entry>BIOS revision</entry>
                 </row>
               </thead>
 
               <tbody>
                 <row>
                   <entry>T20</entry>
                   <entry>IYET49WW or later</entry>
                 </row>
 
                 <row>
                   <entry>T21</entry>
                   <entry>KZET22WW or later</entry>
                 </row>
 
                 <row>
                   <entry>A20p</entry>
                   <entry>IVET62WW or later</entry>
                 </row>
 
                 <row>
                   <entry>A20m</entry>
                   <entry>IWET54WW or later</entry>
                 </row>
 
                 <row>
                   <entry>A21p</entry>
                   <entry>KYET27WW or later</entry>
                 </row>
 
                 <row>
                   <entry>A21m</entry>
                   <entry>KXET24WW or later</entry>
                 </row>
 
                 <row>
                   <entry>A21e</entry>
                   <entry>KUET30WW</entry>
                 </row>
               </tbody>
             </tgroup>
           </informaltable>
 
 	  <para>It has been reported that later IBM BIOS revisions may have
 	    reintroduced the bug.  <ulink
 					  url="http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=200565+208320+/usr/local/www/db/text/2001/freebsd-mobile/20010429.freebsd-mobile">This message</ulink>
 	    from Jacques Vidrine to the &a.mobile; describes a procedure
             which may work if your newer IBM laptop does not boot FreeBSD
             properly, and you can upgrade or downgrade the BIOS..</para>
 	
           <para>If you have an earlier BIOS, and upgrading is not an option a
             workaround is to install FreeBSD, change the partition ID FreeBSD
             uses, and install new boot blocks that can handle the different
             partition ID.</para>
 
           <para>First, you will need to restore the machine to a state where
             it can get through its self-test screen.  Doing this requires
             powering up the machine without letting it find a FreeBSD
             partition on its primary disk.  One way is to remove the hard disk
             and temporarily move it to an older ThinkPad (such as a ThinkPad
             600) or a desktop PC with an appropriate conversion cable.  Once
             it is there, you can delete the FreeBSD partition and move the hard
             disk back.  The ThinkPad should now be in a bootable state
             again.</para>
 
           <para>With the machine functional again, you can use the workaround
             procedure described here to get a working FreeBSD
             installation.</para>
 
           <procedure>
             <step>
               <para>Download <filename>boot1</filename> and
                 <filename>boot2</filename> from <ulink
                   url="http://people.FreeBSD.org/~bmah/ThinkPad/">http://people.FreeBSD.org/~bmah/ThinkPad/</ulink>.
                 Put these files somewhere you will be able to retrieve them
                 later.</para>
             </step>
 
             <step>
               <para>Install FreeBSD as normal on to the ThinkPad.
                 <emphasis>Do not</emphasis> use <literal>Dangerously
                   Dedicated</literal> mode.  <emphasis>Do not</emphasis>
                 reboot when the install has finished.</para>
             </step>
 
             <step>
               <para>Either switch to the <quote>Emergency Holographic
                   Shell</quote> (<keycombo action="simul"><keycap>ALT</keycap>
                   <keycap>F4</keycap></keycombo>) or start a
                 <quote>fixit</quote> shell.</para>
             </step>
 
             <step>
               <para>Use &man.fdisk.8; to change the FreeBSD partition ID from
                 <literal>165</literal> to <literal>166</literal> (this is the
                   type used by OpenBSD).</para>
             </step>
 
             <step>
               <para>Bring the <filename>boot1</filename> and
                 <filename>boot2</filename> files to the local
                 filesystem.</para>
             </step>
 
             <step>
               <para>Use &man.disklabel.8; to write <filename>boot1</filename>
                 and <filename>boot2</filename> to your FreeBSD slice.</para>
 
               <screen>&prompt.root; <userinput>disklabel -B -b boot1 -s boot2 ad0s<replaceable>n</replaceable></userinput></screen>
 
               <para><replaceable>n</replaceable> is the number of the slice
                 where you installed FreeBSD.</para>
             </step>
 
             <step>
               <para>Reboot.  At the boot prompt you will be given the option
                 of booting <literal>OpenBSD</literal>.  This will actually
                 boot FreeBSD.</para>
             </step>
           </procedure>
 
           <para>Getting this to work in the case where you want to dual boot
           OpenBSD and FreeBSD on the same laptop is left as an exercise for
           the reader.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="install-bad-blocks">
           <para>Can I install on a disk with bad blocks?</para>
         </question>
 
         <answer>
           <para>Prior to 3.0, FreeBSD included a utility known as
             <command>bad144</command>, which automatically remapped bad
             blocks. Because modern IDE drives perform this function
             themselves, <command>bad144</command> has been removed from the
             FreeBSD source tree. If you wish to install FreeBSD 3.0 or
             later, we strongly suggest you purchase a newer disk drive. If
             you do not wish to do this, you must run FreeBSD 2.x.</para>
             <para>If you are seeing bad block errors with a modern IDE
             drive, chances are the drive is going to die very soon (the
             drive's internal remapping functions are no longer sufficient
             to fix the bad blocks, which means the disk is heavily
             corrupted); we suggest you buy a new hard drive.</para>
 
           <para>If you have a SCSI drive with bad blocks, see
             <link linkend="awre">this answer</link>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="bad144-3x-4x">
           <para>I have just upgraded from 3.X to 4.X, and my first boot
             failed with <errorname>bad sector table not
             supported</errorname></para>
         </question>
 
         <answer>
           <para>FreeBSD 3.X and earlier supported
             <command>bad144</command>, which automatically remapped
             bad blocks.  FreeBSD 4.X and later do not support this, as
             modern IDE drives include this functionality.  See <link
             linkend="install-bad-blocks">this question</link> for
             more information.</para>
 
           <para>To fix this after an upgrade, you need to physically
             place the drive in a working system and use
             &man.disklabel.8; as discussed in the following
             questions.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="find-bad144">
           <para>How do I tell if a drive has <command>bad144</command>
             information on it before I try to upgrade to FreeBSD 4.0
             and it fails?</para>
         </question>
 
         <answer>
           <para>Use &man.disklabel.8; for this.  <command>disklabel -r
             <replaceable>drive device</replaceable></command> will
             give you the contents of your disk label.  Look for a
             <literal>flags</literal> field.  If you see
             <literal>flags: badsect</literal>, this drive is using
             bad144.  For example, the following drive has
             <command>bad144</command> enabled.:</para>
 
           <screen>&prompt.root; disklabel -r wd0
 # /dev/rwd0c:
 type: ESDI
 disk: wd0s1
 label:
 flags: badsect
 bytes/sector: 512
 sectors/track: 63</screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="disable-bad144">
           <para>How do I remove <command>bad144</command> from my
             pre-4.X system so I can upgrade safely?</para>
         </question>
 
         <answer>
           <para>Use <command>disklabel -e -rwd0 </command> to edit the
             disklabel in place.  Just remove the word
             <literal>badsect</literal> from the flags field, save, and
             exit.  The bad144 file will still take up some space on
             your drive, but the disk itself will be usable.</para>
 
           <para>We still recommend you purchase a new disk if you have
             a large number of bad blocks.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="boot-floppy-strangeness">
           <para>Strange things happen when I boot the install floppy!
             What is happening?</para>
         </question>
 
         <answer>
           <para>If you are seeing things like the machine grinding to a halt
             or spontaneously rebooting when you try to boot the install
             floppy, here are three questions to ask yourself:-</para>
 
           <orderedlist>
             <listitem>
               <para>Did you use a new, freshly-formatted, error-free floppy
                 (preferably a brand-new one straight out of the box, as
                 opposed to the magazine cover disk that has been lying under
                 the bed for the last three years)?</para>
             </listitem>
 
             <listitem>
               <para>Did you download the floppy image in binary (or image)
                 mode? (do not be embarrassed, even the best of us have
                 accidentally downloaded a binary file in ASCII mode at
                 least once!)</para>
             </listitem>
 
             <listitem>
               <para>If you are using Windows95 or Win98 did you run
                 <command>fdimage</command> or <command>rawrite</command> in
                 pure DOS mode? These operating systems can interfere with programs that
                 write directly to hardware, which the disk creation program
                 does; even running it inside a DOS shell in the GUI can
                 cause this problem.</para>
             </listitem>
           </orderedlist>
 
           <para>There have also been reports of Netscape causing problems
             when downloading the boot floppy, so it is probably best to use
             a different FTP client if you can.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="no-install-cdrom">
           <para>I booted from my ATAPI CDROM, but the install program says no
             CDROM is found.  Where did it go?</para>
         </question>
 
         <answer>
           <para>The usual cause of this problem is a mis-configured CDROM
             drive.  Many PCs now ship with the CDROM as the slave device on
             the secondary IDE controller, with no master device on that
             controller.  This is illegal according to the ATAPI specification,
             but Windows plays fast and loose with the specification, and the
             BIOS ignores it when booting.  This is why the BIOS was able to
             see the  CDROM to boot from it, but why FreeBSD cannot see it to
             complete  the install.</para>
 
           <para>Reconfigure your system so that the CDROM is either the
             master device on the IDE controller it is attached to, or make
             sure that it is the slave on an IDE controller that also has a
             master device.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="cannot-install-tape">
           <para>Why can I not install from tape?</para>
         </question>
 
         <answer>
           <para>If you are installing 2.1.7R from tape, you  must create
             the tape using a tar blocksize of 10 (5120 bytes). The default
             tar blocksize is 20 (10240 bytes), and tapes created using this
             default size cannot be used to install 2.1.7R; with these
             tapes, you will get an error that complains about the record
             size being too big.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="install-PLIP">
           <para>Can I install on my laptop over PLIP (Parallel Line
             IP)?</para>
         </question>
 
         <answer>
           <para>Yes. Use a standard Laplink cable. If necessary, you
             can check out the <ulink url="../handbook/plip.html">PLIP
             section of the Handbook</ulink> for details on parallel
             port networking.</para>
 
           <para>If you are running FreeBSD 3.X or earlier, also look at
             the <ulink
             url="http://www.FreeBSD.org/docs.html#PAO">Mobile
             Computing page</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="geometry">
           <para>Which geometry should I use for a disk drive?</para>
         </question>
 
         <answer>
             <note>
               <para>By the <quote>geometry</quote> of a disk, we mean
               the number of cylinders, heads and sectors/track on a
               disk.  We will refer to this as C/H/S for
               convenience. This is how the PC's BIOS works out which
               area on a disk to read/write from.</para>
             </note>
 
           <para>This causes a lot of confusion among new system
             administrators.  First of all, the
             <emphasis>physical</emphasis> geometry of a SCSI drive is
             totally irrelevant, as FreeBSD works in term of disk
             blocks. In fact, there is no such thing as
             <quote>the</quote> physical geometry, as the sector
             density varies across the disk.  What manufacturers claim
             is the <quote>physical geometry</quote> is usually the
             geometry that they have determined wastes the least
             space. For IDE disks, FreeBSD does work in terms of C/H/S,
             but all modern drives internally convert this into block
             references.
             </para>
 
           <para>All that matters is the <emphasis>logical</emphasis>
             geometry.  This is the answer that the BIOS gets when it
             asks the drive <quote>what is your geometry?</quote> It
             then uses this geometry to access the disk. As FreeBSD
             uses the BIOS when booting, it is very important to get
             this right. In particular, if you have more than one
             operating system on a disk, they must all agree on the
             geometry.  Otherwise you will have serious problems
             booting!</para>
 
           <para>For SCSI disks, the geometry to use depends on whether
            extended translation support is turned on in your
            controller (this is often referred to as <quote>support for
            DOS disks &gt;1GB</quote> or something similar). If it is
            turned off, then use <replaceable>N</replaceable>
            cylinders, 64 heads and 32 sectors/track, where
            <replaceable>N</replaceable> is the capacity of the disk in
            MB. For example, a 2GB disk should pretend to have 2048
            cylinders, 64 heads and 32 sectors/track.</para>
 
           <para>If it <emphasis>is</emphasis> turned on (it is often
             supplied this way to get around certain limitations in
             MSDOS) and the disk capacity is more than 1GB, use M
             cylinders, 63 sectors per track (<emphasis>not</emphasis>
             64), and 255 heads, where 'M' is the disk capacity in MB
             divided by 7.844238 (!). So our example 2GB drive would
             have 261 cylinders, 63 sectors per track and 255
             heads.</para>
 
           <para>If you are not sure about this, or FreeBSD fails to
             detect the geometry correctly during installation, the
             simplest way around this is usually to create a small DOS
             partition on the disk. The BIOS should then detect the
             correct geometry, and you can always remove the DOS
             partition in the partition editor if you do not want to
             keep it.  You might want to leave it around for
             programming network cards and the like, however.</para>
 
           <para>Alternatively, there is a freely available utility
             distributed with FreeBSD called
             <filename>pfdisk.exe</filename>.  You can find it in the
             <filename>tools</filename> subdirectory on the FreeBSD
             CDROM or on the various FreeBSD FTP sites.  This program
             can be used to work out what geometry the other operating
             systems on the disk are using. You can then enter this
             geometry in the partition editor.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="disk-divide-restrictions">
           <para>Are there any restrictions on how I divide the disk up?</para>
         </question>
 
         <answer>
           <para>Yes. You must make sure that your root partition is below
             1024
             cylinders so the BIOS can boot the kernel from it.  (Note that
             this is a limitation in the PC's BIOS, not FreeBSD).</para>
 
           <para>For a SCSI drive, this will normally imply that the root
             partition will be in the first 1024MB (or in the first 4096MB
             if extended translation is turned on - see previous question).
             For IDE, the corresponding figure is 504MB.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="disk-manager">
           <para>Is FreeBSD compatible with any disk managers?</para>
         </question>
 
         <answer>
           <para>FreeBSD recognizes the Ontrack Disk Manager and makes
             allowances for it. Other disk managers are not supported.</para>
 
           <para>If you just want to use the disk with FreeBSD you do not
             need a disk manager. Just configure the disk for as much space
             as the BIOS can deal with (usually 504 megabytes), and FreeBSD
             should figure out how much space you really have. If you are
             using an old disk with an MFM controller, you may need to
             explicitly tell FreeBSD how many cylinders to use.</para>
 
           <para>If you want to use the disk with FreeBSD and another
             operating system, you may be able to do without a disk manager:
             just make sure the FreeBSD boot partition and the slice for
             the other operating system are in the first 1024 cylinders. If
             you are reasonably careful, a 20 megabyte boot partition should
             be plenty.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="missing-os">
           <para>When I boot FreeBSD I get <errorname>Missing Operating
             System</errorname>.  What is happening?</para>
         </question>
 
         <answer>
           <para>This is classically a case of FreeBSD and DOS or some other
             OS conflicting over their ideas of disk <link
             linkend="geometry">geometry</link>. You will have to reinstall
             FreeBSD, but obeying the instructions given above will almost
             always get you going.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="stop-at-boot-manager">
           <para>Why can I not get past the boot manager's <prompt>F?</prompt>
             prompt?</para>
         </question>
 
         <answer>
           <para>This is another symptom of the problem described in the
             preceding question. Your BIOS geometry and FreeBSD geometry
             settings do not agree! If your controller or BIOS supports
             cylinder translation (often marked as <quote>&gt;1GB drive
             support</quote>), try toggling its setting and reinstalling
             FreeBSD.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="need-complete-sources">
           <para>Do I need to install the complete sources?</para>
         </question>
 
         <answer>
           <para>In general, no.  However, we would strongly recommend that
             you install, at a minimum, the <literal>base</literal> source
             kit, which includes several of the files mentioned here, and
             the <literal>sys</literal> (kernel) source kit, which includes
             sources for the kernel. There is nothing in the system which
             requires the presence of the sources to operate, however,
             except for the kernel-configuration program &man.config.8;.
             With the exception of the kernel sources, our build structure
             is set up so that you can read-only mount the sources from
             elsewhere via NFS and still be able to make new binaries.
             (Because of the kernel-source restriction, we recommend that
             you not mount this on <filename>/usr/src</filename> directly,
             but rather in some other location with appropriate symbolic
             links to duplicate the top-level structure of the source
             tree.)</para>
 
           <para>Having the sources on-line and knowing how to build a
             system with them will make it much easier for you to upgrade
             to future releases of FreeBSD.</para>
 
           <para>To actually select a subset of the sources, use the Custom
             menu item when you are in the Distributions menu of the
             system installation tool.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="need-kernel">
           <para>Do I need to build a kernel?</para>
         </question>
 
         <answer>
           <para>Building a new kernel was originally pretty much a required
             step in a FreeBSD installation, but more recent releases have
             benefited from the introduction of a much friendlier kernel
             configuration tool. When at the FreeBSD boot prompt (boot:),
             use the <option>-c</option> flag and you will be dropped into a
             visual configuration screen which allows you to configure the
             kernel's settings for most common ISA cards.</para>
 
           <para>It is still recommended that you eventually build a new
             kernel containing just the drivers that you need, just to save a
             bit of RAM, but it is no longer a strict requirement for most
             systems.</para>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="password-encryption">
           <para>Should I use DES passwords, or MD5, and how do I specify
             which form my users receive?</para>
         </question>
 
         <answer>
           <para>The default password format on FreeBSD is to use
             <emphasis>MD5</emphasis>-based passwords. These are believed to
             be more secure than the traditional Unix password format, which
             used a scheme based on the <emphasis>DES</emphasis> algorithm.
             DES passwords are still available if you need to share your
             password file with legacy operating systems which still use the
             less secure password format (they are available if you choose
             to install the <quote>crypto</quote> distribution in
             sysinstall, or by installing the crypto sources if building
             from source). Which password format to use for new passwords is
             controlled by the <quote>passwd_format</quote> login capability
             in <filename>/etc/login.conf</filename>, which takes values of
             either <quote>des</quote> (if available) or <quote>md5</quote>.
             See the &man.login.conf.5; manual page for more information about login
             capabilities.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="boot-floppy-hangs">
           <para>Why does the boot floppy start, but hang at the
             <literal>Probing Devices...</literal> screen?</para>
         </question>
 
         <answer>
 
           <para>If you have a IDE Zip or Jaz drive installed, remove it
             and try again. The boot floppy can get confused by the drives.
             After the system is installed you can reconnect the drive.
             Hopefully this will be fixed in a later release.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="panic-on-install-reboot">
           <para>Why do I get a <errorname>panic: can't mount root</errorname>
             error when rebooting the system after installation?</para>
         </question>
 
         <answer>
           <para>This error comes from confusion between the boot block's
             and the kernel's understanding of the disk devices. The error
             usually manifests on two-disk IDE systems, with the hard disks
             arranged as the master or single device on separate IDE
             controllers, with FreeBSD installed on the secondary IDE
             controller. The boot blocks think the system is installed on
             wd1 (the second BIOS disk) while the kernel assigns the first
             disk on the secondary controller device wd2. After the device
             probing, the kernel tries to mount what the boot blocks think
             is the boot disk, wd1, while it is really wd2, and
             fails.</para>
 
           <para>To fix the problem, do one of the following:</para>
 
             <orderedlist>
               <listitem>
                 <para>For FreeBSD 3.3 and later, reboot the system and hit
                   <literal>Enter</literal> at the <literal>Booting kernel
                   in 10 seconds; hit [Enter] to interrupt</literal> prompt.
                   This will drop you into the boot loader.</para>
 
                 <para>Then type
                   <literal>
                   set root_disk_unit="<replaceable>disk_number</replaceable>"
                   </literal>. <replaceable>disk_number</replaceable>
                   will be <literal>0</literal> if FreeBSD is installed on
                   the master drive on the first IDE controller,
                   <literal>1</literal> if it is installed on the slave on
                   the first IDE controller, <literal>2</literal> if it is
                   installed on the master of the second IDE controller, and
                   <literal>3</literal> if it is installed on the slave of
                   the second IDE controller.</para>
 
                 <para>Then type <literal>boot</literal>, and your system
                   should boot correctly.</para>
 
                 <para>To make this change permanent (ie so you do not have to
                   do this every time you reboot or turn on your FreeBSD
                   machine), put the line <literal>
                   root_disk_unit="<replaceable>disk_number</replaceable>"</literal> in <filename>/boot/loader.conf.local
                   </filename>.</para>
               </listitem>
 
               <listitem>
                 <para>If using FreeBSD 3.2 or earlier, at the Boot: prompt,
                   enter <literal>1:wd(2,a)kernel</literal> and press Enter.
                   If the system starts, then run the command
                   <command>echo "1:wd(2,a)kernel" &gt; /boot.config</command>
                   to make it the default boot string.</para>
               </listitem>
 
               <listitem>
                 <para>Move the FreeBSD disk onto the primary IDE controller,
                   so the hard disks are consecutive.</para>
               </listitem>
 
               <listitem>
                 <para><ulink URL="../handbook/kernelconfig.html">Rebuild
                   your kernel,</ulink> modify the wd configuration lines to
                   read:</para>
 
                   <programlisting>controller      wdc0    at isa? port "IO_WD1" bio irq 14 vector wdintr
 disk            wd0     at wdc0 drive 0
 # disk            wd1     at wdc0 drive 1 # comment out this line
 
 controller      wdc1    at isa? port "IO_WD2" bio irq 15 vector wdintr
 disk            wd1     at wdc1 drive 0 # change from wd2 to wd1
 disk            wd2     at wdc1 drive 1 # change from wd3 to wd2</programlisting>
 
                 <para>Install the new kernel.  If you moved your disks and
                   wish to restore the previous configuration, replace the
                   disks in the desired configuration and reboot.  Your
                   system should boot successfully.</para>
               </listitem>
             </orderedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="memory-limits">
           <para>What are the limits for memory?</para>
         </question>
 
         <answer>
           <para>For memory, the limit is 4 gigabytes. This configuration
             has been tested, see <ulink
             URL="ftp://ftp.cdrom.com/archive-info/configuration">wcarchive's
             configuration</ulink> for more details. If you plan to install
             this much memory into a machine, you need to be careful. You will
             probably want to use ECC memory and to reduce capacitive
             loading use 9 chip memory modules versus 18 chip memory
             modules.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ffs-limits">
           <para>What are the limits for ffs filesystems?</para>
         </question>
 
         <answer>
           <para>For ffs filesystems, the maximum theoretical limit is 8
             terabytes (2G blocks), or 16TB for the default block size of
             8K. In practice, there is a soft limit of 1 terabyte, but with
             modifications filesystems with 4 terabytes are possible (and
             exist).</para>
 
           <para>The maximum size of a single ffs file is approximately 1G
             blocks (4TB) if the block size is 4K.</para>
 
           <table>
             <title>Maximum file sizes</title>
 
             <tgroup cols="5">
               <thead>
                 <row>
                   <entry>fs block size</entry>
 
                   <entry>2.2.7-stable</entry>
 
                   <entry>3.0-current</entry>
 
                   <entry>works</entry>
 
                   <entry>should work</entry>
                 </row>
               </thead>
 
               <tbody>
                 <row>
                   <entry>4K</entry>
 
                   <entry>4T-1</entry>
 
                   <entry>4T-1</entry>
 
                   <entry>4T-1</entry>
 
                   <entry>&gt;4T</entry>
                 </row>
 
                 <row>
                   <entry>8K</entry>
 
                   <entry>&gt;32G</entry>
 
                   <entry>8T-1</entry>
 
                   <entry>&gt;32G</entry>
 
                   <entry>32T-1</entry>
                 </row>
 
                 <row>
                   <entry>16K</entry>
 
                   <entry>&gt;128G</entry>
 
                   <entry>16T-1</entry>
 
                   <entry>&gt;128G</entry>
 
                   <entry>32T-1</entry>
                 </row>
 
                 <row>
                   <entry>32K</entry>
 
                   <entry>&gt;512G</entry>
 
                   <entry>32T-1</entry>
 
                   <entry>&gt;512G</entry>
 
                   <entry>64T-1</entry>
                 </row>
 
                 <row>
                   <entry>64K</entry>
 
                   <entry>&gt;2048G</entry>
 
                   <entry>64T-1</entry>
 
                   <entry>&gt;2048G</entry>
 
                   <entry>128T-1</entry>
                 </row>
               </tbody>
             </tgroup>
           </table>
 
           <para>When the fs block size is 4K, triple indirect blocks work
             and everything should be limited by the maximum fs block number
             that can be represented using triple indirect blocks (approx.
             1K^3 + 1K^2 + 1K), but everything is limited by a (wrong) limit
             of 1G-1 on fs block numbers. The limit on fs block numbers
             should be 2G-1. There are some bugs for fs block numbers near
             2G-1, but such block numbers are unreachable when the fs block
             size is 4K.</para>
 
           <para>For block sizes of 8K and larger, everything should be
             limited by the 2G-1 limit on fs block numbers, but is actually
             limited by the 1G-1 limit on fs block numbers, except under
             -STABLE triple indirect blocks are unreachable, so the limit is
             the maximum fs block number that can be represented using
             double indirect blocks (approx. (blocksize/4)^2 +
             (blocksize/4)), and under -CURRENT exceeding this limit may
             cause problems. Using the correct limit of 2G-1 blocks does
             cause problems.</para>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="archsw-readin-failed-error">
           <para>Why do I get an error message,
             <errorname>archsw.readin.failed</errorname> after compiling
             and booting a new kernel?</para>
         </question>
 
         <answer>
           <para>You can boot by specifying the kernel directly at the second
             stage, pressing any key when the | shows up before loader is
             started. More specifically, you have upgraded the source for
             your kernel, and installed a new kernel builtin from them
             <emphasis>without making world</emphasis>. This is not
             supported. Make world.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="upgrade-3x-4x">
            <para>How do I upgrade from 3.X -&gt; 4.X?</para>
         </question>
 
         <answer>
           <para>We <emphasis>strongly</emphasis> recommend that you use
             binary snapshots to do this. 4-STABLE snapshots are available at
             <ulink
             URL="ftp://releng4.FreeBSD.org/">ftp://releng4.FreeBSD.org/</ulink>.</para>
 
           <para>Because of the many changes between 3.X and 4-STABLE,
             a direct upgrade from source will probably fail.  A source
             upgrade can be done, but only in stages.  First, upgrade
             to the latest 3-STABLE (<literal>RELENG_3</literal>).
             Then upgrade to 4.1.1-RELEASE
             (<literal>RELENG_4_1_1_RELEASE</literal>).  Finally,
             upgrade to 4-STABLE (<literal>RELENG_4</literal>).</para>
 
           <para>If you wish to upgrade using source, please see the <ulink
             URL="../handbook/cutting-edge.html">FreeBSD
             Handbook</ulink> for more information.</para>
 
           <caution>
           <para>Upgrading via source is never recommended for new
             users, and upgrading from 3.X to 4.X is even less so; make sure
             you have read the instructions carefully before attempting to
             upgrade via source.</para>
           </caution>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="security-profiles">
           <para>What are these <quote>security profiles</quote>?</para>
         </question>
 
         <answer>
           <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.  For full details, see the <ulink
             url="../handbook/install-post.html#SECURITYPROFILE">Security
             Profile</ulink> section of the Handbook's <ulink
             url="../handbook/install-post.html">post-install
             chapter</ulink>.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter
     id="hardware">
     <title>Hardware compatibility</title>
 
     <qandaset>
       <qandaentry>
         <question id="architectures">
           <para>Does FreeBSD support architectures other than the
             x86?</para>
         </question>
 
         <answer>
 
           <para>Yes.  FreeBSD currently runs on both Intel x86 and
             DEC (now Compaq) Alpha architectures.  Interest has also
             been expressed in a port of FreeBSD to the SPARC architecture,
 	    join the &a.sparc; if you are interested in joining that project.
 	    Most recent additions to the list of upcoming platforms are
 	    IA-64 and PowerPC, join the &a.ia64; and/or the &a.ppc; for more
 	    information.  For general discussion on new architectures, join
 	    the &a.platforms;.</para>
 
           <para>If your machine has a different architecture and you need
             something right now, we suggest you look at <ulink
             URL="http://www.netbsd.org/">NetBSD</ulink> or <ulink
             URL="http://www.openbsd.org/">OpenBSD</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="which-hardware-to-get">
           <para>I want to get a piece of hardware for my FreeBSD
             system.  Which model/brand/type is best?</para>
         </question>
 
         <answer>
           <para>This is discussed continually on the FreeBSD mailing
             lists.  Since hardware changes so quickly, however, we
             expect this.  We <emphasis>still</emphasis> strongly
             recommend that you read through the 
 	    <ulink URL="&rel.current.hardware;">Hardware Notes</ulink>
 	    and search the mailing list
             <ulink URL="http://www.freebsd.org/search/#mailinglists">
             archives</ulink> before asking about the latest and
             greatest hardware.  Chances are a discussion about the
             type of hardware you are looking for took place just last
             week.</para>
 
           <para>If you are looking for a laptop, check the
             FreeBSD-mobile mailing list archives.  Otherwise, you
             probably want the archives for FreeBSD-questions, or
             possibly a specific mailing list for a particular hardware
             type.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="supported-hard-drives">
           <para>What kind of hard drives does FreeBSD support?</para>
         </question>
 
         <answer>
           <para>FreeBSD supports EIDE and SCSI drives (with a compatible
             controller; see the next section), and all drives using the
             original <quote>Western Digital</quote> interface (MFM, RLL,
             ESDI, and of course IDE). A few ESDI controllers that use
             proprietary interfaces may not work: stick to WD1002/3/6/7
             interfaces and clones.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="supported-scsi-controllers">
           <para>Which SCSI controllers are supported?</para>
         </question>
 
         <answer>
           <para>See the complete list in the current <ulink
             URL="&rel.current.hardware;">Hardware Notes</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="supported-cdrom-drives">
           <para>Which CDROM drives are supported by FreeBSD?</para>
         </question>
 
         <answer>
           <para>Any SCSI drive connected to a supported controller is
             supported.</para>
 
           <para>The following proprietary CDROM interfaces are also
             supported:</para>
 
             <itemizedlist>
               <listitem>
                 <para>Mitsumi LU002 (8bit), LU005 (16bit) and FX001D
                   (16bit 2x Speed).</para>
               </listitem>
 
               <listitem>
                 <para>Sony CDU 31/33A</para>
               </listitem>
 
               <listitem>
                 <para>Sound Blaster Non-SCSI CDROM</para>
               </listitem>
 
               <listitem>
                 <para>Matsushita/Panasonic CDROM</para>
               </listitem>
 
               <listitem>
                 <para>ATAPI compatible IDE CDROMs</para>
               </listitem>
             </itemizedlist>
 
           <para>All non-SCSI cards are known to be extremely slow compared
             to SCSI drives, and some ATAPI CDROMs may not work.</para>
 
           <para>As of 2.2 the FreeBSD CDROM from the FreeBSD Mall supports
             booting directly from the CD.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="supported-cdrw-drives">
           <para>Which CD-RW drives are supported by FreeBSD?</para>
         </question>
 
 	<answer>
 	  <para>FreeBSD supports any ATAPI-compatible IDE CD-R or CD-RW
 	    drive.  For FreeBSD versions 4.0 and later, see the man page for
 	      &man.burncd.8;.  For earlier FreeBSD versions, see the examples
 	    in <filename>/usr/share/examples/atapi</filename>.</para>
 
 	  <para>FreeBSD also supports any SCSI CD-R or CD-RW drives.
 	    Install and use the <command>cdrecord</command> command from the
 	    ports or packages system, and make sure that you have the
 	    <devicename>pass</devicename> device compiled in your
 	    kernel.</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
         <question id="zip-support">
           <para>Does FreeBSD support ZIP drives?</para>
         </question>
 
         <answer>
           <para>FreeBSD supports the SCSI ZIP drive out of the box, of
             course. The ZIP drive can only be set to run at SCSI target IDs
             5 or 6, but if your SCSI host adapter's BIOS supports it you
             can even boot from it.  It is not clear which host
             adapters support booting from targets other than 0 or 1,
             so you will have to consult your adapter's documentation
             if you would like to use this feature.</para>
 
           <para>ATAPI (IDE) Zip drives are supported in FreeBSD 2.2.6 and
             later releases.</para>
 
           <para>FreeBSD has contained support for Parallel Port Zip Drives
             since version 3.0. If you are using a sufficiently up to date
             version, then you should check that your kernel contains the
             <devicename>scbus0</devicename>, <devicename>da0</devicename>,
             <devicename>ppbus0</devicename>, and
             <devicename>vp0</devicename> drivers (the GENERIC kernel
             contains everything except <devicename>vp0</devicename>). With
             all these drivers present, the Parallel Port drive should be
             available as <devicename>/dev/da0s4</devicename>. Disks can be
             mounted using <command>mount /dev/da0s4 /mnt</command> OR (for
             dos disks) <command>mount_msdos /dev/da0s4 /mnt</command> as
             appropriate.</para>
 
           <para>Also check out <link linkend="jaz">the FAQ on removable
             drives</link> later in this chapter, and <link linkend="disklabel">the note on
             <quote>formatting</quote></link>in the Administration chapter.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="jaz-zip-removable-support">
           <para>Does FreeBSD support JAZ, EZ and other removable
             drives?</para>
         </question>
 
         <answer>
           <para>Apart from the IDE version of the EZ drive, these are all
             SCSI devices, so they should all look like SCSI disks to
             FreeBSD, and the IDE EZ should look like an IDE drive.</para>
 
           <para><anchor id="jaz">I am not sure how well FreeBSD supports
             changing the media out while running. You will of course need
             to dismount the drive before swapping media, and make sure that
             any external units are powered on when you boot the system so
             FreeBSD can see them.</para>
 
           <para>See <link linkend="disklabel">this note on
             <quote>formatting</quote></link>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="multiport-serial-support">
           <para>Which multi-port serial cards are supported by
             FreeBSD?</para>
         </question>
 
         <answer>
           <para>There is a list of these in the <ulink
             URL="../handbook/install.html#INSTALL-MISC">Miscellaneous
             devices</ulink> section of the handbook.</para>
 
           <para>Some unnamed clone cards have also been known to work,
             especially those that claim to be AST compatible.</para>
 
           <para>Check the &man.sio.4;
             man page to get more information on configuring such cards.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="usbkbd">
           <para>Does FreeBSD support my USB keyboard?</para>
         </question>
 
         <answer>
           <para>USB device support was added to FreeBSD 3.1.  However, it
             is still in preliminary state and may not always work as of
             version 3.2. If you want to experiment with the USB keyboard
             support, follow the procedure described below.</para>
 
           <procedure>
             <step>
               <para>Use FreeBSD 3.2 or later.</para>
             </step>
 
             <step>
               <para>Add the following lines to your kernel configuration
                 file, and rebuild the kernel.</para>
 
               <programlisting>device  uhci
 device  ohci
 device  usb
 device  ukbd
 options KBD_INSTALL_CDEV</programlisting>
 
               <para>In versions of FreeBSD before 4.0, use this
                 instead:</para>
 
               <programlisting>controller      uhci0
 controller      ohci0
 controller      usb0
 controller      ukbd0
 options         KBD_INSTALL_CDEV</programlisting>
             </step>
 
             <step>
               <para>Go to the <filename>/dev</filename> directory and create
                 device nodes as follows:</para>
 
               <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>./MAKEDEV kbd0 kbd1</userinput></screen>
 
             </step>
 
             <step>
               <para>Edit <filename>/etc/rc.conf</filename> and add the
                 following lines:</para>
 
               <programlisting>usbd_enable="YES"
 usbd_flags=""</programlisting>
 
             </step>
           </procedure>
 
           <para>After the system is rebooted, the AT keyboard becomes
             <devicename>/dev/kbd0</devicename> and the USB keyboard becomes
             <devicename>/dev/kbd1</devicename>, if both are connected to the
             system.  If there is the USB keyboard only, it will be
             <devicename>/dev/ukbd0</devicename>.</para>
 
           <para>If you want to use the USB keyboard in the console, you
             have to explicitly tell the console driver to use the existing
             USB keyboard. This can be done by running the following
             command as a part of system initialization.</para>
 
           <screen>&prompt.root; <userinput>kbdcontrol -k /dev/kbd1 &lt; /dev/ttyv0 &gt; /dev/null</userinput></screen>
 
           <para>Note that if the USB keyboard is the only keyboard, it is
             accessed as <devicename>/dev/kbd0</devicename>, thus, the command
             should look like:</para>
 
           <screen>&prompt.root; <userinput>kbdcontrol -k /dev/kbd0 &lt; /dev/ttyv0 &gt; /dev/null</userinput></screen>
 
           <para><filename>/etc/rc.i386</filename> is a good place to add the
             above command.</para>
 
           <para>Once this is done, the USB keyboard should work in the X
             environment as well without any special settings.</para>
 
           <para>Hot-plugging and unplugging of the USB keyboard may not
             work quite right yet. It is a good idea to connect the keyboard
             before you start the system and leave it connected until the
             system is shutdown to avoid troubles.</para>
 
           <para>See the &man.ukbd.4; man page for more information.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="busmouse">
           <para>I have an unusual bus mouse. How do I set it up?</para>
         </question>
 
         <answer>
           <para>FreeBSD supports the bus mouse and the InPort bus mouse
             from such manufactures as Microsoft, Logitech and ATI. The bus
             device driver is compiled in the GENERIC kernel by default in
             FreeBSD versions 2.X, but not included in version 3.0 or later.
             If you are building a custom kernel with the bus mouse driver,
             make sure to add the following line to the kernel config
             file</para>
 
           <para>In FreeBSD 3.0 or before, add:</para>
 
           <programlisting>device mse0 at isa? port 0x23c tty irq5 vector mseintr</programlisting>
 
           <para>In FreeBSD 3.X, the line should be:</para>
 
           <programlisting>device mse0 at isa? port 0x23c tty irq5</programlisting>
 
           <para>And in FreeBSD 4.X and later, the line should read:</para>
 
           <programlisting>device mse0 at isa? port 0x23c irq5</programlisting>
 
           <para>Bus mice usually comes with dedicated interface cards.
             These cards may allow you to set the port address and the IRQ
             number other than shown above. Refer to the manual of your
             mouse and the &man.mse.4; man page for more information.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ps2mouse">
           <para>How do I use my PS/2 (<quote>mouse port</quote> or
             <quote>keyboard</quote>) mouse?</para>
         </question>
 
         <answer>
 
           <para>If you are running a post-2.2.5 version of FreeBSD, the
             necessary driver, <devicename>psm</devicename>, is included and
             enabled in the kernel. The kernel should detect your PS/2 mouse
             at boot time.</para>
 
           <para>If you are running a previous but relatively recent version
             of FreeBSD (2.1.x or better) then you can simply enable it in
             the kernel configuration menu at installation time, otherwise
             later with <option>-c</option> at the <command>boot:</command>
             prompt. It is disabled by default, so you will need to enable
             it explicitly.</para>
 
           <para>If you are running an older version of FreeBSD then you will
             have to add the following lines to your kernel configuration
             file and compile a new kernel.</para>
 
           <para>In FreeBSD 3.0 or earlier, the line should be:</para>
 
           <programlisting>device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr</programlisting>
 
           <para>In FreeBSD 3.1 or later, the line should be:</para>
 
           <programlisting>device psm0 at isa? tty irq 12</programlisting>
 
           <para>In FreeBSD 4.0 or later, the line should be:</para>
 
           <programlisting>device psm0 at atkbdc? irq 12</programlisting>
 
           <para>See the <ulink
             URL="../handbook/kernelconfig.html">Handbook entry on
             configuring the kernel</ulink> if you have no experience with
             building kernels.</para>
 
           <para>Once you have a kernel detecting
             <devicename>psm0</devicename> correctly at boot time, make sure
             that an entry for <devicename>psm0</devicename> exists in
             <filename>/dev</filename>.  You can do this by typing:</para>
 
           <screen>&prompt.root; <userinput>cd /dev; sh MAKEDEV psm0</userinput></screen>
 
           <para>when logged in as <username>root</username>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="moused">
           <para>Is it possible to make use of a mouse in any way outside
             the X Window system?</para>
         </question>
 
         <answer>
           <para>If you are using the default console driver, syscons, you
             can use a mouse pointer in text consoles to cut &amp; paste
             text. Run the mouse daemon, moused, and turn on the mouse
             pointer in the virtual console:</para>
 
           <screen>&prompt.root; <userinput>moused -p /dev/<replaceable>xxxx</replaceable> -t <replaceable>yyyy</replaceable></userinput>
 &prompt.root; <userinput>vidcontrol -m on</userinput></screen>
 
           <para>Where <replaceable>xxxx</replaceable> is the mouse device
             name and <replaceable>yyyy</replaceable> is a protocol type for
             the mouse.  See the &man.moused.8; man page for supported
             protocol types.</para>
 
           <para>You may wish to run the mouse daemon automatically when the
             system starts.  In version 2.2.1, set the following variables in
             <filename>/etc/sysconfig</filename>.</para>
 
           <programlisting>mousedtype="yyyy"
 mousedport="xxxx"
 mousedflags=""</programlisting>
 
           <para>In versions 2.2.2 to 3.0, set the following variables in
             <filename>/etc/rc.conf</filename>.</para>
 
           <programlisting>moused_type="yyyy"
 moused_port="xxxx"
 moused_flags=""</programlisting>
 
           <para>In 3.1 and later, assuming you have a PS/2 mouse, all you
             need to is add <literal>moused_enable="YES"</literal> to
             <filename>/etc/rc.conf</filename>.</para>
 
           <para>In addition, if you would like to be able to use the mouse
             daemon on all virtual terminals instead of just console at
             boot-time, add the following to
             <filename>/etc/rc.conf</filename>.</para>
 
           <programlisting>allscreens_flags="-m on"</programlisting>
 
           <para>Staring from FreeBSD 2.2.6, the mouse daemon is capable of
             determining the correct protocol type automatically unless the
             mouse is a relatively old serial mouse model. Specify
             <literal>auto</literal> the protocol to invoke automatic
             detection.</para>
 
           <para>When the mouse daemon is running, access to the mouse
             needs to be coordinated between the mouse daemon and other
             programs such as the X Window. Refer to <link
             linkend="x-and-moused">another section</link> on this
             issue.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="text-mode-cut-paste">
           <para>How do I cut and paste text with mouse in the text
             console?</para>
         </question>
 
         <answer>
           <para>Once you get the mouse daemon running (see
             <link linkend="moused">previous section</link>), hold down the
             button 1 (left button) and move the mouse to select a region of
             text. Then, press the button 2 (middle button) or the button 3
             (right button) to paste it at the text cursor.</para>
 
           <para>In versions 2.2.6 and later, pressing the button 2 will
             paste the text. Pressing the button 3 will
             <quote>extend</quote> the selected region of text. If your
             mouse does not have the middle button, you may wish to emulate
             it or remap buttons using moused options. See the
             &man.moused.8; man page for details.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="usbmouse">
           <para>Does FreeBSD support any USB mice?</para>
         </question>
 
         <answer>
 
           <para>Preliminary USB device support was added to FreeBSD
             3.1.  It did not always work through early versions of
             3.X.  As of FreeBSD 4.0, USB devices should work out of
             the box.  If you want to experiment with the USB mouse
             support under FreeBSD 3.X, follow the procedure described
             below.</para>
 
           <procedure>
             <step>
               <para>Use FreeBSD 3.2 or later.</para>
             </step>
 
             <step>
               <para>Add the following lines to your kernel configuration
                 file, and rebuild the kernel.</para>
 
               <programlisting>device  uhci
 device  ohci
 device  usb
 device  ums</programlisting>
 
               <para>In versions of FreeBSD before 4.0, use this
                 instead:</para>
 
               <programlisting>controller        uhci0
 controller        ohci0
 controller        usb0
 device            ums0</programlisting>
             </step>
 
             <step>
               <para>Go to the <filename>/dev</filename> directory and
                 create a device node as follows:</para>
 
               <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>./MAKEDEV ums0</userinput></screen>
             </step>
 
             <step>
               <para>Edit <filename>/etc/rc.conf</filename> and add the
                 following lines:</para>
 
               <programlisting>moused_enable="YES"
 moused_type="auto"
 moused_port="/dev/ums0"
 moused_flags=""
 usbd_enable="YES"
 usbd_flags=""</programlisting>
 
               <para>See the <link linkend="moused">previous section</link>
                 for more detailed discussion on moused.</para>
             </step>
 
             <step>
               <para>In order to use the USB mouse in the X session, edit
                 <filename>XF86Config</filename>.  If you are using XFree86
                 3.3.2 or later, be sure to have the following lines in the
                 <emphasis>Pointer</emphasis> section:</para>
 
               <programlisting>Device          "/dev/sysmouse"
 Protocol        "Auto"</programlisting>
 
               <para>If you are using earlier versions of XFree86, be sure to
                 have the following lines in the <emphasis>Pointer</emphasis>
                 section:</para>
 
               <programlisting>Device          "/dev/sysmouse"
 Protocol        "SysMouse"</programlisting>
             </step>
           </procedure>
 
           <para>Refer to <link linkend="x-and-moused">another section</link>
             on the mouse support in the X environment.</para>
 
           <para>Hot-plugging and unplugging of the USB mouse may not work
             quite right yet. It is a good idea connect the mouse before you
             start the system and leave it connected until the system is
             shutdown to avoid trouble.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="mouse-wheel-buttons">
           <para>My mouse has a fancy wheel and buttons.  Can I use them in
             FreeBSD?</para>
         </question>
 
         <answer>
           <para>The answer is, unfortunately, <quote>It depends</quote>.
             These mice with additional features require specialized driver
             in most cases. Unless the mouse device driver or the user
             program has specific support for the mouse, it will act just
             like a standard two, or three button mouse.</para>
 
           <para>For the possible usage of wheels in the X Window
             environment, refer to <link linkend="x-and-wheel">that
             section</link>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="psmerr">
           <para>Why does my wheel-equipped PS/2 mouse cause my mouse cursor
             to jump around the screen?</para>
         </question>
 
         <answer>
           <para>The PS/2 mouse driver psm in FreeBSD versions 3.2 or
             earlier has difficulty with some wheel mice, including Logitech
             model M-S48 and its OEM siblings. Apply the following patch to
             <filename>/sys/i386/isa/psm.c</filename> and rebuild the
             kernel.</para>
 
           <programlisting>Index: psm.c
 ===================================================================
 RCS file: /src/CVS/src/sys/i386/isa/Attic/psm.c,v
 retrieving revision 1.60.2.1
 retrieving revision 1.60.2.2
 diff -u -r1.60.2.1 -r1.60.2.2
 --- psm.c        1999/06/03 12:41:13 1.60.2.1
 +++ psm.c        1999/07/12 13:40:52 1.60.2.2
 @@ -959,14 +959,28 @@
      sc->mode.packetsize = vendortype[i].packetsize;
 
      /* set mouse parameters */
 +#if 0
 +    /*
 +     * A version of Logitech FirstMouse+ won't report wheel movement,
 +     * if SET_DEFAULTS is sent...  Don't use this command.
 +     * This fix was found by Takashi Nishida.
 +     */
      i = send_aux_command(sc->kbdc, PSMC_SET_DEFAULTS);
      if (verbose >= 2)
          printf("psm%d: SET_DEFAULTS return code:%04x\n", unit, i);
 +#endif
      if (sc->config & PSM_CONFIG_RESOLUTION) {
          sc->mode.resolution
              = set_mouse_resolution(sc->kbdc,
 -                (sc->config & PSM_CONFIG_RESOLUTION) - 1);
 +                       (sc->config & PSM_CONFIG_RESOLUTION) - 1);
 +    } else if (sc->mode.resolution >= 0) {
 +        sc->mode.resolution
 +            = set_mouse_resolution(sc->kbdc, sc->dflt_mode.resolution);
 +    }
 +    if (sc->mode.rate > 0) {
 +        sc->mode.rate = set_mouse_sampling_rate(sc->kbdc, sc->dflt_mode.rate);
      }
 +    set_mouse_scaling(sc->kbdc, 1);
 
      /* request a data packet and extract sync. bits */
      if (get_mouse_status(sc->kbdc, stat, 1, 3) < 3) {</programlisting>
 
           <para>Versions later than 3.2 should be all right.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="laptop-mouse-trackball">
           <para>How do I use the mouse/trackball/touchpad on my
             laptop?</para>
         </question>
 
         <answer>
           <para>Please refer to <link linkend="ps2mouse">the answer to
             the previous question</link>.  Also check out the <ulink
             url="http://www.FreeBSD.org/docs.html#PAO">Mobile
             Computing page</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="tape-support">
           <para>What types of tape drives are supported?</para>
         </question>
 
         <answer>
 
           <para>FreeBSD supports SCSI and QIC-36 (with a QIC-02 interface).
             This includes 8-mm (aka Exabyte) and DAT drives.</para>
 
           <para>Some of the early 8-mm drives are not quite compatible
           with SCSI-2, and may not work well with FreeBSD.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="tape-changer-support">
           <para>Does FreeBSD support tape changers?</para>
         </question>
 
         <answer>
           <para>FreeBSD 2.2 supports SCSI changers using the
             &man.ch.4;
             device and the
             &man.chio.1;
             command. The details of how you actually control the changer
             can be found in the
             &man.chio.1;
             man page.</para>
 
           <para>If you are not using <application>AMANDA</application>
             or some other product that already understands changers,
             remember that they only know how to move a tape from one
             point to another, so you need to keep track of which slot a
             tape is in, and which slot the tape currently in the drive
             needs to go back to.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="sound-card-support">
           <para>Which sound cards are supported by FreeBSD?</para>
         </question>
 
         <answer>
           <para>FreeBSD supports the SoundBlaster, SoundBlaster Pro,
             SoundBlaster 16, Pro Audio Spectrum 16, AdLib and Gravis
             UltraSound sound cards. There is also limited support for
             MPU-401 and compatible MIDI cards. Cards conforming to the
             Microsoft Sound System specification are also supported through
             the pcm driver.</para>
 
             <note>
               <para>This is only for sound!  This driver does not support
                 CDROMs, SCSI or joysticks on these cards, except for the
                 SoundBlaster. The SoundBlaster SCSI interface and some
                 non-SCSI CDROMs are supported, but you cannot boot off this
                 device.</para>
              </note>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="es1370-silent-pcm">
           <para>Workarounds for no sound from es1370 with pcm driver?</para>
         </question>
 
         <answer>
           <para>You can run the following command every time the machine
             booted up:</para>
 
           <screen>&prompt.root; <userinput>mixer pcm 100 vol 100 cd 100</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="network-cards">
           <para>Which network cards does FreeBSD support?</para>
         </question>
 
         <answer>
           <para>See the <ulink
             URL="../handbook/install.html#INSTALL-NICS">
             Ethernet cards</ulink> section of the handbook for a more
             complete list.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="no-math-coprocessor">
           <para>I do not have a math co-processor - is that bad?</para>
         </question>
 
         <answer>
             <note>
               <para>This will only affect 386/486SX/486SLC owners - other
                 machines will have one built into the CPU.</para>
             </note>
 
           <para>In general this will not cause any problems, but there are
             circumstances where you will take a hit, either in performance
             or accuracy of the math emulation code (see the section <link
             linkend="emul">on FP emulation</link>). In particular, drawing
             arcs in X will be VERY slow. It is highly recommended that you
             buy a math co-processor; it is well worth it.</para>
 
             <note>
               <para>Some math co-processors are better than others.  It
                 pains us to say it, but nobody ever got fired for buying
                 Intel. Unless you are sure it works with FreeBSD, beware of
                 clones.</para>
             </note>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="other-device-support">
           <para>What other devices does FreeBSD support?</para>
         </question>
 
         <answer>
           <para>See the <ulink
             URL="../handbook/install.html#INSTALL-MISC">Handbook</ulink>
             for the list of other devices supported.</para>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="power-management-support">
           <para>Does FreeBSD support power management on my laptop?</para>
         </question>
 
         <answer>
           <para>FreeBSD supports <acronym>APM</acronym> on certain machines.  Please look in
             the <filename>LINT</filename> kernel config file, searching for
             the
             <acronym>APM</acronym>
             keyword.  Further information can be found in &man.apm.4;.</para>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="micron-hang-boot">
           <para>Why does my Micron system hang at boot time?</para>
         </question>
 
         <answer>
           <para>Certain Micron motherboards have a non-conforming PCI BIOS
             implementation that causes grief when FreeBSD boots because PCI
             devices do not get configured at their reported addresses.</para>
 
           <para>Disable the <quote>Plug and Play Operating System</quote>
             flag in the BIOS to work around this problem. More information
             can be found at <ulink
             URL="http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron">
             http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron</ulink></para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="newer-adaptec-support">
           <para>Why does FreeBSD not recognize my Adaptec SCSI
             controller card?</para>
         </question>
 
         <answer>
           <para>The newer AIC789x series Adaptec chips are supported under
             the CAM SCSI framework which made its debut in 3.0. Patches
             against 2.2-STABLE are in <ulink
             URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/cam/">
             ftp://ftp.FreeBSD.org/pub/FreeBSD/development/cam/</ulink>.
             A CAM-enhanced boot floppy is available at <ulink
             URL="http://people.FreeBSD.org/~abial/cam-boot/">
             http://people.FreeBSD.org/~abial/cam-boot/</ulink>.
             In both cases read the README before beginning.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="internal-plugnplay-modem">
           <para>Why is FreeBSD not finding my internal Plug &amp; Play
             modem?</para>
         </question>
 
         <answer>
           <para>You will need to add the modem's PnP ID to the PnP ID
             list in the serial driver. To enable Plug &amp; Play support,
             compile a new kernel with <literal>controller pnp0</literal> in
             the configuration file, then reboot the system. The kernel will
             print the PnP IDs of all the devices it finds. Copy the PnP ID
             from the modem to the table in
             <filename>/sys/i386/isa/sio.c</filename>, at about line 2777.
             Look for the string <literal>SUP1310</literal> in the structure
             <literal>siopnp_ids[]</literal> to find the table. Build the
             kernel again, install, reboot, and your modem should be
             found.</para>
 
           <para>You may have to manually configure the PnP devices using
             the <literal>pnp</literal> command in the boot-time
             configuration with a command like</para>
 
           <programlisting>pnp 1 0 enable os irq0 3 drq0 0 port0 0x2f8</programlisting>
 
           <para>to make the modem show.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="support-winmodem">
           <para>Does FreeBSD support software modems, such as
             Winmodems?</para>
         </question>
 
         <answer>
           <para>FreeBSD supports many software modems via add-on
             software.  The <filename role="package">comms/ltmdm</filename> port adds
             support for modems based on the very popular Lucent LT
             chipset.  The <filename role="package">comms/mwavem</filename> port
             supports the modem in IBM Thinkpad 600 and 700
             laptops.</para>
 
           <para>You cannot install FreeBSD via a software modem; this
             software must be installed after the OS is
             installed.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="serial-console-prompt">
           <para>How do I get the boot: prompt to show on the serial
             console?</para>
         </question>
 
         <answer>
             <orderedlist>
               <listitem>
                 <para>Build a kernel with
                   <literal>options COMCONSOLE</literal>.</para>
               </listitem>
 
               <listitem>
                 <para>Create /boot.config and place <option>-P</option>
                   as the only text in the file.</para>
               </listitem>
 
               <listitem>
                 <para>Unplug the keyboard from the system.</para>
               </listitem>
             </orderedlist>
 
           <para>See
             <filename>/usr/src/sys/i386/boot/biosboot/README.serial</filename>
             for information.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="micron-3comnic-failure">
           <para>Why does my 3Com PCI network card not work with my Micron
             computer?</para>
         </question>
 
         <answer>
           <para>Certain Micron motherboards have a non-conforming PCI BIOS
             implementation that does not configure PCI devices at the
             addresses reported. This causes grief when FreeBSD
             boots.</para>
 
           <para>To work around this problem, disable the
             <quote>Plug and Play Operating System</quote> flag in the
             BIOS.</para>
 
           <para>More information on this problem is available at URL:
             <ulink URL="http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron">http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron</ulink></para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="smp-support">
           <para>Does FreeBSD support Symmetric Multiprocessing (SMP)?</para>
         </question>
 
         <answer>
           <para>SMP is supported in 3.0-STABLE and later releases only.
             SMP is not enabled in the <emphasis>GENERIC</emphasis> kernel,
             so you will have to recompile your kernel to enable SMP. Take a
             look at <filename>/sys/i386/conf/LINT</filename> to figure out
             what options to put in your kernel config file.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="asusk7v-boot-failure">
           <para>The boot floppy hangs on a system with an ASUS K7V
             motherboard.  How do I fix this?</para>
         </question>
 
         <answer>
           <para>Go in to the BIOS setup and disable the <quote>boot virus
             protection</quote>.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="troubleshoot">
     <title>Troubleshooting</title>
 
     <qandaset>
       <qandaentry>
         <question id="awre">
           <para>What do I do when I have bad blocks on my hard drive?</para>
         </question>
 
         <answer>
           <para>With SCSI drives, the drive should be capable of re-mapping
             these automatically.  However, many drives are shipped with
             this feature disabled, for some mysterious reason...</para>
 
           <para>To enable this, you will need to edit the first device page
             mode, which can be done on FreeBSD by giving the command
             (as <username>root</username>)</para>
 
           <screen>&prompt.root; <userinput>scsi -f /dev/rsd0c -m 1 -e -P 3</userinput></screen>
 
           <para>and changing the values of AWRE and ARRE from 0 to 1:-</para>
 
           <programlisting>AWRE (Auto Write Reallocation Enbld):  1
 ARRE (Auto Read Reallocation Enbld):  1</programlisting>
 
           <para>The following paragraphs were submitted by Ted Mittelstaedt
             <email>tedm@toybox.placo.com</email>:</para>
 
           <para>For IDE drives, any bad block is usually a sign of
             potential trouble. All modern IDE drives come with internal
             bad-block remapping turned on. All IDE hard drive manufacturers
             today offer extensive warranties and will replace drives with
             bad blocks on them.</para>
 
           <para>If you still want to attempt to rescue an IDE drive with
             bad blocks, you can attempt to download the IDE drive
             manufacturer's IDE diagnostic program, and run this against the
             drive. Sometimes these programs can be set to force the drive
             electronics to rescan the drive for bad blocks and lock them
             out.</para>
 
           <para>For ESDI, RLL and MFM drives, bad blocks are a normal part
             of the drive and are no sign of trouble, generally. With a PC,
             the disk drive controller card and BIOS handle the task of
             locking out bad sectors. This is fine for operating systems
             like DOS that use BIOS code to access the disk. However,
             FreeBSD's disk driver does not go through BIOS, therefore a
             mechanism, bad144, exists that replaces this functionality.
             bad144 only works with the wd driver (which means it is not
             supported in FreeBSD 4.0), it is NOT able to be used with SCSI.
             bad144 works by entering all bad sectors found into a special
             file.</para>
 
           <para>One caveat with bad144 - the bad block special file is
             placed on the last track of the disk. As this file may possibly
             contain a listing for a bad sector that would occur near the
             beginning of the disk, where the /kernel file might be located,
             it therefore must be accessible to the bootstrap program that
             uses BIOS calls to read the kernel file. This means that the
             disk with bad144 used on it must not exceed 1024 cylinders, 16
             heads, and 63 sectors. This places an effective limit of 500MB
             on a disk that is mapped with bad144.</para>
 
           <para>To use bad144, simply set the <quote>Bad Block</quote>
             scanning to ON in the FreeBSD fdisk screen during the initial
             install. This works up through FreeBSD 2.2.7. The disk must
             have less than 1024 cylinders. It is generally recommended that
             the disk drive has been in operation for at least 4 hours prior
             to this to allow for thermal expansion and track
             wandering.</para>
 
           <para>If the disk has more than 1024 cylinders (such as a large
             ESDI drive) the ESDI controller uses a special translation mode
             to make it work under DOS. The wd driver understands about
             these translation modes, IF you enter the
             <quote>translated</quote> geometry with the <quote>set
             geometry</quote> command in fdisk. You must also NOT use the
             <quote>dangerously dedicated</quote> mode of creating the
             FreeBSD partition, as this ignores the geometry. Also, even
             though fdisk will use your overridden geometry, it still knows
             the true size of the disk, and will attempt to create a too
             large FreeBSD partition. If the disk geometry is changed to the
             translated geometry, the partition MUST be manually created
             with the number of blocks.</para>
 
           <para>A quick trick to use is to set up the large ESDI disk with
             the ESDI controller, boot it with a DOS disk and format it with
             a DOS partition. Then, boot the FreeBSD install and in the
             fdisk screen, read off and write down the blocksize and block
             numbers for the DOS partition. Then, reset the geometry to the
             same that DOS uses, delete the DOS partition, and create a
             <quote>cooperative</quote> FreeBSD partition using the
             blocksize you recorded earlier. Then, set the partition
             bootable and turn on bad block scanning. During the actual
             install, bad144 will run first, before any filesystems are
             created. (you can view this with an Alt-F2) If it has any
             trouble creating the badsector file, you have set too large a
             disk geometry - reboot the system and start all over again
             (including repartitioning and reformatting with DOS).</para>
 
           <para>If remapping is enabled and you are seeing bad blocks,
             consider replacing the drive. The bad blocks will only get
             worse as time goes on.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="bustek742a-eisa-scsi">
           <para>Why does FreeBSD not recognize my Bustek 742a EISA
             SCSI controller?</para>
         </question>
 
         <answer>
           <para>This info is specific to the 742a but may also cover
             other Buslogic cards.  (Bustek = Buslogic)</para>
 
           <para>There are 2 general <quote>versions</quote> of the 742a
             card. They are hardware revisions A-G, and revisions H -
             onwards. The revision letter is located after the Assembly
             number on the edge of the card. The 742a has 2 ROM chips on it,
             one is the BIOS chip and the other is the Firmware chip.
             FreeBSD does not care what version of BIOS chip you have but it
             does care about what version of firmware chip. Buslogic will
             send upgrade ROMs out if you call their tech support dept. The
             BIOS and Firmware chips are shipped as a matched pair. You must
             have the most current Firmware ROM in your adapter card for
             your hardware revision.</para>
 
           <para>The REV A-G cards can only accept BIOS/Firmware sets up to
             2.41/2.21. The REV H- up cards can accept the most current
             BIOS/Firmware sets of 4.70/3.37. The difference between the
             firmware sets is that the 3.37 firmware supports <quote>round
             robin</quote></para>
 
           <para>The Buslogic cards also have a serial number on them.  If
             you have a old hardware revision card you can call the Buslogic
             RMA department and give them the serial number and attempt to
             exchange the card for a newer hardware revision. If the card is
             young enough they will do so.</para>
 
           <para>FreeBSD 2.1 only supports Firmware revisions 2.21 onward.
             If you have a Firmware revision older than this your card will
             not be recognized as a Buslogic card. It may be recognized as
             an Adaptec 1540, however. The early Buslogic firmware contains
             an AHA1540 <quote>emulation</quote> mode. This is not a good
             thing for an EISA card, however.</para>
 
           <para>If you have an old hardware revision card and you obtain
             the 2.21 firmware for it, you will need to check the position
             of jumper W1 to B-C, the default is A-B.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="hpnetserver-scsi-failure">
           <para>Why does FreeBSD not detect my HP Netserver's SCSI
             controller?</para>
         </question>
 
         <answer>
           <para>This is basically a known problem.  The EISA on-board SCSI
             controller in the HP Netserver machines occupies EISA slot
             number 11, so all the <quote>true</quote> EISA slots are in
             front of it. Alas, the address space for EISA slots &gt;= 10
             collides with the address space assigned to PCI, and FreeBSD's
             auto-configuration currently cannot handle this situation very
             well.</para>
 
           <para>So now, the best you can do is to pretend there is no
             address range clash :), by bumping the kernel option
             <literal>EISA_SLOTS</literal> to a value of 12. Configure and
             compile a kernel, as described in the <ulink
             URL="../handbook/kernelconfig.html">Handbook entry on
             configuring the kernel</ulink>.</para>
 
           <para>Of course, this does present you with a chicken-and-egg
             problem when installing on such a machine. In order to work
             around this problem, a special hack is available inside
             <emphasis>UserConfig</emphasis>. Do not use the
             <quote>visual</quote> interface, but the plain command-line
             interface there. Simply type</para>
 
           <programlisting>eisa 12
 quit</programlisting>
 
           <para>at the prompt, and install your system as usual.  While
             it is recommended you compile and install a custom kernel
             anyway.</para>
 
           <para>Hopefully, future versions will have a proper fix for
             this problem.</para>
 
             <note>
               <para>You cannot use a
                 <literal>dangerously dedicated</literal> disk
                 with an HP Netserver. See <link linkend="dedicate">this
                 note</link> for more info.</para>
             </note>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="cmd640-ide">
           <para>What is going on with my CMD640 IDE controller?</para>
         </question>
 
         <answer>
           <para>It is broken.  It cannot handle commands on both channels
             simultaneously.</para>
 
           <para>There is a workaround available now and it is enabled
             automatically if your system uses this chip. For the details
             refer to the manual page of the disk driver (man 4 wd).</para>
 
           <para>If you are already running FreeBSD 2.2.1 or 2.2.2 with a
             CMD640 IDE controller and you want to use the second channel,
             build a new kernel with <literal>options "CMD640"</literal>
             enabled. This is the default for 2.2.5 and later.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ed1-timeout">
           <para>I keep seeing messages like
             <errorname>ed1: timeout</errorname>.  What do these messages
             mean?</para>
         </question>
 
         <answer>
           <para>This is usually caused by an interrupt conflict (e.g.,
             two boards using the same IRQ). FreeBSD prior to 2.0.5R used to
             be tolerant of this, and the network driver would still
             function in the presence of IRQ conflicts. However, with 2.0.5R
             and later, IRQ conflicts are no longer tolerated. Boot with the
             -c option and change the ed0/de0/... entry to match your
             board.</para>
 
           <para>If you are using the BNC connector on your network card,
             you may also see device timeouts because of bad termination. To
             check this, attach a terminator directly to the NIC (with no
             cable) and see if the error messages go away.</para>
 
           <para>Some NE2000 compatible cards will give this error if there
             is no link on the UTP port or if the cable is disconnected.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="bad-3c509">
           <para>Why did my 3COM 3C509 card stop working for no
             apparent reason?</para>
         </question>
 
         <answer>
           <para>This card has a bad habit of losing its configuration
             information.  Refresh your card's settings with the DOS
             utility <command>3c5x9.exe</command>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="printer-slow">
           <para>My parallel printer is ridiculously slow. What can I do?</para>
         </question>
 
         <answer>
           <para>If the only problem is that the printer is terribly
             slow, try changing your <ulink
             url="../handbook/printing-intro-setup.html#PRINTING-PARALLEL-PORT-MODE">printer
             port mode</ulink> as discussed in the <ulink
             url="../handbook/printing-intro-setup.html">Printer
             Setup</ulink> section of the Handbook.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="signal11">
           <para>Why do my programs occasionally die with
             <errorname>Signal 11</errorname> errors?</para>
         </question>
 
         <answer>
           <para>Signal 11 errors are caused when your process has attempted
             to access memory which the operating system has not granted it
             access to. If something like this is happening at seemingly
             random intervals then you need to start investigating things
             very carefully.</para>
 
           <para>These problems can usually be attributed to either:</para>
 
           <orderedlist>
             <listitem>
               <para>If the problem is occurring only in a specific
                 application that you are developing yourself it is probably
                 a bug in your code.</para>
             </listitem>
 
             <listitem>
               <para>If it is a problem with part of the base FreeBSD system,
                 it may also be buggy code, but more often than not these
                 problems are found and fixed long before us general FAQ
                 readers get to use these bits of code (that is what -current
                 is for).</para>
             </listitem>
           </orderedlist>
 
           <para>In particular, a dead giveaway that this is <emphasis>not</emphasis> a FreeBSD
             bug is if you see the problem when you are compiling a program,
             but the activity that the compiler is carrying out changes
             each time.</para>
 
           <para>For example, suppose you are running <quote>make
             buildworld</quote>, and the compile fails while trying to
             compile <filename>ls.c</filename> in to
             <filename>ls.o</filename>. If you then run <quote>make
             buildworld</quote> again, and the compile fails in the same
             place then this is a broken build -- try updating your sources
             and try again. If the compile fails elsewhere then this is
             almost certainly hardware.</para>
 
           <para>What you should do:</para>
 
           <para>In the first case you can use a debugger e.g. gdb to find
             the point in the program which is attempting to access a bogus
             address and then fix it.</para>
 
           <para>In the second case you need to verify that it is not your
             hardware at fault.</para>
 
           <para>Common causes of this include:</para>
 
           <orderedlist>
             <listitem>
               <para>Your hard disks might be overheating: Check the fans in
                 your case are still working, as your disk (and perhaps
                 other hardware might be overheating).</para>
             </listitem>
 
             <listitem>
               <para>The processor running is overheating: This might be
                 because the processor has been overclocked, or the fan on
                 the processor might have died. In either case you need to
                 ensure that you have hardware running at what it is
                 specified to run at, at least while trying to solve this
                 problem. i.e. Clock it back to the default settings.</para>
 
               <para>If you are overclocking then note that it is far cheaper
                 to have a slow system than a fried system that needs
                 replacing! Also the wider community is not often
                 sympathetic to problems on overclocked systems, whether you
                 believe it is safe or not.</para>
             </listitem>
 
             <listitem>
               <para>Dodgy memory: If you have multiple memory SIMMS/DIMMS
                 installed then pull them all out and try running the
                 machine with each SIMM or DIMM individually and narrow the
                 problem down to either the problematic DIMM/SIMM or perhaps
                 even a combination.</para>
             </listitem>
 
             <listitem>
               <para>Over-optimistic Motherboard settings: In your BIOS
                 settings, and some motherboard jumpers you have options to
                 set various timings, mostly the defaults will be
                 sufficient, but sometimes, setting the wait states on RAM
                 too low, or setting the <quote>RAM Speed: Turbo</quote> option, or
                 similar in the BIOS will cause strange behaviour. A
                 possible idea is to set to BIOS defaults, but it might be
                 worth noting down your settings first!</para>
             </listitem>
 
             <listitem>
               <para>Unclean or insufficient power to the motherboard. If you
                 have any unused I/O boards, hard disks, or CDROMs in your
                 system, try temporarily removing them or disconnecting the
                 power cable from them, to see if your power supply can
                 manage a smaller load. Or try another power supply,
                 preferably one with a little more power (for instance, if
                 your current power supply is rated at 250 Watts try one
                 rated at 300 Watts).</para>
             </listitem>
 
           </orderedlist>
 
           <para>You should also read the SIG11 FAQ (listed below) which has
             excellent explanations of all these problems, albeit from a
             Linux viewpoint. It also discusses how memory testing software
             or hardware can still pass faulty memory.</para>
 
           <para>Finally, if none of this has helped it is possible that
             you have just found a bug in FreeBSD, and you should follow the
             instructions to send a problem report.</para>
 
           <para>There is an extensive FAQ on this at <ulink
             URL="http://www.bitwizard.nl/sig11/">
             the SIG11 problem FAQ</ulink></para>
           </answer>
         </qandaentry>
 
         <qandaentry>
           <question id="trap-12-panic">
             <para>My system crashes with either <errorname>Fatal
               trap 12: page fault in kernel mode</errorname>, or
               <errorname>panic:</errorname>, and spits out a
               bunch of information.  What should I do?</para>
           </question>
 
           <answer>
             <para>The FreeBSD developers are very interested in these
               errors, but need some more information than just the
               error you see.  Copy your full crash message.  Then
               consult the FAQ section on <link linkend=
               "KERNEL-PANIC-TROUBLESHOOTING">kernel panics</link>,
               build a debugging kernel, and get a backtrace.  This
               might sound difficult, but you do not need any
               programming skills; you just have to follow the
               instructions.</para>
           </answer>
         </qandaentry>
 
         <qandaentry>
           <question id="screen-loses-sync">
             <para>Why does the screen go black and lose sync when I
               boot?</para>
           </question>
 
           <answer>
             <para>This is a known problem with the ATI Mach 64 video card.
               The problem is that this card uses address
               <literal>2e8</literal>, and the fourth serial port does too.
               Due to a bug (feature?) in the &man.sio.4;
               driver it will touch this port even if you do not have the
               fourth serial port, and <emphasis>even</emphasis> if
               you disable sio3 (the fourth port) which normally uses this
               address.</para>
 
             <para>Until the bug has been fixed, you can use this
               workaround:</para>
 
               <orderedlist>
                 <listitem>
                   <para>Enter <option>-c</option> at the boot prompt.
                     (This will put the kernel into configuration mode).</para>
                 </listitem>
 
                 <listitem>
                   <para>Disable <devicename>sio0</devicename>,
                     <devicename>sio1</devicename>,
                     <devicename>sio2</devicename> and
                     <devicename>sio3</devicename> (all of them).  This way
                     the sio driver does not get activated -&gt; no
                     problems.</para>
                 </listitem>
 
                 <listitem>
                   <para>Type exit to continue booting.</para>
                 </listitem>
               </orderedlist>
 
           <para>If you want to be able to use your serial ports, you will
             have to build a new kernel with the following modification: in
             <filename>/usr/src/sys/i386/isa/sio.c</filename> find the one
             occurrence of the string <literal>0x2e8</literal> and remove
             that string and the preceding comma (keep the trailing comma).
             Now follow the normal procedure of building a new
             kernel.</para>
 
           <para>Even after applying these workarounds, you may still find
             that the X Window System does not work properly. If this is the
             case, make sure that the XFree86 version you are using is at
             least XFree86 3.3.3 or higher. This version and upwards has
             built-in support for the Mach64 cards and even a dedicated X
             server for those cards.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="reallybigram">
           <para>Why does FreeBSD only use 64 MB of RAM when my system has
             128 MB of RAM installed?</para>
         </question>
 
         <answer>
           <para>Due to the manner in which FreeBSD gets the memory size
             from the BIOS, it can only detect 16 bits worth of Kbytes in
             size (65535 Kbytes = 64MB) (or less... some BIOSes peg the
             memory size to 16M). If you have more than 64MB, FreeBSD will
             attempt to detect it; however, the attempt may fail.</para>
 
           <para>To work around this problem, you need to use the kernel
             option specified below. There is a way to get complete memory
             information from the BIOS, but we do not have room in the
             bootblocks to do it. Someday when lack of room in the
             bootblocks is fixed, we will use the extended BIOS functions to
             get the full memory information...but for now we are stuck with
             the kernel option.</para>
 
           <para><literal>options "MAXMEM=<replaceable>n</replaceable>"</literal></para>
 
           <para>Where <replaceable>n</replaceable> is your memory in
             Kilobytes. For a 128 MB machine, you would want to use
             <literal>131072</literal>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="panic-kmemmap-too-small">
           <para>Why does FreeBSD 2.0 panic with
             <errorname>kmem_map too small!</errorname>?</para>
         </question>
 
         <answer>
             <note>
               <para>The message may also be
                 <literal>mb_map too small!</literal></para>
             </note>
 
           <para>The panic indicates that the system ran out of virtual
             memory for network buffers (specifically, mbuf clusters). You
             can increase the amount of VM available for mbuf clusters by
             adding:</para>
 
           <para><literal>options "NMBCLUSTERS=<replaceable>n</replaceable>"</literal></para>
 
           <para>to your kernel config file, where
             <replaceable>n</replaceable> is a number in the range 512-4096,
             depending on the number of concurrent TCP connections you need
             to support. I would recommend trying 2048 - this should get rid of
             the panic completely. You can monitor the number of mbuf
             clusters allocated/in use on the system with
             <command>netstat
             -m</command> (see &man.netstat.1;). The default value for NMBCLUSTERS is <literal>512 +
             MAXUSERS * 16</literal>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="proc-table-full">
           <para>Why do I get the error <errorname>/kernel: proc: table
             is full</errorname>?</para>
         </question>
 
         <answer>
           <para>The FreeBSD kernel will only allow a certain number of
             processes to exist at one time.  The number is based on
             the <literal>MAXUSERS</literal> option in the kernel
             configuration.  <literal>MAXUSERS</literal> also affects
             various other in-kernel limits, such as network buffers
             (see <link linkend="panic-kmemmap-too-small">this</link>
             earlier question).  If your machine is heavily loaded, you
             probably want to increase <literal>MAXUSERS</literal>.
             This will increase these other system limits in addition
             to the maximum number of processes.</para>
 
           <para>After FreeBSD 4.4, <literal>MAXUSERS</literal> became
             a tunable value that could be set with
             <varname>kern.maxusers</varname> in
             <filename>/boot/loader.conf</filename>.  In earlier
             versions of FreeBSD, you need to adjust
             <literal>MAXUSERS</literal> in your kernel
             configuration.</para>
 
           <para>If your machine is lightly loaded, and you are simply
             running a very large number of processes, you can adjust
             this with the <varname>kern.maxproc</varname> sysctl.  If
             these processes are being run by a single user, you will
             also need to adjust <varname>kern.maxprocperuid</varname>
             to be one less than your new
             <varname>kern.maxproc</varname> value.  (It must be at
             least one less because one system program, &man.init.8;,
             must always be running.)</para>
 
           <para>To make a sysctl permanent across reboots, set this in
             <filename>/etc/sysctl.conf</filename> in recent versions
             of FreeBSD, or <filename>/etc/rc.local</filename> in older
             versions.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="cmap-busy-panic">
           <para>Why do I get an error reading <errorname>CMAP
               busy</errorname> when rebooting with a new
             kernel?</para>
         </question>
 
         <answer>
           <para>The logic that attempts to detect an out of date
             <filename>/var/db/kvm_*.db</filename> files sometimes fails
             and using a mismatched file can sometimes lead to panics.</para>
 
           <para>If this happens, reboot single-user and do:</para>
 
           <screen>&prompt.root; <userinput>rm /var/db/kvm_*.db</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="brkadrint-illegal-host-access">
           <para>What does the message <errorname>ahc0: brkadrint,
               Illegal Host Access at seqaddr 0x0</errorname>
             mean?</para>
         </question>
 
         <answer>
           <para>This is a conflict with an Ultrastor SCSI Host Adapter.</para>
 
           <para>During the boot process enter the kernel configuration
             menu and disable
             <devicename>uha0</devicename>,
             which is causing the problem.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="aci0-illegal-cable">
           <para>When I boot my system, I get the error
             <errorname>ahc0: illegal cable configuration</errorname>.
             My cabling is correct.  What is going on?</para>
         </question>
 
         <answer>
            <para>Your motherboard lacks the external logic to support
              automatic termination.  Switch your SCSI BIOS to specify
              the correct termination for your configuration rather
              than automatic termination.  The AIC7XXX driver cannot
              determine if the external logic for cable detection (and
              thus auto-termination) is available.  The driver simply
              assumes that this support must exist if the configuration
              contained in the serial EEPROM is set to "automatic
              termination".  Without the external cable detection logic
              the driver will often configure termination incorrectly,
              which can compromise the reliability of the SCSI
              bus.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="mail-loopback">
           <para>Why does Sendmail give me an error reading
             <quote><errorname>mail loops back to
               myself</errorname></quote>?</para>
         </question>
 
         <answer>
           <para>This is answered in the sendmail FAQ as follows:-</para>
 
 <literallayout>        * I'm getting "Local configuration error" messages, such as:
 
         553 relay.domain.net config error: mail loops back to myself
         554 &lt;user@domain.net&gt;... Local configuration error
 
         How can I solve this problem?
 
         You have asked mail to the domain (e.g., domain.net) to be
         forwarded to a specific host (in this case, relay.domain.net)
         by using an MX record, but the relay machine does not recognize
         itself as domain.net.  Add domain.net to /etc/sendmail.cw
         (if you are using FEATURE(use_cw_file)) or add "Cw domain.net"
         to /etc/sendmail.cf.
             </literallayout>
 
           <para>The current version of the <ulink
             URL="ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/sendmail-faq">sendmail
             FAQ</ulink> is no longer maintained with the sendmail release.
             It is however regularly posted to <ulink
             URL="news:comp.mail.sendmail">comp.mail.sendmail</ulink>,
             <ulink URL="news:comp.mail.misc">comp.mail.misc</ulink>, <ulink
             URL="news:comp.mail.smail">comp.mail.smail</ulink>, <ulink
             URL="news:comp.answers">comp.answers</ulink>, and <ulink
             URL="news:news.answers">news.answers</ulink>. You can also
             receive a copy via email by sending a message to
             <email>mail-server@rtfm.mit.edu</email> with the command
             <literal>send usenet/news.answers/mail/sendmail-faq</literal>
             as the body of the message.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="remote-fullscreen">
           <para>Why do full screen applications on remote machines
             misbehave?</para>
         </question>
 
         <answer>
           <para>The remote machine may be setting your terminal type
             to something other than the <literal>cons25</literal> terminal
             type required by the FreeBSD console.</para>
 
           <para>There are a number of possible work-arounds for this
             problem:</para>
             <itemizedlist>
               <listitem>
                 <para>After logging on to the remote machine, set your
                   TERM shell variable to <literal>ansi</literal> or
                   <literal>sco</literal> if the remote machine knows
                   about these terminal types.</para>
               </listitem>
 
               <listitem>
                 <para>Use a VT100 emulator like
                   <application>screen</application> at the FreeBSD console.
                   <application>screen</application> offers you the ability
                   to run multiple concurrent sessions from one terminal,
                   and is a neat program in its own right. Each
                   <application>screen</application> window behaves like a
                   VT100 terminal, so the TERM variable at the remote end
                   should be set to <literal>vt100</literal>.</para>
               </listitem>
 
               <listitem>
                 <para>Install the <literal>cons25</literal> terminal
                   database entry on the remote machine. The way to do this
                   depends on the operating system on the remote machine.
                   The system administration manuals for the remote system
                   should be able to help you here.</para>
               </listitem>
 
               <listitem>
                 <para>Fire up an X server at the FreeBSD end and login to
                   the remote machine using an X based terminal emulator
                   such as <command>xterm</command> or
                   <command>rxvt</command>. The TERM variable at the remote
                   host should be set to <literal>xterm</literal> or
                   <literal>vt100</literal>.</para>
               </listitem>
             </itemizedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="calcru-negative">
           <para>Why does my machine print
             <errorname>calcru: negative time...</errorname>?</para>
         </question>
 
         <answer>
           <para>This can be caused by various hardware and/or software
             ailments relating to interrupts. It may be due to bugs but can
             also happen by nature of certain devices. Running TCP/IP over
             the parallel port using a large MTU is one good way to provoke
             this problem. Graphics accelerators can also get you here, in
             which case you should check the interrupt setting of the card
             first.</para>
 
           <para>A side effect of this problem are dying processes with the
             message <quote>SIGXCPU exceeded cpu time limit</quote>.</para>
 
           <para>For FreeBSD 3.0 and later from Nov 29, 1998 forward: If the
             problem cannot be fixed otherwise the solution is to set
             this sysctl variable:</para>
 
           <screen>&prompt.root; <userinput>sysctl -w kern.timecounter.method=1</userinput></screen>
 
           <para>This means a performance impact, but considering the cause
             of this problem, you probably will not notice. If the problem
             persists, keep the sysctl set to one and set the
             <literal>NTIMECOUNTER</literal> option in your kernel to
             increasingly large values. If by the time you have reached
             <literal>NTIMECOUNTER=20</literal> the problem is not solved,
             interrupts are too hosed on your machine for reliable
             time keeping.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="pcm0-not-found">
           <para>I see <errorname>pcm0 not found</errorname> or my sound card is
             found as <devicename>pcm1</devicename> but I have
             <literal>device pcm0</literal> in my kernel config file.  What is
             going on?</para>
         </question>
 
         <answer>
           <para>This occurs in FreeBSD 3.x with PCI sound cards. The
             <devicename>pcm0</devicename> device is reserved exclusively for
             ISA-based cards so, if you have a PCI card, then you will see
             this error, and your card will appear as <devicename>pcm1</devicename>.
 
             <note>
               <para>You cannot remove the warning by simply changing the
                 line in the kernel config file to <literal>device
                 pcm1</literal> as this will result in
                 <devicename>pcm1</devicename> being reserved for ISA cards and
                 your PCI card being found as <devicename>pcm2</devicename> (along
                 with the warning <errorname>pcm1 not found</errorname>).</para>
             </note>
 
             If you have a PCI sound card you will also have to make the
             <devicename>snd1</devicename> device rather than
             <devicename>snd0</devicename>:</para>
 
           <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>./MAKEDEV snd1</userinput></screen>
 
           <para>This situation does not arise in FreeBSD 4.x as a lot
             of work has been done to make it more
             <emphasis>PnP-centric</emphasis> and the
             <devicename>pcm0</devicename> device is no longer reserved
             exclusively for ISA cards</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="pnp-not-found">
           <para>Why is my PnP card no longer found (or found as
             <literal>unknown</literal>) since upgrading to FreeBSD 4.x?</para>
         </question>
 
         <answer>
           <para>FreeBSD 4.x is now much more <emphasis>PnP-centric</emphasis>
             and this has had the side effect of some PnP devices (e.g. sound
             cards and internal modems) not working even though they worked
             under FreeBSD 3.x.</para>
 
           <para>The reasons for this behaviour are explained by the following
             e-mail, posted to the freebsd-questions mailing list by Peter
             Wemm, in answer to a question about an internal modem that was
             no longer found after an upgrade to FreeBSD 4.x (the comments
             in <literal>[]</literal> have been added to clarify the
             context.</para>
 
           <blockquote>
             <para>The PNP bios preconfigured it [the modem] and left it
               laying around in port space, so [in 3.x] the old-style ISA
               probes <quote>found</quote> it there.</para>
 
             <para>Under 4.0, the ISA code is much more PnP-centric. It was
               possible [in 3.x] for an ISA probe to find a
               <quote>stray</quote> device and then for the PNP device id to
               match and then fail due to resource conflicts. So, it
               disables the programmable cards first so this double probing
               cannot happen. It also means that it needs to know the PnP
               id's for supported PnP hardware. Making this more user
               tweakable is on the TODO list.</para>
           </blockquote>
 
           <para>To get the device working again requires finding its PnP id
             and adding it to the list that the ISA probes use to identify
             PnP devices. This is obtained using &man.pnpinfo.8; to probe the
             device, for example this is the output from &man.pnpinfo.8; for
             an internal modem:</para>
 
           <screen>&prompt.root; <userinput>pnpinfo</userinput>
 Checking for Plug-n-Play devices...
 
 Card assigned CSN #1
 Vendor ID PMC2430 (0x3024a341), Serial Number 0xffffffff
 PnP Version 1.0, Vendor Version 0
 Device Description: Pace 56 Voice Internal Plug & Play Modem
 
 Logical Device ID: PMC2430 0x3024a341 #0
         Device supports I/O Range Check
 TAG Start DF
     I/O Range 0x3f8 .. 0x3f8, alignment 0x8, len 0x8
         [16-bit addr]
     IRQ: 4  - only one type (true/edge)</screen>
 
           <para>[more TAG lines elided]</para>
 
           <screen>TAG End DF
 End Tag
 
 Successfully got 31 resources, 1 logical fdevs
 -- card select # 0x0001
 
 CSN PMC2430 (0x3024a341), Serial Number 0xffffffff
 
 Logical device #0
 IO:  0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8
 IRQ 5 0
 DMA 4 0
 IO range check 0x00 activate 0x01</screen>
 
           <para>The information you require is in the
             <quote>Vendor ID</quote> line at the start of the output. The
             hexadecimal number in parentheses (0x3024a341 in this example)
             is the PnP id and the string immediately before this (PMC2430)
             is a unique ASCII id. This information needs adding to the file
             <filename>/usr/src/sys/isa/sio.c</filename>.</para>
 
           <para>You should first make a backup of <filename>sio.c</filename>
             just in case things go wrong. You will also need it to make the
             patch to submit with your PR (you are going to submit a PR,
             are you not?) then edit <filename>sio.c</filename> and search
             for the line</para>
 
           <programlisting>static struct isa_pnp_id sio_ids[] = {</programlisting>
 
           <para>then scroll down to find the correct place to add the entry
             for your device. The entries look like this, and are sorted on
             the ASCII Vendor ID string which should be included in the
             comment to the right of the line of code along with all (if it
             will fit) or part of the <emphasis>Device Description</emphasis>
             from the output of &man.pnpinfo.8;:</para>
 
           <programlisting>{0x0f804f3f, NULL},     /* OZO800f - Zoom 2812 (56k Modem) */
 {0x39804f3f, NULL},     /* OZO8039 - Zoom 56k flex */
 {0x3024a341, NULL},     /* PMC2430 - Pace 56 Voice Internal Modem */
 {0x1000eb49, NULL},     /* ROK0010 - Rockwell ? */
 {0x5002734a, NULL},     /* RSS0250 - 5614Jx3(G) Internal Modem */</programlisting>
 
           <para>Add the hexadecimal Vendor ID for your device in the
             correct place, save the file, rebuild your kernel, and reboot.
             Your device should now be found as an <literal>sio</literal>
             device as it was under FreeBSD 3.x</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="nlist-failed">
           <para>Why do I get the error <errorname>nlist failed</errorname> when
             running, for example, <command>top</command> or
             <command>systat</command>?</para>
         </question>
 
         <answer>
           <para>The problem is that the application you are trying to run is
             looking for a specific kernel symbol, but, for whatever reason,
             cannot find it; this error stems from one of two problems:</para>
 
           <itemizedlist>
             <listitem>
               <para>Your kernel and userland are not synchronized (i.e., you
                 built a new kernel but did not do an
                 <maketarget>installworld</maketarget>, or vice versa), and
                 thus the symbol table is different from what the user
                 application thinks it is.  If this is the case, simply
                 complete the upgrade process (see
                 <filename>/usr/src/UPDATING</filename> for the correct
                 sequence).</para>
             </listitem>
 
             <listitem>
               <para>You are not using <command>/boot/loader</command> to load
                 your kernel, but doing it directly from boot2 (see
                 &man.boot.8;).  While there is nothing wrong with bypassing
                 <command>/boot/loader</command>, it generally does a better
                 job of making the kernel symbols available to user
                 applications.</para>
             </listitem>
           </itemizedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="connection-delay">
           <para>Why does it take so long to connect to my computer via
             <command>ssh</command> or <command>telnet</command>?</para>
         </question>
 
         <answer>
           <para>The symptom: there is a long delay between the time the TCP
             connection is established and the time when the client software
             asks for a password (or, in &man.telnet.1;'s case, when a login
             prompt appears).</para>
 
           <para>The problem: more likely than not, the delay is caused by
             the server software trying to resolve the client's IP address
             into a hostname.  Many servers, including the Telnet and SSH
             servers that come with FreeBSD, do this in order to, among
             other things, store the hostname in a log file for future
             reference by the administrator.</para>
 
           <para>The remedy: if the problem occurs whenever you connect from
             your computer (the client) to any server, the problem is with
             the client; likewise, if the problem only occurs when someone
             connects to your computer (the server) the problem is with the
             server.</para>
 
           <para>If the problem is with the client, the only remedy is to
             fix the DNS so the server can resolve it.  If this is on a
             local network, consider it a server problem and keep reading;
             conversely, if this is on the global Internet, you will most
             likely need to contact your ISP and ask them to fix it for
             you.</para>
 
           <para>If the problem is with the server, and this is on a local
             network, you need to configure the server to be able to resolve
             address-to-hostname queries for your local address range.  See
             the &man.hosts.5; and &man.named.8; manual pages for more
             information.  If this is on the global Internet, the problem
             may be that your server's resolver is not functioning
             correctly.  To check, try to look up another host--say,
             <hostid>www.yahoo.com</hostid>.  If it does not work, that is
             your problem.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="stray-irq">
           <para>What does <errorname>stray IRQ</errorname> mean?</para>
         </question>
 	<answer>
 	  <para>Stray IRQs are indications of hardware IRQ glitches,
             mostly from hardware that removes its interrupt request in
             the middle of the interrupt request acknowledge
             cycle.</para>
 	  <para>One has three options for dealing with this:</para>
 	  <itemizedlist>
 	    <listitem>
 	      <para>Live with the warnings.  All except the first 5
                 per irq are suppressed anyway.</para>
 	    </listitem>
 	    <listitem>
 	      <para>Break the warnings by changing 5 to 0 in
 	        <function>isa_strayintr()</function> so that all the
 	        warnings are suppressed.</para>
 	    </listitem>
 	    <listitem>
 	      <para>Break the warnings by installing parallel port
               hardware that uses irq 7 and the PPP driver for it (this
               happens on most systems), and install an ide drive or
               other hardware that uses irq 15 and a suitable driver
               for it.</para>
 	    </listitem>
 	  </itemizedlist>
 	</answer>
       </qandaentry>
 
       <qandaentry>
         <question id="file-table-full">
           <para>Why does <errorname>file: table is full</errorname> show up
             repeatedly in dmesg?</para>
         </question>
         <answer>
           <para>
             This error message indicates you have exhausted the number
             of available file descriptors on your system.  Please see
             the <ulink
             url="../handbook/configtuning-kernel-limits.html#KERN-MAXFILES">kern.maxfiles
             </ulink>section of the <ulink
             url="../handbook/configtuning-kernel-limits.html">Tuning
             Kernel Limits</ulink> section of the Handbook for a
             discussion and solution.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
 	<question id="laptop-clock-skew">
 	  <para>Why does the clock on my laptop keep incorrect time?</para>
 	</question>
 
 	<answer>
 	  <para>Your laptop has two or more clocks, and FreeBSD has chosen to
 	    use the wrong one.</para>
 
 	  <para>Run &man.dmesg.8;, and check for lines that contain
 	    <literal>Timecounter</literal>.  The last line printed is the one
 	    that FreeBSD chose, and will almost certainly be
 	    <literal>TSC</literal>.</para>
 
 	  <screen>&prompt.root; <userinput>dmesg | grep Timecounter</userinput>
 Timecounter "i8254"  frequency 1193182 Hz
 Timecounter "TSC"  frequency 595573479 Hz</screen>
 
 	  <para>You can confirm this by checking the
 	    <varname>kern.timecounter.hardware</varname>
 	      &man.sysctl.3;.</para>
 
 	  <screen>&prompt.root; <userinput>sysctl kern.timecounter.hardware</userinput>
 kern.timecounter.hardware: TSC</screen>
 	
 	  <para>The BIOS may modify the TSC clock&mdash;perhaps to change the
 	    speed of the processor when running from batteries, or going in to
 	    a power saving mode, but FreeBSD is unaware of these adjustments,
 	    and appears to gain or lose time.</para>
 
 	  <para>In this example, the <literal>i8254</literal> clock is also
 	    available, and can be selected by writing its name to the
 	    <varname>kern.timecounter.hardware</varname>
 	      &man.sysctl.3;.</para>
 
 	  <screen>&prompt.root; <userinput>sysctl -w kern.timecounter.hardware=i8254</userinput>
 kern.timecounter.hardware: TSC -&gt; i8254</screen>
 
 	  <para>Your laptop should now start keeping more accurate
 	    time.</para>
 
 	  <para>To have this change automatically run at boot time, add the
 	    following line to <filename>/etc/sysctl.conf</filename>.</para>
 
 	  <programlisting>kern.timecounter.hardware=i8254</programlisting>
 	</answer>
       </qandaentry>
 
       <qandaentry>
         <question id="boot-read-error">
           <para>Why does FreeBSD's boot loader display
             <errorname>Read error</errorname> and stop after the BIOS
             screen?</para>
         </question>
 
         <answer>
           <para>FreeBSD's boot loader is incorrectly recognizing the hard 
             drive's geometry. This must be manually set within fdisk when 
             creating or modifying FreeBSD's slice.
           </para>
           <para>The correct drive geometry values can be found within the
             machine's BIOS. Look for the number of cylinders, heads and
             sectors for the particular drive.
           </para>
           <para>Within &man.sysinstall.8;'s fdisk, hit 
             <keycap>G</keycap> to set the drive geometry.</para>
           <para>A dialog will pop up requesting the number of cylinders, heads
             and sectors.  Type the numbers found from the BIOS separates by
             forward slashes.
           </para>
           <para>5000 cylinders, 250 sectors and 60 sectors would be entered as
             <userinput>5000/250/60</userinput>
           </para>
           <para>Press enter to set the values, and hit
           <keycap>W</keycap> to write the
           new partition table to the drive.
           </para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="bootmanager-restore">
           <para>Another operating system destroyed my Boot Manager.  How do I 
             get it back?
           </para>
         </question>
 
         <answer>
           <para>Enter &man.sysinstall.8; and choose Configure,
             then Fdisk.  Select the disk the Boot Manager resided on
             with the <keycap>space</keycap> key.  Press 
             <keycap>W</keycap> to write changes to the drive.  A prompt
             will appear asking which boot loader to install.  Select this,
             and it will be restored.
           </para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="indefinite-wait-buffer">
           <para>What does the error <errorname>swap_pager: indefinite
             wait buffer:</errorname> mean?</para>
         </question>
 
         <answer>
           <para>This means that a process is trying to page memory to
             disk, and the page attempt has hung trying to access the
             disk for more than 20 seconds.  It might be caused by bad
             blocks on the disk drive, disk wiring, cables, or any
             other disk I/O-related hardware.  If the drive itself is
             actually bad, you will also see disk errors in
             <filename>/var/log/messages</filename> and in the output
             of <command>dmesg</command>.  Otherwise, check your cables
             and connections.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="commercial">
     <title>Commercial Applications</title>
 
       <note>
         <para>This section is still very sparse, though we are hoping, of
           course, that companies will add to it! :) The FreeBSD group has
           no financial interest in any of the companies listed here but
           simply lists them as a public service (and feels that commercial
           interest in FreeBSD can have very positive effects on FreeBSD's
           long-term viability). We encourage commercial software vendors to
           send their entries here for inclusion. See <ulink
           URL="../../../../commercial/index.html">the
           Vendors page</ulink> for a longer list.</para>
       </note>
 
     <qandaset>
       <qandaentry>
         <question id="officesuite">
           <para>Where can I get an Office Suite for FreeBSD?</para>
         </question>
         <answer>
 	  <itemizedlist>
   	    <listitem>
 	      <para><ulink url="http://www.freebsdmall.com/">The FreeBSD Mall</ulink>
                 offers a FreeBSD native version of <ulink
                 url="http://www.vistasource.com/">VistaSource</ulink>
                 ApplixWare 5.</para>
 	
 	      <para>ApplixWare is a rich full-featured, commercial
 	        Office Suite for FreeBSD containing a word processor,
 	        spreadsheet, presentation program, vector drawing
 	        package, and other applications.
 		</para>
 
 	      <para>ApplixWare is offered as part of the FreeBSD Mall's BSD
 		Desktop Edition.</para>
 
   	    </listitem>
 	    <listitem>
 	      <para>The Linux version of <ulink
 	        url="http://www.sun.com/staroffice/">StarOffice</ulink>
 	        works flawlessly on FreeBSD.  The easiest way to
 	        install the Linux version of StarOffice is through the
 	        <ulink
 	        url="../handbook/ports.html">FreeBSD
 	        Ports collection</ulink>.  Future versions of the
 	        open-source <ulink
 	        url="http://www.openoffice.org/">OpenOffice</ulink>
 	        suite should work as well.</para>
 	    </listitem>
 	  </itemizedlist>
         </answer>
       </qandaentry>
       <qandaentry>
         <question id="motif">
           <para>Where can I get Motif for FreeBSD?</para>
         </question>
 
         <answer>
 	  <para>The Open Group has released the source code to Motif 2.1.30.
 	    You can install the <literal>open-motif</literal> package, or
 	    compile it from ports.  Refer to
 	    <ulink url="../handbook/ports.html">the ports section of the
 	      Handbook</ulink> for more information on how to do this.
 
 	    <note>
 	      <para>The Open Motif distribution only allows redistribution
 		if it is running on an <ulink url="http://www.opensource.org/">
 		  open source</ulink> operating system.</para>
 	    </note>
 	  </para>
 
           <para>In addition, there are commercial distributions of the Motif
             software available.  These, however, are not for free, but their
             license allows them to be used in closed-source software.
 	    Contact <link linkend="apps2go">Apps2go</link> for the
             least expensive ELF Motif 2.1.20 distribution for FreeBSD
             (either i386 or Alpha).<anchor id="apps2go"></para>
 
           <para>There are two distributions, the <quote>development
             edition</quote> and the <quote>runtime edition</quote> (for
             much less).  These distributions includes:</para>
 
             <itemizedlist>
               <listitem>
                 <para>OSF/Motif manager, xmbind, panner, wsm.</para>
               </listitem>
 
               <listitem>
                 <para>Development kit with uil, mrm, xm, xmcxx, include
                   and Imake files.</para>
               </listitem>
 
               <listitem>
                 <para>Static and dynamic ELF libraries (for use with
                   FreeBSD 3.0 and above).</para>
               </listitem>
 
               <listitem>
                 <para>Demonstration applets.</para>
               </listitem>
             </itemizedlist>
 
           <para>Be sure to specify that you want the FreeBSD version of
             Motif when ordering (do not forget to mention the architecture
             you want too)! Versions for NetBSD and OpenBSD are also sold by
             <emphasis>Apps2go</emphasis>. This is currently a FTP only
             download.</para>
 
             <variablelist>
               <varlistentry>
                 <term>More info</term>
                 <listitem>
                   <para><ulink URL="http://www.apps2go.com/">
                     Apps2go WWW page</ulink></para>
                 </listitem>
               </varlistentry>
 
               <varlistentry>
                 <term>or</term>
                   <listitem>
                     <para>
                       <email>sales@apps2go.com</email> or
                       <email>support@apps2go.com</email>
                       </para>
                   </listitem>
                 </varlistentry>
 
                 <varlistentry>
                   <term>or</term>
                   <listitem>
                     <para>phone (817) 431 8775  or +1 817 431-8775</para>
                   </listitem>
                 </varlistentry>
               </variablelist>
 
           <para>Contact <link linkend="metrox">Metro Link</link>
             for an either ELF or a.out Motif 2.1 distribution for
             FreeBSD.</para>
 
           <para>This distribution includes:</para>
             <itemizedlist>
               <listitem>
                 <para>OSF/Motif manager, xmbind, panner, wsm.</para>
               </listitem>
 
               <listitem>
                 <para>Development kit with uil, mrm, xm, xmcxx, include
                   and Imake files.</para>
               </listitem>
 
               <listitem>
                 <para>Static and dynamic libraries (specify ELF for use
                   with FreeBSD 3.0 and later; or a.out for use with FreeBSD
                   2.2.8 and earlier).</para>
               </listitem>
 
               <listitem>
                 <para>Demonstration applets.</para>
               </listitem>
 
               <listitem>
               <para>Preformatted man pages.</para>
               </listitem>
 
               </itemizedlist>
 
           <para>Be sure to specify that you want the FreeBSD version
             of Motif when ordering! Versions for Linux are also sold by
             <emphasis>Metro Link</emphasis>. This is available on either a
             CDROM or for FTP download.</para>
 
           <para>Contact <link linkend="xig">Xi Graphics</link> for an
             a.out Motif 2.0 distribution for FreeBSD.</para>
 
           <para>This distribution includes:</para>
             <itemizedlist>
               <listitem>
                 <para>OSF/Motif manager, xmbind, panner, wsm.</para>
               </listitem>
 
               <listitem>
                 <para>Development kit with uil, mrm, xm, xmcxx, include
                   and Imake files.</para>
               </listitem>
 
               <listitem>
                 <para>Static and dynamic libraries (for use with FreeBSD
                   2.2.8 and earlier).</para>
               </listitem>
 
               <listitem>
                 <para>Demonstration applets.</para>
               </listitem>
 
               <listitem>
                 <para>Preformatted man pages.</para>
               </listitem>
             </itemizedlist>
 
           <para>Be sure to specify that you want the FreeBSD version
             of Motif when ordering! Versions for BSDI and Linux are also
             sold by <emphasis>Xi Graphics</emphasis>. This is currently a 4
             diskette set... in the future this will change to a unified CD
             distribution like their CDE.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="cde">
           <para>Where can I get CDE for FreeBSD?</para>
         </question>
 
         <answer>
           <para><link linkend="xig">Xi Graphics</link> used to sell CDE
             for FreeBSD, but no longer do.</para>
 
           <para><ulink URL="http://www.kde.org/">KDE</ulink> is an open
             source X11 desktop which is similar to CDE in many respects.
             You might also like the look and feel of <ulink
             URL="http://www.xfce.org/">xfce</ulink>. KDE and xfce are both
             in the <ulink URL="../../../../ports/index.html">ports
             system</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="commercial-xserver">
           <para>Are there any commercial high-performance X servers?</para>
         </question>
 
         <answer>
           <para>Yes, <ulink URL="http://www.xig.com/">Xi Graphics</ulink>
             and <ulink URL="http://www.metrolink.com/">Metro Link</ulink>
             sell Accelerated-X product for FreeBSD and other Intel based
             systems.</para>
 
           <para>The Metro Link offering is a high performance X Server
             that offers easy configuration using the FreeBSD Package suite
             of tools, support for multiple concurrent video boards and is
             distributed in binary form only, in a convenient FTP download.
             Not to mention the Metro Link offering is available at the very
             reasonable price of $39. <anchor id="metrox"></para>
 
           <para>Metro Link also sells both ELF and a.out Motif for
             FreeBSD (see above).</para>
 
             <variablelist>
               <varlistentry>
                 <term>More info</term>
                 <listitem>
                   <para><ulink URL="http://www.metrolink.com/">
                     Metro Link WWW page</ulink></para>
                 </listitem>
               </varlistentry>
 
               <varlistentry>
                 <term>or</term>
                 <listitem>
                   <para><email>sales@metrolink.com</email>
                     or <email>tech@metrolink.com</email>
                     </para>
                 </listitem>
               </varlistentry>
 
               <varlistentry>
                 <term>or</term>
                   <listitem>
                     <para>phone (954) 938-0283  or +1 954 938-0283</para>
                   </listitem>
                 </varlistentry>
               </variablelist>
 
           <para>The Xi Graphics offering is a high performance X Server
             that offers easy configuration, support for multiple concurrent
             video boards and is distributed in binary form only, in a
             unified diskette distribution for FreeBSD and Linux. Xi
             Graphics also offers a high performance X Server tailored for
             laptop support.<anchor id="xig"></para>
 
           <para>There is a free <quote>compatibility demo</quote> of
             version 5.0 available.</para>
 
           <para>Xi Graphics also sells Motif and CDE for FreeBSD (see
             above).</para>
 
             <variablelist>
               <varlistentry>
                 <term>More info</term>
                 <listitem>
                   <para><ulink URL="http://www.xig.com/">
                     Xi Graphics WWW page</ulink></para>
                 </listitem>
               </varlistentry>
 
               <varlistentry>
                 <term>or</term>
                   <listitem>
                     <para><email>sales@xig.com</email>
                       or <email>support@xig.com</email>
                       </para>
                   </listitem>
                 </varlistentry>
 
                 <varlistentry>
                   <term>or</term>
                   <listitem>
                     <para>phone (800) 946 7433  or +1 303 298-7478.</para>
                   </listitem>
                 </varlistentry>
               </variablelist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="database-systems">
           <para>Are there any Database systems for FreeBSD?</para>
         </question>
 
         <answer>
           <para>Yes! See the <ulink
             URL="../../../../commercial/software_bycat.html#CATEGORY_DATABASE">
             Commercial Vendors</ulink> section of FreeBSD's Web site.</para>
 
           <para>Also see the <ulink
             URL="../../../../ports/databases.html">
             Databases</ulink> section of the Ports collection.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="oracle-support">
           <para>Can I run Oracle on FreeBSD?</para>
         </question>
 
         <answer>
           <para>Yes. The following pages tell you exactly how to setup
             Linux-Oracle on FreeBSD:</para>
 
             <itemizedlist>
               <listitem>
                 <para><ulink
                   URL="http://www.scc.nl/~marcel/howto-oracle.html">
                   http://www.scc.nl/~marcel/howto-oracle.html</ulink></para>
               </listitem>
 
               <listitem>
                 <para><ulink
                   URL="http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsd">
 
                   http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsd</ulink></para>
 
               </listitem>
             </itemizedlist>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="applications">
     <title>User Applications</title>
 
     <qandaset>
       <qandaentry>
         <question id="user-apps">
           <para>So, where are all the user applications?</para>
         </question>
 
         <answer>
           <para>Please take a look at
             <ulink URL="../../../../ports/index.html">the ports
             page</ulink> for info on software packages ported to FreeBSD.
             The list currently tops &os.numports; and is growing daily, so come back
             to check often or subscribe to the
             <literal>freebsd-announce</literal> <link
             linkend="mailing">mailing list</link> for periodic updates on
             new entries.</para>
 
           <para>Most ports should be available for the 2.2, 3.x and 4.x
             branches, and many of them should work on 2.1.x systems as
             well. Each time a FreeBSD release is made, a snapshot of the
             ports tree at the time of release in also included in the
             <filename>ports/</filename> directory.</para>
 
           <para>We also support the concept of a <quote>package</quote>,
             essentially no more than a gzipped binary distribution with a
             little extra intelligence embedded in it for doing whatever
             custom installation work is required. A package can be
             installed and uninstalled again easily without having to know
             the gory details of which files it includes.</para>
 
           <para>Use the package installation menu in
             <filename>/stand/sysinstall</filename> (under the
             post-configuration menu item) or invoke the
             &man.pkg.add.1; command on the specific package
             files you are interested in installing. Package files can
             usually be identified by their <filename>.tgz</filename> suffix
             and CDROM distribution people will have a
             <filename>packages/All</filename> directory on their CD which
             contains such files. They can also be downloaded over the net
             for various versions of FreeBSD at the following
             locations:</para>
 
             <variablelist>
               <varlistentry>
                 <term>for 2.2.8-RELEASE/2.2.8-STABLE</term>
                 <listitem>
                   <para><ulink
                     URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-2.2.8/">
                     ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-2.2.8/</ulink></para>
                 </listitem>
               </varlistentry>
 
               <varlistentry>
                 <term>for 3.X-RELEASE/3.X-STABLE</term>
                 <listitem>
                   <para><ulink
                     URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-3-stable/">
                     ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-3-stable/</ulink></para>
                 </listitem>
               </varlistentry>
 
               <varlistentry>
                 <term>for 4.X-RELEASE/4-STABLE</term>
                 <listitem>
                   <para><ulink
                     URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/">
                     ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/</ulink></para>
 
                 </listitem>
               </varlistentry>
 
               <varlistentry>
                 <term>for 5.X-CURRENT</term>
                 <listitem>
                   <para><ulink
                     URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-current/">
                     ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-current</ulink></para>
                 </listitem>
               </varlistentry>
             </variablelist>
 
           <para>or your nearest local mirror site.</para>
 
           <para>Note that all ports may not be available as packages since
             new ones are constantly being added. It is always a good idea
             to check back periodically to see which packages are available
             at the <ulink
             URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp.FreeBSD.org</ulink>
             master site.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="missing-libcso30">
           <para>Where do I find libc.so.3.0?</para>
         </question>
 
         <answer>
           <para>You are trying to run a package built on 2.2 and later on
             a 2.1.x system. Please take a look at the previous section and
             get the correct port/package for your system.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="missing-libcso40">
           <para>Why do I get a message reading <errorname>Error: can't find
             libc.so.4.0</errorname>?</para>
         </question>
 
         <answer>
 
           <para>You accidently downloaded packages meant for 4.X and 5.X
             systems and attempted to install them on your 2.X or 3.X
             FreeBSD system. Please download the correct version of the
             packages.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="emul">
            <para>Why does ghostscript give lots of errors with my
               386/486SX?</para>
         </question>
 
         <answer>
           <para>You do not have a math co-processor, right?
             You will need to add the alternative math emulator to your
             kernel; you do this by adding the following to your kernel
             config file and it will be compiled in.</para>
 
           <programlisting>options GPL_MATH_EMULATE</programlisting>
 
             <note>
               <para>You will need to remove the
                 <literal>MATH_EMULATE</literal> option when you do
                 this.</para>
             </note>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="sco-socksys">
           <para>Why do SCO/iBCS2 applications bomb on
             <errorname>socksys</errorname>?  (FreeBSD 3.0 and older only).</para>
         </question>
 
         <answer>
           <para>You first need to edit the
             <filename>/etc/sysconfig</filename> (or
             <filename>/etc/rc.conf</filename>, see &man.rc.conf.5;) file in the last section to change the
             following variable to <literal>YES</literal>:</para>
 
           <programlisting># Set to YES if you want ibcs2 (SCO) emulation loaded at startup
 ibcs2=NO</programlisting>
 
           <para>It will load the ibcs2 kernel module at startup.</para>
 
           <para>You will then need to set up /compat/ibcs2/dev to look
             like:</para>
 
           <screen>lrwxr-xr-x  1 root  wheel         9 Oct 15 22:20 X0R@ -&gt; /dev/null
 lrwxr-xr-x  1 root  wheel         7 Oct 15 22:20 nfsd@ -&gt; socksys
 -rw-rw-r--  1 root  wheel         0 Oct 28 12:02 null
 lrwxr-xr-x  1 root  wheel         9 Oct 15 22:20 socksys@ -&gt; /dev/null
 crw-rw-rw-  1 root  wheel   41,   1 Oct 15 22:14 spx</screen>
 
           <para>You just need socksys to go to
             <devicename>/dev/null</devicename> (see &man.null.4;)
             to fake the open &amp; close. The code in -CURRENT will handle
             the rest. This is much cleaner than the way it was done before.
             If you want the <devicename>spx</devicename> driver for a local
             socket X connection, define <literal>SPX_HACK</literal> when
             you compile the system.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="configure-inn">
           <para>How do I configure INN (Internet News) for my machine?</para>
         </question>
 
         <answer>
           <para>After installing the <filename role="package">news/inn</filename> package or port, an excellent
             place to start is <ulink
             URL="http://www.cis.ohio-state.edu/~barr/INN.html">Dave Barr's
             INN Page</ulink> where you will find the INN FAQ.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ms-frontpage">
           <para>What version of Microsoft FrontPage should I get?</para>
         </question>
 
         <answer>
           <para>Use the Port, Luke!  A pre-patched version of Apache,
             <filename role="package">apache13-fp</filename>, is available in the ports
             tree.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="java">
           <para>Does FreeBSD support Java?</para>
         </question>
 
         <answer>
           <para>Yes. Please see <ulink
             URL="../../../../java/index.html">
             http://www.FreeBSD.org/java/</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ports-3x">
           <para>Why can I not build this port on my 3.X-STABLE machine?</para>
         </question>
 
         <answer>
           <para>If you are running a FreeBSD version that lags
             significantly behind -CURRENT or -STABLE, you may need a ports
             upgrade kit from <ulink URL="../../../../ports/index.html">
             http://www.FreeBSD.org/ports/</ulink>. If you are up to date,
             then someone might have committed a change to the port which
             works for -CURRENT but which broke the port for -STABLE. Please
             submit a bug report on this with the
             &man.send-pr.1; command, since the ports
             collection is supposed to work for both the -CURRENT and
             -STABLE branches.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="find-ldso">
           <para>Where do I find ld.so?</para>
         </question>
 
         <answer>
           <para>a.out applications like Netscape Navigator require
             a.out libraries.  A version of FreeBSD built with ELF
             libraries does not install them by default.  You will get
             complaints about not having
             <filename>/usr/libexec/ld.so</filename> if this is the
             case on your system.  These libraries are available as an
             add-on in the compat22 distribution.  Use
             &man.sysinstall.8; to install them.  You can
             also install them from the FreeBSD source code:</para>
 
           <screen>&prompt.root; <userinput>cd /usr/src/lib/compat/compat22</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
           <para>If you want to install the latest compat22 libraries
             whenever you run <command>make world</command>, edit
             <filename>/etc/make.conf</filename> to include
             <varname>COMPAT22=YES</varname>.  Old compatibility
             libraries change rarely, if ever, so this is not generally
             needed.</para>
 
           <para>Also see the ERRATAs for 3.1-RELEASE and
             3.2-RELEASE.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ports-update">
            <para>I updated the sources, now how do I update my installed
              ports?</para>
         </question>
 
         <answer>
           <para>FreeBSD does not include a port upgrading tool, but it
             does have some tools to make the upgrade process somewhat
             easier.  You can also install additional tools to simplify
             port handling.</para>
 
           <para>The &man.pkg.version.1; command can generate a script
             that will update installed ports to the latest version in
             the ports tree.</para>
 
           <screen>&prompt.root; <userinput>pkg_version <option>-c</option> > <replaceable>/tmp/myscript</replaceable></userinput></screen>
 
           <para>The output script <emphasis>must</emphasis> be edited by
             hand before you use it. Current versions of
             &man.pkg.version.1; force this by inserting an
             &man.exit.1; at the beginning of the script.</para>
 
           <para>You should save the output of the script, as it will note
             packages that depend on the one that has been updated. These
             may or may not need to be updated as well. The usual case where
             they need to be updated is that a shared library has changed
             version numbers, so the ports that used that library need to be
             rebuilt to use the new version.</para>
 
           <para>If you have the disk space, you can use the
             <command>portupgrade</command> tool to automate all of
             this.  <command>portupgrade</command> includes various
             tools to simplify package handling.  It is available under
             <filename role="package">sysutils/portupgrade</filename>.
             Since it is written in Ruby,
             <command>portupgrade</command> is an unlikely candidate for
             integration with the main FreeBSD tree.  That should not
             stop anyone from using it, however.</para>
 
-          <para>If your system is up full time, the &man.periodic.8 system
+          <para>If your system is up full time, the &man.periodic.8; system
             can be used to generate a weekly list of ports that might need
             updating by setting
             <literal>weekly_status_pkg_enable="YES"</literal> in
             <filename>/etc/periodic.conf</filename>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="minimal-sh">
           <para>Why is <command>/bin/sh</command> so minimal?  Why does
             FreeBSD not use <command>bash</command> or another shell?</para>
         </question>
 
         <answer>
           <para>Because POSIX says that there shall be such a shell.</para>
 
           <para>The more complicated answer: many people need to write shell
             scripts which will be portable across many systems. That is why
             POSIX specifies the shell and utility commands in great detail.
             Most scripts are written in Bourne shell, and because several
             important programming interfaces (&man.make.1;, &man.system.3;,
             &man.popen.3;, and analogues in higher-level scripting
             languages like Perl and Tcl) are specified to use the Bourne
             shell to interpret commands. Because the Bourne shell is so
             often and widely used, it is important for it to be quick to
             start, be deterministic in its behavior, and have a small
             memory footprint.</para>
 
           <para>The existing implementation is our best effort at meeting as
             many of these requirements simultaneously as we can. In order to
             keep <command>/bin/sh</command> small, we have not provided many
             of the convenience features that other shells have. That is why the
             Ports Collection includes more featureful shells like bash, scsh,
             tcsh, and zsh.  (You can compare for yourself the memory
             utilization of all these shells by looking at the
             <quote>VSZ</quote> and <quote>RSS</quote> columns in a <command>ps
               -u</command> listing.)</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="netscape-slow-startup">
           <para>Why do Netscape and Opera take so long to
             start?</para>
         </question>
 
         <answer>
           <para>The usual answer is that DNS on your system is
             misconfigured.  Both Netscape and Opera perform DNS checks
             when starting up.  The browser will not appear on your
             desktop until the program either gets a response or
             determines that the system has no network
             connection.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="kernelconfig">
     <title>Kernel Configuration</title>
 
     <qandaset>
       <qandaentry>
         <question id="make-kernel">
           <para>I would like to customize my kernel. Is it difficult?</para>
         </question>
 
         <answer>
           <para>Not at all! Check out the <ulink
             URL="../handbook/kernelconfig.html">
             kernel config section of the Handbook</ulink>.</para>
 
             <note>
 	      <para>We recommend that you make a dated snapshot of
 	        your new <filename>/kernel</filename> called
 	        <filename>/kernel.YYMMDD</filename> after you get it
 	        working properly.  Also back up your new
 	        <filename>/modules</filename> directory to
 	        <filename>/modules.YYMMDD</filename>.  That way, if
 	        you make a mistake the next time you play with your
 	        configuration you can boot the backup kernel instead
 	        of having to fall back to
 	        <filename>kernel.GENERIC</filename>. This is
 	        particularly important if you are now booting from a
 	        controller that GENERIC does not support.</para>
             </note>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="missing-hw-float">
           <para>My kernel compiles fail because
             <literal>_hw_float</literal> is missing.  How do I solve
             this problem?</para>
         </question>
 
         <answer>
           <para>Let me guess. You removed
             <devicename>npx0</devicename> (see &man.npx.4;)
             from your kernel configuration file because you do not have a
             math co-processor, right? Wrong! :-) The
             <devicename>npx0</devicename> is
             <emphasis>MANDATORY</emphasis>. Even if you do not have a
             mathematic co-processor, you <emphasis>must</emphasis>
             include the <devicename>npx0</devicename> device.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="why-kernel-big">
           <para>Why is my kernel so big (over 10MB)?</para>
         </question>
 
         <answer>
           <para>Chances are, you compiled your kernel in
             <emphasis>debug mode</emphasis>.  Kernels built in debug
             mode contain many symbols that are used for debugging, thus
             greatly increasing the size of the kernel.  Note that if you
             running a FreeBSD 3.0 or later system, there will be little
             or no performance decrease from running a debug kernel,
             and it is useful to keep one around in case of a system
             panic.</para>
 
           <para>However, if you are running low on disk space, or
             you simply do not want to run a debug kernel, make sure
             that both of the following are true:</para>
 
           <itemizedlist>
             <listitem>
               <para>You do not have a line in your kernel
                 configuration file that reads:</para>
 
               <programlisting>makeoptions DEBUG=-g</programlisting>
             </listitem>
 
             <listitem>
               <para>You are not running &man.config.8; with
                 the <option>-g</option> option.</para>
             </listitem>
           </itemizedlist>
 
           <para>Both of the above situations will cause your kernel to
             be built in debug mode.  As long as you make sure you follow
             the steps above, you can build your kernel normally, and you
             should notice a fairly large size decrease; most kernels
             tend to be around 1.5MB to 2MB.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="multiport-serial-interrupts">
           <para>Why do I get interrupt conflicts with multi-port serial
             code?</para>
         </question>
 
         <answer>
           <para>When I compile a kernel
             with multi-port serial code, it tells me that only the first
             port is probed and the rest skipped due to interrupt conflicts.
             How do I fix this?</para>
 
           <para>The problem here is that
             FreeBSD has code built-in to keep the kernel from getting
             trashed due to hardware or software conflicts. The way to fix
             this is to leave out the IRQ settings on all but one port. Here
             is a example:</para>
 
           <programlisting>#
 # Multiport high-speed serial line - 16550 UARTS
 #
 device sio2 at isa? port 0x2a0 tty irq 5 flags 0x501 vector siointr
 device sio3 at isa? port 0x2a8 tty flags 0x501 vector siointr
 device sio4 at isa? port 0x2b0 tty flags 0x501 vector siointr
 device sio5 at isa? port 0x2b8 tty flags 0x501 vector siointr</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="generic-kernel-build-failure">
           <para>Why does every kernel I try to build fail to compile, even
             GENERIC?</para>
         </question>
 
         <answer>
           <para>There are a number of possible causes for this problem.
             They are, in no particular order:</para>
 
           <itemizedlist>
             <listitem>
               <para>You are not using the new <command>make
                 buildkernel</command> and <command>make
                 installkernel</command> targets, and your source tree is
                 different from the one used to build the currently running
                 system (e.g., you are compiling 4.3-RELEASE on a 4.0-RELEASE
                 system).  If you are attempting an upgrade, please read the
                 <filename>/usr/src/UPDATING</filename> file, paying
                 particular attention to the <quote>COMMON ITEMS</quote>
                 section at the end.</para>
             </listitem>
 
             <listitem>
               <para>You are using the new <command>make
                 buildkernel</command> and <command>make
                 installkernel</command> targets, but you failed to assert
                 the completion of the <command>make buildworld</command>
                 target.  The <command>make buildkernel</command> target
                 relies on files generated by the <command>make
                 buildworld</command> target to complete its job
                 correctly.</para>
             </listitem>
 
             <listitem>
               <para>Even if you are trying to build <link
                 linkend="stable">FreeBSD-STABLE</link>, it is possible that
                 you fetched the source tree at a time when it was either
                 being modified, or broken for other reasons; only releases
                 are absolutely guaranteed to be buildable, although <link
                 linkend="stable">FreeBSD-STABLE</link> builds fine the
                 majority of the time.  If you have not already done so, try
                 re-fetching the source tree and see if the problem goes
                 away.  Try using a different server in case the one you are
                 using is having problems.</para>
             </listitem>
           </itemizedlist>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="disks">
     <title>Disks, Filesystems, and Boot Loaders</title>
 
     <qandaset>
       <qandaentry>
         <question id="adding-disks">
           <para>How can I add my new hard disk to my FreeBSD system?</para>
         </question>
 
         <answer>
           <para>See the Disk Formatting Tutorial at <ulink
             URL="../../articles/formatting-media/index.html">
             www.FreeBSD.org</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="new-huge-disk">
           <para>How do I move my system over to my huge new disk?</para>
         </question>
 
         <answer>
           <para>The best way is to reinstall the OS on the new
             disk, then move the user data over.  This is highly
             recommended if you have been tracking -stable for more
             than one release, or have updated a release instead of
             installing a new one.  You can install booteasy on both
             disks with &man.boot0cfg.8;, and dual boot them until
             you are happy with the new configuration.  Skip the
             next paragraph to find out how to move the data after
             doing this.</para>
 
           <para>Should you decide not to do a fresh install, you
             need to partition and label the new disk with either
             <filename>/stand/sysinstall</filename>, or &man.fdisk.8;
             and &man.disklabel.8;.  You should also install booteasy
             on both disks with &man.boot0cfg.8;, so that you can
             dual boot to the old or new system after the copying
             is done.  See the <ulink
             url="../../articles/formatting-media/index.html">
             formatting-media article</ulink> for details on this
             process.</para>
 
           <para>Now you have the new disk set up, and are ready
             to move the data.  Unfortunately, you cannot just blindly
             copy the data.  Things like device files (in
 	    <filename>/dev</filename>), flags, and links tend to
             screw that up.  You need to use tools that understand
             these things, which means &man.dump.8;.
             Although it is suggested that you move the data in single user
             mode, it is not required.</para>
 
           <para>You should never use anything but &man.dump.8; and
             &man.restore.8; to move the root file system.  The
             &man.tar.1; command may work - then again, it may not.
             You should also use &man.dump.8; and &man.restore.8;
             if you are moving a single partition to another empty
             partition.  The sequence of steps to use dump to move
             a partitions data to a new partition is:</para>
 
           <procedure>
             <step>
               <para>newfs the new partition.</para>
             </step>
 
             <step>
               <para>mount it on a temporary mount point.</para>
             </step>
 
             <step>
               <para>cd to that directory.</para>
             </step>
 
             <step>
               <para>dump the old partition, piping output to the
                 new one.</para>
             </step>
           </procedure>
 
           <para>For example, if you are going to move root to
             <devicename>/dev/ad1s1a</devicename>, with
             <filename>/mnt</filename> as the temporary mount point,
             it is:</para>
 
           <screen>&prompt.root; <userinput>newfs /dev/ad1s1a</userinput>
 &prompt.root; <userinput>mount /dev/ad1s1a /mnt</userinput>
 &prompt.root; <userinput>cd /mnt</userinput>
 &prompt.root; <userinput>dump 0af - / | restore xf -</userinput></screen>
 
           <para>Rearranging your partitions with dump takes a bit more
             work. To merge a partition like <filename>/var</filename>
             into its parent, create the new partition large enough
             for both, move the parent partition as described above,
             then move the child partition into the empty directory
             that the first move created:</para>
 	  
           <screen>&prompt.root; <userinput>newfs /dev/ad1s1a</userinput>
 &prompt.root; <userinput>mount /dev/ad1s1a /mnt</userinput>
 &prompt.root; <userinput>cd /mnt</userinput>
 &prompt.root; <userinput>dump 0af - / | restore xf -</userinput>
 &prompt.root; <userinput>cd var</userinput>
 &prompt.root; <userinput>dump 0af - /var | restore xf -</userinput></screen>
 
 	  <para>To split a directory from its parent, say putting
 	    <filename>/var</filename> on its own partition when it was not
 	    before, create both partitions, then mount the child partition
 	    on the appropriate directory in the temporary mount point, then
 	    move the old single partition:</para>
 
           <screen>&prompt.root; <userinput>newfs /dev/ad1s1a</userinput>
 &prompt.root; <userinput>newfs /dev/ad1s1d</userinput>
 &prompt.root; <userinput>mount /dev/ad1s1a /mnt</userinput>
 &prompt.root; <userinput>mkdir /mnt/var</userinput>
 &prompt.root; <userinput>mount /dev/ad1s1d /mnt/var</userinput>
 &prompt.root; <userinput>cd /mnt</userinput>
 &prompt.root; <userinput>dump 0af - / | restore xf -</userinput></screen>
 
           <para>You might prefer &man.cpio.1;, &man.pax.1;,
             &man.tar.1; to &man.dump.8; for user data. At the time of
             this writing, these are known to lose file flag information,
             so use them with caution.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="dangerously-dedicated">
           <para>Will a <quote>dangerously dedicated</quote> disk endanger
             my health?</para>
         </question>
 
         <answer>
 
           <para><anchor id="dedicate">The installation procedure allows
             you to chose two different methods in partitioning your
             hard disk(s). The default way makes it compatible with other
             operating systems on the same machine, by using fdisk table
             entries (called <quote>slices</quote> in FreeBSD), with a
             FreeBSD slice that employs partitions of its own. Optionally,
             one can chose to install a boot-selector to switch between the
             possible operating systems on the disk(s). The alternative uses
             the entire disk for FreeBSD, and makes no attempt to be
             compatible with other operating systems.</para>
 
           <para>So why it is called <quote>dangerous</quote>?  A disk in
             this mode does not contain what normal PC utilities would
             consider a valid fdisk table. Depending on how well they have
             been designed, they might complain at you once they are getting
             in contact with such a disk, or even worse, they might damage
             the BSD bootstrap without even asking or notifying you. In
             addition, the <quote>dangerously dedicated</quote> disk's
             layout is known to confuse many BIOSes, including those from
             AWARD (e.g. as found in HP Netserver and Micronics systems as
             well as many others) and Symbios/NCR (for the popular 53C8xx
             range of SCSI controllers). This is not a complete list, there
             are more. Symptoms of this confusion include the <errorname>read
             error</errorname> message printed by the FreeBSD bootstrap when it
             cannot find itself, as well as system lockups when
             booting.</para>
 
           <para>Why have this mode at all then?  It only saves a few kbytes
             of disk space, and it can cause real problems for a new
             installation. <quote>Dangerously dedicated</quote> mode's
             origins lie in a desire to avoid one of the most common
             problems plaguing new FreeBSD installers - matching the BIOS
             <quote>geometry</quote> numbers for a disk to the disk
             itself.</para>
 
           <para><quote>Geometry</quote> is an outdated concept, but one
             still at the heart of the PC's BIOS and its interaction with
             disks. When the FreeBSD installer creates slices, it has to
             record the location of these slices on the disk in a fashion
             that corresponds with the way the BIOS expects to find them. If
             it gets it wrong, you will not be able to boot.</para>
 
           <para><quote>Dangerously dedicated</quote> mode tries to work
             around this by making the problem simpler. In some cases, it
             gets it right. But it is meant to be used as a last-ditch
             alternative - there are better ways to solve the problem 99
             times out of 100.</para>
 
           <para>So, how do you avoid the need for <quote>DD</quote> mode
             when you are installing? Start by making a note of the geometry
             that your BIOS claims to be using for your disks. You can
             arrange to have the kernel print this as it boots by specifying
             <option>-v</option> at the <literal>boot:</literal> prompt, or
             using <command>boot -v</command> in the loader. Just before the
             installer starts, the kernel will print a list of BIOS
             geometries. Do not panic - wait for the installer to start and
             then use scrollback to read the numbers. Typically the BIOS
             disk units will be in the same order that FreeBSD lists your
             disks, first IDE, then SCSI.</para>
 
           <para>When you are slicing up your disk, check that the disk
             geometry displayed in the FDISK screen is correct (ie. it
             matches the BIOS numbers); if it is wrong, use the
             <literal>g</literal> key to fix it. You may have to do this if
             there is absolutely nothing on the disk, or if the disk has been
             moved from another system. Note that this is only an issue with
             the disk that you are going to boot from; FreeBSD will sort
             itself out just fine with any other disks you may have.</para>
 
           <para>Once you have got the BIOS and FreeBSD agreeing about the
             geometry of the disk, your problems are almost guaranteed to be
             over, and with no need for <quote>DD</quote> mode at all. If,
             however, you are still greeted with the dreaded <errorname>read
             error</errorname> message when you try to boot, it is time to cross
             your fingers and go for it - there is nothing left to
             lose.</para>
 
           <para>To return a <quote>dangerously dedicated</quote> disk
             for normal PC use, there are basically two options. The first
             is, you write enough NULL bytes over the MBR to make any
             subsequent installation believe this to be a blank disk. You
             can do this for example with</para>
 
           <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda0 count=15</userinput></screen>
 
           <para>Alternatively, the undocumented DOS
             <quote>feature</quote></para>
 
           <screen><prompt>C:\&gt;</prompt> <userinput>fdisk /mbr</userinput></screen>
 
           <para>will to install a new master boot record as well, thus
             clobbering the BSD bootstrap.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="safe-softupdates">
           <para>Which partitions can safely use softupdates?  I have
             heard that softupdates on <filename>/</filename> can cause
             problems.</para>
         </question>
 
         <answer>
           <para>Short answer: you can usually use softupdates safely
             on all partitions.</para>
 
           <para>Long answer: There used to be some concern over using
             softupdates on the root partition.  Softupdates has two
             characteristics that caused this.  First, a softupdates
             partition has a small chance of losing data during a
             system crash.  (The partition will not be corrupted; the
             data will simply be lost.)  Also, softupdates can cause
             temporary space shortages.</para>
 
           <para>When using softupdates, the kernel can take up to
             thirty seconds to actually write changes to the physical
             disk.  If you delete a large file, the file still resides
             on disk until the kernel actually performs the deletion.
             This can cause a very simple race condition.  Suppose you
             delete one large file and immediately create another large
             file.  The first large file is not yet actually removed
             from the physical disk, so the disk might not have enough
             room for the second large file.  You get an error that the
             partition does not have enough space, although you know
             perfectly well that you just released a large chunk of
             space!  When you try again mere seconds later, the file
             creation works as you expect.  This has left more than one
             user scratching his head and doubting his sanity, the
             FreeBSD filesystem, or both.</para>
 
           <para>If a system should crash after the kernel accepts a
             chunk of data for writing to disk, but before that data is
             actually written out, data could be lost or corrupted.
             This risk is extremely small, but generally manageable.
             Use of IDE write caching greatly increases this risk; it
             is strongly recommended that you disable IDE write caching
             when using softupdates.</para>
 
           <para>These issues affect all partitions using softupdates.
             So, what does this mean for the root partition?</para>
 
           <para>Vital information on the root partition changes very
             rarely.  Files such as <filename>/kernel</filename> and
             the contents of <filename>/etc</filename> only change
             during system maintenance, or when users change their
             passwords.  If the system crashed during the
             thirty-second window after such a change is made, it is
             possible that data could be lost.  This risk is negligible
             for most applications, but you should be aware that it
             exists.  If your system cannot tolerate this much risk,
             do not use softupdates on the root filesystem!</para>
 
           <para><filename>/</filename> is traditionally one of the
             smallest partitions.  By default, FreeBSD puts the
             <filename>/tmp</filename> directory on
             <filename>/</filename>.  If you have a busy
             <filename>/tmp</filename>, you might see intermittent
             space problems.  Symlinking <filename>/tmp</filename> to
             <filename>/var/tmp</filename> will solve this
             problem.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="inappropriate-ccd">
           <para>What is inappropriate about my ccd?</para>
         </question>
 
         <answer>
           <para>The symptom of this is:</para>
 
           <screen>&prompt.root; <userinput>ccdconfig -C</userinput>
 ccdconfig: ioctl (CCDIOCSET): /dev/ccd0c: Inappropriate file type or format</screen>
 
           <para>This usually happens when you are trying to concatenate
             the <literal>c</literal> partitions, which default to type
             <literal>unused</literal>. The ccd driver requires the
             underlying partition type to be FS_BSDFFS. Edit the disklabel
             of the disks you are trying to concatenate and change the types
             of partitions to <literal>4.2BSD</literal>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ccd-disklabel">
           <para>Why can I not edit the disklabel on my ccd?</para>
         </question>
 
         <answer>
           <para>The symptom of this is:</para>
 
           <screen>&prompt.root; <userinput>disklabel ccd0</userinput>
 (it prints something sensible here, so let us try to edit it)
 &prompt.root; <userinput>disklabel -e ccd0</userinput>
 (edit, save, quit)
 disklabel: ioctl DIOCWDINFO: No disk label on disk;
 use "disklabel -r" to install initial label</screen>
 
           <para>This is because the disklabel returned by ccd is actually
             a <quote>fake</quote> one that is not really on the disk.
             You can solve this problem by writing it back explicitly,
             as in:</para>
 
           <screen>&prompt.root; <userinput>disklabel ccd0 &gt; /tmp/disklabel.tmp</userinput>
 &prompt.root; <userinput>disklabel -Rr ccd0 /tmp/disklabel.tmp</userinput>
 &prompt.root; <userinput>disklabel -e ccd0</userinput>
 (this will work now)</screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="mount-foreign-fs">
           <para>Can I mount other foreign filesystems under FreeBSD?</para>
         </question>
 
         <answer>
           <variablelist>
             <varlistentry>
               <term>Digital UNIX</term>
 
               <listitem>
                 <para>UFS CDROMs can be mounted directly on FreeBSD.
                   Mounting disk partitions from Digital UNIX and other
                   systems that support UFS may be more complex, depending
                   on the details of the disk partitioning for the operating
                   system in question.</para>
               </listitem>
             </varlistentry>
 
             <varlistentry>
               <term>Linux</term>
 
               <listitem>
                 <para>As of 2.2, FreeBSD supports <literal>ext2fs</literal>
                   partitions.  See &man.mount.ext2fs.8; for more
                   information.</para>
               </listitem>
             </varlistentry>
 
             <varlistentry>
               <term>NT</term>
 
               <listitem>
                 <para>A read-only NTFS driver exists for FreeBSD. For more
                   information, see this tutorial by Mark Ovens at <ulink
                   URL="http://ukug.uk.FreeBSD.org/~mark/ntfs_install.html">
                   http://ukug.uk.FreeBSD.org/~mark/ntfs_install.html</ulink>.
                   </para>
               </listitem>
             </varlistentry>
           </variablelist>
 
           <para>Any other information on this subject would be
             appreciated.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="mount-dos">
           <para>How do I mount a secondary DOS partition?</para>
         </question>
 
         <answer>
 
         <para>The secondary DOS partitions are found after ALL the primary
           partitions. For example, if you have an <quote>E</quote>
           partition as the second DOS partition on the second SCSI drive,
           you need to create the special files for <quote>slice 5</quote>
           in /dev, then mount /dev/da1s5:</para>
 
         <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV da1s5</userinput>
 &prompt.root; <userinput>mount -t msdos /dev/da1s5 /dos/e</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="crypto-filesystem">
           <para>Is there a cryptographic filesystem for &os;?</para>
         </question>
 
         <answer>
           <para>Yes; see the <filename role="package">security/cfs</filename> port.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="nt-bootloader">
           <para>How can I use the NT loader to boot FreeBSD?</para>
         </question>
 
         <answer>
           <para>This procedure is slightly different for 2.2.x and 3.x
             (with the 3-stage boot) systems.</para>
 
           <para>The general idea is that you copy the first sector of your
             native root FreeBSD partition into a file in the DOS/NT
             partition. Assuming you name that file something like
             <filename>c:\bootsect.bsd</filename> (inspired by
             <filename>c:\bootsect.dos</filename>), you can then edit the
             <filename>c:\boot.ini</filename> file to come up with something
             like this:</para>
 
           <programlisting>[boot loader]
 timeout=30
 default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
 [operating systems]
 multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT"
 C:\BOOTSECT.BSD="FreeBSD"
 C:\="DOS"</programlisting>
 
           <para>For 2.2.x systems this procedure assumes that DOS, NT,
             FreeBSD, or whatever have been installed into their respective
             fdisk partitions on the <emphasis>same</emphasis>
             disk.  This example was tested on a system where DOS &amp; NT
             were on the first fdisk partition, and FreeBSD on the second.
             FreeBSD was also set up to boot from its native partition, not
             the disk's MBR.</para>
 
           <para>Mount a DOS-formatted floppy (if you have converted to NTFS)
             or the FAT partition, under, say,
             <filename>/mnt</filename>.</para>
 
           <screen>&prompt.root; <userinput>dd if=/dev/rda0a of=/mnt/bootsect.bsd bs=512 count=1</userinput></screen>
 
           <para>Reboot into DOS or NT.  NTFS users copy the
             <filename>bootsect.bsd</filename> and/or the
             <filename>bootsect.lnx</filename> file from the floppy to
             <filename>C:\</filename>. Modify the attributes (permissions)
             on <filename>boot.ini</filename> with:</para>
 
           <screen><prompt>C:\&gt;</prompt> <userinput>attrib -s -r c:\boot.ini</userinput></screen>
 
           <para>Edit to add the appropriate entries from the example
             <filename>boot.ini</filename> above, and restore the
             attributes:</para>
 
           <screen><prompt>C:\&gt;</prompt> <userinput>attrib +s +r c:\boot.ini</userinput></screen>
 
           <para>If FreeBSD is booting from the MBR, restore it with the DOS
             <command>fdisk</command> command after you reconfigure them to
             boot from their native partitions.</para>
 
           <para>For FreeBSD 3.x systems the procedure is somewhat
             simpler.</para>
 
           <para>If FreeBSD is installed on the same disk as the NT boot
             partition simply copy <filename>/boot/boot1</filename> to
             <filename>C:\BOOTSECT.BSD</filename> However, if FreeBSD is
             installed on a different disk <filename>/boot/boot1</filename>
             will not work, <filename>/boot/boot0</filename> is needed.
 
             <warning>
               <para>DO NOT SIMPLY COPY <filename>/boot/boot0</filename>
                 INSTEAD OF <filename>/boot/boot1</filename>, YOU WILL
                 OVERWRITE YOUR PARTITION TABLE AND RENDER YOUR COMPUTER
                 UN-BOOTABLE!</para>
             </warning>
 
             <filename>/boot/boot0</filename> needs to be installed using
               sysinstall by selecting the FreeBSD boot manager on the
               screen which asks if you wish to use a boot manager. This is
               because <filename>/boot/boot0</filename> has the partition
               table area filled with NULL characters but sysinstall copies
               the partition table before copying
               <filename>/boot/boot0</filename> to the MBR.</para>
 
           <para>When the FreeBSD boot manager runs it records the last
             OS booted by setting the active flag on the partition table
             entry for that OS and then writes the whole 512-bytes of itself
             back to the MBR so if you just copy
             <filename>/boot/boot0</filename> to
             <filename>C:\BOOTSECT.BSD</filename> then it writes an empty
             partition table, with the active flag set on one entry, to the
             MBR.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="lilo-bootloader">
           <para>How do I boot FreeBSD and Linux from LILO?</para>
         </question>
 
         <answer>
           <para>If you have FreeBSD and Linux on the same disk, just follow
             LILO's installation instructions for booting a non-Linux
             operating system.  Very briefly, these are:</para>
 
           <para>Boot Linux, and add the following lines to
             <filename>/etc/lilo.conf</filename>:</para>
 
             <programlisting>other=/dev/hda2
         table=/dev/hda
         label=FreeBSD</programlisting>
 
           <para>(the above assumes that your FreeBSD slice is known to Linux
             as <devicename>/dev/hda2</devicename>; tailor to suit your setup).
             Then, run <command>lilo</command> as <username>root</username> and you should be
             done.</para>
 
           <para>If FreeBSD resides on another disk, you need to add
             <literal>loader=/boot/chain.b</literal> to the LILO entry.
             For example:</para>
 
           <programlisting>other=/dev/dab4
         table=/dev/dab
         loader=/boot/chain.b
         label=FreeBSD</programlisting>
 
           <para>In some cases you may need to specify the BIOS drive number
             to the FreeBSD boot loader to successfully boot off the second
             disk.  For example, if your FreeBSD SCSI disk is probed by BIOS
             as BIOS disk 1, at the FreeBSD boot loader prompt you need to
             specify:</para>
 
           <screen>Boot: <userinput>1:da(0,a)/kernel</userinput></screen>
 
           <para>On FreeBSD 2.2.5 and later, you can configure
             &man.boot.8;
             to automatically do this for you at boot time.</para>
 
           <para>The <ulink
             URL="http://sunsite.unc.edu/LDP/HOWTO/mini/Linux+FreeBSD.html">
             Linux+FreeBSD mini-HOWTO</ulink> is a good reference for
             FreeBSD and Linux interoperability issues.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="booteasy-loader">
           <para>How do I boot FreeBSD and Linux using BootEasy?</para>
         </question>
 
         <answer>
           <para>Install LILO at the start of your Linux boot partition
             instead of in the Master Boot Record.   You can then boot LILO
             from BootEasy.</para>
 
           <para>If you are running Windows-95 and Linux this is recommended
             anyway, to make it simpler to get Linux booting again if you
             should need to reinstall Windows95 (which is a Jealous
             Operating System, and will bear no other Operating Systems in
             the Master Boot Record).</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="changing-bootprompt">
           <para>How do I change the boot prompt from <literal>???</literal> to
             something more meaningful?</para>
         </question>
 
         <answer>
           <para>You can not do that with the standard boot manager without
             rewriting it. There are a number of other boot managers
             in the <filename>sysutils</filename> ports category that
             provide this functionality.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="removable-drives">
           <para>I have a new removable drive, how do I use it?</para>
         </question>
 
         <answer>
 
           <para>Whether it is a removable drive like a ZIP or an EZ drive
             (or even a floppy, if you want to use it that way), or a new
             hard disk, once it is installed and recognized by the system,
             and you have your cartridge/floppy/whatever slotted in, things
             are pretty much the same for all devices.</para>
 
           <para><anchor id="disklabel">(this section is based on <ulink
             URL="http://www.vmunix.com/mark/FreeBSD/ZIP-FAQ.html">
             Mark Mayo's ZIP FAQ</ulink>)</para>
 
           <para>If it is a ZIP drive or a floppy, you have already got a DOS
             filesystem on it, you can use a command like this:</para>
 
           <screen>&prompt.root; <userinput>mount -t msdos /dev/fd0c /floppy</userinput></screen>
 
           <para>if it is a floppy, or this:</para>
 
           <screen>&prompt.root; <userinput>mount -t msdos /dev/da2s4 /zip</userinput></screen>
 
           <para>for a ZIP disk with the factory configuration.</para>
 
           <para>For other disks, see how they are laid out using
             &man.fdisk.8; or
             &man.sysinstall.8;.</para>
 
           <para>The rest of the examples will be for a ZIP drive on da2,
             the third SCSI disk.</para>
 
           <para>Unless it is a floppy, or a removable you plan on sharing
             with other people, it is probably a better idea to stick a BSD
             file system on it. You will get long filename support, at least a
             2X improvement in performance, and a lot more stability. First,
             you need to redo the DOS-level partitions/filesystems. You can
             either use &man.fdisk.8; or
             <filename>/stand/sysinstall</filename>, or for a small drive
             that you do not want to bother with multiple operating system
             support on, just blow away the whole FAT partition table
             (slices) and just use the BSD partitioning:</para>
 
           <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/rda2 count=2</userinput>
 &prompt.root; <userinput>disklabel -Brw da2 auto</userinput></screen>
 
           <para>You can use disklabel or
             <filename>/stand/sysinstall</filename> to create multiple BSD
             partitions. You will certainly want to do this if you are adding
             swap space on a fixed disk, but it is probably irrelevant on a
             removable drive like a ZIP.</para>
 
           <para>Finally, create a new file system, this one is on our ZIP
             drive using the whole disk:</para>
 
           <screen>&prompt.root; <userinput>newfs /dev/rda2c</userinput></screen>
 
           <para>and mount it:</para>
 
           <screen>&prompt.root; <userinput>mount /dev/da2c /zip</userinput></screen>
 
           <para>and it is probably a good idea to add a line like this to
             <filename>/etc/fstab</filename> (see &man.fstab.5;) so you can just type
             <command>mount /zip</command> in the future:</para>
 
           <programlisting>/dev/da2c /zip ffs rw,noauto 0 0</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="mount-cd-superblock">
           <para>Why do I get <errorname>Incorrect super block</errorname> when
             mounting a CDROM?</para>
         </question>
 
         <answer>
           <para>You have to tell &man.mount.8; the type of the device
             that you want to mount.  This is described in the <ulink
             URL="../handbook/creating-cds.html"> Handbook section on
             optical media</ulink>, specifically the section <ulink
             URL="../handbook/creating-cds.html#MOUNTING-CD">Using Data
             CDs</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="cdrom-not-configured">
           <para>Why do I get <errorname>Device not configured</errorname> when
             mounting a CDROM?</para>
         </question>
 
         <answer>
           <para>This generally means that there is no CDROM in the
             CDROM drive, or the drive is not visible on the
             bus. Please see the <ulink
             URL="../handbook/creating-cds.html#MOUNTING-CD">Using Data
             CDs</ulink> section of the Handbook for a detailed
             discussion of this issue.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="cdrom-unicode-filenames">
           <para>Why do all non-English characters in filenames show up as
             <quote>?</quote> on my CDs when mounted in FreeBSD?</para>
         </question>
 
         <answer>
           <para>Your CDROM probably uses the <quote>Joliet</quote>
             extension for storing information about files and
             directories.  This is discussed in the Handbook chapter on
             <ulink URL="../handbook/creating-cds.html">creating and
             using CDROMs</ulink>, specifically the section on <ulink
             URL="../handbook/creating-cds.html#MOUNTING-CD">Using Data
             CDROMs</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="burncd-isofs">
           <para>I burned a CD under FreeBSD and now I can not read it
             under any other operating system. Why?</para>
         </question>
   
         <answer>
           <para>You most likely burned a raw file to your CD, rather
             than creating an ISO 9660 filesystem.  Take a look at the
             <ulink URL="../handbook/creating-cds.html">Handbook
             chapter on creating CDROMs</ulink>, particularly the
             section on <ulink
             URL="../handbook/creating-cds.html#RAWDATA-CD">burning raw
             data CDs</ulink>.</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
         <question id="copy-cd">
           <para>How can I create an image of a data CD?</para>
         </question>
 
         <answer>
           <para>This is discussed in the Handbook section on <ulink
             url="../handbook/creating-cds.html#IMAGING-CD">duplicating
             data CDs</ulink>. For more on working with CDROMs, see the
             <ulink url="../handbook/creating-cds.html">Creating CDs
             Section</ulink> in the Storage chapter in the
             Handbook.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="mount-audio-CD">
           <para>Why can I not <command>mount</command> an audio
           CD?</para>
          </question>
 
         <answer>
           <para>If you try to mount an audio CD, you will get an error
             like <errorname>cd9660: /dev/acd0c: Invalid
             argument</errorname>.  This is because
             <command>mount</command> only works on filesystems.  Audio
             CDs do not have filesystems; they just have data.  You
             need a program that reads audio CDs, such as the
             <filename role="package">audio/xmcd</filename> port.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="multi-session-CD">
           <para>How do I <command>mount</command> a multi-session CD?</para>
         </question>
 
         <answer>
           <para>By default, &man.mount.8; will attempt to mount the
             last data track (session) of a CD.  If you would like to
             load an earlier session, you must use the
             <option>-s</option> command line argument.  Please see
             &man.mount.cd9660.8; for specific examples.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="user-floppymount">
           <para>How do I let ordinary users mount floppies, CDROMs and
             other removable media?</para>
         </question>
 
         <answer>
           <para>Ordinary users can be permitted to mount devices. Here is
             how:</para>
 
           <procedure>
             <step>
               <para>As <username>root</username> set the sysctl variable
                 <varname>vfs.usermount</varname> to
                 <literal>1</literal>.</para>
 
               <screen>&prompt.root; <userinput>sysctl -w vfs.usermount=1</userinput></screen>
             </step>
 
             <step>
               <para>As <username>root</username> assign the appropriate
                 permissions to the block device associated with the
                 removable media.</para>
 
               <para>For example, to allow users to mount the first floppy
                 drive, use:</para>
 
               <screen>&prompt.root; <userinput>chmod 666 /dev/fd0</userinput></screen>
 
               <para>To allow users in the group
                 <groupname>operator</groupname> to mount the CDROM drive,
                 use:</para>
 
               <screen>&prompt.root; <userinput>chgrp operator /dev/cd0c</userinput>
 &prompt.root; <userinput>chmod 640 /dev/cd0c</userinput></screen>
             </step>
 
             <step>
               <para>Finally, add the line
                 <literal><varname>vfs.usermount</varname>=1</literal> to the file
                 <filename>/etc/sysctl.conf</filename> so that it is reset
                 at system boot time.</para>
             </step>
           </procedure>
 
           <para>All users can now mount the floppy
             <devicename>/dev/fd0</devicename> onto a directory that they
             own:</para>
 
           <screen>&prompt.user; <userinput>mkdir ~/my-mount-point</userinput>
 &prompt.user; <userinput>mount -t msdos /dev/fd0 ~/my-mount-point</userinput></screen>
 
           <para>Users in group <groupname>operator</groupname> can now
             mount the CDROM <devicename>/dev/cd0c</devicename> onto a
             directory that they own:</para>
 
           <screen>&prompt.user; <userinput>mkdir ~/my-mount-point</userinput>
 &prompt.user; <userinput>mount -t msdos /dev/cd0c ~/my-mount-point</userinput></screen>
 
           <para>Unmounting the device is simple:</para>
 
           <screen>&prompt.user; <userinput>umount <filename>~/my-mount-point</></userinput></screen>
 
           <para>Enabling <varname>vfs.usermount</varname>, however, has
             negative security implications.  A better way to access MSDOS
             formatted media is to use the <ulink
             URL="http://www.FreeBSD.org/cgi/ports.cgi?query=%5Emtools-&amp;stype=name">mtools</ulink> package in the ports collection.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="du-vs-df">
           <para>The <command>du</command> and <command>df</command>
             commands show different amounts of disk space available.
             What is going on?</para>
         </question>
 
         <answer>
           <para>You need to understand what <command>du</command> and
             <command>df</command> really do.  <command>du</command>
             goes through the directory tree, measures how large each
             file is, and presents the totals.  <command>df</command>
             just asks the filesystem how much space it has left.  They
             seem to be the same thing, but a file without a directory
             entry will affect <command>df</command> but not
             <command>du</command>.</para>
 
           <para>When a program is using a file, and you delete the
             file, the file is not really removed from the filesystem
             until the program stops using it.  The file is immediately
             deleted from the directory listing, however.  You can see
             this easily enough with a program such as
             <command>more</command>.  Assume you have a file large
             enough that its presence affects the output of
             <command>du</command> and <command>df</command>.  (Since
             disks can be so large today, this might be a
             <emphasis>very</emphasis> large file!)  If you delete this
             file while using <command>more</command> on it,
             <command>more</command> does not immediately choke and
             complain that it cannot view the file.  The entry is
             simply removed from the directory so no other program or
             user can access it.  <command>du</command> shows that it
             is gone &mdash; it has walked the directory tree and the file
             is not listed.  <command>df</command> shows that it is
             still there, as the filesystem knows that
             <command>more</command> is still using that space.  Once
             you end the <command>more</command> session,
             <command>du</command> and <command>df</command> will
             agree.</para>
 
           <para>Note that softupdates can delay the freeing of disk
             space; you might need to wait up to 30 seconds for the
             change to be visible!</para>
 
           <para>This situation is common on web servers.  Many people
             set up a FreeBSD web server and forget to rotate the log
             files.  The access log fills up <filename>/var</filename>.
             The new administrator deletes the file, but the system
             still complains that the partition is full.  Stopping and
             restarting the web server program would free the file,
             allowing the system to release the disk space.  To prevent
             this from happening, set up &man.newsyslog.8;.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="add-swap-space">
           <para>How can I add more swap space?</para>
         </question>
 
         <answer>
           <para>In the <ulink
           url="../handbook/config-tuning.html">Configuration and
           Tuning</ulink> section of the Handbook, you will find a
           <ulink
           url="../handbook/adding-swap-space.html">section</ulink>
           describing how to do this.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="admin">
     <title>System Administration</title>
 
     <qandaset>
       <qandaentry>
         <question id="startup-config-files">
           <para>Where are the system start-up configuration files?</para>
         </question>
 
         <answer>
 
           <para>From 2.0.5R to 2.2.1R, the primary configuration file is
             <filename>/etc/sysconfig</filename>. All the options are to be
             specified in this file and other files such as
             <filename>/etc/rc</filename> (see &man.rc.8;)
             and <filename>/etc/netstart</filename> just include it.</para>
 
           <para>Look in the <filename>/etc/sysconfig</filename> file and
             change the value to match your system. This file is filled with
             comments to show what to put in there.</para>
 
           <para>In post-2.2.1 and 3.0, <filename>/etc/sysconfig</filename>
             was renamed to a more self-describing &man.rc.conf.5;
             file and the syntax cleaned up a bit in the process.
             <filename>/etc/netstart</filename> was also renamed to
             <filename>/etc/rc.network</filename> so that all files could be
             copied with a
             <command>cp
             /usr/src/etc/rc* /etc</command> command.</para>
 
           <para>And, in 3.1 and later, <filename>/etc/rc.conf</filename>
             has been moved to <filename>/etc/defaults/rc.conf</filename>.
             <emphasis>Do not edit this file!</emphasis> Instead, if there
             is any entry in <filename>/etc/defaults/rc.conf</filename> that
             you want to change, you should copy the line into
             <filename>/etc/rc.conf</filename> and change it there.</para>
 
           <para>For example, if you wish to start named, the DNS server
             included with FreeBSD in FreeBSD 3.1 or later, all you need to
             do is:</para>
           <screen>&prompt.root; <userinput>echo named_enable="YES" &gt;&gt; /etc/rc.conf</userinput></screen>
 
           <para>To start up local services in FreeBSD 3.1 or later, place
             shell scripts in the <filename>/usr/local/etc/rc.d</filename>
             directory. These shell scripts should be set executable, and
             end with a .sh. In FreeBSD 3.0 and earlier releases, you should
             edit the <filename>/etc/rc.local</filename> file.</para>
 
           <para>The <filename>/etc/rc.serial</filename> is for serial port
             initialization (e.g. locking the port characteristics, and so
             on.).</para>
 
           <para>The <filename>/etc/rc.i386</filename> is for Intel-specifics
             settings, such as iBCS2 emulation or the PC system console
             configuration.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="adding-users">
           <para>How do I add a user easily?</para>
         </question>
 
         <answer>
           <para>Use the &man.adduser.8;
             command. For more complicated usage, the &man.pw.8;
             command.</para>
 
           <para>To remove the user again, use the &man.rmuser.8;
             command. Once again, &man.pw.8; will work as
             well.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="root-not-found-cron-errors">
           <para>Why do I keep getting messages like <errorname>root: not
             found</errorname> after editing my crontab file?</para>
         </question>
 
         <answer>
           <para>This is normally caused by editing the system crontab
             (<filename>/etc/crontab</filename>) and then using
             &man.crontab.1; to install it:</para>
 
           <screen>&prompt.root; <userinput>crontab /etc/crontab</userinput></screen>
 
           <para>This is not the correct way to do things.  The system
             crontab has a different format to the per-user crontabs
             which &man.crontab.1; updates (the &man.crontab.5; manual
             page explains the differences in more detail).</para>
 
           <para>If this is what you did, the extra crontab is simply a
             copy of <filename>/etc/crontab</filename> in the wrong
             format it.  Delete it with the command:</para>
 
           <screen>&prompt.root; <userinput>crontab -r</userinput></screen>
 
           <para>Next time, when you edit
             <filename>/etc/crontab</filename>, you should not do
             anything to inform &man.cron.8; of the changes, since it
             will notice them automatically.</para>
 
           <para>If you want something to be run once per day, week, or
             month, it is probably better to add shell scripts
             <filename>/usr/local/etc/periodic</filename>, and let the
             &man.periodic.8; command run from the system cron schedule
             it with the other periodic system tasks.</para>
 
           <para>The actual reason for the error is that the system
             crontab has an extra field, specifying which user to run the
             command as.  In the default system crontab provided with
             FreeBSD, this is <username>root</username> for all entries.
             When this crontab is used as the <username>root</username>
             user's crontab (which is <emphasis>not</emphasis> the
             same as the system crontab), &man.cron.8; assumes the string
             <literal>root</literal> is the first word of the command to
             execute, but no such command exists.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
 	<question id="su-wheel-group">
 	  <para>Why do I get the error, <errorname>you are not in the correct
 	    group to su root</errorname> when I try to su to root?</para>
 	</question>
 
 	<answer>
 	  <para>This is a security feature.  In order to su to
 	    <username>root</username> (or any other account with superuser
 	    privileges), you must be in the <groupname>wheel</groupname>
 	    group.  If this feature were not there, anybody with an account
 	    on a system who also found out <username>root</username>'s
 	    password would be able to gain superuser level access to the
 	    system.  With this feature, this is not strictly true;
 	    &man.su.1; will prevent them from even trying to enter the
 	    password if they are not in <groupname>wheel</groupname>.</para>
 
 	  <para>To allow someone to su to <username>root</username>, simply
 	    put them in the <groupname>wheel</groupname> group.</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
         <question id="rcconf-readonly">
           <para>I made a mistake in <filename>rc.conf</filename>,
             or another startup file, and
             now I cannot edit it because the filesystem is read-only.
             What should I do?</para>
         </question>
 
         <answer>
           <para>When you get the prompt to enter the shell
             pathname, simply press <literal>ENTER</literal>, and run
             <command>mount /</command> to re-mount the root filesystem in
             read/write mode. You may also need to run <command>mount -a -t
             ufs</command> to mount the filesystem where your favourite
             editor is defined. If your favourite editor is on a network
             filesystem, you will need to either configure the network
             manually before you can mount network filesystems, or use an
             editor which resides on a local filesystem, such as
             &man.ed.1;.</para>
 
           <para>If you intend to use a full screen editor such
             as &man.vi.1; or &man.emacs.1;, you may also need to
             run <command>export TERM=cons25</command> so that these
             editors can load the correct data from the &man.termcap.5;
             database.</para>
 
           <para>Once you have performed these steps, you can edit
             <filename>/etc/rc.conf</filename> as you usually would
             to fix the syntax error.  The error message displayed
             immediately after the kernel boot messages should tell you
             the number of the line in the file which is at fault.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="printer-setup">
           <para>Why am I having trouble setting up my printer?</para>
         </question>
 
         <answer>
           <para>Please have a look at the Handbook entry on printing. It
             should cover most of your problem. See the <ulink
             URL="../handbook/printing.html">
             Handbook entry on printing</ulink>.</para>
 
 	  <para>Some printers require a host-based driver to do any kind of
 	    printing.  These so-called <quote>WinPrinters</quote> are not
 	    natively supported by FreeBSD.  If your printer does not work
 	    in DOS or Windows NT 4.0, it is probably a WinPrinter.  Your
 	    only hope of getting one of these to work is to check if the
 	    <filename role="package">print/pnm2ppa</filename> port supports it.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="keyboard-mappings">
           <para>How can I correct the keyboard mappings for my system?</para>
         </question>
 
         <answer>
           <para>Please see the Handbook section on <ulink
             url="../handbook/using-localization.html">using
             localization</ulink>, specifically the section on <ulink
             url="../handbook/using-localization.html#SETTING-CONSOLE">console
             setup</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="pnp-resources">
           <para>Why do I get messages like: <errorname>unknown: &lt;PNP0303&gt;
             can't assign resources</errorname> on boot?</para>
         </question>
 
         <answer>
 	  <para>The following is an excerpt from a post to the
 	    freebsd-current mailing list.</para>
 
 	  <blockquote>
 	    <attribution>&a.wollman;, 24 April 2001</attribution>
 
 	    <para>The <quote>can't assign resources</quote> messages
 	      indicate that the devices are legacy ISA devices for which a
 	      non-PnP-aware driver is compiled into the kernel.  These
 	      include devices such as keyboard controllers, the
 	      programmable interrupt controller chip, and several other
 	      bits of standard infrastructure.  The resources cannot be
 	      assigned because there is already a driver using those
 	      addresses.</para>
 	  </blockquote>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="user-quotas">
           <para>Why can I not get user quotas to work properly?</para>
         </question>
 
         <answer>
 
             <orderedlist>
               <listitem>
                 <para>Do not turn on quotas on <filename>/</filename>,</para>
               </listitem>
 
               <listitem>
                 <para>Put the quota file on the file system that the quotas
                   are to be enforced on. ie:</para>
 
                 <informaltable frame="none">
                   <tgroup cols="2">
                     <thead>
                       <row>
                         <entry>Filesystem</entry>
                         <entry>Quota file</entry>
                       </row>
                     </thead>
 
                     <tbody>
                       <row>
                         <entry><filename>/usr</filename></entry>
                         <entry><filename>/usr/admin/quotas</filename></entry>
                       </row>
 
                       <row>
                         <entry><filename>/home</filename></entry>
                         <entry><filename>/home/admin/quotas</filename></entry>
                       </row>
 
                       <row>
                         <entry>&hellip;</entry>
                         <entry>&hellip;</entry>
                       </row>
                     </tbody>
                   </tgroup>
                 </informaltable>
               </listitem>
             </orderedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="sysv-ipc">
           <para>Does FreeBSD support System V IPC primitives?</para>
         </question>
 
         <answer>
           <para>Yes, FreeBSD supports System V-style IPC.  This includes
             shared memory, messages and semaphores.  You need to add the
             following lines to your kernel config to enable them.</para>
 
           <programlisting>options    SYSVSHM          # enable shared memory
 options    SYSVSEM          # enable for semaphores
 options    SYSVMSG          # enable for messaging</programlisting>
 
             <note>
               <para>In FreeBSD 3.2 and later, these options are already
                 part of the <emphasis>GENERIC</emphasis> kernel, which
                 means they should already be compiled into your
                 system.</para>
             </note>
 
           <para>Recompile and install your kernel.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="uucpmail">
           <para>How do I use sendmail for mail delivery with UUCP?</para>
         </question>
 
         <answer>
 
           <para>The sendmail configuration that ships with FreeBSD is
             suited for sites that connect directly to the Internet.
             Sites that wish to exchange their mail via UUCP must install
             another sendmail configuration file.</para>
 
           <para>Tweaking <filename>/etc/sendmail.cf</filename> manually is
             considered something for purists. Sendmail version 8 comes with
             a new approach of generating config files via some
             &man.m4.1;
             preprocessing, where the actual hand-crafted configuration is
             on a higher abstraction level. You should use the configuration
             files under
             <filename>/usr/src/usr.sbin/sendmail/cf</filename>.</para>
 
           <para>If you did not install your system with full sources,
             the sendmail config stuff has been broken out into a separate
             source distribution tarball just for you. Assuming you have got
             your CDROM mounted, do:</para>
 
           <screen>&prompt.root; <userinput>cd /cdrom/src</userinput>
 &prompt.root; <userinput>cat scontrib.?? | tar xzf - -C /usr/src contrib/sendmail</userinput></screen>
 
           <para>Do not panic, this is only a few hundred kilobytes in size.
             The file <filename>README</filename> in the
             <filename>cf</filename> directory can serve as a basic
             introduction to m4 configuration.</para>
 
           <para>For UUCP delivery, you are best advised to use the
             <literal>mailertable</literal> feature.  This constitutes a
             database that sendmail can use to base its routing decision
             upon.</para>
 
           <para>First, you have to create your <filename>.mc</filename>
             file.  The directory
             <filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> is the
             home of these files.  Look around, there are already a few
             examples.  Assuming you have named your file
             <filename>foo.mc</filename>, all you need to do in order to
             convert it into a valid <filename>sendmail.cf</filename>
             is:</para>
 
           <screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail/cf/cf</userinput>
 &prompt.root; <userinput>make foo.cf</userinput>
 &prompt.root; <userinput>cp foo.cf /etc/mail/sendmail.cf</userinput></screen>
 
           <para>A typical <filename>.mc</filename> file might look
             like:</para>
 
 
           <programlisting>VERSIONID(`<replaceable>Your version number</replaceable>')
 OSTYPE(bsd4.4)
 
 FEATURE(accept_unresolvable_domains)
 FEATURE(nocanonify)
 FEATURE(mailertable, `hash -o /etc/mail/mailertable')
 
 define(`UUCP_RELAY', <replaceable>your.uucp.relay</replaceable>)
 define(`UUCP_MAX_SIZE', 200000)
 define(`confDONT_PROBE_INTERFACES')
 
 MAILER(local)
 MAILER(smtp)
 MAILER(uucp)
 
 Cw    <replaceable>your.alias.host.name</replaceable>
 Cw    <replaceable>youruucpnodename.UUCP</replaceable></programlisting>
 
           <para>The lines containing <literal>accept_unresolvable_domains</literal>,
             <literal>nocanonify</literal>, and <literal>confDONT_PROBE_INTERFACES</literal> features will prevent any usage
             of the DNS during mail delivery.  The
             <literal>UUCP_RELAY</literal> clause is needed for bizarre
             reasons, do not ask.  Simply put an Internet hostname there that
             is able to handle .UUCP pseudo-domain addresses; most likely,
             you will enter the mail relay of your ISP there.</para>
 
           <para>Once you have got this, you need this file called
             <filename>/etc/mail/mailertable</filename>.  If have only
             one link to the outside that is used for all your mails,
             the following file will be enough:</para>
 
           <programlisting>#
 # makemap hash /etc/mail/mailertable.db &lt; /etc/mail/mailertable
 .                             uucp-dom:<replaceable>your.uucp.relay</replaceable></programlisting>
 
           <para>A more complex example might look like this:</para>
 
           <programlisting>#
 # makemap hash /etc/mail/mailertable.db &lt; /etc/mail/mailertable
 #
 horus.interface-business.de   uucp-dom:horus
 .interface-business.de        uucp-dom:if-bus
 interface-business.de         uucp-dom:if-bus
 .heep.sax.de                  smtp8:%1
 horus.UUCP                    uucp-dom:horus
 if-bus.UUCP                   uucp-dom:if-bus
 .                             uucp-dom:</programlisting>
 
 
           <para>As you can see, this is part of a real-life file.  The
             first three lines handle special cases where domain-addressed
             mail should not be sent out to the default route, but instead
             to some UUCP neighbor in order to <quote>shortcut</quote> the
             delivery path. The next line handles mail to the local Ethernet
             domain that can be delivered using SMTP. Finally, the UUCP
             neighbors are mentioned in the .UUCP pseudo-domain notation, to
             allow for a <literal><replaceable>uucp-neighbor
             </replaceable>!<replaceable>recipient</replaceable></literal>
             override of the default rules. The last line is always a single
             dot, matching everything else, with UUCP delivery to a UUCP
             neighbor that serves as your universal mail gateway to the
             world. All of the node names behind the
             <literal>uucp-dom:</literal> keyword must be valid UUCP
             neighbors, as you can verify using the command
             <literal>uuname</literal>.</para>
 
           <para>As a reminder that this file needs to be converted into a
             DBM database file before being usable, the command line to
             accomplish this is best placed as a comment at the top of
             the mailertable.  You always have to execute this command
             each time you change your mailertable.</para>
 
           <para>Final hint: if you are uncertain whether some particular
             mail routing would work, remember the <option>-bt</option>
             option to sendmail. It starts sendmail in <emphasis>address
             test mode</emphasis>; simply enter <literal>3,0</literal>,
             followed by the address you wish to test for the mail routing.
             The last line tells you the used internal mail agent, the
             destination host this agent will be called with, and the
             (possibly translated) address. Leave this mode by typing
             Control-D.</para>
 
           <screen>&prompt.user; <userinput>sendmail -bt</userinput>
 ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
 Enter &lt;ruleset&gt; &lt;address&gt;
 <prompt>&gt;</prompt> <userinput>3,0 foo@example.com</userinput>
 canonify           input: foo @ example . com
 ...
 parse            returns: $# uucp-dom $@ <replaceable>your.uucp.relay</replaceable> $: foo &lt; @ example . com . &gt;
 <prompt>&gt;</prompt> <userinput>^D</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ispmail">
           <para>How do I set up mail with a dialup connection to the
             'net?</para>
         </question>
 
         <answer>
           <para>If you have got a statically assigned IP number, you
             should not need to adjust anything from the default.  Set
             your host name up as your assigned Internet name and
             sendmail will do the rest.</para>
 
           <para>If you have got a dynamically assigned IP number and
             use a dialup PPP connection to the Internet, you will
             probably be given a mailbox on your ISPs mail server. Lets
             assume your ISPs domain is <hostid
             role="domainname">myISP.com</hostid>, and that your user
             name is <username>user</username>. Lets also assume you
             have called your machine <hostid
             role="fqdn">bsd.home</hostid> and that your ISP has told
             you that you may use <hostid
             role="fqdn">relay.myISP.com</hostid> as a mail
             relay.</para>
 
           <para>In order to retrieve mail from your mailbox, you will
             need to install a retrieval
             agent. <application>Fetchmail</application> is a good
             choice as it supports many different protocols. Usually,
             POP3 will be provided by your ISP. If you have chosen to
             use user-PPP, you can automatically fetch your mail when a
             connection to the 'net is established with the following
             entry in <filename>/etc/ppp/ppp.linkup</filename>:</para>
 
           <programlisting>MYADDR:
   !bg su user -c fetchmail</programlisting>
 
           <para>If you are using <application>sendmail</application>
             (as shown below) to deliver mail to non-local accounts,
             put the command</para>
 
           <programlisting>  !bg su user -c "sendmail -q"</programlisting>
 
           <para>after the above shown entry. This forces
             <application>sendmail</application> to process your
             mailqueue as soon as the connection to the 'net is
             established.</para>
 
           <para>I am assuming that you have an account for
             <username>user</username> on <hostid
             role="fqdn">bsd.home</hostid>. In the home directory of
             <username>user</username> on <hostid
             role="fqdn">bsd.home</hostid>, create a
             <filename>.fetchmailrc</filename> file:</para>
 
           <programlisting>poll myISP.com protocol pop3 fetchall pass MySecret</programlisting>
 
           <para>This file should not be readable by anyone except
             <username>user</username> as it contains the password
             <literal>MySecret</literal>.</para>
 
           <para>In order to send mail with the correct
             <literal>from:</literal> header, you must tell
             <application>sendmail</application> to use
             <literal>user@myISP.com</literal> rather than
             <literal>user@bsd.home</literal>. You may also wish to
             tell <application>sendmail</application> to send all mail
             via <hostid role="fqdn">relay.myISP.com</hostid>, allowing
             quicker mail transmission.</para>
 
           <para>The following <filename>.mc</filename> file should
             suffice:</para>
 
           <programlisting>VERSIONID(`bsd.home.mc version 1.0')
 OSTYPE(bsd4.4)dnl
 FEATURE(nouucp)dnl
 MAILER(local)dnl
 MAILER(smtp)dnl
 Cwlocalhost
 Cwbsd.home
 MASQUERADE_AS(`myISP.com')dnl
 FEATURE(allmasquerade)dnl
 FEATURE(masquerade_envelope)dnl
 FEATURE(nocanonify)dnl
 FEATURE(nodns)dnl
 define(`SMART_HOST', `relay.myISP.com')
 Dmbsd.home
 define(`confDOMAIN_NAME',`bsd.home')dnl
 define(`confDELIVERY_MODE',`deferred')dnl</programlisting>
 
           <para>Refer to the previous section for details of how to
             turn this <filename>.mc</filename> file into a
             <filename>sendmail.cf</filename> file.  Also, do not
             forget to restart <application>sendmail</application>
             after updating <filename>sendmail.cf</filename>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="sendmail-alternative">
           <para>What other mail-server software can I use, instead of
             Sendmail?</para>
         </question>
 
         <answer>
           <para><ulink url="http://www.sendmail.org/">Sendmail</ulink> is
             the default mail-server software for FreeBSD, but you can
             easily replace it with one of the other MTA (for instance,
             an MTA installed from the ports).</para>
 
           <para>There are various alternative MTA's in the ports tree
             already, with <filename role="package">mail/exim</filename>,
             <filename role="package">mail/postfix</filename>, <filename role="package">mail/qmail</filename>,
             <filename role="package">mail/zmailer</filename>, being some of the most popular
             choices.</para>
 
           <para>Diversity is nice, and the fact that you have many
             different mail-servers to chose from is considered a
             good thing; therefore try to avoid
             asking questions like <quote>Is Sendmail better than
             Qmail?</quote> in the mailing lists.  If you do feel like
             asking, first check the mailing list archives.  The
             advantages and disadvantages of each and every one of the
             available MTA's have already been discussed a few
             times.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="forgot-root-pw">
           <para>I have forgotten the root password!  What do I do?</para>
         </question><answer>
 
           <para>Do not Panic!  Simply restart the system, type
             <userinput>boot -s</userinput> at the Boot: prompt (just
             <userinput>-s</userinput> for FreeBSD releases before 3.2) to
             enter Single User mode. At the question about the shell to use,
             hit ENTER. You will be dropped to a &prompt.root; prompt. Enter
             <command>mount -u /</command> to remount your root filesystem
             read/write, then run <command>mount -a</command> to remount all
             the filesystems. Run <command>passwd root</command> to change
             the root password then run &man.exit.1; to continue
             booting.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="CAD-reboot">
           <para>How do I keep Control-Alt-Delete from rebooting the
             system?</para>
         </question>
 
         <answer>
 
           <para>If you are using syscons (the default console driver)
             in FreeBSD 2.2.7-RELEASE or later,
             build and install a new kernel with the line</para>
 
           <programlisting>options SC_DISABLE_REBOOT</programlisting>
 
           <para>in the configuration file. If you use the PCVT console
             driver in FreeBSD 2.2.5-RELEASE or later, use the following
             kernel configuration line instead:</para>
 
           <programlisting>options PCVT_CTRL_ALT_DEL</programlisting>
 
           <para>For older versions of FreeBSD, edit the keymap you are
             using for the console and replace the <literal>boot</literal>
             keywords with <literal>nop</literal>. The default keymap is
             <filename>/usr/share/syscons/keymaps/us.iso.kbd</filename>. You
             may have to instruct <filename>/etc/rc.conf</filename> to load
             this keymap explicitly for the change to take effect. Of course
             if you are using an alternate keymap for your country, you
             should edit that one instead.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="dos-to-unix-txt">
           <para>How do I reformat DOS text files to Unix ones?</para>
         </question>
 
         <answer>
 
           <para>Simply use this perl command:</para>
 
           <screen>&prompt.user; <userinput>perl -i.bak -npe 's/\r\n/\n/g' file ...</userinput></screen>
 
           <para>file is the file(s) to process.  The modification is done
             in-place, with the original file stored with a .bak
             extension.</para>
 
           <para>Alternatively you can use the
             &man.tr.1;
             command:</para>
 
           <screen>&prompt.user; <userinput>tr -d '\r' &lt; <replaceable>dos-text-file</replaceable> &gt; <replaceable>unix-file</replaceable></userinput></screen>
 
           <para><replaceable>dos-text-file</replaceable> is the file
             containing DOS text while <replaceable>unix-file</replaceable>
             will contain the converted output.  This can be quite a bit
             faster than using perl.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="kill-by-name">
           <para>How do I kill processes by name?</para>
         </question><answer>
 
           <para>Use &man.killall.1;.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="root-acl">
           <para>Why is su bugging me about not being in
             <username>root</username>'s ACL?</para>
         </question>
 
         <answer>
 
           <para>The error comes from the Kerberos distributed
             authentication system.  The problem is not fatal but annoying.
             You can either run su with the -K option, or uninstall
             Kerberos as described in the next question.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="uninstall-kerberos">
           <para>How do I uninstall Kerberos?</para>
         </question>
 
         <answer>
 
           <para>To remove Kerberos from the system, reinstall the bin
             distribution for the release you are running.  If you have
             the CDROM, you can mount the cd (we will assume on /cdrom)
             and run</para>
 
           <screen>&prompt.root; <userinput>cd /cdrom/bin</userinput>
 &prompt.root; <userinput>./install.sh</userinput></screen>
 
           <para>Alternately, you can remove all "MAKE_KERBEROS"
             options from <filename>/etc/make.conf</filename> and rebuild
             world.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="add-pty">
           <para>How do I add pseudoterminals to the system?</para>
         </question>
 
         <answer>
 
           <para>If you have lots of telnet, ssh, X, or screen users,
             you will probably run out of pseudoterminals.  Here is how to
             add more:</para>
 
             <procedure>
               <step>
                 <para>Build and install a new kernel with the line</para>
 
                 <programlisting>pseudo-device pty 256</programlisting>
 
                 <para>in the configuration file.</para>
               </step>
 
               <step>
                 <para>Run the commands</para>
 
                 <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV pty{1,2,3,4,5,6,7}</userinput></screen>
 
                 <para>to make 256 device nodes for the new terminals.</para>
 
               </step>
 
               <step>
                 <para>Edit <filename>/etc/ttys</filename> and add lines
                 for each of the 256 terminals. They should match the form
                 of the existing entries, i.e. they look like</para>
 
                 <programlisting>ttyqc none network</programlisting>
 
                 <para>The order of the letter designations is
                   <literal>tty[pqrsPQRS][0-9a-v]</literal>, using a
                   regular expression.  </para>
               </step>
 
               <step>
                 <para>Reboot the system with the new kernel and you are
                   ready to go.</para>
               </step>
             </procedure>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="create-snd0">
           <para>Why can I not create the snd0 device?</para>
         </question>
 
         <answer>
           <para>There is no <devicename>snd</devicename> device.  The name
             is used as a shorthand for the various devices that make up the
             FreeBSD sound driver, such as <devicename>mixer</devicename>,
             <devicename>sequencer</devicename>, and
             <devicename>dsp</devicename>.</para>
 
           <para>To create these devices you should</para>
 
           <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="reread-rc">
           <para>How do I re-read <filename>/etc/rc.conf</filename> and re-start <filename>/etc/rc</filename> without
             a reboot?</para>
         </question>
 
         <answer>
 
           <para>Go into single user mode and then back to multi user
             mode.</para>
 
           <para>On the console do:</para>
 
           <screen>&prompt.root; <userinput>shutdown now</userinput>
 (Note: without -r or -h)
 
 &prompt.root; <userinput>return</userinput>
 &prompt.root; <userinput>exit</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="sandbox">
           <para>What is a sandbox?</para>
         </question><answer>
 
           <para><quote>Sandbox</quote> is a security term.  It can mean
             two things:</para>
 
             <itemizedlist>
               <listitem>
 
                 <para>A process which is placed inside a set of virtual
                   walls that are designed to prevent someone who breaks
                   into the process from being able to break into the wider
                   system.</para>
 
                 <para>The process is said to be able to
                   <quote>play</quote> inside the walls.  That is,
                   nothing the process does in regards to executing code is
                   supposed to be able to breech the walls so you do not
                   have to do a detailed audit of its code to be able to
                   say certain things about its security.</para>
 
                 <para>The walls might be a userid, for example.  This is
                   the definition used in the security and named man
                   pages.</para>
 
                 <para>Take the <literal>ntalk</literal> service, for
                   example (see /etc/inetd.conf). This service used to run
                   as userid root. Now it runs as userid tty. The tty user
                   is a sandbox designed to make it more difficult for
                   someone who has successfully hacked into the system via
                   ntalk from being able to hack beyond that user id.</para>
               </listitem>
 
               <listitem>
 
                 <para>A process which is placed inside a simulation of the
                   machine. This is more hard-core. Basically it means that
                   someone who is able to break into the process may believe
                   that he can break into the wider machine but is, in fact,
                   only breaking into a simulation of that machine and not
                   modifying any real data.</para>
 
                 <para>The most common way to accomplish this is to build a
                   simulated environment in a subdirectory and then run the
                   processes in that directory chroot'd (i.e.
                   <filename>/</filename> for that process is this
                   directory, not the real <filename>/</filename> of the
                   system).</para>
 
                 <para>Another common use is to mount an underlying
                   filesystem read-only and then create a filesystem layer
                   on top of it that gives a process a seemingly writeable
                   view into that filesystem. The process may believe it is
                   able to write to those files, but only the process sees
                   the effects - other processes in the system do not,
                   necessarily.</para>
 
                 <para>An attempt is made to make this sort of sandbox so
                   transparent that the user (or hacker) does not realize
                   that he is sitting in it.</para>
               </listitem>
             </itemizedlist>
 
           <para>Unix implements two core sandboxes.  One is at the
             process level, and one is at the userid level.</para>
 
           <para>Every Unix process is completely firewalled off from every
             other Unix process.  One process cannot modify the address
             space of another.  This is unlike Windows where a process
             can easily overwrite the address space of any other, leading
             to a crash.</para>
 
           <para>A Unix process is owned by a particular userid.  If the
             userid is not the <username>root</username> user, it serves to firewall the process
             off from processes owned by other users.  The userid is also
             used to firewall off on-disk data.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="securelevel">
           <para>What is securelevel?</para>
         </question>
 
         <answer>
           <para>The securelevel is a security mechanism implemented in the
             kernel.  Basically, when the securelevel is positive, the
             kernel restricts certain tasks; not even the superuser (i.e.,
             <username>root</username>) is allowed to do them.  At the time
             of this writing, the securelevel mechanism is capable of, among
             other things, limiting the ability to,</para>
 
           <itemizedlist>
             <listitem>
               <para>unset certain file flags, such as
                 <literal>schg</literal> (the system immutable flag),</para>
             </listitem>
 
             <listitem>
               <para>write to kernel memory via
                 <devicename>/dev/mem</devicename> and
                 <devicename>/dev/kmem</devicename>,</para>
             </listitem>
 
             <listitem>
               <para>load kernel modules, and</para>
             </listitem>
 
             <listitem>
               <para>alter &man.ipfirewall.4; rules.</para>
             </listitem>
           </itemizedlist>
 
           <para>To check the status of the securelevel on a running system,
             simply execute the following command:</para>
 
           <screen>&prompt.root; <userinput>sysctl kern.securelevel</userinput></screen>
 
           <para>The output will contain the name of the &man.sysctl.8;
             variable (in this case, <varname>kern.securelevel</varname>)
             and a number.  The latter is the current value of the
             securelevel.  If it is positive (i.e., greater than 0), at
             least some of the securelevel's protections are enabled.</para>
 
           <para>You cannot lower the securelevel of a running system; being
             able to do that would defeat its purpose.  If you need to do a
             task that requires that the securelevel be non-positive (e.g.,
             an <maketarget>installworld</maketarget> or changing the date),
             you will have to change the securelevel setting in
             <filename>/etc/rc.conf</filename> (you want to look for the
             <varname>kern_securelevel</varname> and
             <varname>kern_securelevel_enable</varname> variables) and
             reboot.</para>
 
           <para>For more information on securelevel and the specific things
             all the levels do, please consult the &man.init.8; manual
             page.</para>
 
             <warning>
               <para>Securelevel is not a silver bullet; it has many known
                 deficiencies.  More often than not, it provides a false
                 sense of security.</para>
 
               <para>One of its biggest problems is that in order for it to
                 be at all effective, all files used in the boot process up
                 until the securelevel is set must be protected.  If an
                 attacker can get the system to execute their code prior to
                 the securelevel being set (which happens quite late in the
                 boot process since some things the system must do at
                 start-up cannot be done at an elevated securelevel), its
                 protections are invalidated.  While this task of protecting
                 all files used in the boot process is not technically
                 impossible, if it is achieved, system maintenance will
                 become a nightmare since one would have to take the system
                 down, at least to single-user mode, to modify a
                 configuration file.</para>
 
               <para>This point and others are often discussed on the
                 mailing lists, particularly freebsd-security.  Please search
                 the archives <ulink
                 url="../../../../search/index.html">here</ulink> for an
                 extensive discussion.  Some people are hopeful that
                 securelevel will soon go away in favor of a more
                 fine-grained mechanism, but things are still hazy in this
                 respect.</para>
 
               <para>Consider yourself warned.</para>
             </warning>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="release-candidate">
           <para>I tried to update my system to the latest -STABLE, but
             got -RC or -BETA!  What is going on?</para>
         </question>
 
         <answer>
           <para>Short answer: it is just a name.  RC stands for
             <quote>Release Candidate</quote>.  It signifies that a
             release is imminent.  In FreeBSD, -BETA is typically synonymous
             with the code freeze before a release.</para>
 
           <para>Long answer: FreeBSD derives its releases from one of
             two places.  Major, dot-zero, releases, such as
             3.0-RELEASE and 4.0-RELEASE, are branched from the head of
             the development stream, commonly referred to as <link
             linkend="current">-CURRENT</link>.  Minor releases, such
             as 3.1-RELEASE or 4.2-RELEASE, have been snapshots of the active
             <link linkend="stable">-STABLE</link> branch.  Starting with
 	    4.3-RELEASE, each release also now has its own branch which can be
 	    tracked by people requiring an extremely conservative rate
 	    of development (typically only security advisories).</para>
 
           <para>When a release is about to be made, the branch from
             which it will be derived from has to undergo a certain
             process.  Part of this process is a code freeze.  When a
             code freeze is initiated, the name of the branch is
             changed to reflect that it is about to become a release.
             For example, if the branch used to be called 4.0-STABLE,
             its name will be changed to 4.1-BETA to signify the code
             freeze and signify that extra pre-release testing should
             be happening.  Bug fixes can still be committed to be part
             of the release.  When the source code is in shape for the
             release the name will be changed to 4.1-RC to signify that a
             release is about to be made from it.  Once in the RC stage,
             only the most critical bugs found can be fixed.
             Once the release, 4.1-RELEASE in this example, has been made,
             the branch will be renamed to 4.1-STABLE.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="kernel-chflag-failure">
           <para>I tried to install a new kernel, and the chflags failed.
                 How do I get around this?</para>
         </question>
 
         <answer>
           <para>Short answer: You are probably at security level
             greater than 0.  Reboot directly to single user mode to
             install the kernel.</para>
 
           <para>Long answer: FreeBSD disallows changing system flags
             at security levels greater than 0.  You can check your
             security level with the command:</para>
 
           <screen>&prompt.root; <userinput>sysctl kern.securelevel</userinput></screen>
 
            <para>You cannot lower the security level; you have to boot to
              single mode to install the kernel, or change the security
              level in <filename>/etc/rc.conf</filename> then reboot. See
              the &man.init.8; man page for details on securelevel, and see
              <filename>/etc/defaults/rc.conf</filename> and the
              &man.rc.conf.5; man page for more information on
              rc.conf.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="kernel-securelevel-time">
           <para>I cannot change the time on my system by more than one second!
                 How do I get around this?</para>
         </question>
 
         <answer>
           <para>Short answer: You are probably at security level
             greater than 1.  Reboot directly to single user mode to
             change the date.</para>
 
           <para>Long answer: FreeBSD disallows changing the time by
               more that one second at security levels greater than 1.  You
               can check your security level with the command:</para>
 
           <screen>&prompt.root; <userinput>sysctl kern.securelevel</userinput></screen>
 
            <para>You cannot lower the security level; you have to boot
              to single mode to change the date, or change the security
              level in <filename>/etc/rc.conf</filename> then reboot. See
              the &man.init.8; man page for details on securelevel, and
              see <filename>/etc/defaults/rc.conf</filename> and the
              &man.rc.conf.5; man page for more information on rc.conf.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="statd-mem-leak">
           <para>Why is <command>rpc.statd</command> using 256 megabytes of
             memory?</para>
         </question>
 
         <answer>
           <para>No, there is no memory leak, and it is not using 256 Mbytes
             of memory.  It simply likes to (i.e., always does) map an
             obscene amount of memory into its address space for convenience.
             There is nothing terribly wrong with this from a technical
             standpoint; it just throws off things like &man.top.1; and
             &man.ps.1;.</para>
 
           <para>&man.rpc.statd.8; maps its status file (resident on
             <filename>/var</filename>) into its address space; to save
             worrying about remapping it later when it needs to grow, it maps
             it with a generous size.  This is very evident from the source
             code, where one can see that the length argument to &man.mmap.2;
             is <literal>0x10000000</literal>, or one sixteenth of the
             address space on an IA32, or exactly 256MB.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="unsetting-schg">
           <para>Why can I not unset the <literal>schg</literal> file
             flag?</para>
         </question>
 
         <answer>
           <para>You are running at an elevated (i.e., greater than 0)
             securelevel.  Lower the securelevel and try again.  For more
             information, see <link linkend="securelevel">the FAQ entry on
             securelevel</link> and the &man.init.8; manual page.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ssh-shosts">
 	  <para>Why does SSH authentication through
 	    <filename>.shosts</filename> not work by default in recent
 	    versions of FreeBSD?</para>
 	</question>
 
 	<answer>
 	  <para>The reason why <filename>.shosts</filename>
 	    authentication does not work by default in more recent
 	    versions of FreeBSD is because &man.ssh.1; 
 	    is not installed suid root by default.  To
 	    <quote>fix</quote> this, you can do one of the
 	    following:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>As a permanent fix, set
 		<makevar>ENABLE_SUID_SSH</makevar> to <literal>true</literal>
 		in <filename>/etc/make.conf</filename> and rebuild ssh
 		(or run <command>make world</command>).</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>As a temporary fix, change the mode on
 		<filename>/usr/bin/ssh</filename> to <literal>4555</literal>
 		by running <command>chmod 4755 /usr/bin/ssh</command> as
 		<username>root</username>.  Then add
 		<makevar>ENABLE_SUID_SSH= true</makevar> to
 		<filename>/etc/make.conf</filename> so the change takes
 		effect the next time <command>make world</command> is
 		run.</para>
 	    </listitem>
 	  </itemizedlist>
 	</answer>
       </qandaentry>
 
       <qandaentry>
         <question id="vnlru">
           <para>What is <literal>vnlru</literal>?</para>
         </question>
 
         <answer>
           <para><literal>vnlru</literal> flushes and frees vnodes when
             the system hits the <varname>kern.maxvnodes</varname>
             limit.  This kernel thread sits mostly idle, and only
             activates if you have a huge amount of RAM and are
             accessing tens of thousands of tiny files.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="x">
     <title>The X Window System and Virtual Consoles</title>
 
     <qandaset>
       <qandaentry>
         <question id="running-X">
           <para>I want to run X, how do I go about it?</para>
         </question>
 
         <answer>
 
           <para>The easiest way is to simply specify that you want to
             run X during the installation process.</para>
 
           <para>Then read and follow the documentation on the
             <command>xf86config</command> tool, which assists you in configuring
             XFree86 for your particular graphics card/mouse/etc.</para>
 
           <para>You may also wish to investigate the Xaccel server.
             See the section on <link linkend="xig">Xi Graphics</link> or
             <link linkend="metrox">Metro Link</link> for more details.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="running-X-securelevels">
           <para>I <emphasis>tried</emphasis> to run X, but I get an
             <errorname>KDENABIO failed (Operation not permitted)</errorname>
             error when I type <command>startx</command>. What do I do
             now?</para>
         </question>
 
         <answer>
           <para>Your system is running at a raised securelevel, is not
             it?  It is, indeed, impossible to start X at a raised
             securelevel.  To see why, look at the &man.init.8; man
             page.</para>
 
           <para>So the question is what else you should do instead,
             and you basically have two choices: set your securelevel
             back down to zero (usually from <filename>/etc/rc.conf</filename>),
             or run &man.xdm.1; at boot time (before the securelevel is
             raised).</para>
 
           <para>See <xref linkend="xdm-boot"> for more information about
             running &man.xdm.1; at boot time.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="x-and-moused">
           <para>Why does my mouse not work with X?</para>
         </question>
 
         <answer>
           <para>If you are using syscons (the default console driver),
             you can configure FreeBSD to support a mouse pointer on each
             virtual screen. In order to avoid conflicting with X, syscons
             supports a virtual device called
             <devicename>/dev/sysmouse</devicename>. All mouse events received
             from the real mouse device are written to the sysmouse device
             via moused. If you wish to use your mouse on one or more
             virtual consoles, <emphasis>and</emphasis> use X, see
             <xref linkend="moused" remap="another section"> and set up
             moused.</para>
 
           <para>Then edit <filename>/etc/XF86Config</filename> and make
             sure you have the following lines.</para>
 
           <programlisting>Section         Pointer
 Protocol        "SysMouse"
 Device          "/dev/sysmouse"
 .....</programlisting>
 
           <para>The above example is for XFree86 3.3.2 or later.  For
             earlier versions, the <emphasis>Protocol</emphasis> should be
             <emphasis>MouseSystems</emphasis>.</para>
 
           <para>Some people prefer to use <devicename>/dev/mouse</devicename>
             under X.  To make this work, <devicename>/dev/mouse</devicename>
             should be linked to
             <devicename>/dev/sysmouse</devicename> (see &man.sysmouse.4;):</para>
 
           <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>rm -f mouse</userinput>
 &prompt.root; <userinput>ln -s sysmouse mouse</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="x-and-wheel">
           <para>My mouse has a fancy wheel.  Can I use it in X?</para>
         </question>
 
         <answer>
           <para>Yes.  But you need to customize X client programs. See <ulink
             URL="http://www.inria.fr/koala/colas/mouse-wheel-scroll/">
             Colas Nahaboo's web page
             (http://www.inria.fr/koala/colas/mouse-wheel-scroll/)
             </ulink>.</para>
 
           <para>If you want to use the <application>imwheel</application>
             program, just follow these simple steps.</para>
 
           <orderedlist>
             <listitem>
               <para>Translate the Wheel Events</para>
 
               <para>The <application>imwheel</application> program
                 works by translating mouse button 4 and mouse button 5
                 events into key events.  Thus, you have to get the
                 mouse driver to translate mouse wheel events to button
                 4 and 5 events.  There are two ways of doing this, the
                 first way is to have &man.moused.8; do the
                 translation.  The second way is for the X server
                 itself to do the event translation.</para>
 
               <orderedlist>
                 <listitem>
                   <para>Using &man.moused.8; to Translate Wheel
                     Events</para>
 
                   <para>To have &man.moused.8; perform the event
                     translations, simply add <option>-z 4</option> to
                     the command line used to start &man.moused.8;.
                     For example, if you normally start &man.moused.8;
                     via <command>moused -p /dev/psm0</command> you
                     would start it by entering <command>moused -p
                     /dev/psm0 -z 4</command> instead.  If you start
                     &man.moused.8; automatically during bootup via
                     <filename>/etc/rc.conf</filename>, you can simply
                     add <option>-z 4</option> to the
                     <varname>moused_flags</varname> variable in
                     <filename>/etc/rc.conf</filename>.</para>
 
                   <para>You now need to tell X that you have a 5
                     button mouse.  To do this, simply add the line
                     <literal>Buttons 5</literal> to the
                     <quote>Pointer</quote> section of
                     <filename>/etc/XF86Config</filename>.  For
                     example, you might have the following
                     <quote>Pointer</quote> section in
                     <filename>/etc/XF86Config</filename>.</para>
 
                   <example>
                     <title><quote>Pointer</quote> Section for Wheeled
                       Mouse in XFree86 3.3.x series XF86Config with moused
                       Translation</title>
 
                     <programlisting>Section "Pointer"
    Protocol        "SysMouse"
    Device          "/dev/sysmouse"
    Buttons         5
 EndSection</programlisting>
                   </example>
 
                   <example>
                     <title><quote>InputDevice</quote> Section for Wheeled
                       Mouse in XFree86 4.x series XF86Config with X Server
                       Translation</title>
 
                     <programlisting>Section "InputDevice"
    Identifier      "Mouse1"
    Driver          "mouse"
    Option          "Protocol" "auto"
    Option          "Device" "/dev/sysmouse"
    Option          "Buttons" "5"
 EndSection</programlisting>
                   </example>
 
                   <example>
                     <title><quote>.emacs</quote> example for naive
                       page scrolling with Wheeled Mouse</title>
                     <programlisting>;; wheel mouse
 (global-set-key [mouse-4] 'scroll-down)
 (global-set-key [mouse-5] 'scroll-up)</programlisting>
                   </example>
 
                 </listitem>
 
                 <listitem>
                   <para>Using Your X Server to Translate the Wheel
                     Events</para>
 
                   <para>If you are not running &man.moused.8;, or if
                     you do not want &man.moused.8; to translate your
                     wheel events, you can have the X server do the
                     event translation instead.  This requires a couple
                     of modifications to your
                     <filename>/etc/XF86Config</filename> file.  First,
                     you need to choose the proper protocol for your
                     mouse.  Most wheeled mice use the
                     <quote>IntelliMouse</quote> protocol.  However,
                     XFree86 does support other protocols, such as
                     <quote>MouseManPlusPS/2</quote> for the Logitech
                     MouseMan+ mice.  Once you have chosen the protocol
                     you will use, you need to add a
                     <varname>Protocol</varname> line to the
                     <quote>Pointer</quote> section.</para>
 
                   <para>Secondly, you need to tell the X server to
                     remap wheel scroll events to mouse buttons 4 and
                     5.  This is done with the
                     <varname>ZAxisMapping</varname> option.</para>
 
                   <para>For example, if you are not using
                       &man.moused.8;, and you have an IntelliMouse
                       attached to the PS/2 mouse port you would use
                       the following in
                       <filename>/etc/XF86Config</filename>.</para>
 
                   <example>
                     <title><quote>Pointer</quote> Section for Wheeled
                       Mouse in <filename>XF86Config</filename> with X
                       Server Translation</title>
 
                     <programlisting>Section "Pointer"
    Protocol        "IntelliMouse"
    Device          "/dev/psm0"
    ZAxisMapping    4 5
 EndSection</programlisting>
                   </example>
 
                   <example>
                     <title><quote>InputDevice</quote> Section for Wheeled
                       Mouse in XFree86 4.x series XF86Config with X Server
                       Translation</title>
 
                     <programlisting>Section "InputDevice"
    Identifier      "Mouse1"
    Driver          "mouse"
    Option          "Protocol" "auto"
    Option          "Device" "/dev/psm0"
    Option          "ZAxisMapping" "4 5"
 EndSection</programlisting>
                   </example>
 
                   <example>
                     <title><quote>.emacs</quote> example for naive
                       page scrolling with Wheeled Mouse</title>
                     <programlisting>;; wheel mouse
 (global-set-key [mouse-4] 'scroll-down)
 (global-set-key [mouse-5] 'scroll-up)</programlisting>
                   </example>
 
                 </listitem>
               </orderedlist>
             </listitem>
 
             <listitem>
               <para>Install <application>imwheel</application></para>
 
               <para>Next, install <application>imwheel</application>
                 from the Ports collection.  It can be found in the
                 <filename>x11</filename> category.  This program will
                 map the wheel events from your mouse into keyboard
                 events.  For example, it might send <keycap>Page
                 Up</keycap> to a program when you scroll the wheel
                 forwards.  <application>Imwheel</application> uses a
                 configuration file to map the wheel events to
                 key presses so that it can send different keys to
                 different applications.  The default
                 <application>imwheel</application> configuration file
                 is installed in
                 <filename>/usr/X11R6/etc/imwheelrc</filename>.  You
                 can copy it to <filename>~/.imwheelrc</filename> and
                 then edit it if you wish to customize
                 <application>imwheel</application>'s configuration.
                 The format of the configuration file is documented in
                 &man.imwheel.1;.</para>
             </listitem>
 
             <listitem>
               <para>Configure <application>Emacs</application> to Work
                 with <application>Imwheel</application>
                 (<emphasis>optional</emphasis>)</para>
 
               <para>If you use <application>emacs</application> or
                 <application>Xemacs</application>, then you need to
                 add a small section to your
                 <filename>~/.emacs</filename> file.  For
                 <application>emacs</application>, add the
                 following:</para>
 
               <example>
                 <title><application>Emacs</application> Configuration
                   for <application>Imwheel</application></title>
 
                 <programlisting>;;; For imwheel
 (setq imwheel-scroll-interval 3)
 (defun imwheel-scroll-down-some-lines ()
   (interactive)
   (scroll-down imwheel-scroll-interval))
 (defun imwheel-scroll-up-some-lines ()
   (interactive)
   (scroll-up imwheel-scroll-interval))
 (global-set-key [?\M-\C-\)] 'imwheel-scroll-up-some-lines)
 (global-set-key [?\M-\C-\(] 'imwheel-scroll-down-some-lines)
 ;;; end imwheel section</programlisting>
               </example>
 
               <para>For <application>Xemacs</application>, add the
                 following to your <filename>~/.emacs</filename> file
                 instead:</para>
 
               <example>
                 <title><application>Xemacs</application> Configuration
                   for <application>Imwheel</application></title>
 
                 <programlisting>;;; For imwheel
 (setq imwheel-scroll-interval 3)
 (defun imwheel-scroll-down-some-lines ()
   (interactive)
   (scroll-down imwheel-scroll-interval))
 (defun imwheel-scroll-up-some-lines ()
   (interactive)
   (scroll-up imwheel-scroll-interval))
 (define-key global-map [(control meta \))] 'imwheel-scroll-up-some-lines)
 (define-key global-map [(control meta \()] 'imwheel-scroll-down-some-lines)
 ;;; end imwheel section</programlisting>
               </example>
             </listitem>
 
             <listitem>
               <para>Run <application>Imwheel</application></para>
 
               <para>You can just type <command>imwheel</command>
                 in an xterm to start it up once it is installed.  It
                 will background itself and take effect immediately.
                 If you want to always use
                 <application>imwheel</application>, simply add it to
                 your <filename>.xinitrc</filename> or
                 <filename>.xsession</filename> file.  You can safely
                 ignore any warnings <application>imwheel</application>
                 displays about PID files.  Those warnings only apply
                 to the Linux version of
                 <application>imwheel</application>.</para>
             </listitem>
           </orderedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="window-menu-weird">
           <para>Why do X Window menus and dialog boxes not work right?</para>
         </question>
 
         <answer>
           <para>Try turning off the Num Lock key.</para>
 
           <para>If your Num Lock key is on by default at boot-time, you
             may add the following line in the <literal>Keyboard</literal>
             section of the <filename>XF86Config</filename> file.</para>
 
           <programlisting># Let the server do the NumLock processing.  This should only be
 # required when using pre-R6 clients
     ServerNumLock</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="virtual-console">
           <para>What is a virtual console and how do I make more?</para>
         </question>
 
         <answer>
           <para>Virtual consoles, put simply, enable you to have several
             simultaneous sessions on the same machine without doing anything
             complicated like setting up a network or running X.</para>
 
           <para>When the system starts, it will display a login prompt on
             the monitor after displaying all the boot messages. You can
             then type in your login name and password and start working (or
             playing!) on the first virtual console.</para>
 
           <para>At some point, you will probably wish to start another
             session, perhaps to look at documentation for a program
             you are running or to read your mail while waiting for an
             FTP transfer to finish. Just do Alt-F2 (hold down the Alt
             key and press the F2 key), and you will find a login prompt
             waiting for you on the second <quote>virtual console</quote>!
             When you want to go back to the original session, do
             Alt-F1.</para>
 
           <para>The default FreeBSD installation has three virtual consoles
             enabled (8 starting with 3.3-RELEASE), and Alt-F1, Alt-F2, and
             Alt-F3 will switch between these virtual consoles.</para>
 
           <para>To enable more of them, edit
             <filename>/etc/ttys</filename> (see &man.ttys.5;)
             and add entries for <devicename>ttyv4</devicename>
             to <devicename>ttyvc</devicename> after the comment on
             <quote>Virtual terminals</quote>:</para>
 
           <programlisting># Edit the existing entry for ttyv3 in /etc/ttys and change
 # "off" to "on".
 ttyv3   "/usr/libexec/getty Pc"         cons25  on secure
 ttyv4   "/usr/libexec/getty Pc"         cons25  on secure
 ttyv5   "/usr/libexec/getty Pc"         cons25  on secure
 ttyv6   "/usr/libexec/getty Pc"         cons25  on secure
 ttyv7   "/usr/libexec/getty Pc"         cons25  on secure
 ttyv8   "/usr/libexec/getty Pc"         cons25  on secure
 ttyv9   "/usr/libexec/getty Pc"         cons25  on secure
 ttyva   "/usr/libexec/getty Pc"         cons25  on secure
 ttyvb   "/usr/libexec/getty Pc"         cons25  on secure</programlisting>
 
           <para>Use as many or as few as you want.  The more virtual
             terminals you have, the more resources that are used; this
             can be important if you have 8MB RAM or less.  You may also
             want to change the <literal>secure</literal>
             to <literal>insecure</literal>.</para>
 
             <important>
               <para>If you want to run an X server you
                 <emphasis>must</emphasis> leave at least one virtual
                 terminal unused (or turned off) for it to use. That is to
                 say that if you want to have a login prompt pop up for all
                 twelve of your Alt-function keys, you are out of luck - you
                 can only do this for eleven of them if you also want to run
                 an X server on the same machine.</para>
             </important>
 
           <para>The easiest way to disable a console is by turning it off.
             For example, if you had the full 12 terminal allocation
             mentioned above and you wanted to run X, you would change
             settings for virtual terminal 12 from:</para>
 
           <programlisting>ttyvb   "/usr/libexec/getty Pc"         cons25  on  secure</programlisting>
 
           <para>to:</para>
 
           <programlisting>ttyvb   "/usr/libexec/getty Pc"         cons25  off secure</programlisting>
 
           <para>If your keyboard has only ten function keys, you would
             end up with:</para>
 
 <programlisting>ttyv9   "/usr/libexec/getty Pc"         cons25  off secure
 ttyva   "/usr/libexec/getty Pc"         cons25  off secure
 ttyvb   "/usr/libexec/getty Pc"         cons25  off secure</programlisting>
 
           <para>(You could also just delete these lines.)</para>
 
           <para>Once you have edited
             <filename>/etc/ttys</filename>, the next step is to make sure that you
             have enough virtual terminal devices.  The easiest way to do
             this is:</para>
 
           <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV vty12</userinput></screen>
 
           <para>Next, the easiest (and cleanest) way to activate the
             virtual consoles is to reboot.  However, if you really do not
             want to reboot, you can just shut down the X Window system
             and execute (as <username>root</username>):</para>
 
           <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>
 
           <para>It is imperative that you completely shut down X Window if
             it is running, before running this command.  If you do not,
             your system will probably appear to hang/lock up after
             executing the kill command.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="vty-from-x">
           <para>How do I access the virtual consoles from X?</para>
         </question>
 
         <answer>
           <para>Use <keycombo action="simul">
               <keycap>Ctrl</keycap>
               <keycap>Alt</keycap>
               <keycap>F<replaceable>n</replaceable></keycap>
             </keycombo> to switch back to a virtual console.
             <keycombo action="simul">
               <keycap>Ctrl</keycap>
               <keycap>Alt</keycap>
               <keycap>F1</keycap>
             </keycombo> would return you to the first virtual console.</para>
 
           <para>Once you are back to a text console, you can then use
             <keycombo action="simul">
               <keycap>Alt</keycap>
               <keycap>F<replaceable>n</replaceable></keycap>
             </keycombo> as normal to move between them.</para>
 
           <para>To return to the X session, you must switch to the virtual
             console running X.  If you invoked X from the command line, (e.g.,
             using <command>startx</command>) then the X session will attach to
             the next unused virtual console, not the text console from which
             it was invoked.  If you have eight active virtual terminals then X
             will be running on the ninth, and you would use
             <keycombo action="simul">
               <keycap>Alt</keycap>
               <keycap>F9</keycap>
             </keycombo> to return.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="xdm-boot">
           <para>How do I start XDM on boot?</para>
         </question><answer>
 
           <para>There are two schools of thought on how to start <ulink
             URL="http://www.FreeBSD.org/cgi/man.cgi?manpath=xfree86&amp;query=xdm">
             xdm</ulink>. One school starts xdm from
             <filename>/etc/ttys</filename> (see &man.ttys.5;)
             using the supplied example, while the other simply runs xdm
             from
             <filename>rc.local</filename> (see &man.rc.8;)
             or from a <filename>X.sh</filename> script in
             <filename>/usr/local/etc/rc.d</filename>. Both are equally
             valid, and one may work in situations where the other does not.
             In both cases the result is the same: X will pop up a graphical
             login: prompt.</para>
 
           <para>The ttys method has the advantage of documenting which
             vty X will start on and passing the responsibility of
             restarting the X server on logout to init.  The rc.local
             method makes it easy to kill xdm if there is a problem
             starting the X server.</para>
 
           <para>If loaded from rc.local, <command>xdm</command> should
             be started without any arguments (i.e., as a daemon). xdm must
             start AFTER getty runs, or else getty and xdm will conflict,
             locking out the console. The best way around this is to have
             the script sleep 10 seconds or so then launch xdm.</para>
 
           <para>If you are to start <command>xdm</command> from
             <filename>/etc/ttys</filename>, there still is a chance of
             conflict between <command>xdm</command> and
             &man.getty.8;. One way to avoid this is to add the
             <literal>vt</literal> number in the
             <filename>/usr/X11R6/lib/X11/xdm/Xservers</filename>
             file.</para>
 
           <programlisting>:0 local /usr/X11R6/bin/X vt4</programlisting>
 
           <para>The above example will direct the X server to run in
             <devicename>/dev/ttyv3</devicename>. Note the number is offset by
             one. The X server counts the vty from one, whereas the FreeBSD
             kernel numbers the vty from zero.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="xconsole-failure">
           <para>Why do I get <errorname>Couldn't open console</errorname>
             when I run xconsole?</para>
         </question>
 
         <answer>
           <para>If you start <application>X</application>
             with
             <command>startx</command>, the permissions on
             <devicename>/dev/console</devicename> will
             <emphasis>not</emphasis> get changed, resulting in
             things like
             <command>xterm -C</command> and
             <command>xconsole</command> not working.</para>
 
           <para>This is because of the way console permissions are set
             by default. On a multi-user system, one does not necessarily
             want just any user to be able to write on the system console.
             For users who are logging directly onto a machine with a VTY,
             the &man.fbtab.5;
             file exists to solve such problems.</para>
 
           <para>In a nutshell, make sure an uncommented line of the
             form</para>
 
           <programlisting>/dev/ttyv0 0600 /dev/console</programlisting>
 
           <para>is in
             <filename>/etc/fbtab</filename> (see &man.fbtab.5;) and it will ensure that whomever logs in on
             <devicename>/dev/ttyv0</devicename> will own the console.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="xfree86-root">
           <para>Before, I was able to run XFree86 as a regular user.  Why does
             it now say that I must be <username>root</username>?</para>
         </question>
 
         <answer>
           <para>All X servers need to be run as <username>root</username> in order to get direct
             access to your video hardware.  Older versions of XFree86
             (&lt;= 3.3.6) installed all bundled servers to be automatically
             run as <username>root</username> (setuid to <username>root</username>).  This is obviously a security
             hazard because X servers are large, complicated programs.
             Newer versions of XFree86 do not install the servers setuid to
             <username>root</username> for just this reason.</para>
 
           <para>Obviously, running an X server as the root user is not
             acceptable, nor a good idea security-wise.  There are two ways
             to be able to use X as a regular user.  The first is to use
             <command>xdm</command> or another display manager
             (e.g., <command>kdm</command>); the second is to use the
             <command>Xwrapper</command>.</para>
 
           <para><command>xdm</command> is a daemon that handles graphical
             logins.  It is usually started at boot time, and is responsible
             for authenticating users and starting their sessions; it is
             essentially the graphical counterpart of
             &man.getty.8; and &man.login.1;.  For
             more information on <command>xdm</command> see
             <ulink url="http://www.xfree86.org/support.html">the XFree86
             documentation</ulink>, and the <link linkend="xdm-boot">the FAQ
             entry</link> on it.</para>
 
           <para><command>Xwrapper</command> is the X server wrapper; it is
             a small utility to enable one to manually run an X server while
             maintaining reasonable safety.  It performs some sanity checks
             on the command line arguments given, and if they pass, runs the
             appropriate X server.  If you do not want to run a display
             manger for whatever reason, this is for you.  If you have
             installed the complete ports collection, you can find the port in
             <filename>/usr/ports/x11/wrapper</filename>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ps2-x">
           <para>Why does my PS/2 mouse misbehave under X?</para>
         </question>
 
         <answer>
           <para>Your mouse and the mouse driver may have somewhat become
             out of synchronization.</para>
 
           <para>In versions 2.2.5 and earlier, switching away from X to a
             virtual terminal and getting back to X again may make them
             re-synchronized.  If the problem occurs often, you may add the
             following option in your kernel configuration file and
             recompile it.</para>
 
           <programlisting>options PSM_CHECKSYNC</programlisting>
 
           <para>See the section on <link linkend="make-kernel">building
             a kernel</link> if you have no experience with building
             kernels.</para>
 
           <para>With this option, there should be less chance of
             synchronization problem between the mouse and the driver.
             If, however, you still see the problem, click any mouse
             button while holding the mouse still to re-synchronize the
             mouse and the driver.</para>
 
           <para>Note that unfortunately this option may not work with all
             the systems and voids the <quote>tap</quote> feature of the
             ALPS GlidePoint device attached to the PS/2 mouse port.</para>
 
           <para>In versions 2.2.6 and later, synchronization check is done
             in a slightly better way and is standard in the PS/2 mouse
             driver. It should even work with GlidePoint. (As the check code
             has become a standard feature, PSM_CHECKSYNC option is not
             available in these versions.) However, in rare case the driver
             may erroneously report synchronization problem and you may see
             the kernel message:</para>
 
           <programlisting>psmintr: out of sync (xxxx != yyyy)</programlisting>
 
           <para>and find your mouse does not seem to work properly.</para>
 
           <para>If this happens, disable the synchronization check code
             by setting the driver flags for the PS/2 mouse driver to 0x100.
             Enter <emphasis>UserConfig</emphasis> by giving the
             <option>-c</option> option at the boot prompt:</para>
 
           <screen>boot: <userinput>-c</userinput></screen>
 
           <para>Then, in the <emphasis>UserConfig</emphasis> command
             line, type:</para>
 
           <screen>UserConfig&gt; <userinput>flags psm0 0x100</userinput>
 UserConfig&gt; <userinput>quit</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ps2-mousesystems">
           <para>Why does my PS/2 mouse from MouseSystems not
             work?</para>
         </question>
 
         <answer>
           <para>There have been some reports that certain model of PS/2
             mouse from MouseSystems works only if it is put into the
             <quote>high resolution</quote> mode.  Otherwise, the mouse
             cursor may jump to the upper-left corner of the screen every
             so often.</para>
 
           <para>Unfortunately there is no workaround for versions 2.0.X
             and 2.1.X. In versions 2.2 through 2.2.5, apply the following
             patch to <filename>/sys/i386/isa/psm.c</filename> and rebuild
             the kernel. See the section on <link
             linkend="make-kernel">building a kernel</link> if you have no
             experience with building kernels.</para>
 
           <programlisting>@@ -766,6 +766,8 @@
      if (verbose &gt;= 2)
          log(LOG_DEBUG, "psm%d: SET_DEFAULTS return code:%04x\n",
              unit, i);
 +    set_mouse_resolution(sc-&gt;kbdc, PSMD_RES_HIGH);
 +
  #if 0
      set_mouse_scaling(sc-&gt;kbdc);        /* 1:1 scaling */
      set_mouse_mode(sc-&gt;kbdc);                /* stream mode */</programlisting>
 
           <para>In versions 2.2.6 or later, specify the flags 0x04 to
             the PS/2 mouse driver to put the mouse into the high
             resolution mode.  Enter <emphasis>UserConfig</emphasis> by
             giving the <option>-c</option> option at the boot prompt:</para>
 
           <screen>boot: <userinput>-c</userinput></screen>
 
           <para>Then, in the <emphasis>UserConfig</emphasis> command line,
             type:</para>
 
           <screen>UserConfig&gt; <userinput>flags psm0 0x04</userinput>
 UserConfig&gt; <userinput>quit</userinput></screen>
 
           <para>See the previous section for another possible cause of mouse
             problems.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="imake-tmpl">
           <para>When building an X app, <command>imake</command> cannot
             find <filename>Imake.tmpl</filename>.  Where is it?</para>
         </question>
 
         <answer>
 
           <para><filename>Imake.tmpl</filename> is part of the Imake package, a standard X
             application building tool.  <filename>Imake.tmpl</filename>, as well as several
             header files that are required to build X apps, is contained
             in the X prog distribution. You can install this from sysinstall
             or manually from the X distribution files.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="xfree86-version">
           <para>An X app I am building depends on XFree86 3.3.x, but I 
           have XFree86 4.x installed. What should I do?</para>
         </question>
 
         <answer>
           <para>To tell the port build to link to the XFree86 4.x libraries,
 	  add the following to <filename>/etc/make.conf</filename>, (if you 
           do not have this file, create it):</para>
 
 	  <programlisting>XFREE86_VERSION=        4</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="mouse-button-reverse">
           <para>How do I reverse the mouse buttons?</para>
         </question>
 
         <answer>
           <para>Run the command
             <command>xmodmap -e "pointer = 3 2 1"</command> from your
             <filename>.xinitrc</filename> or <filename>.xsession</filename>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="install-splash">
           <para>How do I install a splash screen and where do I find
             them?</para>
         </question>
 
         <answer>
 
           <para>Just prior to the release of FreeBSD 3.1, a new feature
             was added to allow the display of <quote>splash</quote> screens
             during the boot messages. The splash screens currently must be
             a 256 color bitmap (<filename>*.BMP</filename>) or ZSoft PCX
             (<filename>*.PCX</filename>) file. In addition, they must have
             a resolution of 320x200 or less to work on standard VGA
             adapters. If you compile VESA support into your kernel, then
             you can use larger bitmaps up to 1024x768. Note that VESA
             support requires the <literal>VM86</literal> kernel option to
             be compiled into the kernel. The actual VESA support can either
             be compiled directly into the kernel with the
             <literal>VESA</literal> kernel config option or by loading the
             VESA kld module during bootup.</para>
 
           <para>To use a splash screen, you need to modify the startup
             files that control the boot process for FreeBSD. The files for
             this changed prior to the release of FreeBSD 3.2, so there are
             now two ways of loading a splash screen:</para>
 
             <itemizedlist>
               <listitem>
                 <para>FreeBSD 3.1</para>
 
                 <para>The first step is to find a bitmap version of your
                   splash screen. Release 3.1 only supports Windows bitmap
                   splash screens. Once you have found your splash screen of
                   choice copy it to <filename>/boot/splash.bmp</filename>.
                   Next, you need to have a
                   <filename>/boot/loader.rc</filename> file that contains
                   the following lines:</para>
 
                 <programlisting>load kernel
 load -t splash_image_data /boot/splash.bmp
 load splash_bmp
 autoboot</programlisting>
 
               </listitem>
 
               <listitem>
                 <para>FreeBSD 3.2+</para>
 
                 <para>In addition to adding support for PCX splash screens,
                   FreeBSD 3.2 includes a nicer way of configuring the boot
                   process. If you wish, you can use the method listed above
                   for FreeBSD 3.1. If you do and you want to use PCX,
                   replace <literal>splash_bmp</literal> with
                   <literal>splash_pcx</literal>. If, on the other hand, you
                   want to use the newer boot configuration, you need to
                   create a <filename>/boot/loader.rc</filename> file that
                   contains the following lines:</para>
 
                 <programlisting>include /boot/loader.4th
 start</programlisting>
 
                 <para>and a <filename>/boot/loader.conf</filename> that
                   contains the following:</para>
 
                 <programlisting>splash_bmp_load="YES"
 bitmap_load="YES"</programlisting>
 
                 <para>This assumes you are using
                   <filename>/boot/splash.bmp</filename> for your splash
                   screen.  If you would rather use a PCX file, copy it to
                   <filename>/boot/splash.pcx</filename>, create a
                   <filename>/boot/loader.rc</filename> as instructed
                   above, and create a
                   <filename>/boot/loader.conf</filename> that
                   contains:</para>
 
                 <programlisting>splash_pcx_load="YES"
 bitmap_load="YES"
 bitmap_name="/boot/splash.pcx"</programlisting>
 
               </listitem>
             </itemizedlist>
 
           <para>Now all you need is a splash screen.  For that you can
             surf on over to the gallery at <ulink
             URL="http://www.baldwin.cx/splash/">http://www.baldwin.cx/splash/</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="windows-keys">
           <para>Can I use the <trademark class="registered">Windows</trademark>
 	    keys on my keyboard in X?</para>
         </question>
 
         <answer>
           <para>Yes. All you need to do is use &man.xmodmap.1; to define
             what function you wish them to perform.</para>
 
           <para>Assuming all <quote><trademark class="registered">Windows</trademark></quote> keyboards are
             standard then the keycodes for the 3 keys are</para>
 
           <itemizedlist>
             <listitem>
               <para>115 - <trademark class="registered">Windows</trademark> key,
 		between the left-hand Ctrl and Alt keys</para>
             </listitem>
 
             <listitem>
               <para>116 - <trademark class="registered">Windows</trademark> key,
 		to the right of the Alt-Gr key</para>
             </listitem>
 
             <listitem>
               <para>117 - Menu key, to the left of the right-hand Ctrl key</para>
             </listitem>
           </itemizedlist>
 
           <para>To have the left <trademark class="registered">Windows</trademark>
 	    key print a comma, try this.</para>
 
           <screen>&prompt.root; <userinput>xmodmap -e "keycode 115 = comma"</userinput></screen>
 
           <para>You will probably have to re-start your window manager
             to see the result.</para>
 
           <para>To have the <trademark class="registered">Windows</trademark>
 	    key-mappings enabled automatically every time you start X either
 	    put the <command>xmodmap</command> commands in your
 	    <filename>~/.xinitrc</filename> file or, preferably, create a file
 	    <filename>~/.xmodmaprc</filename> and include the
 	    <command>xmodmap</command> options, one per line, then add the
 	    line</para>
 
           <programlisting>xmodmap $HOME/.xmodmaprc</programlisting>
 
           <para>to your <filename>~/.xinitrc</filename>.</para>
 
 	  <para>For example, you could map the 3 keys top be F13, F14, and
 	    F15, respectively.  This would make it easy to map them to
 	    useful functions within applications or your window
 	    manager, as demonstrated further down.</para>
 
           <para>To do this put the following in
             <filename>~/.xmodmaprc</filename>.</para>
 
           <programlisting>keycode 115 = F13
 keycode 116 = F14
 keycode 117 = F15</programlisting>
 
 	  <para>If you use <command>fvwm2</command>, for example, you
 	    could map the keys
             so that F13 iconifies (or de-iconifies) the window the cursor
             is in, F14 brings the window the cursor is in to the front or,
             if it is already at the front, pushes it to the back, and F15
             pops up the main Workplace (application) menu even if the
             cursor is not on the desktop, which is useful if you do not have
             any part of the desktop visible (and the logo on the key
             matches its functionality).</para>
 
 	  <para>The following entries in
 	    <filename>~/.fvwmrc</filename> implement the
 	    aforementioned setup:</para>
 
           <programlisting>Key F13        FTIWS    A        Iconify
 Key F14        FTIWS    A        RaiseLower
 Key F15        A        A        Menu Workplace Nop</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="x-3d-acceleration">
           <para>How can I get 3D hardware acceleration for
             OpenGL?</para>
         </question>
 
         <answer>
           <para>The availability of 3D acceleration depends on the
             version of XFree86 you are using and the type of video chip
             you have.  If you have an NVIDIA chip, check out the
             <ulink url="http://nvidia.netexplorer.org/">FreeBSD NVIDIA
             Driver Initiative </ulink> page, which discusses 3D
             acceleration for NVIDIA chips using XFree86-4.  For other
             cards with XFree86-4, including the Matrox G200/G400, ATI
             Rage 128/Radeon, and 3dfx Voodoo 3, 4, 5, and Banshee,
             information on hardware acceleration is available on the
             <ulink
             url="http://gladstone.uoregon.edu/~eanholt/dri/">XFree86-4
             Direct Rendering on FreeBSD</ulink> page.  Users of
             XFree86 version 3.3 can use the Utah-GLX port found in
             <filename role="package">graphics/utah-glx</filename> to get limited accelerated
             OpenGL on the Matrox Gx00, ATI Rage Pro, SiS 6326, i810,
             Savage, and older NVIDIA chips.</para>
           </answer>
         </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="networking">
     <title>Networking</title>
 
     <qandaset>
       <qandaentry>
         <question id="diskless-booting">
           <para>Where can I get information on
             <quote>diskless booting</quote>?</para>
           </question>
 
           <answer>
             <para><quote>Diskless booting</quote> means that the FreeBSD
               box is booted over a network, and reads the necessary files
               from a server instead of its hard disk. For full details,
               please read <ulink URL="../handbook/diskless.html">the
               Handbook entry on diskless booting</ulink></para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="router">
           <para>Can a FreeBSD box be used as a dedicated network
             router?</para>
         </question>
 
         <answer>
           <para>Yes.  Please see the Handbook entry on <ulink
             url="../handbook/routing.html"> advanced
             networking</ulink>, specifically the section on <ulink
             url="../handbook/routing.html#DEDICATED-ROUTER">routing
             and gateways</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="win95-connection">
           <para>Can I connect my Win95 box to the Internet via
             FreeBSD?</para>
         </question>
 
         <answer>
           <para>Typically, people who ask this question have two PC's
             at home, one with FreeBSD and one with Win95; the idea is to
             use the FreeBSD box to connect to the Internet and then be able
             to access the Internet from the Windows95 box through the
             FreeBSD box. This is really just a special case of the previous
             question.</para> <para>... and the answer is yes! In FreeBSD
             3.x, user-mode &man.ppp.8; contains a <option>-nat</option> option. If
             you run &man.ppp.8; with the <option>-nat</option>,
             set <literal>gateway_enable</literal> to
             <emphasis>YES</emphasis> in <filename>/etc/rc.conf</filename>,
             and configure your Windows machine correctly, this should work
             fine.</para>
 
           <para>More detailed information about setting this up can be
             found in the <ulink
             URL="../ppp-primer/index.html">
             Pedantic PPP Primer</ulink> by Steve Sims.</para>
 
           <para>If you are using kernel-mode PPP, or have an Ethernet
             connection to the Internet, you will have to use
             &man.natd.8;. Please look at the
             <link linkend="natd">natd</link> section of this FAQ.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="slip-ppp-support">
           <para>Does FreeBSD support SLIP and PPP?</para>
         </question>
 
         <answer>
           <para>Yes.  See the manual pages for &man.slattach.8;,
             &man.sliplogin.8;, &man.ppp.8;, and &man.pppd.8;.  &man.ppp.8;
             and &man.pppd.8; provide support for both incoming and outgoing
             connections, while &man.sliplogin.8; deals exclusively with
             incoming connections, and &man.slattach.8; deals exclusively
             with outgoing connections.</para>
 
           <para>For more information on how to use these, please see the
             <ulink url="../handbook/ppp-and-slip.html">Handbook chapter on
             PPP and SLIP</ulink>.</para>
 
           <para>If you only have access to the Internet through a
             <quote>shell account</quote>, you may want to have a look
             at the <filename role="package">net/slirp</filename> package.  It can provide you
             with (limited) access to services such as ftp and http
             direct from your local machine.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="natd">
           <para>Does FreeBSD support NAT or Masquerading?</para>
         </question>
 
         <answer>
           <para>If you have a local subnet (one or more local machines),
             but have been allocated only a single IP number from your
             Internet provider (or even if you receive a dynamic IP number),
             you may want to look at the &man.natd.8;
             program. &man.natd.8; allows you to connect an
             entire subnet to the Internet using only a single IP
             number.</para>
 
           <para>The &man.ppp.8;
             program has similar functionality built in via
             the <option>-nat</option> switch.  The
             alias library (&man.libalias.3;) is used in both cases.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="parallel-connect">
           <para>How do I connect two FreeBSD systems over a parallel line
             using PLIP?</para>
         </question>
 
         <answer>
           <para>Please see the <ulink url="../handbook/plip.html">PLIP
           section</ulink> of the Handbook.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="create-dev-net">
           <para>Why can I not create a <devicename>/dev/ed0</devicename>
             device?</para>
         </question>
 
         <answer>
           <para>Because they aren't necessary. In the Berkeley
             networking framework, network interfaces are only directly
             accessible by kernel code. Please see the
             <filename>/etc/rc.network</filename> file and the manual
             pages for the various network programs mentioned there for
             more information. If this leaves you totally confused,
             then you should pick up a book describing network
             administration on another BSD-related operating system;
             with few significant exceptions, administering networking
             on FreeBSD is basically the same as on SunOS 4.0 or
             Ultrix.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ethernet-aliases">
           <para>How can I set up Ethernet aliases?</para>
         </question>
 
 	<answer>
 	  <para>If the alias is on the same subnet as an address
 	    already configured on the interface, then add 
 	    <literal>netmask 0xffffffff</literal> to your
 	    &man.ifconfig.8; command-line, as in the following:</para>
 	  <screen>&prompt.root; <userinput>ifconfig ed0 alias 192.0.2.2 netmask 0xffffffff</userinput></screen>
 	  <para>Otherwise, just specify the network address and
 	    netmask as usual:</para>
 	  <screen>&prompt.root; <userinput>ifconfig ed0 alias 172.16.141.5 netmask 0xffffff00</userinput</screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="port-3c503">
           <para>How do I get my 3C503 to use the other network
             port?</para>
         </question>
 
         <answer>
           <para>If you want to use the other ports, you will have to specify
             an additional parameter on the
             &man.ifconfig.8; command line. The default port is
             <literal>link0</literal>. To use the AUI port instead of the
             BNC one, use <literal>link2</literal>.  These flags should be
             specified using the ifconfig_* variables in
             <filename>/etc/rc.conf</filename> (see &man.rc.conf.5;).</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="nfs">
           <para>Why am I having trouble with NFS and FreeBSD?</para>
         </question>
 
         <answer>
           <para>Certain PC network cards are better than others (to put
             it mildly) and can sometimes cause problems with network
             intensive applications like NFS.</para>
 
           <para>See <ulink URL="../handbook/nfs.html">
             the Handbook entry on NFS</ulink> for more information on
             this topic.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="nfs-linux">
           <para>Why can I not NFS-mount from a Linux box?</para>
         </question>
 
         <answer>
           <para>Some versions of the Linux NFS code only accept mount
             requests from a privileged port; try</para>
 
           <screen>&prompt.root; <userinput>mount -o -P linuxbox:/blah /mnt</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="nfs-sun">
           <para>Why can I not NFS-mount from a Sun box?</para>
         </question>
 
         <answer>
           <para>Sun workstations running SunOS 4.X only accept mount
             requests from a privileged port; try</para>
 
           <screen>&prompt.root; <userinput>mount -o -P sunbox:/blah /mnt</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="exports-errors">
           <para>Why does <command>mountd</command> keep telling me it
             <errorname>can't change attributes</errorname> and that I have a
             <errorname>bad exports list</errorname> on my FreeBSD NFS
             server?</para>
         </question>
 
         <answer>
           <para>The most frequent problem is not understanding the
             correct format of <filename>/etc/exports</filename>.
             Please review &man.exports.5; and the <ulink
             url="../handbook/nfs.html">NFS</ulink> entry in the
             Handbook, especially the section on <ulink
             url="../handbook/nfs.html#CONFIGURING-NFS">configuring
             NFS</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-nextstep">
           <para>Why am I having problems talking PPP to NeXTStep
             machines?</para>
         </question>
 
         <answer>
 
           <para>Try disabling the TCP extensions in
             <filename>/etc/rc.conf</filename> (see &man.rc.conf.5;) by changing the following variable to
             NO:</para>
 
           <programlisting>tcp_extensions=NO</programlisting>
 
           <para>Xylogic's Annex boxes are also broken in this regard and
             you must use the above change to connect thru them.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ip-multicast">
           <para>How do I enable IP multicast support?</para>
         </question>
 
         <answer>
           <para>Multicast host operations are fully supported in FreeBSD
             2.0 and later by default. If you want your box to run as a
             multicast router, you will need to recompile your kernel with
             the <literal>MROUTING</literal> option and run
             &man.mrouted.8;. FreeBSD 2.2 and later will start
             &man.mrouted.8; at boot time if the flag
             <literal>mrouted_enable</literal> is set to
             <literal>"YES"</literal> in
             <filename>/etc/rc.conf</filename>.</para>
 
           <para>MBONE tools are available in their own ports category,
             <ulink url="http://www.FreeBSD.org/ports/mbone.html">mbone</ulink>.  If you are looking for the conference tools
             <command>vic</command> and <command>vat</command>,
             look there!</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="dec-pci-chipset">
           <para>Which network cards are based on the DEC PCI
              chipset?</para>
         </question><answer>
 
           <para>Here is a list compiled by Glen Foster
              <email>gfoster@driver.nsta.org</email>,
              with some more modern additions:</para>
 
           <table>
             <title>Network cards based on the DEC PCI chipset</title>
 
             <tgroup cols=2>
               <thead>
                 <row>
                   <entry>Vendor</entry>
                   <entry>Model</entry>
                 </row>
               </thead>
 
               <tbody>
                 <row>
                   <entry>ASUS</entry>
                   <entry>PCI-L101-TB</entry>
                 </row>
                 <row>
                   <entry>Accton</entry>
                   <entry>ENI1203</entry>
                 </row>
                 <row>
                   <entry>Cogent</entry>
                   <entry>EM960PCI</entry>
                 </row>
                 <row>
                   <entry>Compex</entry>
                   <entry>ENET32-PCI</entry>
                 </row>
                 <row>
                   <entry>D-Link</entry>
                   <entry>DE-530</entry>
                 </row>
                 <row>
                   <entry>Dayna</entry>
                   <entry>DP1203, DP2100</entry>
                 </row>
                 <row>
                   <entry>DEC</entry>
                   <entry>DE435, DE450</entry>
                 </row>
                 <row>
                   <entry>Danpex</entry>
                   <entry>EN-9400P3</entry>
                 </row>
                 <row>
                   <entry>JCIS</entry>
                   <entry>Condor JC1260</entry>
                 </row>
                 <row>
                   <entry>Linksys</entry>
                   <entry>EtherPCI</entry>
                 </row>
                 <row>
                   <entry>Mylex</entry>
                   <entry>LNP101</entry>
                 </row>
                 <row>
                   <entry>SMC</entry>
                   <entry>EtherPower 10/100 (Model 9332)</entry>
                 </row>
                 <row>
                   <entry>SMC</entry>
                   <entry>EtherPower (Model 8432)</entry>
                 </row>
                 <row>
                   <entry>TopWare</entry>
                   <entry>TE-3500P</entry>
                 </row>
                 <row>
                   <entry>Znyx (2.2.x)</entry>
                   <entry>ZX312, ZX314, ZX342, ZX345, ZX346, ZX348</entry>
                 </row>
                 <row>
                   <entry>Znyx (3.x)</entry>
                   <entry>ZX345Q, ZX346Q, ZX348Q, ZX412Q, ZX414, ZX442, ZX444,
                     ZX474, ZX478, ZX212, ZX214 (10mbps/hd)</entry>
                 </row>
               </tbody>
             </tgroup>
           </table>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="fqdn-hosts">
           <para>Why do I have to use the FQDN for hosts on my
             site?</para>
         </question>
 
         <answer>
           <para>You will probably find that the host is actually in a
             different domain; for example, if you are in foo.example.org and
             you wish to reach a host called <hostid>mumble</hostid> in the
             <hostid role="domainname">example.org</hostid> domain, you will
             have to refer to it by the fully-qualified domain name, <hostid
             role="fqdn">mumble.example.org</hostid>, instead of just
             <hostid>mumble</hostid>.</para>
 
           <para>Traditionally, this was allowed by BSD BIND resolvers.
             However the current version of
             <application>bind</application> (see &man.named.8;)
             that ships with FreeBSD no longer provides default
             abbreviations for non-fully qualified domain names other than
             the domain you are in. So an unqualified host
             <hostid>mumble</hostid> must either be found as <hostid
             role="fqdn">mumble.foo.example.org</hostid>, or it will be searched
             for in the root domain.</para>
 
           <para>This is different from the previous behavior, where the
             search continued across
             <hostid role="domainname">mumble.example.org</hostid>, and
             <hostid role="domainname">mumble.edu</hostid>.  Have a look at
             RFC 1535 for why this was considered bad practice, or even a
             security hole.</para>
 
           <para>As a good workaround, you can place the line</para>
 
           <programlisting>search foo.example.org example.org</programlisting>
 
           <para>instead of the previous</para>
 
           <programlisting>domain foo.example.org</programlisting>
 
           <para>into your
             <filename>/etc/resolv.conf</filename> file (see &man.resolv.conf.5;).  However, make sure that the
             search order does not go beyond the <quote>boundary between
             local and public administration</quote>, as RFC 1535 calls
             it.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="network-permission-denied">
           <para>Why do I get an error, <errorname>Permission denied</errorname>,
             for all networking operations?</para>
         </question>
 
         <answer>
           <para>If you have compiled your kernel with the
             <literal>IPFIREWALL</literal> option, you need to be aware
             that the default policy as of 2.1.7R (this actually changed
             during 2.1-STABLE development) is to deny all packets that are
             not explicitly allowed.</para>
 
           <para>If you had unintentionally misconfigured your system for
             firewalling, you can restore network operability by typing
             the following while logged in as <username>root</username>:</para>
 
           <screen>&prompt.root; <userinput>ipfw add 65534 allow all from any to any</userinput></screen>
 
           <para>You can also set <literal>firewall_type="open"</literal>
             in <filename>/etc/rc.conf</filename>.</para>
 
           <para>For further information on configuring a FreeBSD firewall,
             see the <ulink URL="../handbook/firewalls.html">
             Handbook section</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ipfw-overhead">
           <para>How much overhead does IPFW incur?</para>
         </question>
 
         <answer>
           <para>Please see the Handbook's <ulink
             url="../handbook/firewalls.html">Firewalls</ulink>
             section, specifically the section on <ulink
             url="../handbook/firewalls.html#IPFW-OVERHEAD">IPFW
             Overhead & Optimization</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ipfw-fwd">
           <para>Why is my <command>ipfw</command> <quote>fwd</quote> rule
             to redirect a service to another machine not working?</para>
         </question>
 
         <answer>
           <para>Possibly because you want to do network address translation
             (NAT) and not just forward packets.  A <quote>fwd</quote> rule
             does exactly what it says; it forwards packets.  It does not
             actually change the data inside the packet.  Say we have a rule
             like:</para>
 
           <screen>01000 fwd <replaceable>10.0.0.1</replaceable> from any to <replaceable>foo 21</replaceable></screen>
 
           <para>When a packet with a destination address of
             <replaceable>foo</replaceable> arrives at the machine with this
             rule, the packet is forwarded to
             <replaceable>10.0.0.1</replaceable>, but it still has the
             destination address of <replaceable>foo</replaceable>!  The
             destination address of the packet is <emphasis>not</emphasis>
             changed to <replaceable>10.0.0.1</replaceable>.  Most machines
             would probably drop a packet that they receive with a
             destination address that is not their own.  Therefore, using a
             <quote>fwd</quote> rule does not often work the way the user
             expects.  This behavior is a feature and not a bug.</para>
 
           <para>See the <link linkend="service-redirect">FAQ about
             redirecting services</link>, the &man.natd.8; manual, or one of
             the several port redirecting utilities in the <ulink
             url="../../../../ports/index.html">ports collection</ulink> for a correct way to do
             this.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="service-redirect">
           <para>How can I redirect service requests from one machine to
             another?</para>
         </question>
 
         <answer>
           <para>You can redirect FTP (and other service) request with
             the <literal>socket</literal> package, available in the ports
             tree in category <quote>sysutils</quote>. Simply replace the
             service's command line to call socket instead, like so:</para>
 
           <programlisting>ftp stream tcp nowait nobody /usr/local/bin/socket socket <replaceable>ftp.example.com</replaceable> <replaceable>ftp</replaceable></programlisting>
 
           <para>where <replaceable>ftp.example.com</replaceable> and
             <replaceable>ftp</replaceable> are the host and port to
             redirect to, respectively.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="bandwidth-mgr-tool">
           <para>Where can I get a bandwidth management tool?</para>
         </question>
 
         <answer>
           <para>There are three bandwidth management tools available for
 	    FreeBSD.  &man.dummynet.4; is integrated into FreeBSD (or more
 	    specifically, &man.ipfw.4;); <ulink
 	    URL="http://www.csl.sony.co.jp/person/kjc/programs.html">ALTQ</ulink>
 	    is available for free; Bandwidth Manager from <ulink
 	    URL="http://www.etinc.com/">Emerging Technologies</ulink> is a
 	    commercial product.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="bpf-not-configured">
           <para>Why do I get <errorname>/dev/bpf0: device not
             configured</errorname>?</para>
         </question>
 
         <answer>
           <para>You are running a program that requires the Berkeley
             Packet Filter (&man.bpf.4;), but it's not in your kernel.
             Add this to your kernel config file and build a new
             kernel:</para>
 
           <programlisting>pseudo-device bpf        # Berkeley Packet Filter</programlisting>
 
           <para>After rebooting, create the device node. This can be
             accomplished by going to the <filename>/dev</filename>
             directory and running:</para>
 
           <screen>&prompt.root; <userinput>sh MAKEDEV bpf0</userinput></screen>
 
           <para>Please see the <ulink
             URL="../handbook/kernelconfig-nodes.html"> Handbook entry
             on device nodes</ulink> for more information on creating
             devices.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="mount-smb-share">
           <para>How do I mount a disk from a Windows machine that is on my
             network, like smbmount in Linux?</para>
         </question>
 
         <answer>
           <para>Use the <application>SMBFS</application> toolset.  It
             includes a set of kernel modifications and a set of
             userland programs.  The programs and information are
             available as <filename role="package">net/smbfs</filename> in the ports
             collection, or in the base system as of 4.5-RELEASE and
             later.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="icmp-response-bw-limit">
           <para>What are these messages about <quote>icmp-response
             bandwidth limit 300/200 pps</quote> in my log
             files?</para>
         </question>
 
         <answer>
           <para>This is the kernel telling you that some activity is
             provoking it to send more ICMP or TCP reset (RST)
             responses than it thinks it should.  ICMP responses are
             often generated as a result of attempted connections to
             unused UDP ports.  TCP resets are generated as a result of
             attempted connections to unopened TCP ports.  Among
             others, these are the kinds of activities which may cause
             these messages:</para>
 
           <itemizedlist>
             <listitem>
               <para>Brute-force denial of service (DoS) attacks (as
                 opposed to single-packet attacks which exploit a
                 specific vulnerability).</para>
             </listitem>
 
             <listitem>
               <para>Port scans which attempt to connect to a large
                 number of ports (as opposed to only trying a few
                 well-known ports).</para>
             </listitem>
           </itemizedlist>
 
           <para>The first number in the message tells you how many
             packets the kernel would have sent if the limit was not in
             place, and the second number tells you the limit.  You can
             control the limit using the
             <varname>net.inet.icmp.icmplim</varname> sysctl variable
             like this, where <literal>300</literal> is the limit in
             packets per second:</para>
 
           <screen>&prompt.root; <userinput>sysctl -w net.inet.icmp.icmplim=300</userinput></screen>
 
           <para>If you do not want to see messages about this in your
             log files, but you still want the kernel to do response
             limiting, you can use the
             <varname>net.inet.icmp.icmplim_output</varname> sysctl
             variable to disable the output like this:</para>
 
           <screen>&prompt.root; <userinput>sysctl -w net.inet.icmp.icmplim_output=0</userinput></screen>
 
           <para>Finally, if you want to disable response limiting, you
             can set the <varname>net.inet.icmp.icmplim</varname>
             sysctl variable (see above for an example) to
             <literal>0</literal>.  Disabling response limiting is
             discouraged for the reasons listed above.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="unknown-hw-addr-format">
           <para>What are these <errorname>arp: unknown hardware
             address format</errorname> error messages?</para>
         </question>
 
         <answer>
           <para>This means that some device on your local Ethernet is
             using a MAC address in a format that FreeBSD does not
             recognize.  This is probably caused by someone
             experimenting with an Ethernet card somewhere else on the
             network.  You will see this most commonly on cable modem
             networks.  It is harmless, and should not affect the
             performance of your FreeBSD machine.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="security">
     <title>Security</title>
     <qandaset>
       <qandaentry>
         <question id="extra-named-port">
 	  <para>BIND (<command>named</command>) is listening on port 53 and
 	    some other high-numbered port.  What is going on?</para>
 	</question>
 
 	<answer>
 	  <para>FreeBSD 3.0 and later use a version of BIND
 	    that uses a random high-numbered port for outgoing queries.  If
 	    you want to use port 53 for outgoing queries, either to get
 	    past a firewall or to make yourself feel better, you can try
 	    the following in
 	    <filename>/etc/namedb/named.conf</filename>:</para>
 
 	  <programlisting>options {
         query-source address * port 53;
 };</programlisting>
 
 	  <para>You can replace the <literal>*</literal> with a single IP
 	    address if you want to tighten things further.</para>
 
 	  <para>Congratulations, by the way.  It is good practice to read
 	    your &man.sockstat.1; output and notice odd
 	    things!</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
         <question id="sendmail-port-587">
           <para>Sendmail is listening on port 587 as well as the
             standard port 25! What is going on?</para>
         </question>
 
         <answer>
           <para>Recent versions of Sendmail support a
             mail submission feature that runs over port 587.  This is
             not yet widely supported, but is growing in
             popularity.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="toor-account">
           <para>What is this UID 0 <username>toor</username> account? Have I
             been compromised?</para>
         </question>
 
         <answer>
           <para>Do not worry. <username>toor</username> is an
             <quote>alternative</quote> superuser account (toor is root
             spelt backwards). Previously it was created when the
             &man.bash.1; shell was installed but now it is created by
             default. It is intended to be used with a non-standard shell so
             you do not have to change <username>root</username>'s default
             shell. This is important as shells which are not part of the
             base distribution (for example a shell installed from ports or
             packages) are likely be to be installed in
             <filename>/usr/local/bin</filename> which, by default, resides
             on a different filesystem. If <username>root</username>'s shell
             is located in <filename>/usr/local/bin</filename> and
             <filename>/usr</filename> (or whatever filesystem contains
             <filename>/usr/local/bin</filename>) is not mounted for some
             reason, <username>root</username> will not be able to log in to
             fix a problem (although if you reboot into single user mode
             you will be prompted for the path to a shell).</para>
 
           <para>Some people use <username>toor</username> for
             day-to-day root tasks with a non-standard shell, leaving
             <username>root</username>, with a standard shell, for
             single user mode or emergencies. By default you cannot log
             in using <username>toor</username> as it does not have a
             password, so log in as <username>root</username> and set a password for
             <username>toor</username> if you want to use it.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="suidperl">
           <para>Why is <command>suidperl</command> not working
             properly?</para>
         </question>
 
         <answer>
           <para>For security reasons, <command>suidperl</command> is
             installed without the suid bit by default.  The system
             administrator can enable suid behavior with the following
             command.</para>
 
 	    <screen>&prompt.root; <userinput>chmod u+s /usr/bin/suidperl</userinput></screen>
 
           <para>If you want <command>suidperl</command> to be built
             suid during upgrades from source, edit
             <filename>/etc/make.conf</filename> and add
             <varname>ENABLE_SUIDPERL=true</varname> before you run
             <command>make buildworld</command>.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="ppp">
     <title>PPP</title>
 
     <qandaset>
       <qandaentry>
         <question id="userppp">
           <para>I cannot make &man.ppp.8; work.  What am I doing wrong?</para>
         </question>
 
         <answer>
           <para>You should first read the
             &man.ppp.8;
             man page and the <ulink
             URL="../handbook/ppp-and-slip.html#USERPPP">
             PPP section of the handbook</ulink>.  Enable logging with
             the command</para>
 
           <programlisting>set log Phase Chat Connect Carrier lcp ipcp ccp command</programlisting>
 
           <para>This command may be typed at the
             &man.ppp.8; command prompt or it may be
             entered in the <filename>/etc/ppp/ppp.conf</filename>
             configuration file (the start of the
             <literal>default</literal> section is the best
             place to put it).  Make sure that
             <filename>/etc/syslog.conf</filename> (see &man.syslog.conf.5;) contains the lines</para>
 
           <programlisting>!ppp
 *.*        /var/log/ppp.log</programlisting>
 
           <para>and that the file <filename>/var/log/ppp.log</filename>
             exists.  You can now find out a lot about what is going on
             from the log file.  Do not worry if it does not all make sense.
             If you need to get help from someone, it may make sense to
             them.</para>
 
           <para>If your version of &man.ppp.8; does not understand the
             <command>set log</command> command, you should download the
             <ulink URL="http://people.FreeBSD.org/~brian/">
             latest version</ulink>. It will build on FreeBSD version
             2.1.5 and higher.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-hangs">
           <para>Why does &man.ppp.8; hang when I run it?</para>
         </question>
 
         <answer>
           <para>This is usually because your hostname will not resolve.
             The best way to fix this is to make sure that
             <filename>/etc/hosts</filename> is consulted by your
             resolver first by editing <filename>/etc/host.conf</filename>
             and putting the <literal>hosts</literal> line first.  Then,
             simply put an entry in <filename>/etc/hosts</filename> for
             your local machine.  If you have no local network, change your
             <hostid>localhost</hostid> line:</para>
 
           <programlisting>127.0.0.1        foo.bar.com foo localhost</programlisting>
 
           <para>Otherwise, simply add another entry for your host.
             Consult the relevant man pages for more details.</para>
 
           <para>You should be able to successfully
             <command>ping -c1 `hostname`</command> when you are done.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-nodial-auto">
           <para>Why will &man.ppp.8; not dial in <literal>-auto</literal>
             mode?</para>
         </question>
 
         <answer>
           <para>First, check that you have got a default route.  By running
             <command>netstat -rn</command> (see &man.netstat.1;), you should see two entries like this:</para>
 
           <programlisting>Destination        Gateway            Flags     Refs     Use     Netif Expire
 default            10.0.0.2           UGSc        0        0      tun0
 10.0.0.2           10.0.0.1           UH          0        0      tun0</programlisting>
 
           <para>This is assuming that you have used the addresses from the
             handbook, the man page or from the ppp.conf.sample file.
             If you do not have a default route, it may be because you are
             running an old version of &man.ppp.8;
             that does not understand the word <literal>HISADDR</literal>
             in the ppp.conf file.  If your version of
             &man.ppp.8; is from before FreeBSD
             2.2.5, change the</para>
 
           <programlisting>add 0 0 HISADDR</programlisting>
 
           <para>line to one saying</para>
 
 
           <programlisting>add 0 0 10.0.0.2</programlisting>
 
           <para>Another reason for the default route line being missing
             is that you have mistakenly set up a default router in your
             <filename>/etc/rc.conf</filename> (see &man.rc.conf.5;) file (this file was called
             <filename>/etc/sysconfig</filename> prior to release 2.2.2),
             and you have omitted the line saying</para>
 
           <programlisting>delete ALL</programlisting>
 
           <para>from <filename>ppp.conf</filename>.  If this is the case,
             go back to the <ulink
             URL="../handbook/ppp-and-slip.html#USERPPP-FINAL">
             Final system configuration</ulink> section of the
             handbook.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="no-route-to-host">
           <para>What does <errorname>No route to host</errorname> mean?</para>
         </question>
 
         <answer>
           <para>This error is usually due to a missing</para>
 
           <programlisting>MYADDR:
   delete ALL
   add 0 0 HISADDR</programlisting>
 
           <para>section in your <filename>/etc/ppp/ppp.linkup</filename>
             file.  This is only necessary if you have a dynamic IP address
             or do not know the address of your gateway.  If you are using
             interactive mode, you can type the following after entering
             <literal>packet mode</literal> (packet mode is
             indicated by the capitalized <acronym>PPP</acronym> in the
             prompt):</para>
 
          <programlisting>delete ALL
 add 0 0 HISADDR</programlisting>
 
           <para>Refer to the <ulink
             URL="../handbook/ppp-and-slip.html#USERPPP-DYNAMICIP">
             PPP and Dynamic IP addresses</ulink> section of the handbook
             for further details.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="connection-threeminutedrop">
           <para>Why does my connection drop after about 3 minutes?</para>
         </question>
 
         <answer>
           <para>The default PPP timeout is 3 minutes.  This can be
             adjusted with the line</para>
 
           <programlisting>set timeout <replaceable>NNN</replaceable></programlisting>
 
           <para>where <replaceable>NNN</replaceable> is the number of
             seconds of inactivity before the connection is closed.  If
             <replaceable>NNN</replaceable> is zero, the connection is never
             closed due to a timeout. It is possible to put this command in
             the <filename>ppp.conf</filename> file, or to type it at the
             prompt in interactive mode. It is also possible to adjust it on
             the fly while the line is active by connecting to
             <application>ppp</application>s server socket using
             &man.telnet.1; or &man.pppctl.8;.
             Refer to the
             &man.ppp.8; man
             page for further details.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-drop-heavy-load">
           <para>Why does my connection drop under heavy load?</para>
         </question>
 
         <answer>
           <para>If you have Link Quality Reporting (LQR) configured,
             it is possible that too many LQR packets are lost between
             your machine and the peer.  Ppp deduces that the line must
             therefore be bad, and disconnects.  Prior to FreeBSD version
             2.2.5, LQR was enabled by default.  It is now disabled by
             default. LQR can be disabled with the line</para>
 
           <programlisting>disable lqr</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-drop-random">
           <para>Why does my connection drop after a random amount of
             time?</para>
         </question>
 
         <answer>
           <para>Sometimes, on a noisy phone line or even on a line with
             call waiting enabled, your modem may hang up because it
             thinks (incorrectly) that it lost carrier.</para>
 
           <para>There is a setting on most modems for determining how
             tolerant it should be to temporary losses of carrier.  On a
             USR Sportster for example, this is measured by the S10
             register in tenths of a second.  To make your modem more
             forgiving, you could add the following send-expect sequence
             to your dial string:</para>
 
           <programlisting>set dial "...... ATS10=10 OK ......"</programlisting>
 
           <para>Refer to your modem manual for details.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-hangs-random">
           <para>Why does my connection hang after a random amount of
             time?</para>
         </question><answer>
 
           <para>Many people experience hung connections with no apparent
             explanation.  The first thing to establish is which side of
             the link is hung.</para>
 
           <para>If you are using an external modem, you can simply try
             using &man.ping.8; to see if the
             <acronym>TD</acronym> light is flashing when you transmit data.
             If it flashes (and the <acronym>RD</acronym> light does not),
             the problem is with the remote end. If <acronym>TD</acronym>
             does not flash, the problem is local. With an internal modem,
             you will need to use the <literal>set server</literal> command in
             your <filename>ppp.conf</filename> file. When the hang occurs,
             connect to &man.ppp.8; using &man.pppctl.8;. If your network connection
             suddenly revives (PPP was revived due to the activity on the
             diagnostic socket) or if you cannot connect (assuming the
             <literal>set socket</literal> command succeeded at startup
             time), the problem is local. If you can connect and things are
             still hung, enable local async logging with <literal>set log
             local async</literal> and use &man.ping.8; from
             another window or terminal to make use of the link. The async
             logging will show you the data being transmitted and received
             on the link. If data is going out and not coming back, the
             problem is remote.</para>
 
           <para>Having established whether the problem is local or remote,
             you now have two possibilities:</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-remote-not-responding">
           <para>The remote end is not responding.  What can I do?</para>
         </question>
 
         <answer>
           <para>There is very little you can do about this.  Most ISPs
             will refuse to help if you are not running a Microsoft OS.
             You can <literal>enable lqr</literal> in your
             <filename>ppp.conf</filename> file, allowing &man.ppp.8; to detect
             the remote failure and hang up, but this detection is
             relatively slow and therefore not that useful.  You may want to
             avoid telling your ISP that you are running user-PPP...</para>
 
           <para>First, try disabling all local compression by adding the
             following to your configuration:</para>
 
           <programlisting>disable pred1 deflate deflate24 protocomp acfcomp shortseq vj
 deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting>
 
           <para>Then reconnect to ensure that this makes no difference.
             If things improve or if the problem is solved completely,
             determine which setting makes the difference through trial
             and error.  This will provide good ammunition when you contact
             your ISP (although it may make it apparent that you are not
             running a Microsoft product).</para>
 
           <para>Before contacting your ISP, enable async logging locally
             and wait until the connection hangs again.  This may use up
             quite a bit of disk space.  The last data read from the port
             may be of interest.  It is usually ascii data, and may even
             describe the problem
             (<quote>Memory fault, core dumped</quote>?).</para>
 
           <para>If your ISP is helpful, they should be able to enable
             logging on their end, then when the next link drop occurs,
             they may be able to tell you why their side is having a
             problem.  Feel free to send the details to &a.brian;, or
             even to ask your ISP to contact me directly.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-hung">
           <para>&man.ppp.8; has hung.  What can I do?</para>
         </question>
 
         <answer>
           <para>Your best bet here is to rebuild &man.ppp.8; by adding
             <literal>CFLAGS+=-g</literal> and <literal>STRIP=</literal>
             to the end of the Makefile, then doing a
             <command>make clean &amp;&amp; make &amp;&amp; make
             install</command>.  When &man.ppp.8; hangs, find the &man.ppp.8; process id
             with <command>ps ajxww | fgrep ppp</command> and run
             <command>gdb ppp <replaceable>PID</replaceable></command>.
             From the gdb prompt, you can then use <command>bt</command>
             to get a stack trace.</para>
 
           <para>Send the results to <email>brian@Awfulhak.org</email>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-loginok-thennothing">
           <para>Why does nothing happen after the <quote>Login OK!</quote>
             message?</para>
         </question>
 
         <answer>
           <para>Prior to FreeBSD version 2.2.5, once the link was
             established, &man.ppp.8;
             would wait for the peer to initiate the Line Control Protocol
             (LCP).  Many ISPs will not initiate negotiations and expect
             the client to do so.  To force
             &man.ppp.8; to initiate the LCP, use the
             following line:</para>
 
           <programlisting>set openmode active</programlisting>
 
             <note>
               <para>It usually does no
             harm if both sides initiate negotiation, so openmode is now
             active by default.  However, the next section explains when
             it <emphasis>does</emphasis> do some harm.</para>
             </note>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-same-magic">
           <para>I keep seeing errors about magic being the same.  What does
             it mean?</para>
         </question>
 
         <answer>
           <para>Occasionally, just after connecting, you may see messages
             in the log that say <quote>magic is the same</quote>.
             Sometimes, these messages are harmless, and sometimes one side
             or the other exits.  Most PPP implementations cannot survive
             this problem, and even if the link seems to come up, you will see
             repeated configure requests and configure acknowledgments in
             the log file until &man.ppp.8; eventually gives up and closes the
             connection.</para>
 
           <para>This normally happens on server machines with slow disks
             that are spawning a getty on the port, and executing &man.ppp.8; from
             a login script or program after login.  I have also heard reports
             of it happening consistently when using slirp.  The reason is
             that in the time taken between &man.getty.8; exiting and &man.ppp.8; starting,
             the client-side &man.ppp.8; starts sending Line Control Protocol (LCP)
             packets.  Because ECHO is still switched on for the port on
             the server, the client &man.ppp.8; sees these packets
             <quote>reflect</quote> back.</para>
 
           <para>One part of the LCP negotiation is to establish a magic
             number for each side of the link so that
             <quote>reflections</quote> can be detected. The protocol says
             that when the peer tries to negotiate the same magic number, a
             NAK should be sent and a new magic number should be chosen.
             During the period that the server port has ECHO turned on, the
             client &man.ppp.8; sends LCP packets, sees the same magic in the
             reflected packet and NAKs it. It also sees the NAK reflect
             (which also means &man.ppp.8; must change its magic). This produces a
             potentially enormous number of magic number changes, all of
             which are happily piling into the server's tty buffer. As soon
             as &man.ppp.8; starts on the server, it is flooded with magic number
             changes and almost immediately decides it has tried enough to
             negotiate LCP and gives up. Meanwhile, the client, who no
             longer sees the reflections, becomes happy just in time to see
             a hangup from the server.</para>
 
           <para>This can be avoided by allowing the peer to start
             negotiating with the following line in your ppp.conf
             file:</para>
 
           <programlisting>set openmode passive</programlisting>
 
           <para>This tells &man.ppp.8; to wait for the server to initiate LCP
             negotiations.  Some servers however may never initiate
             negotiations.  If this is the case, you can do something
             like:</para>
 
           <programlisting>set openmode active 3</programlisting>
 
           <para>This tells &man.ppp.8; to be passive for 3 seconds, and then to
             start sending LCP requests.  If the peer starts sending
             requests during this period, &man.ppp.8; will immediately respond
             rather than waiting for the full 3 second period.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-lcp-constant">
           <para>LCP negotiations continue until the connection is
             closed.  What is wrong?</para>
         </question>
 
         <answer>
           <para>There is currently an implementation mis-feature in
             &man.ppp.8; where it does not associate
             LCP, CCP &amp; IPCP responses with their original requests. As
             a result, if one PPP
             implementation is more than 6 seconds slower than the other
             side, the other side will send two additional LCP configuration
             requests. This is fatal.</para>
 
           <para>Consider two implementations,
             <hostid>A</hostid> and
             <hostid>B</hostid>. <hostid>A</hostid> starts
             sending LCP requests immediately after connecting and
             <hostid>B</hostid> takes 7 seconds to start. When
             <hostid>B</hostid> starts, <hostid>A</hostid>
             has sent 3 LCP REQs. We are assuming the line has ECHO switched
             off, otherwise we would see magic number problems as described in
             the previous section. <hostid>B</hostid> sends a
             REQ, then an ACK to the first of
             <hostid>A</hostid>'s REQs. This results in
             <hostid>A</hostid> entering the <acronym>OPENED</acronym>
             state and sending and ACK (the first) back to
             <hostid>B</hostid>. In the meantime,
             <hostid>B</hostid> sends back two more ACKs in response to
             the two additional REQs sent by <hostid>A</hostid>
             before <hostid>B</hostid> started up.
             <hostid>B</hostid> then receives the first ACK from
             <hostid>A</hostid> and enters the
             <acronym>OPENED</acronym> state.
             <hostid>A</hostid> receives the second ACK from
             <hostid>B</hostid> and goes back to the
             <acronym>REQ-SENT</acronym> state, sending another (forth) REQ
             as per the RFC. It then receives the third ACK and enters the
             <acronym>OPENED</acronym> state. In the meantime,
             <hostid>B</hostid> receives the forth REQ from
             <hostid>A</hostid>, resulting in it reverting to the
             <acronym>ACK-SENT</acronym> state and sending
             another (second) REQ and (forth) ACK as per the RFC.
             <hostid>A</hostid> gets the REQ, goes into
             <acronym>REQ-SENT</acronym> and sends another REQ. It
             immediately receives the following ACK and enters
             <acronym>OPENED</acronym>.</para>
 
           <para>This goes on until one side figures out that they are
             getting nowhere and gives up.</para>
 
           <para>The best way to avoid this is to configure one side to be
             <literal>passive</literal> - that is, make one side
             wait for the other to start negotiating.  This can be done
             with the</para>
 
           <programlisting>set openmode passive</programlisting>
 
           <para>command.  Care should be taken with this option.  You
             should also use the</para>
 
           <programlisting>set stopped N</programlisting>
 
           <para>command to limit the amount of time that
             &man.ppp.8; waits for the peer to begin
             negotiations.  Alternatively, the</para>
 
           <programlisting>set openmode active N</programlisting>
 
           <para>command (where <replaceable>N</replaceable> is the
             number of seconds to wait before starting negotiations) can be
             used.  Check the manual page for details.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-lockups">
           <para>Why does &man.ppp.8; lock up shortly after connection?</para>
         </question>
 
         <answer>
           <para>Prior to version 2.2.5 of FreeBSD, it was possible that
             your link was disabled shortly after connection due to
             &man.ppp.8; mis-handling Predictor1
             compression negotiation. This would only happen if both sides
             tried to negotiate different Compression Control Protocols
             (CCP). This problem is now corrected, but if you are still
             running an old version of &man.ppp.8;
             the problem can be circumvented with the line</para>
 
           <programlisting>disable pred1</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-shell-test-lockup">
           <para>Why does &man.ppp.8; lock up when I shell out to test it?</para>
         </question>
 
         <answer>
           <para>When you execute the <command>shell</command> or
             <command>!</command> command, &man.ppp.8; executes a
             shell (or if you have passed any arguments,
             &man.ppp.8; will execute those arguments). Ppp will
             wait for the command to complete before continuing. If you
             attempt to use the PPP link while running the command, the link
             will appear to have frozen. This is because
             &man.ppp.8; is waiting for the command to
             complete.</para>
 
           <para>If you wish to execute commands like this, use the
             <command>!bg</command> command instead.  This will execute
             the given command in the background, and &man.ppp.8; can continue to
             service the link.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-nullmodem">
           <para>Why does &man.ppp.8; over a null-modem cable never exit?</para>
         </question>
 
         <answer>
           <para>There is no way for &man.ppp.8; to
             automatically determine that a direct connection has been
             dropped.  This is due to the lines that are used in a
             null-modem serial cable.  When using this sort of connection,
             LQR should always be enabled with the line</para>
 
           <programlisting>enable lqr</programlisting>
 
           <para>LQR is accepted by default if negotiated by the peer.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-auto-noreasondial">
           <para>Why does &man.ppp.8; dial for no reason in -auto mode?</para>
         </question><answer>
 
           <para>If &man.ppp.8; is dialing
             unexpectedly, you must determine the cause, and set up Dial
             filters (dfilters) to prevent such dialing.</para>
 
           <para>To determine the cause, use the following line:</para>
 
           <programlisting>set log +tcp/ip</programlisting>
 
           <para>This will log all traffic through the connection.  The
             next time the line comes up unexpectedly, you will see the
             reason logged with a convenient timestamp next to it.</para>
 
           <para>You can now disable dialing under these circumstances.
             Usually, this sort of problem arises due to DNS lookups.  To
             prevent DNS lookups from establishing a connection (this will
             <emphasis>not</emphasis> prevent
             &man.ppp.8; from passing the packets
             through an established connection), use the following:</para>
 
           <programlisting>set dfilter 1 deny udp src eq 53
 set dfilter 2 deny udp dst eq 53
 set dfilter 3 permit 0/0 0/0</programlisting>
 
           <para>This is not always suitable, as it will effectively break
             your demand-dial capabilities - most programs will need a DNS
             lookup before doing any other network related things.</para>
 
           <para>In the DNS case, you should try to determine what is
             actually trying to resolve a host name.  A lot of the time,
             &man.sendmail.8; is the culprit.  You should make sure that
             you tell sendmail not to do any DNS lookups in its
             configuration file.  See the section on
             <link linkend="ispmail">Mail Configuration</link> for details
             on how to create your own configuration file and what should
             go into it.  You may also want to add the following line to
             your <filename>.mc</filename> file:</para>
 
           <programlisting>define(`confDELIVERY_MODE', `d')dnl</programlisting>
 
           <para>This will make sendmail queue everything until the queue
             is run (usually, sendmail is invoked with
             <option>-bd -q30m</option>, telling it to run the queue every
             30 minutes) or until a <command>sendmail -q</command> is done
             (perhaps from your ppp.linkup file).</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ccp-errors">
           <para>What do these CCP errors mean?</para>
         </question>
 
         <answer>
           <para>I keep seeing the following errors in my log file:</para>
 
           <programlisting>CCP: CcpSendConfigReq
 CCP: Received Terminate Ack (1) state = Req-Sent (6)</programlisting>
 
           <para>This is because &man.ppp.8; is trying to negotiate Predictor1
             compression, and the peer does not want to negotiate any
             compression at all.  The messages are harmless, but if you
             wish to remove them, you can disable Predictor1 compression
             locally too:</para>
 
           <programlisting>disable pred1</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-lockup-ioerrors">
           <para>Why does &man.ppp.8; lock up during file transfers with IO
             errors?</para>
         </question>
 
         <answer>
           <para>Under FreeBSD 2.2.2 and before, there was a bug in the
             tun driver that prevents incoming packets of a size larger
             than the tun interface's MTU size.  Receipt of a packet
             greater than the MTU size results in an IO error being logged
             via syslogd.</para>
 
           <para>The PPP specification says that an MRU of 1500 should
             <emphasis>always</emphasis> be accepted as a minimum,
             despite any LCP negotiations, therefore it is possible that
             should you decrease the MTU to less than 1500, your ISP will
             transmit packets of 1500 regardless, and you will tickle this
             non-feature - locking up your link.</para>
 
           <para>The problem can be circumvented by never setting an MTU of
             less than 1500 under FreeBSD 2.2.2 or before.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-connectionspeed">
           <para>Why does &man.ppp.8; not log my connection speed?</para>
         </question>
 
         <answer>
 
           <para>In order to log all lines of your modem
             <quote>conversation</quote>, you must enable the
             following:</para>
 
           <programlisting>set log +connect</programlisting>
 
           <para>This will make &man.ppp.8; log
             everything up until the last requested <quote>expect</quote>
             string.</para>
 
           <para>If you wish to see your connect speed and are using PAP
             or CHAP (and therefore do not have anything to
             <quote>chat</quote> after the CONNECT in the dial script - no
             <literal>set login</literal> script), you must make sure that
             you instruct &man.ppp.8; to <quote>expect</quote> the whole CONNECT
             line, something like this:</para>
 
           <programlisting>set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 4 \
   \"\" ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT \\c \\n"</programlisting>
 
           <para>Here, we get our CONNECT, send nothing, then expect a
             line-feed, forcing &man.ppp.8; to read
             the whole CONNECT response.</para>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-ignores-backslash">
           <para>Why does &man.ppp.8; ignore the <literal>\</literal> character
             in my chat script?</para>
         </question><answer>
 
           <para>Ppp parses each line in your config files so that it can
             interpret strings such as
             <literal>set phone "123 456 789"</literal> correctly (and
             realize that the number is actually only
             <emphasis>one</emphasis> argument. In order to specify a
             <literal>&quot;</literal> character, you must escape it
             using a backslash (<literal>\</literal>).</para>
 
           <para>When the chat interpreter parses each argument, it
             re-interprets the argument in order to find any special
             escape sequences such as <literal>\P</literal> or
             <literal>\T</literal> (see the man page).  As a result of this
             double-parsing, you must remember to use the correct number of
             escapes.</para>
 
           <para>If you wish to actually send a <literal>\</literal>
             character to (say) your modem, you would need something
             like:</para>
 
           <programlisting>set dial "\"\" ATZ OK-ATZ-OK AT\\\\X OK"</programlisting>
 
           <para>resulting in the following sequence:</para>
 
           <programlisting>ATZ
 OK
 AT\X
 OK</programlisting>
 
           <para>or</para>
 
           <programlisting>set phone 1234567
 set dial "\"\" ATZ OK ATDT\\T"</programlisting>
 
           <para>resulting in the following sequence:</para>
 
           <programlisting>ATZ
 OK
 ATDT1234567</programlisting>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-segfault-nocore">
           <para>Why does &man.ppp.8; get a seg-fault, but I see no
             <filename>ppp.core</filename> file?</para>
         </question>
 
         <answer>
           <para>Ppp (or any other program for that matter) should never
             dump core.  Because &man.ppp.8; runs with an effective user id of 0,
             the operating system will not write &man.ppp.8;'s core image to disk
             before terminating it.  If, however &man.ppp.8;
             is actually terminating due to a
             segmentation violation or some other signal that normally
             causes core to be dumped, <emphasis>and</emphasis>
             you are sure you are using the latest version (see the start of
             this section), then you should do the following:</para>
 
           <screen>&prompt.user; <userinput>tar xfz ppp-*.src.tar.gz</userinput>
 &prompt.user; <userinput>cd ppp*/ppp</userinput>
 &prompt.user; <userinput>echo STRIP= &gt;&gt;Makefile</userinput>
 &prompt.user; <userinput>echo CFLAGS+=-g &gt;&gt;Makefile</userinput>
 &prompt.user; <userinput>make clean all</userinput>
 &prompt.user; <userinput>su</userinput>
 &prompt.root; <userinput>make install</userinput>
 &prompt.root; <userinput>chmod 555 /usr/sbin/ppp</userinput></screen>
 
           <para>You will now have a debuggable version of &man.ppp.8; installed.
             You will have to be <username>root</username> to run &man.ppp.8; as all of its privileges
             have been revoked.  When you start &man.ppp.8;, take a careful note
             of what your current directory was at the time.</para>
 
           <para>Now, if and when &man.ppp.8; receives the segmentation violation,
             it will dump a core file called <filename>ppp.core</filename>.  You should then do
             the following:</para>
 
           <screen>&prompt.user; <userinput>su</userinput>
 &prompt.root; <userinput>gdb /usr/sbin/ppp ppp.core</userinput>
 <prompt>(gdb)</prompt> <userinput>bt</userinput>
 .....
 <prompt>(gdb)</prompt> <userinput>f 0</userinput>
 ....
 <prompt>(gdb)</prompt> <userinput>i args</userinput>
 ....
 <prompt>(gdb)</prompt> <userinput>l</userinput>
 .....</screen>
 
           <para>All of this information should be given alongside your
             question, making it possible to diagnose the problem.</para>
 
           <para>If you are familiar with gdb, you may wish to find out some
             other bits and pieces such as what actually caused the dump and
             the addresses &amp; values of the relevant variables.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-autodialprocess-noconnect">
           <para>Why does the process that forces a dial in auto mode never
             connect?</para>
         </question>
 
         <answer>
           <para>This was a known problem with
             &man.ppp.8; set up to negotiate a
             dynamic local IP number with the peer in auto mode.  It is
             fixed in the latest version - search the man page for
             <literal>iface</literal>.</para>
 
           <para>The problem was that when that initial program calls
             &man.connect.2;, the IP number of the tun interface is assigned
             to the socket endpoint. The kernel creates the first outgoing
             packet and writes it to the tun device.
             &man.ppp.8; then reads the packet and
             establishes a connection. If, as a result of
             &man.ppp.8;'s dynamic IP assignment, the
             interface address is changed, the original socket endpoint will
             be invalid. Any subsequent packets sent to the peer will
             usually be dropped. Even if they are not, any responses will
             not route back to the originating machine as the IP number is
             no longer owned by that machine.</para>
 
           <para>There are several theoretical ways to approach this
             problem. It would be nicest if the peer would re-assign the
             same IP number if possible <literal>:-)</literal>
             The current version of &man.ppp.8; does
             this, but most other implementations do not.</para>
 
           <para>The easiest method from our side would be to never change
             the tun interface IP number, but instead to change all outgoing
             packets so that the source IP number is changed from the
             interface IP to the negotiated IP on the fly. This is
             essentially what the <literal>iface-alias</literal> option in
             the latest version of &man.ppp.8; is
             doing (with the help of
             &man.libalias.3; and &man.ppp.8;'s <option>-nat</option> switch) -
             it is maintaining all previous interface addresses and NATing
             them to the last negotiated address.</para>
 
           <para>Another alternative (and probably the most reliable) would
             be to implement a system call that changes all bound sockets
             from one IP to another.  &man.ppp.8; would
             use this call to modify the sockets of all existing programs
             when a new IP number is negotiated. The same system call could
             be used by dhcp clients when they are forced to re-bind() their
             sockets.</para>
 
           <para>Yet another possibility is to allow an interface to be
             brought up without an IP number. Outgoing packets would be
             given an IP number of 255.255.255.255 up until the first
             SIOCAIFADDR ioctl is done. This would result in fully binding
             the socket. It would be up to &man.ppp.8;
             to change the source IP number, but only if it is set to
             255.255.255.255, and only the IP number and IP checksum would
             need to change. This, however is a bit of a hack as the kernel
             would be sending bad packets to an improperly configured
             interface, on the assumption that some other mechanism is
             capable of fixing things retrospectively.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-nat-games">
           <para>Why do most games not work with the -nat switch?</para>
         </question>
 
         <answer>
           <para>The reason games and the like do not work when libalias
             is in use is that the machine on the outside will try to open a
             connection or send (unsolicited) UDP packets to the machine on
             the inside. The NAT software does not know that it should send
             these packets to the interior machine.</para>
 
           <para>To make things work, make sure that the only thing
             running is the software that you are having problems with, then
             either run tcpdump on the tun interface of the gateway or
             enable &man.ppp.8; tcp/ip logging (<literal>set log +tcp/ip</literal>)
             on the gateway.</para>
 
           <para>When you start the offending software, you should see
             packets passing through the gateway machine. When something
             comes back from the outside, it will be dropped (that is the
             problem). Note the port number of these packets then shut down
             the offending software. Do this a few times to see if the port
             numbers are consistent. If they are, then the following line in
             the relevant section of <filename>/etc/ppp/ppp.conf</filename> will make the
             software functional:</para>
 
           <programlisting>nat port <replaceable>proto</replaceable> <replaceable>internalmachine</replaceable>:<replaceable>port</replaceable> <replaceable>port</replaceable></programlisting>
 
           <para>where <replaceable>proto</replaceable> is either
             <literal>tcp</literal> or <literal>udp</literal>,
             <replaceable>internalmachine</replaceable> is the machine that
             you want the packets to be sent to and
             <replaceable>port</replaceable> is the destination port number
             of the packets.</para>
 
           <para>You will not be able to use the software on other machines
             without changing the above command, and running the software
             on two internal machines at the same time is out of the question
             - after all, the outside world is seeing your entire internal
             network as being just a single machine.</para>
 
           <para>If the port numbers are not consistent, there are three
             more options:</para>
 
           <orderedlist>
             <listitem>
           <para>Submit support in
             libalias. Examples of <quote>special cases</quote> can be found
             in <filename>/usr/src/lib/libalias/alias_*.c</filename>
             (<filename>alias_ftp.c</filename> is a good prototype). This
             usually involves reading certain recognised outgoing packets,
             identifying the instruction that tells the outside machine to
             initiate a connection back to the internal machine on a
             specific (random) port and setting up a <quote>route</quote> in
             the alias table so that the subsequent packets know where to
             go.</para>
 
           <para>This is the most difficult solution, but it is the best
             and will make the software work with multiple machines.</para>
             </listitem>
 
             <listitem>
               <para>Use a proxy.  The
             application may support socks5 for example, or (as in the
             <quote>cvsup</quote> case) may have a <quote>passive</quote>
             option that avoids ever requesting that the peer open
             connections back to the local machine.</para>
             </listitem>
 
             <listitem>
           <para>Redirect everything to
             the internal machine using <literal>nat addr</literal>.  This
             is the sledge-hammer approach.</para>
             </listitem>
           </orderedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="useful-port-numbers">
           <para>Has anybody made a list of useful port numbers?</para>
         </question><answer>
 
           <para>Not yet, but this is intended to grow into such a list
             (if any interest is shown).  In each example,
             <replaceable>internal</replaceable> should be replaced with
             the IP number of the machine playing the game.</para>
 
           <itemizedlist>
             <listitem>
               <para><application>Asheron's Call</application></para>
 
               <para><literal>nat port udp
                 <replaceable>internal</replaceable>
                 :65000 65000</literal></para>
 
               <para>Manually change the port number within the game to
                 65000. If you have got a number of machines that you wish
                 to play on assign a unique port number for each (i.e.
                 65001, 65002, etc) and add a <literal>nat port</literal>
                 line for each one.</para>
             </listitem>
 
             <listitem>
               <para><application>Half Life</application></para>
 
               <para><literal>nat port udp
                 <replaceable>internal</replaceable>:27005
                 27015</literal></para>
             </listitem>
 
             <listitem>
               <para><application>PCAnywhere 8.0</application></para>
 
               <para><literal>nat port udp
                 <replaceable>internal</replaceable>:5632
                 5632</literal></para>
 
               <para><literal>nat port tcp
                 <replaceable>internal</replaceable>:5631
                 5631</literal></para>
             </listitem>
 
             <listitem>
               <para><application>Quake</application></para>
 
               <para><literal>nat port udp
                 <replaceable>internal</replaceable>:6112
                 6112</literal></para>
 
               <para>Alternatively, you may want to take a look at <ulink
                 URL="http://www.battle.net/support/proxy/">
                 www.battle.net</ulink> for Quake proxy support.</para>
             </listitem>
 
             <listitem>
               <para><application>Quake 2</application></para>
 
               <para><literal>nat port udp
                 <replaceable>internal</replaceable>:27901
                 27910</literal></para>
               <para><literal>nat port udp
                 <replaceable>internal</replaceable>:60021
                 60021</literal></para>
               <para><literal>nat port udp
                 <replaceable>internal</replaceable>:60040
                 60040</literal></para>
             </listitem>
 
             <listitem>
               <para><application>Red Alert</application></para>
 
               <para><literal>nat port udp
                 <replaceable>internal</replaceable>:8675
                 8675</literal></para>
 
               <para><literal>nat port udp
                 <replaceable>internal</replaceable>:5009
                 5009</literal></para>
             </listitem>
           </itemizedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="fcs-errors">
           <para>What are FCS errors?</para>
         </question>
 
         <answer>
           <para>FCS stands for <literal>F</literal>rame
             <literal>C</literal>heck
             <literal>S</literal>equence.  Each PPP packet
             has a checksum attached to ensure that the data being
             received is the data being sent.  If the FCS of an incoming
             packet is incorrect, the packet is dropped and the HDLC FCS
             count is increased.  The HDLC error values can be displayed
             using the <literal>show hdlc</literal> command.</para>
 
           <para>If your link is bad (or if your serial driver is dropping
             packets), you will see the occasional FCS error.  This is not
             usually worth worrying about although it does slow down the
             compression protocols substantially.  If you have an external
             modem, make sure your cable is properly shielded from
             interference - this may eradicate the problem.</para>
 
           <para>If your link freezes as soon as you have connected and you
             see a large number of FCS errors, this may be because your link
             is not 8 bit clean. Make sure your modem is not using software
             flow control (XON/XOFF). If your datalink
             <emphasis>must</emphasis> use software flow control, use the
             command <literal>set accmap 0x000a0000</literal> to tell
             &man.ppp.8; to escape the <literal>^Q</literal> and
             <literal>^S</literal> characters.</para>
 
           <para>Another reason for seeing too many FCS errors may be that
             the remote end has stopped talking <acronym>PPP</acronym>. You
             may want to enable <literal>async</literal> logging at this
             point to determine if the incoming data is actually a login or
             shell prompt. If you have a shell prompt at the remote end,
             it is possible to terminate &man.ppp.8; without dropping the line by
             using the <literal>close lcp</literal> command (a following
             <literal>term</literal> command will reconnect you to the shell
             on the remote machine.</para>
 
           <para>If nothing in your log file indicates why the link might
             have been terminated, you should ask the remote administrator
             (your ISP?) why the session was terminated.</para>
         </answer>
       </qandaentry>
 
       <qandaentry id=PPPoEwithNAT>
         <question id="macos-win98-pppoe-freeze">
           <para>Why do MacOS and Windows 98 connections freeze when
             running PPPoE on the gateway?</para>
         </question>
 
         <answer>
           <para>Thanks to Michael Wozniak
             <email>mwozniak@netcom.ca</email> for figuring this out and
             Dan Flemming <email>danflemming@mac.com</email> for the Mac
             solution:</para>
 
           <para>This is due to what is called a <quote>Black Hole</quote>
             router.  MacOS and Windows 98 (and maybe other Microsoft OSs)
             send TCP packets with a requested segment size too big to fit
             into a PPPoE frame (MTU is 1500 by default for Ethernet)
             <emphasis>and</emphasis> have the <quote>do not
             fragment</quote> bit set (default of TCP) and the Telco router
             is not sending ICMP <quote>must fragment</quote> back to the
             www site you are trying to load.  (Alternatively, the router is
             sending the ICMP packet correctly, but the firewall at the www
             site is dropping it.)  When the www server is sending
             you frames that do not fit into the PPPoE pipe the Telco router
             drops them on the floor and your page does not load (some
             pages/graphics do as they are smaller than a MSS.) This seems
             to be the default of most Telco PPPoE configurations (if only
             they knew how to program a router... sigh...)</para>
 
           <para>One fix is to use regedit on your 95/98 boxes to add the
             following registry entry...</para>
 
           <programlisting>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\NetTrans\0000\MaxMTU</programlisting>
 
           <para>It should be a string with a value <quote>1436</quote>, as
             some ADSL routers are reported to be unable to deal with packets
             larger than this.  This registry key has been changed to
             <literal>Tcpip\Parameters\Interfaces\<replaceable>ID for adapter</replaceable>\MTU</literal>
             in Windows 2000 and becomes a DWORD.</para>
 
           <para>Refer to the Microsoft Knowledge Base documents <ulink
             url="http://support.microsoft.com/support/kb/articles/Q158/4/74.asp">Q158474
             - Windows TCPIP Registry Entries</ulink> and <ulink
             url="http://support.microsoft.com/support/kb/articles/Q120/6/42.asp">Q120642
             - TCPIP & NBT Configuration Parameters for Windows
             NT</ulink> for more information on changing Windows MTU to
             work with a NAT router.</para>
 
           <para>Another regedit possibility under Windows 2000 is to
             set the
             <literal>Tcpip\Parameters\Interfaces\<replaceable>ID for
             adapter</replaceable>\EnablePMTUBHDetect</literal> DWORD
             to 1 as mentioned in the Microsoft document 120642
             mentioned above.</para>
 
           <para>Unfortunately, MacOS does not provide an interface for
             changing TCP/IP settings. However, there is commercial software
             available, such as OTAdvancedTuner (OT for OpenTransport, the
             MacOS TCP/IP stack) by <ulink
             URL="http://www.softworks.com/">Sustainable Softworks</ulink>,
             that will allow users to customize TCP/IP settings. MacOS NAT
             users should select <literal>ip_interface_MTU</literal> from
             the drop-down menu, enter <literal>1450</literal> instead of
             <literal>1500</literal> in the box, click the box next to
             <literal>Save as Auto Configure</literal>, and click
             <literal>Make Active</literal>.</para>
 
           <para>The latest version of &man.ppp.8;
             (2.3 or greater) has an <command>enable tcpmssfixup</command>
             command that will automatically adjust the MSS to an appropriate
             value.  This facility is enabled by default.  If you are stuck
             with an older version of &man.ppp.8;, you
             may want to look at the <application>tcpmssd</application>
             port.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="desperation">
           <para>None of this helps - I am desperate!  What can I do?</para>
         </question>
 
         <answer>
           <para>If all else fails, send as much information as you can,
             including your config files, how you are starting
             &man.ppp.8;, the relevant parts of your
             log file and the output of the <command>netstat -rn</command>
             command (before and after connecting) to the &a.questions; or
             the <ulink URL="news:comp.unix.bsd.freebsd.misc">
             comp.unix.bsd.freebsd.misc</ulink> news group, and someone
             should point you in the right direction.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="serial">
     <title>Serial Communications</title>
 
     <para>This section answers common questions about serial
       communications with FreeBSD.  PPP and SLIP are covered in the
       <xref linkend="networking" remap="Networking"> section.</para>
 
 
     <qandaset>
       <qandaentry>
         <question id="found-serial">
           <para>How do I tell if FreeBSD found my serial ports?</para>
         </question>
 
         <answer>
           <para>As the FreeBSD kernel boots, it will probe for the serial
             ports in your system for which the kernel was configured.
             You can either watch your system closely for the messages it
             prints or run the command</para>
 
           <screen>&prompt.user; <userinput>dmesg | grep sio</userinput></screen>
 
           <para>after your system is up and running.</para>
 
           <para>Here is some example output from the above command:</para>
 
           <programlisting>sio0 at 0x3f8-0x3ff irq 4 on isa
 sio0: type 16550A
 sio1 at 0x2f8-0x2ff irq 3 on isa
 sio1: type 16550A</programlisting>
 
           <para>This shows two serial ports.  The first is on irq 4, is
             using port address <literal>0x3f8</literal>, and has a
             16550A-type UART chip.  The second uses the same kind of chip
             but is on irq 3 and is at port address <literal>0x2f8</literal>.
             Internal modem cards are treated just like serial ports---except
             that they always have a modem <quote>attached</quote> to the
             port.</para>
 
           <para>The <filename>GENERIC</filename> kernel includes support
             for two serial ports using the same irq and port address
             settings in the above example.  If these settings are not
             right for your system, or if you have added modem cards or have
             more serial ports than your kernel is configured for, just
             reconfigure your kernel.  See section
             <link linkend="make-kernel">about building a kernel</link> for
             more details.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="found-modem">
           <para>How do I tell if FreeBSD found my modem cards?</para>
         </question>
 
         <answer>
           <para>Refer to the answer to the previous question.</para>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="missing-tty0X">
           <para>I just upgraded to 2.0.5 and my
             <devicename>tty0<replaceable>X</replaceable></devicename>
             are missing!  How do I solve this problem?</para>
         </question>
 
         <answer>
           <para>Do not worry, they have been merged with the
             <devicename>ttyd<replaceable>X</replaceable></devicename> devices. You will have to change
             any old configuration files you have, though.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="access-serial-ports">
           <para>How do I access the serial ports on FreeBSD?</para>
         </question>
 
         <answer>
           <para>The third serial port,
             <devicename>sio2</devicename>
             (see &man.sio.4;, known as COM3 in DOS), is on <devicename>/dev/cuaa2</devicename>
             for dial-out devices, and on <devicename>/dev/ttyd2</devicename>
             for dial-in devices.  What is the difference between these two
             classes of devices?</para>
 
           <para>You use <devicename>ttyd<replaceable>X</replaceable></devicename> for dial-ins.  When
             opening <devicename>/dev/ttyd<replaceable>X</replaceable></devicename> in blocking mode, a
             process will wait for the corresponding
             <devicename>cuaa<replaceable>X</replaceable></devicename> device to become inactive, and then
             wait for the carrier detect line to go active.  When you open
             the <devicename>cuaa<replaceable>X</replaceable></devicename> device, it makes sure the serial
             port is not already in use by the <devicename>ttyd<replaceable>X</replaceable></devicename>
             device. If the port is available, it <quote>steals</quote> it
             from the <devicename>ttyd<replaceable>X</replaceable></devicename> device. Also, the
             <devicename>cuaa<replaceable>X</replaceable></devicename> device does not care about carrier
             detect. With this scheme and an auto-answer modem, you can have
             remote users log in and you can still dial out with the same
             modem and the system will take care of all the
             conflicts.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="enable-multiport-serial">
           <para>How do I enable support for a multiport serial
             card?</para>
         </question>
 
         <answer>
           <para>Again, the section on kernel configuration provides
             information about configuring your kernel. For a multiport
             serial card, place an &man.sio.4; line
             for each serial port on the card in the kernel configuration
             file. But place the irq and vector specifiers on only one of
             the entries. All of the ports on the card should share one irq.
             For consistency, use the last serial port to specify the irq.
             Also, specify the <literal>COM_MULTIPORT</literal>
             option.</para>
 
           <para>The following example is for an AST 4-port serial card on
             irq 7:</para>
 
           <programlisting>options "COM_MULTIPORT"
 device sio4 at isa? port 0x2a0 tty flags 0x781
 device sio5 at isa? port 0x2a8 tty flags 0x781
 device sio6 at isa? port 0x2b0 tty flags 0x781
 device sio7 at isa? port 0x2b8 tty flags 0x781 irq 7 vector siointr</programlisting>
 
           <para>The flags indicate that the master port has minor number 7
             (<literal>0x700</literal>), diagnostics enabled during probe
             (<literal>0x080</literal>), and all the ports share an irq
             (<literal>0x001</literal>).</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="multiport-serial-share-irq">
           <para>Can FreeBSD handle multiport serial cards sharing
             irqs?</para>
         </question>
 
         <answer>
           <para>Not yet. You will have to use a different irq for each
             card.</para>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="default-serial-params">
           <para>Can I set the default serial parameters for a
             port?</para>
         </question>
 
         <answer>
           <para>The <devicename>ttyd<replaceable>X</replaceable></devicename> (or
             <devicename>cuaa<replaceable>X</replaceable></devicename>) device is the regular device
             you will want to open for your applications.  When a process
             opens the device, it will have a default set of terminal I/O
             settings. You can see these settings with the command</para>
 
           <screen>&prompt.root; <userinput>stty -a -f /dev/ttyd1</userinput></screen>
 
           <para>When you change the settings to this device, the settings
             are in effect until the device is closed.  When it is reopened,
             it goes back to the default set.  To make changes to the
             default set, you can open and adjust the settings of the
             <quote>initial state</quote> device. For example, to turn on
             <acronym>CLOCAL</acronym> mode, 8 bits, and
             <acronym>XON/XOFF</acronym> flow control by default for
             ttyd5, do:</para>
 
           <screen>&prompt.root; <userinput>stty -f /dev/ttyid5 clocal cs8 ixon ixoff</userinput></screen>
 
           <para>A good place to do this is in
             <filename>/etc/rc.serial</filename>. Now, an application will
             have these settings by default when it opens
             <filename>ttyd5</filename>.  It can still change these settings
             to its liking, though.</para>
 
           <para>You can also prevent certain settings from being changed
             by an application by making adjustments to the
             <quote>lock state</quote> device.  For example, to lock the
             speed of <devicename>ttyd5</devicename> to 57600 bps, do</para>
 
           <screen>&prompt.root; <userinput>stty -f /dev/ttyld5 57600</userinput></screen>
 
           <para>Now, an application that opens <devicename>ttyd5</devicename>
             and tries to change the speed of the port will be stuck with
           57600 bps.</para>
 
           <para>Naturally, you should make the initial state and lock state
             devices writable only by <username>root</username>. The
             &man.MAKEDEV.8;
             script does <emphasis>NOT</emphasis> do this when it creates the
             device entries.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="enable-dialup">
           <para>How can I enable dialup logins on my modem?</para>
         </question>
 
         <answer>
           <para>So you want to become an Internet service provider, eh?
             First, you will need one or more modems that can auto-answer.
             Your modem will need to assert carrier-detect when it detects a
             carrier and not assert it all the time. It will need to hang up
             the phone and reset itself when the data terminal ready
             (<acronym>DTR</acronym>) line goes from on to off. It should
             probably use <filename>RTS/CTS</filename> flow control or no
             local flow control at all. Finally, it must use a constant
             speed between the computer and itself, but (to be nice to your
             callers) it should negotiate a speed between itself and the
             remote modem.</para>
 
           <para>For many Hayes command-set--compatible modems, this
             command will make these settings and store them in
             nonvolatile memory:</para>
 
           <programlisting>AT &amp;C1 &amp;D3 &amp;K3 &amp;Q6 S0=1 &amp;W</programlisting>
 
           <para>See the section <link linkend="direct-at">on sending AT
             commands</link> below for information on how to make these
             settings without resorting to an MS-DOS terminal program.</para>
 
           <para>Next, make an entry in
             <filename>/etc/ttys</filename> (see &man.ttys.5;) for the modem.  This file lists all the ports
             on which the operating system will await logins.  Add a line
             that looks something like this:</para>
 
           <programlisting>ttyd1 "/usr/libexec/getty std.57600" dialup on insecure</programlisting>
 
           <para>This line indicates that the second serial port
             (<devicename>/dev/ttyd1</devicename>) has a modem connected
             running at 57600 bps and no parity
             (<literal>std.57600</literal>, which comes from the file
             <filename>/etc/gettytab</filename>, see &man.gettytab.5;).
             The terminal type for this port is <literal>dialup</literal>.
             The port is <literal>on</literal> and is
             <literal>insecure</literal>---meaning root logins on the port
             are not allowed. For dialin ports like this one, use the
             <devicename>ttyd<replaceable>X</replaceable></devicename> entry.</para>
 
           <para>It is common practice to use <literal>dialup</literal> as
             the terminal type. Many users set up in their <filename>.profile</filename> or
             <filename>.login</filename> files a prompt for the actual terminal type if the
             starting type is dialup. The example shows the port as
             insecure. To become root on this port, you have to login as a
             regular user, then &man.su.1; to become
             <username>root</username>. If you use <literal>secure</literal>
             then <username>root</username> can login in directly.</para>
 
           <para>After making modifications to
             <filename>/etc/ttys</filename>, you need to send a hangup or
             <acronym>HUP</acronym> signal to the
             &man.init.8; process:</para>
 
           <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>
 
           <para>This forces the &man.init.8; process to reread
             <filename>/etc/ttys</filename>.  The init process will then start getty
             processes on all <literal>on</literal> ports.  You can find
             out if logins are available for your port by typing</para>
 
           <screen>&prompt.user; <userinput>ps -ax | grep '[t]tyd1'</userinput></screen>
 
           <para>You should see something like:</para>
 
           <programlisting>747 ??  I      0:00.04 /usr/libexec/getty std.57600 ttyd1</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="dumb-terminal">
           <para>How can I connect a dumb terminal to my FreeBSD
             box?</para>
         </question>
 
         <answer>
           <para>If you are using another computer as a terminal into your
             FreeBSD system, get a null modem cable to go between the two
             serial ports.  If you are using an actual terminal, see its
             accompanying instructions.</para>
 
           <para>Then, modify
             <filename>/etc/ttys</filename> (see &man.ttys.5;), like above.  For example, if you are
             hooking up a WYSE-50 terminal to the fifth serial port,
             use an entry like this:</para>
 
           <programlisting>ttyd4 "/usr/libexec/getty std.38400" wyse50 on secure</programlisting>
 
           <para>This example shows that the port on
             <devicename>/dev/ttyd4</devicename> has a wyse50 terminal
             connected at 38400 bps with no parity
             (<literal>std.38400</literal> from
             <filename>/etc/gettytab</filename>, see &man.gettytab.5;) and <username>root</username> logins are
             allowed (<literal>secure</literal>).</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="cannot-tip">
           <para>Why can I not run <command>tip</command> or
             <command>cu</command>?</para>
         </question>
 
         <answer>
           <para>On your system, the programs &man.tip.1;
             and &man.cu.1;
             are probably executable only by
             <username>uucp</username>
             and group <groupname>dialer</groupname>.  You can use the group
             <groupname>dialer</groupname> to control who has access to your
             modem or remote systems.  Just add yourself to group
             dialer.</para>
 
           <para>Alternatively, you can let everyone on your system
             run &man.tip.1; and &man.cu.1; by
             typing:</para>
 
           <screen>&prompt.root; <userinput>chmod 4511 /usr/bin/cu</userinput>
 &prompt.root; <userinput>chmod 4511 /usr/bin/tip</userinput></screen>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="hayes-unsupported">
           <para>My stock Hayes modem is not supported---what
             can I do?</para>
         </question>
 
         <answer>
           <para>Actually, the man page for &man.tip.1; is
             out of date.  There is a generic Hayes dialer already built in.
             Just use <literal>at=hayes</literal> in your
             <filename>/etc/remote</filename> (see &man.remote.5;) file.</para>
 
           <para>The Hayes driver is not smart enough to recognize some of
             the advanced features of newer modems---messages like
             <literal>BUSY</literal>, <literal>NO DIALTONE</literal>, or
             <literal>CONNECT 115200</literal> will just confuse it. You
             should turn those messages off when you use &man.tip.1;
             (using <literal>ATX0&amp;W</literal>).</para>
 
           <para>Also, the dial timeout for &man.tip.1; is 60
             seconds.  Your modem should use something less, or else tip
             will think there is a communication problem.  Try
             <literal>ATS7=45&amp;W</literal>.</para>
 
           <para>Actually, as shipped &man.tip.1; does not yet
             support it fully. The solution is to edit the file
             <filename>tipconf.h</filename> in the directory
             <filename>/usr/src/usr.bin/tip/tip</filename>.  Obviously you
             need the source distribution to do this.</para>
 
           <para>Edit the line <literal>#define HAYES 0</literal>
             to <literal>#define HAYES 1</literal>. Then
             <command>make</command> and <command>make install</command>.
             Everything works nicely after that.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="direct-at">
           <para>How am I expected to enter these AT commands?</para>
         </question>
 
         <answer>
           <para>Make what is called a <quote>direct</quote> entry in your
             <filename>/etc/remote</filename> file (see &man.remote.5;).  For example, if your modem is hooked
             up to the first serial port, <devicename>/dev/cuaa0</devicename>,
             then put in the following line:</para>
 
           <programlisting>cuaa0:dv=/dev/cuaa0:br#19200:pa=none</programlisting>
 
           <para>Use the highest bps rate your modem supports in the br
             capability.  Then, type
             <command>tip <devicename>cuaa0</devicename></command> (see &man.tip.1;)
             and you will be connected to your modem.</para>
 
           <para>If there is no <devicename>/dev/cuaa0</devicename> on your
             system, do this:</para>
 
           <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV cuaa0</userinput></screen>
 
           <para>Or use cu as <username>root</username> with the following command:</para>
 
           <screen>&prompt.root; <userinput>cu -l<replaceable>line</replaceable> -s<replaceable>speed</replaceable></userinput></screen>
 
           <para>with <replaceable>line</replaceable> being the serial port (e.g.
             <devicename>/dev/cuaa0</devicename>) and <replaceable>speed</replaceable> being the speed
             (e.g.<literal>57600</literal>).  When you are done entering
             the AT commands hit <literal>~.</literal> to exit.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="gt-failure">
           <para>Why does the <literal>&lt;@&gt;</literal> sign for the pn
             capability not work?</para></question><answer>
 
           <para>The <literal>&lt;@&gt;</literal> sign in the phone number
             capability tells tip to look in
             <filename>/etc/phones</filename> for a phone number.  But the
             <literal>&lt;@&gt;</literal> sign is also a special character
             in capability files like <filename>/etc/remote</filename>.
             Escape it with a backslash:</para>
 
           <programlisting>pn=\@</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="dial-command-line">
           <para>How can I dial a phone number on the command
             line?</para>
         </question><answer>
 
           <para>Put what is called a <quote>generic</quote> entry in your
             <filename>/etc/remote</filename> file (see &man.remote.5;).  For example:</para>
 
           <programlisting>tip115200|Dial any phone number at 115200 bps:\
         :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du:
 tip57600|Dial any phone number at 57600 bps:\
         :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:</programlisting>
 
           <para>Then you can do something like <command>tip -115200
             5551234</command>.  If you prefer &man.cu.1;
             over
             &man.tip.1;, use a generic cu entry:</para>
 
           <programlisting>cu115200|Use cu to dial any number at 115200bps:\
         :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:</programlisting>
 
           <para>and type <command>cu 5551234 -s 115200</command>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="set-bps">
           <para>Do I have to type in the bps rate every time I do
             that?</para>
         </question><answer>
 
           <para>Put in an entry for <literal>tip1200</literal> or
             <literal>cu1200</literal>, but go ahead and use whatever bps
             rate is appropriate with the br capability.
             &man.tip.1;
             thinks a good default is 1200 bps which is why it looks for
             a <literal>tip1200</literal> entry. You do not have to use 1200
             bps, though.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="terminal-server">
           <para>How can I more easily access a number of hosts through a
             terminal server?</para>
         </question>
 
         <answer>
           <para>Rather than waiting until you are connected and typing
             <literal>CONNECT <replaceable>host</replaceable></literal>
             each time, use tip's <literal>cm</literal> capability. For
             example, these entries in
             <filename>/etc/remote</filename> (see &man.remote.5;):</para>
 
           <programlisting>pain|pain.deep13.com|Forrester's machine:\
         :cm=CONNECT pain\n:tc=deep13:
 muffin|muffin.deep13.com|Frank's machine:\
         :cm=CONNECT muffin\n:tc=deep13:
 deep13:Gizmonics Institute terminal server:\
         :dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234:</programlisting>
 
           <para>will let you type <command>tip pain</command> or
             <command>tip muffin</command> to connect to the hosts
             <hostid>pain</hostid> or <hostid>muffin</hostid>; and
             <command>tip deep13</command> to get to the terminal
             server.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="tip-multiline">
           <para>Can tip try more than one line for each site?</para>
         </question>
 
         <answer>
           <para>This is often a problem where a university has several
             modem lines and several thousand students trying to use
             them...</para>
 
           <para>Make an entry for your university in
             <filename>/etc/remote</filename> (see &man.remote.5;) and use <literal>&lt;\@&gt;</literal> for
             the <literal>pn</literal> capability:</para>
 
           <programlisting>big-university:\
         :pn=\@:tc=dialout
 dialout:\
         :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:</programlisting>
 
           <para>Then, list the phone numbers for the university in
             <filename>/etc/phones</filename> (see &man.phones.5;):</para>
 
           <programlisting>big-university 5551111
 big-university 5551112
 big-university 5551113
 big-university 5551114</programlisting>
 
           <para>&man.tip.1;
             will try each one in the listed order, then give
             up.  If you want to keep retrying, run &man.tip.1;
             in a while loop.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="multi-controlp">
           <para>Why do I have to hit CTRL+P twice to send CTRL+P
             once?</para>
         </question>
 
         <answer>
           <para>CTRL+P is the default <quote>force</quote> character,
             used to tell &man.tip.1;
             that the next character is literal data.  You can set the
             force character to any other character with the
             <literal>~s</literal> escape, which means <quote>set a
             variable</quote>.</para>
 
           <para>Type <literal>~sforce=<replaceable>single-char
             </replaceable></literal> followed by a newline.
             <replaceable>single-char</replaceable> is any single character.
             If you leave out <replaceable>single-char</replaceable>,
             then the force character is the nul character, which you can
             get by typing CTRL+2 or CTRL+SPACE.  A pretty good value for
             <replaceable>single-char</replaceable> is SHIFT+CTRL+6, which
             I have seen only used on some terminal servers.</para>
 
           <para>You can have the force character be whatever you want by
             specifying the following in your
             <filename>$HOME/.tiprc</filename> file:</para>
 
           <programlisting>force=<replaceable>single-char</replaceable></programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="uppercase">
           <para>Why is everything I type suddenly in UPPER CASE?</para>
         </question>
 
         <answer>
           <para>You must have pressed CTRL+A, &man.tip.1;
             <quote>raise character</quote>, specially
             designed for people with broken caps-lock keys. Use
             <literal>~s</literal> as above and set the variable
             <quote>raisechar</quote> to something reasonable.  In fact,
             you can set it to the same as the force character, if you
             never expect to use either of these features.</para>
 
           <para>Here is a sample .tiprc file perfect for Emacs users who
             need to type CTRL+2 and CTRL+A a lot:</para>
 
           <programlisting>force=^^
 raisechar=^^</programlisting>
 
 <para>The ^^ is SHIFT+CTRL+6.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="tip-filetransfer">
           <para>How can I do file transfers with
             <command>tip</command>?</para>
         </question>
 
         <answer>
           <para>If you are talking to another Unix system, you can send
             and receive files with <literal>~p</literal> (put) and
             <literal>~t</literal> (take).  These commands run
             &man.cat.1; and
             &man.echo.1; on the remote system to accept and send files.
             The syntax is:</para>
 
           <programlisting>~p &lt;local-file&gt; [&lt;remote-file&gt;]
 ~t &lt;remote-file&gt; [&lt;local-file&gt;]</programlisting>
 
           <para>There is no error checking, so you probably should use
             another protocol, like zmodem.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="zmodem-tip">
           <para>How can I run zmodem with
             <application>tip</application>?</para>
         </question>
 
         <answer>
           <para>First, install one of the zmodem programs from the
             ports collection (such as one of the two from the comms
             category, <application>lrzsz</application> or
             <application>rzsz</application>.</para>
 
           <para>To receive files, start the sending program on the
             remote end.  Then, press enter and type
             <literal>~C rz</literal> (or <literal>~C lrz</literal> if you
             installed <application>lrzsz</application>) to begin
             receiving them locally.</para>
 
           <para>To send files, start the receiving program on the remote
             end.  Then, press enter and type
             <literal>~C sz <replaceable>files</replaceable></literal>
             (or <literal>~C lsz <replaceable>files</replaceable></literal>)
             to send them to the remote system.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="cannot-find-serial">
           <para>Why does FreeBSD not find my serial ports, even
             when the settings are correct?</para>
         </question>
 
         <answer>
           <para>Motherboards and cards with Acer UARTs do not probe
             properly under the FreeBSD sio probe.  Obtain a patch from
             <ulink URL="http://www.lemis.com/serial-port-patch.html">
             www.lemis.com</ulink> to fix your problem.</para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="misc">
     <title>Miscellaneous Questions</title>
 
     <qandaset>
       <qandaentry>
         <question id="more-swap">
           <para>FreeBSD uses far more swap space than Linux. Why?</para>
         </question>
 
         <answer>
           <para>FreeBSD only appears to use more swap than Linux.  In
             actual fact, it does not. The main difference between FreeBSD
             and Linux in this regard is that FreeBSD will proactively move
             entirely idle, unused pages of main memory into swap in order
             to make more main memory available for active use. Linux tends
             to only move pages to swap as a last resort. The perceived
             heavier use of swap is balanced by the more efficient use of
             main memory.</para>
 
           <para>Note that while FreeBSD is proactive in this regard, it
             does not arbitrarily decide to swap pages when the system is
             truly idle.  Thus you will not find your system all paged
             out when you get up in the morning after leaving it idle
             overnight.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="top-freemem">
           <para>Why does <command>top</command> show very little free memory even
             when I have very few programs running?</para>
         </question>
 
         <answer>
           <para>The simple answer is that free memory is wasted
             memory.  Any memory that your programs do not actively
             allocate is used within the FreeBSD kernel as disk
             cache.  The values shown by &man.top.1; labeled as
             <literal>Inact</literal>, <literal>Cache</literal>, and
             <literal>Buf</literal> are all cached data at different
             aging levels.  This cached data means the system does
             not have to access a slow disk again for data it has
             accessed recently, thus increasing overall performance.
             In general, a low value shown for <literal>Free</literal>
             memory in &man.top.1; is good, provided it is not
             <emphasis>very</emphasis> low.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="aout-elf">
           <para>Why use (what are) a.out and ELF executable
             formats?</para>
         </question>
 
         <answer>
           <para>To understand why FreeBSD uses the
             <filename>ELF</filename> format, you must first know a little
             about the 3 currently <quote>dominant</quote> executable
             formats for Unix:</para>
 
             <note>
               <para>Prior to FreeBSD 3.x, FreeBSD used the a.out
                 format.</para>
             </note>
 
             <itemizedlist>
               <listitem>
                 <para>&man.a.out.5;</para>
 
                 <para>The oldest and <quote>classic</quote> Unix object
                   format.  It uses a short and compact header with a magic
                   number at the beginning that is often used to
                   characterize the format (see
                   &man.a.out.5; for more details).  It contains three
                   loaded segments: .text, .data, and .bss plus a symbol
                   table and a string table.</para>
               </listitem>
 
               <listitem>
                 <para><acronym>COFF</acronym></para>
 
                 <para>The SVR3 object format.  The header now comprises
                   a section table, so you can have more than just .text,
                   .data, and .bss sections.</para>
               </listitem>
 
               <listitem>
                 <para><acronym>ELF</acronym></para>
 
                 <para>The successor to <acronym>COFF</acronym>, featuring
                   Multiple sections and 32-bit or 64-bit possible values.
                   One major drawback: <acronym>ELF</acronym> was also
                   designed with the assumption that there would be only
                   one ABI per system architecture.  That assumption is
                   actually quite incorrect, and not even in the
                   commercial SYSV world (which has at least three ABIs:
                   SVR4, Solaris, SCO) does it hold true.</para>
 
                 <para>FreeBSD tries to work around this problem somewhat
                   by providing a utility for <emphasis>branding</emphasis>
                   a known <acronym>ELF</acronym> executable with
                   information about the ABI it is compliant with.  See the
                   man page for &man.brandelf.1;
                   for more information.</para>
               </listitem>
             </itemizedlist>
 
           <para>FreeBSD comes from the <quote>classic</quote> camp and has
             traditionally used the &man.a.out.5;
             format, a technology tried and proven through
             many generations of BSD releases. Though it has also been
             possible for some time to build and run native
             <acronym>ELF</acronym> binaries (and kernels) on a FreeBSD
             system, FreeBSD initially resisted the <quote>push</quote> to
             switch to <acronym>ELF</acronym> as the default format. Why?
             Well, when the Linux camp made their painful transition to
             <acronym>ELF</acronym>, it was not so much to flee the
             <filename>a.out</filename> executable format as it was their
             inflexible jump-table based shared library mechanism, which
             made the construction of shared libraries very difficult for
             vendors and developers alike. Since the <acronym>ELF</acronym>
             tools available offered a solution to the shared library
             problem and were generally seen as <quote>the way
             forward</quote> anyway, the migration cost was accepted as
             necessary and the transition made.</para>
 
           <para>In FreeBSD's case, our shared library mechanism is based
             more closely on Sun's <application>SunOS</application>-style
             shared library mechanism and, as such, is very easy to use.
             However, starting with 3.0, FreeBSD officially supports
             <acronym>ELF</acronym> binaries as the default format. Even
             though the <filename>a.out</filename> executable format has
             served us well, the GNU people, who author the compiler tools
             we use, have dropped support for the <filename>a.out</filename>
             format. This has forced us to maintain a divergent version of
             the compiler and linker, and has kept us from reaping the
             benefits of the latest GNU development efforts. Also the
             demands of ISO-C++, notably constructors and destructors, has
             also led to native <acronym>ELF</acronym> support in future
             FreeBSD releases.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="binary-formats">
           <para>Yes, but why are there so many different formats?</para>
         </question>
 
         <answer>
           <para>Back in the dim, dark past, there was simple hardware.
             This simple hardware supported a simple, small system. a.out
             was completely adequate for the job of representing binaries on
             this simple system (a PDP-11). As people ported Unix from this
             simple system, they retained the a.out format because it was
             sufficient for the early ports of Unix to architectures like
             the Motorola 68k, VAXen, etc.</para>
 
           <para>Then some bright hardware engineer decided that if he
             could force software to do some sleazy tricks, then he would be
             able to shave a few gates off the design and allow his CPU core
             to run faster. While it was made to work with this new kind of
             hardware (known these days as RISC), <filename>a.out</filename>
             was ill-suited for this hardware, so many formats were
             developed to get to a better performance from this hardware
             than the limited, simple <filename>a.out</filename> format
             could offer. Things like <acronym>COFF</acronym>,
             <acronym>ECOFF</acronym>, and a few obscure others were
             invented and their limitations explored before things seemed to
             settle on <acronym>ELF</acronym>.</para>
 
           <para>In addition, program sizes were getting huge and disks
             (and physical memory) were still relatively small so the
             concept of a shared library was born. The VM system also became
             more sophisticated. While each one of these advancements was
             done using the <filename>a.out</filename> format, its
             usefulness was stretched more and more with each new feature.
             In addition, people wanted to dynamically load things at run
             time, or to junk parts of their program after the init code had
             run to save in core memory and/or swap space. Languages became
             more sophisticated and people wanted code called before main
             automatically. Lots of hacks were done to the
             <filename>a.out</filename> format to allow all of these things
             to happen, and they basically worked for a time. In time,
             <filename>a.out</filename> was not up to handling all these
             problems without an ever increasing overhead in code and
             complexity. While <acronym>ELF</acronym> solved many of these
             problems, it would be painful to switch from the system that
             basically worked. So <acronym>ELF</acronym> had to wait until
             it was more painful to remain with <filename>a.out</filename>
             than it was to migrate to <acronym>ELF</acronym>.</para>
 
           <para>However, as time passed, the build tools that FreeBSD
             derived their build tools from (the assembler and loader
             especially) evolved in two parallel trees. The FreeBSD tree
             added shared libraries and fixed some bugs. The GNU folks that
             originally write these programs rewrote them and added simpler
             support for building cross compilers, plugging in different
             formats at will, etc. Since many people wanted to build cross
             compilers targeting FreeBSD, they were out of luck since the
             older sources that FreeBSD had for as and ld were not up to the
             task. The new gnu tools chain (binutils) does support cross
             compiling, <acronym>ELF</acronym>, shared libraries, C++
             extensions, etc. In addition, many vendors are releasing
             <acronym>ELF</acronym> binaries, and it is a good thing for
             FreeBSD to run them. And if it is running
             <acronym>ELF</acronym> binaries, why bother having
             <filename>a.out</filename> any more? It is a tired old horse
             that has proven useful for a long time, but it is time to turn
             him out to pasture for his long, faithful years of
             service.</para>
 
           <para><acronym>ELF</acronym> is more expressive than a.out and
             will allow more extensibility in the base system. The
             <acronym>ELF</acronym> tools are better maintained, and offer
             cross compilation support, which is important to many people.
             <acronym>ELF</acronym> may be a little slower than a.out, but
             trying to measure it can be difficult. There are also numerous
             details that are different between the two in how they map
             pages, handle init code, etc. None of these are very important,
             but they are differences. In time support for
             <filename>a.out</filename> will be moved out of the GENERIC
             kernel, and eventually removed from the kernel once the need to
             run legacy <filename>a.out</filename> programs is past.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="chmod-symlinks">
           <para>Why will chmod not change the permissions on symlinks?</para>
         </question>
 
         <answer>
           <para>Symlinks do not have permissions, and by default,
             &man.chmod.1; will not follow symlinks to change the
             permissions on the target file. So if you have a file,
             <filename>foo</filename>, and a symlink to that file,
             <filename>bar</filename>, then this command will always
             succeed.</para>
 
           <screen>&prompt.user; <userinput>chmod g-w bar</userinput></screen>
 
           <para>However, the permissions on <filename>foo</filename> will
             not have changed.</para>
 
           <para>You have to use either <option>-H</option> or
             <option>-L</option> together with the <option>-R</option>
             option to make this work.  See the
             &man.chmod.1; and &man.symlink.7;
             man pages for more info.</para>
 
             <warning>
               <para>The <option>-R</option> option does a
                 <acronym>RECURSIVE</acronym>
                 &man.chmod.1;.  Be careful about
                 specifying directories or symlinks to directories to
                 &man.chmod.1;.  If you want to
                 change the permissions of a directory referenced by a
                 symlink, use &man.chmod.1;
                 without any options and follow the symlink
                 with a trailing slash (<filename>/</filename>).  For
                 example, if <filename>foo</filename> is a symlink to
                 directory <filename>bar</filename>, and you want to change
                 the permissions of <filename>foo</filename> (actually
                 <filename>bar</filename>), you would do something
                 like:</para>
 
               <screen>&prompt.user; <userinput>chmod 555 foo/</userinput></screen>
 
               <para>With the trailing slash, &man.chmod.1;
                 will follow the symlink,
                 <filename>foo</filename>, to change the permissions of the
                 directory, <filename>bar</filename>.</para>
             </warning>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="login-8char">
           <para>Why are login names restricted to 8 characters or less
             in FreeBSD 2.2.X and earlier?</para>
         </question>
 
         <answer>
 
           <para>You would think it would be easy enough to change
             <literal>UT_NAMESIZE</literal> and rebuild the whole world,
             and everything would just work. Unfortunately there are often
             scads of applications and utilities (including system tools)
             that have hard-coded small numbers (not always
             <literal>8</literal> or <literal>9</literal>, but oddball ones
             like <literal>15</literal> and <literal>20</literal>) in
             structures and buffers. Not only will this get you log files
             which are trashed (due to variable-length records getting
             written when fixed records were expected), but it can break
             Suns NIS clients and potentially cause other problems in
             interacting with other Unix systems.</para>
 
           <para>In FreeBSD 3.0 and later, the maximum name length has
             been increased to 16 characters and those various utilities
             with hard-coded name sizes have been found and fixed. The fact
             that this touched so many areas of the system is why, in fact,
             the change was not made until 3.0.</para>
 
           <para>If you are absolutely confident in your ability to find
             and fix these sorts of problems for yourself when and if they
             pop up, you can increase the login name length in earlier
             releases by editing <filename>/usr/include/utmp.h</filename> and changing
             UT_NAMESIZE accordingly. You must also update MAXLOGNAME in
             <filename>/usr/include/sys/param.h</filename> to match the UT_NAMESIZE change.
             Finally, if you build from sources, do not forget that
             /usr/include is updated each time! Change the appropriate files
             in /usr/src/.. instead.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="dos-binaries">
           <para>Can I run DOS binaries under FreeBSD?</para>
         </question>
 
         <answer>
           <para>Yes, starting with version 3.0 you can using BSDI's
             <application>doscmd</application> DOS emulation which has
             been integrated and enhanced. Send mail to the &a.emulation;
             if you are interested in joining this ongoing effort!</para>
 
           <para>For pre-3.0 systems, there is a neat utility called
             <application>pcemu</application> in the ports collection which emulates an 8088
             and enough BIOS services to run DOS text mode applications.
             It requires the X Window System (provided as XFree86).</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="translation">
           <para>What do I need to do to translate a FreeBSD document into
             my native language?</para>
         </question>
 
         <answer>
           <para>See the <ulink url="../fdp-primer/translations.html">
             Translation FAQ</ulink> in the FreeBSD Documentation Project
             Primer.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="freebsd-mail-bounces">
 	  <para>Why does my email to any address at FreeBSD.org bounce?</para>
         </question>
 
         <answer>
 	  <para>The FreeBSD.org mail system rejects mail that is
             either misconfigured or is potential spam.  Your mail
             might bounce for one of the following reasons:</para>
 
 	  <itemizedlist>
 	    <listitem>
               <para>The email is being sent from a known spam
                 domain or IP block.</para>
 
               <para>The FreeBSD mail servers reject email from known
                 spam sources.  If you have service through a company
                 or domain who generates or relays spam, please switch
                 to a service provider who does not.</para>
             </listitem>
 
             <listitem>
               <para>The body of the email only contains HTML.</para>
 
               <para>Mail should be sent in plain text only.  Please
                 configure your mail user agent to send plain
                 text.</para>
             </listitem>
 
             <listitem>
               <para>The mailer at FreeBSD.org cannot resolve the IP
                 address of the connecting host back to a symbolic
                 name.</para>
 
               <para>Working reverse DNS is a standard requirement for
                 accepting mail from a host. Set up reverse DNS for
                 your mail server's IP address.  Many home services
                 (DSL, cable, dialup, etc.) will not give you this
                 option.  In this case, relay your email through your
                 service provider's mail server.</para>
             </listitem>
           </itemizedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="free-account">
           <para>Where can I find a free FreeBSD account?</para>
         </question>
 
         <answer>
           <para>While FreeBSD does not provide open access to any of their
             servers, others do provide open access Unix systems.  The
             charge varies and limited services may be available.</para>
 
           <para><ulink URL="http://www.arbornet.org/">Arbornet,
             Inc</ulink>, also known as M-Net, has been providing open
             access to Unix systems since 1983.  Starting on an Altos
             running System III, the site switched to BSD/OS in 1991.  In
             June of 2000, the site switched again to FreeBSD.  M-Net can be
             accessed via telnet and SSH and provides basic access to the
             entire FreeBSD software suite.  However, network access is
             limited to members and patrons who donate to the system, which
             is run as a non-profit organization.  M-Net also provides an
             bulletin board system and interactive chat.</para>
 
           <para><ulink URL="http://www.grex.org/">Grex</ulink> provides a
             site very similar to M-Net including the same bulletin board
             and interactive chat software.  However, the machine is a Sun
             4M and is running SunOS</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="sup-define">
           <para>What is <command>sup</command>, and how do I use
             it?</para>
         </question>
 
         <answer>
           <para><ulink URL="http://www.FreeBSD.org/cgi/ports.cgi?^sup">
             SUP</ulink> stands for Software Update Protocol, and was
             developed by CMU for keeping their development trees in sync.
             We used it to keep remote sites in sync with our central
             development sources.</para>
 
           <para>SUP is not bandwidth friendly, and has been retired.
             The current recommended method to keep your sources up to
             date is <ulink URL="../handbook/synching.html#CVSUP">
             CVSup</ulink></para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="daemon-name">
           <para>What is the cute little red guy's name?</para>
         </question>
 
         <answer>
           <para>He does not have one, and is just called <quote>the BSD
             daemon</quote>.  If you insist upon using a name, call him
             <quote>beastie</quote>.  Note that <quote>beastie</quote>
             is pronounced <quote>BSD</quote>.</para>
 
           <para>You can learn more about the BSD daemon on his <ulink
             url="http://www.mckusick.com/beastie/index.html">home
             page</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="use-beastie">
           <para>Can I use the BSD daemon image?</para>
         </question>
 
         <answer>
           <para>Perhaps.  The BSD daemon is copyrighted by Marshall
             Kirk McKusick.  You will want to check his <ulink
             url="http://www.mckusick.com/beastie/mainpage/copyright.html">Statement
             on the Use of the BSD Daemon Figure</ulink> for detailed
             usage terms.</para>
 
           <para>In summary, you are free to use the image in a tasteful
             manner, for personal use, so long as appropriate credit is
             given.  If you want to use him commercially, you must
             contact Kirk McKusick.  More details are available on the
             <ulink
             url="http://www.mckusick.com/beastie/index.html">BSD
             Daemon's home page</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="daemon-images">
           <para>Do you have any BSD daemon images I could use?</para>
         </question>
 
         <answer>
           <para>You will find eps and Xfig drawings under
             <filename>/usr/share/examples/BSD_daemon/</filename>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="define-MFC">
           <para>What does <acronym>MFC</acronym> mean?</para>
         </question>
 
         <answer>
           <para>MFC is an acronym for <quote>Merged From -CURRENT</quote>.
             It is used in the CVS logs to denote when a change was
             migrated from the CURRENT to the STABLE branches.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="define-BSD">
           <para>What does <acronym>BSD</acronym> mean?</para>
         </question>
 
         <answer>
           <para>It stands for something in a secret language that only
             members can know. It does not translate literally but its ok
             to tell you that BSD's translation is something between,
             <quote>Formula-1 Racing Team</quote>, <quote>Penguins are
             tasty snacks</quote>, and <quote>We have a better sense of
             humor than Linux</quote>. :-)</para>
 
           <para>Seriously, BSD is an acronym for <quote>Berkeley
             Software Distribution</quote>, which is the name the
             Berkeley <acronym>CSRG</acronym> (Computer Systems Research
             Group) chose for their Unix distribution way back when.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="define-repocopy">
           <para>What is a repo-copy?</para>
         </question>
 
         <answer>
           <para>A repo-copy (which is a short form of <quote>repository
             copy</quote>) refers to the direct copying of files within
             the CVS repository.</para>
 
           <para>Without a repo-copy, if a file needed to be copied or
             moved to another place in the repository, the committer would
             run <command>cvs add</command> to put the file in its new
             location, and then <command>cvs rm</command> on the old file
             if the old copy was being removed.</para>
 
           <para>The disadvantage of this method is that the history
             (i.e. the entries in the CVS logs) of the file would not be
             copied to the new location. As the FreeBSD Project considers
             this history very useful, a repository copy is often used
             instead. This is a process where one of the repository meisters
             will copy the files directly within the repository, rather than
             using the &man.cvs.1; program.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="bikeshed-painting">
           <para>Why should I care what color the bikeshed is?</para>
         </question>
 
         <answer>
           <para>The really, really short answer is that you should not.
             The somewhat longer answer is that just because you are
             capable of building a bikeshed does not mean you should stop
             others from building one just because you do not like the
             color they plan to paint it.  This is a metaphor indicating
             that you need not argue about every little feature just
             because you know enough to do so.  Some people have
             commented that the amount of noise generated by a change is
             inversely proportional to the complexity of the
             change.</para>
 
           <para>The longer and more complete answer is that after a very
             long argument about whether &man.sleep.1; should take
             fractional second arguments, &a.phk; posted a long
             message entitled <quote><ulink
             url="http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=506636+517178+/usr/local/www/db/text/1999/freebsd-hackers/19991003.freebsd-hackers">A bike
             shed (any colour will do) on greener grass...</ulink></quote>.
             The appropriate portions of that message are quoted
             below.</para>
 
           <blockquote>
             <attribution>&a.phk; on freebsd-hackers, October
               2, 1999</attribution>
 
             <para>
               <quote>What is it about this bike shed?</quote> Some
               of you have asked me.</para>
 
             <para>It is a long story, or rather it is an old story, but
               it is quite short actually.  C. Northcote Parkinson wrote
               a book in the early 1960s, called <quote>Parkinson's
               Law</quote>, which contains a lot of insight into the
               dynamics of management.</para>
 
             <para>[snip a bit of commentary on the book]</para>
 
             <para>In the specific example involving the bike shed, the
               other vital component is an atomic power-plant, I guess
               that illustrates the age of the book.</para>
 
             <para>Parkinson shows how you can go in to the board of
               directors and get approval for building a multi-million or
               even billion dollar atomic power plant, but if you want to
               build a bike shed you will be tangled up in endless
               discussions.</para>
 
             <para>Parkinson explains that this is because an atomic
               plant is so vast, so expensive and so complicated that
               people cannot grasp it, and rather than try, they fall
               back on the assumption that somebody else checked all the
               details before it got this far.  Richard P. Feynmann
               gives a couple of interesting, and very much to the point,
               examples relating to Los Alamos in his books.</para>
 
             <para>A bike shed on the other hand.  Anyone can build one
               of those over a weekend, and still have time to watch the
               game on TV.  So no matter how well prepared, no matter how
               reasonable you are with your proposal, somebody will seize
               the chance to show that he is doing his job, that he is
               paying attention, that he is
               <emphasis>here</emphasis>.</para>
 
             <para>In Denmark we call it <quote>setting your
               fingerprint</quote>.  It is about personal pride and
               prestige, it is about being able to point somewhere and
               say <quote>There!  <emphasis>I</emphasis> did that.</quote>
               It is a strong trait in politicians, but present in most
               people given the chance.  Just think about footsteps in
               wet cement.</para>
           </blockquote>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="funnies">
     <title>The FreeBSD Funnies</title>
 
     <qandaset>
       <qandaentry>
         <question id="very-very-cool">
           <para>How cool is FreeBSD?</para>
         </question>
 
         <answer>
           <para>Q. Has anyone done any temperature testing while
             running FreeBSD? I know Linux runs cooler than DOS, but have
             never seen a mention of FreeBSD. It seems to run really
             hot.</para>
 
           <para>A. No, but we have done numerous taste tests on
             blindfolded volunteers who have also had 250 micrograms of
             LSD-25 administered beforehand. 35% of the volunteers said that
             FreeBSD tasted sort of orange, whereas Linux tasted like purple
             haze. Neither group mentioned any significant variances in
 	    temperature.  We eventually had to throw the
             results of this survey out entirely anyway when we found that
             too many volunteers were wandering out of the room during the
             tests, thus skewing the results.  We think most of the volunteers
             are at Apple now, working on their new <quote>scratch and
             sniff</quote> GUI. It is a funny old business we are in!</para>
 
           <para>Seriously, both FreeBSD and Linux use the
             <acronym>HLT</acronym> (halt) instruction when the system is
             idle thus lowering its energy consumption and therefore the
             heat it generates. Also if you have APM (advanced power
             management) configured, then FreeBSD can also put the CPU into
             a low power mode.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="letmeoutofhere">
           <para>Who is scratching in my memory banks??</para>
         </question>
 
         <answer>
           <para>Q. Is there anything <quote>odd</quote> that FreeBSD
             does when compiling the kernel which would cause the memory to
             make a scratchy sound? When compiling (and for a brief moment
             after recognizing the floppy drive upon startup, as well), a
             strange scratchy sound emanates from what appears to be the
             memory banks.</para>
 
           <para>A. Yes!  You will see frequent references to
             <quote>daemons</quote> in the BSD documentation, and what most
             people do not know is that this refers to genuine, non-corporeal
             entities that now possess your computer. The scratchy sound
             coming from your memory is actually high-pitched whispering
             exchanged among the daemons as they best decide how to deal
             with various system administration tasks.</para>
 
           <para>If the noise gets to you, a good
             <command>fdisk /mbr</command> from DOS will get rid of them,
             but do not be surprised if they react adversely and try to stop
             you. In fact, if at any point during the exercise you hear the
             satanic voice of Bill Gates coming from the built-in speaker,
             take off running and do not ever look back! Freed from the
             counterbalancing influence of the BSD daemons, the twin demons
             of DOS and Windows are often able to re-assert total control
             over your machine to the eternal damnation of your soul.
 	    Now that you know, given a choice you would probably prefer to get
 	    used to the scratchy noises, no?</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="changing-lightbulbs">
           <para>How many FreeBSD hackers does it take to change a
             lightbulb?</para>
         </question>
 
         <answer>
           <para>One thousand, one hundred and seventy-two:</para>
 
           <para>Twenty-three to complain to -CURRENT about the lights
             being out;</para>
 
           <para>Four to claim that it is a configuration problem, and
             that such matters really belong on -questions;</para>
 
           <para>Three to submit PRs about it, one of which is misfiled
             under doc and consists only of "it's dark";</para>
 
           <para>One to commit an untested lightbulb which breaks
             buildworld, then back it out five minutes later;</para>
 
           <para>Eight to flame the PR originators for not including
             patches in their PRs;</para>
 
           <para>Five to complain about buildworld being broken;</para>
 
           <para>Thirty-one to answer that it works for them, and they
             must have cvsupped at a bad time;</para>
 
           <para>One to post a patch for a new lightbulb to -hackers;</para>
 
           <para>One to complain that he had patches for this three years
             ago, but when he sent them to -CURRENT they were just ignored,
             and he has had bad experiences with the PR system; besides,
             the proposed new lightbulb is non-reflexive;</para>
 
           <para>Thirty-seven to scream that lightbulbs do not belong in
             the base system, that committers have no right to do things
             like this without consulting the Community, and WHAT IS
             -CORE DOING ABOUT IT!?</para>
 
           <para>Two hundred to complain about the color of the bicycle
             shed;</para>
 
           <para>Three to point out that the patch breaks &man.style.9;;</para>
 
           <para>Seventeen to complain that the proposed new lightbulb is
             under GPL;</para>
 
           <para>Five hundred and eighty-six to engage in a flame war
             about the comparative advantages of the GPL, the BSD
             license, the MIT license, the NPL, and the personal hygiene
             of unnamed FSF founders;</para>
 
           <para>Seven to move various portions of the thread to -chat
             and -advocacy;</para>
 
           <para>One to commit the suggested lightbulb, even though it
             shines dimmer than the old one;</para>
 
           <para>Two to back it out with a furious flame of a commit
             message, arguing that FreeBSD is better off in the dark than
             with a dim lightbulb;</para>
 
           <para>Forty-six to argue vociferously about the backing out
             of the dim lightbulb and demanding a statement from
             -core;</para>
 
           <para>Eleven to request a smaller lightbulb so it will fit
             their Tamagotchi if we ever decide to port FreeBSD to that
             platform;</para>
 
           <para>Seventy-three to complain about the SNR on -hackers and
             -chat and unsubscribe in protest;</para>
 
           <para>Thirteen to post "unsubscribe", "How do I unsubscribe?",
             or "Please remove me from the list", followed by the usual
             footer;</para>
 
           <para>One to commit a working lightbulb while everybody is too
             busy flaming everybody else to notice;</para>
 
           <para>Thirty-one to point out that the new lightbulb would shine
             0.364% brighter if compiled with TenDRA (although it will have
             to be reshaped into a cube), and that FreeBSD should therefore
             switch to TenDRA instead of EGCS;</para>
 
           <para>One to complain that the new lightbulb lacks
             fairings;</para>
 
           <para>Nine (including the PR originators) to ask
             "what is MFC?";</para>
 
           <para>Fifty-seven to complain about the lights being out two
             weeks after the bulb has been changed.</para>
 
           <para><emphasis>&a.nik; adds:</emphasis></para>
 
           <para><emphasis>I was laughing quite hard at
             this.</emphasis></para>
 
           <para><emphasis>And then I thought,
             "Hang on, shouldn't there be '1 to document it.' in that list somewhere?"</emphasis></para>
 
           <para><emphasis>And then I was enlightened :-)</emphasis></para>
         </answer>
       </qandaentry>
       
       <qandaentry>
         <question id="dev-null">
           <para>Where does data written to <filename>/dev/null</filename>
 	    go?</para>
         </question>
         <answer>
           <para>It goes into a special data sink in the CPU where it
             is converted to heat which is vented through the heatsink
             / fan assembly.  This is why CPU cooling is increasingly
             important; as people get used to faster processors, they
             become careless with their data and more and more of it
             ends up in <filename>/dev/null</filename>, overheating
             their CPUs.  If you delete <filename>/dev/null</filename>
             (which effectively disables the CPU data sink) your CPU
             may run cooler but your system will quickly become
             constipated with all that excess data and start to behave
             erratically.  If you have a fast network connection you
             can cool down your CPU by reading data out of
             <filename>/dev/random</filename> and sending it off
             somewhere; however you run the risk of overheating your
             network connection and <filename>/</filename> or angering
             your ISP, as most of the data will end up getting
             converted to heat by their equipment, but they generally
             have good cooling, so if you do not overdo it you should be
             OK.</para>
 
 	  <para><emphasis>Paul Robinson adds:</emphasis></para>
 
 	  <para>There are other methods. As every good sysadmin knows,
             it is part of standard practise to send data to the screen
             of interesting variety to keep all the pixies that make up
             your picture happy. Screen pixies (commonly mis-typed or
             re-named as 'pixels') are categorised by the type of hat
             they wear (red, green or blue) and will hide or appear
             (thereby showing the colour of their hat) whenever they
             receive a little piece of food. Video cards turn data into
             pixie-food, and then send them to the pixies - the more
             expensive the card, the better the food, so the better
             behaved the pixies are. They also need constant simulation
             - this is why screen savers exist.</para>
 
           <para>To take your suggestions further, you could just throw
             the random data to console, thereby letting the pixies
             consume it. This causes no heat to be produced at all,
             keeps the pixies happy and gets rid of your data quite
             quickly, even if it does make things look a bit messy on
             your screen.</para>
 
           <para>Incidentally, as an ex-admin of a large ISP who
             experienced many problems attempting to maintain a stable
             temperature in a server room, I would strongly discourage
             people sending the data they do not want out to the
             network. The fairies who do the packet switching and
             routing get annoyed by it as well.</para>
 	</answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="advanced">
     <title>Advanced Topics</title>
 
     <qandaset>
       <qandaentry>
         <question id="learn-advanced">
           <para>How can I learn more about FreeBSD's internals?</para>
         </question>
 
         <answer>
           <para>At this time, there is no book on FreeBSD-specific OS
             internals.  Much general UNIX knowledge is directly
             applicable to FreeBSD, however.  Additionally, there are
             BSD-specific books that are still relevant.</para>
 
           <para>For a list, please check the Handbook's <ulink
             URL="../handbook/bibliography-osinternals.html">Operating
             System Internals Bibliography</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
 	<question id="how-to-contribute">
 	  <para>How can I contribute to FreeBSD?</para>
 	</question>
 
 	<answer>
 	  <para>Please see the article on <ulink
 	    url="../../articles/contributing/article.html">Contributing
 	    to FreeBSD</ulink> for specific advice on how to do this.
 	    Assistance is more than welcome!</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
         <question id="define-snap-release">
           <para>What are SNAPs and RELEASEs?</para>
         </question>
 
         <answer>
           <para>There are currently three active/semi-active branches
             in the FreeBSD <ulink
             URL="http://www.FreeBSD.org/cgi/cvsweb.cgi">
             CVS Repository</ulink> (the RELENG_2 branch is probably
             only changed twice a year, which is why there are only three
             active branches of development):</para>
 
             <itemizedlist>
               <listitem>
                 <para><literal>RELENG_2_2</literal>   AKA
                   <emphasis>2.2-STABLE</emphasis></para>
               </listitem>
 
               <listitem>
                 <para><literal>RELENG_3</literal>     AKA
                   <emphasis>3.X-STABLE</emphasis></para>
               </listitem>
 
               <listitem>
                 <para><literal>RELENG_4</literal>      AKA
                   <emphasis>4-STABLE</emphasis></para>
               </listitem>
 
               <listitem>
                 <para><literal>HEAD</literal>         AKA
                   <emphasis>-CURRENT</emphasis>  AKA
                   <emphasis>5.0-CURRENT</emphasis></para>
               </listitem>
 
             </itemizedlist>
 
           <para><literal>HEAD</literal> is not an actual branch tag,
             like the other two; it is simply a symbolic constant for
             <quote><emphasis>the current, non-branched development
             stream</emphasis></quote> which we simply refer to as
             <quote>-CURRENT</quote>.</para>
 
           <para>Right now, <quote>-CURRENT</quote> is the 5.0 development
             stream and the <literal>4-STABLE</literal> branch,
             <symbol>RELENG_4</symbol>, forked off from
             <quote>-CURRENT</quote> in Mar 2000.</para>
 
           <para>The <literal>2.2-STABLE</literal> branch,
             <symbol>RELENG_2_2</symbol>, departed -CURRENT in November
             1996, and has pretty much been retired.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="custrel">
           <para>How do I make my own custom release?</para>
         </question>
 
         <answer>
           <para>Please see the <ulink
             url="../../articles/releng/article.html">
             Release Engineering</ulink> article.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="makeworld-clobbers">
           <para>Why does <command>make world</command> clobber my existing
             installed binaries?</para>
         </question>
 
         <answer>
           <para>Yes, this is the general idea; as its name might suggest,
             <command>make world</command> rebuilds every system binary from
             scratch, so you can be certain of having a clean and consistent
             environment at the end (which is why it takes so long).</para>
 
           <para>If the environment variable <literal>DESTDIR</literal>
             is defined while running <command>make world</command> or
             <command>make install</command>, the newly-created binaries
             will be deposited in a directory tree identical to the
             installed one, rooted at <literal>${DESTDIR}</literal>.
             Some random combination of shared libraries modifications and
             program rebuilds can cause this to fail in <command>make
             world</command> however.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="bus-speed-defaulted">
           <para>Why does my system say <quote>(bus speed
             defaulted)</quote> when it boots?</para>
         </question>
 
         <answer>
 
           <para>The Adaptec 1542 SCSI host adapters allow the user to
             configure their bus access speed in software. Previous versions
             of the 1542 driver tried to determine the fastest usable speed
             and set the adapter to that. We found that this breaks some
             users' systems, so you now have to define the
             <symbol>TUNE_1542</symbol> kernel configuration option in order
             to have this take place. Using it on those systems where it
             works may make your disks run faster, but on those systems
             where it does not, your data could be corrupted.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ctm">
           <para>Can I follow current with limited Internet access?</para>
         </question>
 
         <answer>
           <para>Yes, you can do this <literal>without</literal>
             downloading the whole source tree by using the <ulink
             URL="../handbook/synching.html#CTM">CTM facility</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="split-240k">
           <para>How did you split the distribution into 240k files?</para>
         </question>
 
         <answer>
           <para>Newer BSD based systems have a <option>-b</option>
             option to split that allows them to split files on arbitrary
             byte boundaries.</para>
 
           <para>Here is an example from
             <filename>/usr/src/Makefile</filename>.</para>
 
           <programlisting>bin-tarball:
 (cd ${DISTDIR}; \
 tar cf - . \
 gzip --no-name -9 -c | \
 split -b 240640 - \
 ${RELEASEDIR}/tarballs/bindist/bin_tgz.)</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="submitting-kernel-extensions">
           <para>I have written a kernel extension, who do I send it
             to?</para>
         </question>
 
         <answer>
           <para>Please take a look at the article on <ulink
             URL="../../articles/contributing/article.html">Contributing
             to FreeBSD</ulink> to learn how to submit code.</para>
 
           <para>And thanks for the thought!</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="pnp-initialize">
           <para>How are Plug N Play ISA cards detected and
             initialized?</para>
         </question>
 
         <answer>
           <para>By: Frank Durda IV
             <email>uhclem@nemesis.lonestar.org</email></para>
 
           <para>In a nutshell, there a few I/O ports that all of the
             PnP boards respond to when the host asks if anyone is out
             there. So when the PnP probe routine starts, he asks if there
             are any PnP boards present, and all the PnP boards respond with
             their model # to a I/O read of the same port, so the probe
             routine gets a wired-OR <quote>yes</quote> to that question. At
             least one bit will be on in that reply. Then the probe code is
             able to cause boards with board model IDs (assigned by
             Microsoft/Intel) lower than X to go <quote>off-line</quote>. It
             then looks to see if any boards are still responding to the
             query. If the answer was <literal>0</literal>, then there are
             no boards with IDs above X. Now probe asks if there are any
             boards below <literal>X</literal>. If so, probe knows there are
             boards with a model numbers below X. Probe then asks for boards
             greater than X-(limit/4) to go off-line. If repeats the query.
             By repeating this semi-binary search of IDs-in-range enough
             times, the probing code will eventually identify all PnP boards
             present in a given machine with a number of iterations that is
             much lower than what 2^64 would take.</para>
 
           <para>The IDs are two 32-bit fields (hence 2&circ;64) + 8 bit
             checksum. The first 32 bits are a vendor identifier. They never
             come out and say it, but it appears to be assumed that
             different types of boards from the same vendor could have
             different 32-bit vendor ids. The idea of needing 32 bits just
             for unique manufacturers is a bit excessive.</para>
 
           <para>The lower 32 bits are a serial #, Ethernet address,
             something that makes this one board unique. The vendor must
             never produce a second board that has the same lower 32 bits
             unless the upper 32 bits are also different. So you can have
             multiple boards of the same type in the machine and the full 64
             bits will still be unique.</para>
 
           <para>The 32 bit groups can never be all zero.  This allows the
             wired-OR to show non-zero bits during the initial binary
             search.</para>
 
           <para>Once the system has identified all the board IDs present,
             it will reactivate each board, one at a time (via the same I/O
             ports), and find out what resources the given board needs, what
             interrupt choices are available, etc. A scan is made over all
             the boards to collect this information.</para>
 
           <para>This info is then combined with info from any ECU files
             on the hard disk or wired into the MLB BIOS. The ECU and BIOS
             PnP support for hardware on the MLB is usually synthetic, and
             the peripherals do not really do genuine PnP. However by
             examining the BIOS info plus the ECU info, the probe routines
             can cause the devices that are PnP to avoid those devices the
             probe code cannot relocate.</para>
 
           <para>Then the PnP devices are visited once more and given
             their I/O, DMA, IRQ and Memory-map address assignments. The
             devices will then appear at those locations and remain there
             until the next reboot, although there is nothing that says you
             cannot move them around whenever you want.</para>
 
           <para>There is a lot of oversimplification above, but you
             should get the general idea.</para>
 
           <para>Microsoft took over some of the primary printer status
             ports to do PnP, on the logic that no boards decoded those
             addresses for the opposing I/O cycles. I found a genuine IBM
             printer board that did decode writes of the status port during
             the early PnP proposal review period, but MS said
             <quote>tough</quote>. So they do a write to the printer status
             port for setting addresses, plus that use that address +
             <literal>0x800</literal>, and a third I/O port for reading that
             can be located anywhere between <literal>0x200</literal> and
             <literal>0x3ff</literal>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="major-numbers">
           <para>Can you assign a major number for a device driver I have
             written?</para>
         </question>
 
         <answer>
 
           <para>This depends on whether or not you plan on making the
             driver publicly available. If you do, then please send us a
             copy of the driver source code, plus the appropriate
             modifications to <filename>files.i386</filename>, a
             sample configuration file entry, and the appropriate
             &man.MAKEDEV.8;
             code to create any special files your device uses. If you do
             not, or are unable to because of licensing restrictions, then
             character major number 32 and block major number 8 have been
             reserved specifically for this purpose; please use them. In any
             case, we would appreciate hearing about your driver on
             &a.hackers;.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="alternate-directory-layout">
           <para>What about alternative layout policies for
             directories?</para>
         </question>
 
         <answer>
           <para>In answer to the question of alternative layout policies
             for directories, the scheme that is currently in use is
             unchanged from what I wrote in 1983. I wrote that policy for
             the original fast filesystem, and never revisited it. It works
             well at keeping cylinder groups from filling up. As several of
             you have noted, it works poorly for find. Most filesystems are
             created from archives that were created by a depth first search
             (aka ftw). These directories end up being striped across the
             cylinder groups thus creating a worst possible scenario for
             future depth first searches. If one knew the total number of
             directories to be created, the solution would be to create
             (total / fs_ncg) per cylinder group before moving on.
             Obviously, one would have to create some heuristic to guess at
             this number. Even using a small fixed number like say 10 would
             make an order of magnitude improvement. To differentiate
             restores from normal operation (when the current algorithm is
             probably more sensible), you could use the clustering of up to
             10 if they were all done within a ten second window. Anyway, my
             conclusion is that this is an area ripe for
             experimentation.</para>
 
           <para>Kirk McKusick, September 1998</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="kernel-panic-troubleshooting">
           <para>How can I make the most of the data I see when my kernel
             panics?</para>
         </question>
 
         <answer>
           <para><emphasis>[This section was extracted from a mail
             written by &a.wpaul; on the freebsd-current
             <link linkend="mailing">mailing list</link> by &a.des;, who
             fixed a few typos and added the bracketed comments]
             </emphasis></para>
 
           <programlisting>From: Bill Paul &lt;wpaul@skynet.ctr.columbia.edu&gt;
 Subject: Re: the fs fun never stops
 To: Ben Rosengart
 Date: Sun, 20 Sep 1998 15:22:50 -0400 (EDT)
 Cc: current@FreeBSD.org</programlisting>
 
           <para><emphasis>Ben Rosengart posted the following
             panic message]</emphasis></para>
 
           <programlisting>&gt; Fatal trap 12: page fault while in kernel mode
 &gt; fault virtual address   = 0x40
 &gt; fault code              = supervisor read, page not present
 &gt; instruction pointer     = 0x8:0xf014a7e5
                                 ^^^^^^^^^^
 &gt; stack pointer           = 0x10:0xf4ed6f24
 &gt; frame pointer           = 0x10:0xf4ed6f28
 &gt; code segment            = base 0x0, limit 0xfffff, type 0x1b
 &gt;                         = DPL 0, pres 1, def32 1, gran 1
 &gt; processor eflags        = interrupt enabled, resume, IOPL = 0
 &gt; current process         = 80 (mount)
 &gt; interrupt mask          =
 &gt; trap number             = 12
 &gt; panic: page fault</programlisting>
 
           <para>[When] you see a message like this, it is not enough to just
             reproduce it and send it in. The instruction pointer value that
             I highlighted up there is important; unfortunately, it is also
             configuration dependent. In other words, the value varies
             depending on the exact kernel image that you are using. If
             you are using a GENERIC kernel image from one of the snapshots,
             then it is possible for somebody else to track down the
             offending function, but if you are running a custom kernel then
             only <emphasis>you</emphasis> can tell us where the fault
             occurred.</para>
 
           <para>What you should do is this:</para>
 
             <procedure>
               <step>
                 <para>Write down the instruction pointer value. Note that
                   the <literal>0x8:</literal> part at the beginning is not
                   significant in this case: it is the
                   <literal>0xf0xxxxxx</literal> part that we want.</para>
               </step>
 
               <step>
                 <para>When the system reboots, do the following:
 
                   <screen>&prompt.user; <userinput>nm -n /kernel.that.caused.the.panic | grep f0xxxxxx</userinput></screen>
 
                   where <literal>f0xxxxxx</literal> is the instruction
                   pointer value. The odds are you will not get an exact
                   match since the symbols in the kernel symbol table are
                   for the entry points of functions and the instruction
                   pointer address will be somewhere inside a function, not
                   at the start. If you do not get an exact match, omit the
                   last digit from the instruction pointer value and try
                   again, i.e.:
 
                   <screen>&prompt.user; <userinput>nm -n /kernel.that.caused.the.panic | grep f0xxxxx</userinput></screen>
 
                    If that does not yield any results, chop off another
                    digit. Repeat until you get some sort of output. The
                    result will be a possible list of functions which caused
                    the panic. This is a less than exact mechanism for
                    tracking down the point of failure, but it is better than
                    nothing.</para>
               </step>
             </procedure>
 
           <para>I see people constantly show panic messages like this
             but rarely do I see someone take the time to match up the
             instruction pointer with a function in the kernel symbol
             table.</para>
 
           <para>The best way to track down the cause of a panic is by
             capturing a crash dump, then using
             &man.gdb.1; to generate a stack trace on the
             crash dump.</para>
 
           <para>In any case, the method I normally use is this:</para>
 
             <procedure>
               <step>
                 <para>Set up a kernel config file, optionally adding
                   <literal>options DDB</literal> if you think you need
                   the kernel debugger for something. (I use this mainly
                   for setting breakpoints if I suspect an infinite loop
                   condition of some kind.)</para>
               </step>
 
               <step>
                 <para>Use <command>config -g
                   <replaceable>KERNELCONFIG</replaceable></command> to set
                   up the build directory.</para>
               </step>
 
               <step>
                 <para><command>cd /sys/compile/
                   <replaceable>KERNELCONFIG</replaceable>; make
                   </command></para>
               </step>
 
               <step>
                 <para>Wait for kernel to finish compiling.</para>
               </step>
 
               <step>
                 <para><command>make install</command></para>
               </step>
 
               <step>
                 <para>reboot</para>
               </step>
             </procedure>
 
           <para>The &man.make.1; process will have built two kernels.
             <filename>kernel</filename> and
             <filename>kernel.debug</filename>.  <filename>kernel</filename>
             was installed as <filename>/kernel</filename>, while
             <filename>kernel.debug</filename> can be used as the source of
             debugging symbols for &man.gdb.1;.</para>
 
           <para>To make sure you capture a crash dump, you need edit
             <filename>/etc/rc.conf</filename> and set
             <literal>dumpdev</literal> to point to your swap
             partition. This will cause the &man.rc.8; scripts
             to use the &man.dumpon.8; command to enable crash
             dumps. You can also run &man.dumpon.8; manually.
             After a panic, the crash dump can be recovered using
             &man.savecore.8;; if
             <literal>dumpdev</literal> is set in
             <filename>/etc/rc.conf</filename>, the &man.rc.8;
             scripts will run &man.savecore.8; automatically
             and put the crash dump in
             <filename>/var/crash</filename>.</para>
 
             <note>
               <para>FreeBSD crash dumps are usually the same size as the
                 physical RAM size of your machine. That is, if you have
                 64MB of RAM, you will get a 64MB crash dump. Therefore you
                 must make sure there is enough space in
                 <filename>/var/crash</filename> to hold the dump.
                 Alternatively, you run &man.savecore.8;
                 manually and have it recover the crash dump to another
                 directory where you have more room. It is possible to limit
                 the size of the crash dump by using <literal>options
                 MAXMEM=(foo)</literal> to set the amount of memory the
                 kernel will use to something a little more sensible. For
                 example, if you have 128MB of RAM, you can limit the
                 kernel's memory usage to 16MB so that your crash dump size
                 will be 16MB instead of 128MB.</para>
             </note>
 
           <para>Once you have recovered the crash dump, you can get a
             stack trace with &man.gdb.1; as follows:</para>
 
           <screen>&prompt.user; <userinput>gdb -k /sys/compile/KERNELCONFIG/kernel.debug /var/crash/vmcore.0</userinput>
 <prompt>(gdb)</prompt> <userinput>where</userinput></screen>
 
           <para>Note that there may be several screens worth of
             information; ideally you should use
             &man.script.1; to capture all of them. Using the
             unstripped kernel image with all the debug symbols should show
             the exact line of kernel source code where the panic occurred.
             Usually you have to read the stack trace from the bottom up in
             order to trace the exact sequence of events that lead to the
             crash. You can also use &man.gdb.1; to print out
             the contents of various variables or structures in order to
             examine the system state at the time of the crash.</para>
 
           <para>Now, if you are really insane and have a second computer,
             you can also configure &man.gdb.1; to do remote
             debugging such that you can use &man.gdb.1; on
             one system to debug the kernel on another system, including
             setting breakpoints, single-stepping through the kernel code,
             just like you can do with a normal user-mode program. I have not
             played with this yet as I do not often have the chance to set up
             two machines side by side for debugging purposes.</para>
 
           <para><emphasis>[Bill adds: "I forgot to mention one thing: if
             you have DDB enabled and the kernel drops into the debugger,
             you can force a panic (and a crash dump) just by typing 'panic'
             at the ddb prompt. It may stop in the debugger again during the
             panic phase. If it does, type 'continue' and it will finish the
             crash dump." -ed]</emphasis></para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="dlsym-failure">
           <para>Why has dlsym() stopped working for ELF executables?</para>
         </question>
 
         <answer>
           <para>The ELF toolchain does not, by default, make the symbols
             defined in an executable visible to the dynamic linker.
             Consequently <function>dlsym()</function> searches on handles
             obtained from calls to <function>dlopen(NULL,
             flags)</function> will fail to find such symbols.</para>
 
           <para>If you want to search, using <function>dlsym()</function>,
             for symbols present in the main executable of a process, you
             need to link the executable using the
             <option>-export-dynamic</option> option to the
             ELF
             linker (&man.ld.1;).</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="change-kernel-address-space">
           <para>How can I increase or reduce the kernel address space?</para>
         </question>
 
         <answer>
           <para>By default, the kernel address space is 256 MB on
             FreeBSD 3.x and 1 GB on FreeBSD 4.x. If you run a
             network-intensive server (e.g. a large FTP or HTTP server),
             you might find that 256 MB is not enough.</para>
 
           <para>So how do you increase the address space? There are two
             aspects to this. First, you need to tell the kernel to reserve
             a larger portion of the address space for itself. Second, since
             the kernel is loaded at the top of the address space, you need
             to lower the load address so it does not bump its head against
             the ceiling.</para>
 
           <para>The first goal is achieved by increasing the value of
             <literal>NKPDE</literal> in
             <filename>src/sys/i386/include/pmap.h</filename>. Here is what
             it looks like for a 1 GB address space:</para>
 
           <programlisting>#ifndef NKPDE
 #ifdef SMP
 #define NKPDE                   254     /* addressable number of page tables/pde's */
 #else
 #define NKPDE                   255     /* addressable number of page tables/pde's */
 #endif  /* SMP */
 #endif</programlisting>
 
           <para>To find the correct value of <literal>NKPDE</literal>,
             divide the desired address space size (in megabytes) by four,
             then subtract one for UP and two for SMP.</para>
 
           <para>To achieve the second goal, you need to compute the
             correct load address: simply subtract the address space size
             (in bytes) from 0x100100000; the result is 0xc0100000 for a 1
             GB address space. Set <symbol>LOAD_ADDRESS</symbol> in
             <filename>src/sys/i386/conf/Makefile.i386</filename> to that
             value; then set the location counter in the beginning of the
             section listing in
             <filename>src/sys/i386/conf/kernel.script</filename> to the
             same value, as follows:</para>
 
           <programlisting>OUTPUT_FORMAT("elf32-i386", "elf32-i386", "elf32-i386")
 OUTPUT_ARCH(i386)
 ENTRY(btext)
 SEARCH_DIR(/usr/lib); SEARCH_DIR(/usr/obj/elf/home/src/tmp/usr/i386-unknown-freebsdelf/lib);
 SECTIONS
 {
   /* Read-only sections, merged into text segment: */
   . = 0xc0100000 + SIZEOF_HEADERS;
   .interp     : { *(.interp)    }</programlisting>
 
           <para>Then reconfig and rebuild your kernel. You will probably
             have problems with &man.ps.1;
             &man.top.1; and the like; <command>make
             world</command> should take care of it (or a manual rebuild of
             <filename>libkvm</filename>,
             &man.ps.1; and &man.top.1;
             after copying the patched <filename>pmap.h</filename> to
             <filename>/usr/include/vm/</filename>.</para>
 
           <para>NOTE: the size of the kernel address space must be a
             multiple of four megabytes.</para>
 
           <para>[&a.dg; adds: <emphasis>I think the kernel address space
             needs to be a power of two, but I am not certain about that. The
           old(er) boot code used to monkey with the high order address bits
           and I think expected at least 256MB
           granularity.]</emphasis></para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="acknowledgments">
     <title>Acknowledgments</title>
 
     <blockquote>
        <attribution>FreeBSD Core Team</attribution>
 
        <para>If you see a problem with this FAQ, or wish to submit an
          entry, please mail the &a.faq;.  We appreciate your feedback,
          and cannot make this a better FAQ without your help!</para>
     </blockquote>
 
       <variablelist>
         <varlistentry>
           <term>&a.jkh;</term>
             <listitem>
               <para>Occasional fits of FAQ-reshuffling and updating.</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>&a.dwhite;</term>
 
             <listitem>
               <para>Services above and beyond the call of duty on
                 freebsd-questions</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>&a.joerg;</term>
 
             <listitem>
               <para>Services above and beyond the call of duty on
                 Usenet</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>&a.wollman;</term>
 
             <listitem>
               <para>Networking and formatting</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>Jim Lowe</term>
 
             <listitem>
               <para>Multicast information</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>&a.pds;</term>
 
             <listitem>
               <para>FreeBSD FAQ typing machine slavey</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>The FreeBSD Team</term>
 
             <listitem>
               <para>Kvetching, moaning, submitting data</para>
 
             </listitem>
           </varlistentry>
         </variablelist>
 
     <para>And to any others we have forgotten, apologies and heartfelt
       thanks!</para>
   </chapter>
 
   &bibliography;
 </book>
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
index e124d85a66..ff133da1b8 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
@@ -1,1580 +1,1580 @@
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="sgml-primer">
   <title>SGML Primer</title>
 
   <para>The majority of FDP documentation is written in applications of
     SGML.  This chapter explains exactly what that means, how to read
     and understand the source to the documentation, and the sort of SGML
     tricks you will see used in the documentation.</para>
 
   <para>Portions of this section were inspired by Mark Galassi's <ulink
       url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para>
   
   <sect1>
     <title>Overview</title>
 
     <para>Way back when, electronic text was simple to deal with.  Admittedly, 
       you had to know which character set your document was written in (ASCII, 
       EBCDIC, or one of a number of others) but that was about it.  Text was
       text, and what you saw really was what you got.  No frills, no
       formatting, no intelligence.</para>
 
     <para>Inevitably, this was not enough.  Once you have text in a
       machine-usable format, you expect machines to be able to use it and
       manipulate it intelligently.  You would like to indicate that certain
       phrases should be emphasised, or added to a glossary, or be hyperlinks.
       You might want filenames to be shown in a <quote>typewriter</quote> style 
       font for viewing on screen, but as <quote>italics</quote> when printed,
       or any of a myriad of other options for presentation.</para>
 
     <para>It was once hoped that Artificial Intelligence (AI) would make this
       easy.  Your computer would read in the document and automatically
       identify key phrases, filenames, text that the reader should type in,
       examples, and more.  Unfortunately, real life has not happened quite
       like that, and our computers require some assistance before they can
       meaningfully process our text.</para>
 
     <para>More precisely, they need help identifying what is what.  You or I
       can look at
 
       <blockquote>
 	<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
 
 	<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
       </blockquote>
 
       and easily see which parts are filenames, which are commands to be typed
       in, which parts are references to manual pages, and so on.  But the
       computer processing the document cannot.  For this we need
       markup.</para>
     
     <para><quote>Markup</quote> is commonly used to describe <quote>adding
       value</quote> or <quote>increasing cost</quote>.  The term takes on both
       these meanings when applied to text.  Markup is additional text included 
       in the document, distinguished from the document's content in some way,
       so that programs that process the document can read the markup and use
       it when making decisions about the document.  Editors can hide the
       markup from the user, so the user is not distracted by it.</para>
 
     <para>The extra information stored in the markup <emphasis>adds
       value</emphasis> to the document.  Adding the markup to the document
       must typically be done by a person&mdash;after all, if computers could
       recognise the text sufficiently well to add the markup then there would
       be no need to add it in the first place.  This <emphasis>increases the
       cost</emphasis> (i.e., the effort required) to create the
       document.</para>
 
     <para>The previous example is actually represented in this document like
       this;</para>
 
     <programlisting><![ CDATA [
 <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
 
 <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting>
 
     <para>As you can see, the markup is clearly separate from the
       content.</para>
 
     <para>Obviously, if you are going to use markup you need to define what
       your markup means, and how it should be interpreted.  You will need a
       markup language that you can follow when marking up your
       documents.</para>
     
    <para>Of course, one markup language might not be enough.  A markup
       language for technical documentation has very different requirements
       than a markup language that was to be used for cookery recipes.  This,
       in turn, would be very different from a markup language used to describe
       poetry.  What you really need is a first language that you use to write
       these other markup languages.  A <emphasis>meta markup
       language</emphasis>.</para>
     
     <para>This is exactly what the Standard Generalised Markup Language (SGML)
       is.  Many markup languages have been written in SGML, including the two
       most used by the FDP, HTML and DocBook.</para>
     
     <para>Each language definition is more properly called a Document Type
       Definition (DTD).  The DTD specifies the name of the elements that can
       be used, what order they appear in (and whether some markup can be used
       inside other markup) and related information.  A DTD is sometimes
       referred to as an <emphasis>application</emphasis> of SGML.</para>
 
     <para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis>
       specification of all the elements that are allowed to appear, the order
       in which they should appear, which elements are mandatory, which are
       optional, and so forth. This makes it possible to write an SGML
       <emphasis>parser</emphasis> which reads in both the DTD and a document
       which claims to conform to the DTD.  The parser can then confirm whether
       or not all the elements required by the DTD are in the document in the
       right order, and whether there are any errors in the markup.  This is
       normally referred to as <quote>validating  the document</quote>.</para>
 
     <note>
       <para>This processing simply confirms that the choice of elements, their 
 	ordering, and so on, conforms to that listed in the DTD.  It does
 	<emphasis>not</emphasis> check that you have used
 	<emphasis>appropriate</emphasis> markup for the content.  If you were
 	to try and mark up all the filenames in your document as function
 	names, the parser would not flag this as an error (assuming, of
 	course, that your DTD defines elements for filenames and functions,
 	and that they are allowed to appear in the same place).</para>
     </note>
     
     <para>It is likely that most of your contributions to the Documentation
       Project will consist of content marked up in either HTML or DocBook,
       rather than alterations to the DTDs.  For this reason this book will
       not touch on how to write a DTD.</para>
   </sect1>
   
   <sect1 id="sgml-primer-elements">
     <title>Elements, tags, and attributes</title>
 
     <para>All the DTDs written in SGML share certain characteristics.  This is
       hardly surprising, as the philosophy behind SGML will inevitably show
       through. One of the most obvious manifestations of this philosophy is
       that of <emphasis>content</emphasis> and
       <emphasis>elements</emphasis>.</para>
 
     <para>Your documentation (whether it is a single web page, or a lengthy
       book) is considered to consist of content.  This content is then divided
       (and further subdivided) into elements.  The purpose of adding markup is
       to name and identify the boundaries of these elements for further
       processing.</para>
 
     <para>For example, consider a typical book.  At the very top level, the
       book is itself an element.  This <quote>book</quote> element obviously
       contains chapters, which can be considered to be elements in their own
       right.  Each chapter will contain more elements, such as paragraphs,
       quotations, and footnotes.  Each paragraph might contain further
       elements, identifying content that was direct speech, or the name of a
       character in the story.</para>
 
     <para>You might like to think of this as <quote>chunking</quote> content.
       At the very top level you have one chunk, the book.  Look a little
       deeper, and you have more chunks, the individual chapters.  These are
       chunked further into paragraphs, footnotes, character names, and so
       on.</para>
 
     <para>Notice how you can make this differentiation between different
       elements of the content without resorting to any SGML terms.  It really
       is surprisingly straightforward.  You could do this with a highlighter
       pen and a printout of the book, using different colours to indicate
       different chunks of content.</para>
 
     <para>Of course, we do not have an electronic highlighter pen, so we need
       some other way of indicating which element each piece of content belongs
       to.  In languages written in SGML (HTML, DocBook, et al) this is done by
       means of <emphasis>tags</emphasis>.</para>
 
     <para>A tag is used to identify where a particular element starts, and
       where the element ends.  <emphasis>The tag is not part of the element
       itself</emphasis>. Because each DTD was normally written to mark up
       specific types of information, each one will recognise different
       elements, and will therefore have different names for the tags.</para>
 
     <para>For an element called <replaceable>element-name</replaceable> the
       start tag will normally look like
       <literal>&lt;<replaceable>element-name</replaceable>&gt;</literal>.  The
       corresponding closing tag for this element is
       <literal>&lt;/<replaceable>element-name</replaceable>&gt;</literal>.</para>
 
     <example>
       <title>Using an element (start and end tags)</title>
 
       <para>HTML has an element for indicating that the content enclosed by
 	the element is a paragraph, called <literal>p</literal>.  This
 	element has both start and end tags.</para>
       
       <programlisting><![ CDATA [<p>This is a paragraph.  It starts with the start tag for
   the 'p' element, and it will end with the end tag for the 'p'
   element.</p>
 
 <p>This is another paragraph.  But this one is much shorter.</p>]]></programlisting>	  
     </example>
 
     <para>Not all elements require an end tag.  Some elements have no content.
       For example, in HTML you can indicate that you want a horizontal line to
       appear in the document.  Obviously, this line has no content, so just
       the start tag is required for this element.</para>
 
     <example>
       <title>Using an element (start tag only)</title>
 
       <para>HTML has an element for indicating a horizontal rule, called
 	<literal>hr</literal>.  This element does not wrap content, so only
 	has a start tag.</para>
 
       <programlisting><![ CDATA [<p>This is a paragraph.</p>
 
 <hr>
 
 <p>This is another paragraph.  A horizontal rule separates this
   from the previous paragraph.</p>]]></programlisting>
     </example>
     
     <para>If it is not obvious by now, elements can contain other elements.
       In the book example earlier, the book element contained all the chapter
       elements, which in turn contained all the paragraph elements, and so
       on.</para>
 
     <example>
       <title>Elements within elements; <sgmltag>em</sgmltag></title>
       
       <programlisting><![ CDATA [<p>This is a simple <em>paragraph</em> where some
   of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting>
     </example>
     
     <para>The DTD will specify the rules detailing which elements can contain
       other elements, and exactly what they can contain.</para>
 
     <important>
       <para>People often confuse the terms tags and elements, and use the
 	terms as if they were interchangeable.  They are not.</para>
 
       <para>An element is a conceptual part of your document.  An element has
 	a defined start and end.  The tags mark where the element starts and
 	end.</para>
 
       <para>When this document (or anyone else knowledgeable about SGML) refers
 	to <quote>the &lt;p&gt; tag</quote> they mean the literal text
 	consisting of the three characters <literal>&lt;</literal>,
 	<literal>p</literal>, and <literal>&gt;</literal>.  But the phrase
 	<quote>the &lt;p&gt; element</quote> refers to the whole
 	element.</para>
 
       <para>This distinction <emphasis>is</emphasis> very subtle.  But keep it 
 	in mind.</para>
     </important>
       
     <para>Elements can have attributes.  An attribute has a name and a value,
       and is used for adding extra information to the element.  This might be
       information that indicates how the content should be rendered, or might
       be something that uniquely identifies that occurrence of the element, or
       it might be something else.</para>
 
     <para>An element's attributes are written <emphasis>inside</emphasis> the
       start tag for that element, and take the form
       <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
 
     <para>In sufficiently recent versions of HTML, the <sgmltag>p</sgmltag>
       element has an attribute called <literal>align</literal>, which suggests
       an alignment (justification) for the paragraph to the program displaying
       the HTML.</para>
 
     <para>The <literal>align</literal> attribute can take one of four defined
       values, <literal>left</literal>, <literal>center</literal>,
       <literal>right</literal> and <literal>justify</literal>.  If the
       attribute is not specified then the default is
       <literal>left</literal>.</para>
 
     <example>
       <title>Using an element with an attribute</title>
       
       <programlisting><![ CDATA [<p align="left">The inclusion of the align attribute
   on this paragraph was superfluous, since the default is left.</p>
 
 <p align="center">This may appear in the center.</p>]]></programlisting>
     </example>
     
     <para>Some attributes will only take specific values, such as
       <literal>left</literal> or <literal>justify</literal>.  Others will
       allow you to enter anything you want.  If you need to include quotes
       (<literal>"</literal>) within an attribute then use single quotes around
       the attribute value.</para>
 
     <example>
       <title>Single quotes around attributes</title>
       
       <programlisting><![ CDATA [<p align='right'>I am on the right!</p>]]></programlisting>
     </example>
 
     <para>Sometimes you do not need to use quotes around attribute values at
       all.  However, the rules for doing this are subtle, and it is far
       simpler just to <emphasis>always</emphasis> quote your attribute
       values.</para>
 
     <para>The information on attributes, elements, and tags is stored
       in SGML catalogs.  The various Documentation Project tools use
       these catalog files to validate your work.  The tools in
       <filename role="package">textproc/docproj</filename> include a variety of SGML catalog
       files.  The FreeBSD Documentation Project includes its own set
       of catalog files.  Your tools need to know about both sorts of
       catalog files.</para>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <para>In order to run the examples in this document you will need to
         install some software on your system and ensure that an environment
         variable is set correctly.</para>
     
       <procedure>
 	<step>
 	  <para>Download and install <filename role="package">textproc/docproj</filename>
 	    from the FreeBSD ports system.  This is a
             <emphasis>meta-port</emphasis> that should download and install
             all of the programs and supporting files that are used by the
             Documentation Project.</para>
 	</step>
 	
         <step>
           <para>Add lines to your shell startup files to set
             <envar>SGML_CATALOG_FILES</envar>. (If you are not working
             on the English version of the documentation, you will want
             to substitute the correct directory for your
             language.)</para>
     
 	  <example id="sgml-primer-envars">
 	    <title><filename>.profile</filename>, for &man.sh.1; and
 	      &man.bash.1; users</title>
 	    
 	    <programlisting>SGML_ROOT=/usr/local/share/sgml	    
 SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
 SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=/usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES
 export SGML_CATALOG_FILES</programlisting>
 	  </example>
 
 	  <example>
 	    <title><filename>.login</filename>, for &man.csh.1; and
 	      &man.tcsh.1; users</title>
 	    
 	    <programlisting>setenv SGML_ROOT /usr/local/share/sgml
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES</programlisting>
           </example>
     
           <para>Then either log out, and log back in again, or run those
             commands from the command line to set the variable values.</para>
 	</step>
       </procedure>
     
       <procedure>
 	<step>
 	  <para>Create <filename>example.sgml</filename>, and enter the
             following text;</para>
 
 	  <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 
 <html>
   <head>	     
     <title>An example HTML file</title>
   </head>
 
   <body>	    
     <p>This is a paragraph containing some text.</p>
 
     <p>This paragraph contains some more text.</p>
 
     <p align="right">This paragraph might be right-justified.</p>
   </body>	    
 </html>]]></programlisting>
 	</step>
 
 	<step>
 	  <para>Try and validate this file using an SGML parser.</para>
 
 	  <para>Part of <filename role="package">textproc/docproj</filename> is the
 	    &man.nsgmls.1; <link linkend="sgml-primer-validating">validating
 	    parser</link>.  Normally, &man.nsgmls.1; reads in a document
 	    marked up according to an SGML DTD and returns a copy of the
 	    document's Element Structure Information Set (ESIS, but that is
 	    not important right now).</para>
 
 	  <para>However, when &man.nsgmls.1; is given the <option>-s</option>
 	    parameter, &man.nsgmls.1; will suppress its normal output, and
 	    just print error messages.  This makes it a useful way to check to
 	    see if your document is valid or not.</para>
 
 	  <para>Use &man.nsgmls.1; to check that your document is
 	    valid;</para>
 
           <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen>
 
 	  <para>As you will see, &man.nsgmls.1; returns without displaying any
 	    output.  This means that your document validated
 	    successfully.</para>
 	</step>
 
 	<step>
 	  <para>See what happens when required elements are omitted.  Try
 	    removing the <sgmltag>title</sgmltag> and
 	    <sgmltag>/title</sgmltag> tags, and re-run the validation.</para>
 
           <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput>
 nsgmls:example.sgml:5:4:E: character data is not allowed here
 nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
 
 	  <para>The error output from &man.nsgmls.1; is organised into
 	    colon-separated groups, or columns.</para>
 
 	  <informaltable frame="none">
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>Column</entry>
 		  <entry>Meaning</entry>
 		</row>
 	      </thead>
 	      
 	      <tbody>
 		<row>
 		  <entry>1</entry>
 		  <entry>The name of the program generating the error.  This
 		    will always be <literal>nsgmls</literal>.</entry>
 		</row>
 
 		<row>
 		  <entry>2</entry>
 		  <entry>The name of the file that contains the error.</entry>
 		</row>
 
 		<row>
 		  <entry>3</entry>
 		  <entry>Line number where the error appears.</entry>
 		</row>
 
 		<row>
 		  <entry>4</entry>
 		  <entry>Column number where the error appears.</entry>
 		</row>
 
 		<row>
 		  <entry>5</entry>
 		  <entry>A one letter code indicating the nature of the
 		    message.  <literal>I</literal> indicates an informational
 		    message, <literal>W</literal> is for warnings, and
 		    <literal>E</literal> is for errors<footnote>
 		      <para>It is not always the fifth column either.
 			<command>nsgmls -sv</command> displays
 			<literal>nsgmls:I: SP version "1.3"</literal>
 			(depending on the installed version).  As you can see,
 			this is an informational message.</para>
 		    </footnote>, and <literal>X</literal> is for
 		    cross-references.  As you can see, these messages are
 		    errors.</entry>
 		</row>
 
 		<row>
 		  <entry>6</entry>
 		  <entry>The text of the error message.</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 
 	  <para>Simply omitting the <sgmltag>title</sgmltag> tags has
 	    generated 2 different errors.</para>
 
 	  <para>The first error indicates that content (in this case,
 	    characters, rather than the start tag for an element) has occurred
 	    where the SGML parser was expecting something else.  In this case,
 	    the parser was expecting to see one of the start tags for elements
 	    that are valid inside <sgmltag>head</sgmltag> (such as
 	    <sgmltag>title</sgmltag>).</para>
 
 	  <para>The second error is because <sgmltag>head</sgmltag> elements
 	    <emphasis>must</emphasis> contain a <sgmltag>title</sgmltag>
 	    element.  Because it does not &man.nsgmls.1; considers that the
 	    element has not been properly finished.  However, the closing tag
 	    indicates that the element has been closed before it has been
 	    finished.</para>
 	</step>
 
 	<step>
 	  <para>Put the <literal>title</literal> element back in.</para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
 
   <sect1 id="sgml-primer-doctype-declaration">
     <title>The DOCTYPE declaration</title>
 
     <para>The beginning of each document that you write must specify the name
       of the DTD that the document conforms to.  This is so that SGML parsers
       can determine the DTD and ensure that the document does conform to 
       it.</para>
 
     <para>This information is generally expressed on one line, in the DOCTYPE
       declaration.</para>
 
     <para>A typical declaration for a document written to conform with version
       4.0 of the HTML DTD looks like this;</para>
 
     <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting>
 
     <para>That line contains a number of different components.</para>
 
     <variablelist>
       <varlistentry>
 	<term><literal>&lt;!</literal></term>
 	
 	<listitem>
 	  <para>Is the <emphasis>indicator</emphasis> that indicates that this
 	    is an SGML declaration.  This line is declaring the document type.
 	  </para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><literal>DOCTYPE</literal></term>
 	
 	<listitem>
 	  <para>Shows that this is an SGML declaration for the document
 	    type.</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term><literal>html</literal></term>
 	
 	<listitem>
 	  <para>Names the first <link linkend="sgml-primer-elements">element</link> that
 	    will appear in the document.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term>
 
 	<listitem>
 	  <para>Lists the Formal Public Identifier (FPI)<indexterm>
 	      <primary>Formal Public Identifier</primary>
 	    </indexterm>
 	    for the DTD that this
 	    document conforms to.  Your SGML parser will use this to find the
 	    correct DTD when processing this document.</para>
 
 	  <para><literal>PUBLIC</literal> is not a part of the FPI, but
 	    indicates to the SGML processor how to find the DTD referenced in
 	    the FPI.  Other ways of telling the SGML parser how to find the
 	    DTD are shown <link
 	      linkend="sgml-primer-fpi-alternatives">later</link>.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><literal>&gt;</literal></term>
 	
 	<listitem>
 	  <para>Returns to the document.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
     
     <sect2>
       <title>Formal Public Identifiers (FPIs)<indexterm significance="preferred">
 	  <primary>Formal Public Identifier</primary>
 	</indexterm>
 </title>
 
       <note>
 	<para>You do not need to know this, but it is useful background, and
 	  might help you debug problems when your SGML processor can not locate
 	  the DTD you are using.</para>
       </note>
       
       <para>FPIs must follow a specific syntax.  This syntax is as
 	follows;</para>
 
       <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting>
 
       <variablelist>
 	<varlistentry>
 	  <term><replaceable>Owner</replaceable></term>
 	  
 	  <listitem>
 	    <para>This indicates the owner of the FPI.</para>
 
 	    <para>If this string starts with <quote>ISO</quote> then this is an
 	      ISO owned FPI.  For example, the FPI <literal>"ISO
 		8879:1986//ENTITIES Greek Symbols//EN"</literal> lists
 	      <literal>ISO 8879:1986</literal> as being the owner for the set
 	      of entities for Greek symbols.  ISO 8879:1986 is the ISO number
 	      for the SGML standard.</para>
 
 	    <para>Otherwise, this string will either look like
 	      <literal>-//<replaceable>Owner</replaceable></literal> or
 	      <literal>+//<replaceable>Owner</replaceable></literal> (notice
 	      the only difference is the leading <literal>+</literal> or
 	      <literal>-</literal>).</para>
 
 	    <para>If the string starts with <literal>-</literal> then the
 	      owner information is unregistered, with a <literal>+</literal>
 	      it identifies it as being registered.</para>
 
 	    <para>ISO 9070:1991 defines how registered names are generated; it
 	      might be derived from the number of an ISO publication, an ISBN
 	      code, or an organisation code assigned according to ISO 6523.
 	      In addition, a registration authority could be created in order
 	      to assign registered names.  The ISO council delegated this to
 	      the American National Standards Institute (ANSI).</para>
 
 	    <para>Because the FreeBSD Project has not been registered the
 	      owner string is <literal>-//FreeBSD</literal>.  And as you can
 	      see, the W3C are not a registered owner either.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Keyword</replaceable></term>
 	  
 	  <listitem>
 	    <para>There are several keywords that indicate the type of
 	      information in the file.  Some of the most common keywords are
 	      <literal>DTD</literal>, <literal>ELEMENT</literal>,
 	      <literal>ENTITIES</literal>, and <literal>TEXT</literal>.
 	      <literal>DTD</literal> is used only for DTD files,
 	      <literal>ELEMENT</literal> is usually used for DTD fragments
 	      that contain only entity or element declarations.
 	      <literal>TEXT</literal> is used for SGML content (text and
 	      tags).</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Description</replaceable></term>
 	  
 	  <listitem>
 	    <para>Any description you want to supply for the contents of this
 	      file.  This may include version numbers or any short text that
 	      is meaningful to you and unique for the SGML system.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Language</replaceable></term>
 	  
 	  <listitem>
 	    <para>This is an ISO two-character code that identifies the native
 	      language for the file.  <literal>EN</literal> is used for
 	      English.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <sect3>
 	<title><filename>catalog</filename> files</title>
 	
 	<para>If you use the syntax above and try and process this document
 	  using an SGML processor, the processor will need to have some way of
 	  turning the FPI into the name of the file on your computer that
 	  contains the DTD.</para>
 	
 	<para>In order to do this it can use a catalog file.  A catalog file
 	  (typically called <filename>catalog</filename>) contains lines that
 	  map FPIs to filenames.  For example, if the catalog file contained
 	  the line;</para>
 	
 	<programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"</programlisting>
 
 	<para>The SGML processor would know to look up the DTD from
 	  <filename>strict.dtd</filename> in the <filename>4.0</filename>
 	  subdirectory of whichever directory held the
 	  <filename>catalog</filename> file that contained that line.</para>
 
 	<para>Look at the contents of
 	  <filename>/usr/local/share/sgml/html/catalog</filename>.  This is
 	  the catalog file for the HTML DTDs that will have been installed as
 	  part of the <filename role="package">textproc/docproj</filename> port.</para>
       </sect3>
 
       <sect3>
 	<title><envar>SGML_CATALOG_FILES</envar></title>
 
 	<para>In order to locate a <filename>catalog</filename> file, your
 	  SGML processor will need to know where to look.  Many of them
 	  feature command line parameters for specifying the path to one or
 	  more catalogs.</para>
 
 	<para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to
 	  point to the files.  This environment variable should consist of a
 	  colon-separated list of catalog files (including their full
 	  path).</para>
 
 	<para>Typically, you will want to include the following files;</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/docbook/4.1/catalog</filename></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/html/catalog</filename></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/jade/catalog</filename></para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>You should <link linkend="sgml-primer-envars">already have done
 	    this</link>.</para>
       </sect3>
     </sect2>
     
     <sect2 id="sgml-primer-fpi-alternatives">
       <title>Alternatives to FPIs</title>
       
       <para>Instead of using an FPI to indicate the DTD that the document
 	conforms to (and therefore, which file on the system contains the DTD)
 	you can explicitly specify the name of the file.</para>
       
       <para>The syntax for this is slightly different:</para>
       
       <programlisting><![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting>
       
       <para>The <literal>SYSTEM</literal> keyword indicates that the SGML
 	processor should locate the DTD in a system specific fashion.  This
 	typically (but not always) means the DTD will be provided as a
 	filename.</para>
       
       <para>Using FPIs is preferred for reasons of portability.  You do not
 	want to have to ship a copy of the DTD around with your document, and
 	if you used the <literal>SYSTEM</literal> identifier then everyone
 	would need to keep their DTDs in the same place.</para>
     </sect2>
   </sect1>
   
   <sect1 id="sgml-primer-sgml-escape">
     <title>Escaping back to SGML</title>
 
     <para>Earlier in this primer I said that SGML is only used when writing a
       DTD.  This is not strictly true.  There is certain SGML syntax that you
       will want to be able to use within your documents.  For example,
       comments can be included in your document, and will be ignored by the
       parser.  Comments are entered using SGML syntax.  Other uses for SGML
       syntax in your document will be shown later too.</para>
       
     <para>Obviously, you need some way of indicating to the SGML processor
       that the following content is not elements within the document, but is
       SGML that the parser should act upon.</para>
 
     <para>These sections are marked by <literal>&lt;! ...  &gt;</literal> in
       your document.  Everything between these delimiters is SGML syntax as
       you might find within a DTD.</para>
 
     <para>As you may just have realised, the <link
 	linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link>
       is an example of SGML syntax that you need to include in your
       document&hellip;</para>
   </sect1>
   
   <sect1>
     <title>Comments</title>
     
     <para>Comments are an SGML construction, and are normally only valid
       inside a DTD.  However, as <xref linkend="sgml-primer-sgml-escape">
       shows, it is possible to use SGML syntax within your document.</para>
 
     <para>The delimiter for SGML comments is the string
       <quote><literal>--</literal></quote>.  The first occurrence of this string
       opens a comment, and the second closes it.</para>
 
     <example>
       <title>SGML generic comment</title>
 
       <programlisting>&lt;!-- test comment --></programlisting>
       
       <programlisting><![ CDATA [
 <!-- This is inside the comment -->
 
 <!-- This is another comment    -->
 
 <!-- This is one way
      of doing multiline comments -->
 
 <!-- This is another way of   --
   -- doing multiline comments -->]]></programlisting>
     </example>
 
     <![ %output.print; [
     <important>
       <title>Use 2 dashes</title>
 
       <para>There is a problem with producing the Postscript and PDF versions
 	of this document.  The above example probably shows just one hyphen
 	symbol, <literal>-</literal> after the <literal>&lt;!</literal> and
 	before the <literal>&gt;</literal>.</para>
 
       <para>You <emphasis>must</emphasis> use two <literal>-</literal>,
 	<emphasis>not</emphasis> one.  The Postscript and PDF versions have
 	translated the two <literal>-</literal> in the original to a longer,
 	more professional <emphasis>em-dash</emphasis>, and broken this
 	example in the process.</para>
 
       <para>The HTML, plain text, and RTF versions of this document are not
 	affected.</para>
     </important>
     ]]>
     
     <para>If you have used HTML before you may have been shown different rules
       for comments.  In particular, you may think that the string
-      <literal>&lt!--</literal> opens a comment, and it is only closed by
+      <literal>&lt;!--</literal> opens a comment, and it is only closed by
       <literal>--&gt;</literal>.</para>
 
     <para>This is <emphasis>not</emphasis> the case.  A lot of web browsers
       have broken HTML parsers, and will accept that as valid.  However, the
       SGML parsers used by the Documentation Project are much stricter, and
       will reject documents that make that error.</para>
 
     <example>
       <title>Erroneous SGML comments</title>
 
       <programlisting><![ CDATA [
 <!-- This is in the comment --
 
      THIS IS OUTSIDE THE COMMENT!
 
   -- back inside the comment -->]]></programlisting>
 
       <para>The SGML parser will treat this as though it were actually;</para>
 
       <programlisting>&lt;!THIS IS OUTSIDE THE COMMENT&gt;</programlisting>
 
       <para>This is not valid SGML, and may give confusing error
 	messages.</para>
 
       <programlisting><![ CDATA [<!--------------- This is a very bad idea --------------->]]></programlisting>
 
       <para>As the example suggests, <emphasis>do not</emphasis> write
 	comments like that.</para>
 
       <programlisting><![ CDATA [<!--===================================================-->]]></programlisting>
 
       <para>That is a (slightly) better approach, but it still potentially
 	confusing to people new to SGML.</para>
     </example>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <procedure>
 	<step>
 	  <para>Add some comments to <filename>example.sgml</filename>, and
 	    check that the file still validates using &man.nsgmls.1;</para>
 	</step>
 
 	<step>
 	  <para>Add some invalid comments to
 	    <filename>example.sgml</filename>, and see the error messages that
 	    &man.nsgmls.1; gives when it encounters an invalid comment.</para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
     
   <sect1>
     <title>Entities</title>
 
     <para>Entities are a mechanism for assigning names to chunks of content.
       As an SGML parser processes your document, any entities it finds are
       replaced by the content of the entity.</para>
     
     <para>This is a good way to have re-usable, easily changeable chunks of
       content in your SGML documents.  It is also the only way to include one
       marked up file inside another using SGML.</para>
     
     <para>There are two types of entities which can be used in two different
       situations; <emphasis>general entities</emphasis> and
       <emphasis>parameter entities</emphasis>.</para>
     
     <sect2 id="sgml-primer-general-entities">
       <title>General Entities</title>
       
       <para>You cannot use general entities in an SGML context (although you
 	define them in one).  They can only be used in your document.
 	Contrast this with <link
 	  linkend="sgml-primer-parameter-entities">parameter
 	  entities</link>.</para>
 
       <para>Each general entity has a name.  When you want to reference a
 	general entity (and therefore include whatever text it represents in
 	your document), you write
 	<literal>&amp;<replaceable>entity-name</replaceable>;</literal>.  For
 	example, suppose you had an entity called
 	<literal>current.version</literal> which expanded to the current
 	version number of your product.  You could write;</para>
 
       <programlisting><![ CDATA [<para>The current version of our product is
   &current.version;.</para>]]></programlisting>
 
       <para>When the version number changes you can simply change the
 	definition of the value of the general entity and reprocess your
 	document.</para>
 
       <para>You can also use general entities to enter characters that you
 	could not otherwise include in an SGML document.  For example, &lt;
 	and &amp; cannot normally appear in an SGML document.  When the SGML
 	parser sees the &lt; symbol it assumes that a tag (either a start tag
 	or an end tag) is about to appear, and when it sees the &amp; symbol
 	it assumes the next text will be the name of an entity.</para>
 
       <para>Fortunately, you can use the two general entities &amp;lt; and
 	&amp;amp; whenever you need to include one or other of these </para>
 	
       <para>A general entity can only be defined within an SGML context.
 	Typically, this is done immediately after the DOCTYPE
 	declaration.</para>
 
       <example>
 	<title>Defining general entities</title>
 
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY current.version    "3.0-RELEASE">
 <!ENTITY last.version       "2.2.7-RELEASE">
 ]>]]></programlisting>
 	  
 	<para>Notice how the DOCTYPE declaration has been extended by adding a
 	  square bracket at the end of the first line.  The two entities are
 	  then defined over the next two lines, before the square bracket is
 	  closed, and then the DOCTYPE declaration is closed.</para>
 
 	<para>The square brackets are necessary to indicate that we are
 	  extending the DTD indicated by the DOCTYPE declaration.</para>
       </example>
     </sect2>
     
     <sect2 id="sgml-primer-parameter-entities">
       <title>Parameter entities</title>
 
       <para>Like <link linkend="sgml-primer-general-entities">general
 	  entities</link>, parameter entities are used to assign names to
 	reusable chunks of text.  However, where as general entities can only
 	be used within your document, parameter entities can only be used
 	within an <link linkend="sgml-primer-sgml-escape">SGML
 	  context</link>.</para>
 
       <para>Parameter entities are defined in a similar way to general
 	entities.  However, instead of using
 	<literal>&amp;<replaceable>entity-name</replaceable>;</literal> to
 	refer to them, use
 	<literal>%<replaceable>entity-name</replaceable>;</literal><footnote>
 	  <para><emphasis>P</emphasis>arameter entities use the
 	    <emphasis>P</emphasis>ercent symbol.</para>
 	</footnote>.  The definition also includes the <literal>%</literal>
 	between the <literal>ENTITY</literal> keyword and the name of the
 	entity.</para>
       
       <example>
 	<title>Defining parameter entities</title>
 	
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % param.some "some">
 <!ENTITY % param.text "text">
 <!ENTITY % param.new  "%param.some more %param.text">
 
 <!-- %param.new now contains "some more text" -->
 ]>]]></programlisting>
       </example>
 	
       <para>This may not seem particularly useful.  It will be.</para>
     </sect2>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <procedure>
 	<step>
 	  <para>Add a general entity to
 	    <filename>example.sgml</filename>.</para>
 
 	  <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
 <!ENTITY version "1.1">
 ]>	  
 
 <html>
   <head>	     
     <title>An example HTML file</title>
   </head>
 
   <!-- You might well have some comments in here as well -->
 	  
   <body>	    
     <p>This is a paragraph containing some text.</p>
 
     <p>This paragraph contains some more text.</p>
 
     <p align="right">This paragraph might be right-justified.</p>
 
     <p>The current version of this document is: &version;</p>	  
   </body>	    
 </html>]]></programlisting>	  
 	</step>
 
 	<step>
 	  <para>Validate the document using &man.nsgmls.1;</para>
 	</step>
 
 	<step>
 	  <para>Load <filename>example.sgml</filename> into your web browser
 	    (you may need to copy it to <filename>example.html</filename>
 	    before your browser recognises it as an HTML document).</para>
 
 	  <para>Unless your browser is very advanced, you will not see the entity
 	    reference <literal>&amp;version;</literal> replaced with the
 	    version number.  Most web browsers have very simplistic parsers
 	    which do not handle proper SGML<footnote>
 	      <para>This is a shame.  Imagine all the problems and hacks (such
 		as Server Side Includes) that could be avoided if they
 		did.</para>
 	    </footnote>.</para>
 	</step>
 
 	<step>
 	  <para>The solution is to <emphasis>normalise</emphasis> your
 	    document using an SGML normaliser.  The normaliser reads in valid
 	    SGML and outputs equally valid SGML which has been transformed in
 	    some way.  One of the ways in which the normaliser transforms the
 	    SGML is to expand all the entity references in the document,
 	    replacing the entities with the text that they represent.</para>
 
 	  <para>You can use &man.sgmlnorm.1; to do this.</para>
 
           <screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen>
 
 	  <para>You should find a normalised (i.e., entity references
 	    expanded) copy of your document in
 	    <filename>example.html</filename>, ready to load into your web
 	    browser.</para>
 	</step>
 
 	<step>
 	  <para>If you look at the output from &man.sgmlnorm.1; you will see
 	    that it does not include a DOCTYPE declaration at the start.  To
 	    include this you need to use the <option>-d</option>
 	    option;</para>
 
           <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen>
 	</step>
       </procedure>
     </sect2>
   </sect1>
   
   <sect1>
     <title>Using entities to include files</title>
     
     <para>Entities (both <link
 	linkend="sgml-primer-general-entities">general</link> and <link
 	linkend="sgml-primer-parameter-entities">parameter</link>) are
       particularly useful when used to include one file inside another.</para>
 
     <sect2 id="sgml-primer-include-using-gen-entities">
       <title>Using general entities to include files</title>
       
       <para>Suppose you have some content for an SGML book organised into
 	files, one file per chapter, called
 	<filename>chapter1.sgml</filename>,
 	<filename>chapter2.sgml</filename>, and so forth, with a
 	<filename>book.sgml</filename> file that will contain these
 	chapters.</para>
 
       <para>In order to use the contents of these files as the values for your
 	entities, you declare them with the <literal>SYSTEM</literal> keyword.
 	This directs the SGML parser to use the contents of the named file as
 	the value of the entity.</para>
 
       <example>
 	<title>Using general entities to include files</title>
 	
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY chapter.1 SYSTEM "chapter1.sgml">
 <!ENTITY chapter.2 SYSTEM "chapter2.sgml">
 <!ENTITY chapter.3 SYSTEM "chapter3.sgml">
 <!-- And so forth -->
 ]>
 
 <html>
   <!-- Use the entities to load in the chapters -->
 
   &chapter.1;
   &chapter.2;
   &chapter.3;
 </html>]]></programlisting>
       </example>
       
       <warning>
 	<para>When using general entities to include other files within a
 	  document, the files being included
 	  (<filename>chapter1.sgml</filename>,
 	  <filename>chapter2.sgml</filename>, and so on) <emphasis>must
 	    not</emphasis> start with a DOCTYPE declaration.  This is a syntax
 	  error.</para>
       </warning>
     </sect2>
     
     <sect2>
       <title>Using parameter entities to include files</title>
       
       <para>Recall that parameter entities can only be used inside an SGML
 	context.  Why then would you want to include a file within an SGML
 	context?</para>
 
       <para>You can use this to ensure that you can reuse your general
 	entities.</para>
 
       <para>Suppose that you had many chapters in your document, and you
 	reused these chapters in two different books, each book organising the
 	chapters in a different fashion.</para>
 
       <para>You could list the entities at the top of each book, but this
 	quickly becomes cumbersome to manage.</para>
 
       <para>Instead, place the general entity definitions inside one file,
 	and use a parameter entity to include that file within your
 	document.</para>
 
       <example>
 	<title>Using parameter entities to include files</title>
 
 	<para>First, place your entity definitions in a separate file, called
 	  <filename>chapters.ent</filename>.  This file contains the
 	  following;</para>
 	  
 	<programlisting><![ CDATA [<!ENTITY chapter.1 SYSTEM "chapter1.sgml">
 <!ENTITY chapter.2 SYSTEM "chapter2.sgml">
 <!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting>
 
 	<para>Now create a parameter entity to refer to the contents of the
 	  file.  Then use the parameter entity to load the file into the
 	  document, which will then make all the general entities available
 	  for use.  Then use the general entities as before;</para>
 
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!-- Define a parameter entity to load in the chapter general entities -->
 <!ENTITY % chapters SYSTEM "chapters.ent">
 
 <!-- Now use the parameter entity to load in this file -->
 %chapters;
 ]>
 
 <html>
   &chapter.1;
   &chapter.2;
   &chapter.3;
 </html>]]></programlisting>
       </example>
     </sect2>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <sect3>
 	<title>Use general entities to include files</title>
 
 	<procedure>
 	  <step>
 	    <para>Create three files, <filename>para1.sgml</filename>,
 	      <filename>para2.sgml</filename>, and
 	      <filename>para3.sgml</filename>.</para>
 
 	    <para>Put content similar to the following in each file;</para>
 
 	    <programlisting><![ CDATA [<p>This is the first paragraph.</p>]]></programlisting>
 	  </step>
 
 	  <step>
 	    <para>Edit <filename>example.sgml</filename> so that it looks like
 	      this;</para>
 
 	    <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.sgml">
 <!ENTITY para2 SYSTEM "para2.sgml">
 <!ENTITY para3 SYSTEM "para3.sgml">
 ]>
 
 <html>
   <head>
     <title>An example HTML file</title>
   </head>
 
   <body>
     <p>The current version of this document is: &version;</p>
 
     &para1;
     &para2;
     &para3;
   </body>
 </html>]]></programlisting>
 	  </step>
 
 	  <step>
 	    <para>Produce <filename>example.html</filename> by normalising
 	      <filename>example.sgml</filename>.</para>
 
             <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen>
 	  </step>
 
 	  <step>
 	    <para>Load <filename>example.html</filename> in to your web
 	      browser, and confirm that the
 	      <filename>para<replaceable>n</replaceable>.sgml</filename> files
 	      have been included in <filename>example.html</filename>.</para>
 	  </step>
 	</procedure>
       </sect3>
 
       <sect3>
 	<title>Use parameter entities to include files</title>
 
 	<note>
 	  <para>You must have taken the previous steps first.</para>
 	</note>
 	
 	<procedure>
 	  <step>
 	    <para>Edit <filename>example.sgml</filename> so that it looks like
 	      this;</para>
 	    
 	    <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % entities SYSTEM "entities.sgml"> %entities;
 ]>
 
 <html>
   <head>
     <title>An example HTML file</title>
   </head>
 
   <body>
     <p>The current version of this document is: &version;</p>
 
     &para1;
     &para2;
     &para3;
   </body>
 </html>]]></programlisting>
 	  </step>
 
 	  <step>
 	    <para>Create a new file, <filename>entities.sgml</filename>, with
 	      this content:</para>
 
 	    <programlisting><![ CDATA [<!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.sgml">
 <!ENTITY para2 SYSTEM "para2.sgml">
 <!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting>
 	  </step>
 
 	  <step>
 	    <para>Produce <filename>example.html</filename> by normalising
 	      <filename>example.sgml</filename>.</para>
 
             <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen>
 	  </step>
 
 	  <step>
 	    <para>Load <filename>example.html</filename> in to your web
 	      browser, and confirm that the
 	      <filename>para<replaceable>n</replaceable>.sgml</filename> files
 	      have been included in <filename>example.html</filename>.</para>
 	  </step>
 	</procedure>
       </sect3>
     </sect2>
   </sect1>
   
   <sect1 id="sgml-primer-marked-sections">
     <title>Marked sections</title>
     
     <para>SGML provides a mechanism to indicate that particular pieces of the
       document should be processed in a special way.  These are termed
       <quote>marked sections</quote>.</para>
 
     <example>
       <title>Structure of a marked section</title>
 
       <programlisting>&lt;![ <replaceable>KEYWORD</replaceable> [
   Contents of marked section
 ]]&gt;</programlisting>
     </example>
 
     <para>As you would expect, being an SGML construct, a marked section
       starts with <literal>&lt!</literal>.</para>
 
     <para>The first square bracket begins to delimit the marked
       section.</para>
 
     <para><replaceable>KEYWORD</replaceable> describes how this marked
       section should be processed by the parser.</para>
 
     <para>The second square bracket indicates that the content of the marked
       section starts here.</para>
     
     <para>The marked section is finished by closing the two square brackets,
       and then returning to the document context from the SGML context with
       <literal>&gt;</literal></para>
     
     <sect2>
       <title>Marked section keywords</title>
       
       <sect3>
 	<title><literal>CDATA</literal>, <literal>RCDATA</literal></title>
 	
 	<para>These keywords denote the marked sections <emphasis>content
 	    model</emphasis>, and allow you to change it from the
 	  default.</para>
 	
 	<para>When an SGML parser is processing a document it keeps track
 	  of what is called the <quote>content model</quote>.</para>
 	
 	<para>Briefly, the content model describes what sort of content the
 	  parser is expecting to see, and what it will do with it when it
 	  finds it.</para>
 
 	<para>The two content models you will probably find most useful are
 	  <literal>CDATA</literal> and <literal>RCDATA</literal>.</para>
 	
 	<para><literal>CDATA</literal> is for <quote>Character Data</quote>.
 	  If the parser is in this content model then it is expecting to see
 	  characters, and characters only.  In this model the &lt; and &amp;
 	  symbols lose their special status, and will be treated as ordinary
 	  characters.</para>
 	
 	<para><literal>RCDATA</literal> is for <quote>Entity references and
 	  character data</quote> If the parser is in this content model then it
 	  is expecting to see characters <emphasis>and</emphasis> entities.
 	  &lt; loses its special status, but &amp; will still be treated as
 	  starting the beginning of a general entity.</para>
 	
 	<para>This is particularly useful if you are including some verbatim
 	  text that contains lots of &lt; and &amp; characters.  While you
 	  could go through the text ensuring that every &lt; is converted to a
 	  &amp;lt; and every &amp; is converted to a &amp;amp;, it can be
 	  easier to mark the section as only containing CDATA.  When the SGML
 	  parser encounters this it will ignore the &lt; and &amp; symbols
 	  embedded in the content.</para>
 
         <note>
           <para>When you use <literal>CDATA</literal> or
             <literal>RCDATA</literal> in examples of text marked up in SGML,
             keep in mind that the content of <literal>CDATA</literal> is not
             validated.  You have to check the included SGML text using other
             means.  You could, for example, write the example in another
             document, validate the example code, and then paste it to your
             <literal>CDATA</literal> content.</para>
         </note>
 	<!-- The nesting of CDATA within the next example is disgusting -->
 	  
 	<example>
 	  <title>Using a CDATA marked section</title>
 	  
 	  <programlisting>&lt;para>Here is an example of how you would include some text
   that contained many &amp;lt; and &amp;amp; symbols.  The sample
   text is a fragment of HTML.  The surrounding text (&lt;para> and
   &lt;programlisting>) are from DocBook.&lt;/para>
 
 &lt;programlisting>
-  &lt![ CDATA [  <![ CDATA [
+  &lt;![ CDATA [  <![ CDATA [
     <p>This is a sample that shows you some of the elements within
       HTML.  Since the angle brackets are used so many times, it is
       simpler to say the whole example is a CDATA marked section
       than to use the entity names for the left and right angle
       brackets throughout.</p>
 
     <ul>
       <li>This is a listitem</li>
       <li>This is a second listitem</li>
       <li>This is a third listitem</li>
     </ul>
 
     <p>This is the end of the example.</p>]]>
   ]]&gt;
 &lt/programlisting></programlisting>
 
 	  <para>If you look at the source for this document you will see this
 	    technique used throughout.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title><literal>INCLUDE</literal> and
 	  <literal>IGNORE</literal></title>
 	
 	<para>If the keyword is <literal>INCLUDE</literal> then the contents
 	  of the marked section will be processed.  If the keyword is
 	  <literal>IGNORE</literal> then the marked section is ignored and
 	  will not be processed.  It will not appear in the output.</para>
 
 	<example>
 	  <title>Using <literal>INCLUDE</literal> and
 	    <literal>IGNORE</literal> in marked sections</title>
 
 	  <programlisting>&lt;![ INCLUDE [
   This text will be processed and included.
 ]]&gt;
 
 &lt;![ IGNORE [
   This text will not be processed or included.
 ]]&gt;</programlisting>
 	</example>
 	
 	<para>By itself, this is not too useful.  If you wanted to remove text
 	  from your document you could cut it out, or wrap it in
 	  comments.</para>
 	  
 	<para>It becomes more useful when you realise you can use <link
 	    linkend="sgml-primer-parameter-entities">parameter entities</link>
 	  to control this.  Remember that parameter entities can only be used
 	  in SGML contexts, and the keyword of a marked section
 	  <emphasis>is</emphasis> an SGML context.</para>
 
 	<para>For example, suppose that you produced a hard-copy version of
 	  some documentation and an electronic version.  In the electronic
 	  version you wanted to include some extra content that was not to
 	  appear in the hard-copy.</para>
 
 	<para>Create a parameter entity, and set its value to
 	  <literal>INCLUDE</literal>.  Write your document, using marked
 	  sections to delimit content that should only appear in the
 	  electronic version.  In these marked sections use the parameter
 	  entity in place of the keyword.</para>
 
 	<para>When you want to produce the hard-copy version of the document,
 	  change the parameter entity's value to <literal>IGNORE</literal> and
 	  reprocess the document.</para>
 
 	<example>
 	  <title>Using a parameter entity to control a marked
 	    section</title>
 	  
 	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 &lt;!ENTITY % electronic.copy "INCLUDE">	     
 ]]&gt;
 
 ...
 
 &lt;![ %electronic.copy [
   This content should only appear in the electronic
   version of the document.
 ]]&gt;</programlisting>
 
 	  <para>When producing the hard-copy version, change the entity's
 	    definition to;</para>
 	  
-	  <programlisting>&lt!ENTITY % electronic.copy "IGNORE"></programlisting>
+	  <programlisting>&lt;!ENTITY % electronic.copy "IGNORE"></programlisting>
 
 	  <para>On reprocessing the document, the marked sections that use
 	    <literal>%electronic.copy</literal> as their keyword will be
 	    ignored.</para>
 	</example>
       </sect3>
     </sect2>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <procedure>
 	<step>
 	  <para>Create a new file, <filename>section.sgml</filename>, that
 	    contains the following;</para>
 
 	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 &lt;!ENTITY % text.output "INCLUDE">
 ]&gt;
 
 &lt;html>
   &lt;head>
     &lt;title>An example using marked sections&lt;/title>
   &lt;/head>
 
   &lt;body>	    
     &lt;p>This paragraph &lt;![ CDATA [contains many &lt;
       characters (&lt; &lt; &lt; &lt; &lt;) so it is easier
-      to wrap it in a CDATA marked section ]]&gt;&lt/p>
+      to wrap it in a CDATA marked section ]]&gt;&lt;/p>
 
     &lt;![ IGNORE [
     &lt;p>This paragraph will definitely not be included in the
       output.&lt;/p>
     ]]&gt;
 
     &lt;![ <![ CDATA [%text.output]]> [
     &lt;p>This paragraph might appear in the output, or it
       might not.&lt;/p>
 
     &lt;p>Its appearance is controlled by the <![CDATA[%text.output]]>
       parameter entity.&lt;/p>	    
     ]]&gt;
   &lt;/body>
 &lt;/html></programlisting>	    
 	</step>
 
 	<step>
 	  <para>Normalise this file using &man.sgmlnorm.1; and examine the
 	    output.  Notice which paragraphs have appeared, which have
 	    disappeared, and what has happened to the content of the CDATA
 	    marked section.</para>
 	</step>
 
 	<step>
 	  <para>Change the definition of the <literal>text.output</literal>
 	    entity from <literal>INCLUDE</literal> to
 	    <literal>IGNORE</literal>.  Re-normalise the file, and examine the
 	    output to see what has changed.  </para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
   
   <sect1>
     <title>Conclusion</title>
     
     <para>That is the conclusion of this SGML primer.  For reasons of space
       and complexity several things have not been covered in depth (or at
       all).  However, the previous sections cover enough SGML for you to be
       able to follow the organisation of the FDP documentation.</para>
   </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/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
index e982cd61f7..a414659b6b 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,5897 +1,5897 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="advanced-networking">
   <title>Advanced Networking</title>
 
   <sect1>
     <title>Synopsis</title>
 
     <para>This chapter will cover some of the more frequently used network
       services on Unix systems.  We will cover how to define, setup, test and
       maintain all of the network services that FreeBSD utilizes.  In addition,
       there have been example configuration files included throughout this
       chapter for you to benefit from.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The basics of gateways and routes.</para>
       </listitem>
 
       <listitem>
 	<para>How to make FreeBSD act as a bridge.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup a network file system.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup network booting on a diskless machine.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup a network information server for sharing user
 	  accounts.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup automatic network settings using DHCP.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup a domain name server.</para>
       </listitem>
 
       <listitem>
 	<para>How to synchronize the time and date, and setup a
 	  time server, with the NTP protocol.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup network address translation.</para>
       </listitem>
 
       <listitem>
 	<para>How to manage the <command>inetd</command> daemon.</para>
       </listitem>
 
       <listitem>
 	<para>How to connect two computers via PLIP</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>
     </itemizedlist>
   </sect1>
 
   <sect1 id="routing">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Coranth</firstname>
       	  <surname>Gryphon</surname>
 	  <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Gateways and Routes</title>
 
     <indexterm><primary>routing</primary></indexterm>
     <indexterm><primary>gateway</primary></indexterm>
     <indexterm><primary>subnet</primary></indexterm>
     <para>For one machine to be able to find another over a network, there 
       must be a
       mechanism in place to describe how to get from one to the other. This is
       called <firstterm>routing</firstterm>.  A <quote>route</quote> is a defined pair of addresses: a
       <quote>destination</quote> and a <quote>gateway</quote>.  The pair
       indicates that if you are trying to get to this
       <emphasis>destination</emphasis>, communicate through this
       <emphasis>gateway</emphasis>.  There are three types of destinations:
       individual hosts, subnets, and <quote>default</quote>.  The
       <quote>default route</quote> is used if none of the other routes apply.
       We will talk a little bit more about default routes later on.  There are
       also three types of gateways: individual hosts, interfaces (also called
       <quote>links</quote>), and Ethernet hardware addresses (MAC addresses).
     </para>
 
     <sect2>
       <title>An Example</title>
       
       <para>To illustrate different aspects of routing, we will use the
 	following example from <command>netstat</command>:</para>
 
       <screen>&prompt.user; netstat -r
 Routing tables
 
 Destination      Gateway            Flags     Refs     Use     Netif Expire
 
 default          outside-gw         UGSc       37      418      ppp0
 localhost        localhost          UH          0      181       lo0
 test0            0:e0:b5:36:cf:4f   UHLW        5    63288       ed0     77
 10.20.30.255     link#1             UHLW        1     2421 
 example.com      link#1             UC          0        0 
 host1            0:e0:a8:37:8:1e    UHLW        3     4601       lo0
 host2            0:e0:a8:37:8:1e    UHLW        0        5       lo0 =>
 host2.example.com link#1             UC          0        0
 224              link#1             UC          0        0</screen>
 	  
       <indexterm><primary>default route</primary></indexterm>
       <para>The first two lines specify the default route (which we
 	will cover in the <link linkend="routing-default">next
 	  section</link>) and the <hostid>localhost</hostid> route.</para>
 	  
       <indexterm><primary>loopback device</primary></indexterm>
       <para>The interface (<literal>Netif</literal> column) that it specifies
 	to use for <literal>localhost</literal> is
 	<devicename>lo0</devicename>, also known as the loopback device.  This
 	says to keep all traffic for this destination internal, rather than
 	sending it out over the LAN, since it will only end up back where it
 	started.</para>
       
       <indexterm>
         <primary>Ethernet</primary>
         <secondary>MAC address</secondary>
       </indexterm>
       <para>The next thing that stands out are the addresses beginning
 	with <hostid role="mac">0:e0:</hostid>.  These are Ethernet
 	hardware addresses, which are also known as MAC addresses.
 	FreeBSD will automatically identify any hosts
 	(<hostid>test0</hostid> in the example) on the local Ethernet and add
 	a route for that host, directly to it over the Ethernet interface,
 	<devicename>ed0</devicename>.  There is also a timeout
 	(<literal>Expire</literal> column) associated with this type of route,
 	which is used if we fail to hear from the host in a specific amount of
 	time.  In this case the route will be automatically deleted.  These
 	hosts are identified using a mechanism known as RIP (Routing
 	Information Protocol), which figures out routes to local hosts based
 	upon a shortest path determination.</para>
 
       <indexterm><primary>subnet</primary></indexterm>	  
       <para>FreeBSD will also add subnet routes for the local subnet (<hostid
 	  role="ipaddr">10.20.30.255</hostid> is the broadcast address for the
 	subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid
 	  role="domainname">example.com</hostid> is the domain name associated
 	with that subnet).  The designation <literal>link#1</literal> refers
 	to the first Ethernet card in the machine.  You will notice no
 	additional interface is specified for those.</para>
 	  
       <para>Both of these groups (local network hosts and local subnets) have
 	their routes automatically configured by a daemon called
 	<application>routed</application>.  If this is not run, then only 
 	routes which are statically defined (ie. entered explicitly) will
 	exist.</para>
 	  
       <para>The <literal>host1</literal> line refers to our host, which it
 	knows by Ethernet address.  Since we are the sending host, FreeBSD
 	knows to use the loopback interface (<devicename>lo0</devicename>)
 	rather than sending it out over the Ethernet interface.</para>
 	  
       <para>The two <literal>host2</literal> lines are an example of what
 	happens when we use an &man.ifconfig.8; alias (see the section of Ethernet for
 	reasons why we would do this).  The <literal>=&gt;</literal> symbol
 	after the <devicename>lo0</devicename> interface says that not only
 	are we using the loopback (since this is address also refers to the
 	local host), but specifically it is an alias.  Such routes only show
 	up on the host that supports the alias; all other hosts on the local
 	network will simply have a <literal>link#1</literal> line for
 	such.</para>
 	  
       <para>The final line (destination subnet <literal>224</literal>) deals
 	with MultiCasting, which will be covered in a another section.</para>
 	  
       <para>The other column that we should talk about are the
 	<literal>Flags</literal>.  Each route has different attributes that
 	are described in the column.  Below is a short table of some of these
 	flags and their meanings:</para>
 	  
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <tbody>
 	    <row>
 	      <entry>U</entry>
 	      <entry>Up: The route is active.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>H</entry>
 	      <entry>Host: The route destination is a single host.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>G</entry>
 	      <entry>Gateway: Send anything for this destination on to this
 		remote system, which will figure out from there where to send
 		it.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>S</entry>
 	      <entry>Static: This route was configured manually, not
 		automatically generated by the system.</entry>
 	    </row>
 	      
 	    <row>
 	      <entry>C</entry>
 	      <entry>Clone: Generates a new route based upon this route for
 		machines we connect to. This type of route is normally used
 		for local networks.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>W</entry>
 	      <entry>WasCloned: Indicated a route that was auto-configured
 		based upon a local area network (Clone) route.</entry>
 	    </row>
 	      
 	    <row>
 	      <entry>L</entry>
 	      <entry>Link: Route involves references to Ethernet
 		hardware.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
     
     <sect2 id="routing-default">
       <title>Default Routes</title>
       
       <indexterm><primary>default route</primary></indexterm>	  
       <para>When the local system needs to make a connection to remote host,
 	it checks the routing table to determine if a known path exists.  If
 	the remote host falls into a subnet that we know how to reach (Cloned
 	routes), then the system checks to see if it can connect along that
 	interface.</para>
 	  
       <para>If all known paths fail, the system has one last option: the
 	<quote>default</quote> route.  This route is a special type of gateway
 	route (usually the only one present in the system), and is always
 	marked with a <literal>c</literal> in the flags field.  For hosts on a
 	local area network, this gateway is set to whatever machine has a
 	direct connection to the outside world (whether via PPP link,
 	DSL, cable modem, T1, or another network interface).</para>
       
       <para>If you are configuring the default route for a machine which
 	itself is functioning as the gateway to the outside world, then the
 	default route will be the gateway machine at your Internet Service
 	Provider's (ISP) site.</para>
 	  
       <para>Let us look at an example of default routes.  This is a common
 	configuration:</para>
 	    
       <literallayout>
 [Local2]  &lt;--ether--&gt;  [Local1]  &lt;--PPP--&gt; [ISP-Serv]  &lt;--ether--&gt;  [T1-GW]
       </literallayout>
 	  
       <para>The hosts <hostid>Local1</hostid> and
 	<hostid>Local2</hostid> are at your site.
 	<hostid>Local1</hostid> is connected to an ISP via a dial up
 	PPP connection.  This PPP server computer is connected through
 	a local area network to another gateway computer with an
 	external interface to the ISPs Internet feed.</para>
       
       <para>The default routes for each of your machines will be:</para>
       
       <informaltable frame="none">
 	<tgroup cols="3">
 	  <thead>
 	    <row>
 	      <entry>Host</entry>
 	      <entry>Default Gateway</entry>
 	      <entry>Interface</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	      <entry>Local2</entry>
 	      <entry>Local1</entry>
 	      <entry>Ethernet</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>Local1</entry>
 	      <entry>T1-GW</entry>
 	      <entry>PPP</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
       
       <para>A common question is <quote>Why (or how) would we set the T1-GW to
 	be the default gateway for Local1, rather than the ISP server it is
 	connected to?</quote>.</para>
 	  
       <para>Remember, since the PPP interface is using an address on the ISP's
 	local network for your side of the connection, routes for any other
 	machines on the ISP's local network will be automatically generated.
 	Hence, you will already know how to reach the T1-GW machine, so there
 	is no need for the intermediate step of sending traffic to the ISP
 	server.</para>
 	  
       <para>As a final note, it is common to use the address <hostid
 	  role="ipaddr">X.X.X.1</hostid> as the gateway address for your local
 	network.  So (using the same example), if your local class-C address
 	space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was
 	using <hostid role="ipaddr">10.9.9</hostid> then the default routes
 	would be:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Host</entry>
 	      <entry>Default Route</entry>
 	    </row>
 	  </thead>
 	  <tbody>
 	    <row>
 	      <entry>Local2 (10.20.3.2)</entry>
 	      <entry>Local1 (10.20.30.1)</entry>
 	    </row>
 	    <row>
 	      <entry>Local1 (10.20.30.1, 10.9.9.30)</entry>
 	      <entry>T1-GW (10.9.9.1)</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
     
     <sect2>
       <title>Dual Homed Hosts</title>
       <indexterm><primary>dual homed hosts</primary></indexterm>	        
       <para>There is one other type of configuration that we should cover, and
 	that is a host that sits on two different networks. Technically, any
 	machine functioning as a gateway (in the example above, using a PPP
 	connection) counts as a dual-homed host.  But the term is really only
 	used to refer to a machine that sits on two local-area
 	networks.</para>
 	  
       <para>In one case, the machine has two Ethernet cards, each having an
 	address on the separate subnets.  Alternately, the machine may only
 	have one Ethernet card, and be using &man.ifconfig.8; aliasing.  The former is
 	used if two physically separate Ethernet networks are in use, the
 	latter if there is one physical network segment, but two logically
 	separate subnets.</para>
 	  
       <para>Either way, routing tables are set up so that each subnet knows
 	that this machine is the defined gateway (inbound route) to the other
 	subnet.  This configuration, with the machine acting as a Bridge
 	between the two subnets, is often used when we need to implement
 	packet filtering or firewall security in either or both
 	directions.</para>
 
       <para>If you want this machine to actually forward packets
         between the two interfaces, you need to tell FreeBSD to enable
         this ability.  
     </sect2>
 
     <sect2 id="dedicated-router">
       <title>Building a Router</title>
 
       <indexterm><primary>router</primary></indexterm>
 
       <para>A network router is simply a system that forwards packets
 	from one interface to another.  Internet standards and good
 	engineering practice prevent the FreeBSD Project from enabling
 	this by default in FreeBSD.  You can enable this feature by
 	changing the following variable to <literal>YES</literal> in
 	&man.rc.conf.5;:</para>
 
       <programlisting>gateway_enable=YES          # Set to YES if this host will be a gateway</programlisting>
 
       <para>This option will put the &man.sysctl.8; variable
 	<filename>net.inet.ip.forwarding</filename> to
 	<literal>1</literal>.  If you should need to stop routing
 	temporarily, you can reset this to 0 temporarily.</para>
 
       <para>Your new router will need routes to know where to send the
 	traffic.  If your network is simple enough you can use static
 	routes.  FreeBSD also comes with the standard BSD routing
 	daemon &man.routed.8;, which speaks RIP (both version 1 and
 	version 2) and IRDP.  For more complex situations you may want
 	to try <filename role="package">net/gated</filename>.</para>
 
       <para>Even when FreeBSD is configured in this way, it does not
 	completely comply with the Internet standard requirements for
 	routers.  It comes close enough for ordinary use,
 	however.</para>
     </sect2>
     
     <sect2>
       <title>Routing Propagation</title>
       <indexterm><primary>routing propagation</primary></indexterm>
       <para>We have already talked about how we define our routes to the
 	outside world, but not about how the outside world finds us.</para>
 	  
       <para>We already know that routing tables can be set up so that all
 	traffic for a particular address space (in our examples, a class-C
 	subnet) can be sent to a particular host on that network, which will
 	forward the packets inbound.</para>
 	  
       <para>When you get an address space assigned to your site, your service
 	provider will set up their routing tables so that all traffic for your
 	subnet will be sent down your PPP link to your site.  But how do sites
 	across the country know to send to your ISP?</para>
 	  
       <para>There is a system (much like the distributed DNS information) that
 	keeps track of all assigned address-spaces, and defines their point of
 	connection to the Internet Backbone.  The <quote>Backbone</quote> are
 	the main trunk lines that carry Internet traffic across the country,
 	and around the world.  Each backbone machine has a copy of a master
 	set of tables, which direct traffic for a particular network to a
 	specific backbone carrier, and from there down the chain of service
 	providers until it reaches your network.</para>
 	  
       <para>It is the task of your service provider to advertise to the
 	backbone sites that they are the point of connection (and thus the
 	path inward) for your site.  This is known as route
 	propagation.</para>
     </sect2>
     
     <sect2>
       <title>Troubleshooting</title>
       <indexterm>
         <primary><command>traceroute</command></primary>
       </indexterm>      
       <para>Sometimes, there is a problem with routing propagation, and some
 	sites are unable to connect to you.  Perhaps the most useful command
 	for trying to figure out where a routing is breaking down is the
 	  &man.traceroute.8; command.  It is equally useful if you cannot seem
 	to make a connection to a remote machine (i.e. &man.ping.8;
 	fails).</para>
 	  
       <para>The &man.traceroute.8; command is run with the name of the remote
 	host you are trying to connect to.  It will show the gateway hosts
 	along the path of the attempt, eventually either reaching the target
 	host, or terminating because of a lack of connection.</para>
 	  
       <para>For more information, see the manual page for
 	  &man.traceroute.8;.</para>
     </sect2>
   </sect1>
 
   <sect1 id="bridging">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Steve</firstname>
       	  <surname>Peterson</surname>
 	  <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Bridging</title>
 
     <sect2>
       <title>Introduction</title>
       <indexterm><primary>IP subnet</primary></indexterm>
       <indexterm><primary>bridge</primary></indexterm>
       <para>It is sometimes useful to divide one physical network (such as an
 	Ethernet segment) into two separate network segments without having
 	to create IP subnets and use a router to connect the segments
 	together.  A device that connects two networks together in this
 	fashion is called a bridge.  A FreeBSD system with two network
 	interface cards can act as a bridge.</para>
 
       <para>The bridge works by learning the MAC layer addresses 
 	(Ethernet addresses) of the devices on each of its network interfaces.
 	It forwards traffic between two networks only when its source and
 	destination are on different networks.</para>
 
       <para>In many respects, a bridge is like an Ethernet switch with very
 	few ports.</para>
     </sect2>
 
     <sect2>
       <title>Situations Where Bridging Is Appropriate</title>
 
       <para>There are two common situations in which a bridge is used
 	today.</para>
       
       <sect3>
 	<title>High Traffic on a Segment</title>
 
 	<para>Situation one is where your physical network segment is
 	  overloaded with traffic, but you do not want for whatever reason to
 	  subnet the network and interconnect the subnets with a
 	  router.</para>
 
 	<para>Let us consider an example of a newspaper where the Editorial and
 	  Production departments are on the same subnetwork.  The Editorial
 	  users all use server A for file service, and the Production users
 	  are on server B.  An Ethernet is used to connect all users together,
 	  and high loads on the network are slowing things down.</para>
 
 	<para>If the Editorial users could be segregated on one network
 	  segment and the Production users on another, the two network
 	  segments could be connected with a bridge.  Only the network traffic
 	  destined for interfaces on the "other" side of the bridge would be
 	  sent to the other network, reducing congestion on each network
 	  segment.</para>
       </sect3>
 
       <sect3>
 	<title>Filtering/Traffic Shaping Firewall</title>
 	<indexterm><primary>firewall</primary></indexterm>
 	<indexterm><primary>IP Masquerading</primary></indexterm>
 
 	<para>The second common situation is where firewall functionality is
 	  needed without IP Masquerading (NAT).</para>
 
 	<para>An example is a small company that is connected via DSL or ISDN
 	  to their ISP.  They have a 13 globally-accessible IP addresses
 	  from their ISP and have 10 PCs on their network.  In this situation, using a
 	  router-based firewall is difficult because of subnetting
 	  issues.</para>
 
 	<indexterm><primary>router</primary></indexterm>
 	<indexterm><primary>DSL</primary></indexterm>
 	<indexterm><primary>ISDN</primary></indexterm>
 	<para>A bridge-based firewall can be configured and dropped into the
 	  path just downstream of their DSL/ISDN router without any IP
 	  numbering issues.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Configuring a Bridge</title>
 
       <sect3>
 	<title>Network Interface Card Selection</title>
 
 	<para>A bridge requires at least two network cards to function.
 	  Unfortunately, not all network interface cards as of FreeBSD 4.0
 	  support bridging.  Read &man.bridge.4; for details on the cards that
 	  are supported.</para>
 
 	<para>Install and test the two network cards before continuing.</para>
       </sect3>
 
       <sect3>
 	<title>Kernel Configuration Changes</title>
 	<indexterm><primary>kernel configuration</primary></indexterm>
 	<indexterm>
 	  <primary>kernel configuration</primary>
 	  <secondary>options BRIDGE</secondary>
 	</indexterm>
 
 	<para>To enable kernel support for bridging, add the:</para>
 
 	<programlisting>options BRIDGE</programlisting>
 
 	<para>statement to your kernel configuration file, and rebuild your
 	  kernel.</para>
       </sect3>
 
       <sect3>
 	<title>Firewall Support</title>
 	<indexterm><primary>firewall</primary></indexterm>
 	<para>If you are planning to use the bridge as a firewall, you will
 	  need to add the <varname>IPFIREWALL</varname> option as well.  Read <xref
 	    linkend="firewalls"> for general information on configuring the
 	  bridge as a firewall.</para>
 
 	<para>If you need to allow non-IP packets (such as ARP) to flow
 	  through the bridge, there is an undocumented firewall option that
 	  must be set. This option is
 	  <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal>.  Note that this
 	  changes the default rule for the firewall to accept any packet.
 	  Make sure you know how this changes the meaning of your ruleset
 	  before you set it.</para>
       </sect3>
 
       <sect3>
 	<title>Traffic Shaping Support</title>
 
 	<para>If you want to use the bridge as a traffic shaper, you will need
 	  to add the <literal>DUMMYNET</literal> option to your kernel
 	  configuration.  Read &man.dummynet.4; for further
 	  information.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Enabling the Bridge</title>
 
       <para>Add the line:</para>
 
       <programlisting>net.link.ether.bridge=1</programlisting>
 
       <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at
 	runtime.  If you want the bridged packets to be filtered by &man.ipfw.8;, 
 	you should also add:</para>
 
       <programlisting>net.link.ether.bridge_ipfw=1</programlisting>
 
       <para>as well.</para>
     </sect2>
 
     <sect2>
       <title>Performance</title>
 
       <para>My bridge/firewall is a Pentium 90 with one 3Com 3C900B and one
 	3C905B.  The protected side of the network runs at 10mbps half duplex
 	and the connection between the bridge and my router (a Cisco 675) runs
 	at 100mbps full duplex.  With no filtering enabled, I have found that
 	the bridge adds about 0.4 milliseconds of latency to pings from the
 	protected 10mbps network to the Cisco 675.</para>
     </sect2>
 
     <sect2>
       <title>Other Information</title>
 
       <para>If you want to be able to telnet into the bridge from the network,
 	it is OK to assign one of the network cards an IP address.  The
 	consensus is that assigning both cards an address is a bad
 	idea.</para>
 
       <para>If you have multiple bridges on your network, there cannot be more
 	than one path between any two workstations.  Technically, this means
 	that there is no support for spanning tree link management.</para>
     </sect2>
   </sect1>
   
   <sect1 id="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>NFS</title>
 
     <indexterm><primary>NFS</primary></indexterm>
     <para>Among the many different file systems that FreeBSD supports is
       the Network File System, also known as <acronym>NFS</acronym>.
       <acronym>NFS</acronym> allows a system to share directories and files
       with others over a network. By using <acronym>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 setup 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 ZIP 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>
 
       <para>The server has to be running the following daemons:</para>
       <indexterm>
         <primary>NFS</primary>
         <secondary>server</secondary>
       </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">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Daemon</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  <tbody>
 	    <row>
 	      <entry>nfsd</entry> 
 	      <entry>The <acronym>NFS</acronym> daemon which services requests from
               the <acronym>NFS</acronym> clients.</entry>
 	    </row>
 	    <row>
 	      <entry>mountd</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>portmap</entry>
 	      <entry> The portmapper 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="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>portmap_enable="YES"
 nfs_server_enable="YES"
 mountd_flags="-r"</programlisting>
 
       <para><command>mountd</command> 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>Examples of exporting filesystems</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 file system read-only.  With this flag, the
 	remote system will not be able to write any changes to the
 	exported file system.</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 -maproot=root flag is not specified, then even if
         a user has <username>root</username> access on the remote system, they 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 valid:</para>
 
       <programlisting>/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
         <command>mountd</command> whenever you modify
         <filename>/etc/exports</filename> so the changes can take effect.
         This can be accomplished by sending the hangup 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>portmap</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 <literal>server</literal> and the client's
 	name will be <literal>client</literal>.  If you only want to
 	temporarily mount a remote file system 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 filesystems</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>You can use an exported CDROM to install
             software on multiple machines.</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="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>amd</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>
 
 	<screen>&prompt.user; <userinput>showmount -e foobar</userinput>
 Exports list on foobar:
 /usr                               10.10.10.0
 /a                                 10.10.10.0
 &prompt.user; cd /host/foobar/usr</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 through the
 	<filename>rc.conf</filename> system 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; man pages for more
 	information.</para>
     </sect2>
 
     <sect2 id="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 file system 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 mount
 	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 UDP 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 file system.  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 freebox:</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 8k (though it
 	may do fragments of smaller sizes).  Since the maximum Ethernet
 	packet is around 1500 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 8K 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="diskless">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Jean-Fran&ccedil;ois</firstname>
           <surname>Dock&egrave;s</surname>
           <contrib>Updated by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Diskless Operation</title>
     
     <indexterm><primary>diskless workstation</primary></indexterm>
     <indexterm><primary>diskless operation</primary></indexterm>
 
     <para>A FreeBSD machine can boot over the network and operate without a
       local disk, using file systems mounted from an NFS server. No system
       modification is necessary, beyond standard configuration files.
       Such a system is easy to  set up because all the necessary elements
       are readily available:</para>
     <itemizedlist>
       <listitem>
 	<para>There are at least two possible methods to load the kernel over
 	  the network:</para>
 	<itemizedlist>
 	  <listitem>
 	    <para><emphasis>PXE</emphasis>: Intel's Preboot Execution
 	      Environment system is a form of smart boot ROM built into some
 	      networking cards or motherboards. See &man.pxeboot.8; for more
 	      details.</para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>The <application>etherboot</application>
 		port</emphasis> (<filename>/usr/ports/net/etherboot</filename>)
 	      produces ROM-able code to boot kernels over the network. The code
 	      can be either burnt into a boot PROM on a network card, or loaded
 	      from a local floppy (or hard) disk drive, or from a running
 	      MS-DOS system. Many network cards are supported.</para>
 	  </listitem>
 	</itemizedlist>
 	</listitem>
 
       <listitem>
 	<para>A sample script
 	  (<filename>/usr/share/examples/diskless/clone_root</filename>) eases
 	  the creation and maintenance of the workstation's root filesystem
 	  on the server. The script will probably require a little
 	  customization but it will get you started very quickly</para>
       </listitem>
 
       <listitem>
 	<para>Standard system startup files exist in <filename>/etc</filename>
 	  to detect and support a diskless system startup.</para>
       </listitem>
     
       <listitem>
 	<para>Swapping, if needed, can be done either to an NFS file or to
 	  a local disk</para>
       </listitem>
     </itemizedlist>
 
     <para>There are many ways to set up diskless workstations. Many
       elements are involved, and most can be customized to suit local
       taste. The following will describe the setup of a complete system,
       emphasizing simplicity and compatibility with the
       standard FreeBSD startup scripts. The system described has the
       following characteristics:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The diskless workstations use a shared
 	  read-only <filename>root</filename> filesystem, and a shared
 	  read-only <filename>/usr</filename>.</para>
 	<para>The <filename>root</filename> file system is a copy of a
 	  standard FreeBSD root (typically the server's), with some
 	  configuration files overridden by ones specific to diskless
 	  operation or, possibly, to the workstation they belong to.</para>
 	<para>The parts of the <filename>root</filename> which have to be
 	  writable are overlaid with &man.mfs.8; filesystems. Any changes
 	  will be lost when the system reboots.</para>
       </listitem>
       <listitem>
 	<para>The kernel is loaded by <application>etherboot
 	  </application>, using DHCP (or BOOTP) and TFTP.</para>
       </listitem>
     </itemizedlist>
 
     <caution><para>As described, this system is insecure.  It should
 	live in a protected area of a network, and be untrusted by
 	other hosts.</para>
     </caution>
 
 
     <sect2>
       <title>Setup Instructions</title>
 
       <sect3>
 	<title>Configuring DHCP/BOOTP</title>
 
 	<para>There are two protocols that are commonly used to boot a
 	  workstation that retrieves its configuration over the network: BOOTP
 	  and DHCP. They are used at several points in the workstation
 	  bootstrap:</para>
 	<itemizedlist>
 	  <listitem><para><application>etherboot</application> uses
 	      DHCP (by default) or BOOTP (needs a configuration option) to
 	      find the kernel. (PXE uses DHCP).</para>
 	  </listitem>
 	  <listitem><para>The kernel uses BOOTP to locate the NFS
 	      root.</para> 
 	  </listitem>
 	</itemizedlist>
 
 	<para>It is possible to configure a system to use only BOOTP.
 	  The &man.bootpd.8; server program is included in the
 	  base FreeBSD system.</para>
 
 	<para>However, DHCP has a number of advantages over BOOTP (nicer
 	  configuration files, possibility of using PXE, plus many others
 	  not directly related to diskless operation), and we shall describe
 	  both a pure BOOTP, and a BOOTP+DHCP configuration, with an
 	  emphasis on the latter, which will use the ISC DHCP software
 	  package.</para>
 
 	<sect4>
 	  <title>Configuration Using ISC DHCP</title>
 
 	  <para>The <application>isc-dhcp</application> server can answer
 	    both BOOTP and DHCP requests.</para>
 
 	  <para>As of release 4.4, <application>isc-dhcp
   	    3.0</application> is not part of the base
 	    system. You will first need to install the
 	    <filename>/usr/ports/net/isc-dhcp3</filename> port or the
 	    corresponding package. Please refer to <xref linkend="ports">
 	    for general information about ports and packages.</para>
 
 	  <para>Once <application>isc-dhcp</application> is installed, it
 	    needs a configuration file to run, (normally named
 	    <filename>/usr/local/etc/dhcpd.conf</filename>). Here follows
 	    a commented example:</para>
 
           <programlisting>
           default-lease-time 600;
           max-lease-time 7200;
           authoritative;
 
           option domain-name "example.com";
           option domain-name-servers 192.168.4.1;
           option routers 192.168.4.1;
 
           subnet 192.168.4.0 netmask 255.255.255.0 {
             use-host-decl-names on; <co id="co-dhcp-host-name">
             option subnet-mask 255.255.255.0;
             option broadcast-address 192.168.4.255;
 
             host margaux {
               hardware ethernet 01:23:45:67:89:ab;
               fixed-address margaux.example.com;
               next-server 192.168.4.4;<co id="co-dhcp-next-server">
               filename "/tftpboot/kernel.diskless";<co id="co-dhcp-filename">
               option root-path "192.168.4.4:/data/misc/diskless";<co id="co-dhcp-root-path">
             }
           }
           </programlisting>
 
 	  <calloutlist>
 	    <callout arearefs="co-dhcp-host-name"><para>This option tells
 		<command>dhcpd</command> to send the value in the
 		<literal>host</literal> declarations as the hostname for the
 		diskless host. An alternate way would be to add an
 		<literal>option host-name
 		  <replaceable>margaux</replaceable></literal> inside the
 		host declarations.</para>
 	    </callout>
 	    
 	    <callout arearefs="co-dhcp-next-server"><para>The
 		<literal>next-server</literal> directive designates
 		the TFTP server (the default is to use the same host as the
 		DHCP server).</para>
 	    </callout>
 	    
 	    <callout arearefs="co-dhcp-filename"><para>The
 		<literal>filename</literal> directive defines the file that
 		<application>etherboot</application> will load as a
 		kernel. 
 		<note><para>PXE appears to prefer a relative file
 		    name, and it loads <command>pxeboot</command>, not the
 		    kernel (<literal>option filename
 		      "pxeboot"</literal>).</para>
 		</note>
 	      </para>
 	    </callout>
 	    
 	    <callout arearefs="co-dhcp-root-path"><para>The
 		<literal>root-path</literal> option defines the path to
 		the root filesystem, in usual NFS notation</para>
 	    </callout>
 	  </calloutlist>
 
 	</sect4>
 	<sect4>
 	  <title>Configuration Using BOOTP</title>
 
 	  <para>Here follows an equivalent <command>bootpd</command>
 	    configuration. This would be found in
 	    <filename>/etc/bootptab</filename>.</para>
 
 	  <para>Please note that <application>etherboot</application> must
 	  be compiled with the non-default option
 	  <literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP, and that PXE
 	  <emphasis>needs</emphasis> DHCP. The only obvious advantage of
 	  <application>bootpd</application> is that it exists in the base system.</para>
 
           <programlisting>
           .def100:\
             :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
             :sm=255.255.255.0:\
             :ds=192.168.4.1:\
             :gw=192.168.4.1:\
             :hd="/tftpboot":\
             :bf="/kernel.diskless":\
             :rp="192.168.4.4:/data/misc/diskless":
 
           margaux:ha=0123456789ab:tc=.def100
           </programlisting>
 	</sect4>
       </sect3>
 
       <sect3>
 	<title>Preparing a Boot Program with
 	  <application>Etherboot</application></title> 
 
 	<para><ulink url="http://etherboot.sourceforge.net">Etherboot's Web
 	  site</ulink> contains
 	  <ulink url="http://etherboot.sourceforge.net/doc/html/userman.html">
 	  extensive documentation</ulink> mainly intended for Linux
 	  systems, but nonetheless containing useful information. The following
 	  will just outline how you would use
 	  <application>etherboot</application> on a FreeBSD system.</para>
 
 	<para>You must first install - and possibly compile - the
 	  <application>etherboot</application> package. The
 	  <application>etherboot</application> port can normally be found in
 	  <filename>/usr/ports/net/etherboot</filename>. If the ports tree is
 	  installed on your system, just typing <literal>make</literal> in
 	  this directory should take care of everything. Else refer to 
 	  <xref linkend="ports"> for information about ports and
 	  packages.</para> 
 
 	<para>For our setup, we shall use a boot floppy. For other methods
 	  (PROM, or dos program), please refer to the
 	  <application>etherboot</application> documentation.</para> 
 
 	<para>To make a boot floppy, insert a floppy in the drive on the
 	  machine where you installed <application>etherboot</application>,
 	  then change your current directory to the <filename>src</filename>
 	  directory in the <application>etherboot</application> tree and
 	  type:</para> 
 
 	<screen>
 	  &prompt.root; <userinput>gmake bin32/<replaceable>devicetype</replaceable>.fd0</userinput>
 	</screen>
 
 	<para><replaceable>devicetype</replaceable> depends on the type of
 	  the Ethernet card in the diskless workstation. Refer to the
 	  <filename>NIC</filename> file in the same directory to determine the
 	  right <replaceable>devicetype</replaceable>.</para>
 
       </sect3>
 
 
       <sect3>
 	<title>Configuring the TFTP and NFS Servers</title> 
 
 	<para>You need to enable <command>tftpd</command> on the TFTP
 	  server:</para>
         <procedure>
           <step>
             <para>Create a directory from which <command>tftpd</command>
             will serve the files, ie: <filename>/tftpboot</filename></para>
           </step>
             
           <step>
             <para>Add this line to your
 	      <filename>/etc/inetd.conf</filename>:</para> 
 	    
 	    <programlisting>tftp    dgram   udp     wait    nobody  /usr/libexec/tftpd    tftpd /tftpboot</programlisting>
 
 	    <note><para>It appears that at least some PXE versions want
 		the TCP version of TFTP. In this case, add a second line,
 		replacing <literal>dgram udp</literal> with <literal>stream
 		tcp</literal></para> 
 	    </note>
           </step>
 	  <step>
 	    <para>Tell <command>inetd</command> to reread its configuration
 	      file:</para>
 	    <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
 	  </step>
         </procedure>
 
 	<para>You can place the <filename>tftpboot</filename>
 	  directory anywhere on the server. Make sure that the
 	  location is set in both <filename>inetd.conf</filename> and
 	  <filename>dhcpd.conf</filename>.</para>
 
 	<para>You also need to enable NFS service and export the
 	  appropriate filesystem on the NFS server</para>
 	
         <procedure>
           <step>
             <para>Add this to <filename>/etc/rc.conf</filename>:</para>
 	    <programlisting>nfs_server_enable="YES"</programlisting>
           </step>
             
           <step>
             <para>Export the filesystem where the diskless root directory
 	      is located by adding the following to
 	      <filename>/etc/exports</filename> (adjust the volume mount
 	      point and workstation name!):</para>
 	    <programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux</replaceable></programlisting>
           </step>
 	  <step>
 	    <para>Tell <command>mountd</command> to reread its configuration
 	      file. If you actually needed to configure NFS service at step
 	      1, you probably want to reboot instead.</para>
 	    <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
 	  </step>
         </procedure>
 
       </sect3>
 
       <sect3>
 	<title>Building a Diskless Kernel</title>
 
 	<para>Create a kernel configuration file for the diskless client
 	  with the following options (in addition to the usual
 	  ones):</para>
 
 	<programlisting>
           options     BOOTP          # Use BOOTP to obtain IP address/hostname
           options     BOOTP_NFSROOT  # NFS mount root filesystem using BOOTP info
           options     BOOTP_COMPAT   # Workaround for broken bootp daemons.
 	</programlisting>
 
 	<para>You may also want to use <literal>BOOTP_NFSV3</literal> and
 	  <literal>BOOTP_WIRED_TO</literal> (refer to <filename>LINT</filename>).</para>
 
 	<para>Build the kernel (See <xref linkend="kernelconfig">),
 	  and copy it to the tftp directory, under the name listed
 	  in <filename>dhcpd.conf</filename></para>
 
 	  
       </sect3>
 
       <sect3>
 	  <title>Preparing the root Filesystem</title>
 
 	<para>You need to create a root filesystem for the diskless
 	  workstations, in the location listed as
 	  <literal>root-path</literal> in
 	  <filename>dhcpd.conf</filename>.</para>
 
 	<para>The easiest way to do this is to use the
 	  <filename>/usr/share/examples/diskless/clone_root</filename>
 	  shell script. This script needs customization, at least to adjust the
 	  place where the filesystem will be created (the
 	  <literal>DEST</literal> variable).
 
 	<para>Refer to the comments at the top of the script for
 	    instructions. They explain how the base filesystem is built,
 	    and how files may be selectively overridden by versions specific
 	    to diskless operation, to a subnetwork, or to an individual
 	    workstation. They also give examples for the diskless
 	    <filename>/etc/fstab</filename> and <filename>
 	    /etc/rc.conf</filename></para> 
 
 	  <para>The README files in 
 	    <filename>/usr/share/examples/diskless</filename> contain a lot
 	    of interesting background information, but, together with the
 	    other examples in the <filename>diskless</filename> directory,
 	    they actually document a configuration method which is distinct
 	    from the one used by <filename>clone_root</filename> and
 	    <filename>/etc/rc.diskless[12]</filename>, which is a little
 	    confusing. Use them for reference only, except if you prefer
 	    the method that they describe, in which case you will need
 	    customized <filename>rc</filename> scripts</para>
 
 	<para>As of FreeBSD version 4.4-RELEASE, there is a small
 	    incompatibility between the <filename>clone_root</filename>
 	    script and the <filename>/etc/rc.diskless1</filename>
 	    script. Please refer to PR 
 	    <ulink url="http://www.freebsd.org/cgi/query-pr.cgi?pr=31200"> 
 	      conf/31200</ulink> for the small adjustment needed in
 	    <filename>clone_root</filename>.
 	    Also see PR 
 	    <ulink url="http://www.freebsd.org/cgi/query-pr.cgi?pr=29870">conf/29870</ulink>
 	    about a small adjustment needed in
 	    <filename>/etc/rc.diskless2</filename>.
 	  </para> 
       </sect3>
 
       <sect3>
 	<title>Configuring Swap</title>
 
 	<para>If needed, a swap file located on the server can be
 	  accessed via NFS.  The exact <filename>bootptab</filename>
 	  or <filename>dhcpd.conf</filename> options are not clearly
 	  documented at this time.  The following configuration
 	  suggestions have been reported to work in some installations
 	  using isc-dhcp 3.0rc11.</para>
 	<procedure>
 	  <step><para>Add the following lines to
 	  <filename>dhcpd.conf</filename>:</para> 
 	    <programlisting>
               # Global section
               option swap-path code 128 = string;
               option swap-size code 129 = integer 32;
 
               host margaux {
                 ... # Standard lines, see above
                 option swap-path <replaceable>"192.168.4.4:/netswapvolume/netswap"</replaceable>;
                 option swap-size <replaceable>64000</replaceable>;
               }
 	    </programlisting>
 	    <para>The idea is that, at least for a FreeBSD client,
 	      DHCP/BOOTP option code 128 is the path to the NFS swap file,
 	      and option code 129 is the swap size in kilobytes. Older
 	      versions of <command>dhcpd</command> allowed a syntax of
 	      <literal>option option-128 "...</literal>, which does not
 	      seem to work any more.</para>
 	    <para><filename>/etc/bootptab</filename> would use the
 	      following syntax instead:</para>
 
 	    <para><literal>T128="192.168.4.4:/netswapvolume/netswap":T129=64000
 	      </literal></para>
 	  </step>
 
 	  <step>
 	    <para>On the NFS swap file server, create the swap
 	    file(s)</para>
             <screen>
               &prompt.root; <userinput>mkdir <replaceable>/netswapvolume/netswap</replaceable></userinput>
               &prompt.root; <userinput>cd <replaceable>/netswapvolume/netswap</replaceable></userinput>
               &prompt.root; <userinput>dd if=/dev/zero bs=1024 count=<replaceable>64000</replaceable> of=swap.<replaceable>192.168.4.6</replaceable></userinput>
               &prompt.root; <userinput>chmod 0600 swap.<replaceable>192.168.4.6</replaceable></userinput>
             </screen>
 	    <para><replaceable>192.168.4.6</replaceable> is the IP address
 	      for the diskless client</para>
 	  </step>
 
 	  <step>
 	    <para>On the NFS swap file server, add the following line to
 	    <filename>/etc/exports</filename></para>
 	    <programlisting>
 	      <replaceable>/netswapvolume</replaceable>  -maproot=0:10 -alldirs <replaceable>margaux</replaceable> 
 	    </programlisting>
 	    <para>Then tell <application>mountd</application> to reread the 
 		exports file, as above.</para>
 	  </step>
 	</procedure>
 
       </sect3>
 
       <sect3>
 	<title>Miscellaneous Issues</title>
 
 	
 	<sect4>
 	  <title>Running with a read-only <filename>/usr</filename></title
 	    <para>If the diskless workstation is configured to run X, you
 	    will have to adjust the xdm configuration file, which puts 
 	    the error log on <filename>/usr</filename> by default.</para>
 	</sect4>
 	<sect4>
 	  <title>Using a non-FreeBSD Server</title>
 
 	  <para>When the server for the root filesystem is not running FreeBSD,
 	    you will have to create the root file system on a
 	    FreeBSD machine, then copy it to its destination, using
 	    <command>tar</command> or <command>cpio</command>.</para>
 	  <para>In this situation, there are sometimes 
 	    problems with the special files in <filename>/dev</filename>,
 	    due to differing major/minor integer sizes. A solution to this
 	    problem is to export a directory from the non-FreeBSD server,
 	    mount this directory onto a FreeBSD machine, and run
 	    <command>MAKEDEV</command> on the FreeBSD machine
 	    to create the correct device entries.</para>
 
 	</sect4>
 
       </sect3>
 
     </sect2>
   </sect1>
   
   <sect1 id="isdn">
     <title>ISDN</title>
     
     <para>A good resource for information on ISDN technology and hardware is
       <ulink url="http://alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN
 	Page</ulink>.</para>
 
     <para>A quick simple road map to ISDN follows:</para>
     
     <itemizedlist>
       <listitem>
         <para>If you live in Europe you might want to investigate the ISDN card
           section.</para>
       </listitem>
       
       <listitem>
 	<para>If you are planning to use ISDN primarily to connect to the
 	  Internet with an Internet Provider on a dial-up non-dedicated basis,
 	  you might look into Terminal Adapters.  This will give you the
 	  most flexibility, with the fewest problems, if you change
 	  providers.</para>
       </listitem>
       
       <listitem>
 	<para>If you are connecting two LANs together, or connecting to the
 	  Internet with a dedicated ISDN connection, you might consider
 	  the stand alone router/bridge option.</para>
       </listitem>
     </itemizedlist>
     
     <para>Cost is a significant factor in determining what solution you will
       choose.  The following options are listed from least expensive to most
       expensive.</para>
     
     <sect2 id="isdn-cards">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Hellmuth</firstname>
             <surname>Michaelis</surname>
             <contrib>Contributed by </contrib>
           </author>
         </authorgroup>
       </sect2info>
       <title>ISDN Cards</title>
       
       <indexterm>
         <primary>ISDN</primary>
         <secondary>cards</secondary>
       </indexterm>
 
       <para>FreeBSD's ISDN implementation supports only the DSS1/Q.931
 	(or Euro-ISDN) standard using passive cards. Starting with
 	FreeBSD 4.4, some active cards are supported where the firmware
 	also supports other signaling protocols; this also includes the
 	first supported Primary Rate (PRI) ISDN card.</para>
 
       <para><application>Isdn4bsd</application> allows you to connect
 	to other ISDN routers using either IP over raw HDLC or by using
 	synchronous PPP: either by using kernel PPP with isppp, a
 	modified sppp driver, or by using userland &man.ppp.8;. By using
 	userland &man.ppp.8;, channel bonding of two or more ISDN
 	B-channels is possible.  A telephone answering machine
 	application is also available as well as many utilities such as
 	a software 300 Baud modem.</para>
 
       <para>Some growing number of PC ISDN cards are supported under
 	FreeBSD and the reports show that it is successfully used all
 	over Europe and in many other parts of the world.</para>
 
       <para>The passive ISDN cards supported are mostly the ones with
 	the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets,
 	but also ISDN cards with chips from Cologne Chip (ISA bus only),
 	PCI cards with Winbond W6692 chips, some cards with the
 	Tiger300/320/ISAC chipset combinations and some vendor specific
 	chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the
 	AVM Fritz!Card PnP.</para>
 
       <para>Currently the active supported ISDN cards are the AVM B1
 	(ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para>
 
       <para>For documentation on <application>isdn4bsd</application>,
 	have a look at <filename>/usr/share/examples/isdn/</filename>
 	directory on your FreeBSD system or at the <ulink
 	  url="http://www.freebsd-support.de/i4b/">homepage of
 	  isdn4bsd</ulink> which also has pointers to hints, erratas and
 	much more documentation such as the <ulink
 	  url="http://people.FreeBSD.org/~hm/">isdn4bsd
 	  handbook</ulink>.</para>
 
       <para>In case you are interested in adding support for a
 	different ISDN protocol, a currently unsupported ISDN PC card or
 	otherwise enhancing <application>isdn4bsd</application>, please
 	get in touch with &a.hm;.</para>
 
       <para>For questions regarding the installation, configuration
 	and troubleshooting <application>isdn4bsd</application>, a
 	majordomo maintained mailing list is available. To join, send
 	mail to &a.majordomo; and specify:</para>
 
       <para><literal>subscribe freebsd-isdn</literal></para>
 
       <para>in the body of your message.</para>
     </sect2>
     
     <sect2>
       <title>ISDN Terminal Adapters</title>
 
       <para>Terminal adapters(TA), are to ISDN what modems are to regular
 	phone lines.</para>
       <indexterm><primary>modem</primary></indexterm>
       <para>Most TA's use the standard hayes modem AT command set, and can be
 	used as a drop in replacement for a modem.</para>
 	  
       <para>A TA will operate basically the same as a modem except connection
 	and throughput speeds will be much faster than your old modem.  You
 	will need to configure <link linkend="ppp">PPP</link> exactly the same
 	as for a modem setup.  Make sure you set your serial speed as high as
 	possible.</para>
       <indexterm><primary>PPP</primary></indexterm>	  
       <para>The main advantage of using a TA to connect to an Internet
 	Provider is that you can do Dynamic PPP.  As IP address space becomes
 	more and more scarce, most providers are not willing to provide you
 	with a static IP anymore.  Most stand-alone routers are not able to
 	accommodate dynamic IP allocation.</para>
       
       <para>TA's completely rely on the PPP daemon that you are running for
 	their features and stability of connection.  This allows you to
 	upgrade easily from using a modem to ISDN on a FreeBSD machine, if you
 	already have PPP setup.  However, at the same time any problems you
 	experienced with the PPP program and are going to persist.</para>
 	  
       <para>If you want maximum stability, use the kernel <link
 	  linkend="ppp">PPP</link> option, not the user-land <link
 	  linkend="userppp">iijPPP</link>.</para>
 	  
       <para>The following TA's are know to work with FreeBSD.</para>
 	  
       <itemizedlist>
 	<listitem>
 	  <para>Motorola BitSurfer and Bitsurfer Pro</para>
 	</listitem>
 
 	<listitem>
 	  <para>Adtran</para>
 	</listitem>
       </itemizedlist>
       
       <para>Most other TA's will probably work as well, TA vendors try to make
 	sure their product can accept most of the standard modem AT command
 	set.</para>
 	  
       <para>The real problem with external TA's is like modems you need a good
 	serial card in your computer.</para>
 	  
       <para>You should read the <ulink
 	url="../../articles/serial-uart/index.html">FreeBSD Serial
 	Hardware</ulink> tutorial for a detailed understanding of
 	serial devices, and the differences between asynchronous and
 	synchronous serial ports.</para>
       
       <para>A TA running off a standard PC serial port (asynchronous) limits
 	you to 115.2Kbs, even though you have a 128Kbs connection. To fully
 	utilize the 128Kbs that ISDN is capable of, you must move the TA to a
 	synchronous serial card.</para>
 	  
       <para>Do not be fooled into buying an internal TA and thinking you have
 	avoided the synchronous/asynchronous issue.  Internal TA's simply have
 	a standard PC serial port chip built into them.  All this will do, is
 	save you having to buy another serial cable, and find another empty
 	electrical socket.</para>
 	  
       <para>A synchronous card with a TA is at least as fast as a stand-alone
 	router, and with a simple 386 FreeBSD box driving it, probably more
 	flexible.</para>
 	  
       <para>The choice of sync/TA v.s. stand-alone router is largely a
 	religious issue.  There has been some discussion of this in
 	the mailing lists.  I suggest you search the <ulink
 	url="../../../../search/index.html">archives</ulink> for
 	the complete discussion.</para>
     </sect2>
     
     <sect2>
       <title>Stand-alone ISDN Bridges/Routers</title>
       <indexterm>
         <primary>ISDN</primary>
 	<secondary>stand-alone bridges/routers</secondary>
       </indexterm>	        
       <para>ISDN bridges or routers are not at all specific to FreeBSD
 	or any other operating system.  For a more complete
 	description of routing and bridging technology, please refer
 	to a Networking reference book.</para>
 	  
       <para>In the context of this page, the terms router and bridge will
 	be used interchangeably.</para>
 	  
       <para>As the cost of low end ISDN routers/bridges comes down, it
 	will likely become a more and more popular choice.  An ISDN
 	router is a small box that plugs directly into your local
 	Ethernet network, and manages its own connection to the other
 	bridge/router.  It has built in software to communicate via
 	PPP and other popular protocols.</para>
 	  
       <para>A router will allow you much faster throughput that a
 	standard TA, since it will be using a full synchronous ISDN
 	connection.</para>
 	  
       <para>The main problem with ISDN routers and bridges is that
 	interoperability between manufacturers can still be a problem.
 	If you are planning to connect to an Internet provider, you
 	should discuss your needs with them.</para>
 	  
       <para>If you are planning to connect two LAN segments together,
 	such as your home LAN to the office LAN, this is the simplest 
 	lowest
 	maintenance solution.  Since you are buying the equipment for
 	both sides of the connection you can be assured that the link
 	will work.</para>
 	  
       <para>For example to connect a home computer or branch office
 	network to a head office network the following setup could be
 	used.</para>
 	  
       <example>
 	<title>Branch Office or Home Network</title>
 
 	<indexterm><primary>10 base 2</primary></indexterm>	        
 	<para>Network uses a bus based topology with 10 base 2
 	  Ethernet ("thinnet").  Connect router to network cable with
 	  AUI/10BT transceiver, if necessary.</para>
 
         <mediaobject>
           <imageobject>
             <imagedata fileref="advanced-networking/isdn-bus">
           </imageobject>
 
 	  <textobject>
 	    <literallayout class="monospaced">---Sun workstation     
 |
 ---FreeBSD box
 |
 ---Windows 95 (Do not admit to owning it)
 |
 Stand-alone router
    |
 ISDN BRI line</literallayout>
           </textobject>
 
 	  <textobject>
 	    <phrase>10 Base 2 Ethernet</phrase>
 	  </textobject>
 	</mediaobject>
 
 	<para>If your home/branch office is only one computer you can use a
 	  twisted pair crossover cable to connect to the stand-alone router
 	  directly.</para>
       </example>
       
       <example>
 	<title>Head Office or Other LAN</title>
 
 	<indexterm><primary>10 base T</primary></indexterm>
 	<para>Network uses a star topology with 10 base T Ethernet
   	  ("Twisted Pair").</para>
 
         <mediaobject>
           <imageobject>
             <imagedata fileref="advanced-networking/isdn-twisted-pair">
           </imageobject>
 
 	  <textobject>
 	    <literallayout class="monospaced">    -------Novell Server
     | H |
     |   ---Sun      
     |   |
     | U ---FreeBSD
     |   |
     |   ---Windows 95
     | B |
     |___---Stand-alone router
                 |
         ISDN BRI line</literallayout>
 	  </textobject>
 
 	  <textobject>
 	    <phrase>ISDN Network Diagram</phrase>
 	  </textobject>
 	</mediaobject>
       </example>
       
       <para>One large advantage of most routers/bridges is that they allow you
 	to have 2 <emphasis>separate independent</emphasis> PPP connections to
 	2 separate sites at the <emphasis>same</emphasis> time.  This is not
 	supported on most TA's, except for specific (usually expensive) models
 	that
 	have two serial ports. Do not confuse this with channel bonding, MPP, 
 	etc.</para>
 	  
       <para>This can be very useful feature if, for example, you have an
 	dedicated ISDN connection at your office and would like to
 	tap into it, but do not want to get another ISDN line at work. A router
 	at the office location can manage a dedicated B channel connection
 	(64Kbps) to the Internet and use the other B channel for a
 	separate data connection.  The second B channel can be used for
 	dial-in, dial-out or dynamically bonding (MPP, etc.) with the first
 	B channel for more bandwidth.</para>
 
       <indexterm><primary>IPX/SPX</primary></indexterm>	  
       <para>An Ethernet bridge will also allow you to transmit more than just
 	IP traffic.  You can also send IPX/SPX or whatever other protocols you
 	use.</para>
     </sect2>
   </sect1>
 
   <sect1 id="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>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>NIS, 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 systems (Solaris, HP-UX, AIX, Linux,
         NetBSD, OpenBSD, FreeBSD, etc) support NIS.</para>
 
       <indexterm><primary>yellow pages</primary><see>NIS</see></indexterm>
       <para>NIS 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 Windows NT's 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 an NIS client:</para>
 
       <indexterm>
 	<primary><application>portmap</application></primary>
       </indexterm>
 
       <informaltable>
 	<tgroup cols="2">
 	  <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 NT domain name, the NIS
 		domainname does not have anything to do with DNS.</entry>
 	    </row>
 	    <row>
 	      <entry>portmap</entry>
 	      <entry>Must be running in order to enable RPC (Remote
 		Procedure Call, a network protocol used by NIS). If
 		<command>portmap</command> is not running, it will be
 		impossible to run an NIS server, or to act as an NIS
 		client.</entry>
 	    </row>
 	    <row>
 	      <entry>ypbind</entry>
 
 	      <entry><quote>binds</quote> an NIS client to its NIS
 		server.  It will take the NIS domainname from the
 		system, and using RPC, connect to the
 		server. <command>ypbind</command> is the core of
 		client-server communication in an NIS environment; if
 		<command>ypbind</command> dies on a client machine, it
 		will not be able to access the NIS server.</entry>
 	    </row>
 	    <row>
 	      <entry>ypserv</entry>
 	      <entry>Should only be running on NIS servers, 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
 		<command>ypbind</command> process on the client.
 	      </entry>
 	    </row>
 	    <row>
 	      <entry>rpc.yppasswdd</entry>
 	      <entry>Another process that should only be running on
 		NIS master servers, 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 Windows
               NT 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 NT's 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
               NT workstations, authenticate against the NIS server (or the NT
               domain controller in the NT Workstation 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 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>
           <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
 	    "acme-art" NIS domain.  For this example, assume you have
             chosen the name <emphasis>test-domain</emphasis>.</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
                 <emphasis>test-domain</emphasis>
                 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="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
             setup 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 root 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
             root 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 <emphasis>test-domain</emphasis> 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 `NOPUSH =
             "True"' (if it is not commented out already).</para>
         </sect4>
 
         <sect4>
 	  <title>Setting up a NIS Slave Server</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>configuring a 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 an 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="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 root, 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 securenets 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.  This allows the
 	administrator to use the <application>tcpwrapper</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>
           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
         <emphasis>-<replaceable>username</replaceable></emphasis> 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
         <emphasis>bill</emphasis> 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="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>
         <tgroup cols="2">
           <thead>
             <row>
               <entry>User Name(s)</entry>
               <entry>Description</entry>
             </row>
           </thead>
    
           <tbody>
             <row>
               <entry>alpha, beta</entry>
               <entry>Normal employees of the IT department</entry>
             </row>
             
             <row>
               <entry>charlie, delta</entry>
               <entry>The new apprentices of the IT department</entry>
             </row>
             
             <row>
               <entry>echo, foxtrott, golf, ...</entry>
               <entry>Ordinary employees</entry>
             </row>
             
             <row>
               <entry>able, baker, ...</entry>
               <entry>The current interns</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <informaltable>
         <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>war, death, famine, pollution</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>pride, greed, envy, wrath, lust, sloth</entry>
               <entry>Less important servers.  All members of the IT
                 department are allowed to login onto these machines.</entry>
             </row>
             
             <row>
               <entry>one, two, three, four, ...</entry>
               <entry>Ordinary workstations.  Only the
                 <emphasis>real</emphasis> employees are allowed to use
                 these machines.</entry>
             </row>
             
             <row>
               <entry>trashcan</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
         -<replaceable>user</replaceable> 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 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
         <replaceable>war</replaceable>, 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
         <replaceable>IT_EMP</replaceable> is imported into
         <replaceable>war</replaceable>'s password database and only
         these users are allowed to login.</para>
 
       <para>Unfortunately, this limitation also applies to the ~
 	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 passwd 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 /sbin/nologin 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 IT_INTERN, add the new IT interns to this
         netgroup and start to change the config 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
         <replaceable>BIGSRV</replaceable> to define the login
         restrictions for the important servers, another netgroup
         called <replaceable>SMALLSRV</replaceable> for the less
         important servers and a third netgroup called
         <replaceable>USERBOX</replaceable> 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 ``+''.  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 ALL-CAPS 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
         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
             <quote>jsmith</quote> 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, and it is probably the most important weakness. 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 ypserv 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="nis-server-is-client">
       <title>NIS Servers that are also NIS Clients</title>
 
       <para> Care must be taken when running ypserv 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 on 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>libscrypt v.s. libdescrypt</title>
       <indexterm>
         <primary>NIS</primary>
 	<secondary>crypto library</secondary>
       </indexterm>
       <para>One of the most common issues that people run into when trying
 	to implement NIS is crypt library compatibility.  If your NIS
 	server is using the DES crypt libraries, it will only support
 	clients that are using DES as well. To check which one your server
 	and clients are using look at the symlinks in
 	<filename>/usr/lib</filename>.  If the machine is configured to
 	use the DES libraries, it will look something like this:</para>
 
       <screen>&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
 lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 libcrypt.a@ -> libdescrypt.a
 lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 libcrypt.so@ -> libdescrypt.so
 lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 libcrypt.so.2@ -> libdescrypt.so.2
 lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 libcrypt_p.a@ -> libdescrypt_p.a
 -r--r--r--  1 root  wheel  13018 Nov  8 14:27 libdescrypt.a
 lrwxr-xr-x  1 root  wheel     16 Nov  8 14:27 libdescrypt.so@ -> libdescrypt.so.2
 -r--r--r--  1 root  wheel  12965 Nov  8 14:27 libdescrypt.so.2
 -r--r--r--  1 root  wheel  14750 Nov  8 14:27 libdescrypt_p.a</screen>
 
       <para>If the machine is configured to use the standard FreeBSD MD5
 	crypt libraries they will look something like this:</para>
 
       <screen>&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
 lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 libcrypt.a@ -> libscrypt.a
 lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 libcrypt.so@ -> libscrypt.so
 lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 libcrypt.so.2@ -> libscrypt.so.2
 lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 libcrypt_p.a@ -> libscrypt_p.a
 -r--r--r--  1 root  wheel   6194 Nov  8 14:27 libscrypt.a
 lrwxr-xr-x  1 root  wheel     14 Nov  8 14:27 libscrypt.so@ -> libscrypt.so.2
 -r--r--r--  1 root  wheel   7579 Nov  8 14:27 libscrypt.so.2
 -r--r--r--  1 root  wheel   6684 Nov  8 14:27 libscrypt_p.a</screen>
 
       <para>If you have trouble authenticating on an NIS client, this
         is a pretty good place to start looking for possible problems.
         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="dhcp">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Greg</firstname>
       	  <surname>Sutter</surname>
 	  <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>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 attempts to describe only the parts
         of the DHCP system that are integrated with FreeBSD; 
         consequently, the server portions are not described.  The DHCP
         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
         "lease" 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 sysinstall, 
           the first question asked is, "Do you want to try DHCP
           configuration of this interface?"  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>pseudo-device bpf</literal> 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
 		root).  <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.</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, <command>dhcpd</command>, is included
           as part of the <literal>isc-dhcp3</literal> port in the ports
           collection.  This port contains the full ISC DHCP distribution,
           consisting of client, server, relay agent 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/">dhcp.org</ulink>.</para>
     </sect2>
 
     <sect2 id="dhcp-server">
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Ceri</firstname>
 	    <surname>Davies</surname>
 	    <contrib>Written by </contrib>
 	    <affiliation>
 	      <address><email>ceri@FreeBSD.org</email></address>
 	    </affiliation>
 	  </author>
         </authorgroup>
       </sect2info>
 	<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</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>pseudo-device bpf</literal> 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</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 configuration</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 recognise 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 a hostname is OK 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 
 		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 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
 		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. The
 		dhcrelay(8) manual page provided with the
 		port contains more detail.</para>
 	    </listitem>
 	  </itemizedlist>
 	</sect3>
  
       </sect2>
 
   </sect1>
 
   <sect1 id="dns">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
           <surname>Lee</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>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>www.FreeBSD.org</hostid>
         will receive a reply with the IP address of The FreeBSD Project's 
         web server, whereas, a query for <hostid>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 dictates the DNS protocol.
       </para>
 
       <para>
         Currently, BIND is maintained by the <ulink 
         url="http://www.isc.org/">
         Internet Software Consortium (www.isc.org)</ulink>
       </para>
     </sect2>
 
     <sect2>
       <title>Terminology</title>
 
       <para>To understand this document, some terms related to DNS must be
 	understood.</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <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 for the particular zone
 		file</entry>
 	    </row>
 
 	    <row>
 	      <entry>named, bind, name server</entry>
 	      <entry>common names for the BIND name server package within 
 		FreeBSD</entry>
 	    </row>
 
 	    <indexterm><primary>resolver</primary></indexterm>
 	    <row>
 	      <entry>resolver</entry>
 	      <entry>a system process through which a
 		machine queries a name server for zone information</entry>
 	    </row>
 
 	    <indexterm><primary>reverse DNS</primary></indexterm>
 	    <row>
 	      <entry>reverse DNS</entry>
 	      <entry>the opposite of forward DNS, mapping of IP addresses to
 		hostnames</entry>
 	    </row>
 
 	    <indexterm><primary>root zone</primary></indexterm>
 	    <row>
 	      <entry>root zone</entry>
 
 	      <entry>literally, a <quote>.</quote>, refers to the
 		root, or beginning zone.  All zones fall under this, as
 		do all files in fall under the root directory.  It is
 		the beginning of the Internet zone hierarchy.</entry>
 	    </row>
 
 	    <row>
 	      <entry>zone</entry>
 	      <entry>Each individual domain, subdomain, or area dictated by 
 		DNS</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <indexterm>
 	<primary>zones</primary>
 	<secondary>examples</secondary>
       </indexterm>
 
       <para>Examples of zones:
       </para>
       <itemizedlist>
         <listitem>
           <para>. is the root zone</para>
         </listitem>
         <listitem>
           <para><hostid>org.</hostid> is a zone under the root zone</para>
         </listitem>
         <listitem>
           <para><hostid>example.org</hostid> is a zone under the org. zone</para>
         </listitem>
         <listitem>
           <para><hostid>foo.example.org.</hostid> is a subdomain, a zone under the 
              <hostid>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 3.2.1.* IP space.
           </para>
         </listitem>
       </itemizedlist>
 
       <para>As one can see, the more specific part of a hostname appears to 
         its left.  For example, <hostid>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>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
 	    then 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>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">
 	<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 named daemon is started at boot, put the following
          modifications 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>make-localhost</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>127.0.0.1 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="named-sandbox">Running named in a sandbox</link>.
 	</para>
 
 	<programlisting>/*
 zone "domain.com" {
         type slave;
         file "s/domain.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 example.org 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>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 +
 	    origin</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 exchange</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>example.org.</hostid></term>
 
 	    <listitem><para>the domain name, also the origin for this
 		zone file.</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><hostid>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 @
           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.  2001041002 would mean last modified 04/10/2001,
 		  the latter 02 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 <varname>NS</varname> 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
 	  <literal>example.org.</literal>
 	  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>ns1.example.org</hostid> would resolve to
           3.2.1.2.  Again, the origin symbol, <literal>@</literal>, is
           used here, thus meaning <hostid>example.org</hostid>
           would resolve to <hostid>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>example.org</hostid> (3.2.1.30).
           <varname>CNAME</varname>s can be used to provide alias
           hostnames, or round robin one hostname among multiple
           machines.
         </para>
 
         <programlisting>
 @               IN MX   10      mail.example.org.</programlisting>
 
         <para>
           The <varname>MX</varname> record indicates which mail servers are responsible
           for handling incoming mail for the zone.
           mail.example.org 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 example.org
           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 <varname>PTR</varname> entries instead of 
 	  <varname>A</varname> or <varname>CNAME</varname>.
         </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="named-sandbox">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Ceri</firstname>
             <surname>Davies</surname>
             <contrib>Contributed by </contrib>
           </author>
         </authorgroup>
       </sect2info>
 
       <title>Running named 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 root.</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>
 	  <para>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 && make clean all</userinput>
 &prompt.root; <userinput>cd /usr/src/lib/libbind && make clean all</userinput>
 &prompt.root; <userinput>cd /usr/src/libexec/named-xfer && 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>
          <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>This will clean out any <quote>cruft</quote> from your
                source tree, and retrying the steps above should then work.</para>
            </callout>
          </calloutlist>
 	</listitem>
 
 	<listitem>
 	  <para>Make a <devicename>dev/null</devicename> 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.  If this is something that you find useful, you
 	      may wish to add this entry to root's crontab, making use
 	      of the <option>@reboot</option> option. See
 	      &man.crontab.5; for more information regarding
 	      this.</para>
 	  </note>
 
 	</listitem>
 
 	<listitem>
 	  <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>
 	  <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 zonefile 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 zonefile 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
+	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 subscribe to <ulink 
         url="http://www.cert.org/">CERT</ulink> and
         <ulink url="../handbook/eresources.html#ERESOURCES-MAIL">freebsd-security-notifications</ulink>
         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 named would not hurt.</para></tip>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
       <para>
         BIND/named 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/resources/faqs/bind-faqs.html">
 	  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="ntp">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Hukins</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>NTP</title>
 
     <indexterm><primary>NTP</primary></indexterm>
 
     <sect2>
       <title>Overview</title>
 
       <para>Over time, a computer's clock is prone to drift.  As time
 	passes, the computer's clock becomes less accurate.  NTP
 	(Network Time Protocol) is one way to ensure your clock is
 	right.</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 modified since a
 	certain time.  Services such as &man.cron.8; run commands at a
 	given time.  If the clock is inaccurate, these commands may
 	not run when expected.</para>
 
       <indexterm>
 	<primary>NTP</primary>
 	<secondary>ntpd</secondary>
       </indexterm>
       <para>FreeBSD ships with the &man.ntpd.8; NTP server which can
 	be used to query other NTP 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 NTP servers to use.  Your network administrator or
 	ISP may have setup an NTP server for this purpose&mdash;check
 	their documentation to see if this is the case.  There is a
 	<ulink
 	url="http://www.eecis.udel.edu/~mills/ntp/servers.htm">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;.  &man.ntpd.8; 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
 	  <programlisting>ntpdate_enable="YES"</programlisting> 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.
 	  &man.ntpd.8; 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 &man.ntp.conf.5; 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 line <programlisting>restrict default ignore</programlisting>
 	  to <filename>/etc/ntp.conf</filename>.  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 <programlisting>restrict 192.168.1.0 mask 255.255.255.0 notrust nomodify notrap</programlisting>
 	  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 <programlisting>xntpd_enable="YES"</programlisting> to
 	<filename>/etc/rc.conf</filename>.  If you wish to pass
 	additional flags to &man.ntpd.8; edit the
 	<varname>xntpd_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>xntpd_flags</varname> in
 	<filename>/etc/rc.conf</filename>.  For example:</para>
       <screen>&prompt.root; <userinput>ntpd -p /var/run/ntpd.pid</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Using &man.ntpd.8; with a temporary Internet
 	connection</title>
 
       <para><command>ntpd</command> 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 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>
 
   <sect1 id="natd">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
           <surname>Lee</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Network Address Translation</title>
 
     <sect2 id="overview">
       <title>Overview</title>
       <indexterm>
         <primary><application>natd</application></primary>
       </indexterm>
       <para>FreeBSD's Network Address Translation daemon, commonly known as
         &man.natd.8; is a daemon that accepts incoming raw IP packets,
         changes the source to the local machine and re-injects these packets
         back into the outgoing IP packet stream. natd does this by changing 
         the source IP address and port such that when data is received back, it is 
         able to determine the original location of the data and forward it 
         back to its original requester.</para>
       <indexterm><primary>Internet connection sharing</primary></indexterm>
       <indexterm><primary>IP masquerading</primary></indexterm>
       <para>The most common use of NAT is to perform what is commonly known as
         Internet Connection Sharing.</para>
     </sect2>
 
     <sect2 id="setup">
       <title>Setup</title>
       <para>Due to the diminishing IP space in IPv4, and the increased number
         of users on high-speed consumer lines such as cable or DSL, people are
         increasingly in need of an Internet Connection Sharing solution.  The
         ability to connect several computers online through one connection and
         IP address makes &man.natd.8; a reasonable choice.</para>
 
       <para>Most commonly, a user has a machine connected to a cable or DSL
         line with one IP address and wishes to use this one connected computer to
         provide Internet access to several more over a LAN.</para>
 
       <para>To do this, the FreeBSD machine on the Internet must act as a 
         gateway.  This gateway machine must have two NICs--one for connecting
         to the Internet router, the other connecting to a LAN.  All the
         machines on the LAN are connected through a hub or switch.</para>
 
       <mediaobject>
         <imageobject>
           <imagedata fileref="advanced-networking/natd">
         </imageobject>
 
 	<textobject>
 	  <literallayout class="monospaced">  _______       __________       ________
  |       |     |          |     |        |
  |  Hub  |-----| Client B |-----| Router |----- Internet
  |_______|     |__________|     |________|
      |
  ____|_____
 |          |
 | Client A |
 |__________|</literallayout>
         </textobject>
 
 	<textobject>
 	  <phrase>Network Layout</phrase>
 	</textobject>
       </mediaobject>
 
       <para>A setup like this is commonly used to share an Internet
         connection.  One of the <acronym>LAN</acronym> machines is
         connected to the Internet.  The rest of the machines access
         the Internet through that <quote>gateway</quote>
         machine.</para>
     </sect2>
 
     <sect2 id="configuration">
       <indexterm>
         <primary>kernel</primary>
 	<secondary>configuration</secondary>
       </indexterm>
       <title>Configuration</title>
       <para>The following options must be in the kernel configuration
         file:</para>
       <programlisting>options IPFIREWALL
 options IPDIVERT</programlisting>
 
       <para>Additionally, at choice, the following may also be suitable:</para>
       <programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT
 options IPFIREWALL_VERBOSE</programlisting>
 
       <para>The following must be in <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>gateway_enable="YES"
 firewall_enable="YES"
 firewall_type="OPEN"
 natd_enable="YES"
 natd_interface="<replaceable>fxp0</replaceable>"
 natd_flags=""</programlisting>
 
       <informaltable frame="none">
         <tgroup cols="2">
           <tbody>
             <row>
               <entry>gateway_enable="YES"</entry>
               <entry>Sets up the machine to act as a gateway.  Running
                 <command>sysctl -w net.inet.ip.forwarding=1</command>
                 would have the same effect.</entry>
             </row>
             <row><entry>firewall_enable="YES"</entry>
              <entry>Enables the firewall rules in 
                <filename>/etc/rc.firewall</filename> at boot.</entry>
             </row>
             <row><entry>firewall_type="OPEN"</entry>
               <entry>This specifies a predefined firewall ruleset that
                 allows anything in.  See
                 <filename>/etc/rc.firewall</filename> for additional
                 types.</entry>
             </row>
             <row>
               <entry>natd_interface="fxp0"</entry>
               <entry>Indicates which interface to forward packets through. 
                 (the interface connected to the Internet)</entry>
             </row>
             <row>
               <entry>natd_flags=""</entry>
               <entry>Any additional configuration options passed to 
                 &man.natd.8; on boot.</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>Having the previous options defined in 
         <filename>/etc/rc.conf</filename> would run 
         <command>natd -interface fxp0</command> at boot.  This can also 
         be run manually.</para>
 
       <para>Each machine and interface behind the LAN should be assigned IP address 
         numbers in the private network space as defined by
         <ulink url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC 1918</ulink>
         and have a default gateway of the natd machine's internal IP address.</para>
 
       <para>For example, client a and b behind the LAN have IP addresses of 192.168.0.2
         and 192.168.0.3, while the natd machine's LAN interface has an IP address of
         192.168.0.1.  Client a and b's default gateway must be set to that of
         the natd machine, 192.168.0.1.  The natd machine's external, or 
         Internet interface does not require any special modification for natd
         to work.</para>
     </sect2>
 
     <sect2 id="port-redirection">
       <title>Port Redirection</title>
 
       <para>The drawback with natd is that the LAN clients are not accessible
         from the Internet. Clients on the LAN can make outgoing connections to
         the world but cannot receive incoming ones.  This presents a problem 
         if trying to run Internet services on one of the LAN client machines.
         A simple way around this is to redirect selected Internet ports on the
         natd machine to a LAN client.
       </para>
 
       <para>For example, an IRC server runs on Client A, and a web server runs
         on Client B.  For this to work properly, connections received on ports
         6667 (irc) and 80 (web) must be redirected to the respective machines.
       </para>
 
       <para>The <command>-redirect_port</command> must be passed to 
         &man.natd.8; with the proper options.  The syntax is as follows:</para>
       <para><programlisting>     -redirect_port proto targetIP:targetPORT[-targetPORT]
                  [aliasIP:]aliasPORT[-aliasPORT]
                  [remoteIP[:remotePORT[-remotePORT]]]</programlisting></para>
 
       <para>In the above example, the argument should be:
         <programlisting>    -redirect_port tcp 192.168.0.2:6667 6667
     -redirect_port tcp 192.168.0.3:80 80</programlisting>
         This will redirect the proper <emphasis>tcp</emphasis> ports to the 
         LAN client machines.
       </para>
 
       <para>The -redirect_port argument can be used to indicate port
         ranges over individual ports.  For example, <replaceable>tcp
         192.168.0.2:2000-3000 2000-3000</replaceable> would redirect
         all connections received on ports 2000 to 3000 to ports 2000
         to 3000 on Client A.</para>
 
       <para>These options can be used when directly running 
         &man.natd.8; or placed within the
         <programlisting>natd_flags=""</programlisting> option in 
         <filename>/etc/rc.conf</filename>.</para>
 
       <para>For further configuration options, consult &man.natd.8;</para>
     </sect2>
 
     <sect2 id="address-redirection">
       <title>Address Redirection</title>
       <indexterm><primary>address redirection</primary></indexterm>
       <para>Address redirection is useful if several IP addresses are available, yet
         they must be on one machine.  With this, &man.natd.8; can assign each
         LAN client its own external IP address.  &man.natd.8; then rewrites outgoing
         packets from the LAN clients with the proper external IP address and redirects
         all traffic incoming on that particular IP address back to the specific LAN 
         client.  This is also known as static NAT. For example, the IP addresses 
         128.1.1.1, 128.1.1.2, and 128.1.1.3 belong to the natd gateway 
         machine.  128.1.1.1 can be used as the natd gateway machine's external
         IP address, while 128.1.1.2 and 128.1.1.3 are forwarded back to LAN 
         clients A and B.</para>
 
       <para>The -redirect_address syntax is as follows:</para>
       <para><option> -redirect_address localIP publicIP</option>
       </para>
 
       <informaltable frame="none">
         <tgroup cols="2">
           <tbody>
             <row>
               <entry>localIP</entry>
               <entry>The internal IP address of the LAN client.</entry>
             </row>
             <row>
               <entry>publicIP</entry>
               <entry>The external IP address corresponding to the LAN client.</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>In the example, this argument would read:</para>
       <para><option>    -redirect_address 192.168.0.2 128.1.1.2
     -redirect_address 192.168.0.3 128.1.1.3</option></para>
 
       <para>Like -redirect_port, these arguments are also placed within 
         natd_flags of <filename>/etc/rc.conf</filename>.  With address 
         redirection, there is no need for port redirection since all data 
         received on a particular IP address is redirected.</para>
 
       <para>The external IP addresses on the natd machine must be active and aliased 
         to the external interface.  Look at &man.rc.conf.5; to do so.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="inetd">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
           <surname>Lee</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
 
     <title>inetd <quote>Super-Server</quote></title>
 
     <sect2 id="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
 	daemons.  Programs that provide network service are commonly
 	known as daemons.  <application>inetd</application> serves as a
 	managing server for other daemons.  When a connection is
 	received by <application>inetd</application>, it determines
 	which daemon the connection is destined for, spawns the
 	particular daemon and delegates the socket to it.  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="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
 	<quote>NO</quote> 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="inetd-cmdline">
       <title>Command-Line Options</title>
 
       <para><application>inetd</application> sypnosis:</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 in to <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 ``tcp4'' for the protocol and the other using
 	      ``tcp6''.</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 <quote>-wW</quote>,
 	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="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="inetd-hangup">
 	<title>Sending <application>inetd</application> a HangUP Signal</title>
 
-	<screen>&prompt.root kill -HUP `cat /var/run/inetd.pid`</screen>
+	<screen>&prompt.root; kill -HUP `cat /var/run/inetd.pid`</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
 	      UDP transport protocol.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>protocol</term>
 
 	  <listitem>
 	    <para>One of the following:</para>
 
 	    <informaltable>
 	      <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 wait
 	      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>The user 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 argv[0], passed to the daemon on
 	      invocation.  If <application>mydaemon -d</application> 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="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, and send a <link linkend="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>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="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
 	(ident, identd) 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="plip">
     <title>Parallel Line IP (PLIP)</title>
 
     <indexterm><primary>PLIP</primary></indexterm>
     <indexterm><primary>Parallel Line IP</primary></indexterm>
 
     <para>PLIP lets us run TCP/IP between parallel ports.  It is
       useful on machines without network cards, or to install on
       laptops.  In this section, we will discuss:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Creating a parallel (laplink) cable.</para>
       </listitem>
 
       <listitem>
 	<para>connecting two computers with PLIP.</para>
       </listitem>
     </itemizedlist>
 
     <sect2 id="create-parallel-cable">
       <title>Creating a Parallel Cable</title>
 
       <para>You can purchase a parallel cable at most computer supply
         stores.  If you can't do that, or you just want to know how
         it's done, here's how you make one out of a normal parallel
         printer cable.</para>
 
       <table>
 	<title>Wiring a parallel cable for networking</title>
 
 	<tgroup cols="5">
 	  <thead>
 	    <row>
 	      <entry>A-name</entry>
 
 	      <entry>A-End</entry>
 
 	      <entry>B-End</entry>
 
 	      <entry>Descr.</entry>
 
 	      <entry>Post/Bit</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><literallayout>DATA0
 -ERROR</literallayout></entry>
 
 	      <entry><literallayout>2
 15</literallayout></entry>
 
 	      <entry><literallayout>15
 2</literallayout></entry>
 
 	      <entry>Data</entry>
 
 	      <entry><literallayout>0/0x01
 1/0x08</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry><literallayout>DATA1
 +SLCT</literallayout></entry>
 
 	      <entry><literallayout>3
 13</literallayout></entry>
 
 	      <entry><literallayout>13
 3</literallayout></entry>
 
 	      <entry>Data</entry>
 
 	      <entry><literallayout>0/0x02
 1/0x10</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry><literallayout>DATA2
 +PE</literallayout></entry>
 
 	      <entry><literallayout>4
 12</literallayout></entry>
 
 	      <entry><literallayout>12
 4</literallayout></entry>
 
 	      <entry>Data</entry>
 
 	      <entry><literallayout>0/0x04
 1/0x20</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry><literallayout>DATA3
 -ACK</literallayout></entry>
 
 	      <entry><literallayout>5
 10</literallayout></entry>
 
 	      <entry><literallayout>10
 5</literallayout></entry>
 
 	      <entry>Strobe</entry>
 
 	      <entry><literallayout>0/0x08
 1/0x40</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry><literallayout>DATA4
 BUSY</literallayout></entry>
 
 	      <entry><literallayout>6
 11</literallayout></entry>
 
 	      <entry><literallayout>11
 6</literallayout></entry>
 
 	      <entry>Data</entry>
 
 	      <entry><literallayout>0/0x10
 1/0x80</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry>GND</entry>
 
 	      <entry>18-25</entry>
 
 	      <entry>18-25</entry>
 
 	      <entry>GND</entry>
 
 	      <entry>-</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
     </sect2>
 
     <sect2 id="plip-setup">
       <title>Setting up PLIP</title>
 
       <para>Get a laplink cable.</para>
 
       <para>Confirm that both computers have a kernel with lpt driver
 	support.</para>
 
       <screen>&prompt.root; <userinput>dmesg | grep lp</userinput>
 lpt0 at 0x378-0x37f irq 7 on isa
 lpt0: Interrupt-driven
 lp0: TCP/IP capable interface</screen>
 
       <para>Plug in the laplink cable into the parallel interface on
 	both computers.</para>
 
       <para>Configure the network interface parameters for lp0 on both
 	sites as root. For example, if you want connect the host host1
 	with host2</para>
 
       <programlisting>                 host1 &lt;-----&gt; host2
 IP Address    10.0.0.1      10.0.0.2</programlisting>
 
       <para>Configure the interface on host1 by doing:</para>
 
       <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.1 10.0.0.2</userinput></screen>
 
       <para>Configure the interface on host2 by doing:</para>
 
       <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.2 10.0.0.1</userinput></screen>
 
 
       <para>You now should have a working connection. Please read the
         man pages &man.lp.4; and &man.lpt.4; for more details.</para>
 
       <para>You should also add both hosts to
 	<filename>/etc/hosts</filename>.</para>
 
       <programlisting>127.0.0.1               localhost.my.domain localhost
 10.0.0.1                host1.my.domain host1
 10.0.0.2                host2.my.domain</programlisting>
 
       <para>To confirm the connection works, go to each host and ping
 	the other.  For example, on host1:</para>
 
           <screen>&prompt.root; <userinput>ifconfig lp</userinput>0
 lp0: flags=8851&lt;UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
         inet 10.0.0.1 --&gt; 10.0.0.2 netmask 0xff000000
 &prompt.root; <userinput>netstat -r</userinput>
 Routing tables
 
 Internet:
 Destination        Gateway          Flags     Refs     Use      Netif Expire
 host2              host1              UH          4   127592       lp0
 &prompt.root; <userinput>ping -c 4 host2</userinput>
 PING host2 (10.0.0.2): 56 data bytes
 64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
 
 --- host2 ping statistics ---
 4 packets transmitted, 4 packets received, 0% packet loss
 round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms</screen>
 
     </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/contrib/chapter.sgml b/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
index 11b96335df..ee4550f378 100644
--- a/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
@@ -1,480 +1,480 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="contrib">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Jordan</firstname>
 	<surname>Hubbard</surname>
 	<contrib>Contributed by </contrib>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Contributing to FreeBSD</title>
   
   <indexterm><primary>contributing</primary></indexterm>
   <para>So you want to contribute something to FreeBSD? That is great! We can
     always use the help, and FreeBSD is one of those systems that
     <emphasis>relies</emphasis> on the contributions of its user base in order
     to survive.  Your contributions are not only appreciated, they are vital
     to FreeBSD's continued growth!</para>
       
   <para>Contrary to what some people might also have you believe, you do not
     need to be a hot-shot programmer or a close personal friend of the FreeBSD
     core team in order to have your contributions accepted.  The FreeBSD
     Project's development is done by a large and growing number of
     international contributors whose ages and areas of technical expertise
     vary greatly, and there is always more work to be done than there are
     people available to do it.</para>
       
   <para>Since the FreeBSD project is responsible for an entire operating
     system environment (and its installation) rather than just a kernel or a
     few scattered utilities, our <filename>TODO</filename> list also spans a
     very wide range of tasks, from documentation, beta testing and
     presentation to highly specialized types of kernel development.  No matter
     what your skill level, there is almost certainly something you can do to
     help the project!</para>
       
   <para>Commercial entities engaged in FreeBSD-related enterprises are also
     encouraged to contact us.  Need a special extension to make your product
     work? You will find us receptive to your requests, given that they are not
     too outlandish.  Working on a value-added product? Please let us know! We
     may be able to work cooperatively on some aspect of it.  The free software
     world is challenging a lot of existing assumptions about how software is
     developed, sold, and maintained throughout its life cycle, and we urge you
     to at least give it a second look.</para>
       
   <sect1 id="contrib-what">
     <title>What Is Needed</title>
     
     <para>The following list of tasks and sub-projects represents something of
       an amalgam of the various core team <filename>TODO</filename> lists and
       user requests we have collected over the last couple of months.  Where
       possible, tasks have been ranked by degree of urgency.  If you are
       interested in working on one of the tasks you see here, send mail to the
       coordinator listed by clicking on their names.  If no coordinator has
       been appointed, maybe you would like to volunteer?</para>
 
     <sect2>
       <title>Ongoing Tasks</title>
       
       <para>Most of the tasks listed in the previous sections require either a
 	considerable investment of time or an in-depth knowledge of the
 	FreeBSD kernel (or both).  However, there are also many useful tasks
 	which are suitable for &quot;weekend hackers&quot;, or people without
 	programming skills.</para>
       
       <orderedlist>
 	<listitem>
 	  <para>If you run FreeBSD-current and have a good Internet
 	    connection, there is a machine <hostid
 	      role="fqdn">current.FreeBSD.org</hostid> which builds a full
 	    release once a day &mdash; every now and again, try and install
 	    the latest release from it and report any failures in the
 	    process.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Read the freebsd-bugs mailing list.  There might be a
 	    problem you can comment constructively on or with patches you
 	    can test.  Or you could even try to fix one of the problems
 	    yourself.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Read through the FAQ and Handbook periodically.  If anything
 	    is badly explained, out of date or even just completely wrong, let
 	    us know.  Even better, send us a fix (SGML is not difficult to
 	    learn, but there is no objection to ASCII submissions).</para>
 	</listitem>
 
 	<listitem>
 	  <para>Help translate FreeBSD documentation into your native language
 	    (if not already available) &mdash; just send an email to &a.doc;
 	    asking if anyone is working on it.  Note that you are not
 	    committing yourself to translating every single FreeBSD document
 	    by doing this &mdash; in fact, the documentation most in need of
 	    translation is the installation instructions.</para>
 	</listitem>
 
 	<listitem>
-	  <para>Read the freebsd-questions mailing list and &ng.misc
+	  <para>Read the freebsd-questions mailing list and &ng.misc;
 	    occasionally (or even regularly).  It can be very satisfying to
 	    share your expertise and help people solve their problems;
 	    sometimes you may even learn something new yourself! These forums
 	    can also be a source of ideas for things to work on.</para>
 	</listitem>
 
 	<listitem>
 	  <para>If you know of any bug fixes which have been successfully
 	    applied to -current but have not been merged into -stable after a
 	    decent interval (normally a couple of weeks), send the committer a
 	    polite reminder.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Move contributed software to <filename>src/contrib</filename>
 	    in the source tree.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Make sure code in <filename>src/contrib</filename> is up to
 	    date.</para>
 	</listitem>
 	      
 	<listitem>
 	  <para>Build the source tree (or just part of it) with extra warnings
 	    enabled and clean up the warnings.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Fix warnings for ports which do deprecated things like using
 	    gets() or including malloc.h.</para>
 	</listitem>
 
 	<listitem>
 	  <para>If you have contributed any ports, send your patches back to
 	    the original author (this will make your life easier when they
 	    bring out the next version)</para>
 	</listitem>
 
 	<listitem>
 	  <para>Suggest further tasks for this list!</para>
 	</listitem>
       </orderedlist>
     </sect2>
 
     <sect2>
       <title>Work through the PR Database</title>
 
       <indexterm><primary>problem reports database</primary></indexterm>
       <para>The <ulink
 	  url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD PR
 	  list</ulink> shows all the current active problem reports and
 	requests for enhancement that have been submitted by FreeBSD users.
 	Look through the open PRs, and see if anything there takes your
 	interest.  Some of these might be very simple tasks, that just need an
 	extra pair of eyes to look over them and confirm that the fix in the
 	PR is a good one.  Others might be much more complex.</para>
 
       <para>Start with the PRs that have not been assigned to anyone else, but
 	if one them is assigned to someone else, but it looks like something
 	you can handle, email the person it is assigned to and ask if you can
 	work on it&mdash;they might already have a patch ready to be tested,
 	or further ideas that you can discuss with them.</para>
     </sect2>
   </sect1>
   
   <sect1 id="contrib-how">
     <title>How to Contribute</title>
     
     <para>Contributions to the system generally fall into one or more of the
       following 6 categories:</para>
 
     <sect2 id="contrib-general">
       <title>Bug Reports and General Commentary</title>
       
       <para>An idea or suggestion of <emphasis>general</emphasis> technical
 	interest should be mailed to the &a.hackers;.  Likewise, people with
 	an interest in such things (and a tolerance for a
 	<emphasis>high</emphasis> volume of mail!) may subscribe to the
 	hackers mailing list by sending mail to &a.majordomo;.  See <link
 	  linkend="eresources-mail">mailing lists</link> for more information
 	about this and other mailing lists.</para>
 	  
       <para>If you find a bug or are submitting a specific change, please
 	report it using the &man.send-pr.1; program or its <ulink
 	  url="../../../../send-pr.html">WEB-based
 	  equivalent</ulink>.  Try to fill-in each field of the bug report.
 	Unless they exceed 65KB, include any patches directly in the report.
 	If the patch is suitable to be applied to the source tree put
 	<literal>[PATCH]</literal> in the synopsis of the report.
 	When including patches, <emphasis>do not</emphasis> use cut-and-paste
 	because cut-and-paste turns tabs into spaces and makes them unusable.
 	Consider compressing patches and using &man.uuencode.1; if they exceed
 	20KB.  Upload very large submissions to <ulink
 	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming/">ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming/</ulink>.</para>
 	  
       <para>After filing a report, you should receive confirmation along with
 	a tracking number.  Keep this tracking number so that you can update
 	us with details about the problem by sending mail to
 	<email>bug-followup@FreeBSD.org</email>.  Use the number as the
 	message subject, e.g.  <literal>"Re: kern/3377"</literal>.  Additional
 	information for any bug report should be submitted this way.</para>
 	  
       <para>If you do not receive confirmation in a timely fashion (3 days to
 	a week, depending on your email connection) or are, for some reason,
 	unable to use the &man.send-pr.1; command, then you may ask
 	someone to file it for you by sending mail to the &a.bugs;.</para>
     </sect2>
     
     <sect2>
       <title>Changes to the Documentation</title>
       
       <indexterm><primary>documentation submissions</primary></indexterm>
       <para>Changes to the documentation are overseen by the &a.doc;.  Send
 	submissions and changes (even small ones are welcome!) using
 	<command>send-pr</command> as described in <link
 	  linkend="contrib-general">Bug Reports and General
 	  Commentary</link>.</para>
     </sect2>
     
     <sect2>
       <title>Changes to Existing Source Code</title>
       
       <indexterm><primary>FreeBSD-current</primary></indexterm>
       <para>An addition or change to the existing source code is a somewhat
 	trickier affair and depends a lot on how far out of date you are with
 	the current state of the core FreeBSD development. There is a special
 	on-going release of FreeBSD known as <quote>FreeBSD-current</quote>
 	which is made available in a variety of ways for the convenience of
 	developers working actively on the system. See <link
 	  linkend="current">Staying current with FreeBSD</link> for more
 	information about getting and using FreeBSD-current.</para>
 	  
       <para>Working from older sources unfortunately means that your changes
 	may sometimes be too obsolete or too divergent for easy re-integration
 	into FreeBSD.  Chances of this can be minimized somewhat by
 	subscribing to the &a.announce; and the &a.current; lists, where
 	discussions on the current state of the system take place.</para>
 	  
       <para>Assuming that you can manage to secure fairly up-to-date sources
 	to base your changes on, the next step is to produce a set of diffs to
 	send to the FreeBSD maintainers.  This is done with the &man.diff.1;
 	command, with the <quote>context diff</quote> form
 	being preferred.  For example:</para>
       
       <indexterm>
         <primary><command>diff</command></primary>
       </indexterm>
       <para>
 	<screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen>
 
 	or
 
 	<screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen>
 	    
 	would generate such a set of context diffs for the given source file
 	or directory hierarchy.  See the man page for &man.diff.1; for more
 	details.</para>
 	  
       <para>Once you have a set of diffs (which you may test with the
 	  &man.patch.1; command), you should submit them for inclusion with
 	FreeBSD.  Use the &man.send-pr.1; program as described in <link
 	  linkend="contrib-general">Bug Reports and General Commentary</link>.
 	<emphasis>Do not</emphasis> just send the diffs to the &a.hackers; or
 	they will get lost! We greatly appreciate your submission (this is a
 	volunteer project!); because we are busy, we may not be able to
 	address it immediately, but it will remain in the PR database until we
 	do.  Indicate your submission by including <literal>[PATCH]</literal>
 	in the synopsis of the report.</para>
 
       <indexterm>
         <primary><command>uuencode</command></primary>
       </indexterm>
       <para>If you feel it appropriate (e.g. you have added, deleted, or
 	renamed files), bundle your changes into a <command>tar</command> file
 	and run the &man.uuencode.1; program on it.  Shar archives are also
 	welcome.</para>
 
       <para>If your change is of a potentially sensitive nature, e.g. you are
 	unsure of copyright issues governing its further distribution or you
 	are simply not ready to release it without a tighter review first,
 	then you should send it to &a.core; directly rather than submitting it
 	with &man.send-pr.1;.  The core mailing list reaches a much smaller
 	group of people who do much of the day-to-day work on FreeBSD.  Note
 	that this group is also <emphasis>very busy</emphasis> and so you
 	  should only send mail to them where it is truly necessary.</para>
 	  
       <para>Please refer to &man.intro.9; and &man.style.9; style for
 	some information on coding style. We would appreciate it if you
         were at least aware of this information before submitting
 	code.</para>
     </sect2>
     
     <sect2>
       <title>New Code or Major Value-Added Packages</title>
       
       <para>In the case of a significant contribution of a large body
 	work, or the addition of an important new feature to FreeBSD, it
 	becomes almost always necessary to either send changes as uuencoded
 	tar files or upload them to a web or FTP site for other people to
 	access.  If you do not have access to a web or FTP site, ask on an
 	appropriate FreeBSD mailing list for someone to host the changes for
 	you.</para>
 	  
       <para>When working with large amounts of code, the touchy subject of
 	copyrights also invariably comes up.  Acceptable copyrights for code
 	included in FreeBSD are:</para>
 	  
       <orderedlist>
   <indexterm><primary>BSD copyright</primary></indexterm>
 	<listitem>
 	  <para>The BSD copyright.  This copyright is most preferred due to
 	    its <quote>no strings attached</quote> nature and general
 	    attractiveness to commercial enterprises.  Far from discouraging
 	    such commercial use, the FreeBSD Project actively encourages such
 	    participation by commercial interests who might eventually be
 	    inclined to invest something of their own into FreeBSD.</para>
 	</listitem>
 
   <indexterm><primary>GPL</primary><see>GNU General Public License</see></indexterm>
   <indexterm><primary>GNU General Public License</primary></indexterm>
 	<listitem>
 	  <para>The GNU General Public License, or <quote>GPL</quote>.
 	    This license is not quite as popular with us due to the amount
 	    of extra effort demanded of anyone using the code for
 	    commercial purposes, but given the sheer quantity of GPL'd code
 	    we currently require (compiler, assembler, text formatter, etc)
 	    it would be silly to refuse additional contributions under this
 	    license.  Code under the GPL also goes into a different part of
 	    the tree, that being <filename>/sys/gnu</filename> or
 	    <filename>/usr/src/gnu</filename>, and is therefore easily
 	    identifiable to anyone for whom the GPL presents a
 	    problem.</para>
 	</listitem>
       </orderedlist>
       
       <para>Contributions coming under any other type of copyright must be
 	carefully reviewed before their inclusion into FreeBSD will be
 	considered.  Contributions for which particularly restrictive
 	commercial copyrights apply are generally rejected, though the authors
 	are always encouraged to make such changes available through their own
 	channels.</para>
 	  
       <para>To place a <quote>BSD-style</quote> copyright on your work, include
 	the following text at the very beginning of every source code file you
 	wish to protect, replacing the text between the <literal>%%</literal>
 	with the appropriate information.</para>
 	    
       <programlisting>Copyright (c) %%proper_years_here%%
         %%your_name_here%%, %%your_state%%  %%your_zip%%.  
 	All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer as
    the first lines of this file unmodified.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
 
 THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT,
 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 	      
         &#36;Id&#36;</programlisting>
 
       <para>For your convenience, a copy of this text can be found in
 	<filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para>
     </sect2>
     
     <sect2>
       <title>Money, Hardware or Internet Access</title>
       
       <para>We are always very happy to accept donations to further the cause
 	of the FreeBSD Project and, in a volunteer effort like ours, a little
 	can go a long way! Donations of hardware are also very important to
 	expanding our list of supported peripherals since we generally lack
 	the funds to buy such items ourselves.</para>
 	  
       <sect3>
 	<title><anchor id="donations">Donating Funds</title>
 
 	<para>The FreeBSD Foundation is a non-profit, tax-exempt
 	  foundation established to further the goals of the FreeBSD
 	  Project.  As a 501(c)3 entity, the Foundation is generally
 	  exempt from US federal income tax as well as Colorado
 	  State income tax.  Donations to a tax-exempt entity are
 	  often deductible from taxable federal income.</para>
 
 	<para>Donations may be sent in check form to:
 	  <address>
 	    The FreeBSD Foundation
 	    <street>7321 Brockway Dr.</street>
 	    <city>Boulder</city>, <state>CO</state> <postcode>80303</postcode>
 	    <country>USA</country>
 	  </address>
 	  The Foundation is not yet able to accept other forms
 	  of payment such as credit cards and PayPal.</para>
 
 	<para>More information about the FreeBSD Foundation can be
 	  found in <ulink
 	  url="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The
 	  FreeBSD Foundation -- an Introduction</ulink>.  To contact
 	  the Foundation by email, write to
 	  <email>bod@FreeBSDFoundation.org</email>.</para>
       </sect3>
       
       <sect3>
 	<title>Donating Hardware</title>
   <indexterm><primary>donations</primary></indexterm>
 
 	<para>Donations of hardware in any of the 3 following categories are
 	  also gladly accepted by the FreeBSD Project:</para>
 	    
 	<itemizedlist>
 	  <listitem>
 	    <para>General purpose hardware such as disk drives, memory or
 	      complete systems should be sent to the FreeBSD, Inc. address
 	      listed in the <emphasis>donating funds</emphasis>
 	      section.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>Hardware for which ongoing compliance testing is desired.
 	      We are currently trying to put together a testing lab of all
 	      components that FreeBSD supports so that proper regression
 	      testing can be done with each new release.  We are still lacking
 	      many important pieces (network cards, motherboards, etc) and if
 	      you would like to make such a donation, please contact &a.dg;
 	      for information on which items are still required.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>Hardware currently unsupported by FreeBSD for which you
 	      would like to see such support added.  Please contact the
 	      &a.core; before sending such items as we will need to find a
 	      developer willing to take on the task before we can accept
 	      delivery of new hardware.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Donating Internet Access</title>
 
 	<para>We can always use new mirror sites for FTP, WWW or
 	  <command>cvsup</command>.  If you would like to be such a mirror,
 	  please contact the
 	  &a.hubs; for more information.</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/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
index 8067d8845f..cdc31479fb 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -1,1750 +1,1750 @@
 <!--
      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>
     <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 world</command>.</para>
       </listitem>
 
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem><para>Properly setup 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; group 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; group 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
+	      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>
       
 	<orderedlist>
 	  <listitem>
 	    <para>Join the &a.current; and the &a.cvsall;.  This is not
 	      just a good idea, it is <emphasis>essential</emphasis>.  If
 	      you are not on the <emphasis>&a.current;</emphasis>,
 	      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; mailing 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, send mail to &a.majordomo; and
 	      specify the following in the body of your message:</para>
 
 	    <programlisting>subscribe freebsd-current
 subscribe cvs-all</programlisting>
             <indexterm>
               <primary><application>majordomo</application></primary>
             </indexterm>
 
 	    <para>Optionally, you can also say <literal>help</literal>
 	      and Majordomo will send you full help on how to subscribe
 	      and unsubscribe to the various other mailing lists we
 	      support.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Grab the sources from <hostid
 	      role="fqdn">ftp.FreeBSD.org</hostid>.  You can do this in
 	      one of three ways:</para>
 
 	    <orderedlist>
               <indexterm>
                 <primary><command>cvsup</command></primary>
               </indexterm>
               <indexterm>
                 <primary><command>cron</command></primary>
               </indexterm>
               <indexterm>
 	        <primary>-CURRENT</primary>
 		<secondary>Syncing with CVSup</secondary>
 	      </indexterm>
 
 	      <listitem>
 		<para>Use the <link linkend="cvsup">cvsup</link> program
 		  with <ulink
 		  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/standard-supfile">this
 		  supfile</ulink>.  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 supfile above, and configure 
  		  <link linkend="cvsup">cvsup</link> for your environment.
  		  If you want help doing this configuration,
  		  simply type:</para>
 
  		<screen>&prompt.root; <userinput>pkg_add -f ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/All/cvsupit-3.0.tgz</userinput></screen>
 
 	      </listitem>
               <indexterm>
 	        <primary>-CURRENT</primary>
 	        <secondary>Downloading with ftp</secondary>
 	      </indexterm>
 
 	      <listitem>
 		<para>Use <command>ftp</command>.  The source tree for
 		  &os.current; is always <quote>exported</quote> on:
 		  <ulink
 		  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/</ulink>.
 		  Some of our FTP mirrors may also allow
 		  compressed/tarred grabbing of whole trees.  e.g. you
 		  see:</para>
 
 		<screen>usr.bin/lex</screen>
 
 		<para>You can do the following to get the whole directory
 		  as a tar file:</para>
 
 		<screen><prompt>ftp&gt;</prompt> <userinput>cd usr.bin</userinput>
 <prompt>ftp&gt;</prompt> <userinput>get lex.tar</userinput></screen>
 	      </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 9600bps 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>
 
 	    <para>Before compiling &os.current;, read the
 	      <filename>Makefile</filename> in <filename>/usr/src</filename>
 	      carefully.  You should at least run a <link
 	      linkend="makeworld">make world</link> the first time through
 	      as part of the upgrading process.  Reading the &a.current;
 	      will keep you up-to-date on other bootstrapping procedures
 	      that sometimes become necessary as we move towards 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; first 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="../../../../security/index.html">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;.  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; mailing 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, send mail to &a.majordomo; and
 	      specify the following in the body of your message:</para>
 
 	    <programlisting>subscribe freebsd-stable
 subscribe cvs-all</programlisting>
 
 	    <indexterm>
         <primary><application>majordomo</application></primary>
       </indexterm>
 	    <para>Optionally, you can also say <literal>help</literal>
 	      and Majordomo will send you full help on how to subscribe
 	      and unsubscribe to the various other mailing lists we
 	      support.</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://releng4.FreeBSD.org/pub/FreeBSD/">ftp://releng4.FreeBSD.org/pub/FreeBSD/</ulink>
 	      and install it like any other release.</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 <hostid role="fqdn">ftp.FreeBSD.org</hostid>.  This can
 	      be done in one of three ways:</para>
 
 	    <orderedlist>
 	      <indexterm>
 	        <primary>-STABLE</primary>
 		<secondary>syncing with CVSup</secondary>
 	      </indexterm>
 	      <listitem>
 		<para>Use the <link linkend="cvsup">cvsup</link> program
 		  with <ulink
 		  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this
 		  supfile</ulink>.  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.  For a fairly easy
 		  interface to this, simply type:</para>
 	      
 		<blockquote><screen>&prompt.root; <userinput>pkg_add -f ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></screen></blockquote>
 	      </listitem>
 
 	      <indexterm>
 	        <primary>-STABLE</primary>
 		<secondary>downloading with FTP</secondary>
 	      </indexterm>
 	      <listitem>
 		<para>Use <command>ftp</command>.  The source tree for
 		  &os.stable; is always <quote>exported</quote> on:
 		  <ulink
 		  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/</ulink></para>
 
 		<para>Some of our FTP mirrors may also allow
 		  compressed/tarred grabbing of whole trees.  e.g. you
 		  see:</para>
 
 		<screen>usr.bin/lex</screen>
 
 		<para>You can do the following to get the whole directory
 		  for you as a tar file:</para>
 
 		<screen><prompt>ftp&gt;</prompt> <userinput>cd usr.bin</userinput>
 <prompt>ftp&gt;</prompt> <userinput>get lex.tar</userinput></screen>
 	      </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 run a <link
 	    linkend="makeworld">make world</link> the first time through
 	    as part of the upgrading process.  Reading the &a.stable; will
 	    keep you up-to-date on other bootstrapping procedures that
 	    sometimes become necessary as we move towards 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>
     <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 CVSup 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><command>CTM</command></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 CTM or, with
       anoncvs, simply delete the bad bits and resync.</para>
   </sect1>
 
   <sect1 id="makeworld">
     <title>Using <command>make world</command></title>
 
     <indexterm>
       <primary><command>make world</command></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 fix-it floppy to
 	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
 	filesystems (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>
 
     <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>/etc/defaults/make.conf</filename> 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>/etc/defaults/make.conf</filename> 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 <filename>/etc/group</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
         <quote>make world</quote> has expected certain usernames or groups
 	to exist.  When performing an upgrade it is likely that these
 	groups did not exist. This caused problems when upgrading.</para>
 
       <para>The most recent example of this is when the <quote/ppp/ group
 	(later renamed <quote/network/) was added.  Users had the
 	installation process fail for them when parts of the
 	<filename>ppp</filename> subsystem were installed using a
 	non-existent (for them) group name.</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>
 
       <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.</para>
 
       <para>As the superuser, you can execute</para>
 
       <screen>&prompt.root; <userinput/shutdown now/</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 filesystems, remounts <filename>/</filename>
 	read/write, mounts all the other UFS filesystems 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,
             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 timezone settings
             get set up correctly - 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 <quote>make world</quote> 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 and Install 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 <option>-<replaceable/x/</option> <option>-D<replaceable>VARIABLE</replaceable></option> <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=true <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>lines 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>.</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,
 	  A, B and C that you want to upgrade, run <command>make
 	  buildworld</command> and <command>make installworld</command> on
 	  A.  B and C should then NFS mount <filename>/usr/src</filename>
 	  and <filename>/usr/obj</filename> from A, and you can then run
 	  <command>make installworld</command> to install the results of 
 	  the build on B and C.</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 -j 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><command>make world</command></primary>
 	  <secondary>timings</secondary>
 	</indexterm>
 
         <para>Many factors influence the build time, but currently a 500 MHz
           Pentium 3 with 128 MB of RAM takes about 2 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>If you are upgrading to &os; 4.0 or above then the standard
 	kernel build procedure (as described in <xref linkend="kernelconfig">)
 	is deprecated.  Instead, you should run these commands
 	<emphasis>after</emphasis> you have <link
         linkend="make-buildworld">built the world with
         <maketarget>buildworld</maketarget></link>.</para> 
 
       <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make buildkernel</userinput>
 &prompt.root; <userinput>make installkernel</userinput></screen>
 
       <para>If you are upgrading to a version of &os; below 4.0 you should
 	use the standard 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 in to 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=true buildworld</userinput></screen>
 
 	<para>you must install the results with:</para>
 
 	<screen>&prompt.root; <userinput>make -DNOPROFILE=true installworld</userinput></screen>
 
 	<para>otherwise it would try and 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 world</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>
       <indexterm><primary><command>mergemaster</command></primary></indexterm>
 
       <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.  We strongly recommend you
         use &man.mergemaster.8;, however, and if you do then you
         can skip forward to the <link linkend="update-dev">next
         section</link>, since &man.mergemaster.8; is very simple to use.
         You should read the manual page first, and make a backup of
         <filename>/etc</filename> in case anything goes wrong.</para>
 
       <para>If you wish to do the update manually,
         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>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/./.  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/ 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>/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>
     </sect2>
   
     <sect2 id="update-dev">
       <title>Update <filename>/dev</filename></title>
       
       <note>
 	<title>DEVFS</title>
         <indexterm><primary>DEVFS</primary></indexterm>
 	<para>If you are using DEVFS this is unnecessary.</para>
       </note>
 
-      <para>In most cases, the &man.mergemaster.8 tool will realize when
+      <para>In most cases, the &man.mergemaster.8; tool will realize when
         it is necessary to update the devices, and offer to complete it
         automatically.  These instructions tell how to update the devices
         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 devices.</para>
 	    
 	    <screen>&prompt.root; <userinput/sh MAKEDEV all/</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 devices 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
 	  
 	    <screen>&prompt.root; <userinput>sh MAKEDEV sd0s1</userinput></screen>
 
 	    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.</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
 	filesystems (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.fastboot.8; should do it.</para>
 
       <screen>&prompt.root; <userinput>fastboot</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 accidently 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/</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 CVSup, 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 are 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 <quote/make world/ 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 340MB).</para>
       
 	    <para>However, if you know what you are doing you can have
 	      <quote/make world/ 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
 	      realising that it is because they have tried to cut
 	      corners.</para>
       
 	    <para>If you want to live dangerously then make the world, passing
 	      the <makevar>NOCLEAN</makevar> definition to make, like
 	      this:</para>
 
 	    <screen>&prompt.root; <userinput>make -DNOCLEAN world</userinput></screen>
 	  </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 <quote>make world</quote> 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
 	      <quote>make world</quote>.</para>
 
 	    <para>If you see the message
 
 	      <screen>--------------------------------------------------------------
 Building everything..
 --------------------------------------------------------------</screen>
 
 	      in the <quote>make world</quote> 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>
 
 	<indexterm><primary>NFS</primary></indexterm>
 	<qandaentry>
 	  <question>
 	    <para>Can I use one machine as a <emphasis/master/ to upgrade lots
 	      of machines (NFS)?</para>
 	  </question>
 
 	  <answer>
 	    <para>This is a fairly easy task, and can save hours of compile
               time for many machines.  Simply run the 
 	      <makevar>buildworld</makevar> on a central
               machine, and then NFS mount <filename>/usr/src</filename> and
 	      <filename>/usr/obj</filename> on the remote machine and
 	      <makevar>installworld</makevar> there.</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
 		  filesystems held on separate disks.  If possible, put these
 		  disks on separate disk controllers.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Better still, put these filesystems across multiple
-		  disks using the &man.ccd.4 (concatenated disk
+		  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 <quote>-O
 		  -pipe</quote>.  The optimization <quote>-O2</quote> is much
 		  slower, and the optimization difference between
 		  <quote>-O</quote> and <quote>-O2</quote> is normally
 		  negligible.  <quote>-pipe</quote> 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&lt;n&gt;</option> option to make 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 filesystem holding
 		  <filename>/usr/src</filename> can be mounted (or remounted)
 		  with the <option>noatime</option> option.  This prevents the
 		  filesystem from recording the file access time.  You probably
 		  do not need this information anyway.
 		  
 		  <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 filesystem.  If it is not (if it is a part of
 		      <filename>/usr</filename> for example) then you will
 		      need to use  that filesystem mount point, and not
 		      <filename>/usr/src</filename>.</para>
 		  </warning>
 		</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>The filesystem holding <filename>/usr/obj</filename> can
 		  be mounted (or remounted) with the <quote>async</quote>
 		  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 filesystem
 		    more fragile.  With this option there is an increased
 		    chance that, should power fail, the filesystem will be in
 		    an unrecoverable state when the machine restarts.</para>
 	   
 		  <para>If <filename>/usr/obj</filename> is the only thing on
 		    this filesystem then it is not a problem.  If you have
 		    other, valuable data on the same filesystem 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 filesystem, 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>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Tracking for multiple machines</title>
     
     <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 world</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
 	root 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/eresources/chapter.sgml b/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml
index b8907ab146..5057de776a 100644
--- a/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml
@@ -1,1742 +1,1742 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <appendix id="eresources">
   <title>Resources on the Internet</title>
   
   <para>The rapid pace of FreeBSD progress makes print media impractical as a
     means of following the latest developments.  Electronic resources are the
     best, if not often the only, way stay informed of the latest advances.
     Since FreeBSD is a volunteer effort, the user community itself also
     generally serves as a <quote>technical support department</quote> of sorts,
     with electronic mail and  USENET news being the most effective way of
     reaching that community.</para>
       
   <para>The most important points of contact with the FreeBSD user community
     are outlined below.  If you are aware of other resources not mentioned
     here, please send them to the &a.doc;so that they may also be
     included.</para>
   
   <sect1 id="eresources-mail">
     <title>Mailing Lists</title>
     
     <para>Though many of the FreeBSD development members read USENET, we
       cannot always guarantee that we will get to your questions in a timely
       fashion (or at all) if you post them only to one of the
       <literal>comp.unix.bsd.freebsd.*</literal> groups.  By addressing your
       questions to the appropriate mailing list you will reach both us and a
       concentrated FreeBSD audience, invariably assuring a better (or at least
       faster) response.</para>
 
     <para>The charters for the various lists are given at the bottom of this
       document.  <emphasis>Please read the charter before joining or sending
 	mail to any list</emphasis>.  Most of our list subscribers now receive
       many hundreds of FreeBSD related messages every day, and by setting down
       charters and rules for proper use we are striving to keep the
       signal-to-noise ratio of the lists high. To do less would see the
       mailing lists ultimately fail as an effective communications medium for
       the project.</para>
 
     <para>Archives are kept for all of the mailing lists and can be searched
       using the <ulink url="../../../../search/index.html">FreeBSD World
 	Wide Web server</ulink>.  The keyword searchable archive offers an
       excellent way of finding answers to frequently asked questions and
       should be consulted before posting a question.</para>
     
     <sect2 id="eresources-summary">
       <title>List Summary</title>
       
       <para><emphasis>General lists:</emphasis> The following are general
 	lists which anyone is free (and encouraged) to join:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>List</entry>
 	      <entry>Purpose</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	      <entry>cvs-all</entry>
 	      <entry>Changes made to the FreeBSD source tree</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-advocacy</entry>
 	      <entry>FreeBSD Evangelism</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-announce</entry>
 	      <entry>Important events and project milestones</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-arch</entry>
 	      <entry>Architecture and design discussions</entry>
 	    </row>
 
     	    <row>
 	      <entry>freebsd-bugs</entry>
 	      <entry>Bug reports</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-bugbusters</entry>
 	      <entry>Discussions pertaining to the maintenance of the FreeBSD
 		problem report database and related tools</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-chat</entry>
 	      <entry>Non-technical items related to the FreeBSD
 		community</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-config</entry>
 	      <entry>Development of FreeBSD installation and configuration tools</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-current</entry>
 	      <entry>Discussion concerning the use of
 		FreeBSD-current</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-isp</entry>
 	      <entry>Issues for Internet Service Providers using
 		FreeBSD</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-jobs</entry>
 	      <entry>FreeBSD employment and consulting
 		opportunities</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-newbies</entry>
 	      <entry>New FreeBSD users activities and discussions</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-policy</entry>
 	      <entry>FreeBSD Core team policy decisions.  Low volume, and
 		read-only</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-questions</entry>
 		  <entry>User questions and technical support</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-security</entry>
 	      <entry>Security issues</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-security-notifications</entry>
 	      <entry>Security notifications</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-stable</entry>
 	      <entry>Discussion concerning the use of
 		FreeBSD-stable</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-test</entry>
 	      <entry>Where to send your test messages instead of one of
 		the actual lists</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 	  
       <para><emphasis>Technical lists:</emphasis> The following lists are for
 	technical discussion.  You should read the charter for each list
 	carefully before joining or sending mail to one as there are firm
 	guidelines for their use and content.</para>
       
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>List</entry>
 	      <entry>Purpose</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	      <entry>freebsd-afs</entry>
 	      <entry>Porting AFS to FreeBSD</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-aic7xxx</entry>
 	      <entry>Developing drivers for the Adaptec AIC 7xxx</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-alpha</entry>
 	      <entry>Porting FreeBSD to the Alpha</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-arm</entry>
 	      <entry>Porting FreeBSD to ARM processors</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-atm</entry>
 	      <entry>Using ATM networking with FreeBSD</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-audit</entry>
 	      <entry>Source code audit project</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-binup</entry>
 	      <entry>Design and development of the binary update system</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-cluster</entry>
 	      <entry>Using FreeBSD in a clustered environment</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-database</entry>
 	      <entry>Discussing database use and development under
 		FreeBSD</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-doc</entry>
 	      <entry>Creating FreeBSD related documents</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-emulation</entry>
 	      <entry>Emulation of other systems such as
 		Linux/DOS/Windows</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-firewire</entry>
 	      <entry>FreeBSD Firewire (iLink, IEEE 1394) technical
 		discussion</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-fs</entry>
 	      <entry>Filesystems</entry>
 	    </row>
 		
 	    <row>
 	      <entry>freebsd-gnome</entry>
 	      <entry>Porting GNOME and GNOME applications</entry>
 	    </row>
 		
 	    <row>
 	      <entry>freebsd-hackers</entry>
 	      <entry>General technical discussion</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-hardware</entry>
 	      <entry>General discussion of hardware for running
 		FreeBSD</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-i18n</entry>
 	      <entry>FreeBSD Internationalization</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-ia64</entry>
 	      <entry>Porting FreeBSD to Intel's upcoming IA64 systems</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-ipfw</entry>
 	      <entry>Technical discussion concerning the redesign of the IP
 		firewall code</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-isdn</entry>
 	      <entry>ISDN developers</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-java</entry>
 	      <entry>Java developers and people porting JDKs to
 		FreeBSD</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-lfs</entry>
 	      <entry>Porting LFS to FreeBSD</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-libh</entry>
 	      <entry>The second generation installation and package
 	         system</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-mobile</entry>
 	      <entry>Discussions about mobile computing</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-mozilla</entry>
 	      <entry>Porting mozilla to FreeBSD</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-multimedia</entry>
 	      <entry>Multimedia applications</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-new-bus</entry>
 	      <entry>Technical discussions about bus architecture</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-net</entry>
 	      <entry>Networking discussion and TCP/IP source code</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-platforms</entry>
 	      <entry>Concerning ports to non-Intel architecture
 		platforms</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-ports</entry>
 	      <entry>Discussion of the ports collection</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-ppc</entry>
 	      <entry>Porting FreeBSD to the PowerPC</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-qa</entry>
 	      <entry>Discussion of Quality Assurance, usually pending a release</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-realtime</entry>
 	      <entry>Development of realtime extensions to FreeBSD</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-scsi</entry>
 	      <entry>The SCSI subsystem</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-small</entry>
 	      <entry>Using FreeBSD in embedded applications</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-smp</entry>
 	      <entry>Design discussions for [A]Symmetric
 		MultiProcessing</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-sparc</entry>
 	      <entry>Porting FreeBSD to SPARC based systems</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-standards</entry>
 	      <entry>FreeBSD's conformance to the C99 and the POSIX
 		standards</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-tokenring</entry>
 	      <entry>Support Token Ring in FreeBSD</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
       
       <para><emphasis>Limited lists:</emphasis> The following lists are for
 	more specialized (and demanding) audiences and are probably not of
         interest to the general public.  It is also a good idea to establish a
         presence in the technical lists before joining one of these limited
         lists so that you will understand the communications etiquette involved.</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>List</entry>
 	      <entry>Purpose</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	      <entry>freebsd-core</entry>
 	      <entry>FreeBSD core team</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-hubs</entry>
 	      <entry>People running mirror sites (infrastructural
 		support)</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-install</entry>
 	      <entry>Installation development</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-user-groups</entry>
 	      <entry>User group coordination</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-vendors</entry>
 	      <entry>Vendors pre-release coordination</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-www</entry>
 	      <entry>Maintainers of <ulink url="../../../../index.html">www.FreeBSD.org</ulink></entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
       
       <para><emphasis>Digest lists:</emphasis> Many of the above lists are
 	also available as digests.  New messages posted to the list are
 	collected and sent out as a single email when the sizes goes
 	over 100KB. The lists available in digest form are:</para> 
 
       <informaltable frame="none">
 	<tgroup cols="1">
 	  <thead>
 	    <row>
 	      <entry>List</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	      <entry>freebsd-afs-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-alpha-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-chat-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-current-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-cvs-all-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-database-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-hackers-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-ia64-digest</entry>
 	    </row>
 
 	    <row>
 	      <entry>freebsd-isdn-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-java-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-questions-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-security-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-sparc-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-stable-digest</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>freebsd-test-digest</entry>
 	    </row>
 	    
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para><emphasis>CVS lists:</emphasis> The following lists are for people
 	interested in seeing the log messages for changes to various areas of
 	the source tree.  They are <emphasis>Read-Only</emphasis> lists and
 	should not have mail sent to them.</para>
       
       <informaltable frame="none">
 	<tgroup cols="3">
 	  <thead>
 	    <row>
 	      <entry>List</entry>
 	      <entry>Source area</entry>
 	      <entry>Area Description (source for)</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	      <entry>cvs-all</entry>
 	      <entry>/usr/src</entry>
 	      <entry>All changes to the tree (superset)</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
     
     <sect2 id="eresources-subscribe">
       <title>How to Subscribe</title>
       
       <para>All mailing lists live on <hostid
 	  role="fqdn">FreeBSD.org</hostid>, so to post to a given list you
 	simply mail to
 	&lt;<replaceable>listname</replaceable>@FreeBSD.org&gt;.  It will then
 	be redistributed to mailing list members world-wide.</para>
 	  
       <para>To subscribe to a list, send mail to &a.majordomo; and include
 
 	<programlisting>subscribe &lt;listname&gt; [&lt;optional address&gt;]</programlisting>
 
 	in the body of your message.  For example, to subscribe yourself to
 	<literal>freebsd-announce</literal>, you would do:</para>
 	    
       <screen>&prompt.user; <userinput>mail majordomo@FreeBSD.org</userinput>
 subscribe freebsd-announce
 ^D</screen>
 	    
       <para>If you want to subscribe yourself under a different name, or
 	submit a subscription request for a local mailing list (this is more
 	efficient if you have several interested parties at one site, and
 	highly appreciated by us!), you would do something like:</para>
 	    	    
       <screen>&prompt.user; <userinput>mail majordomo@FreeBSD.org</userinput>
 subscribe freebsd-announce local-announce@example.com
 ^D</screen>
 	    
       <para>Finally, it is also possible to unsubscribe yourself from a list,
 	get a list of other list members or see the list of mailing lists
 	again by sending other types of control messages to majordomo.  For a
 	complete list of available commands, do this:</para>
 
       <screen>&prompt.user; <userinput>mail majordomo@FreeBSD.org</userinput>
 help
 ^D</screen>
 	    
       <para>Again, we would like to request that you keep discussion in the
 	technical mailing lists on a technical track. If you are only
 	interested in important announcements then it is suggested that
 	you join freebsd-announce, which is intended only for infrequent
 	traffic.</para>
     </sect2>
     
     <sect2 id="eresources-charters">
       <title>List Charters</title>
       
       <para><emphasis>All</emphasis> FreeBSD mailing lists have certain basic
 	rules which must be adhered to by anyone using them. Failure to comply
 	with these guidelines will result in two (2) written warnings from the
 	FreeBSD Postmaster <email>postmaster@FreeBSD.org</email>, after which,
 	on a third offense, the poster will removed from all FreeBSD mailing
 	lists and filtered from further posting to them. We regret that such
 	rules and measures are necessary at all, but today's Internet is a
 	pretty harsh environment, it would seem, and many fail to appreciate
 	just how fragile some of its mechanisms are.</para>
 	  
       <para>Rules of the road:</para>
       
       <itemizedlist>
 	<listitem>
 	  <para>The topic of any posting should adhere to the basic charter of
 	    the list it is posted to, e.g. if the list is about technical
 	    issues then your posting should contain technical discussion.
 	    Ongoing irrelevant chatter or flaming only detracts from the value
 	    of the mailing list for everyone on it and will not be tolerated.
 	    For free-form discussion on no particular topic, the &a.chat;
 	    is freely available and should be used instead.</para>
 	</listitem>
 
 	<listitem>
 	  <para>No posting should be made to more than 2 mailing lists, and
 	    only to 2 when a clear and obvious need to post to both lists
 	    exists.  For most lists, there is already a great deal of
 	    subscriber overlap and except for the most esoteric mixes (say
 	    "-stable &amp; -scsi"), there really is no reason to post to more
 	    than one list at a time.  If a message is sent to you in such a
 	    way that multiple mailing lists appear on the 
 	    <literal>Cc</literal> line then the <literal>Cc</literal>
 	    line should also be trimmed before sending it out again.
 	    <emphasis>You are <emphasis>still</emphasis> responsible for your
 	      own cross-postings, no matter who the originator might have
 	      been.</emphasis></para>
 	</listitem>
 	      
 	<listitem>
 	  <para>Personal attacks and profanity (in the context of an argument)
 	    are not allowed, and that includes users and developers alike.
 	    Gross breaches of netiquette, like excerpting or reposting private
 	    mail when permission to do so was not and would not be
 	    forthcoming, are frowned upon but not specifically enforced.
 	    <emphasis>However</emphasis>, there are also very few cases where
 	    such content would fit within the charter of a list and it would
 	    therefore probably rate a warning (or ban) on that basis
 	    alone.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Advertising of non-FreeBSD related products or services is
 	    strictly prohibited and will result in an immediate ban if it is
 	    clear that the offender is advertising by spam.</para>
 	</listitem>
       </itemizedlist>
       
       <para><emphasis>Individual list charters:</emphasis></para>
       
       <variablelist>
 	<varlistentry>
 	  <term>FREEBSD-AFS</term>
 
 	  <listitem>
 	    <para><emphasis>Andrew File System</emphasis></para>
 	    
 	    <para>This list is for discussion on porting and using AFS from
 	      CMU/Transarc</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-ANNOUNCE</term>
 	  
 	  <listitem>
 	    <para><emphasis>Important events / milestones</emphasis></para>
 
 	    <para>This is the mailing list for people interested only in
 	      occasional announcements of significant FreeBSD events. This
 	      includes announcements about snapshots and other releases.  It
 	      contains announcements of new FreeBSD capabilities.  It may
 	      contain calls for volunteers etc. This is a low volume, strictly
 	      moderated mailing list.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-ARCH</term>
 	  
 	  <listitem>
 	    <para><emphasis>Architecture and design
 		discussions</emphasis></para>
 
             <para>This list is for discussion of the FreeBSD
 	      architecture.  Messages will mostly be kept strictly
 	      technical in nature.  Examples of suitable topics
 	      are:</para>
 	    
 	    <itemizedlist>
 	      <listitem>
 		<para>How to re-vamp the build system to have several
 		  customized builds running at the same time.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>What needs to be fixed with VFS to make Heidemann layers
 		  work.</para>
 		</listitem>
 
 	      <listitem>
 		<para>How do we change the device driver interface to be able
 		  to use the same drivers cleanly on many buses and
 		  architectures.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>How to write a network driver.</para>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-AUDIT</term>
 	  
 	  <listitem>
 	    <para><emphasis>Source code audit project</emphasis></para>
 
 	    <para>This is the mailing list for the FreeBSD source code
 	      audit project.  Although this was originally intended for
 	      security-related changes, its charter has been expanded to
 	      review any code changes.</para>
 
 	    <para>This list is very heavy on patches, and is probably of no
 	      interest to the average FreeBSD user.  Security discussions
 	      not related to a particular code change are held on
 	      freebsd-security.  Conversely, all developers are encouraged
 	      to send their patches here for review, especially if they
 	      touch a part of the system where a bug may adversely affect
 	      the integrity of the system.</para>
 
 <!-- I can't actually find a charter for this, but there's this email: http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=223347+225804+/usr/local/www/db/text/2000/cvs-all/20001210.cvs-all -->
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-BINUP</term>
 	  
 	  <listitem>
 	    <para><emphasis>FreeBSD Binary Update Project</emphasis></para>
 
 	    <para>This list exists to provide discussion for the binary
 	      update system, or <application>binup</application>.
 	      Design issues, implementation details,
 	      patches, bug reports, status reports, feature requests, commit
 	      logs, and all other things related to 
 	      <application>binup</application> are fair game.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-BUGS</term>
 	  
 	  <listitem>
 	    <para><emphasis>Bug reports</emphasis></para>
 	    
 	    <para>This is the mailing list for reporting bugs in FreeBSD
 	      Whenever possible, bugs should be submitted using the
 		&man.send-pr.1;
 	      command or the <ulink
 		url="../../../../send-pr.html">WEB
 		interface</ulink> to it.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-CHAT</term>
 	  
 	  <listitem>
 	    <para><emphasis>Non technical items related to the FreeBSD
 		community</emphasis></para>
 
 	    <para>This list contains the overflow from the other lists about
 	      non-technical, social information.  It includes discussion about
 	      whether Jordan looks like a toon ferret or not, whether or not
 	      to type in capitals, who is drinking too much coffee, where the
 	      best beer is brewed, who is brewing beer in their basement, and
 	      so on.  Occasional announcements of important events (such as
 	      upcoming parties, weddings, births, new jobs, etc) can be made
 	      to the technical lists, but the follow ups should be directed to
 	      this -chat list.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-CORE</term>
 	  
 	  <listitem>
 	    <para><emphasis>FreeBSD core team</emphasis></para>
 	    
 	    <para>This is an internal mailing list for use by the core
 	      members.  Messages can be sent to it when a serious
 	      FreeBSD-related matter requires arbitration or high-level
 	      scrutiny.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-CURRENT</term>
 		
 	  <listitem>
 	    <para><emphasis>Discussions about the use of
 		FreeBSD-current</emphasis></para>
 
 	    <para>This is the mailing list for users of freebsd-current.  It
 	      includes warnings about new features coming out in -current that
 	      will affect the users, and instructions on steps that must be
 	      taken to remain -current.  Anyone running <quote>current</quote>
 	      must subscribe to this list.  This is a technical mailing list
 	      for which strictly technical content is expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-CURRENT-DIGEST</term>
 	  
 	  <listitem>
 	    <para><emphasis>Discussions about the use of
 		FreeBSD-current</emphasis></para>
 
 	    <para>This is the digest version of the freebsd-current mailing
 	      list.  The digest consists of all messages sent to
 	      freebsd-current bundled together and mailed out as a single
 	      message. This list is <emphasis>Read-Only</emphasis> and
 	      should not be posted to.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-DOC</term>
 		
 	  <listitem>
 	    <para><emphasis>Documentation project</emphasis></para>
 
 	    <para>This mailing list is for the discussion of issues and
 	      projects related to the creation of documentation for FreeBSD.
 	      The members of this mailing list are collectively referred to as
 	      <quote>The FreeBSD Documentation Project</quote>.  It is an open
 	      list; feel free to join and contribute!</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-FIREWIRE</term>
 
 	  <listitem>
 	    <para><emphasis>Firewire (iLink, IEEE 1394)</emphasis></para>
 
 	    <para>This is a mailing list for discussion of the design
 	      and implementation of a Firewire (aka IEEE 1394 aka
 	      iLink) subsystem for FreeBSD.  Relevant topics
 	      specifically include the standards, bus devices and
 	      their protocols, adapter boards/cards/chips sets, and
 	      the architecture and implementation of code for their
 	      proper support.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-FS</term>
 	  
 	  <listitem>
 	    <para><emphasis>Filesystems</emphasis></para>
 	    
 	    <para>Discussions concerning FreeBSD filesystems.  This is a
 	      technical mailing list for which strictly technical content is
 	      expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-GNOME</term>
 	  
 	  <listitem>
 	    <para><emphasis>GNOME</emphasis></para>
 	    
 	    <para>Discussions concerning The GNOME Desktop Environment for 
               FreeBSD filesystems.  This is a technical mailing list for
 	      which strictly technical content is expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-IPFW</term>
 	  
 	  <listitem>
 	    <para><emphasis>IP Firewall</emphasis></para>
 
 	    <para>This is the forum for technical discussions concerning the
 	      redesign of the IP firewall code in FreeBSD.  This is a
 	      technical mailing list for which strictly technical content is
 	      expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-IA64</term>
 
 	  <listitem>
 	    <para><emphasis>Porting FreeBSD to IA64</emphasis></para>
 
 	    <para>This is a technical mailing list for individuals
             actively working on porting FreeBSD to the IA-64 platform
             from Intel, to bring up problems or discuss alternative
             solutions.  Individuals interested in following the
             technical discussion are also welcome.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-ISDN</term>
 		
 	  <listitem>
 	    <para><emphasis>ISDN Communications</emphasis></para>
 	    
 	    <para>This is the mailing list for people discussing the
 	      development of ISDN support for FreeBSD.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-JAVA</term>
 		
 	  <listitem>
 	    <para><emphasis>Java Development</emphasis></para>
 	    
 	    <para>This is the mailing list for people discussing the
 	      development of significant Java applications for FreeBSD and the
 	      porting and maintenance of JDKs.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-HACKERS</term>
 	  
 	  <listitem>
 	    <para><emphasis>Technical discussions</emphasis></para>
 	    
 	    <para>This is a forum for technical discussions related to
 	      FreeBSD.  This is the primary technical mailing list.  It is for
 	      individuals actively working on FreeBSD, to bring up problems or
 	      discuss alternative solutions.  Individuals interested in
 	      following the technical discussion are also welcome.  This is a
 	      technical mailing list for which strictly technical content is
 	      expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-HACKERS-DIGEST</term>
 	  
 	  <listitem>
 	    <para><emphasis>Technical discussions</emphasis></para>
 	    
 	    <para>This is the digest version of the freebsd-hackers mailing
 	      list.  The digest consists of all messages sent to
 	      freebsd-hackers bundled together and mailed out as a single
 	      message.  This list is <emphasis>Read-Only</emphasis>
 	      and should not be posted to.</para>
 	  </listitem>
 	</varlistentry>
 	      
 	<varlistentry>
 	  <term>FREEBSD-HARDWARE</term>
 	  
 	  <listitem>
 	    <para><emphasis>General discussion of FreeBSD
 		hardware</emphasis></para>
 
 	    <para>General discussion about the types of hardware that FreeBSD
 	      runs on, various problems and suggestions concerning what to buy
 	      or avoid.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-HUBS</term>
 
 	  <listitem>
 	    <para><emphasis>Mirror sites</emphasis></para>
 
 	    <para>Announcements and discussion for people who run FreeBSD
 	      mirror sites.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-INSTALL</term>
 	  
 	  <listitem>
 	    <para><emphasis>Installation discussion</emphasis></para>
 	    
 	    <para>This mailing list is for discussing FreeBSD installation
 	      development for the future releases.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-ISP</term>
 	  
 	  <listitem>
 	    <para><emphasis>Issues for Internet Service
 		Providers</emphasis></para>
 	    
 	    <para>This mailing list is for discussing topics relevant to
 	      Internet Service Providers (ISPs) using FreeBSD.  This is a
 	      technical mailing list for which strictly technical content is
 	      expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-NEWBIES</term>
 	  
 	  <listitem>
 	    <para><emphasis>Newbies activities discussion</emphasis></para>
 		
 	    <para>We cover any of the activities of newbies that are not
 	      already dealt with elsewhere, including: independent learning
 	      and problem solving techniques, finding and using resources and
 	      asking for help elsewhere, how to use mailing lists and which
 	      lists to use, general chat, making mistakes, boasting, sharing
 	      ideas, stories, moral (but not technical) support, and taking an
 	      active part in the FreeBSD community.  We take our problems and
 	      support questions to freebsd-questions, and use freebsd-newbies
 	      to meet others who are doing the same things that we do as
 	      newbies.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-PLATFORMS</term>
 		
 	  <listitem>
 	    <para><emphasis>Porting to Non-Intel platforms</emphasis></para>
 
 	    <para>Cross-platform FreeBSD issues, general discussion and
 	      proposals for non-Intel FreeBSD ports.  This is a technical
 	      mailing list for which strictly technical content is
 	      expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-POLICY</term>
 	  
 	  <listitem>
 	    <para><emphasis>Core team policy decisions</emphasis></para>
 
 	    <para>This is a low volume, read-only mailing list for FreeBSD
 	      Core Team Policy decisions.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-PORTS</term>
 	  
 	  <listitem>
 	    <para><emphasis>Discussion of
 		<quote>ports</quote></emphasis></para>
 
 	    <para>Discussions concerning FreeBSD's <quote>ports
 	      collection</quote> (<filename>/usr/ports</filename>), proposed
 	      ports, modifications to ports collection infrastructure and
 	      general coordination efforts.  This is a technical mailing list
 	      for which strictly technical content is expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-QUESTIONS</term>
 		
 	  <listitem>
 	    <para><emphasis>User questions</emphasis></para>
 
 	    <para>This is the mailing list for questions about FreeBSD.  You
 	      should not send <quote>how to</quote> questions to the technical
 	      lists unless you consider the question to be pretty
 	      technical.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-QUESTIONS-DIGEST</term>
 	  
 	  <listitem>
 	    <para><emphasis>User questions</emphasis></para>
 	    
 	    <para>This is the digest version of the freebsd-questions mailing
 	      list.  The digest consists of all messages sent to
 	      freebsd-questions bundled together and mailed out as a single
 	      message.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-SCSI</term>
 	  
 	  <listitem>
 	    <para><emphasis>SCSI subsystem</emphasis></para>
 	    
 	    <para>This is the mailing list for people working on the scsi
 	      subsystem for FreeBSD.  This is a technical mailing list for
 	      which strictly technical content is expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-SECURITY</term>
 	  
 	  <listitem>
 	    <para><emphasis>Security issues</emphasis></para>
 	    
 	    <para>FreeBSD computer security issues (DES, Kerberos, known
 	      security holes and fixes, etc).  This is a technical mailing
 	      list for which strictly technical content is expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-SECURITY-NOTIFICATIONS</term>
 	  
 	  <listitem>
 	    <para><emphasis>Security Notifications</emphasis></para>
 
 	    <para>Notifications of FreeBSD security problems and
 	      fixes. This is not a discussion list.  The discussion
 	      list is FreeBSD-security.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-SMALL</term>
 	    
 	  <listitem>
 	    <para><emphasis>Using FreeBSD in embedded
 	      applications</emphasis></para>
 
 	    <para>This list discusses topics related to unusually small and
 	      embedded FreeBSD installations.  This is a technical mailing
 	      list for which strictly technical content is expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-STABLE</term>
 		
 	  <listitem>
 	    <para><emphasis>Discussions about the use of
 		FreeBSD-stable</emphasis></para>
 	    
 	    <para>This is the mailing list for users of freebsd-stable.  It
 	      includes warnings about new features coming out in -stable that
 	      will affect the users, and instructions on steps that must be
 	      taken to remain -stable.  Anyone running <quote>stable</quote>
 	      should subscribe to this list.  This is a technical mailing list
 	      for which strictly technical content is expected.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-STANDARDS</term>
 
 	  <listitem>
 	    <para><emphasis>C99 &amp; POSIX Conformance</emphasis></para>
 
 	    <para>This is a forum for technical discussions related to
 	      FreeBSD Conformance to the C99 and the POSIX standards.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-USER-GROUPS</term>
 	  
 	  <listitem>
 	    <para><emphasis>User Group Coordination List</emphasis></para>
 
 	    <para>This is the mailing list for the coordinators from each of
 	      the  local area Users Groups to discuss matters with each other
 	      and a  designated individual from the Core Team.  This mail list
 	      should be limited to meeting synopsis and coordination of
 	      projects that span User Groups.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>FREEBSD-VENDORS</term>
 	  
 	  <listitem>
 	    <para><emphasis>VENDORS</emphasis></para>
 	    
 	    <para>Coordination discussions between The FreeBSD Project and 
 	      Vendors of software and hardware for FreeBSD.</para>
 	  </listitem>
 	</varlistentry>
 
       </variablelist>
     </sect2>
   </sect1>
   
   <sect1 id="eresources-news">
     <title>Usenet Newsgroups</title>
     
     <para>In addition to two FreeBSD specific newsgroups, there are many
       others in which FreeBSD is discussed or are otherwise relevant to
       FreeBSD users.  <ulink
 	url="http://minnie.tuhs.org/BSD-info/bsdnews_search.html">Keyword
 	searchable archives</ulink> are available for some of these newsgroups
       from courtesy of Warren Toomey <email>wkt@cs.adfa.edu.au</email>.</para>
     
     <sect2>
       <title>BSD Specific Newsgroups</title>
       
       <itemizedlist>
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</ulink></para>
 	</listitem>
       </itemizedlist>
     </sect2>
     
     <sect2>
       <title>Other Unix Newsgroups of Interest</title>
       
       <itemizedlist>
 	<listitem>
 	  <para><ulink url="news:comp.unix">comp.unix</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.questions">comp.unix.questions</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.admin">comp.unix.admin</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.programmer">comp.unix.programmer</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.shell">comp.unix.shell</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.user-friendly">comp.unix.user-friendly</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.security.unix">comp.security.unix</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.sources.unix">comp.sources.unix</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.advocacy">comp.unix.advocacy</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.misc">comp.unix.misc</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.bugs.4bsd">comp.bugs.4bsd</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.bugs.4bsd.ucb-fixes">comp.bugs.4bsd.ucb-fixes</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.unix.bsd">comp.unix.bsd</ulink></para>
 	</listitem>
       </itemizedlist>
     </sect2>
     
     <sect2>
       <title>X Window System</title>
       
       <itemizedlist>
 	<listitem>
 	  <para><ulink
 	      url="news:comp.windows.x.i386unix">comp.windows.x.i386unix</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.windows.x">comp.windows.x</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.windows.x.apps">comp.windows.x.apps</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.windows.x.announce">comp.windows.x.announce</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.windows.x.intrinsics">comp.windows.x.intrinsics</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.windows.x.motif">comp.windows.x.motif</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.windows.x.pex">comp.windows.x.pex</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="news:comp.emulators.ms-windows.wine">comp.emulators.ms-windows.wine</ulink></para>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
   
   <sect1 id="eresources-web">
     <title>World Wide Web Servers</title>
     
     <itemizedlist>
       <listitem>
 	<para><ulink
 	    url="../../../../index.html">http://www.FreeBSD.org/</ulink>
 	  &mdash; Central Server.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.au.FreeBSD.org/">http://www.au.FreeBSD.org/</ulink> &mdash; Australia/1.</para>
 	    </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www2.au.FreeBSD.org/">http://www2.au.FreeBSD.org/</ulink> &mdash; Australia/2.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www3.au.FreeBSD.org/">http://www3.au.FreeBSD.org/</ulink> &mdash; Australia/3.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://freebsd.itworks.com.au/">http://freebsd.itworks.com.au/</ulink> &mdash; Australia/4.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.br.FreeBSD.org/www.freebsd.org/">http://www.br.FreeBSD.org/www.freebsd.org/</ulink> &mdash; Brazil/1.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www2.br.FreeBSD.org/www.freebsd.org/">http://www2.br.FreeBSD.org/www.freebsd.org/</ulink> &mdash; Brazil/2.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www3.br.FreeBSD.org/">http://www3.br.FreeBSD.org/</ulink> &mdash; Brazil/3.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.bg.FreeBSD.org/">http://www.bg.FreeBSD.org/</ulink> &mdash; Bulgaria.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.ca.FreeBSD.org/">http://www.ca.FreeBSD.org/</ulink> &mdash; Canada/1.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www2.ca.FreeBSD.org/">http://www2.ca.FreeBSD.org/</ulink> &mdash; Canada/2.</para>
       </listitem>
  
       <listitem>
 	<para><ulink
 	    url="http://www3.ca.FreeBSD.org/">http://www3.ca.FreeBSD.org/</ulink> &mdash; Canada/3.</para>
       </listitem>
  
       <listitem>
 	<para><ulink
 	    url="http://www.cn.FreeBSD.org/">http://www.cn.FreeBSD.org/</ulink> &mdash; China.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www.cz.FreeBSD.org/">http://www.cz.FreeBSD.org/</ulink> &mdash; Czech Republic.</para>
       </listitem>
  
        <listitem>
 	<para><ulink
 	    url="http://www.dk.FreeBSD.org/">http://www.dk.FreeBSD.org/</ulink> &mdash; Denmark.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.ee.FreeBSD.org/">http://www.ee.FreeBSD.org/</ulink> &mdash; Estonia.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.fi.FreeBSD.org/">http://www.fi.FreeBSD.org/</ulink> &mdash; Finland.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www.fr.FreeBSD.org/">http://www.fr.FreeBSD.org/</ulink> &mdash; France.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.de.FreeBSD.org/">http://www.de.FreeBSD.org/</ulink> &mdash; Germany/1.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www1.de.FreeBSD.org/">http://www1.de.FreeBSD.org/</ulink> &mdash; Germany/2.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www2.de.FreeBSD.org/">http://www2.de.FreeBSD.org/</ulink> &mdash; Germany/3.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.gr.FreeBSD.org/">http://www.gr.FreeBSD.org/</ulink> &mdash; Greece.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www.hu.FreeBSD.org/">http://www.hu.FreeBSD.org/</ulink> &mdash; Hungary.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.is.FreeBSD.org/">http://www.is.FreeBSD.org/</ulink> &mdash; Iceland.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.ie.FreeBSD.org/">http://www.ie.FreeBSD.org/</ulink> &mdash; Ireland.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.jp.FreeBSD.org/www.FreeBSD.org/">http://www.jp.FreeBSD.org/www.FreeBSD.org/</ulink> &mdash; Japan.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.kr.FreeBSD.org/">http://www.kr.FreeBSD.org/</ulink> &mdash; Korea/1.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www2.kr.FreeBSD.org/">http://www2.kr.FreeBSD.org/</ulink> &mdash; Korea/2.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www.lv.FreeBSD.org/">http://www.lv.FreeBSD.org/</ulink> &mdash; Latvia.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://rama.asiapac.net/freebsd/">http://rama.asiapac.net/freebsd/</ulink> &mdash; Malaysia.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.nl.FreeBSD.org/">http://www.nl.FreeBSD.org/</ulink> &mdash; Netherlands/1.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www2.nl.FreeBSD.org/">http://www2.nl.FreeBSD.org/</ulink> &mdash; Netherlands/2.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.no.FreeBSD.org/">http://www.no.FreeBSD.org/</ulink> &mdash; Norway.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.nz.FreeBSD.org/">http://www.nz.FreeBSD.org/</ulink> &mdash; New Zealand.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www.pl.FreeBSD.org/">http://www.pl.FreeBSD.org/</ulink> &mdash; Poland/1.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www2.pl.FreeBSD.org/">http://www2.pl.FreeBSD.org/</ulink> &mdash; Poland/2.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.pt.FreeBSD.org/">http://www.pt.FreeBSD.org/</ulink> &mdash; Portugal/1.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www2.pt.FreeBSD.org/">http://www2.pt.FreeBSD.org/</ulink> &mdash; Portugal/2.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www3.pt.FreeBSD.org/">http://www3.pt.FreeBSD.org/</ulink> &mdash; Portugal/3.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.ro.FreeBSD.org/">http://www.ro.FreeBSD.org/</ulink> &mdash; Romania.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.ru.FreeBSD.org/">http://www.ru.FreeBSD.org/</ulink> &mdash; Russia/1.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www2.ru.FreeBSD.org/">http://www2.ru.FreeBSD.org/</ulink> &mdash; Russia/2.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www3.ru.FreeBSD.org/">http://www3.ru.FreeBSD.org/</ulink> &mdash; Russia/3.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www4.ru.FreeBSD.org/">http://www4.ru.FreeBSD.org/</ulink> &mdash; Russia/4.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://freebsd.s1web.com/">http://freebsd.s1web.com/</ulink> &mdash; Singapore.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www.sk.FreeBSD.org/">http://www.sk.FreeBSD.org/</ulink> &mdash; Slovak Republic.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.si.FreeBSD.org/">http://www.si.FreeBSD.org/</ulink> &mdash; Slovenia.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.es.FreeBSD.org/">http://www.es.FreeBSD.org/</ulink> &mdash; Spain.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.za.FreeBSD.org/">http://www.za.FreeBSD.org/</ulink> &mdash; South Africa/1.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www2.za.FreeBSD.org/">http://www2.za.FreeBSD.org/</ulink> &mdash; South Africa/2.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.se.FreeBSD.org/">http://www.se.FreeBSD.org/</ulink> &mdash; Sweden.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www.ch.FreeBSD.org/">http://www.ch.FreeBSD.org/</ulink> &mdash; Switzerland.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www.tw.FreeBSD.org/www.freebsd.org/data/">http://www.tw.FreeBSD.org/www.freebsd.org/data/</ulink> &mdash; Taiwan.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.tr.FreeBSD.org/">http://www.tr.FreeBSD.org/</ulink> &mdash; Turkey.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.ua.FreeBSD.org/www.freebsd.org/">http://www.ua.FreeBSD.org/www.freebsd.org/</ulink> &mdash; Ukraine/1.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www2.ua.FreeBSD.org/">http://www2.ua.FreeBSD.org/</ulink> &mdash; Ukraine/2.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www4.ua.FreeBSD.org/">http://www4.ua.FreeBSD.org/</ulink> &mdash; Ukraine/Crimea.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www.uk.FreeBSD.org/">http://www.uk.FreeBSD.org/</ulink> &mdash; United Kingdom/1.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www2.uk.FreeBSD.org/">http://www2.uk.FreeBSD.org/</ulink> &mdash; United Kingdom/2.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www3.uk.FreeBSD.org/">http://www3.uk.FreeBSD.org/</ulink> &mdash; United Kingdom/3.</para>
       </listitem>
 
       <listitem>
 	<para><ulink
 	    url="http://www6.FreeBSD.org/">http://www6.FreeBSD.org/</ulink> &mdash; USA/Oregon.</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://www2.FreeBSD.org/">http://www2.FreeBSD.org/</ulink> &mdash; USA/Texas.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="eresources-email">
     <title>Email Addresses</title>
 
     <para>The following user groups provide FreeBSD related email addresses
       for their members.  The listed administrator reserves the right to
       revoke the address if it is abused in any way.</para>
 
     <informaltable>
       <tgroup cols="4">
         <thead>
 	  <row>
 	    <entry>Domain</entry>
 	    <entry>Facilities</entry>
 	    <entry>User Group</entry>
 	    <entry>Administrator</entry>
           </row>
 	</thead>
 	  
 	<tbody>
 	  <row>
 	    <entry>ukug.uk.FreeBSD.org</entry>
 	    <entry>Forwarding only</entry>
 	    <entry><email>freebsd-users@uk.FreeBSD.org</email></entry>
 	    <entry>Lee Johnston
 	      <email>lee@uk.FreeBSD.org</email></entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
   </sect1>
 
   <sect1 id="eresources-shell">
     <title>Shell Accounts</title>
 
     <para>The following user groups provide shell accounts for people who are
       actively supporting the FreeBSD project.  The listed administrator
       reserves the right to cancel the account if it is abused in any
       way.</para>
 
     <informaltable>
       <tgroup cols="4">
 	<thead>
 	  <row>
 	    <entry>Host</entry>
 	    <entry>Access</entry>
 	    <entry>Facilities</entry>
 	    <entry>Administrator</entry>
           </row>
 	</thead>
 	  
 	<tbody>
 	  <row>
 	    <entry>storm.uk.FreeBSD.org</entry>
 	    <entry>SSH only</entry>
 	    <entry>Read-only cvs, personal web space, email</entry>
-	    <entry>&a.brian</entry>
+	    <entry>&a.brian;</entry>
           </row>
 
 	  <row>
 	    <entry>dogma.freebsd-uk.eu.org</entry>
 	    <entry>Telnet/FTP/SSH</entry>
 	    <entry>Email, Web space, Anonymous FTP</entry>
             <entry>Lee Johnston
 		<email>lee@uk.FreeBSD.org</email></entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
   </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/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
index c242176c57..c11db5ce21 100644
--- a/en_US.ISO8859-1/books/handbook/install/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
@@ -1,5358 +1,5358 @@
 <!--
      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>
     <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.</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 really 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">
 	  <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>4GB, 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>2GB, 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>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 several times 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 all your disk, then there is nothing
 	more to concern yourself with at this point &mdash; you can skip to the
 	next 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 in to 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 <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 100MB 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 250MB without a graphical environment, and 350MB 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>Partition
 	  Magic</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,
 	<application>FIPS</application> and
 	<application>PResizer</application>.  Documentation for both of these
 	is in the same directory.</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 4GB disk that
 	  already has a version of Windows installed, and you have split the
 	  disk in to two drive letters, <devicename>C:</devicename> and
 	  <devicename>D:</devicename>, each of which is 2GB in size.  You have
 	  1GB of data on <devicename>C:</devicename>, and 0.5GB 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 4GB 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 4GB in size.  You are
 	  currently using 1.5GB of space, and want FreeBSD to have 2GB 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 2GB partition at install time.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use one of the tools such as <application>Partition
 		Magic</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 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 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>
 	</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 in to
 	the process.  On very rare occasions those bugs affect the
 	installation process.  As these problems are discovered and fixed they
 	are noted in the FreeBSD Errata, posted 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="../../../../releases/index.html">release
 	information</ulink> section of the 
 	<ulink
 	  url="../../../../index.html">FreeBSD web site</ulink>.</para>
     </sect2>
 
     <sect2 id="install-floppies">
       <title>Prepare the Boot Discs</title>
       
       <para>FreeBSD can be installed from a number of different media; CDROM,
 	DVD, FTP (both anonymous and non-anonymous), NFS, tape, or an existing
 	MS-DOS partition.</para>
 
       <tip>
 	<para>If you have FreeBSD on CDROM or DVD, 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>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.  To do this, you must create some
 	floppy disks that can be booted from, and then boot from them.</para>
 
       <para>If you are <emphasis>not</emphasis> installing directly from
 	CDROM, DVD, or FTP then you are probably preparing your own
 	installation media (e.g., an MS-DOS partition), which must be prepared
 	before you install FreeBSD.  This is a slightly more advanced, 
 	infrequent activity, and is documented in <xref
 	linkend="install-diff-media">.  This includes the scenario where you
 	want to create your own FTP site on your own network so that other
 	computers can use your site as a FreeBSD FTP installation site.</para>
 
       <para>In general, to create boot floppy images, follow these
 	steps:</para>
 
       <procedure>
 	<step>
 	  <title>Acquire the Boot Floppy Images</title>
 	  
 	  <para>The boot discs are available on your installation media
 	    in the floppies directory, and
 	    can also be downloaded from the <ulink
 	    url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/">
 	      floppies directory</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.  In most cases you will need two
 	    files, <filename>kern.flp</filename> and
 	    <filename>mfsroot.flp</filename>, but check
 	    <filename>README.TXT</filename> in the same directory to be
 	    sure.</para>
 
 	  <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.</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 some other 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.
 	    Instead, they are images of the complete contents of the
 	    disk.  This means that you <emphasis>cannot</emphasis> use
 	    commands like DOS' <command>copy</command> to write the
 	    files.  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
       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>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 your 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 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>
 	</orderedlist>
 	</step>
     
 	<step>
 	  <para>FreeBSD will start to boot.  If you are booting from CDROM you
 	    will see a display similar to this:</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 C: is disk3
 BIOS 639kB/261120kB available memory
 
 FreeBSD/i386 bootstrap loader, Revision 0.8
 (murray@builder.freebsdmall.com, Thu Jan 17 19:28:57 PST 2002)
 /kernel text=0x266691 data=0x407c+0x20d68 \
 |
 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:</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 
  (murray@builder.freebsdmall.com, Thu Jan 17 19:28:57 PST 2002) 
 /kernel text=0x266691 data=0x407c+0x20d68 | 
 
 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>Irrespective of 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>
       <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>Irrespective of 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>
 
       <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
 	together, and probing for one piece of hardware can sometimes leave
 	another in an inconsistent state.  This is a basic
 	limitation of the design of the PC.</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 be
 	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 in to 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>
 	</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 in to groups such as
 	    <literal>Storage</literal>, and <literal>Network</literal>.  Each
 	    driver is shown as a description, its two 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 in to 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>
 	</mediaobject>
       </figure>
 
       <para>At this point there will always be conflicts listed.  Do not worry
 	about this, 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>
 
 	  <important>
 	    <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>
 	  </important>
 
 	  <important>
 	    <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>
 	  </important>
 	</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 in to 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 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 = 254611456 (248644K bytes)
 Preloaded elf kernel "kernel" at 0xc069a000.
 Preloaded mfs_root "/mfsroot" at 0xc069a084.
 md1: Malloc disk
 npx0: &lt;math processor> on motherboard
 npx0: INT 16 interface
 pcib0: &lt;Host to PCI bridge> on motherboard
 pci0: &lt;PCI bus> on pcib0
 pcib1: &lt;VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP bridge> at device 1.0 on pci0
 pci1: &lt;PCI bus> on pcib1
 pci1: &lt;Matrox MGA G200 AGP graphics accelerator> at 0.0 irq 11
 isab0: &lt;VIA 82C586 PCI-ISA bridge> at device 7.0 on pci0
 isa0: &lt;ISA bus> on isab0
 atapci0: &lt;VIA 82C586 ATA33 controller> port 0xe000-0xe00f at device 7.1 on pci0
 ata0: at 0x1f0 irq 14 on atapci0
 uhci0: &lt;VIA 83C572 USB controller> port 0xe400-0xe41f irq 10 at device 7.2 on pci0
 usb0: &lt;VIA 83C572 USB controller> 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> at device 7.3 on pci0
 ed0: &lt;NE2000 PCI Ethernet (RealTek 8029)> port 0xe800-0xe81f irq 9 at device 10.0 on pci0
 ed0: address 52:54:05:de:73:1b, type NE2000 (16bit)
 isa0: too many dependant configs (8)
 isa0: unexpected small tag 14
 orm0; &lt;Option ROM> at iomem 0xc0000-0xc7fff on isa0
 fdc0: &lt;NEC 72065B or clone> at port 0x3f0-0x3f5,0x3f7 irq6 drq2 on isa0
 fdc0: FIFO enabled, 8 bytes threshold
 fd0: &lt;1440-KB 3.5" drive> on fdc0 drive 0
 atkbdc0: &lt;keyboard controller (i8042)> at port 0x60-0x64 on isa0
 atkbd0: &lt;AT Keyboard> flags 0x1 irq 1 on atkbdc0
 kbd0 at atkbd0
 psm0: &lt;PS/2 Mouse> irq 12 on atkbdc0
 psm0: model Generic PS/2 mouse, device ID 0
 vga0: &lt;Generic ISA VGA> at port 0x3c0-0c3df iomem 0xa0000-0xbffff on isa0
 sc0: &lt;System console> at flags 0x100 on isa0
 sc0: VGA &lt;16 virtual consoles, flags-0x300>
 sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0
 sio0: type 16550A
 sio1: at port 0x2f8-0x2ff irq3 on isa0
 sio1: type 16550A
 ppc0: &lt;Parallel port> 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:
 ppi0: &lt;Parallel I/O> on ppbus0
 plip0: &lt;PLIP network interface> on ppbus0
 ad0: 8063MB &lt;IBM-DHEA-38451> [16383/16/63] at ata0-master using UDMA33
 acd0: CDROM &lt;DELTA OTC-H101/ST3 F/W by OIPD> at ata0-slave using 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,
 	its easy to exit the <command>sysinstall</command> program
 	and start over again.  Its 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 <guibutton>[Yes]</guibutton> is selected.</para>
 
       <para>If you are booting from floppies it will be necessary to remove
 	the <filename>mfs.root</filename> floppy and replace it with
 	<filename>kern.flp</filename> before rebooting.</para>
     </sect2>
   </sect1>
 
   <sect1 id="using-sysinstall">
     <title>Introducing Sysinstall</title>
 
     <para><application>Sysinstall</application> 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's</application> 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></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; 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.</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>Ghost</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 -- 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>
       <title>Disk Organization</title>
 
       <para>The smallest unit of organization that FreeBSD uses to find files
 	is the filename.  Filenames are case-sensitive, which means that
 	<filename>readme.txt</filename> and <filename>README.TXT</filename>
 	are two separate files.  FreeBSD does not use the extension
 	(<filename>.txt</filename>) of a file to determine whether the file is
 	program, or a document, or some other form of data.</para>
 
       <para>Files are stored in directories.  A directory may contain no
 	files, or it may contain many hundreds of files.  A directory can also
 	contain other directories, allowing you to build up a hierarchy of
 	directories within one another.  This makes it much easier to organize
 	your data.</para>
 
       <para>Files and directories are referenced by giving the file or
 	directory name, followed by a forward slash, <literal>/</literal>,
 	followed by any other directory names that are necessary.  If you have
 	directory <filename>foo</filename>, which contains directory
 	<filename>bar</filename>, which contains the file
 	<filename>readme.txt</filename>, then the full name, or
 	<firstterm>path</firstterm> to the file is
 	<filename>foo/bar/readme.txt</filename>.</para>
 
       <para>Directories and files are stored in a filesystem.  Each filesystem
 	contains exactly one directory at the very top level, called the
 	<firstterm>root directory</firstterm> for that filesystem.  This root
 	directory can then contain other directories.</para>
 
       <para>So far this is probably similar to any other operating system you
 	may have used.  There are a few differences; for example, DOS uses
 	<literal>\</literal> to separate file and directory names, while MacOS
 	uses <literal>:</literal>.</para>
 
       <para>FreeBSD does not use drive letters, or other drive names in the
 	path.  You would not write <filename>c:/foo/bar/readme.txt</filename>
 	on FreeBSD.</para>
 
       <para>Instead, one filesystem is designated the <firstterm>root
 	  filesystem</firstterm>.  The root filesystem's root directory is
 	referred to as <literal>/</literal>.  Every other filesystem is then
 	<firstterm>mounted</firstterm> under the root filesystem.  No matter
 	how many disks you have on your FreeBSD system, every directory
 	appears to be part of the same disk.</para>
 
       <para>Suppose you have three filesystems, called <literal>A</literal>,
 	<literal>B</literal>, and <literal>C</literal>.  Each filesystem has
 	one root directory, which contains two other directories, called
 	<literal>A1</literal>, <literal>A2</literal> (and likewise
 	<literal>B1</literal>, <literal>B2</literal> and
 	<literal>C1</literal>, <literal>C2</literal>).</para>
 
       <para>Call <literal>A</literal> the root filesystem.  If you used the
 	<command>ls</command> command to view the contents of this directory
 	you would see two subdirectories, <literal>A1</literal> and
 	<literal>A2</literal>.  The directory tree looks like this.</para>
 
       <literallayout class="monospaced"> /
  |
  +--- A1
  |
  `--- A2</literallayout>
 
       <para>A filesystem must be mounted on to a directory in another
 	filesystem.  So now suppose that you mount filesystem
 	<literal>B</literal> on to the directory <literal>A1</literal>.  The
 	root directory of <literal>B</literal> replaces <literal>A1</literal>,
 	and the directories in <literal>B</literal> appear accordingly.</para>
 
       <literallayout class="monospaced"> /
  | 
  +--- A1
  |     |
  |     +--- B1
  |     |
  |     `--- B2
  |
  `--- A2</literallayout>
 
       <para>Any files that are in the <literal>B1</literal> or
 	<literal>B2</literal> directories can be reached with the path
 	<filename>/A1/B1</filename> or <filename>/A1/B2</filename> as
 	necessary.  Any files that were in <filename>/A1</filename> have been
 	temporarily hidden.  They will reappear if <literal>B</literal> is
 	<firstterm>unmounted</firstterm> from A.</para>
 
       <para>If <literal>B</literal> had been mounted on <literal>A2</literal>
 	then the diagram would look like this;</para>
 
       <literallayout class="monospaced"> /
  |
  +--- A1
  |
  `--- A2
        |
        +--- B1
        |
        `--- B2</literallayout>
 
       <para>and the paths would be <filename>/A2/B1</filename> and
 	<filename>/A2/B2</filename> respectively.</para>
 
       <para>Filesystems can be mounted on top of one another.  Continuing the
 	last example, the <literal>C</literal> filesystem could be mounted on
 	top of the <literal>B1</literal> directory in the <literal>B</literal>
 	filesystem, leading to this arrangement.</para>
 
       <literallayout class="monospaced"> /
  |
  +--- A1
  |
  `--- A2
        |
        +--- B1
        |     |
        |     +--- C1
        |     |
        |     `--- C2
        |
        `--- B2</literallayout>
 
       <para>Or <literal>C</literal> could be mounted directly on to the
 	<literal>A</literal> filesystem, under the <literal>A1</literal>
 	directory.</para>
 
       <literallayout class="monospaced"> /
  |
  +--- A1
  |     |
  |     +--- C1
  |     |
  |     `--- C2
  |
  `--- A2
        |
        +--- B1
        |
        `--- B2</literallayout>
 
       <para>If you are familiar with DOS, this is similar, although not
 	identical, to the <command>join</command> command.</para>
 
       <para>This is not normally something you need to concern yourself with.
 	Typically you create filesystems when installing FreeBSD and decide
 	where to mount them, and then never change them unless you add a new
 	disk.</para>
 
       <para>It is entirely possible to have one large root filesystem, and not
 	need to create any others.  There are some drawbacks to this approach,
 	and one advantage.</para>
 
       <itemizedlist>
 	<title>Benefits of multiple filesystems</title>
       
 	<listitem>
 	  <para>Different filesystems can have different <firstterm>mount
 	      options</firstterm>.  For example, with careful planning, the
 	    root filesystem can be mounted read-only, making it impossible for
 	    you to inadvertently delete or edit a critical file.</para>
 	</listitem>
 
 	<listitem>
 	  <para>FreeBSD automatically optimizes the layout of files on a
 	    filesystem, depending on how the filesystem is being used.  So a
 	    filesystem that contains many small files that are written
 	    frequently will have a different optimization to one that contains
 	    fewer, larger files.  By having one big filesystem this
 	    optimization breaks down.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>FreeBSD's filesystems are very robust should you lose power.
 	    However, a power loss at a critical point could still damage the
 	    structure of the filesystem.  By splitting your data over multiple
 	    filesystems it is more likely that the system will still come up,
 	    making it easier for you to restore from backup as
 	    necessary.</para>
 	</listitem>
       </itemizedlist>
 
       <itemizedlist>
 	<title>Benefit of a single filesystem</title>
 
 	<listitem>
 	  <para>Filesystems are a fixed size.  If you create a filesystem when
 	    you install FreeBSD and give it a specific size, you may later
 	    discover that you need to make the partition bigger.  This is not
 	    easily accomplished without backing up, recreating the filesystems
 	    with the size, and then restoring.</para>
 
 	  <important>
 	    <para>FreeBSD 4.4 and up have a featured command, the
-	      &man.growfs.8, which will makes it possible to
+	      &man.growfs.8;, which will makes it possible to
 	      increase the size of a filesystem on the fly, removing this
 	      limitation.</para>
 	  </important>
 	</listitem>
       </itemizedlist>
     
       <para>Filesystems are contained in partitions.  This does not have the
 	same meaning as the earlier usage of the term partition in this
 	chapter, because of FreeBSD's Unix heritage.  Each partition is
 	identified by a letter, <literal>a</literal> through to
 	<literal>h</literal>.  Each partition can only contain one filesystem,
 	which means that filesystems are often described by either their
 	typical mount point on the root filesystem, or the letter of the
 	partition they are contained in.</para>
 
       <para>FreeBSD also uses disk space for <firstterm>swap
 	  space</firstterm>. Swap space provides FreeBSD with
 	<firstterm>virtual memory</firstterm>.  This allows your computer to
 	behave as though it has much more memory than it actually does.  When
 	FreeBSD runs out of memory it moves some of the data that is not
 	currently being used to the swap space, and moves it back in (moving
 	something else out) when it needs it.</para>
 
       <para>Some partitions have certain conventions associated with
 	them.</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Partition</entry>
 
 	      <entry>Convention</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><literal>a</literal></entry>
 
 	      <entry>Normally contains the root filesystem</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>b</literal></entry>
 
 	      <entry>Normally contains swap space</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>c</literal></entry>
 
 	      <entry>Normally the same size as the enclosing slice.  This
 		allows utilities that need to work on the entire slice (for
 		example, a bad block scanner) to work on the
 		<literal>c</literal> partition.  You would not normally create
 		a filesystem on this partition.</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>d</literal></entry>
 
 	      <entry>Partition <literal>d</literal> used to have a special
 		meaning associated with it, although that is now gone.  To
 		this day, some tools may operate oddly if told to work on
 		partition <literal>d</literal>, so
 		<application>Sysinstall</application> will not normally create
 		partition <literal>d</literal>.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>Each partition-that-contains-a-filesystem is stored in what
 	FreeBSD calls a <firstterm>slice</firstterm>.  Slice is FreeBSD's term
 	for what were earlier called partitions, and again, this is because of
 	FreeBSD's Unix background.  Slices are numbered, starting at 1,
 	through to 4.</para>
 
 	<indexterm><primary>slices</primary></indexterm>
 	<indexterm><primary>partitions</primary></indexterm>
 	<indexterm><primary>dangerously dedicated</primary></indexterm>
 
       <para>Slice numbers follow
 	the device name, prefixed with an <literal>s</literal>,
 	starting at 1. So <quote>da0<emphasis>s1</emphasis></quote>
 	is the first slice on the first SCSI drive. There can only be
 	four physical slices on a disk, but you can have logical
 	slices inside physical slices of the appropriate type. These
 	extended slices are numbered starting at 5, so
 	<quote>ad0<emphasis>s5</emphasis></quote> is the first
 	extended slice on a disk. These devices are used by file
 	systems that expect to occupy a slice.</para> 
 
       <para>Slices, <quote>dangerously dedicated</quote> physical
 	drives, and other drives contain
 	<firstterm>partitions</firstterm>, which are represented as
 	letters from <literal>a</literal> to <literal>h</literal>.
 	This letter is appended to the device name, so
 	<quote>da0<emphasis>a</emphasis></quote> is the a partition on
 	the first da drive, which is <quote>dangerously dedicated</quote>.
 	<quote>ad1s3<emphasis>e</emphasis></quote> is the fifth partition
 	in the third slice of the second IDE disk drive.</para>
 	
       <para>Finally, each disk on the system is identified.  A disk name
 	starts with a code that indicates the type of disk, and then a number,
 	indicating which disk it is.  Unlike slices, disk numbering starts at
 	0. Common codes that you will see are listed in 
 	<xref linkend="install-dev-codes">.</para>
 
       <para>When referring to a partition FreeBSD requires that you also name
 	the slice and disk that contains the partition, and when referring to
 	a slice you should also refer to the disk name.  Do this by listing
 	the disk name, <literal>s</literal>, the slice number, and then the
 	partition letter.  Examples are shown in 
 	<xref linkend="install-disk-slice-part">.</para>
 
       <para><xref linkend="install-concept-disk-model"> shows a conceptual
 	model of the disk layout that should help make things clearer.</para>
 
       <para>In order to install FreeBSD you must first configure the disk
 	slices, then create partitions within the slice you will use for
 	FreeBSD, and then create a filesystem (or swap space) in each
 	partition, and decide where that filesystem will be mounted.</para>
 
       <table frame="none" id="install-dev-codes">
 	<title>Disk Device Codes</title>
 
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Code</entry>
 	    
 	      <entry>Meaning</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><devicename>ad</devicename></entry>
 
 	      <entry>ATAPI (IDE) disk</entry>
 	    </row>
 
 	    <row>
 	      <entry><devicename>da</devicename></entry>
 	      
 	      <entry>SCSI direct access disk</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><devicename>acd</devicename></entry>
 	      
 	      <entry>ATAPI (IDE) CDROM</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><devicename>cd</devicename></entry>
 	      
 	      <entry>SCSI CDROM</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><devicename>fd</devicename></entry>
 	      
 	      <entry>Floppy disk</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
       
       <example id="install-disk-slice-part">
 	<title>Sample Disk, Slice, and Partition Names</title>
 	
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Name</entry>
 		
 		<entry>Meaning</entry>
 	      </row>
 	    </thead>
 	    
 	    <tbody>
 	      <row>
 		<entry><literal>ad0s1a</literal></entry>
 		
 		<entry>The first partition (<literal>a</literal>) on the first
 		  slice (<literal>s1</literal>) on the first IDE disk
 		  (<literal>ad0</literal>).</entry>
 	      </row>
 
 	      <row>
 		<entry><literal>da1s2e</literal></entry>
 		
 		<entry>The fifth partition (<literal>e</literal>) on the
 		  second slice (<literal>s2</literal>) on the second SCSI disk
 		  (<literal>da1</literal>).</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
       </example>
 
       <example id="install-concept-disk-model">
 	<title>Conceptual Model of a Disk</title>
 
 	<para>This diagram shows FreeBSD's view of the first IDE disk attached
 	  to the system.  Assume that the disk is 4GB in size, and contains
 	  two 2GB slices (DOS partitions).  The first slice contains a DOS
 	  disk, <devicename>C:</devicename>, and the second slice contains a
 	  FreeBSD installation.  This example FreeBSD installation has three
 	  partitions, and a swap partition.</para>
 
 	<para>The three partitions will each hold a filesystem.  Partition
 	  <literal>a</literal> will be used for the root filesystem,
 	  <literal>e</literal> for the <filename>/var</filename> directory
 	  hierarchy, and <literal>f</literal> for the
 	  <filename>/usr</filename> directory hierarchy.</para>
 
         <mediaobject>
           <imageobject>
             <imagedata fileref="install/disk-layout" format="EPS">
           </imageobject>
  
           <textobject>
 	    <literallayout class="monospaced">.-----------------.  --.
 |                 |    |
 |  DOS / Windows  |    |
 :                 :     >  First slice, ad0s1
 :                 :    |
 |                 |    |
 :=================:  ==:                               --.
 |                 |    |  Partition a, mounted as /      |
 |                 |     > referred to as ad0s2a          |
 |                 |    |                                 |
 :-----------------:  ==:                                 |
 |                 |    |  Partition b, used as swap      |
 |                 |     > referred to as ad0s2b          |
 |                 |    |                                 |
 :-----------------:  ==:                                 |  Partition c, no
 |                 |    |  Partition e, used as /var       > filesystem, all 
 |                 |     > referred to as ad0s2e          |  of FreeBSD slice,
 |                 |    |                                 |  ad0s2c
 :-----------------:  ==:                                 |
 |                 |    |                                 |
 :                 :    |  Partition f, used as /usr      |
 :                 :     > referred to as ad0s2f          |
 :                 :    |                                 |
 |                 |    |                                 |
 |                 |  --'                                 |
 `-----------------'                                    --'</literallayout>
           </textobject>
         </mediaobject>
       </example>
     </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.  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 to continue ]</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 in to 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 FAT slice, which almost certainly appears
 	as <devicename>C:</devicename> in DOS / Windows, and an extended
 	slice, which may contain other drive letters for 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 then 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>.</para>
       
       <para>If you have already made space for FreeBSD (perhaps by using a
 	tool such as <application>Partition Magic</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>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>
 
       <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">
 	<title>Partition Layout for First Disk</title>
 
 	<tgroup cols="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>100MB</entry>
 
 	      <entry>This is the root file system.  Every other filesystem
 		will be mounted somewhere under this one.  100MB 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 40MB 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).  So if you have
 		  You should also have at least 64MB of swap, so if you have
 		  less than 32MB of RAM in your computer then set the swap
 		  amount to 64MB.</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., 128MB), 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, 64MB of swap per
 		  disk.</para></entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>e</literal></entry>
 
 	      <entry><filename>/var</filename></entry>
 
 	      <entry>50MB</entry>
 
 	      <entry>The <filename>/var</filename> directory contains variable
 		length files; 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 optimise 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">
 	<title>Partition Layout for Subsequent Disks</title>
 
 	<tgroup cols="4">
 	  <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  ] </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 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>To delete the suggested partitions, and 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>), make sure the disk information 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, more usefully, as a
 	number followed by either <literal>M</literal> for megabytes,
 	<literal>G</literal> for gigabytes, or <literal>C</literal> for
 	cylinders.</para>
 
       <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
 	earlier, 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 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 then 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>
     <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 XFree86 and selection of a default
 	desktop is part of the post-installation steps.</para>
 
       <para>The default XFree86 version installed is the 3.x branch.  You
 	should check to see whether your video card is supported at the
 	<ulink url="http://www.xfree86.org/">XFree86</ulink> web site.
 	If it is only supported under the 4.x branch, then you will need
 	to install and configure XFree86 4.x after installation.  Select a
 	distribution without X and refer to <xref linkend="x11"> for
 	more information.</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.  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.  It is a collection of files which
 	automates the downloading, compiling and installation.
 	<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.</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 100MB 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 <guibutton>[ Yes ]</guibutton> with the arrow keys to
 	install the ports collection or <guibutton>[ No ]</guibutton> 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 press
 	<keycap>Enter</keycap> to continue.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="install-media">
     <title>Choosing Your Installation Media</title>
 
     <para>If Installing from a CDROM, 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 FreeBSD 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 port
 	      addresses.</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 FreeBSD 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 <guibutton>[ Yes ]</guibutton> and press 
       <keycap>Enter</keycap> to proceed.</para>
 
     <para>The installation time will vary according to the distribution
       chosen, installation media used, 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 <guibutton>[ No ]</guibutton> 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 try and 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>/stand/sysinstall</command> 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 tutorial
 	<ulink url="../ppp-primer/index.html">
 	PPP- Pendantic PPP Primer</ulink>.</para>
 
       <screen>                      User Confirmation Requested 
    Would you like to configure Ethernet or SLIP/PPP network devices?
 
                              [ Yes ]   No</screen>
 
       <para>To configure a network device, select
 	<guibutton>[ Yes ]</guibutton> and press <keycap>Enter</keycap>.
       Otherwise, select <guibutton>[ No ]</guibutton> 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 (IPv4) was sufficient and <guibutton>[ No ]</guibutton>
 	was selected with the arrow keys and <keycap>Enter</keycap>
 	pressed.</para>
 
       <para>If you want to try the new Internet protocol (IPv6), choose
 	<guibutton>[ Yes ]</guibutton> 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 <guibutton>[ No ]</guibutton> with the arrow keys and press
 	<keycap>Enter</keycap>.</para>
 
       <para>Selecting <guibutton>[ Yes ]</guibutton> will execute
 	<application>dhclient</application>, and if successful, will fill
 	in the network configuration information automatically.  Refer to
 	<xref linkend="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, e.g. k6-2.example.com in
 	      this case.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Domain</term>
 
 	  <listitem>
 	    <para>The name of the domain that your machine is
 	      in, e.g. example.com for this case.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>IPv4 Gateway</term>
 
 	  <listitem>
 	    <para>IP address of host forwarding packets to non-local
 	      destinations. Fill this in only 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.</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 (208.163.10.2) was
 	      used.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>IPv4 address</term>
 
 	  <listitem>
 	    <para>The IP address to be used for this interface was
 	      (192.168.0.1).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Netmask</term>
 
 	  <listitem>
 	    <para>The address block being used for this local area
 	      network is a Class C block (192.168.0.0 -
 	      192.168.255.255).  The default netmask is for a Class C
 	      network (255.255.255.0).</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 <guibutton>[ Yes ]</guibutton> and pressing
 	<keycap>Enter</keycap> will bring
 	the machine up on the network and be ready for use after leaving
 	leaving the installation.</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
 	<guibutton>[ Yes ]</guibutton> and press <keycap>Enter</keycap>.
 	If the machine is a node on a network then 
 	select <guibutton>[ No ]</guibutton> 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 <guibutton>[ No ]</guibutton> 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="inetd-overview"> for more information.</para>
 
       <para>Select <guibutton>[ Yes ]</guibutton> 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 <guibutton>[ Yes ]</guibutton> 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 seperately 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 <guibutton>[ Yes ]</guibutton> 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>
 
       <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 <guibutton>[ No ]</guibutton> 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
 	  <guibutton>[ Yes ]</guibutton> and press <keycap>Enter</keycap>.
 	  The following screens (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 <guibutton>[ Yes ]</guibutton> 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.</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>
     </sect2>
 
     <sect2 id="nfsconf">
       <title>Configure Network File Services</title>
 
       <para>Network File Services (NFS) allows sharing of files across a
 	network.  A machine can be configured as a server, a client, or
 	both.  Refer to <xref linkend="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 or
 	  client, select <guibutton>[ No ]</guibutton> and press
 	  <keycap>Enter</keycap>.</para>
 
 	<para>If <guibutton>[ Yes ]</guibutton> is chosen, a message will
 	  pop-up indicating that the exports 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 file systems.
 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 exports file to be created and edited.</para>
 
 	<figure id="nfs-server-edit">
 	  <title>Editing the Exports File</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
 	  filename/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>
 
 	<screen>                       User Confirmation Requested
  Do you want to configure this machine as an NFS client? 
 
                               Yes   [ No ]</screen>
 
 	<para>With the arrow keys, select <guibutton>[ Yes ]</guibutton>
 	  or <guibutton>[ No ]</guibutton> 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 (2)
 		<footnote>
 		  <para>If you choose a security profile that sets the
 		    securelevel (Extreme or High), 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 <guibutton>[ No ]</guibutton> and pressing
 	<keycap>Enter</keycap> will set the security profile to medium.</para>
 
       <para>Selecting <guibutton>[ Yes ]</guibutton> 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 <ulink
 	  url="../handbook/eresources.html#ERESOURCES-MAIL">mailing
 	  list</ulink>, 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
 	<guibutton>[ Yes ]</guibutton> 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 screensaver.  Use the arrow keys
 	to select <guimenuitem>Saver</guimenuitem> and then press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="saver-select">
 	<title>Screensaver 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
 	Screensaver 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>Screensaver 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 timezone for your machine will allow it to
 	automatically correct for any regional time changes and perform
 	other timezone 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 <guibutton>[ Yes ]</guibutton> 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 <guibutton>[ Yes ]</guibutton> 
 	or <guibutton>[ No ]</guibutton> 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 press <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 Timezone</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 <guibutton>[ Yes ]</guibutton> and pressing
 	<keycap>Enter</keycap> will allow
 	running Linux software on FreeBSD.  The install will proceed to 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.</para>
 
       <screen>                      User Confirmation Requested 
          Does this system have a non-USB mouse attached to it?
 
                             [ Yes ]   No</screen>
 
       <para>Select <guibutton>[ Yes ]</guibutton> for a non-USB mouse or
 	<guibutton>[ No ]</guibutton> 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, the mouse daemon is enabled and tested.</para>
 
       <figure id="test-mouse-daemon">
 	<title>Test The Mouse Daemon</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse6" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The cursor moved around the screen so the mouse daemon is
 	running:</para>
 
       <para>Select <guibutton>[ Yes ]</guibutton> to return to the previous
 	menu then 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="x-server">
       <title>Configure X-Server</title>
 
       <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>
 
       <para>To see whether your video card is supported, check the
 	<ulink url="http://www.xfree86.org/">XFree86</ulink> web site.
 	If your video card is only supported under XFree86 4.x, refer to
 	<xref linkend="x11"> for installation and configuration.</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
 	  <guibutton>[ No ]</guibutton> and perform the configuration
 	  after installation when you have the information using 
 	  <command>/stand/sysinstall</command>, selecting
 	  <guimenuitem>Configure</guimenuitem> and then 
 	  <guimenuitem>XFree86</guimenuitem>.
 	</para>
       </warning>
 
       <para>If you have graphics card and monitor information, select
 	<guibutton>[ Yes ]</guibutton> 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. <application>XF86Setup</application> is fully graphical and
 	probably the easiest.  Use the arrow keys to select the
 	<guimenuitem>XF86Setup</guimenuitem> and press
 	<keycap>Enter</keycap>.</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>
 
       <screen>                Press [Enter] to switch to graphics mode. 
 
                          This may take a while... 
 
                                  [ OK ]</screen>
 
       <para>Press <keycap>Enter</keycap> to switch to the graphics mode and
 	continue. It will <emphasis>not</emphasis> try to switch to the
 	graphics mode until <keycap>Enter</keycap> is pressed.  The screen
 	will go black and then shortly a screen with a large X in the
 	center will appear. Be patient and wait.</para>
 
       <para>After a few more moments, the <application>XF86Setup</application>
 	introduction will display.  Read all instructions
 	<emphasis>carefully</emphasis>.  Press <keycap>Enter</keycap> to
 	continue.</para>
 
       <procedure>
 	<title><application>XF86Setup</application> Overview</title>
 
 	<para>There are several areas of configuration to be completed.
 	  The configuration choices you make will depend on the hardware
 	  in the system so only a general overview can be given here.</para>
 
 	<para>Along the top of the configuration tool there are buttons
 	  indicating the areas to be configured.  You should be able to use
 	  the mouse if it was previously configured and select each item by
 	  clicking on it.  Review each area and make appropriate selections
 	  for your system.</para>
 
 	<step>
 	<title><guimenuitem>Mouse</guimenuitem></title>
 
 	  <para>The mouse is the first item to be configured.  If you
 	    previously configured your mouse, the mouse daemon will already
 	    be running and should indicate <guimenuitem>SysMouse</guimenuitem>
 	    automatically for the mouse protocol.  If you are use a two
 	    button mouse, you should also select 
 	    <guimenuitem>Emulate3Buttons</guimenuitem>.  There are other
 	    settings that can be tweaked if necessary.</para>
 
 	  <para>After completing your selections, click on the 
 	    <guimenuitem>Apply</guimenuitem> and check the mouse actions are
 	    working properly.  If further adjustment is needed, make them
 	    and recheck the operation by clicking on 
 	    <guimenuitem>Apply</guimenuitem> again.  When finished, move
 	    on to the next item.</para>
 	</step>
 
 	<step>
 	  <title><guimenuitem>Keyboard</guimenuitem></title>
 
 	  <para>Select the appropriate keyboard model.  The default
 	    keyboard is <guimenuitem>Generic 101-key PC</guimenuitem>.</para>
 
 	  <para>Select the language layout for your keyboard.  The default
 	    layout is <guimenuitem>U.S. English</guimenuitem>.  If you are
 	    not using a U.S. keyboard, you may need to additionally
 	    select a variant.</para>
 
 	  <para>There are other options under Group Shift/Lock behavior and
 	    Control Key Position that can be selected if desired.  Generally
 	    the default settings are fine.</para>
 
 	  <para>After completing the keyboard configuration, click on
 	    <guimenuitem>Apply</guimenuitem> and move on to the next
 	    item.</para>
 	</step>
 
 	<step>
 	  <title><guimenuitem>Card</guimenuitem></title>
 
 	  <para>Click on <guimenuitem>Read README file</guimenuitem> for
 	    additional help in configuring your video card.</para>
 
 	  <para>Select the appropriate video card from the list using the
 	    scrollbar. Clicking on your card will show as
 	    <quote>Card selected:</quote> above the list box.</para>
 
 	  <para>Next, the <guimenuitem>Detailed Setup</guimenuitem> was
 	    selected just to check details.  Typically, if your video
 	    card was in the list, no changes will be needed here.</para>
 
 	  <para>When finished, move on to the next item.</para>
 	</step>
 
 	<step>
 	  <title><guimenuitem>Monitor</guimenuitem></title>
 
 	  <para>There are two ways to proceed. One method requires that you
 	    enter the horizontal and vertical sweep capabilities of your
 	    monitor in the text boxes.</para>
 
 	  <para>Choosing one of the monitor options listed that the monitor
 	    is the other method.  After selecting a listed option, the
 	    horizontal and vertical sweep rates that will be used will
 	    display. Compare those to your monitor specifications.  The
 	    monitor must be capable of using those ranges.</para>
 
 	  <para>Do not exceed the ratings of your monitor. Damage could
 	    occur. If you have doubts select <guimenuitem>ABORT</guimenuitem>
 	    and get the information. The remainder of the installation process
 	    will be unaffected and configuring the X-Server can be done
 	    later using <command>/stand/sysinstall</command>.</para>
 
 	  <para>When finished, move on to the next item.</para>
 	</step>
 
 	<step>
 	  <title><guimenuitem>Mode</guimenuitem></title>
 
 	  <para>Select the video mode(s) that you want to use.  You can select
 	    more than one option.  Typically, useful ranges are 640x480,
 	    800x600, and 1024x768 but those are a function of video card
 	    capability, monitor size, and eye comfort.</para>
 
 	  <para>Next, select the default color depth you want to use.  Your
 	    choices are 8bpp, 16bpp, 24bpp, and 32bpp.  Select the highest
 	    color depth that your video card will support.</para>
 
 	  <para>When finished, move on to the next item.</para>
 	</step>
 
 	<step>
 	  <title><guimenuitem>Other</guimenuitem></title>
 
 	  <para>The default settings are reasonable values, so you 
 	    probably will not need to change anything here.</para>
 
 	  <para>The default setting which allows the server to be killed
 	    with the hotkey sequence <keycombo action='simul'>
 	    <keycap>Ctrl</keycap><keycap>Alt</keycap>
 	    <keycap>Backspace</keycap></keycombo> should be left on.  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>Alt</keycap><keycap>+</keycap>
 	    </keycombo> or 
 	    <keycombo action='simul'>
 	      <keycap>Alt</keycap><keycap>-</keycap>
 	    </keycombo>.
 	    
 	  </para>
 	</step>
 
 	<step>
 	  <title>Testing the Server</title>
 
 	  <para>Verify all the settings once again and select
 	    <guibutton>Done</guibutton> and the following message will
 	    display:</para>
 
 	  <screen>If you've finished configuring everything press the
 Okay button to start the X server using the configuration
 you've selected.  If you still wish to configure some things,
 press one of the buttons at the top and then press "Done" again,
 when you've finished.</screen>
 
 	  <para>After selecting <guibutton>Okay</guibutton>, some messages
 	    will briefly appear advising to wait and attempting to start
 	    the X-server.  This process takes a few moments, so be
 	    patient.</para>
 
 	  <para>The screen will go blank for a short period of time and
 	    then a screen will appear with the message
 	    <quote>Congratulations, you've got a running server!</quote></para>
 
 	  <para>If nothing appears or the display is distorted, 
 	    kill the X-server using 
 	    <keycombo action='simul'>
 	      <keycap>Ctrl</keycap>
 	      <keycap>Alt</keycap>
 	      <keycap>Backspace</keycap>
 	    </keycombo>
 	    and adjust the settings or revisit them after installation.</para>
 	</step>
 
 	<step>
 	  <title>Running <command>xvidtune</command></title>
 
 	  <para>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-windows. There may be some display differences when switching
 	    back to text mode, but it is better than damaging equipment.
 	    <application>xvidtune</application> can be ran later using 
 	    <command>/stand/sysinstall</command>.</para>
 
 	  <para>Read the &man.xvidtune.1; man page before making
 	    any adjustments.</para>
 	</step>
 
 	<step>
 	  <title>Saving Configuration</title>
 
 	  <para>When you are satisfied, the configuration can now be saved.
 	    Select <guimenuitem>Save the configuration and Exit</guimenuitem>
 	    The configuration file will be saved to 
 	    <filename>/etc/XF86Config</filename>.</para> 
 	</step>
       </procedure>
 
       <para>Once the configuration is done, the installation program will
 	need to create a link to the server:</para>
 
       <screen>         Do you want to create an 'X' link to the SVGA server? 
 
                (the link will be created in the directory:
                         /usr/X11R6/bin) Okay?
 
                             [ Yes ]   No</screen>
 
       <para>Select <guibutton>[ Yes ]</guibutton> and press
 	<keycap>Enter</keycap> to create the link.</para>
 
       <screen>                        Link created successfully.
 
                                   [ OK ]</screen>
 
       <para>Press <keycap>Enter</keycap> to continue configuration.</para>
     </sect2>
 
     <sect2 id="default-desktop">
       <title>Select Default X Desktop</title>
 
       <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>The 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>/stand/sysinstall</command> 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 <guimenuitem>[ Yes ]</guimenuitem> 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>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>.
 	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 arrow keys to select <guibutton>[ Install ]</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.</para>
     </sect2>
 
     <sect2 id="addusers">
       <title>Add User/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 root.  The
 	root partition is generally small and running applications as
 	root 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 <guibutton>[ Yes ]</guibutton> and press
 	<keycap>Enter</keycap> to continue with adding a user.</para>
 
       <figure id="add-user2">
 	<title>Select Add User</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/adduser1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select <guimenuitem>Add 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). (<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.</para>
 
       <para>The user was also added to the group <groupname>wheel</groupname> to be able to
 	become a superuser with root 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 could also be added at this time if specific needs
 	are known. Otherwise, this may be accessed through using
 	<filename>/stand/sysinstall</filename> 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 <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 root 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.</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 to
 	do any other configurations, you can do it at this point or
 	after installation with <filename>/stand/sysinstall</filename>.</para>
 
       <screen>                     User Confirmation Requested
  Visit the general configuration menu for a chance to set any last
  options? 
 
                               Yes   [ No ]</screen>
 
       <para>Selecting <guibutton>[ No ]</guibutton> with the arrow keys
 	and pressing <keycap>Enter</keycap> returns 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 <guibutton>[ Yes ]</guibutton> and remove floppy if
 	booting from floppy. The CDROM drive is locked until the machine
 	starts to reboot. The CDROM drive is then unlocked and 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
 	(rpratt, in this example).  Avoid logging in as root except when
 	necessary.</para>
 
       <para>Typical boot messages:</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. 
 FreeBSD 4.5-RC2 #0: Thu Jan 17 21:24:52 GMT 2002
     murray@builder.freebsdmall.com:/usr/src/sys/compile/GENERIC
 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 initilization:. 
 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
 	root password.  This will work only if the user is a member of the
 	group wheel. Otherwise, login as root 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 <keycap>CTRL+ALT+DEL</keycap> key
         combination to reboot the system, however this is not recommended
         during normal operation.</para>
 
     </sect2>
   </sect1>
 
   <sect1>
     <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 sysinstall's documentation
       menu.  It lists, for a given architecture, what hardware devices
       are known to be supported by each release of FreeBSD.</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
           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>Change 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>MS-DOS User's Questions and Answers</title>
 
       <indexterm><primary>DOS</primary></indexterm>
       <para>Many users wish to install FreeBSD on PCs inhabited by MS-DOS.
         Here are some commonly asked questions about installing FreeBSD on
         such systems.</para>
 
       <qandaset>
         <qandaentry>
 	  <question>
 	    <para>Help, I have no space!  Do I need to delete everything 
 	      first?</para>
 	  </question>
 
 	  <answer>
 	    <para>If your machine is already running MS-DOS and has little
 	      or no free space available for the FreeBSD installation, all
 	      hope is not lost!  You may find the <application>FIPS</application>
 	      utility, provided
 	      in the <filename>tools</filename> directory on the FreeBSD
 	      CDROM or various FreeBSD FTP sites to be quite
 	      useful.</para>
 
 	    <indexterm>
         <primary><command>FIPS</command></primary>
       </indexterm>
 	    <para><application>FIPS</application> 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 defragment your MS-DOS partition using the Windows
 	      <application>DEFRAG</application> utility (go into Explorer,
 	      right-click on the
 	      hard drive, and choose to defrag your
 	      hard drive), or Norton Disk Tools. You then must run 
 	      <application>FIPS</application>.  It
 	      will prompt you for the rest of the information it needs.
 	      Afterwards, you can reboot and install FreeBSD on the new
 	      free slice.  See the <emphasis>Distributions</emphasis> menu
 	      for an estimate of how much free space you will need for the
 	      kind of installation you want.</para>
 
 	    <indexterm>
         <primary><application>Partition Magic</application></primary>
       </indexterm>
 	    <para>There is also a <emphasis>very</emphasis> useful
 	      product from <ulink
 	      url="http://www.powerquest.com/">PowerQuest</ulink>
 	      called <application>Partition Magic</application>. This
 	      application has far more functionality than 
 	      <application>FIPS</application>, and is
 	      highly recommended if you plan to often add/remove
 	      operating systems (like me). However, it does cost
 	      money, and if you plan to install FreeBSD once and then
 	      leave it there, <application>FIPS</application> will probably 
 	      be fine for you.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Can I use compressed MS-DOS filesystems from
 	      FreeBSD?</para>
 	  </question>
 
 	  <answer>
 	    <para>No.  If you are using a utility such as
 	      <trademark class="trade">Stacker</trademark> or
 	      <trademark class="trade">DoubleSpace</trademark>, FreeBSD
 	      will only be able to use whatever portion of the filesystem
 	      you leave uncompressed.  The rest of the filesystem will
 	      show up as one large file (the stacked/double spaced file!).
 	      <emphasis>Do not remove that file or you will probably regret
 	      it greatly!</emphasis></para>
 
 	    <para>It is probably better to create another uncompressed
 	      primary MS-DOS partition and use this for communications
 	      between MS-DOS and FreeBSD.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Can I mount my extended MS-DOS partition?</para>
 	  </question>
 
 	  <answer>
 	    <indexterm><primary>partitions</primary></indexterm>
 	    <indexterm><primary>slices</primary></indexterm>
 	    <para>Yes.  DOS extended partitions are mapped in at the end
 	      of the other <quote>slices</quote> in FreeBSD, e.g., your
 	      <devicename>D:</devicename> drive might be
 	      <filename>/dev/da0s5</filename>, your
 	      <devicename>E:</devicename> drive,
 	      <filename>/dev/da0s6</filename>, and so on.  This example
 	      assumes, of course, that your extended partition is on SCSI
 	      drive 0.  For IDE drives, substitute <filename>ad</filename>
 	      for <filename>da</filename> appropriately if installing
 	      4.0-RELEASE or later, and substitute
 	      <filename>wd</filename> for <filename>da</filename> if you
 	      are installing a version of FreeBSD prior to 4.0.  You otherwise
 	      mount extended partitions exactly like you would any other
 	      DOS drive, for example:</para>
 
 	    <screen>&prompt.root; <userinput>mount -t msdos /dev/ad0s5 /dos_d</userinput></screen>
 	  </answer>
 	</qandaentry>
       </qandaset>
     </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 these steps:</para>
 
       <procedure>
         <step>
           <title>Fetch the Right Boot Floppy Images</title>
 
           <para>First you will need to get the right disk images so
             that you can boot into the install program. The secret
             with using a serial console is that you tell the boot
             loader to send I/O through a serial port instead of
             displaying console output to the VGA device and trying to
             read input from a local keyboard.  Enough of that now,
             let's get back to getting these disk images.</para>
 
 	  <para>You will need to get <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/kern.flp">kern.flp</ulink> and
             <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/mfsroot.flp">
             mfsroot.flp</ulink> from the
             <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/">
             floppies directory</ulink>.</para>
 
         </step>
         <step>
 	  <title>Write the Image Files to the Floppy Disks.</title>
 
           <para>The image files, such as
 	    <filename>kern.flp</filename>, are
 	    <emphasis>not</emphasis> regular files that you copy to
 	    the disk.  Instead, they are images of the complete
 	    contents of the disk.</para>
 
 	  <para>This means that you can <emphasis>not</emphasis> use
 	    commands like DOS' <command>copy</command> to write the
 	    files.  Instead, you must use specific tools to write the
 	    images directly to the disk.</para>
 	  
 	  <indexterm>
       <primary><command>fdimage</command></primary>
     </indexterm>
 	  <para>If you are creating the floppies on a computer running
 	    DOS 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.  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>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>
 
 	  <step>
 	    <title>Enabling the Boot Floppies to Boot into a Serial
 	    Console</title>
 
             <warning>
               <para>Do not try to mount the floppy if it is write-protected</para>
             </warning>
 
   	    <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 floppy 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 null modem cable 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 be able to control the headless
         machine through your <command>cu</command> session now.  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. Just
         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.  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, FreeBSD does not recognize your CD/DVD
 	  drive, but 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-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.44MB or 1.2MB 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 &quot;Format&quot;.</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.44MB 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.2MB 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 5 of them will fit on a conventional
 	  1.44MB 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 <quote>Floppy</quote> 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 on that
 	  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>bin</emphasis> distribution can be 
 	found in the <ulink
 	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/bin/">&rel.current;/bin/</ulink> directory.</para>
     
 	<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 go to do the installation, you should also 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.  You
 	  should expect to require as much temporary storage as you have
 	  stuff written on tape.</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 you can do.
 	  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="../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 50kbytes/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 (see below), 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 a server
 	    somewhere 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 this option in the Options 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
 	    appropriate Options flag.</para>
 
 	  <para>In order for NFS installation to work, the server must
 	    support subdir mounts, e.g., if your FreeBSD 3.4 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>.  Other NFS
 	    servers may have different conventions.  If you are getting
 	    <quote>permission denied</quote> 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/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
index 0ba3207aba..e4450da3ad 100644
--- a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
@@ -1,978 +1,978 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="l10n">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Andrey A.</firstname>
 	<surname>Chernov</surname>
 	<contrib>Contributed by </contrib>
       </author>
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Michael C.</firstname>
 	<surname>Wu</surname>
 	<contrib>Rewritten by </contrib>
       </author>
       <!-- 30 Nv 2000 -->
     </authorgroup>
   </chapterinfo>
 
   <title>Localization - I18N/L10N Usage and Setup</title>
 
   <sect1>
     <title>Synopsis</title>
 
     <para>FreeBSD is a very distributed project with users and
       contributors located all over the world.  This chapter discusses
       the internationalization and localization features of FreeBSD
       that allow non-English speaking users to get real work done.
       There are many aspects of the i18n implementation in both the system
       and application levels, so where applicable we refer the reader
       to more specific sources of documentation.</para>
 
     <para>After reading this chapter, you will know:</para>
     <itemizedlist>
       <listitem><para>How different languages and locales are encoded
       on modern operating systems.</para></listitem>
       <listitem><para>How to set the locale for your login
       shell.</para></listitem>
       <listitem><para>How to configure your console for non-English
       languages.</para></listitem>
       <listitem><para>How to use X Windows effectively with different
       languages.</para></listitem>
       <listitem><para>Where to find more information about writing
       i18n-compliant applications.</para></listitem>
    </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem><para>Know how to install additional third-party
         applications (<xref linkend="ports">).</para></listitem>
     </itemizedlist>
   </sect1>
 
   <sect1>
     <title>The Basics</title>
 
     <sect2>
       <title>What is I18N/L10N?</title>
     <indexterm><primary>internationalization</primary></indexterm> 
     <indexterm><primary>localization</primary></indexterm> 
 
       <para>Developers shortened internationalization into the term I18N,
 	counting the number of letters between the first and the last
 	letters of internationalization.  L10N uses the same naming
 	scheme, coming from "localization".  Combined
 	together, I18N/L10N methods, protocols, and applications allow
 	users to use languages of their choice.</para>
 
       <para>I18N applications are programmed using I18N kits under
 	libraries.  It allows for developers to write a simple file and
 	translate displayed menus and texts to each language.  We strongly
 	encourage programmers to follow this convention.</para>
     </sect2>
 
     <sect2>
       <title>Why Should I Use I18N/L10N?</title>
 
       <para>I18N/L10N is used whenever you wish to either view, input, or
 	process data in non-English languages.</para>
     </sect2>
 
     <sect2>
       <title>What Languages Are Supported in the I18N Effort?</title>
 
       <para>I18N and L10N are not FreeBSD specific.  Currently, one can
 	choose from most of the major languages of the World, including
 	but not limited to:  Chinese, German, Japanese, Korean, French,
 	Russian, Vietnamese and others.</para>
     </sect2>
   </sect1>
 
   <sect1 id="using-localization">
     <title>Using Localization</title>
 
     <para>In all its splendor, I18N is not FreeBSD-specific and is a
       convention.  We encourage you to help FreeBSD in following this
       convention.</para>
     <indexterm><primary>locale</primary></indexterm>
 
     <para>Localization settings are based on three main terms:
       Language Code, Country Code, and Encoding.  Locale names are
       constructed from these parts as follows:</para>
 
     <programlisting><replaceable>LanguageCode</replaceable>_<replaceable>CountryCode</replaceable>.<replaceable>Encoding</replaceable></programlisting>
 
     <sect2>
       <title>Language and Country Codes</title>
       <indexterm><primary>language codes</primary></indexterm>
       <indexterm><primary>country codes</primary></indexterm>
 
       <para>In order to localize a FreeBSD system to a specific language
 	(or any other I18N-supporting Unixes), the user needs to find out
 	the codes for the specify country and language (country
 	codes tell applications what variation of given
 	language to use).  In addition, web
 	browsers, SMTP/POP servers, web servers, etc. make decisions based on
 	them.  The following are examples of language/country codes:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Language/Country Code</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>en_US</entry>
 	      <entry>English - United States</entry>
 	    </row>
 
 	    <row>
 	      <entry>ru_RU</entry>
 	      <entry>Russian for Russia</entry>
 	    </row>
 
 	    <row>
 	      <entry>zh_TW</entry>
 	      <entry>Traditional Chinese for Taiwan</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
     </sect2>
 
     <sect2>
       <title>Encodings</title>
       <indexterm><primary>encodings</primary></indexterm>
       <indexterm><primary>ASCII</primary></indexterm>
 
       <para>Some languages use non-ASCII encodings that are 8-bit, wide
 	or multibyte characters, see &man.multibyte.3; for more
 	details. Older applications do not recognize them
 	and mistake them for control characters.  Newer applications
 	usually do recognize 8-bit characters.  Depending on the
 	implementation, users may be required to compile an application
 	with wide or multibyte characters support, or configure it correctly.
 	To be able to input and process wide or multibyte characters, the <ulink 
 	url="../../../../ports/index.html">FreeBSD Ports collection</ulink> has provided
 	each language with different programs.  Refer to the I18N
 	documentation in the respective FreeBSD Port.</para>
 
       <para>Specifically, the user needs to look at the application
 	documentation to decide on how to configure it correctly or to
 	pass correct values into the configure/Makefile/compiler.</para>
 
       <para>Some things to keep in mind are:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Language specific single C chars character sets
 	  (see &man.multibyte.3;), i.e.,
 	    ISO-8859-1, ISO-8859-15, KOI8-R, CP437.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Wide or multibyte encodings, f.e. EUC, Big5.</para>
 	</listitem>
       </itemizedlist>
 
       <para>You can check the active list of character sets at the
 	<ulink
 	url="http://www.iana.org/assignments/character-sets">IANA Registry</ulink>.</para>
 
       <note>
       <para>FreeBSD versions 4.5 and up use X11-compatible locale
 	encodings instead.</para>
       </note>
 
     </sect2>
 
     <sect2>
       <title>I18N Applications</title>
 
       <para>In the FreeBSD Ports and Package system, I18N applications
 	have been named with <literal>I18N</literal> in their names for
 	easy identification.  However, they do not always support the
 	language needed.</para>
     </sect2>
 
     <sect2 id="setting-locale">
       <title>Setting Locale</title>
 
       <para>Theoretically, one only needs to export the value of his/her
 	locale name as <envar>LANG</envar> in the login shell and is
 	usually done through the user's
 	<filename>~/.login_conf</filename> or the user login shell
 	configuration (<filename>~/.profile</filename>,
 	<filename>~/.bashrc</filename>, <filename>~/.cshrc</filename>).
 	This should set all of the locale subsets (such as
 	<envar>LC_CTYPE</envar>, <envar>LC_CTIME</envar>, etc.).  Please
 	refer to language-specific FreeBSD documentation for more
 	information.</para>
 
       <para>You should set the following two values in your configuration
 	files:</para>
 
       <itemizedlist>
         <indexterm><primary>POSIX</primary></indexterm>
         <listitem>
 	  <para><envar>LANG</envar> for POSIX &man.setlocale.3; family
 	    functions</para>
 	</listitem>
 
         <indexterm><primary>MIME</primary></indexterm>
 	<listitem>
 	  <para><envar>MM_CHARSET</envar> for applications' MIME character
 	    set</para>
 	</listitem>
       </itemizedlist>
 
       <para>This includes the user shell config, the specific application
         config, and the X11 config.</para>
 
       <sect3>
 	<title>Setting Locale Methods</title>
         <indexterm><primary>locale</primary></indexterm>
         <indexterm><primary>login class</primary></indexterm>
 
 	<para>There are two methods for setting locale, and both are
 	  described below.  The first (recommended one) is by assigning
 	  the environment variables in <link linkend="login-class">login
 	  class</link>, and the second is by adding the environment
 	  variable assignments to the system's shell <link
 	  linkend="startup-file">startup file</link>.</para>
 
 	<sect4 id="login-class">
 	  <title>Login Classes Method</title>
 
 	  <para>This method allows environment variables needed for locale
 	    name and MIME character sets to be assigned once for every
 	    possible shell instead of adding specific shell assignments to
 	    each shell's startup file.  <link linkend="usr-setup">User
 	    Level Setup</link> can be done by an user himself and <link
 	    linkend="adm-setup">Administrator Level Setup</link> require
 	    superuser privileges.</para>
 
 	  <sect5 id="usr-setup">
 	    <title>User Level Setup</title>
 
 	    <para>Here is a minimal example of a
 	      <filename>.login_conf</filename> file in user's home
 	      directory which has both variables set for Latin-1
 	      encoding:</para>
 
 	    <programlisting>german:German User:\
 	:charset=ISO-8859-1:\
 	:lang=de_DE.ISO_8859-1:</programlisting>
 
 	    <note>
 	      <para><filename>de_DE.ISO8859-1</filename> for FreeBSD
 		      versions 4.5 and up.</para>
 	    </note>
 
 	    <indexterm><primary>Traditional Chinese / BIG-5 encoding</primary></indexterm>
 	    <para>Here is an example of a 
 	       <filename>.login_conf</filename> that sets the variables
 	       for Traditional Chinese in BIG-5 encoding.  Notice the many
 	       more variables set because some software does not respect
 	       locale variables correctly for Chinese, Japanese, and Korean.</para>
 
 	    <programlisting>#Users who do not wish to use monetary units or time formats
 #of Taiwan can manually change each variable
 taiwan:Taiwanese User:\
 	lang=zh_TW.Big5:\
 	lc_all=zh_TW.Big:\
 	lc_collate=zh_TW.Big5:\ 
 	lc_ctype=zh_TW.Big5:\
 	lc_messages=zh_TW.Big5:\
 	lc_monetary=zh_TW.Big5:\
 	lc_numeric=zh_TW.Big5:\
 	lc_time=zh_TW.Big5:\
 	charset=big5:\
 	xmodifiers="@im=xcin": #Setting the XIM Input Server</programlisting> 
 
 	    <para>See <link linkend="adm-setup">Administrator Level
 	      Setup</link> and &man.login.conf.5; for more details.</para>
 	  </sect5>
 
 	  <sect5 id="adm-setup">
 	    <title>Administrator Level Setup</title>
 
 	    <para>Check that <filename>/etc/login.conf</filename> have the
 	      correct language user's class.  Make sure these settings
 	      appear in <filename>/etc/login.conf</filename>:</para>
 
 	    <programlisting><replaceable>language_name</replaceable>:<replaceable>accounts_title</replaceable>:\
 	:charset=<replaceable>MIME_charset</replaceable>:\
 	:lang=<replaceable>locale_name</replaceable>:\
 	:tc=default:</programlisting>
 
 	    <para>So sticking with our previous example using Latin-1, it
 	      would look like this:</para>
 
 	    <programlisting>german:German Users Accounts:\
 	:charset=ISO-8859-1:\
 	:lang=de_DE.ISO_8859-1:\
 	:tc=default:</programlisting>
 
 	    <note>
 	      <para><filename>de_DE.ISO8859-1</filename> for FreeBSD
 		      versions 4.5 and up.</para>
 	    </note>
 
 	    <para>Changing Login Classes with &man.vipw.8;</para>
 
 	    <indexterm>
         <primary><command>vipw</command></primary>
       </indexterm>
 	    <para>Use <command>vipw</command> to add new users, and make
 	      the entry look like this:</para>
 
 	    <programlisting>user:password:1111:11:<replaceable>language</replaceable>:0:0:User Name:/home/user:/bin/sh</programlisting>
 
 	    <para>Changing Login Classes with &man.adduser.8;</para>
 
 	    <indexterm>
         <primary><command>adduser</command></primary>
       </indexterm>
 	    <indexterm><primary>login class</primary></indexterm>
 	    <para>Use <command>adduser</command> to add new users, and do
 	      the following:</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para>Set <literal>defaultclass =
 		  <replaceable>language</replaceable></literal> in
 		  <filename>/etc/adduser.conf</filename>.  Keep in mind
 		  you must enter a <literal>default</literal> class for
 		  all users of other languages in this case.</para>
 	      </listitem>
 
 	      <listitem>
 		<para>An alternative variant is answering the specified
 		  language each time that 
 <screen><prompt>Enter login class: default []: </prompt></screen>
 		  appears from &man.adduser.8;</para>
 	      </listitem>
 
 	      <listitem>
 		<para>Another alternative is to use the following for each
 		  user of a different language that you wish to
 		  add:</para>
 
 		<screen>&prompt.root; <userinput>adduser -class <replaceable>language</replaceable></userinput></screen>
 	      </listitem>
 	    </itemizedlist>
 
 	    <para>Changing Login Classes with &man.pw.8;</para>
 	    <indexterm>
         <primary><command>pw</command></primary>
       </indexterm>
 	    <para>If you use &man.pw.8; for adding new users, call it in
 	      this form:</para>
 
 	    <screen>&prompt.root; <userinput>pw useradd <replaceable>user_name</replaceable> -L <replaceable>language</replaceable></userinput></screen>
 	  </sect5>
 	</sect4>
 
 	<sect4 id="startup-file">
 	  <title>Shell Startup File Method</title>
 
 	  <note>
 	    <para>This method is not recommended because it requires a
 	      different setup for each possible login program chosen.  Use
 	      the <link linkend="login-class">Login Class Method</link>
 	      instead.</para>
 	  </note>
 
 	  <indexterm><primary>MIME</primary></indexterm>
 	  <indexterm><primary>locale</primary></indexterm>
 	  <para>To add the locale name and MIME character set, just set
 	    the two environment variables shown below in the
 	    <filename>/etc/profile</filename> and/or
 	    <filename>/etc/csh.login</filename> shell startup files.  We
 	    will use the German language as an example below:</para>
 
 	  <para>In <filename>/etc/profile</filename>:</para>
 
 	  <programlisting><envar>LANG=de_DE.ISO_8859-1; export LANG</envar>
 <envar>MM_CHARSET=ISO-8859-1; export MM_CHARSET</envar></programlisting>
 
 	  <para>Or in <filename>/etc/csh.login</filename>:</para>
 
 	  <programlisting><envar>setenv LANG de_DE.ISO_8859-1</envar>
 <envar>setenv MM_CHARSET ISO-8859-1</envar></programlisting>
 
 	  <note>
 	    <para><filename>de_DE.ISO8859-1</filename> for FreeBSD
 		    versions 4.5 and up.</para>
 	  </note>
 
 	  <para>Alternatively, you can add the above instructions to
 	    <filename>/usr/share/skel/dot.profile</filename> (similar to
 	    what was used in <filename>/etc/profile</filename> above), or
 	    <filename>/usr/share/skel/dot.login</filename> (similar to
 	    what was used in <filename>/etc/csh.login</filename>
 	    above).</para>
 
 	  <para>For X11:</para>
 
 	  <para>In <filename>$HOME/.xinitrc</filename>:</para>
 
 	  <programlisting><envar>LANG=de_DE.ISO_8859-1; export LANG</envar></programlisting>
 
 	  <para>Or:</para>
 
 	  <programlisting><envar>setenv LANG de_DE.ISO_8859-1</envar></programlisting>
 
 	  <para>Depending on your shell (see above).</para>
 
 	  <note>
 	    <para><filename>de_DE.ISO8859-1</filename> for FreeBSD
 		    versions 4.5 and up.</para>
 	  </note>
 	</sect4>
       </sect3>
     </sect2>
 
     <sect2 id="setting-console">
       <title>Console Setup</title>
 
       <para>For all single C chars character sets, set the correct
 	console fonts in <filename>/etc/rc.conf</filename> for the
 	language in question with:</para>
 
       <programlisting>font8x16=<replaceable>font_name</replaceable>
 font8x14=<replaceable>font_name</replaceable>
 font8x8=<replaceable>font_name</replaceable></programlisting>
 
       <para>The <replaceable>font_name</replaceable> here is taken from
         the <filename>/usr/share/syscons/fonts</filename> directory,
 	without the <filename>.fnt</filename> suffix.</para>
 
       <indexterm>
         <primary><application>sysinstall</application></primary>
       </indexterm>
       <indexterm><primary>keymap</primary></indexterm>
       <indexterm><primary>screenmap</primary></indexterm>
       <para>Also be sure to set the correct keymap and screenmap for your
 	single C chars character set through
 	<filename>/stand/sysinstall</filename>.
 	Once inside sysinstall, choose <literal>Configure</literal>, then
 	<literal>Console</literal>.  Alternatively, you can add the
 	following to <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>scrnmap=<replaceable>screenmap_name</replaceable>
 keymap=<replaceable>keymap_name</replaceable>
 keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting>
 	
       <para>The <replaceable>screenmap_name</replaceable> here is taken
         from the <filename>/usr/share/syscons/scrnmaps</filename>
 	directory, without the <filename>.scm</filename> suffix.  A
 	screenmap with a corresponding mapped font is usually needed as a
 	workaround for expanding bit 8 to bit 9 on a VGA adapter's font
 	character matrix in pseudographics area, i.e., to move letters out
 	of that area if screen font uses a bit 8 column.</para>
 
       <para>If you have the <application>moused daemon</application>
 	enabled by setting the following
 	in your <filename>/etc/rc.conf</filename>:</para>
 
 <programlisting>moused_enable="YES"</programlisting>
 
       <para>then examine the mouse cursor information in the next
 	paragraph.</para>
 
       <indexterm>
         <primary><application>moused</application></primary>
       </indexterm>
       <para>By default the mouse cursor of the syscons driver occupies the
 	0xd0-0xd3 range in the character set.  If your language uses this
 	range, you need to move the cursor's range outside of it.  To enable
 	the workaround for FreeBSD versions before 5.0, insert the following
 	line into your kernel config:</para>
 
       <programlisting>options		SC_MOUSE_CHAR=0x03</programlisting>
 
       <para>For the FreeBSD versions 4.4 and up insert the following line
 	into <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>mousechar_start=3</programlisting>
 
       <para>The <replaceable>keymap_name</replaceable> here is taken from
         the <filename>/usr/share/syscons/keymaps</filename> directory,
 	without the <filename>.kbd</filename> suffix.  If you're
-	uncertain which keymap to use, you use &man.kbdmap.1 to test
+	uncertain which keymap to use, you use &man.kbdmap.1; to test
 	keymaps without rebooting.</para>
 
       <para>The <literal>keychange</literal> is usually needed to program
         function keys to match the selected terminal type because
 	function key sequences cannot be defined in the key map.</para>
 
       <para>Also be sure to set the correct console terminal type in
         <filename>/etc/ttys</filename> for all <literal>ttyv*</literal>
 	entries.  Current pre-defined correspondences are:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Character Set</entry>
 	      <entry>Terminal Type</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>ISO-8859-1 or ISO-8859-15</entry>
 	      <entry><literal>cons25l1</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>ISO-8859-2</entry>
 	      <entry><literal>cons25l2</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>ISO-8859-7</entry>
 	      <entry><literal>cons25l7</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>KOI8-R</entry>
 	      <entry><literal>cons25r</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>KOI8-U</entry>
 	      <entry><literal>cons25u</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>CP437 (VGA default)</entry>
 	      <entry><literal>cons25</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>US-ASCII</entry>
 	      <entry><literal>cons25w</literal></entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>For wide or multibyte characters languages, use the correct
 	FreeBSD port in your
 	<filename>/usr/ports/<replaceable>language</replaceable></filename>
 	directory.  Some ports appear as console while the system sees it
 	as serial vtty's, hence you must reserve enough vtty's for both
 	X11 and the pseudo-serial console.  Here is a partial list of
 	applications for using other languages in console:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Language</entry>
 	      <entry>Location</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>Traditional Chinese (BIG-5)</entry>
 	      <entry><filename role="package">chinese/big5con</filename></entry>
 	    </row>
 
 	    <row>
 	      <entry>Japanese</entry>
 	      <entry><filename role="package">japanese/ja-kon2-*</filename> or
 	        <filename role="package">japanese/Mule_Wnn</filename></entry>
 	    </row>
 
 	    <row>
 	      <entry>Korean</entry>
 	      <entry><filename role="package">korean/ko-han</filename></entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
 
     <sect2>
       <title>X11 Setup</title>
 
       <para>Although X11 is not part of the FreeBSD Project, we have
 	included some information here for FreeBSD users.  For more
 	details, refer to the <ulink url="http://www.xfree86.org/">XFree86
 	web site</ulink> or whichever X11 Server you use.</para>
 
       <para>In <filename>~/.Xresources</filename>, you can additionally
 	tune application specific I18N settings (e.g., fonts, menus,
 	etc.).</para>
 
       <sect3>
 	<title>Displaying Fonts</title>
 	<indexterm><primary>X11 True Type font server</primary></indexterm>
 	<para>Install the X11 True Type-Common server (XTT-common) and
 	  install the language truetype fonts.  Setting the correct
 	  locale should allow you to view your selected language in menus
 	  and such.</para>
       </sect3>
 
       <sect3>
 	<title>Inputting Non-English Characters</title>
 	<indexterm><primary>X11 Input Method (XIM)</primary></indexterm>
 	<para>The X11 Input Method (XIM) Protocol is a new standard for
 	  all X11 clients.  All X11 applications should be written as XIM
 	  clients that take input from XIM Input servers.  There are
 	  several XIM servers available for different languages.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Printer Setup</title>
 
       <para>Some single C chars character sets are usually hardware
 	coded into printers. Wide or multibyte
 	character sets require special setup and we recommend using
 	<application>apsfilter</application>.  You may also convert the
 	document to PostScript or PDF formats using language specific
 	converters.</para>
     </sect2>
 
     <sect2>
       <title>Kernel and File Systems</title>
 
       <para>The FreeBSD FFS filesystem is 8-bit clean, so it can be used
 	with any single C chars character set (see &man.multibyte.3;),
 	but there is no character set
 	name stored in the filesystem; i.e., it is raw 8-bit and does not
 	know anything about encoding order.  Officially, FFS does not
 	support any form of wide or multibyte character sets yet.  However, some
 	wide or multibyte character sets have independent patches for FFS
 	enabling such support.  They are only temporary unportable
 	solutions or hacks and we have decided to not include them in the
 	source tree.  Refer to respective languages' web sites for more
 	informations and the patch files.</para>
 
       <indexterm><primary>DOS</primary></indexterm>
       <indexterm><primary>Unicode</primary></indexterm>
       <para>The FreeBSD MS-DOS filesystem has the configurable ability to
 	convert between MS-DOS, Unicode character sets and chosen
 	FreeBSD filesystem character sets.  See &man.mount.msdos.8; for
 	details.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Compiling I18N Programs</title>
 
     <para>Many FreeBSD Ports have been ported with I18N support.  Some
       of them are marked with -I18N in the port name.  These and many
       other programs have built in support for I18N and need no special
       consideration.</para>
 
     <indexterm>
       <primary><application>MySQL</application></primary>
     </indexterm>
     <para>However, some applications such as 
       <application>MySQL</application> need to be have the
       <filename>Makefile</filename> configured with the specific
       charset.  This is usually done in the
       <filename>Makefile</filename> or done by passing a value to
       configure in the source.</para>
   </sect1>
 
   <sect1 id="lang-setup">	
     <title>Localizing FreeBSD to Specific Languages</title>
 
     <sect2 id="ru-localize">
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Andrey A.</firstname>
 	    <surname>Chernov</surname>
 	    <contrib>Originally contributed by </contrib>
 	  </author>
 	</authorgroup>
       </sect2info>
       <title>Russian Language (KOI8-R encoding)</title>
       <indexterm><primary>Russian localization</primary></indexterm>
 
       <para>For more information about KOI8-R encoding, see the <ulink
 	url="http://koi8.pp.ru/">KOI8-R References
 	(Russian Net Character Set)</ulink>.</para>
 
       <sect3>
 	<title>Locale Setup</title>
 
 	<para>Put the following lines into your
 	  <filename>~/.login_conf</filename> file:</para>
 
 	<programlisting>me:My Account:\
 	:charset=KOI8-R:\
 	:lang=ru_RU.KOI8-R:</programlisting>
 
 	<para>See earlier in this chapter for examples of setting up the
 	  <link linkend="setting-locale">locale</link>.</para>
       </sect3>
 
       <sect3>
 	<title>Console Setup</title>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>For the FreeBSD versions before 5.0 add the following line
 	      to your kernel configuration file:</para>
 
 	    <programlisting>options		SC_MOUSE_CHAR=0x03</programlisting>
 
 	    <para>For the FreeBSD versions 4.4 and up insert the following
 	      line into <filename>/etc/rc.conf</filename>:</para>
 
 	    <programlisting>mousechar_start=3</programlisting>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use following settings in
 	      <filename>/etc/rc.conf</filename>:</para>
 
 	    <programlisting>keymap="ru.koi8-r"
 scrnmap="koi8-r2cp866"
 font8x16="cp866b-8x16"
 font8x14="cp866-8x14"
 font8x8="cp866-8x8"</programlisting>
 
 	  </listitem>
 
 	  <listitem>
 	    <para>For each <literal>ttyv*</literal> entry in
 	      <filename>/etc/ttys</filename>, use
 	      <literal>cons25r</literal> as the terminal type.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>See earlier in this chapter for examples of setting up the
 	  <link linkend="setting-console">console</link>.</para>
       </sect3>
 
       <sect3>
 	<title>Printer Setup</title>
 	<indexterm><primary>printers</primary></indexterm>
 	<para>Since most printers with Russian characters come with
 	  hardware code page CP866, a special output filter is needed for
 	  KOI8-R -&gt; CP866 conversion.  Such a filter is installed by
 	  default as <filename>/usr/libexec/lpr/ru/koi2alt</filename>.
 	  A Russian printer <filename>/etc/printcap</filename> entry
 	  should look like:</para>
 
 	<programlisting>lp|Russian local line printer:\
 	:sh:of=/usr/libexec/lpr/ru/koi2alt:\
 	:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:</programlisting>
 
 	<para>See &man.printcap.5; for a detailed description.</para>
       </sect3>
 
       <sect3>
 	<title>MS-DOS FS and Russian Filenames</title>
 
 	<para>The following example &man.fstab.5; entry enables support
 	  for Russian filenames in mounted MS-DOS filesystems:</para>
 
 	<programlisting>/dev/ad0s2      /dos/c  msdos   rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0</programlisting>
 
 	<para>See &man.mount.msdos.8; for a detailed description of the
 	  <option>-W</option> and <option>-L</option> options.</para>
       </sect3>
 
       <sect3>
 	<title>X11 Setup</title>
 
 	<orderedlist>
 	  <listitem>
 	    <para>Do <link linkend="setting-locale">non-X locale
 	      setup</link> first as described.</para>
 
 	    <note>
 	      <para><anchor id="russian-note">The Russian KOI8-R locale
 		may not work with old XFree86 releases (lower than 3.3).
 		The XFree86 port from
 		<filename role="package">x11/XFree86</filename> already is the
 		most recent XFree86 version, so it will work if you
 		install XFree86 from the port.  This should not be an
 		issue unless you are using an old version of
 		FreeBSD.</para>
 	    </note>
 	  </listitem>
 
 	  <listitem>
 	    <para>Go to the
 	      <filename role="package">russian/X.language</filename> directory
 	      and issue the following command:</para>
 
 	    <screen>&prompt.root; <userinput>make install</userinput></screen>
       
 	    <para>The above port installs the latest version of the KOI8-R
 	      fonts.  XFree86 3.3 already has some KOI8-R fonts, but these
 	      are scaled better.</para>
 
 	    <para>Check the <literal>"Files"</literal> section
 	      in your <filename>/etc/XF86Config</filename> file.
 	      The following
 	      lines must be added <emphasis>before</emphasis> any other
 	      <literal>FontPath</literal> entries:</para>
 
 	    <programlisting>FontPath   "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
 FontPath   "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
 FontPath   "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"</programlisting>
 
 	    <para>If you use a high resolution video mode, swap the 75 dpi
 	      and 100 dpi lines.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>To activate a Russian keyboard, add the following to the
 	      <literal>"Keyboard"</literal> section of your
 	      <filename>XF86Config</filename> file.</para>
 
 	    <para>For XFree86 v3.*:</para>
 
 	    <programlisting>XkbLayout  "ru"
 XkbOptions "grp:caps_toggle"</programlisting>
 
 	    <para>For XFree86 v4.*:</para>
 
 	    <programlisting>Option "XkbLayout"   "ru"
 Option "XkbOptions"  "grp:caps_toggle"</programlisting>
 
 	    <para>Also make sure that <literal>XkbDisable</literal> is
 	      turned off (commented out) there.</para>
 
 	    <para>The RUS/LAT switch will be <literal>CapsLock</literal>.
 	      The old <literal>CapsLock</literal> function is still
 	      available via <literal>Shift+CapsLock</literal> (in LAT mode
 	      only).</para>
 
 	    <para>If you have <quote>Windows</quote> keys on your keyboard,
 	      and notice that some non-alphabetical keys are mapped
 	      incorrectly in RUS mode, add the following line in your
 	      <filename>XF86Config</filename> file.</para>
 
 	    <para>For XFree86 v3.*:</para>
 
 	<programlisting>XkbVariant "winkeys"</programlisting>
 
 	    <para>For XFree86 v4.*:</para>
 
 	<programlisting>Option "XkbVariant" "winkeys"</programlisting>
 
 	    <note>
 	      <para>The Russian XKB keyboard may not work with old XFree86
 		versions, see the <link linkend="russian-note">above
 		note</link> for more information.  The Russian XKB
 		keyboard may also not work with non-localized
 		applications as well.  Minimally localized applications
 		should call a <literal>XtSetLanguageProc (NULL, NULL,
 		NULL);</literal> function early in the program.
 		See <ulink
 		url="http://koi8.pp.ru/xwin.html">
 		KOI8-R for X-Window</ulink> for more instructions on
 		localizing X11 applications.</para>
 	    </note>
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Traditional Chinese Localization for Taiwan</title>
       <indexterm><primary>Traditional Chinese localization</primary></indexterm>
       <para>The FreeBSD-Taiwan Project has an I18N/L10N tutorial for
 	FreeBSD at <ulink url="http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/">http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/</ulink>
 	using many <filename role="package">chinese/*</filename> applications.
 	The editor for the <literal>zh-L10N-tut</literal> is Clive Lin
 	<email>Clive@CirX.org</email>.  You can also cvsup the following
 	collections at <hostid
 	role="fqdn">freebsd.sinica.edu.tw</hostid>:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Collection</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>outta-port tag=.</entry>
 	      <entry>Beta-quality ports collection for Chinese</entry>
 	    </row>
 
 	    <row>
 	      <entry>zh-L10N-tut tag=.</entry>
 	      <entry>Localizing FreeBSD Tutorial in BIG-5 Traditional
 		Chinese</entry>
 	    </row>
 
 	    <row>
 	      <entry>zh-doc tag=.</entry>
 	      <entry>FreeBSD Documentation Translation to BIG-5 Traditional
 		Chinese</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>Chuan-Hsing Shen <email>s874070@mail.yzu.edu.tw</email> has
 	created the <ulink url="http://cnpa.yzu.edu.tw/~cfc/">Chinese
 	FreeBSD Collection (CFC)</ulink> using FreeBSD-Taiwan's
 	<literal>zh-L10N-tut</literal>.  The packages and the script files
 	are available at <ulink url="ftp://ftp.csie.ncu.edu.tw/OS/FreeBSD/taiwan/CFC/">ftp://ftp.csie.ncu.edu.tw/OS/FreeBSD/taiwan/CFC/</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>German Language Localization (For All ISO 8859-1
 	Languages)</title>
       <indexterm><primary>German localization</primary></indexterm>
 
       <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a
 	tutorial how to use umlauts on a FreeBSD machine.  The tutorial
 	is written in German and available at <ulink
 	url="http://www.de.FreeBSD.org/de/umlaute/">http://www.de.FreeBSD.org/de/umlaute/</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>Japanese and Korean Language Localization</title>
       <indexterm><primary>Japanese localization</primary></indexterm>
       <indexterm><primary>Korean localization</primary></indexterm>
       <para>For Japanese, refer to <ulink
 	url="http://www.jp.FreeBSD.org/">http://www.jp.FreeBSD.org/</ulink>,
 	and for Korean, refer to <ulink
 	url="http://www.kr.FreeBSD.org/">http://www.kr.FreeBSD.org/</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>Non-English FreeBSD Documentation</title>
 
       <para>Some FreeBSD contributors have translated parts of FreeBSD to
 	other languages.  They are available through links on the <ulink
 	url="../../../../index.html">main site</ulink> or in
 	<filename>/usr/share/doc</filename>.</para>
     </sect2>
   </sect1>
 </chapter>
diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
index 262b671845..c1b4d6e3c8 100644
--- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
@@ -1,2614 +1,2614 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="linuxemu">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured and parts updated by </contrib>
       </author>
       <!-- 22 Mar 2000 -->
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Brian N.</firstname>
 	<surname>Handy</surname>
 	<contrib>Originally contributed by </contrib>
       </author>
       <author>
 	<firstname>Rich</firstname>
 	<surname>Murphey</surname>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Linux Binary Compatibility</title>
 
   <sect1>
     <title>Synopsis</title>
     <indexterm><primary>Linux binary compatibility</primary></indexterm>
     <indexterm>
       <primary>binary compatibility</primary>
       <secondary>Linux</secondary>
     </indexterm>
 
     <para>FreeBSD provides binary compatibility with several other
       Unix-like operating systems, including Linux.  At this point,
       you may be asking yourself why exactly, does
       FreeBSD need to be able to run Linux binaries?  The answer to that
       question is quite simple.  Many companies and developers develop
       only for Linux, since it is the latest <quote>hot thing</quote> in
       the computing world.  That leaves the rest of us FreeBSD users
       bugging these same companies and developers to put out native
       FreeBSD versions of their applications.  The problem is, that most
       of these companies do not really realize how many people would use
       their product if there were FreeBSD versions too, and most continue
       to only develop for Linux.  So what is a FreeBSD user to do?  This
       is where the Linux binary compatibility of FreeBSD comes into
       play.</para>
 
     <para>In a nutshell, the compatibility allows FreeBSD users to run
       about 90% of all Linux applications without modification.  This
       includes applications such as <application>Star Office</application>, 
       the Linux version of <application>Netscape</application>, 
       <application>Adobe Acrobat</application>, 
       <application>RealPlayer</application>
       5 and 7, <application>VMWare</application>, 
       <application>Oracle</application>,
       <application>WordPerfect</application>, <application>Doom</application>, 
       <application>Quake</application>, and more.  It is also reported
       that in some situations, Linux binaries perform better on FreeBSD 
       than they do under Linux.</para>
     <indexterm>
       <primary>Linux</primary>
       <secondary><filename>/proc</filename> filesystem</secondary>
     </indexterm>
 
     <para>There are, however, some Linux-specific operating system
       features that are not supported under FreeBSD.  Linux binaries will
       not work on FreeBSD if they overly use the Linux
       <filename>/proc</filename> filesystem (which is different from
       FreeBSD's <filename>/proc</filename> filesystem), or i386-specific
       calls, such as enabling virtual 8086 mode.</para>
 
     <para>After reading this chapter, you will know:</para>
     <itemizedlist>
       <listitem><para>How to enable Linux binary compatibility on your
         system.</para></listitem>
       <listitem><para>How to install additional Linux shared
         libraries.</para></listitem>
       <listitem><para>How to install Linux applications on your
         FreeBSD system.</para></listitem>
       <listitem><para>The implementation details of Linux
         compatibility in FreeBSD.</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>
 
   </sect1>
 
   <sect1 id="linuxemu-lbc-install">
     <title>Installation</title>
 
     <indexterm><primary>KLD (kernel loadable object)</primary></indexterm>
 
     <para>Linux binary compatibility is not turned on by default.  The
       easiest way to enable this functionality is to load the
       <literal>linux</literal> KLD object (<quote>Kernel LoaDable
       object</quote>).  You can load this module by simply typing
       <command>linux</command> at the command prompt.</para>
 
     <para>If you would like Linux compatibility to always be enabled,
       then you should add the following line to
       <filename>/etc/rc.conf</filename>:</para>
 
     <programlisting>linux_enable=<quote>YES</quote></programlisting>
 
     <para>This, in turn, triggers the following action in
       <filename>/etc/rc.i386</filename>:</para>
 
     <programlisting># Start the Linux binary compatibility if requested.
 #
 case ${linux_enable} in
 [Yy][Ee][Ss])
 	echo -n ' linux';	linux &gt; /dev/null 2&gt;&amp;1
 	;;
 esac</programlisting>
 
     <para>The &man.kldstat.8; command can be used to verify that the
       KLD is loaded:</para>
 
     <screen>&prompt.user; <userinput>kldstat</userinput>
 Id Refs Address    Size     Name
  1    2 0xc0100000 16bdb8   kernel
  7    1 0xc24db000 d000     linux.ko</screen>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>LINUX</secondary>
     </indexterm>
 
     <para>If for some reason you do not want to or cannot load the KLD,
       then you may statically link Linux binary compatibility into the kernel
       by adding <literal>options LINUX</literal> to your kernel
       configuration file.  Then install your new kernel as described in
       <xref linkend="kernelconfig">.</para>
     
     <sect2>
       <title>Installing Linux Runtime Libraries</title>
       <indexterm>
         <primary>Linux</primary>
 	<secondary>installing Linux libraries</secondary>
       </indexterm>
 
       <para>This can be done one of two ways, either by using the
         <link linkend="linuxemu-libs-port">linux_base</link> port, or
         by installing them <link
         linkend="linuxemu-libs-manually">manually</link>.</para>
 
       <sect3 id="linuxemu-libs-port">
 	<title>Installing Using the linux_base Port</title>
 	<indexterm><primary>ports collection</primary></indexterm>
 
 	<para>This is by far the easiest method to use when installing the
 	  runtime libraries.  It is just like installing any other port
 	  from the <ulink url="file://localhost/usr/ports/">ports collection</ulink>.
 	  Simply do the following:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput>
 &prompt.root; <userinput>make install distclean</userinput></screen>
 
 	<para>You should now have working Linux binary compatibility.
 	  Some programs may complain about incorrect minor versions of the
 	  system libraries.  In general, however, this does not seem to be
 	  a problem.</para>
       </sect3>
 
       <sect3 id="linuxemu-libs-manually">
 	<title>Installing Libraries Manually</title>
 
 	<para>If you do not have the <quote>ports</quote> collection
 	  installed, you can install the libraries by hand instead.  You
 	  will need the Linux shared libraries that the program depends on
 	  and the runtime linker.  Also, you will need to create a
 	  <quote>shadow root</quote> directory,
 	  <filename>/compat/linux</filename>, for Linux libraries on your
 	  FreeBSD system.  Any shared libraries opened by Linux programs
 	  run under FreeBSD will look in this tree first.  So, if a Linux
 	  program loads, for example, <filename>/lib/libc.so</filename>,
 	  FreeBSD will first try to open
 	  <filename>/compat/linux/lib/libc.so</filename>, and if that does
 	  not exist, it will then try <filename>/lib/libc.so</filename>.
 	  Shared libraries should be installed in the shadow tree
 	  <filename>/compat/linux/lib</filename> rather than the paths
 	  that the Linux <command>ld.so</command> reports.</para>
 
 	<para>Generally, you will need to look for the shared libraries
 	  that Linux binaries depend on only the first few times that you
 	  install a Linux program on your FreeBSD system.  After a while,
 	  you will have a sufficient set of Linux shared libraries on your
 	  system to be able to run newly imported Linux binaries without
 	  any extra work.</para>
       </sect3>
 
       <sect3>
 	<title>How to Install Additional Shared Libraries</title>
 	<indexterm><primary>shared libraries</primary></indexterm>
 
 	<para>What if you install the <filename>linux_base</filename> port
 	  and your application still complains about missing shared
 	  libraries?  How do you know which shared libraries Linux
 	  binaries need, and where to get them?  Basically, there are 2
 	  possibilities (when following these instructions you will need
 	  to be root on your FreeBSD system).</para>
 
 	<para>If you have access to a Linux system, see what shared
 	  libraries the application needs, and copy them to your FreeBSD
 	  system.  Look at the following example:</para>
 	  
 	<informalexample>
 	  <para>Let us assume you used FTP to get the Linux binary of
 	    Doom, and put it on a Linux system you have access to.  You
 	    then can check which shared libraries it needs by running
 	    <command>ldd linuxdoom</command>, like so:</para>
 
 	  <screen>&prompt.user; <userinput>ldd linuxdoom</userinput>
 libXt.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libXt.so.3.1.0
 libX11.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libX11.so.3.1.0
 libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
 
 	  <indexterm><primary>symbolic links</primary></indexterm>
 	  <para>You would need to get all the files from the last column,
 	    and put them under <filename>/compat/linux</filename>, with
 	    the names in the first column as symbolic links pointing to
 	    them.  This means you eventually have these files on your
 	    FreeBSD system:</para>
 
 	  <screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0
 /compat/linux/usr/X11/lib/libXt.so.3 -&gt; libXt.so.3.1.0
 /compat/linux/usr/X11/lib/libX11.so.3.1.0
 /compat/linux/usr/X11/lib/libX11.so.3 -&gt; libX11.so.3.1.0
 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
 
 	  <blockquote>
 	    <note>
 	      <para>Note that if you already have a Linux shared library
 		with a matching major revision number to the first column
 		of the <command>ldd</command> output, you will not need to
 		copy the file named in the last column to your system, the
 		one you already have should work.  It is advisable to copy
 		the shared library anyway if it is a newer version,
 		though.  You can remove the old one, as long as you make
 		the symbolic link point to the new one.  So, if you have
 		these libraries on your system:</para>
 
 	      <screen>/compat/linux/lib/libc.so.4.6.27
 /compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.27</screen>
 
 	      <para>and you find a new binary that claims to require a
 		later version according to the output of
 		<command>ldd</command>:</para>
 
 	      <screen>libc.so.4 (DLL Jump 4.5pl26) -&gt; libc.so.4.6.29</screen>
 
 	      <para>If it is only one or two versions out of date in the
 		in the trailing digit then do not worry about copying
 		<filename>/lib/libc.so.4.6.29</filename> too, because the
 		program should work fine with the slightly older version.
 		However, if you like, you can decide to replace the
 		<filename>libc.so</filename> anyway, and that should leave
 		you with:</para>
 
 	      <screen>/compat/linux/lib/libc.so.4.6.29
 /compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
 	    </note>
 	  </blockquote>
 
 	  <blockquote>
 	    <note>
 	      <para>The symbolic link mechanism is
 		<emphasis>only</emphasis> needed for Linux binaries.  The
 		FreeBSD runtime linker takes care of looking for matching
 		major revision numbers itself and you do not need to worry
 		about it.</para>
 	    </note>
 	  </blockquote>
 	</informalexample>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Installing Linux ELF Binaries</title>
       <indexterm>
         <primary>Linux</primary>
 	<secondary>ELF binaries</secondary>
       </indexterm>
 
       <para>ELF binaries sometimes require an extra step of
 	<quote>branding</quote>.  If you attempt to run an unbranded ELF
 	binary, you will get an error message like the following:</para>
 
       <screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput>
 ELF binary type not known
 Abort</screen>
 
       <para>To help the FreeBSD kernel distinguish between a FreeBSD ELF
 	binary from a Linux binary, use the &man.brandelf.1;
 	utility.</para>
 
       <screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen>
 
       <indexterm><primary>GNU toolchain</primary></indexterm>
       <para>The GNU toolchain now places the appropriate branding
 	information into ELF binaries automatically, so you this step
 	should become increasingly more rare in the future.</para>
     </sect2>
 
     <sect2>
       <title>Configuring the Hostname Resolver</title>
 
       <para>If DNS does not work or you get this message:</para>
 
       <screen>resolv+: "bind" is an invalid keyword resolv+:
 "hosts" is an invalid keyword</screen>
 
       <para>You will need to configure a
 	<filename>/compat/linux/etc/host.conf</filename> file
 	containing:</para>
 
       <programlisting>order hosts, bind
 multi on</programlisting>
 	  
       <para>The order here specifies that <filename>/etc/hosts</filename>
 	is searched first and DNS is searched second.  When
 	<filename>/compat/linux/etc/host.conf</filename> is not
 	installed, Linux applications find FreeBSD's
 	<filename>/etc/host.conf</filename> and complain about the
 	incompatible FreeBSD syntax.  You should remove
 	<literal>bind</literal> if you have not configured a name server
 	using the <filename>/etc/resolv.conf</filename> file.</para>
     </sect2>
   </sect1>
 
   <sect1 id="linuxemu-mathematica">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Murray</firstname>
 	  <surname>Stokely</surname>
 	  <contrib>Updated for Mathematica 4.X by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Bojan</firstname>
 	  <surname>Bistrovic</surname>
 	  <contrib>Merged with work by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Installing Mathematica</title>
 
     <indexterm>
       <primary>applications</primary>
       <secondary><application>Mathematica</application></secondary>
     </indexterm>
 
     <para>This document describes the process of installing the Linux
       version of <application>Mathematica 4.X</application> onto
       a FreeBSD system.</para>
 
     <para>The Linux version of <application>Mathematica</application>
       runs perfectly under FreeBSD
       however the binaries shipped by Wolfram need to be branded so that
       FreeBSD knows to use the Linux ABI to execute them.</para>
 
     <para>The Linux version of <application>Mathematica</application>
       or <application>Mathematica for Students</application> can
       be ordered directly from Wolfram at <ulink
       url="http://www.wolfram.com/">http://www.wolfram.com/</ulink>.</para>
 
     <sect2>
       <title>Branding the Linux Binaries</title>
 
       <para>The Linux binaries are located in the <filename>Unix</filename>
 	directory of the <application>Mathematica</application> CDROM 
 	distributed by Wolfram.  You
 	need to copy this directory tree to your local hard drive so that
 	you can brand the Linux binaries with &man.brandelf.1; before
 	running the installer:</para>
 
       <screen>&prompt.root; <userinput>mount /cdrom</userinput>
 &prompt.root; <userinput>cp -rp /cdrom/Unix/ /localdir/</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm</userinput>
 &prompt.root; <userinput>cd /localdir/Installers/Linux/</userinput>
 &prompt.root; <userinput>./MathInstaller</userinput></screen>
 
        <para>Alternatively, you can simply set the default ELF brand
          to Linux for all unbranded binaries with the command:</para>
        <screen>&prompt.root; <userinput>sysctl -w kern.fallback_elf_brand=3</userinput></screen>
        <para>This will make FreeBSD assume that unbranded ELF binaries
          use the Linux ABI and so you should be able to run the
          installer straight from the CDROM.</para>
     </sect2>
 
     <sect2>
       <title>Obtaining Your Mathematica Password</title>
 
       <para>Before you can run <application>Mathematica</application>
 	you will have to obtain a
 	password from Wolfram that corresponds to your <quote>machine
 	ID</quote>.</para>
       <indexterm>
         <primary>Ethernet</primary>
         <secondary>MAC address</secondary>
       </indexterm>
 
       <para>Once you have installed the Linux compatibility runtime
 	libraries and unpacked <application>Mathematica</application>
 	you can obtain the
 	<quote>machine ID</quote> by running the program
 	<command>mathinfo</command> in the Install directory.  This
 	machine ID is based solely on the MAC address of your first
 	Ethernet card.</para>
 
       <screen>&prompt.root; <userinput>cd /localdir/Files/SystemFiles/Installation/Binaries/Linux</userinput>
 &prompt.root; <userinput>mathinfo</userinput>
 disco.example.com 7115-70839-20412</screen>
 
       <para>When you register with Wolfram, either by email, phone or fax,
 	you will give them the <quote>machine ID</quote> and they will
 	respond with a corresponding password consisting of groups of
 	numbers.  You can then enter this information when you attempt to
 	run <application>Mathematica</application> for the first time
 	exactly as you would for any other 
 	<application>Mathematica</application> platform.</para>
     </sect2>
 
     <sect2>
       <title>Running the Mathematica Frontend over a Network</title>
 
       <para><application>Mathematica</application> uses some special 
 	fonts to display characters not
 	present in any of the standard font sets (integrals, sums, Greek
 	letters, etc.).  The X protocol requires these fonts to be install
 	<emphasis>locally</emphasis>.  This means you will have to copy
 	these fonts from the CDROM or from a host with 
 	<application>Mathematica</application>
 	installed to your local machine.  These fonts are normally stored
 	in <filename>/cdrom/Unix/Files/SystemFiles/Fonts</filename> on the
 	CDROM, or
 	<filename>/usr/local/mathematica/SystemFiles/Fonts</filename> on
 	your hard drive.  The actual fonts are in the subdirectories
 	<filename>Type1</filename> and <filename>X</filename>.  There are
 	several ways to use them, as described below.</para>
 
       <para>The first way is to copy them into one of the existing font
 	directories in <filename>/usr/X11R6/lib/X11/fonts</filename>.
 	This will require editing the <filename>fonts.dir</filename> file,
 	adding the font names to it, and changing the number of fonts on
 	the first line.  Alternatively, you should also just be able to
 	run <command>mkfontdir</command> in the directory you have copied
 	them to.</para>
 
       <para>The second way to do this is to copy the directories to
 	<filename>/usr/X11R6/lib/X11/fonts</filename>:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts</userinput>
 &prompt.root; <userinput>mkdir X</userinput>
 &prompt.root; <userinput>mkdir MathType1</userinput>
 &prompt.root; <userinput>cd /cdrom/Unix/Files/SystemFiles/Fonts</userinput>
 &prompt.root; <userinput>cp X/* /usr/X11R6/lib/X11/fonts/X</userinput>
 &prompt.root; <userinput>cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1</userinput>
 &prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/X</userinput>
 &prompt.root; <userinput>mkfontdir</userinput>
 &prompt.root; <userinput>cd ../MathType1</userinput>
 &prompt.root; <userinput>mkfontdir</userinput</screen>
 
       <para>Now add the new font directories to your font path:</para>
 
       <screen>&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/X</userinput>
 &prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/MathType1</userinput>
 &prompt.root; <userinput>xset fp rehash</userinput></screen>
 
       <para>If you are using the XFree86 server, you can have these font
 	directories loaded automatically by adding them to your
 	<filename>XF86Config</filename> file.</para>
       <indexterm><primary>fonts</primary></indexterm>
 
       <para>If you <emphasis>do not</emphasis> already have a directory
 	called <filename>/usr/X11R6/lib/X11/fonts/Type1</filename>, you
 	can change the name of the <filename>MathType1</filename>
 	directory in the example above to
 	<filename>Type1</filename>.</para>
     </sect2>
   </sect1>
 
   <sect1 id="linuxemu-maple">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Aaron</firstname>
 	  <surname>Kaplan</surname>
 <!--	  <address><email>aaron@lo-res.org</email></address>-->
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Robert</firstname>
 	  <surname>Getschmann</surname>
 <!--	  <address><email>rob@getschmann.org</email></address>-->
 	  <contrib>Thanks to </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Installing Maple</title>
 
     <indexterm>
       <primary>applications</primary>
       <secondary><application>Maple</application></secondary>
     </indexterm>
 
     <para>Maple is a commercial mathematics program similar to
       Mathematica.  You must purchase this software from <ulink
       url="http://www.maplesoft.com/"></ulink> and then register there
       for a license file.  To install this software on FreeBSD, please
       follow these simple steps.</para>
 
       <procedure>
 	<step><para>Execute the <filename>INSTALL</filename> shell
 	  script from the product distribution.  Choose the
 	  <quote>RedHat</quote> option when prompted by the
 	  installation program.  A typical installation directory
 	  might be <filename
 	  class="directory">/usr/local/maple</filename></para></step>
 
         <step><para>If you have not done so, order a license for Maple
 	  from Maple Waterloo Software (http://register.maplesoft.com)
 	  and copy it to
 	  <filename>/usr/local/maple/license/license.dat</filename></step>
 
         <step><para>Install the <application>FLEXlm</application>
 	  license manager by running the
 	  <filename>INSTALL_LIC</filename> install shell script that
 	  comes with <application>Maple</application>.  Specify the
 	  primary hostname for your machine for the license
 	  server.</para>
 
         <step><para>Patch the
           <filename>usr/local/maple/bin/maple.system.type</filename>
           file with the following:</para>
 <programlisting>   ----- snip ------------------
 *** maple.system.type.orig      Sun Jul  8 16:35:33 2001
 --- maple.system.type   Sun Jul  8 16:35:51 2001
 ***************
 *** 72,77 ****
 --- 72,78 ----
           # the IBM RS/6000 AIX case
           MAPLE_BIN="bin.IBM_RISC_UNIX"
           ;;
 +     "FreeBSD"|\
       "Linux")
           # the Linux/x86 case
         # We have two Linux implementations, one for Red Hat and
    ----- snip end of patch -----</programlisting>
 
 	<para>Please note that after the "FreeBSD"|\ no other
 	  whitespace should be present.</para>
 
 	<para>This patch instructs <application>Maple</application> to
 	  recognize <quote>FreeBSD</quote> as a type of Linux system.
 	  The <filename>bin/maple</filename> shell script calls the
 	  <filename>bin/maple.system.type</filename> shell script
 	  which in turn calls uname -a to find out the operating
 	  system name. Depending on the OS name it will find out which
 	  binaries to use.</para></step>
 
       <step><para>Start the license server.</para>
 
 	<para>The following script, installed as
 	  <filename>/usr/local/etc/rc.d/lmgrd.sh</filename> is a
 	  convenient way to start up lmgrd:</para>
 
 	<programlisting>   ----- snip ------------
 
 #! /bin/sh
 PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin
 PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX
 export PATH
 
 LICENSE_FILE=/usr/local/maple/license/license.dat
 LOG=/var/log/lmgrd.log
 
 case "$1" in
 start)
 	lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2
 	echo -n " lmgrd"
 	;;
 stop)
 	lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2
 	;;
 *)
 	echo "Usage: `basename $0` {start|stop}" 1>&2
 	exit 64
 	;;
 esac
 
 exit 0
    ----- snip ------------</programlisting></step>
 
 
       <step><para>Test-start maple:</para>
 	<screen>&prompt.user; cd /usr/local/maple/bin
-&prompt.user ./xmaple</screen>
+&prompt.user; ./xmaple</screen>
 
 	<para>You should be up and running. Make sure to write
 	  Maplesoft to let them know you would like a native FreeBSD
 	  version!</para></step>
     </procedure>
 
     <sect2>
       <title>Common Pitfalls</title>
 
       <itemizedlist>
 	<listitem><para>The FLEXlm license manager can be a difficult
 	  tool to work with.  Additional documentation on the subject
 	  can be found at <ulink
 	  url="http://www.globetrotter.com/"></ulink>.</para></listitem>
 
 	<listitem><para><command>lmgrd</command> is known to be very picky
 	  about the license file and to core dump if there are any
 	  problems.  A correct license file should look like this:</para>
 
 <programlisting># =======================================================
 # License File for UNIX Installations ("Pointer File")
 # =======================================================
 SERVER chillig ANY
 #USE_SERVER
 VENDOR maplelmg
 
 FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \
          PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \
          ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \
          SN=XXXXXXXXX</programlisting>
  
 	  <note><para>Serial number and key 'X''ed out. "chillig" is a
 	    hostname.</para></note>
 
   	  <para>Editing the license file works as long as you do not
  	    touch the "FEATURE" line (which is protected by the
  	    license key).</para></listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="linuxemu-oracle">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Marcel</firstname>
 	  <surname>Moolenaar</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<!-- marcel@cup.hp.com -->
       </authorgroup>
     </sect1info>
     <title>Installing Oracle</title>
 
     <indexterm>
       <primary>applications</primary>
       <secondary><application>Oracle</application></secondary>
     </indexterm>
 
     <sect2>
       <title>Preface</title>
       <para>This document describes the process of installing Oracle 8.0.5 and
 	Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD
 	machine</para>
     </sect2>
     
     <sect2>
       <title>Installing the Linux Environment</title>
       
       <para>Make sure you have both <filename>linux_base</filename> and
 	<filename>linux_devtools</filename> from the ports collection
 	installed.  These ports are added to the collection after the release
 	of FreeBSD 3.2.  If you are using FreeBSD 3.2 or an older version for
 	that matter, update your ports collection.  You may want to consider
 	updating your FreeBSD version too.  If you run into difficulties with
 	<filename>linux_base-6.1</filename> or
 	<filename>linux_devtools-6.1</filename> you may have to use version
 	5.2 of these packages.</para>
 
       <para>If you want to run the intelligent agent, you will
 	also need to install the Red Hat Tcl package:
 	<filename>tcl-8.0.3-20.i386.rpm</filename>.  The general command
 	for installing packages with the official RPM port is:</para>
       
       <screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen>
 
       <para>Installation of the package should not generate any errors.</para>
     </sect2>
 
     <sect2>
       <title>Creating the Oracle Environment</title>
       
       <para>Before you can install Oracle, you need to set up a proper
 	environment.  This document only describes what to do
 	<emphasis>specially</emphasis> to run Oracle for Linux on FreeBSD, not
 	what has been described in the Oracle installation guide.</para>
 
       <sect3 id="linuxemu-kernel-tuning">
         <title>Kernel Tuning</title>
 	<indexterm><primary>kernel tuning</primary></indexterm>
 	
 	<para>As described in the Oracle installation guide, you need to set
 	  the maximum size of shared memory.  Do not use
 	  <literal>SHMMAX</literal> under FreeBSD. <literal>SHMMAX</literal>
 	  is merely calculated out of <literal>SHMMAXPGS</literal> and
 	  <literal>PGSIZE</literal>.  Therefore define
 	  <literal>SHMMAXPGS</literal>.  All other options can be used as
 	  described in the guide.  For example:</para>
 
 	<programlisting>options SHMMAXPGS=10000
 options SHMMNI=100
 options SHMSEG=10
 options SEMMNS=200
 options SEMMNI=70
 options SEMMSL=61</programlisting>
 	
         <para>Set these options to suit your intended use of Oracle.</para>
 
 	<para>Also, make sure you have the following options in your kernel
 	  config-file:</para>
 
 <programlisting>options SYSVSHM #SysV shared memory
 options SYSVSEM #SysV semaphores
 options SYSVMSG #SysV interprocess communication</programlisting>
       </sect3>
 
       <sect3 id="linuxemu-oracle-account">
 	
         <title>Oracle Account</title>
 
 	<para>Create an Oracle account just as you would create any other
 	  account. The  Oracle account is special only that you need to give
 	  it a Linux shell.  Add <literal>/compat/linux/bin/bash</literal> to
 	  <filename>/etc/shells</filename> and set the shell for the Oracle
 	  account to <filename>/compat/linux/bin/bash</filename>.</para>
       </sect3>
 
       <sect3 id="linuxemu-environment">
         <title>Environment</title>
 
 	<para>Besides the normal Oracle variables, such as
 	  <envar>ORACLE_HOME</envar> and <envar>ORACLE_SID</envar> you must
 	  set the following environment variables:</para>
 
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Variable</entry>
 
 		<entry>Value</entry>
 	      </row>
 	    </thead>
 	    <tbody>
 	      <row>
 		<entry><envar>LD_LIBRARY_PATH</envar></entry>
 
 		<entry><literal>$ORACLE_HOME/lib</literal></entry>
 	      </row>
 
 	      <row>
 		<entry><envar>CLASSPATH</envar></entry>
 
 		<entry><literal>$ORACLE_HOME/jdbc/lib/classes111.zip</literal></entry>
 	      </row>
 
 	      <row>
 		<entry><envar>PATH</envar></entry>
 
 		<entry><literal>/compat/linux/bin
 /compat/linux/sbin
 /compat/linux/usr/bin
 /compat/linux/usr/sbin
 /bin
 /sbin
 /usr/bin
 /usr/sbin
 /usr/local/bin
 $ORACLE_HOME/bin</literal></entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
         <para>It is advised to set all the environment variables in
 	  <filename>.profile</filename>.  A complete example is:</para>
 
 <programlisting>ORACLE_BASE=/oracle; export ORACLE_BASE
 ORACLE_HOME=/oracle; export ORACLE_HOME
 LD_LIBRARY_PATH=$ORACLE_HOME/lib
 export LD_LIBRARY_PATH
 ORACLE_SID=ORCL; export ORACLE_SID
 ORACLE_TERM=386x; export ORACLE_TERM
 CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
 export CLASSPATH
 PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin
 PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
 PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
 export PATH</programlisting>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Installing Oracle</title> 
       
       <para>Due to a slight inconsistency in the Linux emulator, you need to
 	create a directory named <filename>.oracle</filename> in
 	<filename>/var/tmp</filename> before you start the installer.  Either
 	make it world writable or let it be owner by the oracle user.  You
 	should be able to install Oracle without any problems.  If you have
 	problems, check your Oracle distribution and/or configuration first!
 	After you have installed Oracle, apply the patches described in the
 	next two subsections.</para>
 
       <para>A frequent problem is that the TCP protocol adapter is not
 	installed right. As a consequence, you cannot start any TCP listeners.
 	The following actions help solve this problem:</para>
 
       <screen>&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
 &prompt.root; <userinput>make -f ins_network.mk ntcontab.o</userinput>
 &prompt.root; <userinput>cd $ORACLE_HOME/lib</userinput>
 &prompt.root; <userinput>ar r libnetwork.a ntcontab.o</userinput>
 &prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
 &prompt.root; <userinput>make -f ins_network.mk install</userinput></screen>
 
       <para>Do not forget to run <filename>root.sh</filename> again!</para>
 
     <sect3 id="linuxemu-patch-root">
       <title>Patching root.sh</title>
     
 	<para>When installing Oracle, some actions, which need to be performed
 	  as <username>root</username>, are recorded in a shell script called
 	  <filename>root.sh</filename>.  <filename>root.sh</filename> is
 	  written in the <filename>orainst</filename> directory.  Apply the
 	  following patch to root.sh, to have it use to proper location of
 	  <command>chown</command> or alternatively run the script under a 
 	  Linux native shell.</para>
 
 	<programlisting>*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
 --- orainst/root.sh Mon Dec 28 15:58:53 1998
 ***************
 *** 31,37 ****
 # This is the default value for CHOWN
 # It will redefined later in this script for those ports
 # which have it conditionally defined in ss_install.h
 ! CHOWN=/bin/chown
 #
 # Define variables to be used in this script
 --- 31,37 ----
 # This is the default value for CHOWN
 # It will redefined later in this script for those ports
 # which have it conditionally defined in ss_install.h
 ! CHOWN=/usr/sbin/chown
 #
 # Define variables to be used in this script</programlisting>
 
 	<para>When you do not install Oracle from CD, you can patch the source
 	  for <filename>root.sh</filename>.  It is called
 	  <filename>rthd.sh</filename> and is located in the
 	  <filename>orainst</filename> directory in the source tree.</para>
       </sect3>
 
       <sect3 id="linuxemu-patch-tcl">
 	<title>Patching genclntsh</title>
 	
 	<para>The script <command>genclntsh</command> is used to create 
 	  a single shared client
 	  library.  It is used when building the demos.  Apply the following
 	  patch to comment out the definition of PATH:</para>
 
 	<programlisting>*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
 --- bin/genclntsh Tue Dec 22 15:36:49 1998
 ***************
 *** 32,38 ****
 #
 # Explicit path to ensure that we're using the correct commands
 #PATH=/usr/bin:/usr/ccs/bin export PATH
 ! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
 #
 # each product MUST provide a $PRODUCT/admin/shrept.lst
 --- 32,38 ----
 #
 # Explicit path to ensure that we're using the correct commands
 #PATH=/usr/bin:/usr/ccs/bin export PATH
 ! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
 #
 # each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Running Oracle</title>
       
       <para>When you have followed the instructions, you should be able to run
 	<application>Oracle</application> as if it was run on Linux 
 	itself.</para>
     </sect2>
   </sect1>
   
 
 
 
 
   <sect1 id="sapr3">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Holger</firstname>
 	  <surname>Kipp</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
       <!-- holger.kipp@alogis.com -->
       <authorgroup>
 	<author>
 	  <firstname>Valentino</firstname>
 	  <surname>Vaschetto</surname>
 	  <contrib>Converted to SGML by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title>Installing SAP R/3 (4.6B - IDES)</title>
 
     <indexterm>
       <primary>applications</primary>
       <secondary><application>SAP R/3</application></secondary>
     </indexterm>
 
     <para>Installations of SAP Systems using FreeBSD will not be
       supported by the SAP support team &mdash; they only offer support
       for certified platforms.</para>
 
     <sect2 id="preface">
       <title>Preface</title>
 
       <para>This document describes a possible way of installing a 
 	<application>SAP R/3 4.6B IDES-System</application>
 	with <application>Oracle 8.0.5</application>
 	for Linux onto a FreeBSD 4.3 machine, including the installation
 	of FreeBSD 4.3-STABLE and 
 	<application>Oracle 8.0.5</application>.</para>
 
       <para>Even though this document tries to describe all important
         steps in a greater detail, it is not intended as a replacement
         for the <application>Oracle</application> and 
 	<application>SAP R/3</application> installation guides.</para>
 
       <para>Please see the documentation that comes with the 
 	<application>SAP R/3</application>
         Linux edition for <application>SAP-</application> and 
 	<application>Oracle</application>-specific questions, as well
         as resources from <application>Oracle</application> and 
 	<application>SAP OSS</application>.</para>
     </sect2>
 
     <sect2 id="software">
       <title>Software</title>
 
       <para>The following CDROMs have been used for
         SAP-installation:</para>
       <informaltable>
         <tgroup cols=3>
         <thead>
         <row>
           <entry>Name</entry> <entry>Number</entry> <entry>Description</entry>
         </row>
         </thead>
         <tbody>
         <row>
           <entry>KERNEL</entry> <entry>51009113</entry> <entry>SAP Kernel Oracle /
           Installation / AIX, Linux, Solaris</entry>
         </row>
         <row>
           <entry>RDBMS</entry> <entry>51007558</entry> <entry>Oracle / RDBMS 8.0.5.X /
           Linux</entry>
         </row>
         <row>
           <entry>EXPORT1</entry> <entry>51010208</entry> <entry>IDES / DB-Export / Disc
           1 of 6</entry>
         </row>
         <row>
           <entry>EXPORT2</entry> <entry>51010209</entry> <entry>IDES / DB-Export / Disc
           2 of 6</entry>
         </row>
         <row>
           <entry>EXPORT3</entry> <entry>51010210</entry> <entry>IDES / DB-Export /
           Disc3 of 6</entry>
         </row>
         <row>
           <entry>EXPORT4</entry> <entry>51010211</entry> <entry>IDES / DB-Export /
           Disc4 of 6</entry>
         </row>
         <row>
           <entry>EXPORT5</entry> <entry>51010212</entry> <entry>IDES / DB-Export /
           Disc5 of 6</entry>
         </row>
         <row>
           <entry>EXPORT6</entry> <entry>51010213</entry> <entry>IDES / DB-Export /
           Disc6 of 6</entry>
         </row>
         </tbody>
         </tgroup>
       </informaltable>
 
       <para>Additionally, I used the <application>Oracle 8
         Server</application> (Pre-production version 8.0.5 for Linux,
         Kernel Version 2.0.33) CD which is not really necessary, and
         of course FreeBSD 4.3 stable (it was only a few days past 4.3
         RELEASE).</para>
     </sect2>
 
     <sect2 id="sap-notes">
       <title>SAP-Notes</title>
 
       <para>The following notes should be read before installing
         <application>SAP R/3</application> or proved to be useful
         during installation:</para>
 
       <informaltable>
         <tgroup cols="2">
         <thead>
         <row>
           <entry>Number</entry>
           <entry>Title</entry>
         </row>
         </thead>
         <tbody>
         <row>
           <entry>0171356</entry> <entry>SAP Software auf Linux: grundlegenden
           Anmerkungen</entry>
         </row>
         <row>
           <entry>0201147</entry> <entry>INST: 4.6C R/3 Inst. on UNIX -
           Oracle</entry>
         </row>
         <row>
           <entry>0373203</entry> <entry>Update / Migration Oracle 8.0.5 -->
           8.0.6/8.1.6 LINUX</entry>
         </row>
         <row>
           <entry>0072984</entry> <entry>Release of Digital UNIX 4.0B for
           Oracle</entry>
         </row>
         <row>
           <entry>0130581</entry> <entry>R3SETUP step DIPGNTAB terminates</entry>
         </row>
         <row>
           <entry>0144978</entry> <entry>Your system has not been installed
           correctly</entry>
         </row>
         <row>
           <entry>0162266</entry> <entry>Questions and tips for R3SETUP on Windows
           NT / W2K</entry>
         </row>
         </tbody>
         </tgroup>
       </informaltable>
 
     </sect2>
 
     <sect2 id="hardware-requirements">
       <title>Hardware-Requirements</title>
 
       <para>The following equipment is sufficient for a
         <application>SAP R/3 System</application> (4.6B):</para>
 
       <informaltable>
         <tgroup cols="3">
         <thead>
         <row>
           <entry>Component</entry>
           <entry>4.6B</entry>
           <entry>4.6C</entry>
         </row>
         </thead>
         <tbody>
         <row>
           <entry>Processor</entry>
           <entry>2 x 800MHz Pentium III</entry>
           <entry>2 x 800MHz Pentium III</entry>
         </row>
         <row>
           <entry>Memory</entry>
           <entry>1GB ECC</entry>
           <entry>2GB ECC</entry>
         </row>
         <row>
           <entry>Hard Disc Space</entry>
           <entry>50-60GB (IDES)</entry>
           <entry>50-60GB (IDES)</entry>
         </row>
         </tbody>
 	</tgroup>
       </informaltable>
 
       <para>For use in production, Xeon-Processors with large cache,
         high-speed disc access (SCSI, RAID hardware controller), USV
         and ECC-RAM is recommended.  The large amount of Hard disc
         space is due to the preconfigured IDES System, which creates
         27 GB of database files during installation.  Usually after
         installation it is then necessary to extend some
         tablespaces.</para>
 
       <para>I used a dual processor board with 2 800MHz Pentium III
         processors, Adaptec 29160 Ultra160 SCSI adapter (for accessing
         a 40/80 GB DLT tape drive and CDROM), Mylex AcelleRAID (2
         channels, firmware 6.00-1-00 with 32MB RAM).  To the Mylex
         Raid-controller are attached two 17GB hard discs (mirrored)
         and four 36GB hard discs (RAID level 5).</para>
 
     </sect2>
 
     <sect2 id="installation">
       <title>Installation of FreeBSD 4.3-STABLE</title>
 
       <para>First I installed FreeBSD 4.3 stable. I did the
         default-installation via FTP.</para>
 
       <sect3 id="install-via-ftp">
         <title>Installation via FTP</title> <para>Get the diskimages
         kern.flp and mfsroot.flp and put them on floppy disks (I got
         mine from ftp7.de.FreeBSD.org. Please choose the appropriate
         mirror).</para>
 
         <screen>&prompt.root; <userinput>dd if=kern.flp of=/dev/fd0</userinput> 
 &prompt.root; <userinput>dd if=mfsroot.flp of=/dev/fd0</userinput> </screen>
 
         <para>Do not forget to use different disks for the two images,
           then boot from the floppy with the kern.flp-image on it
           and follow instructions.  I used the following disk
           layout:</para>
 
         <informaltable>
           <tgroup cols="4">
           <thead>
           <row>
             <entry>Filesystem</entry>
             <entry>Size (1k-blocks)</entry>
             <entry>Size (GB)</entry>
             <entry>Mounted on</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>/dev/da0s1a</entry>
             <entry>1.016.303</entry>
             <entry>1</entry>
             <entry>/</entry>
           </row>
           <row>
             <entry>/dev/da0s1b</entry>
             <entry> </entry>
             <entry>6</entry>
             <entry>&lt;swap&gt;</entry>
           </row>
           <row>
             <entry>/dev/da0s1e</entry>
             <entry>2.032.623</entry>
             <entry>2</entry>
             <entry>/var</entry>
           </row>
           <row>
             <entry>/dev/da0s1f</entry>
             <entry>8.205.339</entry>
             <entry>8</entry>
             <entry>/usr</entry>
           </row>
           <row>
             <entry>/dev/da1s1e</entry>
             <entry>45.734.361</entry>
             <entry>45</entry>
             <entry>/compat/linux/oracle</entry>
           </row>
           <row>
             <entry>/dev/da1s1f</entry>
             <entry>2.032.623</entry>
             <entry>2</entry>
             <entry>/compat/linux/sapmnt</entry>
           </row>
           <row>
             <entry>/dev/da1s1g</entry>
             <entry>2.032.623</entry>
             <entry>2</entry>
             <entry>/compat/linux/usr/sap</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>I had to configure and initialize the two logical drives
           with the Mylex software beforehand. It is located on the
           board itself and can be started during the boot phase of the
           PC.</para>
   
         <para> Please note that this disk layout differs slightly from
           the SAP recommendations, as SAP suggests mounting the
           oracle-subdirectories (and some others) separately - I
           decided to just create them as real subdirectories for
           simplicity.</para>
 
       </sect3>
 
       <sect3 id="getlatestsources">
         <title>Get the Latest STABLE Sources</title>
 
         <para>For FreeBSD 4.3 stable onwards, it is quite easy to get
           the latest stable sources. With the older versions of
           FreeBSD, I had my own script located in /etc/cvsup. Setting
           up <application>CVSup</application> for FreeBSD 4.3 is quite
 	  easy. As user
           <username>root</username> do the following:</para>
 
         <screen>&prompt.root; <userinput>cp /etc/defaults/make.conf /etc/make.conf</userinput>
 &prompt.root; <userinput>vi /etc/make.conf</userinput> </screen>
 
         <para>The file <filename>/etc/make.conf</filename> requires the
         following entries to be active:</para>
 
         <programlisting>SUP_UPDATE=    yes
 SUP=           /usr/local/bin/cvsup
 SUPFLAGS=      -g -L 2
 SUPHOST=       cvsup8.FreeBSD.org
 SUPFILE=       /usr/share/examples/cvsup/stable-supfile 
 PORTSSUPFILE=  /usr/share/examples/cvsup/ports-supfile 
 DOCSUPFILE=    /usr/share/examples/cvsup/doc-supfile</programlisting>
 
         <para>Change the <emphasis>SUPHOST</emphasis>-value
           appropriately.  The supfiles in
           <filename>/usr/share/examples/cvsup</filename> should be
           fine. If you do not want to load all the docfiles, leave the
           corresponding <emphasis>DOCSUPFILE</emphasis>-entry
           inactive.  Starting <application>cvsup</application>
 	  to get the latest stable-sources is then very easy:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make update</userinput> </screen>
 
       </sect3>
 
 
       <sect3 id="makeworldandnewkernel">
         <title><command>make world</command> and a New Kernel</title>
 
         <para>The first thing to do is to install the sources.
           As user root, do the following:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make world</userinput> </screen>
 
         <para>If this goes through, one can then continue creating and
           configuring the new kernel. Usually this is where to
           customize the kernel configuration file.  As the computer is
           named <hostid>troubadix</hostid>, the natural name for the 
 	  config file also is <filename>troubadix</filename>:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
 &prompt.root; <userinput>cp GENERIC TROUBADIX</userinput>
 &prompt.root; <userinput>vi TROUBADIX</userinput> </screen>
 
         <para>At this stage one can define the drivers to use and not
           to use, etc.  See the appropriate documentation or have a
           look at file <filename>LINT</filename> for some additional
           explanations.</para>
 
         <para>One can then also include the parameters as described
           below Creating the new kernel then requires:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
 &prompt.root; <userinput>config TROUBADIX</userinput>
 &prompt.root; <userinput>cd /usr/src/sys/compile/TROUBADIX</userinput>
 &prompt.root; <userinput>make depend</userinput>
 &prompt.root; <userinput>make</userinput>
 &prompt.root; <userinput>make install</userinput> </screen>
 
 
         <para>After <command>make install</command> finished
           successfully, one should reboot the computer to have the new
           kernel available.</para>
 
       </sect3>
     </sect2>
 
     <sect2 id="installingthelinuxenviornment">
       <title>Installing the Linux Environment</title>
 
       <para>I had some trouble downloading the required RPM-files (for
         4.3 stable, 2nd May 2001), so you might try one of the
         following locations (if all the others fail and the following
         are not out of date):</para>
 
       <itemizedlist>
         <listitem><para>ftp7.de.FreeBSD.org/pub/FreeBSD/distfiles/rpm</para></listitem>
         <listitem><para>ftp.redhat.com/pub/redhat/linux/6.1/en/os/i386/RedHat/RPMS</para></listitem>
       </itemizedlist>
 
       <sect3 id="installinglinuxbase-system">
         <title>Installing Linux Base-system</title>
         <para>First the Linux base-system needs to be installed (as root):
         <screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput>
 &prompt.root; <userinput>make package</userinput> </screen></para>
       </sect3>
 
 
       <sect3 id="installinglinuxdevelopment">
         <title>Installing Linux Development</title>
 
         <para>Next, the Linux development is needed:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/devel/linux_devtools</userinput>
 &prompt.root; <userinput>make package</userinput> </screen>
 
       </sect3>
 
 
       <sect3 id="installingnecessaryrpms">
         <title>Installing Necessary RPMs</title>
 	<indexterm><primary>RPMs</primary></indexterm>
 
         <para>To start the R3SETUP-Program, pam support is needed.  As
           this also requires some other packages, I ended up
           installing several packages. After that, pam still
           complained about a missing package, so I forced the
           installation and it worked. I wonder if the other packages
           are really needed or if it would have been sufficient to
           install the pam-package.</para>
 
         <para>Anyway, here is the list of packages I installed:</para>
 
         <itemizedlist>
           <listitem><para>cracklib-2.7-5.i386.rpm</para></listitem>
           <listitem><para>cracklib-dicts-2.7-5.i386.rpm</para></listitem>
           <listitem><para>pwdb-0.60-1.i386.rpm</para></listitem>
           <listitem><para>pam-0.68-7.i386.rpm</para></listitem>
         </itemizedlist>
 
         <para>I installed these packages with the following
           command:</para>
 
         <screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm &lt;package_name&gt;</userinput> </screen>
 
         <para>except for the pam package, which I forced with</para>
 
         <screen>&prompt.root; <userinput>rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm \
      pam-0.68-7.i386.rpm</userinput> </screen>
 
         <para>For <application>Oracle</application> to run the
           intelligent agent, I also had to install the following
           RedHat Tcl package (as is stated in the FreeBSD Handbook):
           <filename>tcl-8.0.5-30.i386.rpm</filename> (otherwise the
           relinking during <application>Oracle</application> install
           will not work).  There are some other issues regarding
           relinking of <application>Oracle</application>, but that is
           a Oracle-Linux issue, not FreeBSD specific as far as I
           understand it.</para>
 
       </sect3>
     </sect2>
 
     <sect2 id="creatingsapr3env">
       <title>Creating the SAP/R3 Environment</title>
 
       <sect3 id="filesystemsandmountpoints">
         <title>Creating the Necessary Filesystems and Mountpoints</title>
 
         <para>For a simple installation, it is sufficient to create the
           following filesystems:</para>
 
         <informaltable>
           <tgroup cols="2">
           <thead>
           <row>
             <entry>mountpoint</entry>
             <entry>size in GB</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>/compat/linux/oracle</entry>
             <entry>45 GB</entry>
           </row>
           <row>
             <entry>/compat/linux/sapmnt</entry>
             <entry>2 GB</entry>
           </row>
           <row>
             <entry>/compat/linux/usr/sap</entry>
             <entry>2 GB</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>I also created some links, so FreeBSD will also find the
           correct path:</para>
 
         <screen>&prompt.root; <userinput>ln -s /compat/linux/oracle /oracle</userinput>
 &prompt.root; <userinput>ln -s /compat/linux/sapmnt /sapmnt</userinput>
 &prompt.root; <userinput>ln -s /compat/linux/usr/sap /usr/sap</userinput> </screen>
       </sect3>
 
       <sect3 id="creatingusersanddirectories">
         <title>Creating Users and Directories</title>
 
         <para><application>SAP R/3</application> needs two users and
 	  three groups. The usernames depend on the
 	  <application>SAP</application> system id (SID) which consists
 	  of three letters. Some of these SIDs are reserved
 	  by <application>SAP</application> (for example
 	  <emphasis>SAP</emphasis> and <emphasis>NIX</emphasis>. For a
 	  complete list please see the SAP documentation).  For the IDES
 	  installation I used <emphasis>IDS</emphasis>.  We have
 	  therefore the following groups (group ids might differ, these
 	  are just the values I used with my installation):</para>
 
         <informaltable>
           <tgroup cols="3">
           <thead>
           <row>
             <entry>group id</entry>
             <entry>group name</entry>
             <entry>description</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>100</entry>
             <entry>dba</entry>
             <entry>Data Base Administrator</entry>
           </row>
           <row>
             <entry>101</entry>
             <entry>sapsys</entry>
             <entry>SAP System</entry>
           </row>
           <row>
             <entry>102</entry>
             <entry>oper</entry>
             <entry>Data Base Operator</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>For a default Oracle-Installation, only group
           <groupname>dba</groupname> is used. As
           <groupname>oper</groupname>-group, one also uses group
           <groupname>dba</groupname> (see Oracle- and
           SAP-documentation for further information).</para>
 
         <para>We also need the following users:</para>
 
         <informaltable>
           <tgroup cols="6">
           <thead>
           <row>
             <entry>user id</entry>
             <entry>username</entry>
             <entry>generic name</entry>
             <entry>group</entry>
             <entry>additional groups</entry>
             <entry>description</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>1000</entry>
             <entry>idsadm</entry>
             <entry>&lt;sid&gt;adm</entry>
             <entry>sapsys</entry>
             <entry>oper</entry>
             <entry>SAP Administrator</entry>
           </row>
           <row>
             <entry>1002</entry>
             <entry>oraids</entry>
             <entry>ora&lt;sid&gt;</entry>
             <entry>dba</entry>
             <entry>oper</entry>
             <entry>DB Administrator</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>Adding the users with <command>adduser</command>
           requires the following (please note shell and home
           directory) entries for SAP-Administrator:</para>
 
         <programlisting>Name: idsadm            &lt;sid&gt;adm
 Password: ******
 Fullname: SAP IDES Administrator
 Uid: 1000
 Gid: 101 (sapsys)
 Class:
 Groups: sapsys dba
 HOME: /home/idsadm      /home/&lt;sid&gt;adm
 Shell: /bin/sh</programlisting>
 
         <para>and for Database-Administrator:</para>
 
         <programlisting>Name: oraids          ora&lt;sid&gt; 
 Password: ****** 
 Fullname: Oracle IDES Administrator 
 Uid: 1002 
 Gid: 100 (dba) 
 Class: 
 Groups: dba 
 HOME: /oracle/IDS     /oracle/&lt;sid&gt; 
 Shell: /bin/sh</programlisting>
 
         <para>This should also include group
           <groupname>oper</groupname> in case you are using both
           groups <groupname>dba</groupname> and
           <groupname>oper</groupname>.</para>
 
       </sect3>
 
       <sect3 id="creatingdirectories">
         <title>Creating Directories</title>
 
         <para>These directories are usually created as separate
           filesystems.  This depends entirely on your requirements.  I
           choose to create them as simple directories, as they are all
           located on the same RAID 5 anyway:</para>
 
         <para>First we will set owners and right of some directories (as
           user <username>root</username>):</para>
 
         <screen>&prompt.root; <userinput>chmod 775 /oracle</userinput>
 &prompt.root; <userinput>chmod 777 /sapmnt</userinput>
 &prompt.root; <userinput>chown root:dba /oracle</userinput>
 &prompt.root; <userinput>chown idsadm:sapsys /compat/linux/usr/sap</userinput>
 &prompt.root; <userinput>chmow 775 /compat/linux/usr/sap</userinput> </screen>
 
         <para>Second we will create directories as user ora&lt;sid&gt;. These
         will all be subdirectories of /oracle/IDS:</para>
 
         <screen>&prompt.root; <userinput>su - oraids</userinput>
 &prompt.root; <userinput>mkdir mirrlogA mirrlogB origlogA origlogB</userinput>
 &prompt.root; <userinput>mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6</userinput>
 &prompt.root; <userinput>mkdir saparch sapreorg</userinput>
 &prompt.root; <userinput>exit</userinput> </screen>
 
         <para>In the third step we create directories as user 
 	  <username>idsadm</username> (&lt;sid&gt;adm):</para>
 
         <screen>&prompt.root; <userinput>su - idsadm</userinput>
 &prompt.root; <userinput>cd /usr/sap</userinput>
 &prompt.root; <userinput>mkdir IDS</userinput>
 &prompt.root; <userinput>mkdir trans</userinput>
 &prompt.root; <userinput>exit</userinput> </screen>
       </sect3>
 
       <sect3 id="entriesinslashetcslashservices">
         <title>Entries in /etc/services</title>
 
         <para>SAP R/3 requires some entries in file
           <filename>/etc/services</filename>, which will not be set
           correctly during installation under FreeBSD.  Please add the
           following entries (you need at least those entries
           corresponding to the instance number - in this case,
           <emphasis>00</emphasis>.  It will do no harm adding all
           entries from <emphasis>00</emphasis> to
           <emphasis>99</emphasis> for <emphasis>dp</emphasis>,
           <emphasis>gw</emphasis>, <emphasis>sp</emphasis> and
           <emphasis>ms</emphasis>):</para>
 
         <programlisting>sapdp00  3200/tcp # SAP Dispatcher.      3200 + Instance-Number
 sapgw00  3300/tcp # SAP Gateway.         3300 + Instance-Number
 sapsp00  3400/tcp #                      3400 + Instance-Number
 sapms00  3500/tcp #                      3500 + Instance-Number
 sapmsIDS 3600/tcp # SAP Message Server.  3600 + Instance-Number</programlisting>
       </sect3>
 
       <sect3 id="necessarylocales">
         <title>Necessary Locales</title>
 	<indexterm><primary>locale</primary></indexterm>
 
         <para>SAP requires at least two locales that are not part of
           the default RedHat installation. SAP offers the required
           RPMs as download from their FTP-server (which is only
           accessible if you are a customer with OSS-access).  See note
           0171356 for a list of RPMs you need.</para>
 
         <para>It is also possible to just create appropriate links
           (for example from <emphasis>de_DE</emphasis> and
           <emphasis>en_US</emphasis> ), but I would not recommend this
           for a production system (so far it worked with the IDES
           system without any problems, though).  The following locales
           are needed:</para>
 
         <programlisting>de_DE.ISO-8859-1
 en_US.ISO-8859-1</programlisting>
 
         <para>If they are not present, there will be some problems
           during the installation.  If these are then subsequently
           ignored (eg by setting the status of the offending steps to
           OK in file CENTRDB.R3S), it will be impossible to log onto
           the SAP-system without some additional effort.</para>
       </sect3>
 
       <sect3 id="kerneltuning">
         <title>Kernel Tuning</title>
 	<indexterm><primary>kernel tuning</primary></indexterm>
 
         <para>SAP R/3 Systems need a lot of resources.  I therefore
         added the following parameters to my kernel config-file:
 
         <programlisting># Set these for memory pigs (SAP and Oracle):
 options MAXDSIZ="(1024*1024*1024)"
 options DFLDSIZ="(1024*1024*1024)" # System V options needed.
 options SYSVSHM #SYSV-style shared memory
 options SHMMAXPGS=262144 #max amount of shared mem. pages
 options SHMMNI=256 #max number of shared memory ident if.
 options SHMSEG=100 #max shared mem.segs per process
 options SYSVMSG #SYSV-style message queues 
 options MSGSEG=32767 #max num. of mes.segments in system 
 options MSGSSZ=32 #size of msg-seg. MUST be power of 2
 options MSGMNB=65535 #max char. per message queue
 options MSGTQL=2046 #max amount of msgs in system
 options SYSVSEM #SYSV-style semaphores 
 options SEMMNU=256 #number of semaphore UNDO structures
 options SEMMNS=1024 #number of semaphores in system
 options SEMMNI=520 #number of semaphore indentifiers
 options SEMUME=100 #number of UNDO keys</programlisting></para>
 
         <para>The minimum values are specified in the documentation that
           comes from SAP.  As there is no description for Linux, see the
           HP-UX-section (32-bit) for further information.
         </para>
       </sect3>
     </sect2>
 
     <sect2 id="installingsapr3">
       <title>Installing SAP R/3</title>
 
       <sect3 id="preparingsapcdroms">
         <title>Preparing SAP CDROMs</title>
 
         <para>There are lots of CDROMs to mount and unmount during
           installation.  Assuming you have enough CDROM-drives, you
           can just mount them all.  I decided to copy the CDROM
           contents to corresponding directories:</para>
 
         <programlisting>/oracle/IDS/sapreorg/&lt;cd-name&gt;</programlisting>
 
         <para>where &lt;cd-name&gt; was one of <filename>KERNEL</filename>, 
 	  <filename>RDBMS</filename>, <filename>EXPORT1</filename>,
 	  <filename>EXPORT2</filename>, <filename>EXPORT3</filename>,
 	  <filename>EXPORT4</filename>, <filename>EXPORT5</filename> and 
 	  <filename>EXPORT6</filename>. All the
 	  filenames should be in capital letters, otherwise use the -g
 	  option for mounting. So use the following commands:</para>
 
         <screen>&prompt.root; <userinput>mount_cd9660 -g /dev/cd0a /mnt</userinput>
 &prompt.root; <userinput>cp -R /mnt/* /oracle/IDS/sapreorg/&lt;cd-name&gt;</userinput>
 &prompt.root; <userinput>umount /mnt</userinput> </screen>
       </sect3>
 
       <sect3 id="runningtheinstall-script">
         <title>Running the install-script</title>
 
         <para>First we need to prepare an install-directory:</para>
 
         <screen>&prompt.root; <userinput>cd /oracle/IDS/sapreorg</userinput>
 &prompt.root; <userinput>mkdir install</userinput>
 &prompt.root; <userinput>cd install</userinput> </screen>
 
         <para>Then the install-script is started, which will copy nearly
           all the relevant files into the install-directory:</para>
 
         <para><filename>/oracle/IDS/sapreorg/KERNEL/UNIX/INSTTOOL.SH</filename></para>
 
         <para>As this is an IDES-Installation with a fully customized
           SAP R/3 Demo-System, we have six instead of just three
           EXPORT-CDs.  At this point the installation template
           CENTRDB.R3S is for installing a standard central instance
           (R/3 and Database), not an IDES central instance, so copy
           the corresponding CENTRDB.R3S from the EXPORT1 directory,
           otherwise R3SETUP will only ask for three EXPORT-CDs.</para>
       </sect3>
 
       <sect3 id="startr3setup">
         <title>Start R3SETUP</title>
 
         <para>Make sure LD_LIBRARY_PATH is set correctly:</para>
 
         <screen>&prompt.root; <userinput>export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib</userinput> </screen>
 
         <para>Start R3SETUP as user root from installation
         directory:</para>
 
         <screen>&prompt.root; <userinput>cd /oracle/IDS/sapreorg/install</userinput>
 &prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput> </screen>
 
         <para>The script then asks some questions (defaults in brackets,
         followed by actual input):</para>
 
         <informaltable>
           <tgroup cols="3">
           <thead>
           <row>
             <entry>Question</entry>
             <entry>Default</entry>
             <entry>Input</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>Enter SAP System ID</entry>
             <entry>[C11]</entry>
             <entry>IDS&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter SAP Instance Number</entry>
             <entry>[00]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter SAPMOUNT Directory</entry>
             <entry>[/sapmnt]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter name of SAP central host</entry>
             <entry>[troubadix.domain.de]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter name of SAP db host</entry>
             <entry>[troubadix]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Select character set</entry>
             <entry>[1] (WE8DEC)</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.6</entry>
             <entry> </entry>
             <entry>1&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Extract Oracle Client archive</entry>
             <entry>[1] (Yes, extract)</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter path to KERNEL CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/KERNEL</entry>
           </row>
           <row>
             <entry>Enter path to RDBMS CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/RDBMS</entry>
           </row>
           <row>
             <entry>Enter path to EXPORT1 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT1</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT1 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD4_DIR]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter path to EXPORT2 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT2</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT2 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD5_DIR]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter path to EXPORT3 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT3</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT3 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD6_DIR]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter path to EXPORT4 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT4</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT4 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD7_DIR]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter path to EXPORT5 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT5</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT5 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD8_DIR]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter path to EXPORT6 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT6</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT6 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD9_DIR]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter amount of RAM for SAP + DB</entry>
             <entry> </entry>
             <entry>850&lt;ret&gt; (in Megabytes)</entry>
           </row>
           <row>
             <entry>Service Entry Message Server</entry>
             <entry>[3600]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter Group-ID of sapsys</entry>
             <entry>[101]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter Group-ID of oper</entry>
             <entry>[102]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter Group-ID of dba</entry>
             <entry>[100]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter User-ID of &lt;sid&gt;adm</entry>
             <entry>[1000]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter User-ID of ora&lt;sid&gt;</entry>
             <entry>[1002]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Number of parallel procs</entry>
             <entry>[2]</entry>
             <entry>&lt;ret&gt;</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
       
         <para>If I had not copied the CDs to the different locations,
           then the SAP-Installer cannot find the CD needed (identified
           by the <filename>LABEL.ASC</filename>-File on CD) and would
           then ask you to insert / mount the CD and confirm or enter
           the mount path.</para>
    
         <para>The <filename>CENTRDB.R3S</filename> might not be
           error-free. In my case, it requested EXPORT4 again (but
           indicated the correct key (6_LOCATI ON, then 7_LOCATION
           etc.), so one can just continue with entering the correct
           values. Do not get irritated.</para>
 
         <para>Apart from some problems mentioned below, everything
           should go straight through up to the point where the Oracle
           database software needs to be installed.</para>
       </sect3>
     </sect2>
 
     <sect2 id="installingoracle805">
       <title>Installing Oracle 8.0.5</title>
 
       <para>Please see the corresponding SAP-Notes and Oracle Readmes
         regarding Linux and Oracle DB for possible problems. Most if
         not all problems stem from incompatible libraries</para>
 
       <para>For more information on installing Oracle, refer to <link
 	  linkend="linuxemu-oracle">the Installing Oracle
 	  chapter.</link></para>
 
 
       <sect3 id="installingtheoracle805withorainst">
         <title>Installing the Oracle 8.0.5 with orainst</title>
 
         <para>If <application>Oracle 8.0.5</application> is to be
           used, some additional libraries are needed for successfully
           relinking, as Oracle 8.0.5 was linked with an old glibc
           (RedHat 6.0), but RedHat 6.1 already uses a new glibc. So
           you have to install the following additional packages to
           ensure that linking will work:</para>
 
         <para><filename>compat-libs-5.2-2.i386.rpm</filename></para>
         <para><filename>compat-glibc-5.2-2.0.7.2.i386.rpm</filename></para>
         <para><filename>compat-egcs-5.2-1.0.3a.1.i386.rpm</filename></para>
         <para><filename>compat-egcs-c++-5.2-1.0.3a.1.i386.rpm</filename></para>
         <para><filename>compat-binutils-5.2-2.9.1.0.23.1.i386.rpm</filename></para>
 
         <para>See the corresponding SAP-Notes or Oracle Readmes for
           further information.  If this is no option (at the time of
           installation I did not have enough time to check this), one
           could use the original binaries, or use the relinked
           binaries from an original RedHat System.</para>
 
         <para>For compiling the intelligent agent, the RedHat Tcl
           package must be installed.  If you cannot get
           <filename>tcl-8.0.3-20.i386.rpm</filename>, a newer one like
           <filename>tcl-8.0.5-30.i386.rpm</filename> for RedHat 6.1
           should also do.</para>
 
         <para>Apart from relinking, the installation is
           straightforward:</para>
 
         <screen>&prompt.root; <userinput>su - oraids</userinput>
 &prompt.root; <userinput>export TERM=xterm</userinput>
 &prompt.root; <userinput>export ORACLE_TERM=xterm</userinput>
 &prompt.root; <userinput>export ORACLE_HOME=/oracle/IDS</userinput>
 &prompt.root; <userinput>cd /ORACLE_HOME/orainst_sap</userinput>
 &prompt.root; <userinput>./orainst</userinput> </screen>
 
         <para>Confirm all Screens with Enter until the software is
           installed, except that one has to deselect the
           <emphasis>Oracle On-Line Text Viewer</emphasis>, as this is
           not currently available for Linux. Oracle then wants to
           relink with <command>i386-glibc20-linux-gcc</command>
           instead of the available <command>gcc</command>,
           <command>egcs</command> or <command>i386-redhat-linux-gcc
           </command>.</para>
 
         <para>Due to time constrains I decided to use the binaries
           from an <application>Oracle 8.0.5 PreProduction</application>
 	  release, after the first
           attempt at getting the version from the RDBMS-CD working,
           failed, and finding / accessing the correct RPMs was a
           nightmare at that time.</para>
 
       </sect3>
 
       <sect3 id="installingtheoracle805preproduction">
         <title>Installing the Oracle 8.0.5 Pre-Production release for
           Linux (Kernel 2.0.33)</title>
 
         <para>This installation is quite easy. Mount the CD, start the
           installer.  It will then ask for the location of the Oracle
           home directory, and copy all binaries there. I did not
           delete the remains of my previous RDBMS-installation tries,
           though.</para>
 
         <para>Afterwards, Oracle Database could be started with no
           problems.</para>
       </sect3>
     </sect2>
 
     <sect2 id="continuewithsapr4installation">
       <title>Continue with SAP R/3 Installation</title>
 
       <para>First check the environment settings of users 
 	<username>idsamd</username>
         (&lt;sid&gt;adm) and 
 	<username>oraids</username> (ora&lt;sid&gt;). They should now
         both have the files <filename>.profile</filename>,
         <filename>.login</filename> and <filename>.cshrc</filename>
         which are all using <command>hostname</command>. In case the
         system's hostname is the fully qualified name, you need to
         change <command>hostname</command> to <command>hostname
         -s</command> within all three files.</para>
 
       <sect3 id="databaseload">
         <title>Database Load</title>
 
         <para>Afterwards, R3SETUP can either be restarted or continued
           (depending on whether exit was chosen or not). R3SETUP then
           creates the tablespaces and loads the data from EXPORT1 to
           EXPORT6 (remember, it is an IDES system, otherwise it would
           only be EXPORT1 to EXPORT3) with R3load into the
           database.</para>
 
         <para>When the database load is finished (might take a few
           hours), some passwords are requested. For test
           installations, one can use the well known default passwords
           (use different ones if security is an issue!):</para>
 
         <informaltable>
           <tgroup cols="2">
           <thead>
           <row>
             <entry>Question</entry>
             <entry>Input</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>Enter Password for sapr3</entry>
             <entry>sap&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Confirum Password for sapr3</entry>
             <entry>sap&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter Password for sys</entry>
             <entry>change_on_install&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Confirm Password for sys</entry>
             <entry>change_on_install&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Enter Password for system</entry>
             <entry>manager&lt;ret&gt;</entry>
           </row>
           <row>
             <entry>Confirm Password for system</entry>
             <entry>manager&lt;ret&gt;</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>At this point I had a few problems with 
 	  <literal>dipgntab</literal>.</para>
       </sect3>
 
       <sect3 id="listener">
         <title>Listener</title>
 
         <para>Start the Oracle-Listener as user 
 	  <username>oraids</username> (ora&lt;sid&gt;) as follows:</para>
 
         <programlisting>umask 0; lsnrctl start</programlisting>
 
         <para>Otherwise you might get ORA-12546 as the sockets will not
         have the correct permissions. See SAP note 072984.</para>
       </sect3>
     </sect2>
 
     <sect2 id="postinstallationsteps">
       <title>Post-installation Steps</title>
 
       <sect3 id="requestsapr3licensekey">
         <title>Request SAP R/3 License Key</title>
 
         <para>This is needed, as the temporary license is only valid for
         four weeks.  Do not forget to enter the correct Operating System:
         (X) Other: <emphasis>FreeBSD 4.3 Stable</emphasis>. First get
         the hardware key.  Log on as user <username>idsadm</username> and
         call <command>saplicense</command>:</para>
 
         <screen>&prompt.root; <userinput>/sapmnt/IDS/exe/saplicense -get</userinput></screen>
 
         <para>Calling <command>saplicense</command> without options
         gives a list of options.  Upon receiving the license key, it can
         be installed using</para>
 
         <screen>&prompt.root; <userinput>/sapmnt/IDS/exe/saplicense -install</userinput></screen>
 
         <para>You are then required to enter the following
         values:</para>
 
         <programlisting>SAP SYSTEM ID   = &lt;SID, 3 chars&gt;
 CUSTOMER KEY    = &lt;hardware key, 11 chars&gt;
 INSTALLATION NO = &lt;installation, 10 digits&gt;
 EXPIRATION DATE = &lt;yyyymmdd, usually "99991231"&gt;
 LICENSE KEY     = &lt;license key, 24 chars&gt;</programlisting>
       </sect3>
 
       <sect3 id="creatingusers">
         <title>Creating Users</title>
 
         <para>Create a user within client 000 (for some tasks required
         to be done within client 000, but with a user different from
         users <username>sap*</username> and
         <username>ddic</username>). As a username, I usually choose
         <replaceable>wartung</replaceable> (or
         <replaceable>service</replaceable> in English).  Profiles
         required are <emphasis>sap_new</emphasis> and
         <emphasis>sap_all</emphasis>. For additional safety the
         passwords of default users within all clients should be
         changed (this includes users <username>sap*</username> and
         <username>ddic</username>).</para>
       </sect3>
 
       <sect3 id="configtranssysprofileopermodesetc">
         <title>Configure Transport System, Profile, Operation Modes, Etc.</title>
 
         <para>Within client 000, user different from <username>ddic</username>
 	  and sap*, do at least the following:</para>
 
         <informaltable>
           <tgroup cols="2">
           <thead>
           <row>
             <entry>Task</entry>
             <entry>Transaction</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>Configure Transport System, eg as <emphasis>Stand-Alone
             Transport Domain Entity</emphasis></entry>
 	    <entry>STMS</entry>
           </row>
           <row>
             <entry>Create / Edit Profile for System</entry>
             <entry>RZ10</entry>
           </row>
           <row>
             <entry>Maintain Operation Modes and Instances</entry>
             <entry>RZ04</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>These and all the other post-installation steps are
           thoroughly described in SAP installation guides.</para>
       </sect3>
 
       <sect3 id="editintsidsap">
         <title>Edit init&lt;sid&gt;.sap (initIDS.sap)</title>
 
         <para>The file
           <filename>/oracle/IDS/dbs/initIDS.sap</filename> contains
           the SAP backup profile.  Here the size of the tape to be
           used, type of compression and so on need to be defined. To
           get this running with <command>sapdba</command> /
           <command>brbackup</command>, I changed the following
           values:</para>
 
         <programlisting>compress = hardware
 archive_function = copy_delete_save
 cpio_flags = "-ov --format=newc --block-size=128 --quiet"
 cpio_in_flags = "-iuv --block-size=128 --quiet"
 tape_size = 38000M
 tape_address = /dev/nsa0
 tape_address_rew = /dev/sa0</programlisting>
 
         <para>Explanations:</para>
 
         <para><emphasis>compress</emphasis> The tape I use is a HP DLT1
         which does hardware compression.</para>
 
         <para><emphasis>archive_function</emphasis> This defines the
         default behavior for saving Oracle archive logs: New logfiles
         are saved to tape, already saved logfiles are saved again and
         are then deleted.  This prevents lots of trouble if one needs to
         recover the database, and one of the archive-tapes has gone
         bad.</para>
 
         <para><emphasis>cpio_flags</emphasis> Default is to use -B which
         sets blocksize to 5120 Bytes. For DLT-Tapes, HP recommends at
         least 32K blocksize, so I used --block-size=128 for
         64K. --format=newc is needed I have inode numbers greater than
         65535. The last option --quiet is needed as otherwise 
 	<command>brbackup</command>
         complains as soon as <command>cpio</command> outputs the 
 	numbers of blocks saved.</para>
 
         <para><emphasis>cpio_in_flags</emphasis> Flags needed for
         loading data back from tape. Format is recognized
         automagically.</para>
 
         <para><emphasis>tape_size</emphasis> This usually gives the raw
         storage capability of the tape. For security reason (we use
         hardware compression), the</para>
 
         <para><emphasis>value</emphasis> is slightly lower than the
         actual value.</para>
 
         <para><emphasis>tape_address</emphasis> The non-rewindable
         device to be used with <command>cpio</command>.</para>
 
         <para><emphasis>tape_address_rew The rewindable device to be
         used with cpio.</emphasis></para>
       </sect3>
 
       <sect3>
 	<title>Configuration Issues after Installation</title>
 
 	<para>The following SAP-parameters should be tuned after
 	  installation:</para>
 
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Name</entry>
 		<entry>Value</entry>
 	      </row>
 	    </thead>
 	    <tbody>
 	      <row>
 		<entry>ztta/roll_extension</entry>
 		<entry>250000000</entry>
 	      </row>
 	      <row>
 		<entry>abap/heap_area_dia</entry>
                 <entry>300000000</entry>
 	      </row>
 	      <row>
 		<entry>abap/heap_area_nondia</entry>
 		<entry>400000000</entry>
 	      </row>
 	      <row>
 		<entry>em/initial_size_MB</entry>
 		<entry>256</entry>
 	      </row>
 	      <row>
 		<entry>em/blocksize_kB</entry>
 		<entry>1024</entry>
 	      </row>
 	      <row>
 		<entry>ipc/shm_psize_40</entry>
 		<entry>70000000</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
 	<para>SAP-Note 0013026:</para>
 
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Name</entry>
 		<entry>Value</entry>
 	      </row>
 	    <tbody>
 	      <row>
 		<entry>ztta/dynpro_area</entry>
 		<entry>2500000</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
 	<para>SAP-Note 0157246:</para>
 
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Name</entry>
 		<entry>Value</entry>
 	      </row>
 	    <tbody>
 	      <row>
 		<entry>rdisp/ROLL_MAXFS</entry>
 		<entry>16000</entry>
 	      </row>
 	      <row>
 		<entry>rdisp/PG_MAXFS</entry>
 		<entry>30000</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
 	<note>
 	  <para>With the above parameters, on a system with 1 gigabyte
 	    of memory, one may find memory consumption similar to:
 
 	  <programlisting>Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K Free</programlisting></para>
 	</note>
       </sect3>
     </sect2>
 
     <sect2 id="problemsduringinstallation">
       <title>Problems During Installation</title>
 
       <sect3 id="indoraduringduringr3setup">
         <title>OSUSERSIDADM_IND_ORA During R3SETUP</title>
 
         <para>If R3SETUP complains at this stage, edit file
           CENTRDB.R3S.  Locate [OSUSERSIDADM_IND_ORA] and edit the
           following values:</para>
 
         <programlisting>HOME=/home/idsadm (was empty)
 STATUS=OK (had status ERROR)
         </programlisting>
 
         <para>Then you can restart R3SETUP with:</para>
 
         <screen>&prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput></screen>
       </sect3>
 
       <sect3 id="indoraduringr3setup">
         <title>OSUSERDBSID_IND_ORA During R3SETUP</title>
 
         <para>Possibly R3SETUP also complains at this stage. Just edit
           CENTRDB.R3S.  Locate [OSUSERDBSID_IND_ORA] and edit the
           following value in that section:</para>
 
         <programlisting>STATUS=OK</programlisting>
 
         <para>Then just restart R3SETUP again:</para>
 
         <screen>&prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput></screen>
       </sect3>
 
       <sect3 id="oraviewvrffilenotfound">
         <title>oraview.vrf FILE NOT FOUND During Oracle Installation</title>
 
         <para>You have not deselected <emphasis>Oracle On-Line Text Viewer</emphasis>
           before starting the installation. This is marked for installation even
           though this option is currently not available for Linux. Deselect this
           product inside the Oracle installation menu and restart installation.</para>
       </sect3>
 
       <sect3 id="textenvincalid">
         <title>TEXTENV_INVALID During R3SETUP, RFC or SAPGUI Start</title>
 
         <para>If this error is encountered, the correct locale is
 	  missing.  SAP note 0171356 lists the necessary RPMs that need
 	  be installed (eg <emphasis>saplocales-1.0-3</emphasis>,
 	  <emphasis>saposcheck-1.0-1</emphasis> for RedHat 6.1). In case
 	  you ignored all the related errors and set the corresponding
 	  status from ERROR to OK (in CENTRDB.R3S) every time R3SETUP
 	  complained and just restarted R3SETUP, the SAP-System will not
 	  be properly configured and you will then not be able to
 	  connect to the system with a
 	  <literal>sapgui</literal>, even though the system
 	  can be started. Trying to connect with the old Linux
 	  <literal>sapgui</literal> gave the following
 	  messages:</para>
 
         <programlisting>Sat May 5 14:23:14 2001
 *** ERROR => no valid userarea given [trgmsgo. 0401]
 Sat May 5 14:23:22 2001
 *** ERROR => ERROR NR 24 occured [trgmsgi. 0410]
 *** ERROR => Error when generating text environment. [trgmsgi. 0435]
 *** ERROR => function failed [trgmsgi. 0447]
 *** ERROR => no socket operation allowed [trxio.c 3363]
 Speicherzugriffsfehler</programlisting>
 
         <para>This behavior is due to SAP R/3 being unable to
           correctly assign a locale and also not being properly
           configured itself (missing entries in some database
           tables). To be able to connect to SAP, add the following
           entries to file DEFAULT.PFL (see note 0043288):</para>
 
         <programlisting>abap/set_etct_env_at_new_mode =0
 install/collate/active =0
 rscp/TCP0B =TCP0B
         </programlisting>
 
         <para>Restart the SAP system. Now one can connect to the
           system, even though country-specific language settings might
           not work as expected.  After correcting country-settings
           (and providing the correct locales), these entries can be
           removed from DEFAULT.PFL and the SAP system can be
           restarted.</para>
 
       </sect3>
 
       <sect3 id="ora-12546">
         <title>ORA-12546. Start Listener with Correct Permissions</title>
 
         <para>Start the Oracle Listener as user
           <username>oraids</username> with the following commands:</para>
 
         <screen>&prompt.root; <userinput>umask 0; lsnrctl start</userinput></screen>
 
         <para>Otherwise one might get ORA-12546 as the sockets will not
           have the correct permissions. See SAP note 0072984.</para>
       </sect3>
 
       <sect3 id="dipgntabindind">
         <title>[DIPGNTAB_IND_IND] During R3SETUP</title>
 
         <para>In general, see SAP note 0130581 (R3SETUP step 
 	  <literal>DIPGNTAB</literal>
           terminates).  During this specific installation, for some
           reasons the installation process was not using the proper
           SAP system name "IDS", but the empty string "" instead. This
           lead to some minor problems with accessing directories, as
           the paths are generated dynamically using &lt;sid&gt; (in
           this case IDS).  So instead of accessing:</para>
 
         <programlisting>/usr/sap/IDS/SYS/...
 /usr/sap/IDS/DVMGS00</programlisting>
 
         <para>the following path were used:</para>
 
         <programlisting>/usr/sap//SYS/...
 /usr/sap/D00i</programlisting>
 
         <para>To continue with the installation, I created a link and an
           additional directory:</para>
 
         <screen>&prompt.root; pwd
 /compat/linux/usr/sap
 &prompt.root; ls -l
 total 4
 drwxr-xr-x 3  idsadm sapsys 512 May 5 11:20 D00
 drwxr-x--x 5  idsadm sapsys 512 May 5 11:35 IDS
 lrwxr-xr-x 1  root   sapsys 7 May 5 11:35 SYS -> IDS/SYS
 drwxrwxr-x 2  idsadm sapsys 512 May 5 13:00 tmp
 drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans </screen>
    
         <para>I also found SAP notes (0029227 and 0008401) describing
         this behavior.</para>
       </sect3>
 
       <sect3 id="rfcrswboiniindind">
         <title>[RFCRSWBOINI_IND_IND] During R3SETUP</title>
 
         <para>Set STATUS of the offending step from ERROR to OK (file
 	  <filename>CENTRDB.R3S</filename>) and restart R3SETUP. After
 	  installation, you have to execute the report
 	  <literal>RSWBOINS</literal> from transaction SE38. See SAP
 	  note 0162266 for additional information about phase
 	  <literal>RFCRSWBOINI</literal> and
 	  <literal>RFCRADDBDIF</literal>.</para>
       </sect3>
 
       <sect3 id="rfcraddbdifindind">
         <title>[RFCRADDBDIF_IND_IND] During R3SETUP</title>
 
         <para>Set STATUS of the offending step from ERROR to OK (file
 	  <filename>CENTRDB.R3S</filename>) and restart R3SETUP. After
 	  installation, you have to execute the report
 	  <literal>RADDBDIF</literal> from transaction SE38.
 	  See SAP note 0162266 for further information.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Advanced Topics</title>
 
     <para>If you are curious as to how the Linux binary compatibility
       works, this is the section you want to read.  Most of what follows
       is based heavily on an email written to &a.chat; by Terry Lambert
       <email>tlambert@primenet.com</email> (Message ID:
       <literal>&lt;199906020108.SAA07001@usr09.primenet.com&gt;</literal>).</para>
 
     <sect2>
       <title>How Does It Work?</title>
       <indexterm><primary>execution class loader</primary></indexterm>
 
       <para>FreeBSD has an abstraction called an <quote>execution class
 	loader</quote>.  This is a wedge into the &man.execve.2; system
 	call.</para>
 
       <para>What happens is that FreeBSD has a list of loaders, instead of
 	a single loader with a fallback to the <literal>#!</literal>
 	loader for running any shell interpreters or shell scripts.</para>
 
       <para>Historically, the only loader on the Unix platform examined
 	the magic number (generally the first 4 or 8 bytes of the file) to
 	see if it was a binary known to the system, and if so, invoked the
 	binary loader.</para>
 
       <para>If it was not the binary type for the system, the
 	&man.execve.2; call returned a failure, and the shell attempted to
 	start executing it as shell commands.</para>
 
       <para>The assumption was a default of <quote>whatever the current
 	shell is</quote>.</para>
 
       <para>Later, a hack was made for &man.sh.1; to examine the first two
 	characters, and if they were <literal>:\n</literal>, then it
 	invoked the &man.csh.1; shell instead (we believe SCO first made
 	this hack).</para>
 
       <para>What FreeBSD does now is go through a list of loaders, with a
 	generic <literal>#!</literal> loader that knows about interpreters
 	as the characters which follow to the next whitespace next to
 	last, followed by a fallback to
 	<filename>/bin/sh</filename>.</para>
       <indexterm><primary>ELF</primary></indexterm>
 
       <para>For the Linux ABI support, FreeBSD sees the magic number as an
 	ELF binary (it makes no distinction between FreeBSD, Solaris,
 	Linux, or any other OS which has an ELF image type, at this
 	point).</para>
       <indexterm><primary>Solaris</primary></indexterm>
 
       <para>The ELF loader looks for a specialized
 	<emphasis>brand</emphasis>, which is a comment section in the ELF
 	image, and which is not present on SVR4/Solaris ELF
 	binaries.</para>
 
       <para>For Linux binaries to function, they must be
 	<emphasis>branded</emphasis> as type <literal>Linux</literal>;
 	from &man.brandelf.1;:</para>
 
       <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>
 
       <para>When this is done, the ELF loader will see the
 	<literal>Linux</literal> brand on the file.</para>
       <indexterm>
         <primary>ELF</primary>
 	<secondary>branding</secondary>
       </indexterm>
 
       <para>When the ELF loader sees the <literal>Linux</literal> brand,
 	the loader replaces a pointer in the <literal>proc</literal>
 	structure.  All system calls are indexed through this pointer (in
 	a traditional Unix system, this would be the
 	<literal>sysent[]</literal> structure array, containing the system
 	calls).  In addition, the process flagged for special handling of
 	the trap vector for the signal trampoline code, and sever other
 	(minor) fix-ups that are handled by the Linux kernel
 	module.</para>
 
       <para>The Linux system call vector contains, among other things, a
 	list of <literal>sysent[]</literal> entries whose addresses reside
 	in the kernel module.</para>
 
       <para>When a system call is called by the Linux binary, the trap
 	code dereferences the system call function pointer off the
 	<literal>proc</literal> structure, and gets the Linux, not the
 	FreeBSD, system call entry points.</para>
 
       <para>In addition, the Linux mode dynamically
 	<emphasis>reroots</emphasis> lookups; this is, in effect, what the
 	<literal>union</literal> option to FS mounts
 	(<emphasis>not</emphasis> the unionfs!) does.  First, an attempt
 	is made to lookup the file in the
 	<filename>/compat/linux/<replaceable>original-path</replaceable></filename>
 	directory, <emphasis>then</emphasis> only if that fails, the
 	lookup is done in the
 	<filename>/<replaceable>original-path</replaceable></filename>
 	directory.  This makes sure that binaries that require other
 	binaries can run (e.g., the Linux toolchain can all run under
 	Linux ABI support).  It also means that the Linux binaries can
 	load and exec FreeBSD binaries, if there are no corresponding
 	Linux binaries present, and that you could place a &man.uname.1;
 	command in the <filename>/compat/linux</filename> directory tree
 	to ensure that the Linux binaries could not tell they were not
 	running on Linux.</para>
 
       <para>In effect, there is a Linux kernel in the FreeBSD kernel; the
 	various underlying functions that implement all of the services
 	provided by the kernel are identical to both the FreeBSD system
 	call table entries, and the Linux system call table entries: file
 	system operations, virtual memory operations, signal delivery,
 	System V IPC, etc&hellip;  The only difference is that FreeBSD
 	binaries get the FreeBSD <emphasis>glue</emphasis> functions, and
 	Linux binaries get the Linux <emphasis>glue</emphasis> functions
 	(most older OS's only had their own <emphasis>glue</emphasis>
 	functions: addresses of functions in a static global
 	<literal>sysent[]</literal> structure array, instead of addresses
 	of functions dereferenced off a dynamically initialized pointer in
 	the <literal>proc</literal> structure of the process making the
 	call).</para>
 
       <para>Which one is the native FreeBSD ABI?  It does not matter.
 	Basically the only difference is that (currently; this could
 	easily be changed in a future release, and probably will be after
 	this) the FreeBSD <emphasis>glue</emphasis> functions are
 	statically linked into the kernel, and the Linux glue functions
 	can be statically linked, or they can be accessed via a kernel
 	module.</para>
 
       <para>Yeah, but is this really emulation?  No.  It is an ABI
 	implementation, not an emulation.  There is no emulator (or
 	simulator, to cut off the next question) involved.</para>
 
       <para>So why is it sometimes called <quote>Linux emulation</quote>?
 	To make it hard to sell FreeBSD!  Really, it
 	is because the historical implementation was done at a time when
 	there was really no word other than that to describe what was
 	going on; saying that FreeBSD ran Linux binaries was not true, if
 	you did not compile the code in or load a module, and there needed
 	to be a word to describe what was being loaded&mdash;hence
 	<quote>the Linux emulator</quote>.</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/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
index 5c682c3fa5..2c8e8a454d 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
@@ -1,1544 +1,1544 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="ports">
   <title>Installing Applications: Packages and Ports</title>
 
   <sect1>
     <title>Synopsis</title>
 
     <indexterm><primary>ports</primary></indexterm>
     <indexterm><primary>packages</primary></indexterm>
     <para>FreeBSD is bundled with a rich collection of system tools as
       part of the base system.  However, there is only so much one can
       do before needing to install an additional third-party
       application to get real work done.  FreeBSD provides two
       complementary technologies for installing third party software
       on your system; the FreeBSD Ports Collection, and binary
       software packages.  Either system may be used to install the
       newest version of your favorite applications from local media or
       straight off the network.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How to install third-party binary software packages.</para>
       </listitem>
       <listitem>
 	<para>How to build third-party software from the ports
 	collection.</para>
       </listitem>
       <listitem>
 	<para>How to remove previously installed packages or ports.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1>
     <title>Overview of Software Installation</title>
 
     <para>If you have used a Unix system before you will know that the typical
       procedure for installing third party software goes something like
       this:</para>
 
     <procedure>
       <step>
 	<para>Download the software, which might be distributed in source code
 	  format, or as a binary.</para>
       </step>
 
       <step>
 	<para>Unpack the software from its distribution format (typically a
 	  tarball compressed with either &man.compress.1; or &man.gzip.1;).</para>
       </step>
 
       <step>
 	<para>Locate the documentation (perhaps a <filename>README</filename>
 	  file, or some files in a <filename>doc/</filename> subdirectory) and
 	  read up on how to install the software.</para>
       </step>
 
       <step>
 	<para>If the software was distributed in source format, compile it.
 	  This may involve editing a <filename>Makefile</filename>, or
 	  running a <command>configure</command> script, and other work.</para>
       </step>
 
       <step>
 	<para>Test and install the software.</para>
       </step>
     </procedure>
 
     <para>And that is only if everything goes well.  If you are installing a
       software package that was not deliberately ported to FreeBSD you may
       even have to go in and edit the code to make it work properly.</para>
 
     <para>Should you want to, you can continue to install software the
       <quote>traditional</quote> way with FreeBSD.  However, FreeBSD
       provides two technologies which can save you a lot of effort;
       packages and ports.  At the time of writing, over &os.numports;
       third party applications have been made available in this
       way.</para>
 
     <para>For any given application, the FreeBSD package for that application
       is a single file which you must download.  The package contains
       pre-compiled copies of all the commands for the application, as well as
       any configuration files or documentation.  A downloaded package file can
       be manipulated with FreeBSD package management commands, such as
       &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so on.</para>
 
     <para>Installing a new application can be carried out with a single
       command.</para>
 
     <para>A FreeBSD port for an application is a collection of files designed
       to automate the process of compiling an application from source
       code.</para>
 
     <para>Remember that there are a number of steps you would normally carry
       out if you compiled a program yourself (unpacking, patching, compiling,
       installing).  The files that make up a port contain all the necessary
       information to allow the system to do this for you.  You run a handful
       of simple commands and the source code for the application is
       automatically downloaded, extracted, patched, compiled, and installed
       for you.</para>
 
     <para>In fact, the ports system can also be used to generate packages
       which can later be manipulated with <command>pkg_add</command>
       and the other package management commands that will be introduced
       shortly.</para>
 
     <para>Both packages and ports understand
       <emphasis>dependencies</emphasis>.  Suppose you want to install an
       application that depends on a specific library being installed.  Both
       the application and the library have been made available as FreeBSD
       ports and packages.  If you use the <command>pkg_add</command> command
       or the ports system to add the application, both will notice that the
       library has not been installed, and the commands will install the
       library first.</para>
 
     <para>Given that the two technologies are quite similar, you might be
       wondering why FreeBSD bothers with both.  Packages and ports both have
       their own strengths, and which one you use will depend on your own
       preference.</para>
 
     <itemizedlist>
       <title>Package Benefits</title>
       
       <listitem>
 	<para>A compressed package tarball is typically smaller than the
 	  compressed tarball containing the source code for the application.</para>
       </listitem>
 
       <listitem>
 	<para>Packages do not require any additional compilation.  For large
 	  applications, such as <application>Mozilla</application>,
 	  <application>KDE</application>, or <application>GNOME</application>
 	  this can be important, particularly if you are on a slow system.</para>
       </listitem>
 
       <listitem>
 	<para>Packages do not require you to understand the process
 	  involved in compiling software on FreeBSD.</para>
       </listitem>
     </itemizedlist>
 
     <itemizedlist>
       <title>Ports Benefits</title>
       
       <listitem>
 	<para>Packages are normally compiled with conservative options,
 	  because they have to run on the maximum number of systems.  By
 	  installing from the port, you can tweak the compilation options to
 	  (for example) generate code that is specific to a Pentium
 	  III or Athlon processor.</para>
       </listitem>
 
       <listitem>
 	<para>Some packages have compile time options relating to what they
 	  can and cannot do.  For example, <application>Apache</application>
 	  can be configured with a wide variety of different built-in options.
 	  By building from the port you do not have to accept the default
 	  options, and can set them yourself.</para>
 
 	<para>In some cases, multiple packages will exist for the same
 	  application to specify certain settings.  For example,
 	  <application>Ghostscript</application> is available as a
 	  <filename>ghostscript</filename> package and a
 	  <filename>ghostscript-nox11</filename> package, depending on whether
 	  or not you have installed an X11 server.  This sort of rough
 	  tweaking is possible with packages, but rapidly becomes impossible
 	  if an application has more than one or two different compile time
 	  options.</para>
       </listitem>
 
       <listitem>
 	<para>The licensing conditions of some software distributions forbid
 	  binary distribution.  They must be distributed as source
 	  code.</para>
       </listitem>
 
       <listitem>
 	<para>Some people do not trust binary distributions.  At least with
 	  source code, you can (in theory) read through it and look for
 	  potential problems yourself.</para>
       </listitem>
 
       <listitem>
 	<para>If you have local patches, you will need the source in order to
 	  apply them.</para>
       </listitem>
 
       <listitem>
 	<para>Some people like having code around, so they can read it if they
 	  get bored, hack it, borrow from it (license permitting, of course),
 	  and so on.</para>
       </listitem>
     </itemizedlist>
 
     <para>To keep track of updated ports, subscribe to the
       &a.ports;.</para>
 
     <para>The remainder of this chapter will explain how to use packages and
       ports to install and manage third party software on FreeBSD.</para>
   </sect1>
 
   <sect1>
     <title>Finding Your Application</title>
 
     <para>Before you can install any applications you need to know what you
       want, and what the application is called.</para>
 
     <para>FreeBSD's list of available applications is growing all the
       time.  Fortunately, there are a number of ways to
       find what you want.</para>
 
     <itemizedlist>
       <listitem>
 	<para>The FreeBSD web site maintains an up-to-date searchable list of
 	  all the available applications, at
 	  <ulink url="../../../../ports/index.html">http://www.FreeBSD.org/ports/</ulink>.
 	  The name space is divided in to categories, and you may either
 	  search for an application by name (if you know it), or you can list
 	  all the applications available in a category.</para>
       </listitem>
 
       <indexterm><primary>FreshPorts</primary></indexterm>
 
       <listitem>
 	<para>Dan Langille maintains FreshPorts, at
 	  <ulink url="http://www.FreshPorts.org/">http://www.FreshPorts.org/</ulink>.
 	  FreshPorts tracks changes to the applications in the ports tree as
 	  they happen, and allows you to <quote>watch</quote> one or more
 	  ports, and will send you an email when they are updated.</para>
       </listitem>
 
       <indexterm><primary>FreshMeat</primary></indexterm>
 
       <listitem>
 	<para>If you do not know the name of the application you want, try
 	  using a site like FreshMeat
 	  (<ulink url="http://www.freshmeat.net/">http://www.freshmeat.net/</ulink>)
 	  to find an application, then check back at the FreeBSD site to see
 	  if the application has been ported yet.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="packages-using">
     <sect1info>    
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
 	  <surname>Lee</surname>
 	  <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     <!-- 30 Mar 2001 -->
     </sect1info>
 
     <title>Using the Packages System</title>
 
     <sect2>
       <title>Installing a Package</title>
       <indexterm>
         <primary>packages</primary>
         <secondary>installing</secondary>
       </indexterm>
     
       <indexterm>
         <primary><command>pkg_add</command></primary>
       </indexterm>
       <para>You can use the &man.pkg.add.1; utility to install a
 	FreeBSD software package from a local file or from a server on
 	the network.</para>
 
       <example>
         <title>Downloading a Package and then Installing It Locally</title>
 
         <screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput>
 Connected to ftp2.FreeBSD.org.
 220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
 331 Guest login ok, send your email address as password.
 230-
 230-     This machine is in Vienna, VA, USA, hosted by Verio.
 230-         Questions? E-mail freebsd@vienna.verio.net.
 230-
 230-
 230 Guest login ok, access restrictions apply.
 Remote system type is UNIX.
 Using binary mode to transfer files.
 <prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/packages/sysutils/</userinput>
 250 CWD command successful.
 <prompt>ftp></prompt> <userinput>get lsof-4.56.4.tgz</userinput>
 local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
 200 PORT command successful.
 150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
 100% |**************************************************| 92375       00:00 ETA
 226 Transfer complete.
 92375 bytes received in 5.60 seconds (16.11 KB/s)
 <prompt>ftp></prompt> <userinput>exit</userinput>
 &prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen>
       </example>
 
       <para>If you do not have a source of local packages (such as a
         FreeBSD CDROM set) then it will probably be easier to use the
         -r option to &man.pkg.add.1;.  This will cause the utility to
         automatically determine the correct object format and release
         and then to fetch and install the package from an FTP site.
       </para>
 
       <indexterm>
         <primary><command>pkg_add</command></primary></indexterm>
       <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof-4.56.4</replaceable></userinput></screen>
 
       <para>The example above would download the correct package and add it without
         any further user intervention.</para>
 
       <para>Package files are distributed in .tgz format.  You can
           find them at <ulink
           url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">
           ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/</ulink>,
           or on the FreeBSD CDROM distribution.  Every CD on the
           FreeBSD 4-CD set (and PowerPak, etc) contains packages in
           the <filename>/packages</filename> directory.  The layout of
           the packages is similar to that of the
           <filename>/usr/ports</filename> tree.  Each category has its
           own directory, and every package can be found within the
           <filename>All</filename> directory.
       </para>
 
       <para>The directory structure of the package system is identical
         to that of the ports; they work with each other to form the entire
         package/port system.
       </para>
 
     </sect2>
 
     <sect2>
       <title>Deleting a Package</title>
       <indexterm>
         <primary><command>pkg_delete</command></primary>
       </indexterm>
       <indexterm>
         <primary>packages</primary>
         <secondary>deleting</secondary>
       </indexterm>
       <para>To remove a previously installed software package, use the
 	&man.pkg.delete.1; utility.
       </para>
 
-      <screen>&prompt.root <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>
+      <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>
     </sect2>
 
     <sect2>
       <title>Managing Packages</title>
 
       <indexterm>
         <primary>packages</primary>
         <secondary>managing</secondary>
       </indexterm>
       <para>&man.pkg.info.1; is a utility that lists and describes 
         the various packages installed.
       </para>
 
       <indexterm>
         <primary><command>pkg_info</command></primary>
       </indexterm>
-      <screen>&prompt.root <userinput>pkg_info</userinput>
+      <screen>&prompt.root; <userinput>pkg_info</userinput>
 cvsup-16.1          A general network file distribution system optimized for CV
 docbook-1.2         Meta-port for the different versions of the DocBook DTD
 ...</screen>
       <para>&man.pkg.version.1; is a utility that summarizes the
         versions of all installed packages.  It compares the package 
         version to the current version found in the ports tree.
       </para> 
-        <screen>&prompt.root <userinput>pkg_version</userinput>
+        <screen>&prompt.root; <userinput>pkg_version</userinput>
 cvsup                       =
 docbook                     =
 ...</screen>
 
       <para>The symbols in the second column indicate the relative age
       of the installed version and the version available in the local
       ports tree.</para>
 
       <informaltable frame="none">
         <tgroup cols="2">
 	  <thead>
             <row>
               <entry>Symbol</entry>
               <entry>Meaning</entry>
             </row>
           </thead>
 
  	  <tbody>
   	    <row>
 	    <entry>=</entry> <entry>The version of the
 	    installed package matches that of the one found in the
 	    local ports tree.</entry>
   	    </row>
  
         <row><entry>&lt;</entry>
 	<entry>The installed version is older then the one available
 	in the ports tree.</entry>
 	</row>
 
         <row><entry>&gt;</entry><entry>The installed version is newer
           than the one found in the local ports tree. (local ports
           tree is probably out of date)</entry></row>
 
         <row><entry>?</entry><entry>The installed package cannot be
         found in the ports index.</entry></row>
 
         <row><entry>*</entry><entry>There are multiple versions of the
         package.</entry></row>
 
 	</tbody>
 	</tgroup>
     </informaltable>
     </sect2>
 
     <sect2>
       <title>Miscellaneous</title>
       <para>All package information is stored within the 
         <filename>/var/db/pkg</filename> directory.  The installed
 	file list and descriptions of each package can be found within 
         files in this directory.
       </para>
     </sect2>
   </sect1>
   
   <sect1 id="ports-using">
     <title>Using the Ports Collection</title>
 
     <para>The following sections provide basic instructions on using the
       ports collection to install or remove programs from your
       system.</para>
 
     <sect2 id="ports-tree">
       <title>Obtaining the Ports Collection</title>
 
       <para>Before you can install ports, you must first obtain the
 	ports collection&mdash;which is essentially a set of Makefiles,
 	patches, and description files usually placed in
 	<filename>/usr/ports</filename>.
       </para>
 
       <para>When installing your FreeBSD system,
 	<application>Sysinstall</application> asked if you would like to
 	install the ports collection.  If you chose no, you can follow
 	these instructions to obtain the ports collection.</para>
 
       <procedure>
 	<title>Sysinstall Method</title>
 
 	<para>This method involves using
 	  <application>sysinstall</application> again to manually
 	  install the ports collection.</para>
 
 	<step>
 	  <para>As root, run <command>/stand/sysinstall</command> as
 	    shown below:</para>
 
 	  <screen>&prompt.root; /stand/sysinstall</screen>
 	</step>
 
 	<step>
 	  <para>Scroll down and select <literal>Configure</literal>,
 	    Press Enter</para>
 	</step>
 
 	<step>
 	  <para>Scroll down and select
 	    <literal>Distributions</literal>, Press Enter</para>
 	</step>
 
 	<step>
 	  <para>Scroll down to <literal>ports</literal>, Press the
 	    Space key</para>
 	</step>
 
 	<step>
 	  <para>Scroll up to <literal>Exit</literal>, Press
 	    Enter</para>
 	</step>
 
 	<step>
 	  <para>Select your desired installation media, such as CDROM,
 	    FTP, and so on.</para>
 	</step>
 
 	<step>
 	  <para>Follow the menus to Exit <application>sysinstall</application></para>
 	</step>
       </procedure>
 
       <para>The alternative method to obtain and keep your ports
 	collection up to date is by using
 	<application>CVSup</application>.  Look at the ports
 	<application>CVSup</application> file,
 	<filename>/usr/share/examples/cvsup/ports-supfile</filename>.
 	See <link linkend="cvsup">Using CVSup</link> (<xref
 	  linkend="cvsup">) for more information on using
 	<application>CVSup</application> and the mentioned file.</para>
 
       <procedure>
 	<title>CVSup Method</title>
 
 	<para>This is a quick method to getting the ports collection
 	  using <application>CVSup</application>.  If you want to keep
 	  your ports tree up to date, or learn more about
 	  <application>CVSup</application>, read the previously
 	  mentioned sections.</para>
 
 	<step>
 	  <para>Install the <filename role="package">net/cvsup</filename> port.  See <link
 	      linkend="cvsup-install">CVSup Installation</link> (<xref
 	      linkend="cvsup-install">) for more details.</para>
 	</step>
 
 	<step>
 	  <para>As root, copy
 	    <filename>/usr/share/examples/cvsup/ports-supfile</filename>
 	    to a new location, such as <filename>/root</filename> or your
 	      home directory</para>
 	</step>
 
 	<step>
 	  <para>Edit <filename>ports-supfile</filename></para>
 	</step>
 
 	<step>
 	  <para>Change <literal>CHANGE_THIS.FreeBSD.org</literal> to a
 	    <application>CVSup</application> near you.  See <link
 	      linkend="cvsup-mirrors">CVSupp Mirrors</link> (<xref
 	      linkend="cvsup-mirrors">) for a complete listing of mirror
 	    sites.</para>
 	</step>
 
 	<step>
 	  <para>Run <command>cvsup -g -L 2 &lt;path_to_supfile&gt;</command></para>
 
 	  <screen>&prompt.root; cvsup -g -L 2 /root/ports-supfile</screen>
 	</step>
 
 	<step>
 	  <para>Running this consequent times at later dates will
 	    download all the recent changes to your ports
 	    collection.</para>
 	</step>
       </procedure>
     </sect2>
 
     <sect2 id="ports-skeleton">
       <title>Installing Ports</title>
 
       <indexterm>
         <primary>ports</primary>
         <secondary>installing</secondary>
       </indexterm>
       <para>The first thing that should be explained
         when it comes to the ports collection is what is actually meant
 	by a <quote>skeleton</quote>.  In a nutshell, a port skeleton is a
 	minimal set of files that tell your FreeBSD system how to
         cleanly compile and install a program.  Each port skeleton includes:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>A <filename>Makefile</filename>.  The
 	    <filename>Makefile</filename> contains various statements that
 	    specify how the application should be compiled and where it
 	    should be installed on your system</para>
 	</listitem>
 
 	<listitem>
 	  <para>A <filename>distinfo</filename> file.  This file contains
 	    information about the files that must be downloaded to build the
 	    port, and checksums, to ensure that those files have not been
 	    corrupted during the download.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>A <filename>files</filename> directory.  This directory
 	    contains patches to make the program compile and install on
 	    your FreeBSD system.  Patches are basically small files that
 	    specify changes to particular files.  They are in plain text
 	    format, and basically say <quote>Remove line 10</quote> or
 	    <quote>Change line 26 to this ...</quote>.  Patches are also
 	    known as <quote>diffs</quote> because they are generated by the
 	    <application>diff</application> program.</para>
 
 	  <para>This directory may also contain other files used in building
 	    the port.</para>
 	</listitem>
 
 	<listitem>
 	  <para>A <filename>pkg-comment</filename> file.  This is a one-line
 	    description of the program.</para>
 	</listitem>
 
 	<listitem>
 	  <para>A <filename>pkg-descr</filename> file.  This is a more
 	    detailed, often multiple-line, description of the program.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>A <filename>pkg-plist</filename> file.  This is a list of all
 	    the files that will be installed by the port.  It also tells the
 	    ports system what files to remove upon deinstallation.</para>
 	</listitem>
       </itemizedlist>
 
       <para>Some ports have other files, such as
         <filename>pkg-message</filename>.  The ports system uses these
         files to handle special situations.  If you want more details
         on these files, and on ports in general, check out the <ulink
         url="../porters-handbook/index.html">FreeBSD Porter's
         Handbook</ulink>.</para>
 
       <para>Now that you have enough background information to know what
         the ports collection is used for, you are ready to install your
 	first port.  There are two ways this can be done, and each is
 	explained below.</para>
 
       <para>Before we get into that however, you will need to choose a
         port to install.  There are a few ways to do this, with the
 	easiest method being the <ulink
 	url="../../../../ports/index.html">ports listing on the FreeBSD
 	web site</ulink>.  You can browse through the ports listed there
 	or use the search function on the site.  Each port also includes
 	a description so you can read a bit about each port before
 	deciding to install it.</para>
 
       <para>Another method is to use the <command>whereis</command>
         command.  To use <command>whereis</command>, simply type
 	<quote><command>whereis &lt;program you want to
 	install&gt;</command></quote> at the prompt, and if it is found on
         your system, you will be told where it is, like so:</para>
 
       <screen>&prompt.root; <userinput>whereis lsof</userinput>
 lsof: /usr/ports/sysutils/lsof</screen>
 
       <para>This tells us that <command>lsof</command> (a system utility)
 	can be found in the
         <filename>/usr/ports/sysutils/lsof</filename> directory.</para>
 
       <para>Yet another way of finding a particular port is by using the
         ports collection's built-in search mechanism.  To use the search
         feature, you will need to be in the
 	<filename>/usr/ports</filename> directory.  Once in that
 	directory, run <command>make search name=program-name</command>
 	where <quote>program-name</quote> is the name of the program you
 	want to find.  For example, if you were looking for 
 	<command>lsof</command>:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make search name=lsof</userinput>
 Port:   lsof-4.56.4
 Path:   /usr/ports/sysutils/lsof
 Info:   Lists information about open files (similar to fstat(1))
 Maint:  obrien@FreeBSD.org
 Index:  sysutils
 B-deps: 
 R-deps: </screen>
 
       <para>The part of the output you want to pay particular attention
         to is the <quote>Path:</quote> line, since that tells you where to
 	find it.  The other information provided is not needed in order
 	to install the port directly, so it will not be covered
 	here.</para>
 
       <para>For more in-depth searching you can also use
        <command>make search key=string</command> where 
        <quote>string</quote> is some text to search for.  This searches 
        port names, comments, descriptions and dependencies and can be used 
        to find ports which relate to a particular subject if you don't 
        know the name of the program you are looking for.</para>
 
       <para>In both of these cases, the search string is case-insensitive.
        Searching for <quote>LSOF</quote> will yield the same results as 
        searching for <quote>lsof</quote>.</para>
 
       <note>
         <para>You must be the <username>root</username> user to install
           ports.</para>
       </note>
 
       <para>Now that you have found a port you would like to install,
         you are ready to do the actual installation.  The port
         includes instructions on how to build source code, but no
         actual source code.  You can get the source code from a CDROM
         or from the Internet.  Source code is distributed in whatever
         manner the software author desires.  Frequently this is a
         tarred and gzipped file, but it might be compressed with some
         other tool or even uncompressed.  The program source code,
         whatever form it comes in, is called a
         <quote>distfile</quote>.  You can get the distfile from a
         CDROM or from the Internet.</para>
 
       <sect3 id="ports-cd">
         <title>Installing Ports from a CDROM</title>
 
         <indexterm>
           <primary>ports</primary>
           <secondary>installing from CDROM</secondary>
         </indexterm>
         <para>The FreeBSD Project's official CDROM images no longer
 	  include distfiles.  They take up a lot of room that is
 	  better used by precompiled packages.  CDROM products such as
 	  the FreeBSD Power Pak do include distfiles, and you can
 	  order these sets from a vendor such as the <ulink
 	  url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>.
 	  This section assumes you have such a FreeBSD CDROM
 	  set.</para>
 
         <para>Place your FreeBSD CDROM in the drive.  Mount it on
 	  <filename>/cdrom</filename>.  (If you use a different mount
 	  point, the install will not work.)  To begin, change to the
 	  directory for the port you want to install:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen>
 
         <para>Once inside the <filename>lsof</filename> directory,
 	  you will see the port
 	  skeleton.  The next step is to compile (also called build) the
 	  port.  This is done by simply typing <command>make</command> at
 	  the prompt.  Once you have done so, you should see something
 	  like this:</para>
 
         <screen>&prompt.root; <userinput>make</userinput>
 &gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
 &gt;&gt; Attempting to fetch from file:/cdrom/ports/distfiles/.
 ===&gt;  Extracting for lsof-4.57
 ...
 [extraction output snipped]
 ...
 &gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
 ===&gt;  Patching for lsof-4.57
 ===&gt;  Applying FreeBSD patches for lsof-4.57
 ===&gt;  Configuring for lsof-4.57
 ...
 [configure output snipped]
 ...
 ===&gt;  Building for lsof-4.57
 ...
 [compilation snipped]
 ...
 &prompt.root;</screen>
 
         <para>Take notice that once the compile is complete you are
 	  returned to your prompt.  The next step is to install the
 	  port.  In order to install it, you simply need to tack one word
 	  onto the <command>make</command> command, and that word is
 	  <command>install</command>:</para>
 
         <screen>&prompt.root; <userinput>make install</userinput>
 ===&gt;  Installing for lsof-4.57
 ...
 [install routines snipped]
 ...
 ===&gt;   Generating temporary packing list
 ===&gt;   Compressing manual pages for lsof-4.57
 ===&gt;   Registering installation for lsof-4.57
 ===&gt;  SECURITY NOTE: 
       This port has installed the following binaries which execute with
       increased privileges.
 &prompt.root;</screen>
 
         <para>Once you are returned to your prompt, you should be able to
           run the application you just installed.  Since 
 	  <command>lsof</command> is a
 	  program that runs with increased privileges, a security
 	  warning is shown.  During the building and installation of
 	  ports, you should take heed of any other warnings that
 	  may appear.</para>
 
         <note>
           <para>You can save an extra step by just running <command>make
             install</command> instead of <command>make</command> and
 	    <command>make install</command> as two separate steps.</para>
 	</note>
 
         <note>
           <para>Please be aware that the licenses of a few ports do not
             allow for inclusion on the CDROM.  This could be because a
             registration form needs
 	    to be filled out before downloading, redistribution is not
 	    allowed, and so on.  If you wish to install a port not
 	    included on the CDROM, you will need to be online in order to
 	    do so (see the <link linkend="ports-inet">next
 	    section</link>).</para>
 	</note>
       </sect3>
 
       <sect3 id="ports-inet">
       <title>Installing Ports from the Internet</title>
 
         <para>As with the last section, this section makes an assumption
           that you have a working Internet connection.  If you do not,
 	  you will need to perform the <link linkend="ports-cd">CDROM
 	  installation</link>.</para>
 
         <para>Installing a port from the Internet is done exactly the same
 	  way as it would be if you were installing from a CDROM.  The
 	  only difference between the two is that the port distfile
 	  is downloaded from the Internet instead of pulled from the
 	  CDROM.</para>
 
         <para>The steps involved are identical:</para>
 
         <screen>&prompt.root; <userinput>make install</userinput>
 &gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
 &gt;&gt; Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.
 Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
 439860 bytes transferred in 18.0 seconds (23.90 kBps)
 ===&gt;  Extracting for lsof-4.57
 ...
 [extraction output snipped]
 ...
 &gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
 ===&gt;  Patching for lsof-4.57
 ===&gt;  Applying FreeBSD patches for lsof-4.57
 ===&gt;  Configuring for lsof-4.57
 ...
 [configure output snipped]
 ...
 ===&gt;  Building for lsof-4.57
 ...
 [compilation snipped]
 ...
 ===&gt;  Installing for lsof-4.57
 ...
 [install routines snipped]
 ...
 ===&gt;   Generating temporary packing list
 ===&gt;   Compressing manual pages for lsof-4.57
 ===&gt;   Registering installation for lsof-4.57
 ===&gt;  SECURITY NOTE: 
       This port has installed the following binaries which execute with
       increased privileges.
 &prompt.root;</screen>
 
         <para>As you can see, the only difference is the line that tells
 	  you where the system is fetching the port from.</para>
 
         <para>That about does it for installing ports onto your
 	  system.  In the next section you will learn how to remove a
 	  port from your system.</para>
       </sect3>
     </sect2>
 
     <sect2 id="ports-removing">
       <title>Removing Installed Ports</title>
 
       <indexterm>
         <primary>ports</primary>
         <secondary>removing</secondary>
       </indexterm>
       <para>Now that you know how to install ports, you are probably
         wondering how to remove them, just in case you install one and
 	later on you decide that you installed the wrong port.  
         We will remove our previous example (which was 
 	<command>lsof</command> for
         those of you not paying attention).  As with installing ports,
 	the first thing you must do is change to the port directory,
 	<filename>/usr/ports/sysutils/lsof</filename>.  After you change
 	directories, you are ready to uninstall <command>lsof</command>.
 	This is done with
 	the <command>make deinstall</command> command:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
 &prompt.root; <userinput>make deinstall</userinput>
 ===&gt;  Deinstalling for lsof-4.57</screen>
 
       <para>That was easy enough.  You have removed
 	<command>lsof</command>
         from your system.  If you would like to reinstall it, you can do
 	so by running <command>make reinstall</command> from the
         <filename>/usr/ports/sysutils/lsof</filename> directory.</para>
 
       <para>The <command>make deinstall</command> and <command>make
         reinstall</command> sequence does not work once you have run
         <command>make clean</command>.  If you want to deinstall a
         port after cleaning, use <command>pkg_delete</command> as
         discussed in the <link linkend="packages-using">Packages
         section of the Handbook</link>.</para>
     </sect2>
   </sect1>
 
   <sect1 id="ports-nextsteps">
     <title>Post-installation activities</title>
 
     <para>After installing a new application you will normally want to read
       any documentation it may have included, edit any configuration files
       that are required, ensure that the application starts at boot time (if
       it is a daemon), and so on.</para>
 
     <para>The exact steps you need to take to configure each application will
       obviously be different.  However, if you have just installed a new
       application and are wondering <quote>What now?</quote> these tips might
       help.</para>
 
     <itemizedlist>
       <listitem>
 	<para>Use &man.pkg.info.1; to find out which files were installed,
 	  and where they were installed to.  For example, if you have just
 	  installed FooPackage version 1.0.0, then this command</para>
 
 	<screen>&prompt.root; <userinput>pkg_info -L foopackage-1.0.0 | less</userinput></screen>
 
 	<para>will show all the files installed by the package.  Pay special
 	  attention to files in <filename>man/</filename> directories, which
 	  will be manual pages, <filename>etc/</filename> directories, which
 	  will be configuration files, and <filename>doc/</filename>, which will be
 	  more comprehensive documentation.</para>
 
 	<para>If you are not sure which version of the application was just
 	  installed, a command like this</para>
 
 	<screen>&prompt.root; <userinput>pkg_info | grep foopackage</userinput></screen>
 
 	<para>will find all the installed packages that have
 	  <literal>foopackage</literal> in the package name.  Replace
 	  <literal>foopackage</literal> in your commandline as
 	  necessary.</para>
       </listitem>
 
       <listitem>
 	<para>Once you have identified where the application's manual pages
 	  have been installed, review them using &man.man.1;.  Similarly, 
 	  look over the sample configuration files, and any additional 
 	  documentation that may have been provided.</para>
       </listitem>
 
       <listitem>
 	<para>If the application has a web site, check it for additional
 	  documentation, frequently asked question files, and so forth.  If
 	  you are not sure of the web site address it may be listed in the
 	  output from</para>
 
 	<screen>&prompt.root; <userinput>pkg_info foopackage-1.0.0</userinput></screen>
 	
 	<para>will often include a <literal>WWW:</literal> line with the URL
 	  of the application's web site.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="ports-trouble">
     <title>Troubleshooting</title>
 
     <para>The following sections cover some of the more frequently asked
       questions about the ports collection and some basic troubleshooting
       techniques, and what do to if a <link
       linkend="ports-broken">port is broken.</link></para>
 
     <sect2 id="ports-questions">
       <title>Some Questions and Answers</title>
 
       <qandaset>
         <qandaentry>
 	  <question>
 	  <para>I thought this was going to be a discussion about
 	    modems??!</para>
 	  </question>
 
 	  <answer>
 	  <para>Ah, you must be thinking of the serial ports on the back
 	    of your computer.  We are using <quote>port</quote> here to
 	    mean the result of <quote>porting</quote> a program from one
 	    version of Unix to another.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para id="ports-patch">What is a patch?</para>
 	  </question>
 
 	  <answer>
 	  <para>A patch is a small file that specifies how to go from
 	    one version of a file to another.  It contains plain text,
 	    and basically says things like <quote>delete line 23</quote>,
 	    <quote>add these two lines after line 468</quote>, or
 	    <quote>change line 197 to this</quote>.  They are also known
 	    as diffs because they are generated by the
 	    <application>diff</application> program.</para>
 	  </answer>
 	</qandaentry>
 
   <indexterm><primary>tarball</primary></indexterm>
 	<qandaentry>
 	  <question>
 	  <para id="ports-tarball">What is all this about
 	    tarballs?</para>
 	  </question>
 
 	  <answer>
 	  <para>It is a file ending in <filename>.tar</filename>, or
 	    with variations such as <filename>.tar.gz</filename>,
 	    <filename>.tar.Z</filename>, <filename>.tar.bz2</filename>,
 	    and even <filename>.tgz</filename>.</para>
 
 	  <para>Basically, it is a directory tree that has been archived
 	    into a single file (<filename>.tar</filename>) and
 	    optionally compressed (<filename>.gz</filename>).  This
 	    technique was originally used for <emphasis>T</emphasis>ape
 	    <emphasis>AR</emphasis>chives (hence the name
 	    <command>tar</command>), but it is a widely used way of
 	    distributing program source code around the Internet.</para>
 
 	  <para>You can see what files are in them, or even extract
             them yourself by using the standard Unix
 	    <command>tar</command> program, which comes with the base
 	    FreeBSD system, like this:</para>
 
 	  <screen>&prompt.user; <userinput>tar tvzf foobar.tar.gz</userinput>
 &prompt.user; <userinput>tar xzvf foobar.tar.gz</userinput>
 &prompt.user; <userinput>tar tvf foobar.tar</userinput>
 &prompt.user; <userinput>tar xvf foobar.tar</userinput></screen>
 	  </answer>
 	</qandaentry>
 
   <indexterm><primary>checksum</primary></indexterm>
 	<qandaentry>
 	  <question>
 	  <para id="ports-checksum">And a checksum?</para>
 	  </question>
 
 	  <answer>
 	  <para>It is a number generated by adding up all the data in
 	    the file you want to check.  If any of the characters
 	    change, the checksum will no longer be equal to the total,
 	    so a simple comparison will allow you to spot the
 	    difference.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I did what you said for compiling ports from a CDROM and
 	    it worked great until I tried to install the kermit
 	    port.</para>
 
 	  <screen>&prompt.root; <userinput>make install</userinput>
 &gt;&gt; cku190.tar.gz doesn't seem to exist on this system.
 &gt;&gt; Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.</screen>
 
 	  <para>Why can it not be found?  Have I got a dud CDROM?</para>
 	  </question>
 
 	  <answer>
 	  <para>As explained in the <link
 	    linkend="ports-cd">compiling ports from CDROM</link>
 	    section, some ports cannot be put on the CDROM set
 	    due to licensing restrictions.  Kermit is an example of
 	    that.  The licensing terms for kermit do not allow us to put
 	    the tarball for it on the CDROM, so you will have to fetch
 	    it by hand&mdash;sorry!</para>
 
 	  <para>The reason why you got all those error messages was
 	    because you were not connected to the Internet at the time.
 	    Once you have downloaded it from any of the MASTER_SITES
 	    (listed in the Makefile), you can restart the install
 	    process.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I did that, but when I tried to put it into
 	    <filename>/usr/ports/distfiles</filename> I got some error
 	    about not having permission.</para>
 	  </question>
 
 	  <answer>
 	  <para>The ports mechanism will download distribution
 	    tarballs into <filename>/usr/ports/distfiles</filename>,
 	    but many system administrators will symlink this directory
 	    to a remote file server or local read-only CDROM media.
 	    If this is the case, then you should specify a different
 	    directory to be used for storing distfiles with the
 	    following command:</para>
 
 	  <screen>&prompt.root; <userinput>make DISTDIR=<replaceable>/local/dir/with/write/permission</replaceable> install</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>Does the ports scheme only work if you have everything
 	    in <filename>/usr/ports</filename>?  My system administrator
 	    says I must put everything under
 	    <filename>/u/people/guests/wurzburger</filename>, but it
 	    does not seem to work.</para>
 	  </question>
 
 	  <answer>
 	  <para>You can use the <makevar>PORTSDIR</makevar> and
 	    <makevar>PREFIX</makevar> variables to tell the ports
 	    mechanism to use different directories.  For
 	    instance,</para>
 
 	  <screen>&prompt.root; <userinput>make PORTSDIR=/u/people/guests/wurzburger/ports install</userinput></screen>
 
 	  <para>will compile the port in
 	    <filename>/u/people/guests/wurzburger/ports</filename> and
 	    install everything under
 	    <filename>/usr/local</filename>.</para>
 
 	  <screen>&prompt.root; <userinput>make PREFIX=/u/people/guests/wurzburger/local install</userinput></screen>
 
 	  <para>will compile it in <filename>/usr/ports</filename> and
 	    install it in
 	    <filename>/u/people/guests/wurzburger/local</filename>.</para>
 
 	  <para>And of course,</para>
 
 	  <screen>&prompt.root; <userinput>make PORTSDIR=../ports PREFIX=../local install</userinput></screen>
 
 	  <para>will combine the two (it is too long to write fully on
 	    the page, but it should give you the general idea).</para>
 
 	  <indexterm><primary>imake</primary></indexterm>
 
 	  <para>Some ports that use &man.imake.1; (a part of the X Windows
 	  System) do not work well with <makevar>PREFIX</makevar>, and will insist on
 	  installing under <filename>/usr/X11R6</filename>.  Similarly, some Perl ports
 	  ignore <makevar>PREFIX</makevar> and install in the Perl tree.  Making these
 	  ports respect <makevar>PREFIX</makevar> is a difficult or impossible
 	  job.</para>
 
 	  <para>If you do not fancy typing all that in every time you
 	    install a port, it is a good idea to put these variables
 	    into your environment.  Read the manual page for your shell for
 	    instructions on doing so.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I do not have a FreeBSD CDROM, but I would like to have
 	    all the tarballs handy on my system so I do not have to wait
 	    for a download every time I install a port.  Is there any
 	    way to get them all at once?</para>
 	  </question>
 
 	  <answer>
 	  <para>To get every single tarball for the ports collection,
 	    do:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make fetch</userinput></screen>
 
 	  <para>For all the tarballs for a single ports directory,
 	    do:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
 &prompt.root; <userinput>make fetch</userinput></screen>
 
 	  <para>and for just one port&mdash;well, you have probably
 	    guessed already.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I know it is probably faster to fetch the tarballs from
 	    one of the FreeBSD mirror sites close by.  Is there any way
 	    to tell the port to fetch them from servers other than the
 	    ones listed in the MASTER_SITES?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes.  If you know, for example, that <hostid
 	    role="fqdn">ftp.FreeBSD.org</hostid> is much closer to you
 	    than the sites listed in <makevar>MASTER_SITES</makevar>,
 	    do as follows:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
 &prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I want to know what files <command>make</command> is
 	    going to need before it tries to pull them down.</para>
 	  </question>
 
 	  <answer>
 	  <para><command>make fetch-list</command> will display a list
 	    of the files needed for a port.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>Is there any way to stop the port from compiling?  I
 	    want to do some hacking on the source before I install it,
 	    but it is a bit tiresome to watch it and hit control-C every
 	    time.</para>
 	  </question>
 
 	  <answer>
             <para>Doing <command>make extract</command> will stop it
 	      after it has fetched and extracted the source code.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I am trying to make my own port and I want to be able
 	    to stop it compiling until I have had a chance to see if my
 	    patches worked properly.  Is there something like
 	    <command>make extract</command>, but for patches?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes, <command>make patch</command> is what you want.
 	    You will probably find the <makevar>PATCH_DEBUG</makevar>
 	    option useful as well.  And by the way, thank you for your
 	    efforts!</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I have heard that some compiler options can cause bugs.
 	    Is this true?  How can I make sure that I compile ports
 	    with the right settings?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes, with version 2.6.3 of <command>gcc</command> (the
 	    version shipped with FreeBSD 2.1.0 and 2.1.5), the
 	    <option>-O2</option> option could result in buggy code
 	    unless you used the <option>-fno-strength-reduce</option>
 	    option as well.  (Most of the ports do not use
 	    <option>-O2</option>).  You <emphasis>should</emphasis> be
 	    able to specify the compiler options used by something
 	    like:</para>
 
 	  <screen>&prompt.root; <userinput>make CFLAGS='-O2 -fno-strength-reduce' install</userinput></screen>
 
 	  <para>or by editing <filename>/etc/make.conf</filename>, but
 	    unfortunately not all ports respect this.  The surest way
 	    is to do <command>make configure</command>, then go into
 	    the source directory and inspect the Makefiles by hand, but
 	    this can get tedious if the source has lots of
 	    sub-directories, each with their own Makefiles.</para>
 
 	    <para>The default FreeBSD compiler options are quite conservative, 
 	      so if you have not changed them you should not have any
 	      problems.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>There are so many ports it is hard to find the one I
 	    want.  Is there a list anywhere of what ports are
 	    available?</para>
 	  </question>
 
 	  <answer>
 	  <para>Look in the <filename>INDEX</filename> file in
 	    <filename>/usr/ports</filename>.  If you would like to
 	    search the ports collection for a keyword, you can do that
 	    too.  For example, you can find ports relevant to the LISP
 	    programming language using:</para>
 
 	  <screen>&prompt.user; <userinput>cd /usr/ports</userinput>
 &prompt.user; <userinput>make search key=lisp</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I went to install the <literal>foo</literal> port but
 	    the system suddenly stopped compiling it and starting
 	    compiling the <literal>bar</literal> port.  What is going
 	    on?</para>
 	  </question>
 
 	  <answer>
 	  <para>The <literal>foo</literal> port needs something that is
 	    supplied with <literal>bar</literal> &mdash; for instance,
 	    if <literal>foo</literal> uses graphics,
 	    <literal>bar</literal> might have a library with useful
 	    graphics processing routines.  Or <literal>bar</literal>
 	    might be a tool that is needed to compile the
 	    <literal>foo</literal> port.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para id="ports-remove">  I installed the
 	    <literal>grizzle</literal> program from the ports and
 	    frankly it is a complete waste of disk space.  I want to
 	    delete it but I do not know where it put all the files.
 	    Any clues?</para>
 	  </question>
 
 	  <answer>
 	  <para>No problem, just type:</para>
 
 	  <screen>&prompt.root; <userinput>pkg_delete grizzle-6.5</userinput></screen>
 
 	  <para>Alternatively, you can type:</para>
 
 	  <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/grizzle</replaceable></userinput>
 &prompt.root; <userinput>make deinstall</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>Hang on a minute, you have to know the version number
 	    to use that command.  You do not seriously expect me to
 	    remember that, do you?</para>
 	  </question>
 
 	  <answer>
 	  <para>Not at all, you can find it out by doing:</para>
 
 	  <screen>&prompt.root; <userinput>pkg_info -I 'grizzle*'</userinput>
 Information for grizzle-6.5:
 grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
 arcade game.</screen>
 
 	  <para>The version number can also be found using the 
 	    <command>pkg_info</command> or by typing:
 	    <command>ls /var/db/pkg</command></para>
 
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>Talking of disk space, the ports directory seems to be
 	    taking up an awful lot of room.  Is it safe to go in there
 	    and delete things?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes, if you have installed the program and are fairly
 	    certain you will not need the source again, there is no
 	    point in keeping it hanging around.  The surest way to do
 	    this is:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make clean</userinput></screen>
 
 	  <para>which will go through all the ports subdirectories and
 	    delete everything except the skeletons for each
 	    port.</para>
 
 	  <tip><para>It is possible to achieve the same effect without
 		recursively calling each makefile.  For example, you
 		can delete all of the work subdirectories directly
 		with the following command:
 	    <screen>&prompt.root; <userinput>find /usr/ports -depth -name work -exec rm -rf {} \;</userinput></screen></para>
 	    </tip>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I tried that and it still left all those tarballs or
 	    whatever you called them in the
 	    <filename>distfiles</filename> directory.  Can I delete
 	    those as well?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes, if you are sure you have finished with them,
 	     those can go as well.  They can be removed manually, or by
 	     using <command>make distclean</command>.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I like having lots and lots of programs to play with.
 	    Is there any way of installing all the ports in one
 	    go?</para>
 	  </question>
 
 	  <answer>
 	  <para>Just do:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make install</userinput></screen>
 
 	    <para>Be careful, as some ports may install files with the same
 	      name.  If you install two graphics ports and they both install
 	      <filename>/usr/local/bin/plot</filename> then you will obviously 
 	      have problems.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>OK, I tried that, but I thought it would take a very
 	    long time so I went to bed and left it to get on with it.
 	    When I looked at the computer this morning, it had only
 	    done three and a half ports.  Did something go
 	    wrong?</para>
 	  </question>
 
 	  <answer>
 	  <para>No, the problem is that some of the ports need to ask
 	    you questions that we cannot answer for you (e.g., <quote>Do
 	    you want to print on A4 or US letter sized paper?</quote>)
 	    and they need to have someone on hand to answer
 	    them.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I really do not want to spend all day staring at the
 	    monitor.  Any better ideas?</para>
 	  </question>
 
 	  <answer>
 	  <para>OK, do this before you go to bed/work/the local
 	    park:</para>
 
-	  <screen>&prompt.root <userinput>cd /usr/ports</userinput>
+	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make -DBATCH install</userinput></screen>
 
 	  <para>This will install every port that does
 	    <emphasis>not</emphasis> require user input.  Then, when
 	    you come back, do:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make -DINTERACTIVE install</userinput></screen>
 
 	  <para>to finish the job.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>At work, we are using <literal>frobble</literal>, which
 	    is in your ports collection, but we have altered it quite a
 	    bit to get it to do what we need.  Is there any way of making
 	    our own packages, so we can distribute it more easily around
 	    our sites?</para>
 	  </question>
 
 	  <answer>
 	  <para>No problem, assuming you know how to make patches for
 	    your changes:</para>
 
 	  <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/frobble</replaceable></userinput>
 &prompt.root; <userinput>make extract</userinput>
 &prompt.root; <userinput>cd work/frobble-2.8</userinput>
 [Apply your patches]
 &prompt.root; <userinput>cd ../..</userinput>
 &prompt.root; <userinput>make package</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>This ports stuff is really clever.  I am desperate to
 	    find out how you did it.  What is the secret?</para>
 	  </question>
 
 	  <answer>
 	  <para>Nothing secret about it at all, just look at the
 	    <filename>bsd.port.mk</filename> and
 	    <filename>bsd.port.subdir.mk</filename> files in
 	    <filename>/usr/ports/Mk/</filename>.</para>
 
 	  <para>(Readers with an aversion to intricate shell-scripts are
 	    advised not to look at the files in this directory.)</para>
 	  </answer>
 	</qandaentry>
       </qandaset>
     </sect2>
 
     <sect2 id="ports-broken">
       <title>Help!  This Port Is Broken!</title>
 
       <para>If you come across a port that does not work for you, there are
         a few things you can do, including:</para>
 
       <orderedlist>
         <listitem>
 	  <para>Fix it!  The <ulink
 	    url="../porters-handbook/index.html">Porter's
 	    Handbook</ulink> includes detailed information on the
 	    "Ports" infrastructure so that you can fix the occasional
 	    broken port or even submit your own!</para>
 	</listitem>
 
 	<listitem>
 	  <para>Gripe&mdash;<emphasis>by email only!</emphasis>  Send
 	    email to the maintainer of the port first.  Type <command>make
 	    maintainer</command> or read the <filename>Makefile</filename>
 	    to find the maintainer's email address.  Remember to include
 	    the name and version of the port (send the
 	    <literal>&dollar;FreeBSD:</literal> line from the
 	    <filename>Makefile</filename>) and the output leading up to the
 	    error when you email the maintainer.  If you do not get a
 	    response from the maintainer, you can use
 	    <command>send-pr</command> to submit a bug report.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Grab the package from an ftp site near you.  The
 	    <quote>master</quote> package collection is on <hostid
 	    role="fqdn">ftp.FreeBSD.org</hostid> in the <ulink
 	    URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages
 	    directory</ulink>, but be sure to check your local mirror
 	    <emphasis>first!</emphasis>  These are more likely to work
 	    than trying to compile from source and are a lot faster as
 	    well.  Use the &man.pkg.add.1; program to install the package
 	    on your system.</para>
 	</listitem>
       </orderedlist>
     </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/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
index 73d357412f..216787df60 100644
--- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
@@ -1,3491 +1,3491 @@
 <!--
      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>
     <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 FreeBSD.  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>FreeBSD 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 FreeBSD.</para>
       </listitem>
 
       <listitem>
 	<para>About the various crypt mechanisms available in FreeBSD,
 	  such as DES and MD5.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup S/Key, an alternative, one-time password
 	  authentication system.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup Kerberos, another alternative
 	  authentication system.</para>
       </listitem>
 
       <listitem>
 	<para>How to create firewalls using IPFW.</para>
       </listitem>
 
       <listitem>
 	<para>How to configure IPSec.</para>
       </listitem>
      
       <listitem>
 	<para>How to configure and use OpenSSH, FreeBSD's SSH
 	  implementation.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Understand basic FreeBSD and Internet concepts.</para>
       </listitem>
     </itemizedlist>
 
   </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 &ndash; 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
       internetworked, 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> flags (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; root-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
 	  filesystems.</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>
 
   <indexterm>
     <primary>security</primary>
     <secondary>securing</secondary>
   </indexterm>
 
   <sect1 id="securing-freebsd">
     <title>Securing FreeBSD</title>
 
     <note>
       <title>Command vs. Protocol</title>
       <para>Throughout this document, we will use
        <application>bold</application> text to refer to a command or
        application. This is used 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
       FreeBSD 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 pty's are specified as being unsecure 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 &ndash;
         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 wheel 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>
 
       <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 crypted
         password for the staff accounts. Using the &man.vipw.8;
         command, one can replace each instance of a crypted 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 setup.  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>Kerberos</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 effect 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>FreeBSD 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 crypted password file, potentially compromising
 	any passworded account.  Alternatively an intruder who breaks
 	group <literal>kmem</literal> can monitor keystrokes sent through
 	pty's, including pty's 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 crypted
 	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
 	Filesystems</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 FreeBSD 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
 	<devicename>/dev/mem</devicename> and 
 	<devicename>/dev/kmem</devicename>
 	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 &ndash; 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 &ndash; 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 &ndash; allowing you to monitor the
 	filesystems 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
 	unsecure 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 &ndash; 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 effect
 	convenience, and can add security features that
 	<emphasis>do</emphasis> effect convenience with some added thought.
 	Even more importantly, a security administrator should mix it up a
 	bit &ndash; 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,
 	which can be attacked directly.  You generally do not want to use
 	the reverse-ident feature of
 	<application>tcpwrappers</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
 	&ndash; 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 FreeBSD
 	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
 	&ndash; 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 FreeBSD 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>Kerberos</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 unsecure machine, your keys
 	becomes exposed.  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
 	unsecure 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 exposable
 	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, FreeBSD 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 FreeBSD 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 FreeBSD 4.4 <filename>libcrypt.a</filename> was a
 	symbolic link pointing to the library which was used for
 	encryption.  FreeBSD 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 FreeBSD uses MD5 to encrypt
 	passwords.</para>
 
       <para>It is pretty easy to identify which encryption method 
 	FreeBSD 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;2&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 <quote>passwd_format</quote> login capability in
 	<filename>/etc/login.conf</filename>, which takes values of
 	<quote>des</quote> or <quote>md5</quote> or
 	<quote>blf</quote>.  See the &man.login.conf.5; manual page
 	for more information about login capabilities.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="skey">
     <title>S/Key</title>
     <indexterm><primary>S/Key</primary></indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>S/Key</secondary>
     </indexterm>
 
     <para>S/Key is a one-time password scheme based on a one-way hash
       function.  FreeBSD uses the MD4 hash for compatibility but other
       systems have used MD5 and DES-MAC.  S/Key has been part of the
       FreeBSD 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 FreeBSD, S/Key has been replaced with
       the functionally equivalent OPIE (Onetime Passwords In
       Everything). OPIE uses the MD5 hash by default.</para>
 
     <para>There are three different sorts of passwords which we will talk
       about in the discussion 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
       <command>opiekey</command> program and accepted by the
       <command>keyinit</command> or <command>opiepasswd</command> 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 Unix
       passwords, 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 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 ssh), 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> command to
 	generate a number of one-time passwords before hand 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>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>Restrictions can be placed 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 FreeBSD default), 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 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 uneducable.</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>
     </sect2>
   </sect1>
 
   <sect1 id="kerberos">
     <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>Kerberos</title>
     <indexterm><primary>Kerberos</primary></indexterm>
     
     <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 FreeBSD.  However, you should refer to the
       relevant manual pages for a complete description.</para>
 
     <sect2>
       <title>Installing Kerberos</title>
 
       <indexterm><primary>MIT</primary></indexterm>
       <indexterm>
 	<primary>Kerberos</primary>
 	<secondary>installing</secondary>
       </indexterm>
       <para>Kerberos is an optional component of FreeBSD.  The easiest
         way to install this software is by selecting the 'krb4' or
         'krb5' distribution in <application>sysinstall</application>
         during the initial installation of FreeBSD.  This will install
         the 'eBones' (KerberosIV) or 'Heimdal' (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 <filename>EXAMPLE.COM</filename> 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 <filename>EXAMPLE.COM</filename> realm and also add an entry to
 	put all hosts in the <hostid role="domainname">.example.com</hostid>
 	domain in the <filename>EXAMPLE.COM</filename> 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>
 	  
       <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, <command>kpasswd</command> and
 	<command>rcmd</command> allow other systems to change Kerberos
 	passwords and run commands like <command>rcp</command>,
 	<command>rlogin</command> and <command>rsh</command>.</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 <command>mv</command> 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 automagically 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 <command>passwd</command> 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> <command>su</command> password.
 	We could now add an id which is authorized to
 	<command>su</command> 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 <command>su</command>:</para>
 	  
       <screen>&prompt.user; <prompt>su</prompt>
 <prompt>Password:</prompt></screen>
 	  
       <para>and take a look at what tokens we have:</para>
 	  
       <screen>&prompt.root; klist
 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 <command>su</command> 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 <filename>EXAMPLE.COM</filename> realm
 	who has authenticated themselves to <username>jane</username> or
 	<username>jack</username> (via <command>kinit</command>, see above)
 	access to <command>rlogin</command> to <username>jane</username>'s
 	account or files on this system (<hostid>grunt</hostid>) via
 	<command>rlogin</command>, <command>rsh</command> or
 	<command>rcp</command>.</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 Jack logs into Jane'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="firewalls">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Gary</firstname>
 	  <surname>Palmer</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<author>
 	  <firstname>Alex</firstname>
 	  <surname>Nash</surname>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title>Firewalls</title>
     <indexterm><primary>firewall</primary></indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>firewalls</secondary>
     </indexterm>
 
     <para>Firewalls are an area of increasing interest for people who are
       connected to the Internet, and are even finding applications on private
       networks to provide enhanced security.  This section will hopefully
       explain what firewalls are, how to use them, and how to use the
       facilities provided in the FreeBSD kernel to implement them.</para>
 
     <note>
       <para>People often think that having a firewall between your
 	internal network and the <quote>Big Bad Internet</quote> will solve all
 	your security problems.  It may help, but a poorly setup firewall
 	system is more of a security risk than not having one at all.  A
 	firewall can add another layer of security to your systems, but it
 	cannot stop a really determined cracker from penetrating your internal
 	network.  If you let internal security lapse because you believe your
 	firewall to be impenetrable, you have just made the crackers job that
 	much easier.</para>
     </note>
 
     <sect2>
       <title>What Is a Firewall?</title>
       
       <para>There are currently two distinct types of firewalls in common use
 	on the Internet today.  The first type is more properly called a
 	<emphasis>packet filtering router</emphasis>, where the kernel on a
 	multi-homed machine chooses whether to forward or block packets based
 	on a set of rules.  The second type, known as a <emphasis>proxy
 	  server</emphasis>, relies on daemons to provide authentication and to
 	forward packets, possibly on a multi-homed machine which has kernel
 	packet forwarding disabled.</para>
 	  
       <para>Sometimes sites combine the two types of firewalls, so that only a
 	certain machine (known as a <emphasis>bastion host</emphasis>) is
 	allowed to send packets through a packet filtering router onto an
 	internal network.  Proxy services are run on the bastion host, which
 	are generally more secure than normal authentication
 	mechanisms.</para>
 	  
       <para>FreeBSD comes with a kernel packet filter (known as
 	IPFW), which is what the rest of this
 	section will concentrate on.  Proxy servers can be built on FreeBSD
 	from third party software, but there is such a variety of proxy
 	servers available that it would be impossible to cover them in this
 	section.</para>
 	  
       <sect3 id="firewalls-packet-filters">
 	<title>Packet Filtering Routers</title>
 
 	<para>A router is a machine which forwards packets between two or more
 	  networks.  A packet filtering router has an extra piece of code in
 	  its kernel which compares each packet to a list of rules before
 	  deciding if it should be forwarded or not.  Most modern IP routing
 	  software has packet filtering code within it that defaults to
 	  forwarding all packets.  To enable the filters, you need to define a
 	  set of rules for the filtering code so it can decide if the
 	  packet should be allowed to pass or not.</para>
 	    
 	<para>To decide whether a packet should be passed on, the code looks
 	  through its set of rules for a rule which matches the contents of
 	  this packets headers.  Once a match is found, the rule action is
 	  obeyed.  The rule action could be to drop the packet, to forward the
 	  packet, or even to send an ICMP message back to the originator.
 	  Only the first match counts, as the rules are searched in order.
 	  Hence, the list of rules can be referred to as a <quote>rule
 	  chain</quote>.</para>
 	    
 	<para>The packet matching criteria varies depending on the software
 	  used, but typically you can specify rules which depend on the source
 	  IP address of the packet, the destination IP address, the source
 	  port number, the destination port number (for protocols which
 	  support ports), or even the packet type (UDP, TCP, ICMP,
 	  etc).</para>
       </sect3>
 	  
       <sect3 id="firewalls-proxy-servers">
 	<title>Proxy Servers</title>
 	    
 	<para>Proxy servers are machines which have had the normal system
 	  daemons (<application>telnetd</application>, 
 	  <application>ftpd</application>, etc) replaced with special servers.
 	  These
 	  servers are called <emphasis>proxy servers</emphasis> as they
 	  normally only allow onward connections to be made.  This enables you
 	  to run (for example) a proxy telnet server on your firewall host,
 	  and people can telnet in to your firewall from the outside, go
 	  through some authentication mechanism, and then gain access to the
 	  internal network (alternatively, proxy servers can be used for
 	  signals coming from the internal network and heading out).</para>
 	    
 	<para>Proxy servers are normally more secure than normal servers, and
 	  often have a wider variety of authentication mechanisms available,
 	  including <quote>one-shot</quote> password systems so that even if
 	  someone manages to discover what password you used, they will not be
 	  able to use it to gain access to your systems as the password
 	  instantly expires.  As they do not actually give users access to the
 	  host machine, it becomes a lot more difficult for someone to install
 	  backdoors around your security system.</para>
 	    
 	<para>Proxy servers often have ways of restricting access further, so
 	  that only certain hosts can gain access to the servers, and often
 	  they can be set up so that you can limit which users can talk to
 	  which destination machine.  Again, what facilities are available
 	  depends largely on what proxy software you choose.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>What Does IPFW Allow Me to Do?</title>
       <indexterm><primary><command>ipfw</command></primary></indexterm>
       
       <para>IPFW, the software supplied with
 	FreeBSD, is a packet filtering and accounting system which resides in
 	the kernel, and has a user-land control utility,
 	    &man.ipfw.8;.  Together, they allow you to define and query the
 	rules currently used by the kernel in its routing decisions.</para>
 	  
       <para>There are two related parts to IPFW.
 	The firewall section allows you to perform packet filtering.  There is
 	also an IP accounting section which allows you to track usage of your
 	router, based on similar rules to the firewall section.  This allows
 	you to see (for example) how much traffic your router is getting from
 	a certain machine, or how much WWW (World Wide Web) traffic it is
 	forwarding.</para>
 	  
       <para>As a result of the way that IPFW is
 	designed, you can use IPFW on non-router
 	machines to perform packet filtering on incoming and outgoing
 	connections.  This is a special case of the more general use of
 	IPFW, and the same commands and techniques
 	should be used in this situation.</para>
     </sect2>
 
     <sect2>
       <title>Enabling IPFW on FreeBSD</title>
       <indexterm>
         <primary><command>ipfw</command></primary>
         <secondary>enabling</secondary>
       </indexterm>
       
       <para>As the main part of the IPFW system
 	lives in the kernel, you will need to add one or more options to your
 	kernel configuration file, depending on what facilities you want, and
 	recompile your kernel.  See "Reconfiguring your Kernel" (<xref
 	linkend="kernelconfig">)
 	for more details on how to recompile your
 	kernel.</para>
       
       <para>There are currently three kernel configuration options relevant to
 	IPFW:</para>
 	  
       <variablelist>
 	<varlistentry>
 	  <term><literal>options IPFIREWALL</literal></term>
 
 	  <listitem>
 	    <para>Compiles into the kernel the code for packet
 	      filtering.</para>
 	  </listitem>
 	</varlistentry>
 	      
 	<varlistentry>
 	  <term><literal>options IPFIREWALL_VERBOSE</literal></term>
 		
 	  <listitem>
 	    <para>Enables code to allow logging of packets through
 		&man.syslogd.8;.  Without this option, even if you specify
 	      that packets should be logged in the filter rules, nothing will
 	      happen.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>options IPFIREWALL_VERBOSE_LIMIT=10</literal></term>
 		
 	  <listitem>
 	    <para>Limits the number of packets logged through
 		&man.syslogd.8; on a per entry basis.  You may wish to use
 	      this option in hostile environments in which you want to log
 	      firewall activity, but do not want to be open to a denial of
 	      service attack via syslog flooding.</para>
 
 	    <para>When a chain entry reaches the packet limit specified,
 	      logging is turned off for that particular entry.  To resume
 	      logging, you will need to reset the associated counter using the
 		&man.ipfw.8; utility:</para>
 	    
 	    <screen>&prompt.root; <userinput>ipfw zero 4500</userinput></screen>
 	    <para>Where 4500 is the chain entry you wish to continue
 	      logging.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <note><para>Previous versions of FreeBSD contained an
 	<literal>IPFIREWALL_ACCT</literal>  option.  This is now obsolete as
 	the firewall code automatically  includes accounting
 	facilities.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Configuring IPFW</title>
       <indexterm>
         <primary><command>ipfw</command></primary>
         <secondary>configuring</secondary>
       </indexterm>
       
       <para>The configuration of the IPFW software
 	is done through the &man.ipfw.8; utility.  The syntax for this
 	command looks quite complicated, but it is relatively simple once you
 	understand its structure.</para>
 
       <para>There are currently four different command categories used by the
 	utility: addition/deletion, listing, flushing, and clearing.
 	Addition/deletion is used to build the rules that control how packets
 	are accepted, rejected, and logged.  Listing is used to examine the
 	contents of your rule set (otherwise known as the chain) and packet
 	counters (accounting).  Flushing is used to remove all entries from
 	the chain.  Clearing is used to zero out one or more accounting
 	entries.</para>
 	  
       <sect3>
 	<title>Altering the IPFW Rules</title>
 
 	<para>The syntax for this form of the command is:
 	  <cmdsynopsis>
 	    <command>ipfw</command>
 	    <arg>-N</arg>
 	    <arg choice="plain">command</arg>
 	    <arg>index</arg>
 	    <arg choice="plain">action</arg>
 	    <arg>log</arg>
 	    <arg choice="plain">protocol</arg>
 	    <arg choice="plain">addresses</arg>
 	    <arg>options</arg>
 	  </cmdsynopsis></para>
 
 	<para>There is one valid flag when using this form of the
 	  command:</para>
 
 	<variablelist>
 	  <varlistentry>
 	    <term>-N</term>
 
 	    <listitem>
 	      <para>Resolve addresses and service names in output.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
 	<para>The <emphasis>command</emphasis> given can be shortened to the
 	  shortest unique form.  The valid <emphasis>commands</emphasis>
 	  are:</para>
 	    
 	<variablelist>
 	  <varlistentry>
 	    <term>add</term>
 
 	    <listitem>
 	      <para>Add an entry to the firewall/accounting rule list</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>delete</term>
 	    
 	    <listitem>
 	      <para>Delete an entry from the firewall/accounting rule
 		list</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
 	<para>Previous versions of IPFW used
 	  separate firewall and accounting entries.  The present version
 	  provides packet accounting with each firewall entry.</para>
 	    
 	<para>If an <emphasis>index</emphasis> value is supplied, it is used to
 	  place the entry at a specific point in the chain. Otherwise, the
 	  entry is placed at the end of the chain at an index 100 greater than
 	  the last chain entry (this does not include the default policy, rule
 	  65535, deny).</para>
 	    
 	<para>The <literal>log</literal> option causes matching rules to be
 	  output to the system console if the kernel was compiled with
 	  <literal>IPFIREWALL_VERBOSE</literal>.</para>
 	    
 	<para>Valid <emphasis>actions</emphasis> are:</para>
 	    
 	<variablelist>
 	  <varlistentry>
 	    <term>reject</term>
 
 	    <listitem>
 	      <para>Drop the packet, and send an ICMP host or port unreachable
 		(as appropriate) packet to the source.</para>
 	    </listitem>
 	  </varlistentry>
 		
 	  <varlistentry>
 	    <term>allow</term>
 	    
 	    <listitem>
 	      <para>Pass the packet on as normal.  (aliases:
 		<literal>pass</literal> and
 		<literal>accept</literal>)</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>deny</term>
 	    
 	    <listitem>
 	      <para>Drop the packet.  The source is not notified via an
 		ICMP message (thus it appears that the packet never
 		arrived at the destination).</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>count</term>
 	    
 	    <listitem>
 	      <para>Update packet counters but do not allow/deny the packet
 		based on this rule.  The search continues with the next chain
 		entry.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
 	<para>Each <emphasis>action</emphasis> will be recognized by the
 	  shortest unambiguous prefix.</para>
 	    
 	<para>The <emphasis>protocols</emphasis> which can be specified
 	  are:</para>
 	    
 	<variablelist>
 	  <varlistentry>
 	    <term>all</term>
 
 	    <listitem>
 	      <para>Matches any IP packet</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>icmp</term>
 	    
 	    <listitem>
 	      <para>Matches ICMP packets</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>tcp</term>
 	    
 	    <listitem>
 	      <para>Matches TCP packets</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>udp</term>
 	    
 	    <listitem>
 	      <para>Matches UDP packets</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
 	<para>The <emphasis>address</emphasis> specification is:</para>
 
 	<cmdsynopsis>
 	  <arg choice="plain">from</arg>
 	  <arg choice="plain"><replaceable>address/mask</replaceable></arg><arg><replaceable>port</replaceable></arg>
 	  <arg choice="plain">to</arg>
 	  <arg choice="plain"><replaceable>address/mask</replaceable></arg><arg><replaceable>port</replaceable></arg>
 	  <arg>via <replaceable>interface</replaceable></arg>
 	</cmdsynopsis>
 	    
 	<para>You can only specify <replaceable>port</replaceable> in
 	  conjunction with <emphasis>protocols</emphasis> which support ports
 	  (UDP and TCP).</para>
 	    
 	<para>The <option>via</option> is optional and may specify the IP
 	  address or domain name of a local IP interface, or an interface name
 	  (e.g.  <devicename>ed0</devicename>) to match only packets coming
 	  through this interface.  Interface unit numbers can be specified
 	  with an optional wildcard.  For example, <literal>ppp*</literal>
 	  would match all kernel PPP interfaces.</para>
 	    
 	<para>The syntax used to specify an
 	  <replaceable>address/mask</replaceable> is:
 	  
 	  <screen><replaceable>address</replaceable></screen>
 	      
 	  or
 	      
 	  <screen><replaceable>address</replaceable>/<replaceable>mask-bits</replaceable></screen>
 	      
 	  or
 	      
 	  <screen><replaceable>address</replaceable>:<replaceable>mask-pattern</replaceable></screen>
 	</para>
 
 	<para>A valid hostname may be specified in place of the IP address.
 	  <option><replaceable>mask-bits</replaceable></option> is a decimal
 	  number representing how many bits in the address mask should be set.
 	  e.g.  specifying <literal>192.216.222.1/24</literal> will create a
 	  mask which will allow any address in a class C subnet (in this case,
 	  192.216.222) to be matched.
 	  <option><replaceable>mask-pattern</replaceable></option> is an IP
 	  address which will be logically AND'ed with the address given. The
 	  keyword <literal>any</literal> may be used to specify <quote>any IP
 	  address</quote>.</para>
 	    
 	<para>The port numbers to be blocked are specified as:
 	  
 	  <cmdsynopsis>
 	    <arg choice="plain"><replaceable>port</replaceable><arg>,<replaceable>port</replaceable><arg>,<replaceable>port</replaceable><arg>&hellip;</arg></arg></arg></arg>
 	  </cmdsynopsis>
 
 	  to specify either a single port or a list of ports, or
 	  
 	  <cmdsynopsis>
 	    <arg choice="plain"><replaceable>port</replaceable>-<replaceable>port</replaceable></arg>
 	  </cmdsynopsis>
 
 	  to specify a range of ports.  You may also combine a single range
 	  with a list, but the range must always be specified first.</para>
 	    
 	<para>The <emphasis>options</emphasis> available are:</para>
 
 	<variablelist>
 	  <varlistentry>
 	    <term>frag</term>
 
 	    <listitem>
 	      <para>Matches if the packet is not the first fragment of the
 		datagram.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>in</term>
 	    
 	    <listitem>
 	      <para>Matches if the packet is on the way in.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>out</term>
 	    
 	    <listitem>
 	      <para>Matches if the packet is on the way out.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>ipoptions <replaceable>spec</replaceable></term>
 	    
 	    <listitem>
 	      <para>Matches if the IP header contains the comma separated list
 		of options specified in <replaceable>spec</replaceable>.  The
 		supported list of IP options are: <literal>ssrr</literal>
 		(strict source route), <literal>lsrr</literal> (loose source
 		route), <literal>rr</literal> (record packet route), and
 		<literal>ts</literal> (time stamp).  The absence of a
 		particular option may be denoted with a leading
 		<literal>!</literal>.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>established</term>
 	    
 	    <listitem>
 	      <para>Matches if the packet is part of an already established
 		TCP connection (i.e. it has the RST or ACK bits set).  You can
 		optimize the performance of the firewall by placing
 		<emphasis>established</emphasis> rules early in the
 		chain.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>setup</term>
 	    
 	    <listitem>
 	      <para>Matches if the packet is an attempt to establish a TCP
 		connection (the SYN bit is set but the ACK bit is
 		not).</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>tcpflags <replaceable>flags</replaceable></term>
 	    
 	    <listitem>
 	      <para>Matches if the TCP header contains the comma separated
 		list of <replaceable>flags</replaceable>.  The supported flags
 		are <literal>fin</literal>, <literal>syn</literal>,
 		<literal>rst</literal>, <literal>psh</literal>,
 		<literal>ack</literal>, and <literal>urg</literal>.  The
 		absence of a particular flag may be indicated by a leading
 		<literal>!</literal>.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>icmptypes <replaceable>types</replaceable></term>
 	    
 	    <listitem>
 	      <para>Matches if the ICMP type is present in the list
 		<replaceable>types</replaceable>.  The list may be specified
 		as any combination of ranges and/or individual types separated
 		by commas.  Commonly used ICMP types are: <literal>0</literal>
 		echo reply (ping reply), <literal>3</literal> destination
 		unreachable, <literal>5</literal> redirect,
 		<literal>8</literal> echo request (ping request), and
 		<literal>11</literal> time exceeded (used to indicate TTL
 		expiration as with &man.traceroute.8;).</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
       </sect3>
       
       <sect3>
 	<title>Listing the IPFW Rules</title>
 
 	<para>The syntax for this form of the command is:
 	  <cmdsynopsis>
 	    <command>ipfw</command>
 	    <arg>-a</arg>
 	    <arg>-t</arg>
 	    <arg>-N</arg>
 	    <arg choice="plain">l</arg>
 	  </cmdsynopsis></para>
 
 	<para>There are three valid flags when using this form of the
 	  command:</para>
 	    
 	<variablelist>
 	  <varlistentry>
 	    <term>-a</term>
 
 	    <listitem>
 	      <para>While listing, show counter values.  This option is the
 		only way to see accounting counters.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-t</term>
 	    
 	    <listitem>
 	      <para>Display the last match times for each chain entry. The
 		time listing is incompatible with the input syntax used by the
 		  &man.ipfw.8; utility.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-N</term>
 	    
 	    <listitem>
 	      <para>Attempt to resolve given addresses and service
 		names.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
       </sect3>
       
       <sect3>
 	<title>Flushing the IPFW Rules</title>
 
 	<para>The syntax for flushing the chain is:
 	  <cmdsynopsis>
 	    <command>ipfw</command>
 	    <arg choice="plain">flush</arg>
 	  </cmdsynopsis></para>
 
 	<para>This causes all entries in the firewall chain to be removed
 	  except the fixed default policy enforced by the kernel (index
 	  65535).  Use caution when flushing rules, the default deny policy
 	  will leave your system cut off from the network until allow entries
 	  are added to the chain.</para>
       </sect3>
       
       <sect3>
 	<title>Clearing the IPFW Packet Counters</title>
 
 	<para>The syntax for clearing one or more packet counters is:
 	  <cmdsynopsis>
 	    <command>ipfw</command>
 	    <arg choice="plain">zero</arg>
 	    <arg choice="opt"><replaceable>index</replaceable></arg>
 	  </cmdsynopsis></para>
 
 	<para>When used without an <replaceable>index</replaceable> argument,
 	  all packet counters are cleared.  If an
 	  <replaceable>index</replaceable> is supplied, the clearing operation
 	  only affects a specific chain entry.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Example Commands for <application>ipfw</application></title>
       
       <para>This command will deny all packets from the host <hostid
 	  role="fqdn">evil.crackers.org</hostid> to the telnet port of the
 	host <hostid role="fqdn">nice.people.org</hostid>:</para>
 	  	  
-      <screen>&prompt.root <userinput>ipfw add deny tcp from evil.crackers.org to nice.people.org 23</userinput></screen>
+      <screen>&prompt.root; <userinput>ipfw add deny tcp from evil.crackers.org to nice.people.org 23</userinput></screen>
 	  
       <para>The next example denies and logs any TCP traffic from the entire
 	<hostid role="domainname">crackers.org</hostid> network (a class C) to
 	the <hostid role="fqdn">nice.people.org</hostid> machine (any
 	port).</para>
 	  
       <screen>&prompt.root; <userinput>ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org</userinput></screen>
 	  
       <para>If you do not want people sending X sessions to your internal
 	network (a subnet of a class C), the following command will do the
 	necessary filtering:</para>
 	  
       <screen>&prompt.root; <userinput>ipfw add deny tcp from any to my.org/28 6000 setup</userinput></screen>
 	  
       <para>To see the accounting records:
 	    
 	<screen>&prompt.root; <userinput>ipfw -a list</userinput></screen>
 
 	or in the short form
 	    
 	<screen>&prompt.root; <userinput>ipfw -a l</userinput></screen>
       </para>
 
       <para>You can also see the last time a chain entry was matched
 	with:</para>
       
       <screen>&prompt.root; <userinput>ipfw -at l</userinput></screen>
     </sect2>
     
     <sect2>
       <title>Building a Packet Filtering Firewall</title>
       
       <note>
 	<para>The following suggestions are just that: suggestions.  The
 	  requirements of each firewall are different and we cannot tell you
 	  how to build a firewall to meet your particular requirements.</para>
       </note>
 	  
       <para>When initially setting up your firewall, unless you have a test
 	bench setup where you can configure your firewall host in a controlled
 	environment, it is strongly recommend you use the logging version of the
 	commands and enable logging in the kernel.  This will allow you to
 	quickly identify problem areas and cure them without too much
 	disruption.  Even after the initial setup phase is complete, I
 	recommend using the logging for `deny' as it allows tracing of
 	possible attacks and also modification of the firewall rules if your
 	requirements alter.</para>
 	  
       <note>
 	<para>If you use the logging versions of the <command>accept</command>
 	  command, it can generate <emphasis>large</emphasis> amounts of log
 	  data as one log line will be generated for every packet that passes
 	  through the firewall, so large FTP/http transfers, etc, will really
 	  slow the system down.  It also increases the latencies on those
 	  packets as it requires more work to be done by the kernel before the
 	  packet can be passed on.  <application>syslogd</application> will 
 	  also start using up a lot
 	  more processor time as it logs all the extra data to disk, and it
 	  could quite easily fill the partition <filename>/var/log</filename>
 	  is located on.</para>
       </note>
 	  
       <para>You should enable your firewall from
 	<filename>/etc/rc.conf.local</filename> or
 	<filename>/etc/rc.conf</filename>.  The associated manual page explains
 	which knobs to fiddle and lists some preset firewall configurations.
 	If you do not use a preset configuration, <command>ipfw list</command>
 	will output the current ruleset into a file that you can
 	pass to <filename>rc.conf</filename>.  If you do not use
 	<filename>/etc/rc.conf.local</filename> or
 	<filename>/etc/rc.conf</filename> to enable your firewall,
 	it is important to make sure your firewall is enabled before
 	any IP interfaces are configured.</para>
 	  
       <para>The next problem is what your firewall should actually
 	<emphasis>do</emphasis>! This is largely dependent on what access to
 	your network you want to allow from the outside, and how much access
 	to the outside world you want to allow from the inside. Some general
 	rules are:</para>
       
       <itemizedlist>
 	<listitem>
 	  <para>Block all incoming access to ports below 1024 for TCP. This is
 	    where most of the security sensitive services are, like finger,
 	    SMTP (mail) and telnet.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Block <emphasis>all</emphasis> incoming UDP traffic.  There
 	    are very few useful services that travel over UDP, and what useful
 	    traffic there is, is normally a security threat (e.g. Suns RPC and
 	    NFS protocols).  This has its disadvantages also, since UDP is a
 	    connectionless protocol, denying incoming UDP traffic also blocks
 	    the replies to outgoing UDP traffic.  This can cause a problem for
 	    people (on the inside) using external archie (prospero) servers.
 	    If you want to allow access to archie, you will have to allow
 	    packets coming from ports 191 and 1525 to any internal UDP port
 	    through the firewall.  <application>ntp</application> is another
 	    service you may consider allowing through, which comes from port
 	    123.</para>
 	</listitem>
 	      
 	<listitem>
 	  <para>Block traffic to port 6000 from the outside.  Port 6000 is the
 	    port used for access to X11 servers, and can be a security threat
 	    (especially if people are in the habit of doing <command>xhost
 	      +</command> on their workstations).  X11 can actually use a
 	    range of ports starting at 6000, the upper limit being how many X
 	    displays you can run on the machine.  The upper limit as defined
 	    by RFC 1700 (Assigned Numbers) is 6063.</para>
 	</listitem>
 	      
 	<listitem>
 	  <para>Check what ports any internal servers use (e.g. SQL servers,
 	    etc).  It is probably a good idea to block those as well, as they
 	    normally fall outside the 1-1024 range specified above.</para>
 	</listitem>
       </itemizedlist>
 	  
       <para>Another checklist for firewall configuration is available from
 	CERT at <ulink
 	  url="http://www.cert.org/tech_tips/packet_filtering.html">http://www.cert.org/tech_tips/packet_filtering.html</ulink></para>
 	  
       <para>As stated above, these are only <emphasis>guidelines</emphasis>.
 	You will have to decide what filter rules you want to use on your
 	firewall yourself.  We cannot accept ANY responsibility if someone
 	breaks into your network, even if you follow the advice given
 	above.</para>
     </sect2>
 
     <sect2 id="ipfw-overhead">
       <title>IPFW Overhead and Optimization</title>
 
       <para>Many people want to know how much overhead IPFW adds to a
 	system. The answer to this depends mostly on your rule set and
 	processor speed. For most applications dealing with Ethernet
 	and small rule sets, the answer is
 	<quote>negligible</quote>. For those of you that need actual
 	measurements to satisfy your curiosity, read on.</para>
 
       <para>The following measurements were made using 2.2.5-STABLE on
 	a 486-66.  (While IPFW has changed slightly in later releases
 	of FreeBSD, it still performs with similar speed.) IPFW was
 	modified to measure the time spent within the
 	<literal>ip_fw_chk</literal> routine, displaying the results
 	to the console every 1000 packets.</para>
 
       <para>Two rule sets, each with 1000 rules were tested.  The
 	first set was designed to demonstrate a worst case scenario by
 	repeating the rule:</para>
 
       <screen>&prompt.root; <userinput>ipfw add deny tcp from any to any 55555</userinput></screen>
 
       <para>This demonstrates worst case by causing most of IPFW's
 	packet check routine to be executed before finally deciding
 	that the packet does not match the rule (by virtue of the port
 	number). Following the 999th iteration of this rule was an
 	<literal>allow ip from any to any</literal>.</para>
 
       <para>The second set of rules were designed to abort the rule
 	check quickly:</para>
 
       <screen>&prompt.root; <userinput>ipfw add deny ip from 1.2.3.4 to 1.2.3.4</userinput></screen>
 
       <para>The non-matching source IP address for the above rule
 	causes these rules to be skipped very quickly.  As before, the
 	1000th rule was an <literal>allow ip from any to
 	any</literal>.</para>
 
       <para>The per-packet processing overhead in the former case was
 	approximately 2.703ms/packet, or roughly 2.7 microseconds per
 	rule. Thus the theoretical packet processing limit with these
 	rules is around 370 packets per second. Assuming 10Mbps
 	Ethernet and a ~1500 byte packet size, we would only be able
 	to achieve a 55.5% bandwidth utilization.</para>
 
       <para>For the latter case each packet was processed in
 	approximately 1.172ms, or roughly 1.2 microseconds per rule.
 	The theoretical packet processing limit here would be about
 	853 packets per second, which could consume 10Mbps Ethernet
 	bandwidth.</para>
 
       <para>The excessive number of rules tested and the nature of
 	those rules do not provide a real-world scenario -- they were
 	used only to generate the timing information presented here.
 	Here are a few things to keep in mind when building an
 	efficient rule set:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Place an <literal>established</literal> rule early on
 	    to handle the majority of TCP traffic.  Do not put any
 	    <literal>allow tcp</literal> statements before this
 	    rule.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Place heavily triggered rules earlier in the rule set
 	    than those rarely used (<emphasis>without changing the
 	    permissiveness of the firewall</emphasis>, of course).
 	    You can see which rules are used most often by examining
 	    the packet counting statistics with <command>ipfw -a
 	    l</command>.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="openssl">
     <title>OpenSSL</title>
     <indexterm>
       <primary>security</primary>
       <secondary>OpenSSL</secondary>
     </indexterm>
     <indexterm><primary>OpenSSL</primary></indexterm>
 
     <para>As of FreeBSD 4.0, the OpenSSL toolkit is a part of the base
       system.  <ulink url="http://www.openssl.org/">OpenSSL</ulink>
       provides a general-purpose cryptography library, as well as the
       Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer
       Security v1 (TLSv1) network security protocols.</para>
 
     <para>However, one of the algorithms (specifically IDEA)
       included in OpenSSL is protected by patents in the USA and
       elsewhere, and is not available for unrestricted use.
       IDEA is included in the OpenSSL sources in FreeBSD, but it is not
       built by default.  If you wish to use it, and you comply with the
       license terms, enable the <literal>MAKE_IDEA</literal> switch in
       <filename>/etc/make.conf</filename> and
       rebuild your sources using <command>make world</command>.</para>
 
     <para>Today, the RSA algorithm is free for use in USA and other
       countries.  In the past it was protected by a patent.</para>
 
     <indexterm>
       <primary>OpenSSL</primary>
       <secondary>install</secondary>
     </indexterm>
 
     <sect2>
       <title>Source Code Installations</title>
       
       <para>OpenSSL is part of the <literal>src-crypto</literal> and
 	<literal>src-secure</literal> cvsup collections.  See the <link
 	linkend="mirrors">Obtaining FreeBSD</link> section for more
 	information about obtaining and updating FreeBSD source
 	code.</para>
     </sect2>
   </sect1>
 
   <sect1 id="ipsec">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Yoshinobu</firstname>
 	  <surname>Inoue</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<!-- 5 Mar 2000 -->
       </authorgroup>
     </sect1info>
 
     <title>IPsec</title>
     <indexterm><primary>IPsec</primary></indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>IPsec</secondary>
     </indexterm>
 
     <note>
       <title>Terminating Characters</title>
       <para>Throughout examples in this section, and other sections,
 	you will notice that there is a <quote>^D</quote> at the end
 	of some examples. This means to hold down the <keycap>Control</keycap>
 	key and hit the <keycap>D</keycap> key. Another commonly used
 	character is <quote>^C</quote>, which respectively means to hold
 	down <keycap>Control</keycap> and press <keycap>C</keycap>.</para>
     </note>
 
     <tip>
       <para>For other HOWTOs detailing IPSec implementation in
         FreeBSD, take a look at <ulink
         url="http://www.daemonnews.org/200101/ipsec-howto.html"></ulink>
         and <ulink
         url="http://www.freebsddiary.org/ipsec.php"></ulink>.</para>
     </tip>
 
     <para>The IPsec mechanism provides secure communication for IP
       layer and socket layer communication.  This section should
       explain how to use them.  For implementation details, please
       refer to <ulink
       url="../developers-handbook/ipv6.html">The
       Developers' Handbook</ulink>.</para>
 
     <para>The current IPsec implementation supports both transport mode
       and tunnel mode.  However, tunnel mode comes with some restrictions.
       <ulink url="http://www.kame.net/newsletter/">http://www.kame.net/newsletter/
       </ulink> has more comprehensive examples.</para>
 
     <para>Please be aware that in order to use this functionality, you
       must have the following options compiled into your kernel:</para>
 
     <programlisting>options          IPSEC              #IP security
 options          IPSEC_ESP          #IP security (crypto; define w/IPSEC)</programlisting>
 
     <sect2>
       <title>Transport Mode Example with IPv4</title>
 
       <para>Let us setup security association to deploy a secure channel
         between HOST A (10.2.3.4) and HOST B (10.6.7.8).  Here we show a little
         complicated example.  From HOST A to HOST B, only old AH is used.
         From HOST B to HOST A, new AH and new ESP are combined.</para>
 
       <para>Now we should choose an algorithm to be used corresponding to
         <quote>AH</quote>/<quote>new AH</quote>/<quote>ESP</quote>/
 	<quote>new ESP</quote>.  Please refer to the &man.setkey.8; man
         page to know algorithm names.  Our choice is MD5 for AH, new-HMAC-SHA1
         for new AH, and new-DES-expIV with 8 byte IV for new ESP.</para>
 
       <para>Key length highly depends on each algorithm.  For example, key
         length must be equal to 16 bytes for MD5, 20 for new-HMAC-SHA1,
         and 8 for new-DES-expIV.  Now we choose <quote>MYSECRETMYSECRET</quote>,
         <quote>KAMEKAMEKAMEKAMEKAME</quote>, <quote>PASSWORD</quote>,
 	respectively.</para>
 
       <para>OK, let us assign SPI (Security Parameter Index) for each protocol.
         Please note that we need 3 SPIs for this secure channel since three
         security headers are produced (one for from HOST A to HOST B, two for
         from HOST B to HOST A).  Please also note that SPI MUST be greater
         than or equal to 256.  We choose, 1000, 2000, and 3000,
 	respectively.</para>
 
       <screen>
 	         (1)
 	HOST A ------> HOST B
 
 	(1)PROTO=AH
 		ALG=MD5(RFC1826)
 		KEY=MYSECRETMYSECRET
 		SPI=1000
 
 	         (2.1)
 	HOST A <------ HOST B
 	       <------
 	         (2.2)
 
 	(2.1)
 	PROTO=AH
 		ALG=new-HMAC-SHA1(new AH)
 		KEY=KAMEKAMEKAMEKAMEKAME
 		SPI=2000
 
 	(2.2)
 	PROTO=ESP
 		ALG=new-DES-expIV(new ESP)
 			IV length = 8
 		KEY=PASSWORD
 		SPI=3000
 </screen>
 
       <para>Now, let us setup security association.  Execute &man.setkey.8;
         on both HOST A and B:</para>
 
       <screen>
 &prompt.root; <command>setkey -c</command>
 add 10.2.3.4 10.6.7.8 ah-old  1000 -m transport -A keyed-md5 "MYSECRETMYSECRET" ;
 add 10.6.7.8 10.2.3.4 ah  2000 -m transport -A hmac-sha1 "KAMEKAMEKAMEKAMEKAME" ;
 add 10.6.7.8 10.2.3.4 esp 3000 -m transport -E des-cbc "PASSWORD" ;
 ^D
 </screen>
 
      <para>Actually, IPsec communication does not process until security policy
        entries are defined.  In this case, you must setup each host.</para>
 
      <screen>
 At A:
 
 &prompt.root; <command>setkey -c</command>
 spdadd 10.2.3.4 10.6.7.8 any -P out ipsec
 	ah/transport/10.2.3.4-10.6.7.8/require ;
 ^D
 
 At B:
 
 &prompt.root; <command>setkey -c</command>
 spdadd 10.6.7.8 10.2.3.4 any -P out ipsec
 	esp/transport/10.6.7.8-10.2.3.4/require ;
 spdadd 10.6.7.8 10.2.3.4 any -P out ipsec
 	ah/transport/10.6.7.8-10.2.3.4/require ;
 ^D
 
 
    HOST A --------------------------------------> HOST E
   10.2.3.4                                       10.6.7.8
           |                                     |
           ========== old AH keyed-md5 ==========>
 
           <========= new AH hmac-sha1 ===========
           <========= new ESP des-cbc ============
 </screen>
     </sect2>
 
     <sect2>
       <title>Transport Mode Example with IPv6</title>
 
       <para>Another example using IPv6.</para>
 
       <para>ESP transport mode is recommended for TCP port number 110 between
         Host-A and Host-B.</para>
 
       <screen>
               ============ ESP ============
               |                           |
            Host-A                        Host-B
           fec0::10 -------------------- fec0::11
 </screen>
 
       <para>Encryption algorithm is blowfish-cbc whose key is
 	<quote>kamekame</quote>, and authentication algorithm is hmac-sha1
 	whose key is <quote>this is the test key</quote>.
 	Configuration at Host-A:</para>
 
       <screen>
         &prompt.root; <command>setkey -c</command> &lt;&lt;<filename>EOF</filename>
         spdadd fec0::10[any] fec0::11[110] tcp -P out ipsec
                 esp/transport/fec0::10-fec0::11/use ;
         spdadd fec0::11[110] fec0::10[any] tcp -P in ipsec
                 esp/transport/fec0::11-fec0::10/use ;
         add fec0::10 fec0::11 esp 0x10001
                 -m transport
                 -E blowfish-cbc "kamekame"
                 -A hmac-sha1 "this is the test key" ;
         add fec0::11 fec0::10 esp 0x10002
                 -m transport
                 -E blowfish-cbc "kamekame"
                 -A hmac-sha1 "this is the test key" ;
         EOF
 </screen>
 
       <para>and at Host-B:</para>
 
       <screen>&prompt.root; <command>setkey -c</command> &lt;&lt;<filename>EOF</filename>
         spdadd fec0::11[110] fec0::10[any] tcp -P out ipsec
                 esp/transport/fec0::11-fec0::10/use ;
         spdadd fec0::10[any] fec0::11[110] tcp -P in ipsec
                 esp/transport/fec0::10-fec0::11/use ;
         add fec0::10 fec0::11 esp 0x10001 -m transport
                 -E blowfish-cbc "kamekame"
                 -A hmac-sha1 "this is the test key" ;
         add fec0::11 fec0::10 esp 0x10002 -m transport
                 -E blowfish-cbc "kamekame"
                 -A hmac-sha1 "this is the test key" ;
         EOF
 </screen>
 
       <para>Note the direction of SP.</para>
     </sect2>
 
     <sect2>
       <title>Tunnel Mode Example with IPv4</title>
 
       <para>Tunnel mode between two security gateways</para>
 
       <para>Security protocol is old AH tunnel mode, i.e. specified by
         RFC1826, with keyed-md5 whose key is <quote>this is the test</quote> as
         authentication algorithm.</para>
 
       <screen>
                              ======= AH =======
                              |                |
          Network-A       Gateway-A        Gateway-B        Network-B
         10.0.1.0/24 ---- 172.16.0.1 ----- 172.16.0.2 ---- 10.0.2.0/24
 </screen>
 
       <para>Configuration at Gateway-A:</para>
 
       <screen>
         &prompt.root; <command>setkey -c</command> &lt;&lt;<filename>EOF</filename>
         spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec
                 ah/tunnel/172.16.0.1-172.16.0.2/require ;
         spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec
                 ah/tunnel/172.16.0.2-172.16.0.1/require ;
         add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any
                 -A keyed-md5 "this is the test" ;
         add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any
                 -A keyed-md5 "this is the test" ;
 
         EOF
 </screen>
 
       <para>If the port number field is omitted such as above then
 	<literal>[any]</literal> is employed. <literal>-m</literal>
 	specifies the mode of SA to be used. <literal>-m any</literal> means
 	wild-card of mode of security protocol. You can use this SA for both
 	tunnel and transport mode.</para>
 
       <para>and at Gateway-B:</para>
 
       <screen>
         &prompt.root; <command>setkey -c</command> &lt;&lt;<filename>EOF</filename>
         spdadd 10.0.2.0/24 10.0.1.0/24 any -P out ipsec
                 ah/tunnel/172.16.0.2-172.16.0.1/require ;
         spdadd 10.0.1.0/24 10.0.2.0/24 any -P in ipsec
                 ah/tunnel/172.16.0.1-172.16.0.2/require ;
         add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any
                 -A keyed-md5 "this is the test" ;
         add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any
                 -A keyed-md5 "this is the test" ;
 
         EOF
 </screen>
 
       <para>Making SA bundle between two security gateways</para>
 
       <para>AH transport mode and ESP tunnel mode is required between
         Gateway-A and Gateway-B. In this case, ESP tunnel mode is applied first,
         and AH transport mode is next.</para>
 
       <screen>
                             ========== AH =========
                             |  ======= ESP =====  |
                             |  |               |  |
        Network-A          Gateway-A        Gateway-B           Network-B
     fec0:0:0:1::/64 --- fec0:0:0:1::1 ---- fec0:0:0:2::1 --- fec0:0:0:2::/64
 </screen>
     </sect2>
 
     <sect2>
       <title>Tunnel Mode Example with IPv6</title>
 
       <para>Encryption algorithm is 3des-cbc, and authentication algorithm
         for ESP is hmac-sha1.  Authentication algorithm for AH is hmac-md5.
         Configuration at Gateway-A:</para>
 
       <screen>
         &prompt.root; <command>setkey -c</command> &lt;&lt;<filename>EOF</filename>
         spdadd fec0:0:0:1::/64 fec0:0:0:2::/64 any -P out ipsec
                 esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require
                 ah/transport/fec0:0:0:1::1-fec0:0:0:2::1/require ;
         spdadd fec0:0:0:2::/64 fec0:0:0:1::/64 any -P in ipsec
                 esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require
                 ah/transport/fec0:0:0:2::1-fec0:0:0:1::1/require ;
         add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10001 -m tunnel
                 -E 3des-cbc "kamekame12341234kame1234"
                 -A hmac-sha1 "this is the test key" ;
         add fec0:0:0:1::1 fec0:0:0:2::1 ah 0x10001 -m transport
                 -A hmac-md5 "this is the test" ;
         add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10001 -m tunnel
                 -E 3des-cbc "kamekame12341234kame1234"
                 -A hmac-sha1 "this is the test key" ;
         add fec0:0:0:2::1 fec0:0:0:1::1 ah 0x10001 -m transport
                 -A hmac-md5 "this is the test" ;
 
         EOF
 </screen>
 
       <para>Making SAs with the different end</para>
 
       <para>ESP tunnel mode is required between Host-A and Gateway-A. Encryption
         algorithm is cast128-cbc, and authentication algorithm for ESP is
         hmac-sha1.  ESP transport mode is recommended between Host-A and Host-B.
         Encryption algorithm is rc5-cbc, and authentication algorithm for ESP is
         hmac-md5.</para>
 
       <screen>
               ================== ESP =================
               |  ======= ESP =======                 |
               |  |                 |                 |
              Host-A            Gateway-A           Host-B
           fec0:0:0:1::1 ---- fec0:0:0:2::1 ---- fec0:0:0:2::2
 </screen>
 
       <para>Configuration at Host-A:</para>
 
       <screen>
         &prompt.root; <command>setkey -c</command> &lt;&lt;<filename>EOF</filename>
         spdadd fec0:0:0:1::1[any] fec0:0:0:2::2[80] tcp -P out ipsec
                 esp/transport/fec0:0:0:1::1-fec0:0:0:2::2/use
                 esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ;
         spdadd fec0:0:0:2::1[80] fec0:0:0:1::1[any] tcp -P in ipsec
                 esp/transport/fec0:0:0:2::2-fec0:0:0:l::1/use
                 esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ;
         add fec0:0:0:1::1 fec0:0:0:2::2 esp 0x10001
                 -m transport
                 -E cast128-cbc "12341234"
                 -A hmac-sha1 "this is the test key" ;
         add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10002
                 -E rc5-cbc "kamekame"
                 -A hmac-md5 "this is the test" ;
         add fec0:0:0:2::2 fec0:0:0:1::1 esp 0x10003
                 -m transport
                 -E cast128-cbc "12341234"
                 -A hmac-sha1 "this is the test key" ;
         add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10004
                 -E rc5-cbc "kamekame"
                 -A hmac-md5 "this is the test" ;
 
         EOF
 </screen>
     </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>Secure shell 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.
       ssh encrypts all traffic to effectively eliminate eavesdropping,
       connection hijacking, and other network-level attacks.</para>
 
     <para>OpenSSH 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.  OpenSSH has been
       in the base system since FreeBSD 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.  OpenSSH 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 additions to your 
         <filename>rc.conf</filename> file:</para>
       <screen>sshd_enable="YES"</screen>
       <para>This will load the <application>ssh</application> daemon
 	the next time your system initializes.  Alternatively, you can
 	simply run the <application>sshd</application> daemon.</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>
+      <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, OpenSSH servers are configured to accept both
 	SSH v1 and SSH v2 connections.  The client, however, can choose
 	between the two.  Version 2 is known to be more robust and
 	secure than its predecessor.</para>
 
       <para><command>ssh</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 <command>scp</command> command works similarly to
 	<command>rcp</command>; 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>
+      <screen>&prompt.root; <userinput> scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput>
 user@example.com's password: 
 COPYRIGHT            100% |*****************************|  4735       
 00:00    
-&prompt.root</screen>
+&prompt.root;</screen>
       <para>Since the fingerprint was already saved for this host in the
         previous example, it is verified when using <command>scp</command>
         here.</para>
 
       <para>The arguments passed to <command>scp</command> are similar
 	to <command>cp</command>, 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></option>.</para>
 
     </sect2>
 
     <sect2>
       <title>Configuration</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>configuration</secondary>
       </indexterm>
 
       <para>The system-wide configuration files for both the OpenSSH 
         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</userinput>
+      <screen>&prompt.user; <userinput>ssh-keygen</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>
 
       <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 v2 DSA key can be created for the same purpose by using
 	the <command>ssh-keygen -d</command> command (or
 	<command>ssh-keygen -t dsa</command> for FreeBSD &os.current;).
 	This will
 	create a public/private DSA key for use in SSH v2 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 placed in
 	<filename>~/.ssh/authorized_keys2</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>
     </sect2>
 
     <sect2>
       <title>SSH Tunneling</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>tunneling</secondary>
       </indexterm>
 
       <para>OpenSSH 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 telnet.</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 telnet,
 	this would create a secure telnet 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: ******</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.myserver.com</replaceable></userinput>
 user@unfirewalled.myserver.com's password: *******</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>
 
 </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:
 -->