diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml
index 4ac3b2632a..759de3f96e 100644
--- a/en_US.ISO8859-1/articles/committers-guide/article.sgml
+++ b/en_US.ISO8859-1/articles/committers-guide/article.sgml
@@ -1,2566 +1,2566 @@
 <!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 % 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;
 ]>
 
 <article>
   <articleinfo>
     <title>Committer Guide</title>
 
     <authorgroup>
       <author>
 	<surname>The FreeBSD Documentation Project</surname>
       </author>
     </authorgroup>
 
     <pubdate>$FreeBSD$</pubdate>
 
     <copyright>
       <year>1999</year>
       <year>2000</year>
       <year>2001</year>
       <holder>The FreeBSD Documentation Project</holder>
     </copyright>
 
     <abstract>
       <para>This document provides information for the FreeBSD committer
 	community.  All new committers should read this document before they
 	start, and existing committers are strongly encouraged to review it
 	from time to time.</para>
     </abstract>
   </articleinfo>
 
   <sect1 id="admin">
     <title>Administrative Details</title>
 
     <informaltable frame="none" orient="port">
       <tgroup cols="2">
 	<tbody>
 	  <row>
 	    <entry><emphasis>Main Repository Host</emphasis></entry>
 	    <entry><hostid>freefall.FreeBSD.org</hostid></entry>
 	  </row>
 	  
 	  <row>
 	    <entry><emphasis>Login Methods</emphasis></entry>
 	    <entry>&man.ssh.1;</entry>
 	  </row>
 	  
 	  <row>	  
 	    <entry><emphasis>Main CVSROOT</emphasis></entry>
 	    <entry><filename>/home/ncvs</filename></entry>
 	  </row>
 	  
 	  <row>
 	    <entry><emphasis>Main CVS Repository Meisters</emphasis></entry>
 	    <entry>&a.peter; and &a.markm;, as well as &a.joe; and &a.asami; for
 	      <filename>ports/</filename></entry>
 	  </row>
 	  
 	  <row>	  
 	    <entry><emphasis>Mailing List</emphasis></entry>
 	    <entry>&a.developers;, &a.committers;</entry>
 	  </row>
 	  
 	  <row>	  
 	    <entry><emphasis>Noteworthy CVS Tags</emphasis></entry>
 	    <entry>RELENG_3 (3.x-STABLE), RELENG_4 (4.x-STABLE), HEAD (-CURRENT)</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
     
     <para>It is required that you use &man.ssh.1; or &man.telnet.1;
       with Kerberos 5 to connect to the repository hosts.  These are
       generally more secure than plain &man.telnet.1; or
       &man.rlogin.1; since credential negotiation will always be
       encrypted.  All traffic is encrypted by default with &man.ssh.1;.
       With utilities like &man.ssh-agent.1; and &man.scp.1; also
       available, &man.ssh.1; is also far more convenient.  If you do
       not know anything about &man.ssh.1;, please see
       <xref linkend="ssh.guide">.</para>
   </sect1>
 
   <sect1 id="committer.types">
     <title>Commit Bit Types</title>
 
     <para>The FreeBSD CVS repository has a number of components which,
       when combined, support the basic operating system source,
       documentation, third party application ports infrastructure, and
       various maintained utilities.  When FreeBSD commit bits are
       allocated, the areas of the tree where the bit may be used are
       specified.  Generally, the areas associated with a bit reflect who
       authorized the allocation of the commit bit.  Additional areas of
       authority may be added at a later date: when this occurs, the
       committer should follow normal commit bit allocation procedures for
       that area of the tree, seeking approval from the appropriate entity
       and possibly getting a mentor for that area for some period of time.
       </para>
 
     <informaltable frame="none">
       <tgroup cols="3">
 	<tbody>
 	  <row>
 	    <entry><emphasis>Committer Type</emphasis></entry>
 	    <entry><emphasis>Responsible</emphasis></entry>
 	    <entry><emphasis>Tree Components</emphasis></entry>
 	  </row>
 
 	  <row>
 	    <entry>src</entry>
 	    <entry>core@</entry>
 	    <entry>src/, doc/ subject to appropriate review</entry>
 	  </row>
 
 	  <row>
 	    <entry>doc</entry>
 	    <entry>nik@</entry>
 	    <entry>doc/, src/ documentation</entry>
 	  </row>
 
 	  <row>
 	    <entry>ports</entry>
 	    <entry>portmgr@</entry>
 	    <entry>ports/</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
 
     <para>Commit bits allocated prior to the development of the notion of
       areas of authority may be appropriate for use in many parts of the
       tree.  However, common sense dictates that a committer who has not
       previously worked in an area of the tree seek review prior to
       committing, seek approval from the appropriate responsible party,
       and/or work with a mentor.  Since the rules regarding code
       maintenance differ by area of the tree, this is as much for the
       benefit of the committer working in an area of less familiarity as
       it is for others working on the tree.</para>
 
     <para>Committers are encouraged to seek review for their work as part
       of the normal development process, regardless of the area of the
       tree where the work is occuring.</para>
   </sect1>
 
   <sect1 id="cvs.operations">
     <title>CVS Operations</title>
 
     <para>It is assumed that you are already familiar with the basic operation 
       of CVS.</para>
     
     <para>The CVS Repository Meisters (Peter Wemm and John Polstra)
       are the <quote>owners</quote> of the CVS repository and are
       responsible for any and <emphasis>all</emphasis> direct
       modification of it for the purposes of cleanup or fixing some
       grievous abuse of CVS by a committer.  No one else should
       attempt to touch the repository directly.  Should you cause some
       repository accident, say a bad cvs import or tag operation, do
       <emphasis role="bold">not</emphasis> attempt to fix it yourself!
       Mail or call John or Peter immediately and report the problem to
       one of them instead.  The only ones allowed to directly fiddle
       the repository bits are the repomeisters.  Satoshi Asami is also a
       repomeister for the <filename>ports/</filename> portion of the
       tree.</para>
 
     <para>CVS operations are usually done by logging into
       <hostid>freefall</hostid>, making sure the
       <envar>CVSROOT</envar> environment variable is set to
       <filename>/home/ncvs</filename>, and then doing the appropriate
       check-out/check-in operations.  If you wish to add
       something which is wholly new (like contrib-ified
       sources, etc), a script called <quote>easy-import</quote> is
       also provided for making the process easier.  It automatically
       adds the new module entry, does the appropriate thing with
       <command>cvs import</command>, etc. &ndash; just run it without
       arguments and it will prompt you for everything it needs to
       know.</para>
 
     <para>Note that when you use CVS on <hostid>freefall</hostid>, you
       should set your <literal>umask</literal> to <literal>2</literal>,
       as well as setting the <envar>CVSUMASK</envar> environment
       variable to <literal>2</literal>.  This ensures that any new
       files created by <command>cvs add</command> will have the correct
       permissions.  If you add a file or directory and discover that the
       file in the repository has incorrect permissions (specifically,
       all files in the repository should be group writable by group
       <literal>ncvs</literal>), contact one of the repository meisters
       as described below.</para>
 
     <para>If you are familiar with remote CVS and consider yourself
       pretty studly with CVS in general, you can also do CVS
       operations directly from your own machine and local working
       sources. Just remember to set <envar>CVS_RSH</envar> to
       <wordasword>ssh</wordasword> so that you are using a relatively
       secure and reliable transport.  If you have no idea what any of
       the above even means, on the other hand, then please stick with
       logging into <hostid>freefall</hostid> and applying your diffs
       with &man.patch.1;.</para>
 
     <para>If you need to use CVS <command>add</command> and
       <command>delete</command> operations in a manner that is
       effectively a <quote>mv</quote> operation, then a repository
       copy is in order rather than your CVS <command>add</command> and
       <command>delete</command>.  In a repository copy, a <link
       linkend="conventions">CVS Meister</link> will copy the file(s)
       to their new name and/or location and let you know when it is
       done.  The purpose of a repository copy is to preserve file
       change history, or logs.  We in the FreeBSD Project greatly
       value the change history CVS gives to the project.</para>
 
     <para>CVS reference information, tutorials, and FAQs can also be found at:
       <ulink
 	url="http://www.cvshome.org/docs/">http://www.cvshome.org/docs/</ulink>, 
       and the information in <ulink url="http://cvsbook.red-bean.com/cvsbook.html">Karl Fogel's
         chapters from <quote>Open Source Development with CVS</quote></ulink> are also very
       useful.</para>
 
     <para>&a.des; also supplied the following <quote>mini primer</quote> for
       CVS.</para>
 
     <orderedlist>
       <listitem>
         <para>Check out a module with the <command>co</command> or
 	  <command>checkout</command> command.</para>
 
         <screen>&prompt.user; <userinput>cvs checkout shazam</userinput></screen>
 
         <para>This checks out a copy of the <filename>shazam</filename> module. If
           there is no <filename>shazam</filename> module in the modules file, it looks for a
           top-level directory named <filename>shazam</filename> instead.</para>
 
         <table frame="none">
 	  <title>Useful <command>cvs checkout</command> options</title>
 
           <tgroup cols=2>
             <tbody>
               <row>
                 <entry><option>-P</option></entry>
                 <entry>Do not create empty directories</entry>
               </row>
 
               <row>
                 <entry><option>-l</option></entry>
                 <entry>Check out a single level, no subdirectories</entry>
               </row>
 
               <row>
                 <entry><option>-r<replaceable>rev</replaceable></option></entry>
                 <entry>Check out revision, branch or tag
                   <replaceable>rev</replaceable></entry>
               </row>
 
               <row>
                 <entry><option>-D<replaceable>date</replaceable></option></entry>
                 <entry>Check out the sources as they were on date
                   <replaceable>date</replaceable></entry>
               </row>
             </tbody>
           </tgroup>
         </table>
 
         <para>Practical FreeBSD examples:</para>
 
         <itemizedlist>
           <listitem>
             <para>Check out the <filename>miscfs</filename> module,
               which corresponds to <filename>src/sys/miscfs</filename>:</para>
 
             <screen>&prompt.user; <userinput>cvs co miscfs</userinput></screen>
 
             <para>You now have a directory named <filename>miscfs</filename>
               with subdirectories <filename>CVS</filename>,
               <filename>deadfs</filename>, <filename>devfs</filename>, and so
               on.  One of these (<filename>linprocfs</filename>) is
               empty.</para>
           </listitem>
 
           <listitem>
             <para>Check out the same files, but with full path:</para>
 
             <screen>&prompt.user; <userinput>cvs co src/sys/miscfs</userinput></screen>
 
             <para>You now have a directory named <filename>src</filename>,
               with subdirectories <filename>CVS</filename> and
               <filename>sys</filename>.  <filename>src/sys</filename> has
               subdirectories <filename>CVS</filename> and
               <filename>miscfs</filename>, etc.</para>
           </listitem>
 
           <listitem>
             <para>Check out the same files, but prunes empty
               directories:</para>
 
             <screen>&prompt.user; <userinput>cvs co -P miscfs</userinput></screen>
 
             <para>You now have a directory named
               <filename>miscfs</filename> with subdirectories
               <filename>CVS</filename>, <filename>deadfs</filename>,
               <filename>devfs</filename>... but note that there is no
               <filename>linprocfs</filename> subdirectory, because there
               are no files in it.</para>
           </listitem>
 
           <listitem>
             <para>Check out the directory <filename>miscfs</filename>, but
               none of the subdirectories:</para>
 
             <screen>&prompt.root; <userinput>cvs co -l miscfs</userinput></screen>
 
             <para>You now have a directory named <filename>miscfs</filename>
               with just one subdirectory named
               <filename>CVS</filename>.</para>
           </listitem>
 
           <listitem>
             <para>Check out the <filename>miscfs</filename> module as
               it is in the 4.x branch:</para>
 
             <screen>&prompt.user; <userinput>cvs co -rRELENG_4 miscfs</userinput></screen>
 
             <para>You can modify the sources and commit along this
               branch.</para>
           </listitem>
 
           <listitem>
             <para>Check out the <filename>miscfs</filename> module as
               it was in 3.4-RELEASE.</para>
 
             <screen>&prompt.user; <userinput>cvs co -rRELENG_3_4_0_RELEASE miscfs</userinput></screen>
 
             <para>You will not be able to commit modifications, since
               RELENG_3_4_0_RELEASE is a point in time, not a branch.</para>
           </listitem>
 
           <listitem>
             <para>Check out the <filename>miscfs</filename> module as it was
               on Jan 15 2000.</para>
 
             <screen>&prompt.user; <userinput>cvs co -D'01/15/2000' miscfs</userinput></screen>
 
             <para>You will not be able to commit modifications.</para>
           </listitem>
 
           <listitem>
             <para>Check out the <filename>miscfs</filename> module as it was
               one week ago.</para>
 
             <screen>&prompt.user; <userinput>cvs co -D'last week' miscfs</userinput></screen>
 
             <para>You will not be able to commit modifications.</para>
           </listitem>
         </itemizedlist>
 
         <para>Note that cvs stores metadata in subdirectories named
           <filename>CVS</filename>.</para>
 
         <para>Arguments to <option>-D</option> and <option>-r</option>
           are sticky, which means cvs will remember them later, e.g.
           when you do a <command>cvs update</command>.</para>
       </listitem>
 
       <listitem>
         <para>Check the status of checked-out files with the
           <command>status</command> command.</para>
 
         <screen>&prompt.user; <userinput>cvs status shazam</userinput></screen>
 
         <para>This displays the status of the
           <filename>shazam</filename> file or of every file in the
           <filename>shazam</filename> directory. For every file, the
           status is given as one of:</para>
 
         <informaltable frame="none">
           <tgroup cols=2>
             <tbody>
               <row>
                 <entry>Up-to-date</entry>
                 <entry>File is up-to-date and unmodified.</entry>
               </row>
 
               <row>
                 <entry>Needs Patch</entry>
                 <entry>File is unmodified, but there is a newer revision in
                   the repository.</entry>
               </row>
 
               <row>
                 <entry>Locally Modified</entry>
                 <entry>File is up-to-date, but modified.</entry>
               </row>
 
               <row>
                 <entry>Needs Merge</entry>
                 <entry>File is modified, and there is a newer revision in the
                   repository.</entry>
               </row>
 
               <row>
                 <entry>File had conflicts on merge</entry>
                 <entry>There were conflicts the last time this file was
                   updated, and they have not been resolved yet.</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
         <para>You will also see the local revision and date,
           the revision number of the newest applicable version
           (<quote>newest applicable</quote> because if you have a
           sticky date, tag or branch, it may not be the actual newest
           revision), and any sticky tags, dates or options.</para>
       </listitem>
 
       <listitem>
         <para>Once you have checked something out, update it with the
           <command>update</command> command.</para>
 
         <screen>&prompt.user; <userinput>cvs update shazam</userinput></screen>
 
         <para>This updates the <filename>shazam</filename> file or the
           contents of the <filename>shazam</filename> directory to the
           latest version along the branch you checked out.  If you
           checked out a <quote>point in time</quote>, does nothing
           unless the tags have moved in the repository or some other weird
           stuff is going on.</para>
 
         <para>Useful options, in addition to those listed above for
           <command>checkout</command>:</para>
 
         <informaltable frame="none">
           <tgroup cols=2>
             <tbody>
               <row>
                 <entry><option>-d</option></entry>
                 <entry>Check out any additional missing directories.</entry>
               </row>
 
               <row>
                 <entry><option>-A</option></entry>
                 <entry>Update to head of main branch.</entry>
               </row>
 
               <row>
                 <entry><option>-j<replaceable>rev</replaceable></option></entry>
                 <entry>More magic (see below).</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
         <para>If you checked out a module with <option>-r</option> or
           <option>-D</option>, running <command>cvs update</command>
           with a different <option>-r</option> or <option>-D</option>
           argument or with <option>-A</option> will select a new branch,
           revision or date. The <option>-A</option> option clears all
           sticky tags, dates or revisions whereas <option>-r</option>
           and <option>-D</option> set new ones.</para>
 
         <para>Theoretically, specifying <literal>HEAD</literal> as
           argument to <option>-r</option> will give you the same result
           as <option>-A</option>, but that is just theory.</para>
 
         <para>The <option>-d</option> option is useful if:</para>
 
         <itemizedlist>
           <listitem>
             <para>somebody has added subdirectories to the module
               you have checked out after you checked it out.</para>
           </listitem>
 
           <listitem>
             <para>you checked out with <option>-l</option>, and later
               change your mind and want to check out the subdirectories
               as well.</para>
           </listitem>
 
           <listitem>
             <para>you deleted some subdirectories and want to check
               them all back out.</para>
           </listitem>
         </itemizedlist>
 
         <para><emphasis>Watch the output of the <command>cvs
           update</command> with care.</emphasis> The letter in front of
           each file name indicates what was done with it:</para>
 
         <informaltable frame="none">
           <tgroup cols=2>
             <tbody>
               <row>
                 <entry><literal>U</literal></entry>
                 <entry>The file was updated with no trouble.</entry>
               </row>
 
               <row>
                 <entry><literal>P</literal></entry>
                 <entry>The file was updated with no trouble (you will only see
                   this when working against a remote repo).</entry>
               </row>
 
               <row>
                 <entry><literal>M</literal></entry>
                 <entry>The file had been modified, and was merged with no
                   conflicts.</entry>
               </row>
 
               <row>
                 <entry><literal>C</literal></entry>
                 <entry>The file had been modified, and was merged with
                   conflicts.</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
         <para>Merging is what happens if you check out a copy of
           some source code, modify it, then someone else commits a
           change, and you run <command>cvs update</command>. CVS notices
           that you have made local changes, and tries to merge your
           changes with the changes between the version you originally
           checked out and the one you updated to. If the changes are to
           separate portions of the file, it will almost always work fine
           (though the result might not be syntactically or semantically
           correct).</para>
 
         <para>CVS will print an <literal>M</literal> in front of every locally modified
           file even if there is no newer version in the repository, so
           <command>cvs update</command> is handy for getting a summary
           of what you have changed locally.</para>
 
         <para>If you get a <literal>C</literal>, then your changes
           conflicted with the changes in the repository (the changes
           were to the same lines, or neighboring lines, or you changed
           the local file so much that <command>cvs</command> can not
           figure out how to apply the repository's changes). You will have
           to go through the file manually and resolve the conflicts;
           they will be marked with rows of <literal>&lt;</literal>,
           <literal>=</literal> and <literal>&gt;</literal> signs. For
           every conflict, there will be a marker line with seven
           <literal>&lt;</literal> signs and the name of the file,
           followed by a chunk of what your local file contained,
           followed by a separator line with seven <literal>=</literal>
           signs, followed by the corresponding chunk in the
           repository version, followed by a marker line with seven
           <literal>&gt;</literal> signs and the revision number you
           updated to.</para>
 
         <para>The <option>-j</option> option is slightly voodoo. It
           updates the local file to the specified revision as if you
           used <option>-r</option>, but it does not change the recorded
           revision number or branch of the local file. It is not really
           useful except when used twice, in which case it will merge the
           changes between the two specified versions into the working
           copy.</para>
 
         <para>For instance, say you commit a change to
           <filename>shazam/shazam.c</filename> in &os.current; and later
           want to MFC it.  The change you want to MFC was revision
           1.15:</para>
 
         <itemizedlist>
           <listitem>
             <para>Check out the &os.stable; version of the
               <filename>shazam</filename> module:</para>
 
             <screen>&prompt.user; <userinput>cvs co -rRELENG_4 shazam</userinput></screen>
           </listitem>
 
           <listitem>
             <para>Apply the changes between rev 1.14 and 1.15:</para>
 
             <screen>&prompt.user; <userinput>cvs update -j1.14 -j1.15 shazam/shazam.c</userinput></screen>
           </listitem>
         </itemizedlist>
 
         <para>You will almost certainly get a conflict because
-          of the <literal>$Id: article.sgml,v 1.106 2002-03-27 12:40:02 murray Exp $</literal> (or in FreeBSD's case,
+          of the <literal>$Id: article.sgml,v 1.107 2002-04-07 23:52:25 keramida Exp $</literal> (or in FreeBSD's case,
           <literal>$<!-- stop expansion -->FreeBSD<!-- stop expansion -->$</literal>) lines, so you will have to edit
           the file to resolve the conflict (remove the marker lines and
-          the second <literal>$Id: article.sgml,v 1.106 2002-03-27 12:40:02 murray Exp $</literal> line, leaving the original
-          <literal>$Id: article.sgml,v 1.106 2002-03-27 12:40:02 murray Exp $</literal> line intact).</para>
+          the second <literal>$Id: article.sgml,v 1.107 2002-04-07 23:52:25 keramida Exp $</literal> line, leaving the original
+          <literal>$Id: article.sgml,v 1.107 2002-04-07 23:52:25 keramida Exp $</literal> line intact).</para>
       </listitem>
 
       <listitem>
         <para>View differences between the local version and the
           repository version with the <command>diff</command>
           command.</para>
 
         <screen>&prompt.user; <userinput>cvs diff shazam</userinput></screen>
 
         <para>shows you every modification you have made to the
           <filename>shazam</filename> file or module.</para>
 
         <table frame="none">
 	  <title>Useful <command>cvs diff</command> options</title>
 	  
           <tgroup cols=2>
             <tbody>
               <row>
                 <entry><option>-u</option></entry>
                 <entry>Uses the unified diff format.</entry>
               </row>
 
               <row>
                 <entry><option>-N</option></entry>
                 <entry>Shows missing or added files.</entry>
               </row>
             </tbody>
           </tgroup>
         </table>
 
         <para>You always want to use <option>-u</option>, since
           unified diffs are much easier to read than almost any other
           diff format (in some circumstances, context diffs may be
           better, but they are much bulkier). A unified diff consists of
           a series of hunks. Each hunk begins with a line that starts
           with two <literal>@</literal> signs and specifies where in the
           file the differences are and how many lines they span. This
           is followed by a number of lines; some (preceded by a blank)
           are context; some (preceded by a <literal>-</literal> sign)
           are outtakes and some (preceded by a <literal>+</literal>) are
           additions.</para>
 
         <para>You can also diff against a different version
           than the one you checked out by specifying a version
           with <option>-r</option> or <option>-D</option> as in
           <command>checkout</command> or <command>update</command>,
           or even view the diffs between two arbitrary versions
           (with no regard for what you have locally) by specifying
           <emphasis>two</emphasis> versions with <option>-r</option> or
           <option>-D</option>.</para>
       </listitem>
 
       <listitem>
         <para>View log entries with the <command>log</command>
           command.</para>
 
         <screen>&prompt.user; <userinput>cvs log shazam</userinput></screen>
 
         <para>If <filename>shazam</filename> is a file, this will print a
           <emphasis>header</emphasis> with information about this file, such
           as where in the repository this file is stored, which revision is
           the <literal>HEAD</literal> for this file, what branches this file
           is in, and any tags that are valid for this file.  Then, for each
           revision of this file, a log message is printed.  This includes
           the date and time of the commit, who did the commit, how many lines
           were added and/or deleted, and finally the log message that the
           committer who did the change wrote.</para>
 
         <para>If <filename>shazam</filename> is a directory, then the log
           information described above is printed for each file in the
           directory in turn.  Unless you give the <option>-l</option> to
           <command>log</command>, the log for all subdirectories of
           <filename>shazam</filename> is printed too, in a recursive
           manner.</para>
 
         <para>Use the <command>log</command> command to view the history of
           one or more files, as it is stored in the CVS repository.  You can
           even use it to view the log message of a specific revision, if you
           add the <option>-r<replaceable>rev</replaceable></option> to the
           <command>log</command> command:</para>
 
         <screen>&prompt.user; <userinput>cvs log -r1.2 shazam</userinput></screen>
 
         <para>This will print only the log message for revision
           <literal>1.2</literal> of file <filename>shazam</filename> if it is
           a file, or the log message for revision <literal>1.2</literal> of
           each file under <filename>shazam</filename> if it is a
           directory.</para>
       </listitem>
 
       <listitem>
         <para>See who did what with the <command>annotate</command> command.
           This command shows you each line of the specified file or
           files, along with which user most recently changed that
           line.</para>
 
         <screen>&prompt.user; <userinput>cvs annotate shazam</userinput></screen>
       </listitem>
 
       <listitem>
         <para>Add new files with the <command>add</command> command.</para>
 
         <para>Create the file, <command>cvs add</command> it, then
           <command>cvs commit</command> it.</para>
 
         <para>Similarly, you can add new directories by creating them
           and then <command>cvs add</command>ing them. Note that you
           do not need to commit directories.</para>
       </listitem>
 
       <listitem>
         <para>Remove obsolete files with the <command>remove</command> command.</para>
 
         <para>Remove the file, then <command>cvs rm</command> it, then
           <command>cvs commit</command> it.</para>
       </listitem>
 
       <listitem>
         <para>Commit with the <command>commit</command> or
           <command>checkin</command> command.</para>
 
         <table frame="none">
 	  <title>Useful <command>cvs commit</command> options</title>
 	  
           <tgroup cols=2>
             <tbody>
               <row>
                 <entry><option>-f</option></entry>
                 <entry>Force a commit of an unmodified file.</entry>
               </row>
 
               <row>
                 <entry><option>-m<replaceable>msg</replaceable></option></entry>
                 <entry>Specify a commit message on the command line rather
                   than invoking an editor.</entry>
               </row>
             </tbody>
           </tgroup>
         </table>
 
         <para>Use the <option>-f</option> option if you realize that
           you left out important information from the commit message.</para>
 
         <para>Good commit messages are important. They tell others
           why you did the changes you did, not just right here and now,
           but months or years from now when someone wonders why some
           seemingly illogical or inefficient piece of code snuck into
           your source file. It is also an invaluable aid to deciding
           which changes to MFC and which not to MFC.</para>
 
 	<para>Commit messages should be clear, concise and provide
 	  a reasonable summary to give an indication of what was
 	  changed and why.</para>
 
 	<para>Commit messages should provide enough information to
 	  enable a third party to decide if the change is relevant to
 	  them and if they need to read the change itself.</para>
 
         <para>Avoid committing several unrelated changes in one go. It
           makes merging difficult, and also makes it harder to determine
           which change is the culprit if a bug crops up.</para>
 
         <para>Avoid committing style or whitespace fixes and
           functionality fixes in one go. It makes merging difficult,
           and also makes it harder to understand just what functional
           changes were made.</para>
 
         <para>Avoid committing changes to multiple files in one go
           with a generic, vague message. Instead, commit each file (or
           small groups of files) with tailored commit messages.</para>
 
         <para>Before committing, <emphasis>always</emphasis>:</para>
 
         <itemizedlist>
           <listitem>
             <para>verify which branch you are committing to, using
               <command>cvs status</command>.</para>
           </listitem>
 
           <listitem>
             <para>review your diffs, using
               <command>cvs diff</command></para>
           </listitem>
         </itemizedlist>
 
         <para>Also, ALWAYS specify which files to commit explicitly on
           the command line, so you do not accidentally commit other files
           than the ones you intended - <command>cvs commit</command>
           with no arguments will commit every modification in your
           current working directory and every subdirectory.</para>
       </listitem>
     </orderedlist>
 
     <para>Additional tips and tricks:</para>
 
     <orderedlist>
       <listitem>
 
         <para>You can place commonly used options in your
           <filename>~/.cvsrc</filename>, like this:</para>
 
         <programlisting>cvs -z3
 diff -Nu
 update -Pd
 checkout -P</programlisting>
 
         <para>This example says:</para>
 
         <itemizedlist>
           <listitem>
             <para>always use compression level 3 when talking to a
               remote server. This is a life-saver when working over a
               slow connection.</para>
           </listitem>
 
           <listitem>
             <para>always use the <option>-N</option> (show added or
               removed files) and <option>-u</option> (unified diff
               format) options to &man.diff.1;.</para>
           </listitem>
 
           <listitem>
             <para>always use the <option>-P</option> (prune empty
               directories) and <option>-d</option> (check out new
               directories) options when updating.</para>
           </listitem>
 
           <listitem>
             <para>always use the <option>-P</option> (prune empty
               directories) option when checking out.</para>
           </listitem>
         </itemizedlist>
       </listitem>
 
       <listitem>
         <para>Use Eivind Eklund's <command>cdiff</command> script to
           view unidiffs.  It is a wrapper for &man.less.1; that adds ANSI
           color codes to make hunk headers, outtakes and additions stand
           out; context and garbage are unmodified.  It also expands tabs
           properly (tabs often look wrong in diffs because of the extra
           character in front of each line).</para>
 
         <para><ulink url="http://people.FreeBSD.org/~eivind/cdiff">http://people.FreeBSD.org/~eivind/cdiff</ulink></para>
 
         <para>Simply use it instead of &man.more.1; or &man.less.1;:</para>
 
         <screen>&prompt.user; <userinput>cvs diff -Nu shazam | cdiff</userinput></screen>
 
 	<para>Alternatively some editors like &man.vim.1;
 	  (ports/editors/vim5) have color support and when used as
 	  a pager with color syntax highlighting switched on will
 	  highlight many types of file, including diffs, patches,
 	  and cvs/rcs logs. </para>
 
 	<screen>&prompt.user; <userinput> echo "syn on" >> ~/.vimrc </userinput>
 &prompt.user; <userinput> cvs diff -Nu shazam | vim -</userinput>
 &prompt.user; <userinput> cvs log shazam | vim -</userinput> </screen>
       </listitem>
 
       <listitem>
         <para>CVS is old, arcane, crufty and buggy, and sometimes
           exhibits non-deterministic behavior which some claim as proof
           that it is actually merely the Newtonian manifestation of a
           sentient transdimensional entity.  It is not humanly possible
           to know its every quirk inside out, so do not be afraid to ask
           the resident AI (&a.cvs;) for help when you screw up.</para>
       </listitem>
 
       <listitem>
         <para>Do not leave the <command>cvs commit</command> command in commit
           message editing mode for too long (more than 2-3 minutes).  It
           locks the directory you are working with and will prevent other
           developers from committing into the same directory.  If you have
           to type a long commit message, type it before executing
           <command>cvs commit</command>, and insert it into the commit
           message.</para>
       </listitem>
     </orderedlist>
 
   </sect1>
 
   <sect1 id="conventions">
     <title>Conventions and Traditions</title>
 
     <para>As a new committer there are a number of things you should do
       first.</para>
 
     <itemizedlist>
       <listitem>
 	<para>Add yourself to the <quote>Developers</quote> section of
 	  the <ulink url="../contributors/index.html">Contributors List</ulink>
 	  and remove yourself from the <quote>Additional
 	  Contributors</quote> section.</para>
 
 	<para>This is a relatively easy task, but remains a good first test of 
 	  your CVS skills.</para>
       </listitem>
 
       <listitem>
 	<para>Add an entry for yourself to
 	  <filename>www/en/news/news.xml</filename>. Look for the other
 	  entries that look like <quote>A new committer</quote> and follow the
 	  format.</para>
       </listitem>
 
       <listitem>
 	<para>If you have a PGP or GnuPG key, you may want to add it to
 	  <filename>doc/en_US.ISO8859-1/books/handbook/pgpkeys</filename>.
 	  </para>
 
 	<para>&a.des; has
 	  written a shell script to make this extremely simple.  See the
 	  <ulink
 	  url="http://cvsweb.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/pgpkeys/README">README</ulink>
 	  file for more information.</para>
       </listitem>
 
       <listitem>
 	<para>Some people add an entry for themselves to
 	  <filename>ports/astro/xearth/files/freebsd.committers.markers</filename>.</para>
       </listitem>
 
       <listitem>
 	<para>Some people add an entry for themselves to <filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>.</para>
       </listitem>
 
       <listitem>
 	<para>Introduce yourself to the other committers, otherwise no one
 	  will have any idea who you are or what you are working on.  You do
 	  not have to write a comprehensive biography, just write a paragraph
 	  or two about who you are and what you plan to be working on as a
 	  committer in FreeBSD.  Email this to the &a.developers; and you will
 	  be on your way!</para>
       </listitem>
 
       <listitem>
 	<para>Log into <hostid>hub.FreeBSD.org</hostid> and create a
 	  <filename>/var/forward/<replaceable>user</replaceable></filename>
 	  (where <replaceable>user</replaceable> is your username) file
 	  containing the e-mail address where you want mail addressed to
 	  <replaceable>yourusername</replaceable>@FreeBSD.org to be forwarded.
 	  This includes all of the commit messages as well as any other mail
 	  addressed to the &a.committers; and &a.developers;.  Really
 	  large mailboxes which have taken up permanent residence on
 	  <hostid>hub</hostid> often get <quote>accidently</quote> truncated
 	  without warning, so forward it or read it and you will not lose
 	  it.</para>
       </listitem>
     </itemizedlist>
     
     <para>All new committers also have a mentor assigned to them for
       the first few months.  Your mentor is more or less responsible for
       explaining anything which is confusing to you and is also
       responsible for your actions during this initial period.  If you
       make a bogus commit, it is only going to embarrass your mentor
       and you should probably make it a policy to pass at least your
       first few commits by your mentor before committing it to the
       repository.</para>
 
     <para>All commits should go to &os.current; first
       before being merged to &os.stable;.  No major new
       features or high-risk modifications should be made to the
       &os.stable; branch.</para>
   </sect1>
 
   <sect1 id="developer.relations">
     <title>Developer Relations</title>
 
     <para>If you are working directly on your own code or on code
       which is already well established as your responsibility, then
       there is probably little need to check with other committers
       before jumping in with a commit.  If you see a bug in an area of
       the system which is clearly orphaned (and there are a few such
       areas, to our shame), the same applies.  If, however, you are
       about to modify something which is clearly being actively
       maintained by someone else (and it is only by watching the
       <literal>cvs-committers</literal> mailing list that you can
       really get a feel for just what is and is not) then consider
       sending the change to them instead, just as you would have
       before becoming a committer.  For ports, you should contact the
       listed <makevar>MAINTAINER</makevar> in the
       <filename>Makefile</filename>.  For other parts of the
       repository, if you are unsure who the active maintainer might
       be, it may help to scan the output of <command>cvs log</command>
       to see who has committed changes in the past.  &a.fenner; has
       written a nice shell script that can help determine who the
       active maintainer might be.  It lists each person who has
       committed to a given file along with the number of commits each
       person has made.  It can be found on <hostid>freefall</hostid>
       at <filename>~fenner/bin/whodid</filename>.  If your queries go
       unanswered or the committer otherwise indicates a lack of
       proprietary interest in the area affected, go ahead and commit
       it.</para>
 
     <para>If you are unsure about a commit for any reason at
       all, have it reviewed by <literal>-hackers</literal>
       before committing.  Better to have it flamed then and there
       rather than when it is part of the CVS repository.  If you do
       happen to commit something which results in controversy
       erupting, you may also wish to consider backing the change out
       again until the matter is settled.  Remember &ndash; with CVS we
       can always change it back.</para>
   </sect1>
 
   <sect1 id="gnats">
     <title>GNATS</title>
 
     <para>The FreeBSD Project utilizes
       <application>GNATS</application> for tracking bugs and change
       requests.  Be sure that if you commit a fix or suggestion found
       in a <application>GNATS</application> PR, you use
       <command>edit-pr <replaceable>pr-number</replaceable></command>
       on <hostid>freefall</hostid> to close it.  It is also considered
       nice if you take time to close any PRs associated with your
       commits, if appropriate.  You can also make use of
       &man.send-pr.1; yourself for proposing any change which you feel
       should probably be made, pending a more extensive peer-review
       first.</para>
 
     <para>You can find out more about <application>GNATS</application>
       at:</para>
 
     <itemizedlist>
       <listitem>
 	<para><ulink url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html">http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html</ulink></para>
       </listitem>
 
       <listitem>
 	<para><ulink url="../../../../support.html">http://www.FreeBSD.org/support.html</ulink></para>
       </listitem>
 
       <listitem>
 	<para><ulink url="../../../../send-pr.html">http://www.FreeBSD.org/send-pr.html</ulink></para>
       </listitem>
 
       <listitem>
 	<para>&man.send-pr.1;</para>
       </listitem>
     </itemizedlist>
 
     <para>You can run a local copy of GNATS, and then integrate the FreeBSD
       GNATS tree in to it using CVSup.  Then you can run GNATS commands
       locally, or use other interfaces, such as <command>tkgnats</command>.
       This lets you query the PR database without needing to be connected to
       the Internet.</para>
 
     <procedure>
       <title>Using a local GNATS tree</title>
 
       <step>
 	<para>If you are not already downloading the GNATS tree, add this line 
 	  to your <filename>supfile</filename>, and re-sup. Note that since
 	  GNATS is not under CVS control it has no tag, so if you are adding
 	  it to your existing <filename>supfile</filename> it should appear
 	  before any <quote>tag=</quote> entry as these remain active once set.
 	</para>
 
 	<programlisting>gnats release=current prefix=/usr</programlisting>
 
 	<para>This will place the FreeBSD GNATS tree in
 	  <filename>/usr/gnats</filename>.  You can use a
 	  <emphasis>refuse</emphasis> file to control which categories to
 	  receive.  For example, to only receive <literal>docs</literal> PRs,
 	  put this line in
 	  <filename>/usr/local/etc/cvsup/sup/refuse</filename><footnote>
 	    <para>The precise path depends on the <literal>*default
 		base</literal> setting in your
 	      <filename>supfile</filename>.</para>
 	  </footnote>.</para>
 
 	<programlisting>gnats/[a-ce-z]*</programlisting>
 
 	<para>The rest of these examples assume you have only supped the
 	  <literal>docs</literal> category.  Adjust them as necessary,
 	  depending on the categories you are synching.</para>
       </step>
 
       <step>
 	<para>Install the GNATS port from
 	  <filename>ports/databases/gnats</filename>.  This will place the
 	  various GNATS directories under
 	  <filename>$PREFIX/share/gnats</filename>.</para>
       </step>
 
       <step>
 	<para>Symlink the GNATS directories you are supping under the version
 	  of GNATS you have installed.</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/local/share/gnats/gnats-db</userinput>
 &prompt.root; <userinput>ln -s /usr/gnats/docs</userinput></screen>
 
 	<para>Repeat as necessary, depending on how many GNATS categories you
 	  are synching.</para>
       </step>
 
       <step>
 	<para>Update the GNATS <filename>categories</filename> file with these
 	  categories.  The file is
 	  <filename>$PREFIX/share/gnats/gnats-db/gnats-adm/categories</filename>.</para>
 
 	<programlisting># This category is mandatory
 pending:Category for faulty PRs:gnats-admin:
 #
 # FreeBSD categories
 #
 docs:Documentation Bug:nik:</programlisting>
       </step>
 
       <step>
 	<para>Run <filename>$PREFIX/libexec/gnats/gen-index</filename> to
 	  recreate the GNATS index.  The output has to be redirected to
 	  <filename>$PREFIX/share/gnats/gnats-db/gnats-adm/index</filename>.
 	  You can do this periodically from &man.cron.8;, or run &man.cvsup.1; 
 	  from a shell script that does this as well.</para>
 
 	<screen>&prompt.root; <userinput>/usr/local/libexec/gnats/gen-index \
         > /usr/local/share/gnats/gnats-db/gnats-adm/index</userinput></screen>
       </step>
 
       <step>
 	<para>Test the configuration by querying the PR database.  This
 	  command shows open <literal>docs</literal> PRs.</para>
 
 	<screen>&prompt.root; <userinput>query-pr -c docs -s open</userinput></screen>
 
 	<para>Other interfaces, like
 	  <filename>ports/databases/tkgnats</filename> should also work
 	  nicely.</para>
       </step>
 
       <step>
 	<para>Pick a PR and close it.</para>
       </step>
     </procedure>
 
     <note>
       <para>This procedure only works to allow you to view and query the PRs
 	locally.  To edit or close them you will still have to log in to
 	<hostid>freefall</hostid> and do it from there.</para>
     </note>
   </sect1>
 
   <sect1 id="people">
     <title>Who's Who</title>
 
     <para>Besides Peter Wemm and John Polstra, the repository
     meisters, there are other FreeBSD project members whom you will
     probably get to know in your role as a committer.  Briefly,
     and by no means all-inclusively, these are:</para>
 
     <variablelist>
 
       <varlistentry>
 	<term>&a.jhb;</term>
 
 	<listitem>
 	  <para>John is the manager of the SMPng Project, and has
 	    authority over the architectural design and implementation
 	    of the move to fine-grained kernel threading and locking.
 	    He's also the editor of the SMPng Architecture Document.
 	    If you're working on fine-grained SMP and locking, please
 	    coordinate with John.  You can learn more about the
 	    SMPng Project on its home page: <ulink
 	    url="http://www.FreeBSD.org/smp/">
 	    http://www.FreeBSD.org/smp/</ulink></para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.jake;, &a.tmm;</term>
 
 	<listitem>
 	  <para>Jake and Thomas are the maintainers of the sparc64 hardware
 	    port.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.nik;</term>
 	
 	<listitem>
 	  <para>Nik oversees the
 	    <ulink url="../../../../docproj/index.html">Doc. Project</ulink>.
 	    As well as writing documentation he put together the
 	    infrastructure under <filename>doc/share/mk</filename> and the
 	    stylesheets and related code under
 	    <filename>doc/share/sgml</filename>.  If you have got questions
 	    about these you are encouraged to send them via the &a.doc;.
 	    Committers interested in contributing to the documentation should
 	    familiarise themselves with the
 	    <ulink url="../../books/fdp-primer/index.html">Documentation Project Primer</ulink>.</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term>&a.ru;</term>
 	
 	<listitem>
 	  <para>Ruslan is Mister &man.mdoc.7;.  If you are writing a
 	    man page and need
 	    some advice on the structure, or the markup, ask Ruslan.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.bde;</term>
 	
 	<listitem>
 	  <para>Bruce is the Style Police-Meister.
 	    When you do a commit that could have been done better,
 	    Bruce will be there to tell you.  Be thankful that someone
 	    is.  Bruce is also very knowledgeable on the various
 	    standards applicable to FreeBSD.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.gallatin;</term>
 	<term>&a.mjacob;</term>
 	<term>&a.dfr;</term>
 	<term>&a.obrien;</term>
 	
 	<listitem>
 	  <para>These are the primary developers and overseers of the
 	  DEC Alpha AXP platform.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.dg;</term>
 	
 	<listitem>
 	  <para>David is the overseer of the
 	    VM system.  If you have a VM system change in mind,
 	    coordinate it with David.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.murray;</term>
 	<term>&a.steve;</term>
 	<term>&a.rwatson;</term>
 	<term>&a.jhb;</term>
 
         <listitem>
           <para>These are the members of the &a.re;.  This team is
             responsible for setting release deadlines and controlling
             the release process.  During code freezes, the release
             engineers have final authority on all changes to the
             system for whichever branch is pending release status.  If
             there is something you want merged from &os.current; to
             &os.stable; (whatever values those may have at any given
             time), these are the people to talk to about it.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.bmah;</term>
 
 	<listitem>
 	  <para>Bruce is keeper of the release documentation
 	    (<filename>src/release/doc/*</filename>).  If you commit a
 	    change that you think is worthy of mention in the release notes,
 	    please make sure Bruce knows about it.  Better still, send him
 	    a patch with your suggested commentary.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.obrien;</term>
 	
 	<listitem>
 	  <para>David is the unofficial <filename>src/contrib</filename>-Meister.
 	    If you have something
 	    significant you would like to do there, you should probably
 	    coordinate it with David first.  Please consult him before
 	    importing into <filename>src/contrib</filename> if you have
 	    never done this before in the FreeBSD CVS repository.  Also
 	    if you need to commit to something you do not maintain in
 	    <filename>src/contrib</filename> and it is unclear who the
 	    maintainer / point of contact is.  (It is also not a bad idea
 	    to consult David if you need to make a non-import commit to
 	    something you maintain in <filename>src/contrib</filename> and
 	    you are new to how FreeBSD does things.)</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.benno;</term>
 
 	<listitem>
 	  <para>Benno is the official maintainer of the PowerPC port.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.brian;</term>
 	
 	<listitem>
 	  <para>Official maintainer of
 	    <filename>/usr/sbin/ppp</filename>.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
         <term>&a.nectar;</term>
 
         <listitem>
           <para>Jacques is the 
           <ulink url="../../../../security/">FreeBSD Security 
           Officer</ulink> 
           and oversees the Security Officer Team.
           </para>
         </listitem>
       </varlistentry>
  
       <varlistentry>
 	<term>&a.wollman;</term>
 	
 	<listitem>
 	  <para>If you need advice on obscure network internals or
 	    are not sure of some potential change to the networking
 	    subsystem you have in mind, Garrett is someone to talk
 	    to.  Garrett is also very knowledgeable on the various
 	    standards applicable to FreeBSD.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.committers;</term>
 	
 	<listitem>
 	  <para>cvs-committers is the entity that CVS uses to send you all your
 	    commit messages.  You should <emphasis>never</emphasis> send email
 	    directly to this list.  You should only send replies to this list
 	    when they are short and are directly related to a commit.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>&a.developers;</term>
 	
 	<listitem>
 	  <para>developers is all committers.  This list was created to be a
 	    forum for the committers <quote>community</quote> issues.
 	    Examples are Core
 	    voting, announcements, etc...  developers@FreeBSD.org is
 	    <emphasis>not</emphasis> intended as a place for code reviews or a
 	    replacement for the &a.arch; or the &a.audit;.  In fact
 	    using it as such hurts the FreeBSD Project as it gives a sense of a
 	    closed list where general decisions affecting all of the FreeBSD
 	    using community are made without being <quote>open</quote>.
 	    Last, but not least <emphasis>never, never ever, email
 	    developers@FreeBSD.org and CC:/BCC: another FreeBSD list</emphasis>.
 	    Never, ever email another FreeBSD email list and CC:/BCC:
 	    developers@FreeBSD.org.  Doing so can greatly diminish the benefits
 	    of this list.
 			</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
   <sect1 id="ssh.guide">
     <title>SSH Quick-Start Guide</title>
 
     <procedure>
       <step>
 	<para>If you are using FreeBSD 4.0 or later,
 	  OpenSSH is included in the base system.
 	  If you are using an earlier release,
 	  update and install one of the SSH ports.  In general,
 	  you will probably want to get OpenSSH from the port in
 	  <filename>/usr/ports/security/openssh</filename>.  You
 	  may also wish to check out the original ssh1 in
 	  <filename>/usr/ports/security/ssh</filename>, but make
 	  certain you pay attention to its license.  Note that both
 	  of these ports cannot be installed at the same time.</para>
       </step>
 
       <step>
 	<para>If you do not wish to type your password in every
 	  time you use &man.ssh.1;, and you use RSA keys to
 	  authenticate, &man.ssh-agent.1; is there for your
 	  convenience.  If you want to use &man.ssh-agent.1;, make
 	  sure that you run it before running other applications.  X
 	  users, for example, usually do this from their
 	  <filename>.xsession</filename> or
 	  <filename>.xinitrc</filename> file.  See &man.ssh-agent.1;
 	  for details.</para>
       </step>
       
       <step>
 	<para>Generate a key pair using &man.ssh-keygen.1;.  The key
 	  pair will wind up in the
 	  <filename><envar>$HOME</envar>/.ssh</filename>
 	  directory.</para>
       </step>
 
       <step>
 	<para>Send your public key
 	  (<filename><envar>$HOME</envar>/.ssh/identity.pub</filename>)
 	  to the person setting you up as a committer so it can be put
 	  into your <filename>authorized_keys</filename> file in your
 	  home directory on <hostid>freefall</hostid>
 	  (i.e.
 	  <filename><envar>$HOME</envar>/.ssh/authorized_keys</filename>).
 	</para>
       </step>
     </procedure>
     
     <para>Now you should be able to use &man.ssh-add.1; for
       authentication once per session.  This will prompt you for
       your private key's pass phrase, and then store it in your
       authentication agent (&man.ssh-agent.1;).  If you no longer
       wish to have your key stored in the agent, issuing
       <command>ssh-add -d</command> will remove it.</para>
     
     <para>Test by doing something such as <command>ssh
 	freefall.FreeBSD.org ls /usr</command>.</para>
 
     <para>For more information, see
       <filename>/usr/ports/security/openssh</filename>, &man.ssh.1;,
       &man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and
       &man.scp.1;.</para>
   </sect1>
 
   <sect1>
     <title>The FreeBSD Committers' Big List of Rules</title>
 
     <orderedlist>
       <listitem>
         <para>Respect other committers.</para>
       </listitem>
 
       <listitem>
         <para>Respect other contributors.</para>
       </listitem>
 
       <listitem>
 	<para>Discuss any significant change
 	  <emphasis>before</emphasis> committing.</para>
       </listitem>
 
       <listitem>
 	<para>Respect existing maintainers (if listed in the
 	  <makevar>MAINTAINER</makevar> field in
 	  <filename>Makefile</filename> or in the
 	  <filename>MAINTAINER</filename> file in the top-level
 	  directory).</para>
       </listitem>
 
       <listitem>
 	<para>Never touch the repository directly.  Ask a
 	  Repomeister.</para>
       </listitem>
 
       <listitem>
 	<para>Any disputed change must be backed out pending
 	  resolution of the dispute if requested by a maintainer.
 	  Security related changes may
 	  override a maintainer's wishes at the Security Officer's
 	  discretion.</para>
       </listitem>
 
       <listitem>
 	<para>Changes go to &os.current; before
 	  &os.stable; unless specifically permitted by
 	  the release engineer or unless they are not applicable to
 	  &os.current;.  Any non-trivial or non-urgent
 	  change which is applicable should also be allowed to sit in
 	  &os.current; for at least 3 days before
 	  merging so that it can be given sufficient testing.  The
 	  release engineer has the same authority over the
 	  &os.stable; branch as outlined for the
 	  maintainer in rule #6.</para>
       </listitem>
 
       <listitem>
 	<para>Do not fight in public with other committers; it looks
 	  bad.  If you must <quote>strongly disagree</quote> about
 	  something, do so only in private.</para>
       </listitem>
 
       <listitem>
 	<para>Respect all code freezes and read the
 	  <literal>committers</literal> mailing list in a timely manner
 	  so you know when a code freeze is in effect.</para>
       </listitem>
 
       <listitem>
 	<para>When in doubt on any procedure, ask first!</para>
       </listitem>
 
       <listitem>
 	<para>Test your changes before committing them.</para>
       </listitem>
 
       <listitem>
 	<para>Do not commit to anything under the
 	  <filename>src/contrib</filename>,
 	  <filename>src/crypto</filename>, and
 	  <filename>src/sys/contrib</filename> trees without
 	  <emphasis>explicit</emphasis> approval from the respective
 	  maintainer(s).</para>
       </listitem>
     </orderedlist>
 
     <para>As noted, breaking some of these rules can be grounds for
       suspension or, upon repeated offense, permanent removal of
       commit privileges.  Three or more members of core
       acting in unison,
       have the power to temporarily suspend commit privileges until
       <literal>-core</literal> as a whole has the chance to review the
       issue.  In case of an <quote>emergency</quote> (a committer
       doing damage to the repository), a temporary suspension may also
       be done by the repository meisters or any other member of core
       who may happen to be awake at the time.  Only core as a whole
       has the authority to suspend commit privileges for any
       significant length of time or to remove them permanently, the
       latter generally only being done after consultation with
       committers.  This rule does not exist to set core up as a bunch
       of cruel dictators who can dispose of committers as casually as
       empty soda cans, but to give the project a kind of safety fuse.
       If someone is seriously out of control, it is important to be
       able to deal with this immediately rather than be paralyzed by
       debate.  In all cases, a committer whose privileges are
       suspended or revoked is entitled to a <quote>hearing</quote>,
       the total duration of the suspension being determined at that
       time.  A committer whose privileges are suspended may also
       request a review of the decision after 30 days and every 30 days
       thereafter (unless the total suspension period is less than 30
       days).  A committer whose privileges have been revoked entirely
       may request a review after a period of 6 months have elapsed.
       This review policy is <emphasis>strictly informal</emphasis>
       and, in all cases, core reserves the right to either act on or
       disregard requests for review if they feel their original
       decision to be the right one.</para>
     
     <para>In all other aspects of project operation, core is a subset
       of committers and is bound by the <emphasis>same
       rules</emphasis>.  Just because someone is in core does not mean
       that they have special dispensation to step outside of any of
       the lines painted here; core's <quote>special powers</quote>
       only kick in when it acts as a group, not on an individual
       basis.  As individuals, we are all committers first and core
       second.</para>
     
     <sect2>
       <title>Details</title>
 
       <orderedlist>
 	<listitem id="respect">
 	  <para>Respect other committers.</para>
 
 	  <para>This means that you need to treat other committers as
 	    the peer-group developers that they are.  Despite our
 	    occasional attempts to prove the contrary, one does not get
 	    into committers by being stupid and nothing rankles more
 	    than being treated that way by one of your peers.  Whether
 	    we always feel respect for one another or not (and
 	    everyone has off days), we still have to
 	    <emphasis>treat</emphasis> other committers with respect
 	    at all times or the whole team structure rapidly breaks
 	    down.</para>
 	  
 	  <para>Being able to work together long term is this project's
 	    greatest asset, one far more important than any set of
 	    changes to the code, and turning arguments about code into
 	    issues that affect our long-term ability to work
 	    harmoniously together is just not worth the trade-off by
 	    any conceivable stretch of the imagination.</para>
 	  
 	  <para>To comply with this rule, do not send email when you are
 	    angry or otherwise behave in a manner which is likely to
 	    strike others as needlessly confrontational.  First calm
 	    down, then think about how to communicate in the most
 	    effective fashion for convincing the other person(s) that
 	    your side of the argument is correct, do not just blow off
 	    some steam so you can feel better in the short term at the
 	    cost of a long-term flame war.  Not only is this very bad
 	    <quote>energy economics</quote>, but repeated displays of
 	    public aggression which impair our ability to work well
 	    together will be dealt with severely by the project
 	    leadership and may result in suspension or termination of
 	    your commit privileges.  That is never an option which the
 	    project's leadership enjoys in the slightest, but unity
 	    comes first.  No amount of code or good advice is worth
 	    trading that away.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Respect other contributors.</para>
 
 	  <para>You were not always a committer. At one time you were 
 	    a contributor. Remember that at all times. Remember what 
 	    it was like trying to get help and attention.  Do not forget
 	    that your work as a contributor was very important to 
 	    you.  Remember what it was like. Do not discourage, belittle, 
 	    or demean contributors.  Treat them with respect.  They are 
 	    our committers in waiting.  They are every bit as important 
 	    to the project as committers. Their contributions are as 
 	    valid and as important as your own.  After all, you made 
 	    many contributions before you became a committer.  Always 
 	    remember that.  </para>
 
 	  <para>Consider the points raised under <xref linkend="respect">
 	    and apply them also to contributors.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Discuss any significant change
 	    <emphasis>before</emphasis> committing.</para>
 	  
 	  <para>The CVS repository is not where changes should be
 	    initially submitted for correctness or argued over, that
 	    should happen first in the mailing lists and then
 	    committed only once something resembling consensus has
 	    been reached.  This does not mean that you have to ask
 	    permission before correcting every obvious syntax error or
 	    man page misspelling, simply that you should try to
 	    develop a feel for when a proposed change is not quite such
 	    a no-brainer and requires some feedback first.  People
 	    really do not mind sweeping changes if the result is
 	    something clearly better than what they had before, they
 	    just do not like being <emphasis>surprised</emphasis> by
 	    those changes.  The very best way of making sure that
 	    you are on the right track is to have your code reviewed by
 	    one or more other committers.</para>
 
 	  <para>When in doubt, ask for review!</para>
 	</listitem>
 
 	<listitem>
 	  <para>Respect existing maintainers if listed.</para>
 
 	  <para>Many parts of FreeBSD are not <quote>owned</quote> in
 	    the sense that any specific individual will jump up and
 	    yell if you commit a change to <quote>their</quote> area,
 	    but it still pays to check first.  One convention we use
 	    is to put a maintainer line in the
 	    <filename>Makefile</filename> for any package or subtree
 	    which is being actively maintained by one or more people;
 	    see <ulink
 	    url="../../books/developers-handbook/policies.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html</ulink>
 	    for documentation on this.  Where sections of code have
 	    several maintainers, commits to affected areas by one
 	    maintainer need to be reviewed by at least one other
 	    maintainer.  In cases where the
 	    <quote>maintainer-ship</quote> of something is not clear,
 	    you can also look at the CVS logs for the file(s) in
 	    question and see if someone has been working recently or
 	    predominantly in that area.</para>
 
 	  <para>Other areas of FreeBSD fall under the control of
 	    someone who manages an overall category of FreeBSD
 	    evolution, such as internationalization or networking.
 	    See <ulink
 	    url="../contributors/staff-who.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/staff-who.html</ulink> for more information on this.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>Never touch the repository directly.  Ask a
 	    Repomeister.</para>
 
 	  <para>This is pretty clear - you are not allowed to make
 	    direct modifications to the CVS repository, period.  In
 	    case of difficulty, ask one of the repository meisters by
 	    sending mail to the &a.cvs; and simply
 	    wait for them to fix the problem and get back to you. Do
 	    not attempt to fix the problem yourself!</para>
 	  
 	  <para>If you are thinking about putting down a tag or doing a
 	    new import of code on a vendor branch, you might also find
 	    it useful to ask for advice first.  A lot of people get
 	    this wrong the first few times and the consequences are
 	    expensive in terms of files touched and angry CVSup/CTM
 	    folks who are suddenly getting a lot of changes sent over
 	    unnecessarily.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Any disputed change must be backed out pending
 	    resolution of the dispute if requested by a maintainer.
 	    Security related changes may
 	    override a maintainer's wishes at the Security Officer's
 	    discretion.</para>
 	  
 	  <para>This may be hard to swallow in times of conflict (when
 	    each side is convinced that they are in the right, of
 	    course) but CVS makes it unnecessary to have an ongoing
 	    dispute raging when it is far easier to simply reverse the
 	    disputed change, get everyone calmed down again and then
-	    try and figure out how best to proceed.  If the change
+	    try to figure out what is the best way to proceed.  If the change
 	    turns out to be the best thing after all, it can be easily
 	    brought back. If it turns out not to be, then the users
 	    did not have to live with the bogus change in the tree
 	    while everyone was busily debating its merits.  People
 	    very very rarely call for back-outs in the repository
 	    since discussion generally exposes bad or controversial
 	    changes before the commit even happens, but on such rare
 	    occasions the back-out should be done without argument so
 	    that we can get immediately on to the topic of figuring
 	    out whether it was bogus or not.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Changes go to &os.current; before
 	    &os.stable; unless specifically permitted
 	    by the release engineer or unless they are not applicable
 	    to &os.current;.  Any non-trivial or
 	    non-urgent change which is applicable should also be
 	    allowed to sit in &os.current; for at least
 	    3 days before merging so that it can be given sufficient
 	    testing.  The release engineer has the same authority over
 	    the &os.stable; branch as outlined in rule
 	    #6.</para>
 	
 	  <para>This is another <quote>do not argue about it</quote>
 	    issue since it is the release engineer who is ultimately
 	    responsible (and gets beaten up) if a change turns out to
 	    be bad.  Please respect this and give the release engineer
 	    your full cooperation when it comes to the
 	    &os.stable; branch.  The management of
 	    &os.stable; may frequently seem to be
 	    overly conservative to the casual observer, but also bear
 	    in mind the fact that conservatism is supposed to be the
 	    hallmark of &os.stable; and different rules
 	    apply there than in &os.current;.  There is
 	    also really no point in having &os.current;
 	    be a testing ground if changes are merged over to
 	    &os.stable; immediately.  Changes need a
 	    chance to be tested by the &os.current;
 	    developers, so allow some time to elapse before merging
 	    unless the &os.stable; fix is critical,
 	    time sensitive or so obvious as to make further testing
 	    unnecessary (spelling fixes to man pages, obvious bug/typo
 	    fixes, etc.)  In other words, apply common sense.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Do not fight in public with other committers; it looks
 	    bad.  If you must <quote>strongly disagree</quote> about
 	    something, do so only in private.</para>
 	  
 	  <para>This project has a public image to uphold and that
 	    image is very important to all of us, especially if we are
 	    to continue to attract new members.  There will be
 	    occasions when, despite everyone's very best attempts at
 	    self-control, tempers are lost and angry words are
-	    exchanged, and the best we can do is try and minimize the
+	    exchanged.  The best thing that can be done in such cases is to minimize the
 	    effects of this until everyone has cooled back down.  That
 	    means that you should not air your angry words in public
 	    and you should not forward private correspondence to
 	    public mailing lists or aliases.  What people say
 	    one-to-one is often much less sugar-coated than what they
 	    would say in public, and such communications therefore
 	    have no place there - they only serve to inflame an
 	    already bad situation. If the person sending you a
 	    flame-o-gram at least had the grace to send it privately,
 	    then have the grace to keep it private yourself.  If you
 	    feel you are being unfairly treated by another developer,
 	    and it is causing you anguish, bring the matter up with
 	    core rather than taking it public.  We will do our best to
 	    play peace makers and get things back to sanity.  In cases
 	    where the dispute involves a change to the codebase and
 	    the participants do not appear to be reaching an amicable
 	    agreement, core may appoint a mutually-agreeable 3rd party
 	    to resolve the dispute.  All parties involved must then
 	    agree to be bound by the decision reached by this 3rd
 	    party.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Respect all code freezes and read the
 	    <literal>committers</literal> mailing list on a timely
 	    basis so you know when they are.</para>
 	  
 	  <para>Committing changes during a code freeze is a really
 	    big mistake and committers are expected to keep up-to-date
 	    on what is going on before jumping in after a long absence
 	    and committing 10 megabytes worth of accumulated stuff.
 	    People who abuse this on a regular basis will have their
 	    commit privileges suspended until they get back from the
 	    FreeBSD Happy Reeducation Camp we run in Greenland.</para>
 	</listitem>
 
 	<listitem>
 	  <para>When in doubt on any procedure, ask first!</para>
 
 	  <para>Many mistakes are made because someone is in a hurry
 	    and just assumes they know the right way of doing
 	    something.  If you have not done it before, chances are
 	    good that you do not actually know the way we do things
 	    and really need to ask first or you are going to
 	    completely embarrass yourself in public.  There is no shame
 	    in asking <quote>how in the heck do I do this?</quote> We
 	    already know you are an intelligent person; otherwise, you
 	    would not be a committer.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Test your changes before committing them.</para>
 	  
 	  <para>This may sound obvious, but if it really were so
 	    obvious then we probably would not see so many cases of
 	    people clearly not doing this.  If your changes are to the
 	    kernel, make sure you can still compile both GENERIC and
 	    LINT.  If your changes are anywhere else, make sure you
 	    can still make world.  If your changes are to a branch,
 	    make sure your testing occurs with a machine which is
 	    running that code.  If you have a change which also may
 	    break another architecture, be sure and test on all
 	    supported architectures.  Currently, this is only the x86
 	    and the Alpha so it is pretty easy to do.  If you need to
 	    test on the AXP, your account on <hostid
 	    role="fqdn">beast.FreeBSD.org</hostid> will let you
 	    compile and test Alpha binaries/kernels/etc.  As other
 	    architectures are added to the FreeBSD supported platforms
 	    list, the appropriate shared testing resources will be
 	    made available.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Do not commit to anything under the
 	    <filename>src/contrib</filename>,
 	    <filename>src/crypto</filename>, and
 	    <filename>src/sys/contrib</filename> trees without
 	    <emphasis>explicit</emphasis> approval from the respective
 	    maintainer(s).</para>
 
 	  <para>The trees mentioned above are for contributed software
 	    usually imported onto a vendor branch.  Committing something
 	    there, even if it does not take the file off the vendor branch,
 	    may cause unnecessary headaches for those responsible for
 	    maintaining that particular piece of software.  Thus, unless
 	    you have <emphasis>explicit</emphasis> approval from the
 	    maintainer (or you are the maintainer), do
 	    <emphasis>not</emphasis> commit there!</para>
 
 	  <para>Please note that this does not mean you should not try to
 	    improve the software in question; you are still more than
 	    welcome to do so.  Ideally, you should submit your patches to
 	    the vendor.  If your changes are FreeBSD-specific, talk to the
 	    maintainer; they may be willing to apply them locally.  But
 	    whatever you do, do <emphasis>not</emphasis> commit there by
 	    yourself!</para>
 
 	  <para>Contact the &a.core; if you wish to take up maintainership
 	    of an unmaintained part of the tree.</para>
 	</listitem>
       </orderedlist>
     </sect2>
 
     <sect2>
       <title>Other Suggestions</title>
 
       <para>When committing documentation changes, use a spell checker
 	before committing. :) For all SGML docs, you should also
 	verify that your formatting directives are correct by running
 	<command>make lint</command>.</para>
 
       <para>For all on-line manual pages, run <command>manck</command>
 	(from ports) over the man page to verify all of the cross
 	references and file references are correct and that the man
 	page has all of the appropriate <makevar>MLINK</makevar>s
 	installed.</para>
 
       <para>Do not mix style fixes with new functionality.  A style
 	fix is any change which does not modify the functionality of
 	the code.  Mixing the changes obfuscates the functionality
 	change when using <command>cvs diff</command>, which can hide
 	any new bugs.  Do not include whitespace changes with content
 	changes in commits to <filename>doc/</filename> or
 	<filename>www/</filename>.  The extra clutter in the diffs
 	makes the translators' job much more difficult.  Instead, make
 	any style or whitespace changes in separate commits that are
 	clearly labeled as such in the commit message.</para>
     </sect2>
 
     <sect2>
       <title>Deprecating Features</title>
 
       <para>When it is necessary to remove functionality from software
 	in the base system the following guidelines should be followed
 	whenever possible:</para>
 
       <orderedlist>
 	<listitem>
 	  <para>Mention is made in the manual page and possibly the
 	    release notes that the option, utility, or interface is
 	    deprecated.  Use of the deprecated feature generates a
 	    warning.</para>
 	</listitem>
  
 	<listitem>
 	  <para>The option, utility, or interface is preserved until
 	    the next major (point zero) release.</para>
 	</listitem>
 
 	<listitem>
 	  <para>The option, utility, or interface is removed and no
 	    longer documented.  It is now obsolete.  It is also
 	    generally a good idea to note its removal in the release
 	    notes.</para>
 	</listitem>
       </orderedlist>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Ports Specific FAQ</title>
 
     <qandaset>
       <qandadiv>
 	<title>Adding a New Port</title>
 
 	<qandaentry>
 	  <question>
 	    <para>How do I add a new port?</para>
 	  </question>
 
 	  <answer>
 	    <para>First, please read the section about repository
 	      copy.</para>
 
 	    <para>The easiest way to add a new port is to use the
 	      <command>addport</command> script on
 	      <hostid>freefall</hostid>.  It will add a port from the
 	      directory you specify, determining the category automatically
 	      from the port <filename>Makefile</filename>.
 	      It will also add an entry to the
 	      <filename>CVSROOT/modules</filename> file and the port's
 	      category <filename>Makefile</filename>.  It was
 	      written by &a.mharo; and &a.will;, but Will is the current
 	      maintainer so please send questions/patches about
 	      <command>addport</command> to him.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Any other things I need to know when I add a new
 	      port?</para>
 	  </question>
 
 	  <answer>
 	    <para>Check the port, preferably to make sure it compiles
 	      and packages correctly.  This is the recommended
 	      sequence:</para>
 
 	    <screen>&prompt.root; <userinput>make install</userinput>
 &prompt.root; <userinput>make package</userinput>
 &prompt.root; <userinput>make deinstall</userinput>
 &prompt.root; <userinput>pkg_add <replaceable>package you built above</replaceable></userinput>
 &prompt.root; <userinput>make deinstall</userinput>
 &prompt.root; <userinput>make reinstall</userinput>
 &prompt.root; <userinput>make package</userinput>
 	    </screen>
 
 	    <para>The 
 	      <ulink url="../../books/porters-handbook/index.html">Porters
 	      Handbook</ulink> contains more detailed
 	      instructions.</para>
 
 	    <para>Use &man.portlint.1; to check the syntax of the port.
 	      You do not necessarily have to eliminate all warnings but
 	      make sure you have fixed the simple ones.</para>
 
 	    <para>If the port came from a submitter who has not
 	      contributed to the project before, add that person's
 	      name to the <ulink
 	      url="../contributors/contrib-additional.html">Additional
 	      Contributors</ulink> section of the FreeBSD Contributors
 	      List.</para>
 
 	    <para>Close the PR if the port came in as a PR.  To close
 	      a PR, just do 
 	      <userinput>edit-pr <replaceable>PR#</replaceable></userinput>
 	      on <hostid>freefall</hostid> and change the
 	      <varname>state</varname> from <constant>open</constant>
 	      to <constant>closed</constant>.  You will be asked to
 	      enter a log message and then you are done.</para>
 	  </answer>
 	</qandaentry>
       </qandadiv>
 
       <qandadiv>
 	<title>Repository Copies</title>
 
 	<qandaentry>
 	  <question>
 	    <para>When do we need a repository copy?</para>
 	  </question>
 
 	  <answer>
 	    <para>When you want to add a port that is related to
 	      any port that is already in the tree in a separate
 	      directory, please send mail to the ports manager asking
 	      about it.  Here <wordasword>related</wordasword> means
 	      it is a different version or a slightly modified
 	      version.  Examples are
 	      <filename>print/ghostscript*</filename> (different
 	      versions) and <filename>x11-wm/windowmaker*</filename>
 	      (English-only and internationalized version).</para>
 
 	    <para>Another example is when a port is moved from one
 	      subdirectory to another, or when you want to change the
 	      name of a directory because the author(s) renamed their
 	      software even though it is a
 	      descendant of a port already in a tree.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>When do we <emphasis>not</emphasis> need a
 	      repository copy?</para>
 	  </question>
 
 	  <answer>
 	    <para>When there is no history to preserve.  If a port is
 	      added into a wrong category and is moved immediately,
 	      it suffices to simply <command>cvs remove</command> the
 	      old one and <command>addport</command> the new
 	      one.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>What do I need to do?</para>
 	  </question>
 
 	  <answer>
 	    <para>Send mail to the ports manager, who will do a copy
 	      from the old location/name to the new location/name.
 	      You will then get a notice, at which point you are
 	      expected to perform the following:</para>
 
 	    <procedure>
 	      <step>
 		<para><command>cvs remove</command> the old port (if
 		  necessary)</para>
 	      </step>
 
 	      <step>
 		<para>Adjust the parent (category)
 		  <filename>Makefile</filename></para>
 	      </step>
 
 	      <step>
 		<para>Update <filename>CVSROOT/modules</filename></para>
 	      </step>
 
 	      <step>
 		<para>If other ports depend on the updated port,
 		  change their <filename>Makefile</filename>s'
 		  dependency lines</para>
 	      </step>
 
 	      <step>
 		<para>If the port changed categories, modify the
 		  <makevar>CATEGORIES</makevar> line of the port's
 		  <filename>Makefile</filename> accordingly</para>
 	      </step>
 	    </procedure>
 	  </answer>
 	</qandaentry>
       </qandadiv>
 
       <qandadiv>
 	<title>Ports Freeze</title>
 
 	<qandaentry>
 	  <question>
 	    <para>What is a <quote>ports freeze</quote>?</para>
 	  </question>
 
 	  <answer>
 	    <para>Before a release, it is necessary to restrict
 	      commits to the ports tree for a short period of time
 	      while the packages and the release itself are being
 	      built.  This is to ensure consistency among the various
 	      parts of the release, and is called the <quote>ports
 	      freeze</quote>.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>How long is a ports freeze?</para>
 	  </question>
 
 	  <answer>
 	    <para>Usually an hour or two.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>What does it mean to me?</para>
 	  </question>
 
 	  <answer>
 	    <para>During the ports freeze, you are not allowed to
 	      commit anything to the tree without explicit approval
 	      from the ports manager.  <quote>Explicit
 	      approval</quote> here means either of the
 	      following:</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para>You asked the ports manager and got a reply
 		  saying, <quote>Go ahead and commit
 		  it.</quote></para>
 	      </listitem>
 
 	      <listitem>
 		<para>The ports manager sent a mail to you or the
 		  mailing lists during the ports freeze pointing out
 		  that the port is broken and has to be fixed.</para>
 	      </listitem>
 	    </itemizedlist>
 
 	    <para>Note that you do not have implicit permission to fix
 	      a port during the freeze just because it is
 	      broken.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>How do I know when the ports freeze starts?</para>
 	  </question>
 
 	  <answer>
 	    <para>The ports manager will send out warning messages to
 	      the &a.ports; and &a.committers;
 	      announcing the start of the impending release, usually
 	      two or three weeks in advance.  The exact starting time
 	      will not be determined until a few days before the
 	      actual release.  This is because the ports freeze has to
 	      be synchronized with the release, and it is usually not
 	      known until then when exactly the release will be
 	      rolled.</para>
 
 	    <para>When the freeze starts, there will be another
 	      announcement to the &a.committers;, of course.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>How do I know when the ports freeze ends?</para>
 	  </question>
 
 	  <answer>
 	    <para>A few hours after the release, the ports manager
 	      will send out a mail to the &a.ports; and &a.committers;
 	      announcing the end of the ports freeze.  Note that the
 	      release being cut does not automatically end the freeze.
 	      We have to make sure there will not be any last minute
 	      snafus that result in an immediate re-rolling of the
 	      release.</para>
 	  </answer>
 	</qandaentry>
       </qandadiv>
 
       <qandadiv>
 	<title>Miscellaneous Questions</title>
 
 	<qandaentry>
 	  <question>
 	    <para>How do I know if my port is building correctly or
 	      not?</para>
 	  </question>
 
 	  <answer>
 	    <para>First, go check
 	      <ulink url="http://bento.FreeBSD.org/~asami/errorlogs/">http://bento.FreeBSD.org/~asami/errorlogs/</ulink>.
 
 	      There you will find error logs from the latest package
 	      building runs on 3-stable, 4-stable and 5-current.</para>
 
 	    <para>However, just because the port does not show up there
 	      does not mean it is building correctly.  (One of the
 	      dependencies may have failed, for instance.)  Here are
 	      the relevant directories on bento, so feel free to dig
 	      around.</para>
 
 	    <programlisting> /a/asami/portbuild/3/errors        error logs from latest 3-stable run
                      /logs          all logs from latest 3-stable run
                      /packages      packages from latest 3-stable run
                      /bak/errors    error logs from last complete 3-stable run
                      /bak/logs      all logs from last complete 3-stable run
                      /bak/packages  packages from last complete 3-stable run
                    /4/errors        error logs from latest 4-stable run
                      /logs          all logs from latest 4-stable run
                      /packages      packages from latest 4-stable run
                      /bak/errors    error logs from last complete 4-stable run
                      /bak/logs      all logs from last complete 4-stable run
                      /bak/packages  packages from last complete 4-stable run
                    /5/errors        error logs from latest 5-current run
                      /logs          all logs from latest 5-current run
                      /packages      packages from latest 5-current run
                      /bak/errors    error logs from last complete 5-current run
                      /bak/logs      all logs from last complete 5-current run
                      /bak/packages  packages from last complete 5-current run
 	    </programlisting>
 
 	    <para>Basically, if the port shows up in
 	      <filename>packages</filename>, or it is in
 	      <filename>logs</filename> but not in
 	      <filename>errors</filename>, it built fine.  (The
 	      <filename>errors</filename> directories are what you get
 	      from the web page.)</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>I added a new port.  Do I need to add it to the
 	      <filename>INDEX</filename>?</para>
 	  </question>
 
 	  <answer>
 	    <para>No.  The ports manager will regenerate the
 	      <filename>INDEX</filename> and commit it every few
 	      days.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Are there any other files I am not allowed to
 	      touch?</para>
 	  </question>
 
 	  <answer>
 	    <para>Any file directly under <filename>ports/</filename>, or
 	      any file under a subdirectory that starts with an
 	      uppercase letter (<filename>Mk/</filename>,
 	      <filename>Tools/</filename>, etc.).  In particular, the
 	      ports manager is very protective of
 	      <filename>ports/Mk/bsd.port*.mk</filename> so do not
 	      commit changes to those files unless you want to face his
 	      wra(i)th.</para>
 	  </answer>
 	</qandaentry>
       </qandadiv>
     </qandaset>
   </sect1>
 
   <sect1>
     <title>Perks of the Job</title>
 
     <para>Unfortunately, there aren't many perks involved with being a
       committer.  Recognition as a competent software engineer is probably
       the only thing that will be of benefit in the long run.  However,
       there are at least some perks:</para>
 
     <variablelist>
 
       <varlistentry>
 	<term>Direct access to <hostid>cvsup-master</hostid></term>
 
 	<listitem>
 	  <para>As a committer, you may apply to &a.jdp; for direct access
 	    to <hostid role="fqdn">cvsup-master.FreeBSD.org</hostid>,
 	    providing the public key output from <command>cvpasswd
 	    <replaceable>yourusername</replaceable>@FreeBSD.org
 	    cvsup-master.FreeBSD.org</command>.  Access to
 	    <hostid>cvsup-master</hostid> should not be over-used as it is
 	    a busy machine.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>A Free DVD Subscription</term>
 
 	<listitem>
 	  <para>FreeBSD Services Limited offer a free DVD subscription to
 	    FreeBSD committers.  To take advantage of this offer, go to <ulink
 	    url="https://www.freebsd-services.com/cgi/index/sales/login">
 	    www.freebsd-services.com</ulink> and fill out their customer form,
 	    making sure that you tick the FreeBSD Committer and free
 	    subscription check-boxes.  A message will be sent to your
 	    <emphasis role="bold">FreeBSD.org</emphasis> email address asking
 	    for confirmation.  Just reply to the mail, quoting the message
 	    and updating the <quote>Membership Valid</quote> field with a
 	    <literal>Y</literal>.  You can confirm that the reply was sent
 	    successfully by <ulink
             url="https://www.freebsd-services.com/cgi/index/customer">logging
 	    in </ulink>to their site and checking that your <literal>Current
 	    Status</literal> is set to
 	    <emphasis role="bold">Associated</emphasis>.</para>
 
 	  <para>In addition to the free subscription, committers are also
 	    entitled to a <emphasis role="bold">10% discount</emphasis> on
 	    all products on the site.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>A Free 4-CD Set Subscription</term>
 
 	<listitem>
 	  <para><ulink url="http://www.freebsdmall.com">FreeBSD Mall,
             Inc.</ulink> offers a free subscription of the official
             4-CD set to all FreeBSD committers.  Information about how
             to obtain your free CD is mailed to
             <email>developers@FreeBSD.org</email> following each major
             release.</para>
         </listitem>
       </varlistentry>
 
     </variablelist>
   </sect1>
 
   <sect1>
     <title>Miscellaneous Questions</title>
 
     <qandaset>
       <qandaentry>
 	<question>
 	  <para>Why are trivial or cosmetic changes to files on a vendor
 	    branch a bad idea?</para>
 	</question>
 
 	<answer>
 	  <itemizedlist>
 	    <listitem>
 	      <para>From now on, every new vendor release of that file will
 		need to have patches merged in by hand.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>From now on, every new vendor release of that file will
 		need to have patches <emphasis>verified</emphasis> by hand.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>The <option>-j</option> option does not work very well.
 		Ask &a.obrien; for horror stories.</para>
 	    </listitem>
 	  </itemizedlist>
 	</answer>
       </qandaentry>
 
       <qandaentry>
 	<question>
 	  <para>How do I add a new file to a CVS branch?</para>
 	</question>
 
 	<answer>
 	  <para>To add a file onto a branch, simply checkout or update
 	  to the branch you want to add to and then add the file using
 	  <command>cvs add</command> as you normally would.  For
 	  example, if you wanted to MFC the file
 	  <filename>src/sys/alpha/include/smp.h</filename> from HEAD
 	  to RELENG_4 and it does not exist in RELENG_4 yet, you would
 	  use the following steps:</para>
 
 	  <example>
 	    <title>MFC'ing a New File</title>
 
 	    <screen>&prompt.user; <userinput>cd sys/alpha/include</userinput>
 &prompt.user; <userinput>cvs update -rRELENG_4</userinput>
 cvs update: Updating .
 U clockvar.h
 U console.h
 ...
 &prompt.user; <userinput>cvs update -kk -Ap smp.h &gt; smp.h</userinput>
 ===================================================================
 Checking out smp.h
 RCS:  /usr/cvs/src/sys/alpha/include/smp.h,v
 VERS: 1.1
 ***************
 &prompt.user; <userinput>cvs add smp.h</userinput>
 cvs add: scheduling file `smp.h' for addition on branch `RELENG_4'
 cvs add: use 'cvs commit' to add this file permanently
 &prompt.user; <userinput>cvs commit</userinput>
 	    </screen>
 	  </example>
 	</answer>
       </qandaentry>
 
       <qandaentry>
 	<question>
 	  <para>What <quote>meta</quote> information should I include in a
 	    commit message?</para>
 	</question>
 
 	<answer>
 	  <para>As well as including an informative message with each commit
 	    you may need to include some additional information as
 	    well.</para>
 
 	  <para>This information consists of one or more lines containing the
 	    the key word or phrase, a colon, tabs for formatting, and then the
 	    additional information.</para>
 
 	  <para>The key words or phrases are:</para>
 
 	  <informaltable frame="none">
 	    <tgroup cols="2">
 	      <tbody>
 		<row>
 		  <entry><literal>PR:</literal></entry>
 		  <entry>The problem report (if any) which is affected
 		    (typically, by being closed) by this commit.</entry>
 		</row>
 
 		<row>
 		  <entry><literal>Submitted by:</literal></entry>
 		  <entry>The name and e-mail address of the person that
 		    submitted the fix.</entry>
 		</row>
 
 		<row>
 		  <entry><literal>Reviewed by:</literal></entry>
 		  <entry>The name and e-mail address of the person or people
 		    that reviewed the change.  If a patch was submitted to a
 		    mailing list for review, and the review was favourable,
 		    then just include the list name.</entry>
 		</row>
 
 		<row>
 		  <entry><literal>Approved by:</literal></entry>
 		  <entry>The name and e-mail address of the person or people
 		    that approved the change.  It is customary to get prior
 		    approval for a commit if it is to an area of the tree to
 		    which you do not usually commit.  In addition, during the
 		    run up to a new release all commits
 		    <emphasis>must</emphasis> be approved by the release
 		    engineer.  If these are your first commits then you should
 		    have passed them past your mentor first for approval, and
 		    you should list your mentor.</entry>
 		</row>
 
 		<row>
 		  <entry><literal>Obtained from:</literal></entry>
 		  <entry>The name of the project (if any) from which the code
 		    was obtained.</entry>
 		</row>
 
 		<row>
 		  <entry><literal>MFC after:</literal></entry>
 
                   <entry>If you wish to receive an e-mail reminder to
 		    <acronym>MFC</acronym> at a later date, specify the
 		    number of days, weeks, or months after which an
 		    <acronym>MFC</acronym> is planned.</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 
 	  <example>
 	    <title>Commit log for a commit based on a PR</title>
 
 	    <para>You want to commit a change based on a PR submitted by John
 	      Smith containing a patch.  The end of the commit message should
 	      look something like this.</para>
 
 	    <programlisting>...
 
 PR:                foo/12345
 Submitted by:	   John Smith &lt;John.Smith@example.com></programlisting>
 	  </example>
 
 	  <example>
 	    <title>Commit log for a commit needing review</title>
 
 	    <para>You want to change the virtual memory system.  You have
 	      posted patches to the appropriate mailing list (in this case,
 	      <literal>freebsd-arch</literal>) and the changes have been
 	      approved.</para>
 	    
 	    <programlisting>...
 
 Reviewed by:       -arch</programlisting>
 	  </example>
 
 	  <example>
 	    <title>Commit log for a commit needing approval</title>
 
 	    <para>You want to commit a change to a section of the tree with a
 	      MAINTAINER assigned.  You have collaborated with the listed
 	      MAINTAINER, who has told you to go ahead and commit.</para>
 
 	    <programlisting>...
 
 Approved by:	    <replaceable>abc</replaceable></programlisting>
 
 	    <para>Where <replaceable>abc</replaceable> is the account name of
 	      the person who approved.</para>
 	  </example>
 
 	  <example>
 	    <title>Commit log for a commit bringing in code from
 	      OpenBSD</title>
 
 	    <para>You want to commit some code based on work done in the
 	      OpenBSD project.</para>
 
 	    <programlisting>...
 
 Obtained from:      OpenBSD</programlisting>
 	  </example>
 
 	  <example>
 	    <title>Commit log for a change to &os.current; with a planned
               commit to &os.stable; to follow at a later date.</title>
 
 	    <para>You want to commit some code which will be merged from
 	      &os.current; into the &os.stable; branch after two
 	      weeks.</para>
 
 	    <programlisting>...
 
 MFC after:      <replaceable>2 weeks</replaceable></programlisting>
 
 	    <para>Where <replaceable>2</replaceable> is the number of days,
 	      weeks, or months after which an <acronym>MFC</acronym> is
 	      planned.  The <replaceable>weeks</replaceable> option may be
 	      <literal>day</literal>, <literal>days</literal>,
 	      <literal>week</literal>, <literal>weeks</literal>,
 	      <literal>month</literal>, <literal>months</literal>,
 	      or may be left off (in which case, days will be assumed).</para>
 	  </example>
 
 	  <para>In some cases you may need to combine some of these.</para>
 
 	  <para>Consider the situation where a user has submitted a PR
 	    containing code from the NetBSD project.  You are looking at the
 	    PR, but it is not an area of the tree you normally work in, so
 	    you have decided to get the change reviewed by the
 	    <literal>arch</literal> mailing list.  Since the change is
 	    complex, you opt to <acronym>MFC</acronym> after one month to
 	    allow adequate testing.</para>
 
 	  <para>The extra information to include in the commit would look
 	    something like</para>
 
 	  <programlisting>PR:                 foo/54321
 Submitted by:       John Smith &lt;John.Smith@example.com>
 Reviewed by:        -arch
 Obtained from:      NetBSD
 MFC after:          1 month</programlisting>
 	</answer>
       </qandaentry>
 
       <qandaentry>
 	<question>
 	  <para>How do I access <hostid
 	    role="fqdn">people.FreeBSD.org</hostid> to put up personal
 	    or project information?</para>
 	</question>
 
 	<answer>
 	  <para><hostid role="fqdn">people.FreeBSD.org</hostid> is the
 	    same as <hostid
 	    role="fqdn">freefall.FreeBSD.org</hostid>. Just create a
 	    <filename>public_html</filename> directory.  Anything you
 	    place in that directory will automatically be visible
 	    under <ulink
 	    url="http://people.FreeBSD.org">people.FreeBSD.org</ulink>.</para>
 	</answer>
       </qandaentry>
     </qandaset>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/articles/contributing/article.sgml b/en_US.ISO8859-1/articles/contributing/article.sgml
index 8c4b280b79..43e7cfc4e5 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
+	    release once a day&mdash;every now and again, try to 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;
 	    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/cvs-freebsd/article.sgml b/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml
index 025e710839..a1214db840 100644
--- a/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml
+++ b/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml
@@ -1,658 +1,658 @@
 <!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>Setting up a CVS repository - the FreeBSD way</title>
 
     <author>
       <firstname>Stijn</firstname>
       <surname>Hoop</surname>
       <affiliation>
         <address><email>stijn@win.tue.nl</email></address>
       </affiliation>
     </author>
 
     <copyright>
       <year>2001</year>
       <holder role="mailto:stijn@win.tue.nl">Stijn Hoop</holder>
     </copyright>
 
-    <pubdate role="rcs">$Date: 2002-04-05 08:16:31 $</pubdate>
+    <pubdate role="rcs">$Date: 2002-04-07 23:52:32 $</pubdate>
 
     <releaseinfo>$FreeBSD$</releaseinfo>
 
     <abstract>
       <para>This article describes the steps I took to setup a CVS repository
         that uses the same scripts the FreeBSD project uses in their setup.
         This has several advantages over a stock CVS setup, including more
         granular access control to the source tree and generation of readable
         email of every commit.</para>
     </abstract>
   </articleinfo>
 
   <sect1>
     <title>Introduction</title>
 
     <para>Most of the open source software projects use
       <application>CVS</application> as their source code control system.
       While <application>CVS</application> is pretty good at this, it has its
       share of flaws and weaknesses.  One of these is that sharing a source
       tree with other developers can quickly lead to a system administration
       nightmare, especially if one wishes to protect parts of the tree from
       general access.</para>
 
     <para>FreeBSD is one of the projects using <application>CVS</application>.
       It also has a large base of developers located around the world.
       They developed some scripts to make management of the repository easier.
       Recently, these scripts were revisited and normalized by Joseph
       Karthauser to make it easier to reuse them in other projects. This
       article describes one method of using the new scripts.</para>
 
     <para>To make the most use of the information in this article, you need to
       be familiar with the basic method of operation of
       <application>CVS</application>.</para>
   </sect1>
 
   <sect1>
     <title>First setup</title>
 
     <warning>
       <para>It might be best to first perform this procedure with an empty
         test repository, to make sure you understand all consequences.
         As always, make sure you have recent, readable backups!</para>
     </warning>
 
     <sect2>
       <title>Initializing the repository</title>
 
       <para>The first thing to do when setting up a new repository is to tell
         <application>CVS</application> to initialize it:
 
         <screen>&prompt.user; <userinput>cvs -d <replaceable>path-to-repository</replaceable> init</userinput></screen>
 
         This tells <application>CVS</application> to create the
         <filename>CVSROOT</filename> administrative directory, where all the
         customization takes place.</para>
     </sect2>
 
     <sect2>
       <title>The repository group</title>
 
       <para>Now we will create the group which will own the repository.
         All committers need to be in this group, so that they can write to the
         repository. We will assume the FreeBSD default of
         <literal>ncvs</literal> for this group.
 
         <screen>&prompt.root; <userinput>pw groupadd <replaceable>ncvs</replaceable></userinput></screen>
 
         Next, you should &man.chown.8; the directory to the user and group
         you just added:
 
         <screen>&prompt.root; <userinput>chown -R :<replaceable>ncvs</replaceable> <replaceable>path-to-your-repository</replaceable></userinput></screen>
 
         This ensures that no one can write to the repository without proper
         group permissions.</para>
     </sect2>
 
     <sect2>
       <title>Getting the sources</title>
 
       <para>Now you need to obtain the <filename>CVSROOT</filename> directory
         from the FreeBSD repository. This is most easily done by checking it
         out from a FreeBSD anonymous CVS mirror. See <ulink
           url="../../books/handbook/anoncvs.html">the relevant chapter in
         the handbook</ulink> for more information. Let us assume that the
         sources are stored in <filename>CVSROOT-freebsd</filename> in the
         current directory.</para>
     </sect2>
 
     <sect2>
       <title>Copying the FreeBSD scripts</title>
 
       <para>Next, we will copy the FreeBSD <filename>CVSROOT</filename>
         sources into your own repository. If you are accustomed to
-        <application>CVS</application>, it might occur to you to try and
+        <application>CVS</application>, you might be thinking that you can just
         import the scripts, in an attempt to make synchronizing with later
         versions easier. However, it turns out that
         <application>CVS</application> has a deficiency in this area:
         when importing sources into the <filename>CVSROOT</filename> directory,
         it will not update the needed administrative files. In order to make
         it recognize those, you will need to checkin each file after importing
         them, losing the value of <literal>cvs import</literal>. Therefore,
         the recommended method is to simply copy over the scripts.</para>
 
       <para>It does not matter if the above paragraph did not make sense to
         you&mdash;the end result is the same. Simply check out your
         <filename>CVSROOT</filename> and copy the FreeBSD files over your
         local (untouched) copies:
 
         <screen>&prompt.user; <userinput>cvs -d <replaceable>path-to-your-repository</replaceable> checkout CVSROOT</userinput>
 &prompt.user; <userinput>cd CVSROOT</userinput>
 &prompt.user; <userinput>cp ../CVSROOT-freebsd/* .</userinput>
 &prompt.user; <userinput>cvs add *</userinput></screen>
 
         Note that you will probably get a few warnings about some directories
         not being copied; this is normal, you don't need those.</para>
     </sect2>
 
     <sect2>
       <title>The scripts</title>
 
       <para>Now you have in your working directory an exact copy of the scripts
         that the FreeBSD project itself uses for their repository. A summary
         of what each file is used for is included below.</para>
 
       <itemizedlist>
         <listitem>
           <para><filename>access</filename> - this file is not used in the
             default setup. It is used in <link linkend="freebsdspecific">the
             FreeBSD project specific setup</link>, where it controls access to
             the repository. You can remove this file if you
             do not wish to use this setup.</para>
         </listitem>
 
         <listitem>
           <para><filename>avail</filename> - this file controls access to the
             repository. In this, you can specify groups of people that are
             allowed access to the repository, as well as disallow commits on a
             per-directory basis. You should tailor it to contain the groups
             and directories that will be in your repository.</para>
         </listitem>
 
         <listitem>
           <para><filename>cfg.pm</filename> - this file parses your
             configuration, and provides the default configuration.  You should
             <emphasis>not</emphasis> make changes to this file. Instead, put
             your configuration changes in
             <filename>cfg_local.pm</filename>.</para>
         </listitem>
 
         <listitem>
           <para><filename>cfg_local.pm</filename> - this file contains all
             configurable parameters of the system. You should configure all
             sorts of settings here, such as where commit mail is send, on what
             hosts people can commit, and others. More information on this
             below.</para>
         </listitem>
 
         <listitem>
           <para><filename>checkoutlist</filename> - this files lists all
             files under control of <application>CVS</application> in this
             directory. You should edit this to remove some FreeBSD specific
             files.</para>
         </listitem>
 
         <listitem>
           <para><filename>commit_prep.pl</filename> - this script performs
             various pre-commit checks, based on whether you enabled them in your
             <filename>cfg_local.pm</filename>. You should not have to touch
             this.</para>
         </listitem>
 
         <listitem>
           <para><filename>commitcheck</filename> - this script is invoked
             directly from <application>CVS</application>. It first checks if
             the committer has access to the specified part of the tree, and
             then runs <filename>commit_prep.pl</filename> for the various
             pre-commit checks. If those are OK, <application>CVS</application>
             will allow the commit to proceed. You should not have to touch
             this file.</para>
         </listitem>
 
         <listitem>
           <para><filename>commitinfo</filename> - this file is used by
             <application>CVS</application> to determine which script to run
             before a commit. You should not have to touch this file.</para>
         </listitem>
 
         <listitem>
           <para><filename>config</filename> - the configuration file for
             this repository. You should change this as needed, but most
             administrators can probably leave the defaults. More information on
             the options that can be set here can be found in the
             <application>CVS</application> manual.</para>
         </listitem>
 
         <listitem>
           <para><filename>cvs_acls.pl</filename> - this script determines
             the committers identity, and whether he/she is allowed access to the
             tree. It does this based on the <filename>avail</filename> file.
             You should not have to touch this file.</para>
         </listitem>
 
         <listitem>
           <para><filename>cvsignore</filename> - this file specifies files
             that <application>CVS</application> should not checkin in the
             repository. You can edit this as you wish. More information about
             this file is available in the <application>CVS</application>
             manual.</para>
         </listitem>
 
         <listitem>
           <para><filename>cvswrappers</filename> - this file is used by
             <application>CVS</application> to enable or disable keyword
             expansion, or whether a file should be considered binary. You
             can edit this as you wish. More information about this file
             is available in the <application>CVS</application> manual.</para>
         </listitem>
 
         <listitem>
           <para><filename>edithook</filename> - this file is not used
             any more, but kept for historic reasons. You should not have to
             touch this file.</para>
         </listitem>
 
         <listitem>
           <para><filename>editinfo</filename> - <application>CVS</application>
             uses this file for editor overrides. FreeBSD does not use this
             functionality, as parsing the log message is done in the
             <filename>verifymsg</filename> and <filename>logcheck</filename>
             files. You should not have to touch this file.</para>
         </listitem>
 
         <listitem>
           <para><filename>exclude</filename> - this file lists regular
             expressions that are used to determine files which cannot contain a
             revision header. In the FreeBSD setup, all files under revision
             control need to have a revision header (like
             &dollar;FreeBSD&dollar;). All filenames that match one of the lines
             in this file are exempted from this check. You should add
             expressions to this file as you checkin files that cannot have a
             revision header. For the purpose of installing the scripts, it
             may be best to exclude <filename>CVSROOT/</filename> from header
             checks.</para>
         </listitem>
 
         <listitem>
           <para><filename>log_accum.pl</filename> - this is a script that
             takes the log message as provided by the
             <filename>logcheck</filename> script, and appends it to a log file
             in the repository for backup purposes. It also handles mailing out a
             message to an email address you provide (in
             <filename>cfg_local.pm</filename>). You should not have to touch
             this file.</para>
         </listitem>
 
         <listitem>
           <para><filename>logcheck</filename> - this file parses the commit
             log message that committers provide, and attempts to sanitize it
             somewhat.</para>
 
           <note><para>This script depends on a local FreeBSD hack of
             <application>CVS</application>: this version reads the log message
             back in after this script has modified it. The stock version of
             <application>CVS</application> apparently does not, which would
             make this script useless.</para></note>
         </listitem>
 
         <listitem>
           <para><filename>loginfo</filename> - this file is used by
             <application>CVS</application> to control where log
             information is sent. You should not have to touch this
             file.</para>
         </listitem>
 
         <listitem>
           <para><filename>modules</filename> - this file retains its
             traditional meaning in <application>CVS</application>. You should
             remove the FreeBSD modules from the stock version. You can edit this
             as you wish. More information about this file is available in the
             <application>CVS</application> manual.</para>
         </listitem>
 
         <listitem>
           <para><filename>notify</filename> - this file is used by
             <application>CVS</application> in case someone sets a watch on a
             file. It is not used in the FreeBSD repository. You can edit this as
             you wish. More information about this file is available in the
             <application>CVS</application> manual.</para>
         </listitem>
 
         <listitem>
           <para><filename>options</filename> - this file is specific to
             the FreeBSD version of <application>CVS</application>. It contains
             the keyword to expand in revision headers. You should alter this to
             match the keyword you specified in
             <filename>cfg_local.pm</filename> (if you use that feature, which
             is FreeBSD specific for now).</para>
         </listitem>
 
         <listitem>
           <para><filename>rcsinfo</filename> - this file maps directories in
             the repository to template files. By default, FreeBSD uses one
             template for the whole repository. You can add others to this file
             if you wish.</para>
         </listitem>
 
         <listitem>
           <para><filename>rcstemplate</filename> - this file is the actual
             template committers will see when they make a checkin. You should
             edit this to describe the various extra parameters you defined in
             <filename>cfg_local.pm</filename>.</para>
         </listitem>
 
         <listitem>
           <para><filename>tagcheck</filename> - this files controls access
             to tagging in the repository. The stock FreeBSD version disallows
             tags with names of RELENG*, because of the release engineering
             process. You should edit this file as desired.</para>
         </listitem>
 
         <listitem>
           <para><filename>taginfo</filename> - this file maps tag operations
             on repository directories to access control scripts. You should not
             have to touch this file.</para>
         </listitem>
 
         <listitem>
           <para><filename>unwrap</filename> - this script is needed to
             automatically <quote>unwrap</quote> binary files (see
             <filename>cvswrappers</filename>) on checkout. It is not used in the
             current FreeBSD setup. You should not have to touch this
             file.</para>
         </listitem>
 
         <listitem>
           <para><filename>verifymsg</filename> - this file maps repository
             directories to post processor scripts of log messages. You should
             not have to touch this file.</para>
         </listitem>
 
         <listitem>
           <para><filename>wrap</filename> - this script is needed to
             automatically <quote>wrap</quote> binary files (see
             <filename>cvswrappers</filename>) on checkin. It is not used in the
             current FreeBSD setup. You should not have to touch this
             file.</para>
         </listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Customizing the scripts</title>
 
       <para>The next step is to setup the scripts so that they work in
         your environment. You should go over all files in the directory and
         make your customizations. In particular, you might want to do edit the
         following files:</para>
 
       <procedure>
         <step>
           <para>If you do not wish to use the <link linkend="freebsdspecific">
             FreeBSD specific features</link> of the scripts, you can safely
             remove the <filename>access</filename> file:
 
             <screen>&prompt.user; <userinput>cvs rm -f access</userinput></screen></para>
         </step>
 
         <step>
           <para>Edit <filename>avail</filename> to contain the various
             repository directories in which you want to control access. Make
             sure you retain the <literal>avail||CVSROOT</literal> line,
             otherwise you will lock yourself out in the next step.</para>
 
           <para>The other thing you can add in this file are committer groups.
             By default, FreeBSD uses the <filename>access</filename> file to
             list all its committers in, but you can use any file you wish. You
             can also add groups if you want (the syntax is specified at the
             top of <filename>cvs_acls.pl</filename>).</para>
         </step>
 
         <step>
           <para>Edit <filename>cfg_local.pm</filename> to contain the options
             you want. In particular, you should take a look at the following
             configurable items:
 
             <itemizedlist>
               <listitem>
                 <para><literal>%TEMPLATE_HEADERS</literal> - these get
                   processed by the log scripts, and inserted below the
                   commit mail if present and non-empty in the commit
                   message. You can probably remove the <literal>PR</literal>
                   and <literal>MFC after</literal> entries. And of course
                   you can add your own.</para>
               </listitem>
 
               <listitem>
                 <para><literal>$MAIL_BRANCH_HDR</literal> - if you want
                   to insert a header into each commit mail describing the
                   branch on which the commit was made, define this to match
                   your setup. Or leave it empty if you don't want such a
                   header.</para>
               </listitem>
 
               <listitem>
                 <para><literal>@COMMIT_HOSTS</literal> - define this to
                   be a list of hosts on which people can commit.</para>
               </listitem>
 
               <listitem>
                 <para><literal>$MAILADDRS</literal> - set this to the
                   admin or list address that should receive commit mail.</para>
               </listitem>
 
               <listitem>
                 <para><literal>@LOG_FILE_MAP</literal> - change this array
                   as you wish - each regexp is matched on the directory of
                   the commit, and the commit log message gets stored in
                   the <filename>commitlogs</filename> subdirectory in
                   the filename mentioned.</para>
               </listitem>
 
               <listitem>
                 <para><literal>$COMMITCHECK_EXTRA</literal> - if you do not
                   want to use <link linkend="freebsdspecific">the FreeBSD
                   specific access checks</link>, you should remove the
                   definition of <literal>$COMMITCHECK_EXTRA</literal> from
                   this file.</para>
               </listitem>
             </itemizedlist>
 
           <note><para>Changing the <literal>$IDHEADER</literal> parameter
             is only guaranteed to work on FreeBSD platforms; it depends on
             FreeBSD specific modifications to
             <application>CVS</application>.</para></note>
 
           You can check <filename>cfg.pm</filename> to see which other
           options can be changed, but the above is a reasonable subset.</para>
         </step>
 
         <step>
           <para>Edit <filename>exclude</filename> to remove the FreeBSD specific
             entries (such as all lines beginning with <literal>^ports/</literal>
             etc.). Furthermore, comment out the lines beginning with
             <literal>^CVSROOT/</literal>, and add one line with only
             <literal>^CVSROOT/</literal> on it. After the wrapper is
             installed, you can add your header to the files in the
             <filename>CVSROOT</filename> directory and restore these lines,
             but for now they will only be in the way when you try to commit
             later on.</para>
         </step>
 
         <step>
           <para>Edit <filename>modules</filename>, and delete all FreeBSD
             stuff. Add your own modules if you wish.</para>
         </step>
 
         <step>
           <note><para>This step is only necessary if you specified a
             value for <literal>$IDHEADER</literal> in
             <filename>cfg_local.pm</filename> (which only works using a
             FreeBSD modified <application>CVS</application>).</para></note>
 
           <para>Edit <filename>options</filename> to match the tag you
             specified in <filename>cfg_local.pm</filename>. A global
             search and replace of <literal>FreeBSD</literal> with your
             tag should suffice.</para>
         </step>
 
         <step>
           <para>Edit <filename>rcstemplate</filename> to contain the same
             keywords as specified in <filename>cfg_local.pm</filename>.</para>
         </step>
 
         <step>
           <para>Optionally remove the FreeBSD checks from
              <filename>tagcheck</filename>. You can simply add
              <literal>exit 0</literal> to the top of the file to disable all
              checks on tagging.</para>
         </step>
 
         <step>
           <para>The last thing to do before you are finished, is to make sure
             the commitlogs can be stored. By default these are stored in
             the repository, in the <filename>commitlogs</filename> subdirectory
             of the <filename>CVSROOT</filename> directory. This directory
             needs to be created, so do the following:
 
             <screen>&prompt.user; <userinput>mkdir commitlogs</userinput>
 &prompt.user; <userinput>cvs add commitlogs</userinput></screen></para>
         </step>
       </procedure>
 
       <para>Now, after careful review, you should commit your changes. Be
         sure that you have granted yourself access to the
         <filename>CVSROOT</filename> directory in your
         <filename>avail</filename> before you do this, because otherwise you
         will lock yourself out. So make sure everything is as you intend, and
         then do the following:
 
         <screen>&prompt.user; <userinput>cvs commit -m '<replaceable>- Initial FreeBSD scripts commit</replaceable>'</userinput></screen></para>
     </sect2>
 
     <sect2>
       <title>Testing the setup</title>
 
       <para>You are ready for the first test: a forced commit to the
         <filename>avail</filename> file, to make sure everything works as
         expected.
 
         <screen>&prompt.user; <userinput>cvs commit -f -m '<replaceable>Forced commit to test the new CVSROOT scripts</replaceable>' avail</userinput></screen>
 
         If everything works, congratulations! You now have a working setup
         of the FreeBSD scripts for your repository. If
         <application>CVS</application> still complains about something, go
         back and recheck if all of the above steps have been performed
         correctly.</para>
     </sect2>
   </sect1>
 
   <sect1 id="freebsdspecific">
     <title>FreeBSD specific setup</title>
 
     <para>The FreeBSD project itself uses a slightly different setup, which
       also uses files from the <filename>freebsd</filename> subdirectory of
       the FreeBSD <filename>CVSROOT</filename>. The project uses this because
       of the large number of committers, which all would have to be in the
       same group. So, a simple wrapper was written which ensures that people
       have the correct credentials to commit, and then sets the group id
       to that of the repository.</para>
 
     <para>If your repository also needs this, the steps to set this up are
       documented below. But first an overview of the files involved.</para>
 
     <sect2>
       <title>Files used in the FreeBSD setup</title>
 
       <para>
         <itemizedlist>
           <listitem>
             <para><filename>access</filename> - this file controls access
               information. You should edit this file to include all members
               of your project.</para>
           </listitem>
 
           <listitem>
             <para><filename>freebsd/commitmail.pl</filename> - this file is
               not used any more, but kept for historic reasons. You should not
               have to touch this file.</para>
           </listitem>
 
           <listitem>
             <para><filename>freebsd/cvswrap.c</filename> - this is the source
               to the CVS wrapper that you will need to install to make all
               access checks actually work. More information on this below. You
               should edit the paths in the <literal>ACCESS</literal> and
               <literal>REALCVS</literal> macros to match your setup.</para>
           </listitem>
 
           <listitem>
             <para><filename>freebsd/mailsend.c</filename> - this file is
               needed by the FreeBSD setup of the mailing lists. You should
               not have to touch this file.</para>
           </listitem>
         </itemizedlist>
       </para>
     </sect2>
 
     <sect2>
       <title>The procedure</title>
 
       <procedure>
         <step>
           <para>Edit the <filename>access</filename> file to contain only
             your username.</para>
         </step>
 
         <step>
           <para>Edit <filename>cvswrap.c</filename> to contain the
             correct path for your setup. This is defined in a macro named
             <literal>ACCESS</literal>. You should also change the location of
             the real <command>cvs</command> binary if it is not appropriate to
             your situation.  The stock <filename>cvswrap.c</filename> expects
             to be a replacement for the systemwide cvs command, which will be
             moved to <filename>/usr/bin/ncvs</filename>.</para>
 
           <para>My copy of <filename>cvswrap.c</filename> has this:</para>
 
           <programlisting>#define ACCESS "/local/cvsroot/CVSROOT/access"
 #define REALCVS "/usr/bin/ncvs"</programlisting>
         </step>
 
         <step>
           <para>Next up is installing the wrapper to ensure you become the
             correct group when committing. The sources for this live in
             <filename>cvswrap.c</filename> in your
             <filename>CVSROOT</filename>.</para>
 
           <para>Compile the sources that you edited to include the correct
             paths:
 
             <screen>&prompt.user; <userinput>cc -o cvs cvswrap.c</userinput></screen>
 
             And then install them (you have to be root for this step):
 
             <screen>&prompt.root; <userinput>mv /usr/bin/cvs /usr/bin/ncvs</userinput>
 &prompt.root; <userinput>mv cvs /usr/bin/cvs</userinput>
 &prompt.root; <userinput>chown root:<replaceable>ncvs</replaceable> /usr/bin/cvs /usr/bin/ncvs</userinput>
 &prompt.root; <userinput>chmod o-rx /usr/bin/ncvs</userinput>
 &prompt.root; <userinput>chmod u-w,g+s /usr/bin/cvs</userinput></screen>
 
             This installs the wrapper as the default <command>cvs</command>
             command, making sure that anyone who wants to use the repository
             has to have the correct access levels.</para>
         </step>
 
         <step>
           <para>You can now remove everyone from your repository group. All
             access control is done by your wrapper, and this wrapper will
             set the correct group for access.</para>
       </procedure>
     </sect2>
 
     <sect2>
       <title>Testing the setup</title>
 
       <para>Your wrapper should now be setup. You can of course test this by
         making a forced commit to the <filename>access</filename> file:
 
         <screen>&prompt.user; <userinput>cvs commit -f -m '<replaceable>Forced commit to test the new CVSROOT scripts</replaceable>' access</userinput></screen>
 
         Again, if this fails, check to see whether all of the above steps have
         been executed correctly.</para>
     </sect2>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/articles/filtering-bridges/article.sgml b/en_US.ISO8859-1/articles/filtering-bridges/article.sgml
index f864e45e1d..171bc08a42 100644
--- a/en_US.ISO8859-1/articles/filtering-bridges/article.sgml
+++ b/en_US.ISO8859-1/articles/filtering-bridges/article.sgml
@@ -1,385 +1,385 @@
 <!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>Filtering Bridges</title>
 
     <authorgroup>
       <author>
         <firstname>Alex</firstname>
         <surname>Dupre</surname>
         <affiliation>
           <address><email>sysadmin@alexdupre.com</email></address>
         </affiliation>
       </author>
     </authorgroup>
 
     <pubdate>$FreeBSD$</pubdate>
 
     <abstract>
       <para>Often it is useful to divide one physical network (like an
 	Ethernet) into two separate segments without having to create subnets,
 	and use a router to link them together. The device that connects the
 	two networks in this way is called a bridge.  A FreeBSD system with
 	two network interfaces is enough in order to act as a bridge.</para>
 
       <para>A bridge works by scanning the addresses of <acronym>MAC</acronym>
 	level (Ethernet addresses) of the devices connected to each of its
 	network interfaces and then forwarding the traffic between the two
 	networks only if the source and the destination are on different
 	segments. Under many points of view a brigde is similar to an Ethernet
 	switch with only two ports.</para>
     </abstract>
   </articleinfo>
 
   <sect1 id="filtering-bridges-why">
     <title>Why use a filtering bridge?</title>
 
     <para>More and more frequently, thanks to the lowering costs of broad band
       Internet connections (xDSL) and also because of the reduction of
       available IPv4 addresses, many companies are connected to the Internet
       24 hours on 24 and with few (sometimes not even a power of 2) IP
       addresses. In these situations it is often desirable to have a firewall
       that filters incoming and outgoing traffic from and towards Internet,
       but a packet filtering solution based on router may not be applicable,
       either due to subnetting issues, the router is owned by the connectivity
       supplier (<acronym>ISP</acronym>), or because it doesn't support such
       functionalities. In these scenarios the use of a filtering bridge is
       highly advised.</para>
 
     <para>A bridge-based firewall can be configured and inserted between the
       xDSL router and your Ethernet hub/switch without any IP numbering
       issues.</para>
   </sect1>
 
   <sect1 id="filtering-bridges-how">
     <title>How to Install</title>
 
     <para>Adding bridge functionalities to a FreeBSD system is not difficult.
       Since 4.5 release it is possible to load such functionalities as modules
       instead of having to rebuild the kernel, simplifying the procedure a
       great deal. In the following subsections I will explain both
       installation ways.</para>
 
     <important>
       <para><emphasis>Do not</emphasis> follow both instructions: a procedure
 	<emphasis>excludes</emphasis> the other one.  Select the best choice
 	according to your needs and abilities.</para>
     </important>
 
     <para>Before going on, be sure to have at least two Ethernet cards that
       support the promiscuous mode for both reception and transmission, since
       they must be able to send Ethernet packets with any address, not just
       their own. Moreover, to have a good throughput, the cards should be PCI
       bus mastering cards. The best choices are still the Intel EtherExpress
       Pro, followed by the 3Com 3c9xx series. To simplify the firewall
       configuration it may be useful to have two cards of different
       manufacturers (using different drivers) in order to distinguish clearly
       which interface is connected to the router and which to the inner
       network.</para>
 
     <sect2 id="filtering-bridges-kernel">
       <title>Kernel Configuration</title>
 
       <para>So you have decided to use the older but well tested installation
 	method. To begin, you have to add the following rows to your kernel
 	configuration file:</para>
 
       <programlisting>options BRIDGE
 options IPFIREWALL
 options IPFIREWALL_VERBOSE</programlisting>
 
       <para>The first line is to compile the bridge support, the second one is
 	the firewall and the third one is the logging functions of the
 	firewall.</para>
 
       <para>Now it is necessary to build and install the new kernel.  You may
 	find detailed instructions in the <ulink
 	  url="../../books/handbook/kernelconfig-building.html">Building
 	and Installing a Custom Kernel</ulink> section of the FreeBSD
 	Handbook.</para>
     </sect2>
 
     <sect2 id="filtering-bridges-modules">
       <title>Modules Loading</title>
 
       <para>If you have choosen to use the new and simpler installation
 	method, the only thing to do now is add the following row to
         <filename>/boot/loader.conf</filename>:</para>
 
       <programlisting>bridge_load="YES"</programlisting>
 
       <para>In this way, during the system startup, the
 	<filename>bridge.ko</filename> module will be loaded together with the
 	kernel. It is not required to add a similar row for the
 	<filename>ipfw.ko</filename> module, since it will be loaded
 	automatically after the execution of the steps in the following
 	section.</para>
     </sect2>
   </sect1>
 
   <sect1 id="filtering-bridges-finalprep">
     <title>Final Preperation</title>
 
     <para>Before rebooting in order to load the new kernel or the required
       modules (according to the previously choosen installation method), you
       have to make some changes to the <filename>/etc/rc.conf</filename>
       configuration file. The default rule of the firewall is to reject all IP
       packets.  Initially we'll set up an 'open' firewall, in order to verify
       its operation without any issue related to packet filtering (in case you
       are going to execute this procedure remotely, such configuration will
       avoid you to remain isolated from the network). Put these lines in
       <filename>/etc/rc.conf</filename>:</para>
 
     <programlisting>firewall_enable="YES"
 firewall_type="open"
 firewall_quiet="YES"
 firewall_logging="YES"</programlisting>
 
     <para>The first row will enable the firewall (and will load the module
       <filename>ipfw.ko</filename> if it is not compiled in the kernel), the
       second one to set up it in 'open' mode (as explained in
       <filename>/etc/rc.firewall</filename>), the third one to not show rules
       loading and the fourth one to enable logging support.</para>
 
     <para>About the configuration of the network interfaces, the most used way
       is to assign an IP to only one of the network cards, but the bridge will
       work equally even if both interfaces or none has a configured IP. In the
       last case (IP-less) the bridge machine will be still more hidden, as
       inaccessible from the network: to configure it, you have to login from
       console or through a third network interface separated from the bridge.
       Sometimes, during the system startup, some programs require network
       access, say for domain resolution: in this case it is necessary to
       assign an IP to the external interface (the one connected to Internet,
       where <acronym>DNS</acronym> server resides), since the bridge will be
       activated at the end of the startup procedure. It means that the
       <devicename>fxp0</devicename> interface (in our case) must be mentioned
       in the ifconfig section of the <filename>/etc/rc.conf</filename> file,
       while the <devicename>xl0</devicename> is not. Assigning an IP to both
       the network cards does not make much sense, unless, during the start
       procedure, applications should access to services on both Ethernet
       segments.</para>
 
     <para>There is another important thing to know. When running IP over
       Ethernet, there are actually two Ethernet protocols in use: one is IP,
       the other is <acronym>ARP</acronym>.  <acronym>ARP</acronym> does the
       conversion of the IP address of a host into its Ethernet address
       (<acronym>MAC</acronym> layer).  In order to allow the communication
       between two hosts separated by the bridge, it is necessary that the
       bridge will forward <acronym>ARP</acronym> packets. Such protocol is not
       included in the IP layer, since it exists only with IP over Ethernet.
       The FreeBSD firewall filters exclusively on the IP layer and therefore
       all non-IP packets (<acronym>ARP</acronym> included) will be forwarded
       without being filtered, even if the firewall is configured to not permit
       anything.</para>
 
     <para>Now it's time to reboot the system and use it as before: there will
       be some new messages about the bridge and the firewall, but the bridge
       will not be activated and the firewall, being in 'open' mode, will not
       avoid any operations.</para>
 
-    <para>If there are any problems, you should try and sort them out now
+    <para>If there are any problems, you should sort them out now
       before proceeding.</para>
   </sect1>
 
   <sect1 id="filtering-bridges-enabling">
     <title>Enabling the Bridge</title>
 
     <para>At this point, to enable the bridge, you have to execute the
       following commands (having the shrewdness to replace the names of the
       two network interfaces <devicename>fxp0</devicename> and
       <devicename>xl0</devicename> with your own ones):</para>
 
     <screen>&prompt.root; <userinput>sysctl net.link.ether.bridge_cfg=fxp0:0,xl0:0</userinput>
 &prompt.root; <userinput>sysctl net.link.ether.bridge_ipfw=1</userinput>
 &prompt.root; <userinput>sysctl net.link.ether.bridge=1</userinput></screen>
 
     <para>The first row specifies which interfaces should be activated by the
       bridge, the second one will enable the firewall on the bridge and
       finally the third one will enable the bridge.</para>
 
     <para>At this point you should be able to insert the machine between two
       sets of hosts without compromising any communication abilities between
       them. If so, the next step is to add the
       <literal>net.link.ether.<replaceable>[blah]</replaceable>=<replaceable>[blah]</replaceable></literal>
       portions of these rows to the <filename>/etc/sysctl.conf</filename>
       file, in order to have them execute at startup.</para>
   </sect1>
 
   <sect1 id="filtering-bridges-ipfirewall">
     <title>Configuring The Firewall</title>
 
     <para>Now it is time to create your own file with custom firewall rules,
       in order to secure the inside network. There will be some complication
       in doing this because not all of the firewall functionalities are
       available on bridged packets. Furthermore, there is a difference between
       the packets that are in the process of being forwarded and packets that
       are being received by the local machine. In general, incoming packets
       are run through the firewall only once, not twice as is normally the
       case; in fact they are filtered only upon receipt, so rules that use
       'out' or 'xmit' will never match. Personally, I use 'in via' which is an
       older syntax, but one that has a sense when you read it. Another
       limitation is that you are restricted to use only 'pass' or 'drop'
       commands for packets filtered by a bridge.  Sophisticated things like
       'divert', 'forward' or 'reject' are not available. Such options can
       still be used, but only on traffic to or from the bridge machine itself
       (if it has an IP address).</para>
 
     <para>New in FreeBSD 4.0, is the concept of stateful filtering.  This is a
       big improvement for <acronym>UDP</acronym> traffic, which typically is a
       request going out, followed shortly thereafter by a response with the
       exact same set of IP addresses and port numbers (but with source and
       destination reversed, of course). For firewalls that have no
       statekeeping, there is almost no way to deal with this sort of traffic
       as a single session. But with a firewall that can "remember" an outgoing
       <acronym>UDP</acronym> packet and, for the next few minutes, allow a
       response, handling <acronym>UDP</acronym> services is trivial. The
       following example shows how to do it. It's possible to do the same thing
       with <acronym>TCP</acronym> packets. This allows you to avoid some
       denial of service attacks and other nasty tricks, but it also typically
       makes your state table grow quickly in size.</para>
 
     <para>Let's look at an example setup. Note first that at the top of
       <filename>/etc/rc.firewall</filename> there are already standard rules
       for the loopback interface <devicename>lo0</devicename>, so we shouldn't
       have to care for them anymore. Custom rules should be put in a separate
       file (say <filename>/etc/rc.firewall.local</filename>) and loaded at
       system startup, by modifying the row of
       <filename>/etc/rc.conf</filename> where we defined the 'open'
       firewall:</para>
 
     <programlisting>firewall_type="/etc/rc.firewall.local"</programlisting>
 
     <important>
       <para>You have to specify the <emphasis>full</emphasis> path, otherwise
 	it will not be loaded with the risk to remain isolated from the
 	network.</para>
     </important>
 
     <para>For our example imagine to have the <devicename>fxp0</devicename>
       interface connected towards the outside (Internet) and the
       <devicename>xl0</devicename> towards the inside
       (<acronym>LAN</acronym>).  The bridge machine has the IP <hostid
       role="ipaddr">1.2.3.4</hostid> (it is not possible that your
       <acronym>ISP</acronym> can give you a class A address like this, but for
       our example it is good).</para>
 
     <programlisting># Things that we have kept state on before get to go through in a hurry
 add check-state
 
 # Throw away RFC 1918 networks
 add drop all from 10.0.0.0/8 to any in via fxp0
 add drop all from 172.16.0.0/12 to any in via fxp0
 add drop all from 192.68.0.0/16 to any in via fxp0
 
 # Allow the bridge machine to say anything it wants
 # (if the machine is IP-less don't include these rows)
 add pass tcp from 1.2.3.4 to any setup keep-state
 add pass udp from 1.2.3.4 to any keep-state
 add pass ip from 1.2.3.4 to any
 
 # Allow the inside hosts to say anything they want
 add pass tcp from any to any in via xl0 setup keep-state
 add pass udp from any to any in via xl0 keep-state
 add pass ip from any to any in via xl0
 
 # TCP section
 # Allow SSH
 add pass tcp from any to any 22 in via fxp0 setup keep-state
 # Allow SMTP only towards the mail server
 add pass tcp from any to relay 25 in via fxp0 setup keep-state
 # Allow zone transfers only by the slave name server [dns2.nic.it]
 add pass tcp from 193.205.245.8 to ns 53 in via fxp0 setup keep-state
 # Pass ident probes.  It's better than waiting for them to timeout
 add pass tcp from any to any 113 in via fxp0 setup keep-state
 # Pass the "quarantine" range
 add pass tcp from any to any 49152-65535 in via fxp0 setup keep-state
 
 # UDP section
 # Allow DNS only towards the name server
 add pass udp from any to ns 53 in via fxp0 keep-state
 # Pass the "quarantine" range
 add pass udp from any to any 49152-65535 in via fxp0 keep-state
 
 # ICMP section
 # Pass 'ping'
 add pass icmp from any to any icmptypes 8 keep-state
 # Pass error messages generated by 'traceroute'
 add pass icmp from any to any icmptypes 3
 add pass icmp from any to any icmptypes 11
 
 # Everything else is suspect
 add drop log all from any to any</programlisting>
 
     <para>Those of you who have set up firewalls before may notice some things
       missing. In particular, there are no anti-spoofing rules, in fact we did
       <emphasis>not</emphasis> add:</para>
 
     <programlisting>add deny all from 1.2.3.4/8 to any in via fxp0</programlisting>
 
     <para>That is, drop packets that are coming in from the outside claiming
       to be from our network. This is something that you would commonly do to
-      be sure that someone does not try and evade the packet filter, by
+      be sure that someone does not try to evade the packet filter, by
       generating nefarious packets that look like they are from the inside.
       The problem with that is that there is <emphasis>at least</emphasis> one
       host on the outside interface that you do not want to ignore: the
       router. But usually, the <acronym>ISP</acronym> anti-spoofs at their
       router, so we do not need to bother that much.</para>
 
     <para>The last rule seems to be an exact duplicate of the default rule,
       that is, do not let anything pass that is not specifically allowed. But
       there is a difference: all suspected traffic will be logged.</para>
 
     <para>There are two rules for passing <acronym>SMTP</acronym> and
       <acronym>DNS</acronym> traffic towards the mail server and the name
       server, if you have them. Obviously the whole rule set should be
       flavored to personal taste, this is only a specific example (rule format
       is described accurately in the &man.ipfw.8; man page). Note that in
       order for 'relay' and 'ns' to work, name service lookups must work
       <emphasis>before</emphasis> the bridge is enabled. This is an example of
       making sure that you set the IP on the correct network card.
       Alternatively it is possible to specify the IP address instead of the
       host name (required if the machine is IP-less).</para>
 
     <para>People that are used to setting up firewalls are probably also used
       to either having a 'reset' or a 'forward' rule for ident packets
       (<acronym>TCP</acronym> port 113). Unfortunately, this is not an
       applicable option with the bridge, so the best thing is to simply pass
       them to their destination. As long as that destination machine is not
       running an ident daemon, this is relatively harmless. The alternative is
       dropping connections on port 113, which creates some problems with
       services like <acronym>IRC</acronym> (the ident probe must
       timeout).</para>
 
     <para>The only other thing that is a little weird that you may have
       noticed is that there is a rule to let the bridge machine speak, and
       another for internal hosts. Remember that this is because the two sets
       of traffic will take different paths through the kernel and into the
       packet filter. The inside net will go through the bridge, while the
       local machine will use the normal IP stack to speak. Thus the two rules
       to handle the different cases. The 'in via
       <devicename>fxp0</devicename>' rules work for both paths. In general, if
       you use 'in via' rules throughout the filter, you will need to make an
       exception for locally generated packets, because they did not come in
       via any of our interfaces.</para>
   </sect1>
 
   <sect1 id="filtering-bridges-contributors">
     <title>Contributors</title>
 
     <para>Many parts of this article have been taken, updated and adapted from
       an old text about bridging, edited by Nick Sayer. A pair of inspirations
       are due to an introduction on bridging by Steve Peterson.</para>
 
     <para>A big thanks to Luigi Rizzo for the implementation of the bridge
       code in FreeBSD and for the time he has dedicated to me answering all of
       my related questions.</para>
 
     <para>A thanks goes out also to Tom Rhodes who looked over my job of
       translation from Italian (the original language of this article) into
       English.</para>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
index be2d2ba82c..2b0f5e2f2d 100644
--- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
@@ -1,399 +1,399 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="policies">
   <title>Source Tree Guidelines and Policies</title>
   
   <para><emphasis>Contributed by &a.phk;.</emphasis></para>
   
   <para>This chapter documents various guidelines and policies in force for
     the FreeBSD source tree.</para>
   
   <sect1 id="policies-maintainer">
     <title><makevar>MAINTAINER</makevar> on Makefiles</title>
     <indexterm><primary>ports maintainer</primary></indexterm>
     
     <para>June 1996.</para>
     
     <para>If a particular portion of the FreeBSD distribution is being
       maintained by a person or group of persons, they can communicate this
       fact to the world by adding a
 
       <programlisting>MAINTAINER= email-addresses</programlisting>
 
       line to the <filename>Makefile</filename>s covering this portion of the
       source tree.</para>
 
     <para>The semantics of this are as follows:</para>
     
     <para>The maintainer owns and is responsible for that code.  This means
       that he is responsible for fixing bugs and answering problem reports
       pertaining to that piece of the code, and in the case of contributed
       software, for tracking new versions, as appropriate.</para>
 
     <para>Changes to directories which have a maintainer defined shall be sent
       to the maintainer for review before being committed.  Only if the
       maintainer does not respond for an unacceptable period of time, to
       several emails, will it be acceptable to commit changes without review
-      by the maintainer.  However, it is suggested that you try and have the
+      by the maintainer.  However, it is suggested that you try to have the
       changes reviewed  by someone else if at all possible.</para>
 
     <para>It is of course not acceptable to add a person or group as
       maintainer unless they agree to assume this duty.  On the other hand it
       does not have to be a committer and it can easily be a group of
       people.</para>
   </sect1>
   
   <sect1 id="policies-contributed">
     <title>Contributed Software</title>
     
     <indexterm><primary>contributed software</primary></indexterm>
     <para><emphasis>Contributed by &a.phk; and &a.obrien;.  </emphasis></para>
     
     <para>June 1996.</para>
     
     <para>Some parts of the FreeBSD distribution consist of software that is
       actively being maintained outside the FreeBSD project.  For historical
       reasons, we call this <emphasis>contributed</emphasis> software.  Some
       examples are perl, gcc and patch.</para>
 
     <para>Over the last couple of years, various methods have been used in
       dealing with this type of software and all have some number of
       advantages and drawbacks.  No clear winner has emerged.</para>
 
     <para>Since this is the case, after some debate one of these methods has
       been selected as the <quote>official</quote> method and will be required
       for future imports of software of this kind.  Furthermore, it is
       strongly suggested that existing contributed software converge on this
       model over time, as it has significant advantages over the old method,
       including the ability to easily obtain diffs relative to the
       <quote>official</quote> versions of the source by everyone (even without
       cvs access).  This will make it significantly easier to return changes
       to the primary developers of the contributed software.</para>
 
     <para>Ultimately, however, it comes down to the people actually doing the
       work.  If using this model is particularly unsuited to the package being
       dealt with, exceptions to these rules may be granted only with the
       approval of the core team and with the general consensus of the other
       developers.  The ability to maintain the package in the future will be a
       key issue in the decisions.</para>
 
     <note>
       <para>Because of some unfortunate design limitations with the RCS file
 	format and CVS's use of vendor branches, minor, trivial and/or
 	cosmetic changes are <emphasis>strongly discouraged</emphasis> on
 	files that are still tracking the vendor branch.  <quote>Spelling
 	fixes</quote> are explicitly included here under the
 	<quote>cosmetic</quote> category and are to be avoided for files with
 	revision 1.1.x.x.  The repository bloat impact from a single character
 	change can be rather dramatic.</para>
     </note>
     
     <para>The <application>Tcl</application> embedded programming
       language will be used as example of how this model works:</para>
 
     <para><filename>src/contrib/tcl</filename> contains the source as
       distributed by the maintainers of this package.  Parts that are entirely
       not applicable for FreeBSD can be removed.  In the case of Tcl, the
       <filename>mac</filename>, <filename>win</filename> and
       <filename>compat</filename> subdirectories were eliminated before the
       import.</para>
 
     <para><filename>src/lib/libtcl</filename> contains only a "bmake style"
       <filename>Makefile</filename> that uses the standard
       <filename>bsd.lib.mk</filename> makefile rules to produce the library
       and install the documentation.</para>
 
     <para><filename>src/usr.bin/tclsh</filename> contains only a bmake style
       <filename>Makefile</filename> which will produce and install the
       <command>tclsh</command> program and its associated man-pages using the
       standard <filename>bsd.prog.mk</filename> rules.</para>
 
     <para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of
       shell-scripts that can be of help when the tcl software needs updating.
       These are not part of the built or installed software.</para>
 
     <para>The important thing here is that the
       <filename>src/contrib/tcl</filename> directory is created according to
       the rules: it is supposed to contain the sources as distributed (on a
       proper CVS vendor-branch and without RCS keyword expansion) with as few
       FreeBSD-specific changes as possible.  The 'easy-import' tool on
       freefall will assist in doing the import, but if there are any doubts on
       how to go about it, it is imperative that you ask first and not blunder
       ahead and hope it <quote>works out</quote>.  CVS is not forgiving of
       import accidents and a fair amount of effort is required to back out
       major mistakes.</para>
     
     <para>Because of the previously mentioned design limitations with CVS's
       vendor branches, it is required that <quote>official</quote> patches from
       the vendor be applied to the original distributed sources and the result
       re-imported onto the vendor branch again.  Official patches should never
       be patched into the FreeBSD checked out version and <quote>committed</quote>, as this
       destroys the vendor branch coherency and makes importing future versions
       rather difficult as there will be conflicts.</para>
 
     <para>Since many packages contain files that are meant for compatibility
       with other architectures and environments that FreeBSD, it is
       permissible to remove parts of the distribution tree that are of no
       interest to FreeBSD in order to save space.  Files containing copyright
       notices and release-note kind of information applicable to the remaining
       files shall <emphasis>not</emphasis> be removed.</para>
     
     <para>If it seems easier, the <command>bmake</command>
       <filename>Makefile</filename>s can be produced from the dist tree
       automatically by some utility, something which would hopefully make it
       even easier to upgrade to a new version.  If this is done, be sure to
       check in such utilities (as necessary) in the
       <filename>src/tools</filename> directory along with the port itself so
       that it is available to future maintainers.</para>
 
     <para>In the <filename>src/contrib/tcl</filename> level directory, a file
       called <filename>FREEBSD-upgrade</filename> should be added and it
       should state things like:</para>
     
     <itemizedlist>
       <listitem>
 	<para>Which files have been left out.</para>
       </listitem>
       
       <listitem>
 	<para>Where the original distribution was obtained from and/or the
 	  official master site.</para>
       </listitem>
       
       <listitem>
 	<para>Where to send patches back to the original authors.</para>
       </listitem>
       
       <listitem>
 	<para>Perhaps an overview of the FreeBSD-specific changes that have
 	  been made.</para>
       </listitem>
     </itemizedlist>
     
     <para>However, please do not import <filename>FREEBSD-upgrade</filename>
       with the contributed source. Rather you should <command>cvs add
 	FREEBSD-upgrade ; cvs ci</command> after the initial import.  Example
       wording from <filename>src/contrib/cpio</filename> is below:</para>
 
     <programlisting>This directory contains virgin sources of the original distribution files
 on a "vendor" branch.  Do not, under any circumstances, attempt to upgrade
 the files in this directory via patches and a cvs commit.  New versions or
 official-patch versions must be imported.  Please remember to import with
 "-ko" to prevent CVS from corrupting any vendor RCS Ids.
 
 For the import of GNU cpio 2.4.2, the following files were removed:
 
         INSTALL         cpio.info       mkdir.c             
         Makefile.in     cpio.texi       mkinstalldirs
 
 To upgrade to a newer version of cpio, when it is available:
         1. Unpack the new version into an empty directory.
            [Do not make ANY changes to the files.]
 
         2. Remove the files listed above and any others that don't apply to
            FreeBSD.
 
         3. Use the command:
                 cvs import -ko -m 'Virgin import of GNU cpio v&lt;version&gt;' \
                         src/contrib/cpio GNU cpio_&lt;version&gt;
 
            For example, to do the import of version 2.4.2, I typed:
                 cvs import -ko -m 'Virgin import of GNU v2.4.2' \
                         src/contrib/cpio GNU cpio_2_4_2
 
         4. Follow the instructions printed out in step 3 to resolve any
            conflicts between local FreeBSD changes and the newer version.
 
 Do not, under any circumstances, deviate from this procedure.
 
 To make local changes to cpio, simply patch and commit to the main
 branch (aka HEAD).  Never make local changes on the GNU branch.
 
 All local changes should be submitted to "cpio@gnu.ai.mit.edu" for
 inclusion in the next vendor release.
 
 obrien@FreeBSD.org - 30 March 1997</programlisting>
   </sect1>
 
   <sect1 id="policies-encumbered">
     <title>Encumbered Files</title>
 
     <para>It might occasionally be necessary to include an encumbered file in
       the FreeBSD source tree.  For example, if a device requires a small
       piece of binary code to be loaded to it before the device will operate,
       and we do not have the source to that code, then the binary file is said 
       to be encumbered.  The following policies apply to including encumbered
       files in the FreeBSD source tree.</para>
 
     <orderedlist>
       <listitem>
         <para>Any file which is interpreted or executed by the system CPU(s)
 	  and not in source format is encumbered.</para>
       </listitem>
 
       <listitem>
         <para>Any file with a license more restrictive than BSD or GNU is
 	  encumbered.</para>
       </listitem>
 
       <listitem>
         <para>A file which contains downloadable binary data for use by the
 	  hardware is not encumbered, unless (1) or (2) apply to it.  It must
 	  be stored in an architecture neutral ASCII format (file2c or
 	  uuencoding is recommended).</para>
       </listitem>
 
       <listitem>
         <para>Any encumbered file requires specific approval from the 
 	  <ulink url="../../articles/contributors/staff-core.html">Core team</ulink> before it is added to the
 	  CVS repository.</para>
       </listitem>
 
       <listitem>
         <para>Encumbered files go in <filename>src/contrib</filename> or
 	  <filename>src/sys/contrib</filename>.</para>
       </listitem>
 
       <listitem>
         <para>The entire module should be kept together.  There is no point in 
 	  splitting it, unless there is code-sharing with non-encumbered
 	  code.</para>
       </listitem>
 
       <listitem>
         <para>Object files are named
 	  <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para>
       </listitem>
 
       <listitem>
         <para>Kernel files:</para>
 
         <orderedlist>
           <listitem>
             <para>Should always be referenced in
               <filename>conf/files.*</filename> (for build simplicity).</para>
 	  </listitem>
 
           <listitem>
             <para>Should always be in <filename>LINT</filename>, but the 
 	      <ulink url="../../articles/contributors/staff-core.html">Core team</ulink> decides per case if it
 	      should be commented out or not.  The 
 	      <ulink url="../../articles/contributors/staff-core.html">Core team</ulink> can, of course, change
 	      their minds later on.</para>
           </listitem>
 
           <listitem>
             <para>The <firstterm>Release Engineer</firstterm>
               decides whether or not it goes in to the release.</para>
           </listitem>
         </orderedlist>
       </listitem>
 
       <listitem>
         <para>User-land files:</para>
 
         <orderedlist>
           <listitem>
             <indexterm><primary>core team</primary></indexterm>
             <para>The <ulink url="../../articles/contributors/staff-core.html">Core team</ulink> decides if
               the code should be part of <command>make world</command>.</para>
           </listitem>
          
           <listitem>
             <indexterm><primary>release engineer</primary></indexterm>
             <para>The <ulink url="../../articles/contributors/staff-who.html">Release Engineer</ulink>
               decides if it goes in to the release.</para>
           </listitem>
         </orderedlist>
       </listitem>
     </orderedlist>
   </sect1>
   
   <sect1 id="policies-shlib">
     <title>Shared Libraries</title>
     
     <para><emphasis>Contributed by &a.asami;, &a.peter;, and &a.obrien;  9 
         December 1996.</emphasis></para>
 
     <para>If you are adding shared library support to a port or other piece of
       software that does not have one, the version numbers should follow these
       rules.  Generally, the resulting numbers will have nothing to do with
       the release version of the software.</para>
 
     <para>The three principles of shared library building are:</para>
     
     <itemizedlist>
       <listitem>
 	<para>Start from <literal>1.0</literal></para>
       </listitem>
       
       <listitem>
 	<para>If there is a change that is backwards compatible, bump minor
 	  number (note that ELF systems ignore the minor number)</para>
       </listitem>
       
       <listitem>
 	<para>If there is an incompatible change, bump major number</para>
       </listitem>
     </itemizedlist>
     
     <para>For instance, added functions and bugfixes result in the minor
       version number being bumped, while deleted functions, changed function
       call syntax, etc. will force the major version number to change.</para>
     
     <para>Stick to version numbers of the form major.minor
       (<replaceable>x</replaceable>.<replaceable>y</replaceable>).  Our a.out
       dynamic linker does not handle version numbers of the form
       <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
       well.  Any version number after the <replaceable>y</replaceable>
       (i.e. the third digit) is totally ignored when comparing shared lib
       version numbers to decide which library to link with.  Given two shared
       libraries that differ only in the <quote>micro</quote> revision,
       <command>ld.so</command> will link with the higher one.  That is, if you link
       with <filename>libfoo.so.3.3.3</filename>, the linker only records
       <literal>3.3</literal> in the headers, and will link with anything
       starting with
       <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
 	3)</replaceable>.<replaceable>(highest
 	available)</replaceable>.</para>
     
     <note>
       <para><command>ld.so</command> will always use the highest
 	<quote>minor</quote> revision.  For instance, it will use
 	<filename>libc.so.2.2</filename> in preference to
 	<filename>libc.so.2.0</filename>, even if the program was initially
 	linked with <filename>libc.so.2.0</filename>.</para>
     </note>
 
     <para>In addition, our ELF dynamic linker does not handle minor version
     numbers at all.  However, one should still specify a major and minor
     version number as our <filename>Makefile</filename>s <quote>do the right thing</quote>
     based on the type of system.</para>
     
     <para>For non-port libraries, it is also our policy to change the shared
       library version number only once between releases.  In addition, it is
       our policy to change the major shared library version number only once
       between major OS releases (i.e. from 3.0 to 4.0).  When you make a
       change to a system library that requires the version number to be
       bumped, check the <filename>Makefile</filename>'s commit logs. It is the
       responsibility of the committer to ensure that the first such change
       since the release will result in the shared library version number in
       the <filename>Makefile</filename> to be updated, and any subsequent
       changes will not.</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/faq/book.sgml b/en_US.ISO8859-1/books/faq/book.sgml
index 03dbf4ed90..5b822f7431 100644
--- a/en_US.ISO8859-1/books/faq/book.sgml
+++ b/en_US.ISO8859-1/books/faq/book.sgml
@@ -1,12375 +1,12381 @@
 <!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>
+                number of different output formats.  Each format has its own
+                advantages and disadvantages.  Some formats are better suited
+                for online reading, while others are meant to be aesthetically
+                pleasing when printed on paper.  Having the documentation
+                available in any of these formats ensures that our readers
+                will be able to read the parts they are interested in, either
+                on their monitor, or on paper after printing the documents.
+                The currently available 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
+                support or try to 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
             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 ff133da1b8..663eef951e 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
+	<emphasis>appropriate</emphasis> markup for the content.  If you
+	tried to 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
+	<para>If you use the syntax above 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>--&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 [
     <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>
 
 	  <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>
 
     &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/fdp-primer/translations/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml
index 467130e879..f1a318c829 100644
--- a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml
@@ -1,479 +1,479 @@
 <!-- Copyright (c) 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="translations">
   <title>Translations</title>
 
   <para>This is the FAQ for people translating the FreeBSD documentation
     (FAQ, Handbook, tutorials, man pages, and others) to different
     languages.</para>
   
   <para>It is <emphasis>very</emphasis> heavily based on the translation FAQ
     from the FreeBSD German Documentation Project, originally written by Frank
     Gr&uuml;nder <email>elwood@mc5sys.in-berlin.de</email> and translated back to
     English by Bernd Warken <email>bwarken@mayn.de</email>.</para>
 
   <para>The FAQ maintainer is &a.nik;.</para>
 
   <qandaset>
     <qandaentry>
       <question>
 	<para>Why a FAQ?</para>
       </question>
 
       <answer>
 	<para>More and more people are approaching the freebsd-doc mailing
 	  list and volunteering to translate FreeBSD documentation to other
 	  languages. This FAQ aims to answer their questions so they can start
 	  translating documentation as quickly as possible.</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>What do <phrase>i18n</phrase> and <phrase>l10n</phrase>
 	  mean?</para>
       </question>
       
       <answer>
 	<para><phrase>i18n</phrase> means
 	  <phrase>internationalisation</phrase> and <phrase>l10n</phrase>
 	  means <phrase>localisation</phrase>. They are just a convenient
 	  shorthand.</para>
 
 	<para><phrase>i18n</phrase> can be read as <quote>i</quote> followed by
 	  18 letters, followed by <quote>n</quote>. Similarly,
 	  <phrase>l10n</phrase> is <quote>l</quote> followed by 10 letters,
 	  followed by <quote>n</quote>.</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>Is there a mailing list for translators?</para>
       </question>
 
       <answer>
 	<para>Yes, <email>freebsd-translate@ngo.org.uk</email>. Subscribe by
 	  sending a message to
 	  <email>freebsd-translate-request@ngo.org.uk</email> with the word
 	  <literal>subscribe</literal> in the body of the message.</para>
 
 	<para>You will receive a reply asking you to confirm your subscription
 	  (in exactly the same manner as the FreeBSD lists at <hostid
 	    role="domainname">FreeBSD.org</hostid>).</para>
 
 	<para>The primary language of the mailing list is English. However,
 	  posts in other languages will be accepted. The mailing list is not
 	  moderated, but you need to be a member of the list before you can
 	  post to it.</para>
 
 	<para>The mailing list is archived, but they are not currently
 	  searchable. Sending the message <literal>help</literal> to
 	  <email>majordomo@ngo.org.uk</email> will send back instructions on
 	  how to access the archive.</para>
 
 	<para>It is expected that the mailing list will transfer to <hostid
 	    role="domainname">FreeBSD.org</hostid> and therefore become
 	  <emphasis>official</emphasis> in the near future.</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>Are more translators needed?</para>
       </question>
 
       <answer>
 	<para>Yes. The more people work on translation the faster it gets
 	  done, and the faster changes to the English documentation are
 	  mirrored in the translated documents.</para>
 
 	<para>You do not have to be a professional translator to be able to
 	  help.</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>What languages do I need to know?</para>
       </question>
 
       <answer>
 	<para>Ideally, you will have a good knowledge of written English, and
 	  obviously you will need to be fluent in the language you are
 	  translating to.</para>
 
 	<para>English is not strictly necessary. For example, you could do a
 	  Hungarian translation of the FAQ from the Spanish
 	  translation.</para>
       </answer>
     </qandaentry>
     
     <qandaentry>
       <question>
 	<para>What software do I need to know?</para>
       </question>
 
       <answer>
 	<para>It is strongly recommended that you maintain a local copy of the
 	  FreeBSD CVS repository (at least the documentation part) either
 	  using <application>CTM</application> or
 	  <application>CVSup</application>. The "Staying current with FreeBSD"
 	  chapter in the Handbook explains how to use these
 	  applications.</para>
 
 	<para>You should be comfortable using <application>CVS</application>.
 	  This will allow you to see what has changed between different
 	  versions of the files that make up the documentation.</para>
 
 	<para>[XXX To Do -- write a tutorial that shows how to use CVSup to
 	  get just the documentation, check it out, and see what has changed
 	  between two arbitrary revisions]</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>How do I find out who else might be translating to the same
 	  language?</para>
       </question>
 
       <answer>
 	<para>The <ulink
 	    url="../../../../docproj/translations.html">Documentation
 	    Project translations page</ulink> lists the translation efforts
 	  that are currently known about. If others are already working
 	  on translating documentation to your language, please do not
 	  duplicate their efforts. Instead, contact them to see how you can
 	  help.</para>
 
 	<para>If no one is listed on that page as translating for your
 	  language, then send a message to the &a.doc; in case someone else
 	  is thinking of doing a translation, but has not announced it yet.
 	  </para>
       </answer>
     </qandaentry>
       
     <qandaentry>
       <question>
 	<para>No one else is translating to my language.  What do I do?</para>
       </question>
 
       <answer>
 	<para>Congratulations, you have just started the <quote>FreeBSD
 	  <replaceable>your-language-here</replaceable> Documentation
           Translation Project</quote>. Welcome aboard.</para>
 
 	<para>First, decide whether or not you have got the time to spare. Since
 	  you are the only person working on your language at the moment it is
 	  going to be your responsibility to publicise your work and
 	  coordinate any volunteers that might want to help you.</para>
 
 	<para>Write an e-mail to the Documentation Project mailing list,
 	  announcing that you are going to translate the documentation, so the
 	  Documentation Project translations page can be maintained.</para>
 
 	<para>You should subscribe to the
 	  <email>freebsd-translate@ngo.org.uk</email> mailing list (as
 	  described earlier).</para>
 
 	<para>If there is already someone in your country providing FreeBSD
 	  mirroring services you should contact them and ask if you can
 	  have some webspace for your project, and possibly an e-mail
 	  address or mailing list services.</para>
 	
 	<para>Then pick a document and start translating. It is best to start
 	  with something fairly small&mdash;either the FAQ, or one of the
 	  tutorials.</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>I have translated some documentation, where do I send it?</para>
       </question>
 
       <answer>
 	<para>That depends. If you are already working with a translation team
 	  (such as the Japanese team, or the German team) then they will have
 	  their own procedures for handling submitted documentation, and these
 	  will be outlined on their web pages.</para>
 
 	<para>If you are the only person working on a particular language (or
 	  you are responsible for a translation project and want to submit
 	  your changes back to the FreeBSD project) then you should send your
 	  translation to the FreeBSD project (see the next question).</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>I am the only person working on translating to this language, how
 	  do I submit my translation?</para>
 
 	<para>or</para>
 
 	<para>We are a translation team, and want to submit documentation that
 	  our members have translated for us?</para>
       </question>
 
       <answer>
 	<para>First, make sure your translation is organised properly. This
 	  means that it should drop in to the existing documentation tree and
 	  build straight away.</para>
 
 	<para>Currently, the FreeBSD documentation is stored in a top level
 	  directory called <filename>doc/</filename>. Directories below this
 	  are named according to the language code they are written in, as
 	  defined in ISO639 (<filename>/usr/share/misc/iso639</filename> on a
 	  version of FreeBSD newer than 20th January 1999).</para>
 
 	<para>If your language can be encoded in different ways (for example,
 	  Chinese) then there should be directories below this, one for each
 	  encoding format you have provided.</para>
 
 	<para>Finally, you should have directories for each document.</para>
 
 	<para>For example, a hypothetical Swedish translation might look
 	  like</para>
 
 	<programlisting>doc/
     sv_SE.ISO8859-1/
                      Makefile 
                      books/
                            faq/
                                Makefile
                                book.sgml</programlisting>
 
 	<para><literal>sv_SE.ISO8859-1</literal> is the name of the
 	  translation, in
 	  <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
 	  form.  Note the
 	  two Makefiles, which will be used to build the documentation.</para>
 
 	<para>Use &man.tar.1; and &man.gzip.1; to compress up your
 	  documentation, and send it to the project.</para>
 
 	<screen>&prompt.user; <userinput>cd doc</userinput>
 &prompt.user; <userinput>tar cf swedish-docs.tar sv</userinput>
 &prompt.user; <userinput>gzip -9 swedish-docs.tar</userinput></screen>
 
 	<para>Put <filename>swedish-docs.tar.gz</filename> somewhere.  If you
 	  do not have access to your own webspace (perhaps your ISP does not
 	  let you have any) then you can e-mail &a.nik;, and arrange to e-mail
 	  the files when it is convenient.</para>
 
 	<para>Either way, you should use &man.send-pr.1; to submit a report
 	  indicating that you have submitted the documentation. It would be
 	  very helpful if you could get other people to look over your
 	  translation and double check it first, since it is unlikely that the
 	  person committing it will be fluent in the language.</para>
 
 	<para>Someone (probably the Documentation Project Manager, currently
 	  &a.nik;) will then take your translation and confirm that it builds.
 	  In particular, the following things will be looked at:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>Do all your files use RCS strings (such as "ID")?</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Does <command>make all</command> in the
 	      <filename>sv_SE.ISO8859-1</filename> directory work correctly?</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>Does <command>make install</command> work correctly?</para>
 	  </listitem>
         </orderedlist>
 	  
 	<para>If there are any problems then whoever is looking at the
-	  submission will get back to you to try and work them out.</para>
+	  submission will get back to you to work them out.</para>
 
 	<para>If there are no problems your translation will be committed
 	  as soon as possible.</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>Can I include language or country specific text in my
 	  translation?</para>
       </question>
 
       <answer>
 	<para>We would prefer that you did not.</para>
 
 	<para>For example, suppose that you are translating the Handbook to
 	  Korean, and want to include a section about retailers in Korea in
 	  your Handbook.</para>
 
 	<para>There is no real reason why that information should not be in the
 	  English (or German, or Spanish, or Japanese, or &hellip;) versions
 	  as well. It is feasible that an English speaker in Korea might try
 	  and pick up a copy of FreeBSD whilst over there. It also helps
 	  increase FreeBSD's perceived presence around the globe, which is not
 	  a bad thing.</para>
 
 	<para>If you have country specific information, please submit it as a
 	  change to the English Handbook (using &man.send-pr.1;) and then
 	  translate the change back to your language in the translated
 	  Handbook.</para>
 
 	<para>Thanks.</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>How should language specific characters be included?</para>
       </question>
 
       <answer>
 	<para>Non-ASCII characters in the documentation should be included
 	  using SGML entities.</para>
 
 	<para>Briefly, these look like an ampersand (&amp;), the name of the
 	  entity, and a semi-colon (;).</para>
 
 	<para>The entity names are defined in ISO8879, which is in the ports
 	  tree as <filename role="package">textproc/iso8879</filename>.</para>
 
 	<para>A few examples include</para>
 
 	<segmentedlist>
           <segtitle>Entity</segtitle>
 
           <segtitle>Appearance</segtitle>
 
           <segtitle>Description</segtitle>
 
 	  <seglistitem>
 	    <seg>&amp;eacute;</seg>
 	    <seg>&eacute;</seg>
 	    <seg>Small <quote>e</quote> with an acute accent</seg>
 	  </seglistitem>
 
 	  <seglistitem>
 	    <seg>&amp;Eacute;</seg>
 	    <seg>&Eacute;</seg>
 	    <seg>Large <quote>E</quote> with an acute accent</seg>
 	  </seglistitem>
 
 	  <seglistitem>
 	    <seg>&amp;uuml;</seg>
 	    <seg>&uuml;</seg>
 	    <seg>Small <quote>u</quote> with an umlaut</seg>
 	  </seglistitem>
 	</segmentedlist>
 
 	<para>After you have installed the iso8879 port, the files in
 	  <filename>/usr/local/share/sgml/iso8879</filename> contain the
 	  complete list.</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>Addressing the reader</para>
       </question>
 
       <answer>
 	<para>In the English documents, the reader is addressed as
 	  <quote>you</quote>, there is no formal/informal distinction as there
 	  is in some languages.</para>
 
 	<para>If you are translating to a language which does distinguish, use
 	  whichever form is typically used in other technical documentation in
 	  your language. If in doubt, use a mildly polite form.</para>
       </answer>
     </qandaentry>
 
     <qandaentry>
       <question>
 	<para>Do I need to include any additional information in my
 	  translations?</para>
       </question>
 
       <answer>
 	<para>Yes.</para>
 
 	<para>The header of the English version of each document will look
 	  something like this;</para>
 
 	<programlisting>&lt;!--
      The FreeBSD Documentation Project
 
      &dollar;FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.5 2000/07/07 18:38:38 dannyboy Exp &dollar;
 --&gt;</programlisting>
 
 	<para>The exact boilerplate may change, but it will always include a
 	  &dollar;FreeBSD&dollar; line and the phrase <literal>The FreeBSD Documentation
 	    Project</literal>.
 	  Note that the &dollar;FreeBSD part is expanded automatically by
 	  CVS, so it should be empty (just
 	  <literal>&dollar;FreeBSD&dollar;</literal>) for new files.</para>
 
 	<para>Your translated documents should include their own
 	  &dollar;FreeBSD&dollar; line, and change the
 	  <literal>FreeBSD Documentation Project</literal> line to
 	  <literal>The FreeBSD <replaceable>language</replaceable>
 	    Documentation Project</literal>.</para>
 
 	<para>In addition, you should add a third line which indicates which
 	  revision of the English text this is based on.</para>
 	
 	<para>So, the Spanish version of this file might start</para>
 
 	<programlisting>&lt;!--
      The FreeBSD Spanish Documentation Project
 
      &dollar;FreeBSD: doc/es_ES.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp &dollar;
      Original revision: 1.11
 --&gt;</programlisting>
       </answer>
     </qandaentry>
   </qandaset>
 </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/basics/chapter.sgml b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
index 013722849d..4183da033c 100644
--- a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
@@ -1,1478 +1,1479 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="basics">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Chris</firstname>
 	<surname>Shumway</surname>
 	<contrib>Rewritten by </contrib>
       </author>
     </authorgroup>
     <!-- 10 Mar 2000 -->
   </chapterinfo>
 
   <title>Unix Basics</title>
   
   <sect1>
     <title>Synopsis</title>
     <indexterm><primary>basics</primary></indexterm>
 
 
    <para>The following chapter will cover the basic commands and
      functionality of the FreeBSD operating system.  Much of this
      material is relevant for any Unix-like operating system.  Feel
      free to skim over this chapter if you are familiar with the
      material.  If you are new to FreeBSD, then you will definitely
      want to read through this chapter carefully.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How Unix file permissions work.</para>
       </listitem>
       <listitem>
 	<para>What processes, daemons, and signals are.</para>
       </listitem>
       <listitem>
 	<para>What a shell is, and how to change your default login
 	environment.</para>
       </listitem>
       <listitem>
 	<para>How to use basic text editors.</para>
       </listitem>
       <listitem>
 	<para>How to read manual pages for more information.</para>
       </listitem>
     </itemizedlist>
 
   </sect1>
 
   <sect1 id="permissions">
     <title>Permissions</title>
     <indexterm><primary>Unix</primary></indexterm>
 
     <para>FreeBSD, being a direct descendant of BSD Unix, is based on
       several key Unix concepts.  The first, and
       most pronounced, is that FreeBSD is a multi-user operating system.
       The system can handle several users all working simultaneously on
       completely unrelated tasks.  The system is responsible for properly
       sharing and managing requests for hardware devices, peripherals,
       memory, and CPU time evenly to each user.</para>
 
     <para>Because the system is capable of supporting multiple users,
       everything the system manages has a set of permissions governing who
       can read, write, and execute the resource.  These permissions are
       stored as two octets broken into three pieces, one for the owner of
       the file, one for the group that the file belongs to, and one for
       everyone else.  This numerical representation works like
       this:</para>
 
     <indexterm><primary>permissions</primary></indexterm>
     <indexterm>
       <primary>file permissions</primary>
     </indexterm>
     <informaltable frame="none">
       <tgroup cols="3">
 	<thead>
 	  <row>
 	    <entry>Value</entry>
 	    <entry>Permission</entry>
 	    <entry>Directory Listing</entry>
 	  </row>
 	</thead>
 
 	<tbody>
 	  <row>
 	    <entry>0</entry>
 	    <entry>No read, no write, no execute</entry>
 	    <entry><literal>---</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>1</entry>
 	    <entry>No read, no write, execute</entry>
 	    <entry><literal>--x</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>2</entry>
 	    <entry>No read, write, no execute</entry>
 	    <entry><literal>-w-</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>3</entry>
 	    <entry>No read, write, execute</entry>
 	    <entry><literal>-wx</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>4</entry>
 	    <entry>Read, no write, no execute</entry>
 	    <entry><literal>r--</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>5</entry>
 	    <entry>Read, no write, execute</entry>
 	    <entry><literal>r-x</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>6</entry>
 	    <entry>Read, write, no execute</entry>
 	    <entry><literal>rw-</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>7</entry>
 	    <entry>Read, write, execute</entry>
 	    <entry><literal>rwx</literal></entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
     <indexterm>
       <primary><command>ls</command></primary>
     </indexterm>
     <indexterm><primary>directories</primary></indexterm>
 
     <para>You can use the <option>-l</option> command line
       argument to &man.ls.1; to view a long directory listing that
       includes a column with information about a file's permissions
       for the owner, group, and everyone else.  Here is how the first
       column of <command>ls -l</command> is broken up:</para>
 
     <screen>-rw-r--r--</screen>
 
     <para>The first character, from left to right, is a special character
       that tells if this is a regular file, a directory, a special
       character or block device, a socket, or any other special
       pseudo-file device.  The  next three characters, designated as
       <literal>rw-</literal> gives the permissions for the owner of the
       file.  The next three characters, <literal>r--</literal> gives the
       permissions for the group that the file belongs to.  The final three
       characters, <literal>r--</literal>, gives the permissions for the
       rest of the world.  A dash means that the permission is turned off.
       In the case of this file, the permissions are set so the owner can
       read and write to the file, the group can read the file, and the
       rest of the world can only read the file.  According to the table
       above, the permissions for this file would be
       <literal>644</literal>, where each digit represents the three parts
       of the file's permission.</para>
 
     <para>This is all well and good, but how does the system control
       permissions on devices? FreeBSD actually treats most hardware
       devices as a file that programs can open, read, and write data to
       just like any other file.  These special device files are stored on
       the <filename>/dev</filename> directory.</para>
 
     <para>Directories are also treated as files.  They have read, write,
       and execute permissions.  The executable bit for a directory has a
       slightly different meaning than that of files.  When a directory is
       marked executable, it means it can be moved into, i.e. it is
       possible to <quote>cd</quote> into it.  This also means that
       within the directory it is possible to access files whose names are
       known (subject, of course, to the permissions on the files
       themselves).</para>
 
     <para>In particular, in order to able to perform a directory listing,
       read permission must be set on the directory, whilst to delete a file
       that one knows the name of, it is necessary to have write
       <emphasis>and</emphasis> execute permissions to the directory
       containing the file.</para>
 
     <para>There are more to permissions, but they are primarily used in
       special circumstances such as setuid binaries and sticky
       directories.  If you want more information on file permissions and
       how to set them, be sure to look at the &man.chmod.1; man
       page.</para>
   </sect1>
 
   <sect1 id="dirstructure">
     <title>Directory Structure</title>
     <indexterm><primary>directory hierarchy</primary></indexterm>
 
     <para>The FreeBSD directory hierarchy is fundamental to obtaining
       an overall understanding of the system.  The most important
       concept to grasp is that of the root directory,
       <quote>/</quote>.  This directory is the first one mounted at
       boot time and it contains the base system necessary to prepare
       the operating system for multi-user operation.  The root
       directory also contains mount points for every other file system
       that you may want to mount.</para>
 
     <para>A mount point is a directory where additional file systems can
       be grafted onto the root file system.  Standard mount points include
       <filename>/usr</filename>, <filename>/var</filename>,
       <filename>/mnt</filename>, and <filename>/cdrom</filename>.  These
       directories are usually referenced to entries in the file
       <filename>/etc/fstab</filename>.  <filename>/etc/fstab</filename> is
       a table of various file systems and mount points for reference by the
       system.  Most of the file systems in <filename>/etc/fstab</filename>
       are mounted automatically at boot time from the script &man.rc.8;
       unless they contain the <option>noauto</option> option.  Consult the
       &man.fstab.5; manual page for more information on the format of the
       <filename>/etc/fstab</filename> file and the options it
       contains.</para>
 
     <para>A complete description of the filesystem hierarchy is
       available in &man.hier.7;.  For now, a brief overview of the
       most common directories will suffice.</para>
 
     <para>
       <informaltable frame="none">
         <tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Directory</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  <tbody>
             <row>
 	      <entry><filename class="directory">/</filename></entry>
 	      <entry>Root directory of the filesystem.</entry>
             </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/bin/</filename></entry>
 	      <entry>User utilities fundamental to both single-user
 	      and multi-user environments.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/boot/</filename></entry>
 	      <entry>Programs and configuration files used during
 	      operating system bootstrap.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/boot/defaults/</filename></entry>
 	      <entry>Default bootstrapping configuration files; see
 	      &man.loader.conf.5;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/dev/</filename></entry>
 	      <entry>Device nodes; see &man.intro.4;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/</filename></entry>
 	      <entry>System configuration files and scripts.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/defaults/</filename></entry>
 	      <entry>Default system configuration files; see &man.rc.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/mail/</filename></entry>
 	      <entry>Configuration files for mail transport agents such
 		as &man.sendmail.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/namedb/</filename></entry>
 	      <entry><command>named</command> configuration files; see
 	      &man.named.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/periodic/</filename></entry>
 	      <entry>Scripts that are run daily, weekly, and monthly,
 		via &man.cron.8;; see &man.periodic.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/ppp/</filename></entry>
 	      <entry><command>ppp</command> configuration files; see
 	      &man.ppp.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/mnt/</filename></entry>
 	      <entry>Empty directory commonly used by system administrators as a 
 		temporary mount point.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/proc/</filename></entry>
 	      <entry>Process file system; see &man.procfs.5;,
 	      &man.mount.procfs.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/root/</filename></entry>
 	      <entry>Home directory for the <username>root</username>
 	      account.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename class="directory">/sbin/</filename></entry>
 	      <entry>System programs and administration utilities fundamental to
 		both single-user and multi-user environments.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/stand/</filename></entry>
 	      <entry>Programs used in a standalone environment.</entry>
 	    </row>
 	    
 	    
 	    <row>
 	      <entry><filename class="directory">/tmp/</filename></entry>
 	      <entry>Temporary files, usually a &man.mfs.8;
 		memory-based filesystem (the contents of <filename
 		class="directory">/tmp</filename> are usually NOT
 		preserved across a system reboot).</entry>
 	    </row>
 	    
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/</filename></entry>
 	      <entry>The majority of user utilities and applications.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/bin/</filename></entry>
 	      <entry>Common utilities, programming tools, and applications.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/include/</filename></entry>
 	      <entry>Standard C include files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/lib/</filename></entry>
 	      <entry>Archive libraries.</entry>
 	    </row>
 	    
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/libdata/</filename></entry>
 	      <entry>Miscellaneous utility data files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/libexec/</filename></entry>
 	      <entry>System daemons & system utilities (executed by other
 		programs).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename
 	      class="directory">/usr/local/</filename></entry>
 
 	      <entry>Local executables, libraries, etc.  Also used as
 	        the default destination for the FreeBSD ports
 	        framework.  Within <filename>/usr/local</filename>,
 	        the general layout sketched out by &man.hier.7; for
 	        <filename>/usr</filename> should be used.  Exceptions
 	        are the man directory is directly under
 	        <filename>/usr/local</filename> rather than under
 	        <filename>/usr/local/share</filename>.  Ports
 	        documentation is in
 	        <filename>share/doc/<replaceable>port</replaceable></filename>.
 	      </entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/obj/</filename></entry>
 	      <entry>Architecture-specific target tree produced by building
 		the <filename>/usr/src</filename> tree.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/ports</filename></entry>
 	      <entry>The FreeBSD ports collection (optional).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/sbin/</filename></entry>
 	      <entry>System daemons & system utilities (executed by users).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/share/</filename></entry>
 	      <entry>Architecture-independent files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/src/</filename></entry>
 	      <entry>BSD and/or local source files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename
 	      class="directory">/usr/X11R6/</filename></entry>
 	      <entry>X11R6 distribution executables, libraries, etc
 	      (optional).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/var/</filename></entry>
 	      <entry>Multi-purpose log, temporary, transient, and spool files.
 	      </entry>
 	    </row>
 	    
 	    
 	    <row>
 	      <entry><filename class="directory">/var/log/</filename></entry>
 	      <entry>Miscellaneous system log files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/var/mail/</filename></entry>
 	      <entry>User mailbox files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/var/spool/</filename></entry>
 	      <entry>Miscellaneous printer and mail system spooling directories.
 	      </entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/var/tmp/</filename></entry>
 	      <entry>Temporary files that are kept between system reboots.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename>/var/yp</filename></entry>
 	      <entry>NIS maps.</entry>
 	    </row>
 
 	  </tbody>
 	</tgroup>
       </informaltable>
     </para>
 
   </sect1>
 
   <sect1 id="mount-unmount">
     <title>Mounting and Unmounting Filesystems</title>
 
     <para>The filesystem is best visualized as a tree,
       rooted, as it were, at <filename>/</filename>.
       <filename>/dev</filename>, <filename>/usr</filename>, and the
       other directories in the root directory are branches, which may
       have their own branches, such as
       <filename>/usr/local</filename>, and so on.</para>
 
     <indexterm><primary>root filesystem</primary></indexterm>
     <para>There are various reasons to house some of these
       directories on separate filesystems.  <filename>/var</filename>
       contains the directories <filename>log/</filename>,
       <filename>spool/</filename>,
       and various types of temporary files, and
       as such, may get filled up.  Filling up the root filesystem
       is not a good idea, so splitting <filename>/var</filename> from
       <filename>/</filename> is often favorable.</para>
 
     <para>Another common reason to contain certain directory trees on
       other filesystems is if they are to be housed on separate
       physical disks, or are separate virtual disks, such as <link
 	linkend="nfs">Network File System</link> mounts, or CDROM
       drives.</para>
 
     <sect2 id="disks-fstab">
       <title>The <filename>fstab</filename> File</title>
       <indexterm>
 	<primary>filesystems</primary>
 	<secondary>mounted with fstab</secondary>
       </indexterm>
 
       <para>During the <link linkend="boot">boot process</link>,
 	filesystems listed in <filename>/etc/fstab</filename> are
 	automatically mounted (unless they are listed with the
 	<option>noauto</option> option).</para>
 
       <para>The <filename>/etc/fstab</filename> file contains a list
 	of lines of the following format:</para>
 
       <programlisting><replaceable>device</replaceable>       <replaceable>/mount-point</replaceable> <replaceable>fstype</replaceable>     <replaceable>options</replaceable>      <replaceable>dumpfreq</replaceable>     <replaceable>passno</replaceable></programlisting>
 
       <variablelist>
 	<varlistentry>
 	  <term><literal>device</literal></term>
 	  <listitem>
 	    <para>A device name (which should exist), as explained in
 	      <link linkend="disks-naming">Disk naming
 		conventions</link> above.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>mount-point</literal></term>
             
 	  <listitem><para>A directory (which should exist), on which
 	      to mount the filesystem.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><literal>fstype</literal></term>
             
 	  <listitem><para>The filesystem type to pass to
 		&man.mount.8;.  The default FreeBSD filesystem is
 	      <literal>ufs</literal>.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><literal>options</literal></term>
             
 	  <listitem><para>Either <option>rw</option> for read-write
 	      filesystems, or <option>ro</option> for read-only
 	      filesystems, followed by any other options that may be
 	      needed.  A common option is <option>noauto</option> for
 	      filesystems not normally mounted during the boot sequence.
 	      Other options are listed in the &man.mount.8; manual page.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><literal>dumpfreq</literal></term>
           
          <listitem><para>This is used by dump to determine which
              filesystems require dumping.  If the field is missing,
              a value of zero is assumed.</para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><literal>passno</literal></term>
 
          <listitem>
            <para>This determines the order in which filesystems should
            be checked.  Filesystems that should be skipped should have
            their <literal>passno</literal> set to zero.  The root
            filesystem (which needs to be checked before everything
            else) should have it's <literal>passno</literal> set to
            one, and other filesystems' <literal>passno</literal>
            should be set to values greater than one.  If more than one
            filesystems have the same <literal>passno</literal> then
            &man.fsck.8; will attempt to check filesystems in parallel
            if possible.</para>
          </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2 id="disks-mount">
       <title>The mount Command</title>
       <indexterm>
 	<primary>filesystems</primary>
 	<secondary>mounting</secondary>
       </indexterm>
         
       <para>The &man.mount.8; command is what is ultimately used to
 	mount filesystems.</para>
         
       <para>In its most basic form, you use:</para>
 
       <informalexample>
 	<screen>&prompt.root; <userinput>mount <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></userinput></screen>
       </informalexample>
 
       <para>There are plenty of options, as mentioned in the
 	  &man.mount.8; manual page, but the most common are:</para>
 
       <variablelist>
 	<title>Mount Options</title>
 
 	<varlistentry>
 	  <term><option>-a</option></term>
             
 	  <listitem>
 	    <para>Mount all the filesystems listed in
 	      <filename>/etc/fstab</filename>.  Exceptions are those
 	      marked as <quote>noauto</quote>, excluded by the
 	      <option>-t</option> flag, or those that are already
 	      mounted.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-d</option></term>
             
 	  <listitem>
 	    <para>Do everything except for the actual system call.
 	      This option is useful in conjunction with the
 	      <option>-v</option> flag to determine what the
 	      <command>mount</command> is actually trying to do.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-f</option></term>
 
 	  <listitem>
 	    <para>Force the mount of an unclean filesystem
 	      (dangerous), or forces the revocation of write access
 	      when downgrading a filesystem's mount status from
 	      read-write to read-only.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
           <term><option>-r</option></term>
             
 	  <listitem>
 	    <para>Mount the filesystem read-only.  This is identical
 	      to using the <option>rdonly</option> argument to the
 	      <option>-o</option> option.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-t</option>
 	    <replaceable>fstype</replaceable></term>
 
 	  <listitem>
 	    <para>Mount the given filesystem as the given filesystem
 	      type, or mount only filesystems of the given type, if
 	      given the <option>-a</option> option.</para>
               
 	    <para><quote>ufs</quote> is the default filesystem
 	      type.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-u</option></term>
             
 	  <listitem>
 	    <para>Update mount options on the filesystem.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-v</option></term>
             
 	  <listitem>
 	    <para>Be verbose.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-w</option></term>
             
 	  <listitem>
 	    <para>Mount the filesystem read-write.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
         
       <para>The <option>-o</option> option takes a comma-separated list of
 	the options, including the following:</para>
         
       <variablelist>
 	<varlistentry>
 	  <term>nodev</term>
             
 	  <listitem>
 	    <para>Do not interpret special devices on the
 	      filesystem.  This is a useful security option.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term>noexec</term>
             
 	  <listitem>
               <para>Do not allow execution of binaries on this
 	      filesystem.  This is also a useful security option.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term>nosuid</term>
             
 	  <listitem>
 	    <para>Do not interpret setuid or setgid flags on the
 	      filesystem.  This is also a useful security option.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2 id="disks-umount">
       <title>The <command>umount</command> Command</title>
       <indexterm>
 	<primary>filesystems</primary>
 	<secondary>unmounting</secondary>
       </indexterm>
         
       <para>The &man.umount.8; command takes, as a parameter, one of a
 	mountpoint, a device name, or the <option>-a</option> or
 	<option>-A</option> option.</para>
         
       <para>All forms take <option>-f</option> to force unmounting,
         and <option>-v</option> for verbosity.  Be warned that
         <option>-f</option> is not generally a good idea.  Forcibly
         unmounting filesystems might crash the computer or damage data
         on the filesystem.</para>
         
       <para><option>-a</option> and <option>-A</option> are used to
 	unmount all mounted filesystems, possibly modified by the
 	filesystem types listed after <option>-t</option>.
 	<option>-A</option>, however, does not attempt to unmount the
 	root filesystem.</para>
     </sect2>
   </sect1>
 
   <sect1 id="basics-processes">
     <title>Processes</title>
 
     <para>FreeBSD is a multi-tasking operating system.  This means that it
       seems as though more than one program is running at once.  Each program
       running at any one time is called a <firstterm>process</firstterm>.
       Every command you run will start at least one new process, and there are
       a number of system processes that run all the time, keeping the system
       functional.</para>
 
     <para>Each process is uniquely identified by a number called a
       <firstterm>process ID</firstterm>, or <firstterm>PID</firstterm>, and,
       like files, each process also has one owner and group.  The owner and
       group information is used to determine what files and devices the
       process can open, using the file permissions discussed earlier.  Most
       processes also have a parent process.  The parent process is the process
       that started them.  For example, if you are typing commands to the shell
       then the shell is a process, and any commands you run are also
       processes.  Each process you run in this way will have your shell as its
       parent process.  The exception to this is a special process called
       <command>init</command>.  <command>init</command> is always the first
       process, so its PID is always 1.  <command>init</command> is started
       automatically by the kernel when FreeBSD starts.</para>
 
     <para>Two commands are particularly useful to see the processes on the
       system, &man.ps.1; and &man.top.1;.  The &man.ps.1; command is used to
       show a static list of the currently running processes, and can show
       their PID, how much memory they are using, the command line they were
       started with, and so on.  The &man.top.1; command displays all the
       running processes, and updates the display every few seconds, so that
       you can interactively see what your computer is doing.</para>
 
     <para>By default, &man.ps.1; only shows you the commands that are running
       and are owned by you.  For example:</para>
 
     <screen>&prompt.user; <userinput>ps</userinput>
   PID  TT  STAT      TIME COMMAND
   298  p0  Ss     0:01.10 tcsh
  7078  p0  S      2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
 37393  p0  I      0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
 48630  p0  S      2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
 48730  p0  IW     0:00.00 (dns helper) (navigator-linux-)
 72210  p0  R+     0:00.00 ps
   390  p1  Is     0:01.14 tcsh
  7059  p2  Is+    1:36.18 /usr/local/bin/mutt -y
  6688  p3  IWs    0:00.00 tcsh
 10735  p4  IWs    0:00.00 tcsh
 20256  p5  IWs    0:00.00 tcsh
   262  v0  IWs    0:00.00 -tcsh (tcsh)
   270  v0  IW+    0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
   280  v0  IW+    0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
   284  v0  IW     0:00.00 /bin/sh /home/nik/.xinitrc
   285  v0  S      0:38.45 /usr/X11R6/bin/sawfish</screen>
 
     <para>As you can see in this example, the output from &man.ps.1; is
       organized in to a number of columns.  <literal>PID</literal> is the
       process ID discussed earlier.  PIDs are assigned starting from 1, go up
       to 99999, and wrap around back to the beginning when you run out.
       <literal>TT</literal> shows the tty the program is running on, and can
       safely be ignored for the moment.  <literal>STAT</literal> shows the
       program's state, and again, can be safely ignored.
       <literal>TIME</literal> is the amount of time the program has been
       running on the CPU&mdash;this is not necessarily the elapsed time since
       you started the program, as some programs spend a lot of time waiting
       for things to happen before they need to spend time on the CPU.
       Finally, <literal>COMMAND</literal> is the command line that was used to
       run the program.</para>
 
     <para>&man.ps.1; supports a number of different options to change the
       information that is displayed.  One of the most useful sets is
       <literal>auxww</literal>.  <option>a</option> displays information
       about all the running processes, not just your own.  <option>u</option>
       displays the username of the process' owner, as well as memory usage.
       <option>x</option> displays information about daemon processes, and
       <option>ww</option> causes &man.ps.1; to display the full command line,
       rather than truncating it once it gets too long to fit on the
       screen.</para>
 
     <para>The output from &man.top.1; is similar.  A sample session looks like
       this:</para>
 
     <screen>&prompt.user; <userinput>top</userinput>
 last pid: 72257;  load averages:  0.13,  0.09,  0.03    up 0+13:38:33  22:39:10
 47 processes:  1 running, 46 sleeping
 CPU states: 12.6% user,  0.0% nice,  7.8% system,  0.0% interrupt, 79.7% idle
 Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
 Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
 
   PID USERNAME PRI NICE  SIZE    RES STATE    TIME   WCPU    CPU COMMAND
 72257 nik       28   0  1960K  1044K RUN      0:00 14.86%  1.42% top
  7078 nik        2   0 15280K 10960K select   2:54  0.88%  0.88% xemacs-21.1.14
   281 nik        2   0 18636K  7112K select   5:36  0.73%  0.73% XF86_SVGA
   296 nik        2   0  3240K  1644K select   0:12  0.05%  0.05% xterm
 48630 nik        2   0 29816K  9148K select   3:18  0.00%  0.00% navigator-linu
   175 root       2   0   924K   252K select   1:41  0.00%  0.00% syslogd
  7059 nik        2   0  7260K  4644K poll     1:38  0.00%  0.00% mutt
 ...</screen>
 
     <para>The output is split in to two sections.  The header (the first five
       lines) shows the PID of the last process to run, the system load averages
       (which are a measure of how busy the system is), the system uptime (time
       since the last reboot) and the current time.  The other figures in the
       header relate to how many processes are running (47 in this case), how
       much memory and swap space has been taken up, and how much time the
       system is spending in different CPU states.</para>
 
     <para>Below that are a series of columns containing similar information
       to the output from &man.ps.1;.  As before you can see the PID, the
       username, the amount of CPU time taken, and the command that was run.
       &man.top.1; also defaults to showing you the amount of memory space
       taken by the process.  This is split in to two columns, one for total
       size, and one for resident size&mdash;total size is how much memory the
       application has needed, and the resident size is how much it is actually
       using at the moment.  In this example you can see that Netscape has
       required almost 30 MB of RAM, but is currently only using 9 MB.</para>
 
     <para>&man.top.1; automatically updates this display every two seconds;
       this can be changed with the <option>s</option> option.</para>
   </sect1>
 
   <sect1>
     <title>Daemons, Signals, and Killing Processes</title>
 
     <para>When you run an editor it is easy to control the editor, tell it to
       load files, and so on.  You can do this because the editor provides
       facilities to do so, and because the editor is attached to a
       <firstterm>terminal</firstterm>.  Some programs are not designed to be
       run with continuous user input, and so they disconnect from the terminal
       at the first opportunity.  For example, a web server spends all day
       responding to web requests, it normally does not need any input from
       you.  Programs that transport email from site to site are another
       example of this class of application.</para>
 
     <para>We call these programs <firstterm>daemons</firstterm>.  Daemons were
       characters in Greek mythology; neither good or evil, they were little
       attendant spirits that, by and large, did useful things for mankind.
       Much like the web servers and mail servers of today do useful things.
       This is why the BSD mascot has, for a long time, been the cheerful
       looking daemon with sneakers and a pitchfork.</para>
 
     <para>There is a convention to name programs that normally run as daemons
       with a trailing <quote>d</quote>. <application>BIND</application> is the
       Berkeley Internet Name Daemon (and the actual program that executes is called
       <command>named</command>), the <application>Apache</application> web
       server program is called <command>httpd</command>, the line printer
       spooling daemon is <command>lpd</command> and so on.  This is a
       convention, not a hard and fast rule; for example, the main mail daemon
       for the <application>Sendmail</application> application is called
       <command>sendmail</command>, and not <command>maild</command>, as you
       might imagine.</para>
 
     <para>Sometimes you will need to communicate with a daemon process.  These
       communications are called <firstterm>signals</firstterm>, and you can
       communicate with daemons (or with any running process) by sending it a
       signal.  There are a number of different signals that you can
       send&mdash;some of them have a specific meaning, others are interpreted
       by the application, and the application's documentation will tell you
       how that application interprets signals.  You can only send a signal to
-      a process that you own.  If you try and send a signal to someone else's
-      process it will be ignored.  The exception to this is the
+      a process that you own.  If you send a signal to someone else's
+      process with &man.kill.1; or &man.kill.2; permission will be denied.
+      The exception to this is the
       <username>root</username> user, who can send signals to everyone's
       processes.</para>
 
     <para>FreeBSD will also send applications signals in some cases.  If an
       application is badly written, and tries to access memory that it is not
       supposed to, FreeBSD sends the process the <firstterm>Segmentation
 	Violation</firstterm> signal (<literal>SIGSEGV</literal>).  If an
       application has used the &man.alarm.3; system call to be alerted after a
       period of time has elapsed then it will be sent the Alarm signal
       (<literal>SIGALRM</literal>), and so on.</para>
 
     <para>Two signals can be used to stop a process,
       <literal>SIGTERM</literal> and <literal>SIGKILL</literal>.
       <literal>SIGTERM</literal> is the polite way to kill a process; the
       process can <emphasis>catch</emphasis> the signal, realize that you want
       it to shut down, close any log files it may have open, and generally
       finish whatever it is doing at the time before shutting down.  In some
       cases a process may even ignore <literal>SIGTERM</literal> if it is in
       the middle of some task that can not be interrupted.</para>
 
     <para><literal>SIGKILL</literal> can not be ignored by a process.  This is
       the <quote>I do not care what you are doing, stop right now</quote>
       signal.  If you send <literal>SIGKILL</literal> to a process then
       FreeBSD will stop that process there and then<footnote>
 	<para>Not quite true&mdash;there are a few things that can not be
 	  interrupted.  For example, if the process is trying to read from a
 	  file that is on another computer on the network, and the other
 	  computer has gone away for some reason (been turned off, or the
 	  network has a fault), then the process is said to be
 	  <quote>uninterruptible</quote>.  Eventually the process will time
 	  out, typically after two minutes.  As soon as this time out occurs
 	  the process will be killed.</para>
       </footnote>.</para>
 
     <para>The other signals you might want to use are
       <literal>SIGHUP</literal>, <literal>SIGUSR1</literal>, and
       <literal>SIGUSR2</literal>.  These are general purpose signals, and
       different applications will do different things when they are
       sent.</para>
 
     <para>Suppose that you have changed your web server's configuration
       file&mdash;you would like to tell the web server to re-read its
       configuration.  You could stop and restart <command>httpd</command>, but
       this would result in a brief outage period on your web server, which may
       be undesirable.  Most daemons are written to respond to the
       <literal>SIGHUP</literal> signal by re-reading their configuration
       file.  So instead of killing and restarting <command>httpd</command> you
       would send it the <literal>SIGHUP</literal> signal.  Because there is no
       standard way to respond to these signals, different daemons will have
       different behavior, so be sure and read the documentation for the
       daemon in question.</para>
     
     <para>Signals are sent using the &man.kill.1; command, as this example
       shows.</para>
 
     <procedure>
       <title>Sending a Signal to a Process</title>
 
       <para>This example shows how to send a signal to &man.inetd.8;.  The
 	  &man.inetd.8; configuration file is
 	<filename>/etc/inetd.conf</filename>, and &man.inetd.8; will re-read
 	this configuration file when it is sent
 	<literal>SIGHUP</literal>.</para>
 
       <step>
 	<para>Find the process ID of the process you want to send the signal
 	  to.  Do this using &man.ps.1; and &man.grep.1;.  The &man.grep.1;
 	  command is used to search through output, looking for the string you
 	  specify.  This command is run as a normal user, and &man.inetd.8; is
 	  run as <username>root</username>, so the <option>ax</option> options
 	  must be given to &man.ps.1;.</para>
 
 	<screen>&prompt.user; <userinput>ps -ax | grep inetd</userinput>
   198  ??  IWs    0:00.00 inetd -wW</screen>
 
 	<para>So the &man.inetd.8; PID is 198.  In some cases the
 	  <literal>grep inetd</literal> command might also occur in this
 	  output.  This is because of the way &man.ps.1; has to find the list
 	  of running processes.</para>
       </step>
 
       <step>
 	<para>Use &man.kill.1; to send the signal.  Because &man.inetd.8; is
 	  being run by <username>root</username> you must use &man.su.1; to
 	  become <username>root</username> first.</para>
 
 	<screen>&prompt.user; <userinput>su</userinput>
 <prompt>Password:</prompt>
 &prompt.root; <userinput>/bin/kill -s HUP 198</userinput></screen>
 
 	<para>In common most with Unix commands, &man.kill.1; will not print any
-	  output if it is successful.  If you try and send a signal to a
+	  output if it is successful.  If you send a signal to a
 	  process that you do not own then you will see <errorname>kill:
 	    <replaceable>PID</replaceable>: Operation not
 	    permitted</errorname>.  If you mistype the PID you will either
 	  send the signal to the wrong process, which could be bad, or, if
 	  you are lucky, you will have sent the signal to a PID that is not
 	  currently in use, and you will see <errorname>kill:
 	    <replaceable>PID</replaceable>: No such process</errorname>.</para>
 
 	<note>
 	  <title>Why Use <command>/bin/kill</command>?</title>
 
 	  <para>Many shells provide the <command>kill</command> command as a
 	    built in command; that is, the shell will send the signal
 	    directly, rather than running <filename>/bin/kill</filename>.
 	    This can be very useful, but different shells have a different
 	    syntax for specifying the name of the signal to send.  Rather than
 	    try to learn all of them, it can be simpler just to use the
 	    <command>/bin/kill <replaceable>...</replaceable></command>
 	    command directly.</para>
 	</note>
       </step>
     </procedure>
 
     <para>Sending other signals is very similar, just substitute
       <literal>TERM</literal> or <literal>KILL</literal> in the command line
       as necessary.</para>
 
     <important>
       <para>Killing random process on the system can be a bad idea.  In
 	particular, &man.init.8;, process ID 1, is very special.  Running
 	<command>/bin/kill -s KILL 1</command> is a quick way to shutdown your
 	system.  <emphasis>Always</emphasis> double check the arguments you
 	run &man.kill.1; with <emphasis>before</emphasis> you press
 	<keycap>Return</keycap>.</para>
     </important>
   </sect1>
 
   <sect1 id="shells">
     <title>Shells</title>
     <indexterm><primary>shells</primary></indexterm>
     <indexterm><primary>command-line</primary></indexterm>
 
     <para>In FreeBSD, a lot of everyday work is done in a command line
       interface called a shell.  A shell's main job is to take commands
       from the input channel and execute them.  A lot of shells also have
       built in functions to help everyday tasks such a file management,
       file globing, command line editing, command macros, and environment
       variables.  FreeBSD comes with a set of shells, such as 
       <command>sh</command>, the Bourne Shell, and <command>tcsh</command>, 
       the improved C-shell.  Many other shells are available
       from the FreeBSD Ports Collection, such as
       <command>zsh</command> and <command>bash</command>.</para>
 
     <para>Which shell do you use?  It is really a matter of taste.  If you
       are a C programmer you might feel more comfortable with a C-like shell
       such as <command>tcsh</command>.  If you have come from Linux or are new 
       to a Unix command line interface you might try <command>bash</command>.  
       The point is that each
       shell has unique properties that may or may not work with your
       preferred working environment, and that you have a choice of what
       shell to use.</para>
 
     <para>One common feature in a shell is file-name completion.  Given
       the typing of the first few letters of a command or filename, you
       can usually have the shell automatically complete the rest of the
       command or filename by hitting the <keycap>Tab</keycap> key on the keyboard.  Here is
       an example.  Suppose you have two files called
       <filename>foobar</filename> and <filename>foo.bar</filename>.  You
       want to delete <filename>foo.bar</filename>.  So what you would type
       on the keyboard is: <command>rm fo[<keycap>Tab</keycap>].[<keycap>Tab</keycap>]</command>.</para>
 
     <para>The shell would print out <command>rm
       foo[BEEP].bar</command>.</para>
 
     <para>The [BEEP] is the console bell, which is the shell telling me it
       was unable to totally complete the filename because there is more
       than one match.  Both <filename>foobar</filename> and
       <filename>foo.bar</filename> start with <literal>fo</literal>, but
       it was able to complete to <literal>foo</literal>.  If you type in
       <literal>.</literal>, then hit <keycap>Tab</keycap> again, the shell would be able to
       fill in the rest of the filename for you.</para>
     <indexterm><primary>environment variables</primary></indexterm>
 
     <para>Another function of the shell is environment variables.
       Environment variables are a variable key pair stored in the shell's
       environment space.  This space can be read by any program invoked by
       the shell, and thus contains a lot of program configuration.  Here
       is a list of common environment variables and what they mean:</para>
     <indexterm><primary>environment variables</primary></indexterm>
 
     <informaltable frame="none">
       <tgroup cols="2">
 	<thead>
 	  <row>
 	    <entry>Variable</entry>
 	    <entry>Description</entry>
 	  </row>
 	</thead>
 
 	<tbody>
 	  <row>
 	    <entry><envar>USER</envar></entry>
 	    <entry>Current logged in user's name.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>PATH</envar></entry>
 	    <entry>Colon separated list of directories to search for
 	      binaries.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>DISPLAY</envar></entry>
 	    <entry>Network name of the X11 display to connect to, if
 	      available.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>SHELL</envar></entry>
 	    <entry>The current shell.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>TERM</envar></entry>
 	    <entry>The name of the user's terminal.  Used to determine the
 	      capabilities of the terminal.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>TERMCAP</envar></entry>
 	    <entry>Database entry of the terminal escape codes to perform
 	      various terminal functions.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>OSTYPE</envar></entry>
 	    <entry>Type of operating system.  e.g., FreeBSD.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>MACHTYPE</envar></entry>
 	    <entry>The CPU architecture that the system is running
 	      on.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>EDITOR</envar></entry>
 	    <entry>The user's preferred text editor.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>PAGER</envar></entry>
 	    <entry>The user's preferred text pager.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>MANPATH</envar></entry>
 	    <entry>Colon separated list of directories to search for
 	      manual pages.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
 
     <indexterm><primary>Bourne shells</primary></indexterm>
     <para>To view or set an environment variable differs somewhat from
       shell to shell.  For example, in the C-Style shells such as
       <command>tcsh</command> and <command>csh</command>, you would use
       <command>setenv</command> to set and view environment variables.
       Under Bourne shells such as <command>sh</command> and
       <command>bash</command>, you would use <command>set</command> and
       <command>export</command> to view and set your current environment
       variables.  For example, to set or modify the
       <envar>EDITOR</envar> environment variable, under <command>csh</command> or 
       <command>tcsh</command> a
       command like this would set <envar>EDITOR</envar> to
       <filename>/usr/local/bin/emacs</filename>:</para>
 
     <screen>&prompt.user; <userinput>setenv EDITOR /usr/local/bin/emacs</userinput></screen>
 
     <para>Under Bourne shells:</para>
 
     <screen>&prompt.user; <userinput>export EDITOR="/usr/local/bin/emacs"</userinput></screen>
 
     <para>You can also make most shells expand the environment variable by
       placing a <literal>$</literal> character in front of it on the
       command line.  For example, <command>echo $TERM</command> would
       print out whatever <envar>$TERM</envar> is set to, because the shell
       expands <envar>$TERM</envar> and passes it on to echo.</para>
 
     <para>Shells treat a lot of special characters, called meta-characters
       as special representations of data.  The most common one is the
       <literal>*</literal> character, which represents any number of
       characters in a filename.  These special meta-characters can be used
       to do file name globing.  For example, typing in
       <command>echo *</command> is almost the same as typing in
       <command>ls</command> because the shell takes all the files that
       match <command>*</command> and puts them on the command line for
       echo to see.</para>
 
     <para>To prevent the shell from interpreting these special characters,
       they can be escaped from the shell by putting a backslash
       (<literal>\</literal>) character in front of them.  <command>echo
       $TERM</command> prints whatever your terminal is set to.
       <command>echo \$TERM</command> prints <envar>$TERM</envar> as
       is.</para>
 
     <sect2 id="changing-shells">
       <title>Changing Your Shell</title>
 
       <para>The easiest way to change your shell is to use the
 	<command>chsh</command> command.  Running <command>chsh</command> will
 	place you into the editor that is in your <envar>EDITOR</envar>
 	environment variable; if it is not set, you will be placed in
 	<command>vi</command>.  Change the <quote>Shell:</quote> line
 	accordingly.</para>
 
       <para>You can also give <command>chsh</command> the
 	<option>-s</option> option; this will set your shell for you,
 	without requiring you to enter an editor.  
 	For example, if you wanted to
 	change your shell to bash, the following should do the
 	trick:</para>
 	
       <screen>&prompt.user; <userinput>chsh -s /usr/local/bin/bash</userinput></screen>
 
       <para>Running <command>chsh</command> with no parameters and editing
 	the shell from there would work also.</para>
 
       <note>
 	<para>The shell that you wish to use <emphasis>must</emphasis> be
 	  present in the <filename>/etc/shells</filename> file.  If you
 	  have installed a shell from the <link linkend="ports">ports
 	  collection</link>, then this should have been done for you
 	  already.  If you installed the shell by hand, you must do
 	  this.</para>
      
       <para>For example, if you installed <command>bash</command> by hand
 	and placed it into <filename>/usr/local/bin</filename>, you would
 	want to:</para>
 
       <screen>&prompt.root; <userinput>echo &quot;/usr/local/bin/bash&quot; &gt;&gt; /etc/shells</userinput></screen>
 
        <para>Then rerun <command>chsh</command>.</para>
      </note>
    </sect2>
   </sect1>
 
   <sect1 id="editors">
     <title>Text Editors</title>
     <indexterm><primary>text editors</primary></indexterm>
     <indexterm><primary>editors</primary></indexterm>
 
     <para>A lot of configuration in FreeBSD is done by editing text files.
       Because of this, it would be a good idea to become familiar
       with a text editor.  FreeBSD comes with a few as part of the base
       system, and many more are available in the ports collection.</para>
 
     <indexterm>
       <primary><command>ee</command></primary>
     </indexterm>
     <para>The easiest and simplest editor to learn is an editor called
       <application>ee</application>, which stands for easy editor.  To
       start <application>ee</application>, one would type at the command
       line <command>ee filename</command> where
       <literal>filename</literal> is the name of the file to be edited.
       For example, to edit <filename>/etc/rc.conf</filename>, type in
       <command>ee /etc/rc.conf</command>.  Once inside of 
       <command>ee</command>, all of the
       commands for manipulating the editor's functions are listed at the
       top of the display. The caret <literal>^</literal> character means
       the control key on the keyboard, so ^e expands to pressing the
       control key plus the letter <literal>e</literal>.  To leave
       <application>ee</application>, hit the escape key, then choose leave
       editor.  The editor will prompt you to save any changes if the file
       has been modified.</para>
 
     <indexterm>
       <primary><command>vi</command></primary>
     </indexterm>
     <indexterm>
       <primary>editors</primary>
       <secondary><command>vi</command></secondary>
     </indexterm>
     <indexterm>
       <primary><command>emacs</command></primary>
     </indexterm>
     <indexterm>
       <primary>editors</primary>
       <secondary><command>emacs</command></secondary>
     </indexterm>
     <para>FreeBSD also comes with more powerful text editors such as
       <command>vi</command> as part of the base system, and
       <command>emacs</command> and <command>vim</command>
       as part of the FreeBSD Ports Collection.  These editors offer much
       more functionality and power at the expense of being a little more
       complicated to learn.  However if you plan on doing a lot of text
       editing, learning a more powerful editor such as
       <command>vim</command> or <command>emacs</command>
       will save you much more time in the long run.</para>
   </sect1>
 
   <sect1>
     <title>Devices and Device Nodes</title>
 
     <para>A device is a term used mostly for hardware-related
       activities in a system, including disks, printers, graphics
       cards, and keyboards.  When FreeBSD boots, the majority
       of what FreeBSD displays are devices being detected.
       You can look through the boot messages again by viewing
       <filename>/var/run/dmesg.boot</filename>.</para>
 
     <para>For example, <devicename>acd0</devicename> is the
       first IDE CDROM drive, while <devicename>kbd0</devicename>
       represents the keyboard.</para>
 
     <para>Most of these devices in a Unix operating system must be
       accessed through a special file called device nodes, which are
       located in the <filename>/dev</filename> directory.</para>
 
     <sect2>
       <title>Creating Device Nodes</title>
       <para>When adding a new device to your system, or compiling
 	in support for additional devices, a device driver
 	often-times needs to be created.</para>
 
       <sect3>
 	<title>MAKEDEV Script</title>
 	<para>On systems without DEVFS, device nodes are created
 	  using the &man.MAKEDEV.8; script as shown below:</para>
 
 	<screen>&prompt.root; cd /dev
 &prompt.root; sh MAKEDEV ad1
 	</screen>
 
 	<para>This example would make the proper device nodes
 	  for the second IDE drive when installed.</para>
       </sect3>
 
       <sect3>
 	<title>devfs (Device File System)</title>
 
 	<para> The device file system, or devfs, provides access to
 	  kernel's device namespace in the global filesystem namespace.
 	  Instead of having to create and modify device nodes,
 	  devfs maintains this particular filesystem for you.</para>
 
 	<para>See the &man.devfs.5; man page for more
 	  information.</para>
 
 	<para>devfs is used by default in FreeBSD 5.0.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1>
     <title>For More Information...</title>
 
     <sect2 id="basics-man">
       <title>Manual Pages</title>
       <indexterm><primary>manual pages</primary></indexterm>
 
       <para>The most comprehensive documentation on FreeBSD is in the form
 	of manual pages. Nearly every program on the system comes with a
 	short reference manual explaining the basic operation and various
 	arguments. These manuals can be viewed with the <command>man</command> command.  Use
 	of the <command>man</command> command is simple:</para>
 
       <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
 
       <para><literal>command</literal> is the name of the command you
         wish to learn about.  For example, to learn more about
 	<command>ls</command> command type:</para>
 
       <screen>&prompt.user; <userinput>man ls</userinput></screen>
 
       <para>The online manual is divided up into numbered sections:</para>
 
       <orderedlist>
 	<listitem>
 	  <para>User commands.</para>
 	</listitem>
 
 	<listitem>
 	  <para>System calls and error numbers.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Functions in the C libraries.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Device drivers.</para>
 	</listitem>
 
 	<listitem>
 	  <para>File formats.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Games and other diversions.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Miscellaneous information.</para>
 	</listitem>
 
 	<listitem>
 	  <para>System maintenance and operation commands.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Kernel developers.</para>
 	</listitem>
       </orderedlist>
 
       <para>In some cases, the same topic may appear in more than one
 	section of the online manual.  For example, there is a
 	<command>chmod</command> user command and a
 	<function>chmod()</function> system call.  In this case, you can
 	tell the man command which one you want by specifying the
 	section:</para>
 
       <screen>&prompt.user; <userinput>man 1 chmod</userinput></screen>
 
       <para>This will display the manual page for the user command
         <command>chmod</command>. References to a particular section of
 	the online manual are traditionally placed in parenthesis in
 	written documentation, so &man.chmod.1; refers to the
 	<command>chmod</command> user command and &man.chmod.2; refers to
 	the system call.</para>
 
       <para>This is fine if you know the name of the command and simply
 	wish to know how to use it, but what if you cannot recall the
 	command name?  You can use <command>man</command> to search for keywords in the
 	command descriptions by using the <option>-k</option>
 	switch:</para>
 
       <screen>&prompt.user; <userinput>man -k mail</userinput></screen>
 
       <para>With this command you will be presented with a list of
         commands that have the keyword <quote>mail</quote> in their
 	descriptions.  This is actually functionally equivalent to using
 	the <command>apropos</command> command.</para>
 
       <para>So, you are looking at all those fancy commands in
 	<filename>/usr/bin</filename> but do not have the faintest idea
 	what most of them actually do?  Simply do:</para>
 
 	<screen>&prompt.user; <userinput>cd /usr/bin</userinput>
 &prompt.user; <userinput>man -f *</userinput></screen>
 
 	<para>or</para>
 
 	<screen>&prompt.user; <userinput>cd /usr/bin</userinput>
 &prompt.user; <userinput>whatis *</userinput></screen>
 
 	<para>which does the same thing.</para>
     </sect2>
 
     <sect2 id="basics-info">
       <title>GNU Info Files</title>
       <indexterm><primary>Free Software Foundation</primary></indexterm>
 
       <para>FreeBSD includes many applications and utilities produced by
 	the Free Software Foundation (FSF).  In addition to manual pages,
 	these programs come with more extensive hypertext documents called
 	<literal>info</literal> files which can be viewed with the
 	<command>info</command> command or, if you installed
 	<application>emacs</application>, the info mode of
 	<application>emacs</application>.</para>
 
       <para>To use the &man.info.1; command, simply type:</para>
 
       <screen>&prompt.user; <userinput>info</userinput></screen>
 
       <para>For a brief introduction, type <literal>h</literal>.  For a
 	quick command reference, type <literal>?</literal>.</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/contrib/chapter.sgml b/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
index ee4550f378..df3aafdbd7 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
+	    release once a day &mdash; every now and again, try to 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;
 	    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 672cd044bc..45be67436f 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -1,1808 +1,1808 @@
 <!--
      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
 	      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
+	<para>otherwise it would try to install profiled libraries that
 	  had not been built during the <command>make buildworld</command>
 	  phase.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Update Files Not Updated by <command>make 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 described below.
         Be sure to make a backup of
         <filename>/etc</filename> in case anything goes wrong.</para>
 
       <para>The &man.mergemaster.8; utility is a Bourne script that will
         aid you in determining the differences between your configuration files
         in <filename>/etc</filename>, and the configuration files in
         the source tree <filename>/usr/src/etc</filename>. This is
         the recommended solution for keeping the system configuration files up to date
         with those located in the source tree.</para>
 
       <para><command>mergemaster</command> was integrated into the FreeBSD base
         system between 3.3-RELEASE and 3.4-RELEASE, which means it is
         present in all -STABLE and -CURRENT systems since 3.3.</para>
 
       <para>To begin simply type <command>mergemaster</command> at your prompt, and
         watch it start going.  <command>mergemaster</command> will then build a
         temporary root environment, from <filename>/</filename> down, and populate
         it with various system configuration files.  Those files are then compared
         to the ones currently installed in your system.  At this point, files that
         differ will be shown in &man.diff.1; format, with the <option>+</option> sign
         representing added or modified lines, and <option>-</option> representing
         lines that will be removed either completely, or replaced with a new line.
         See the &man.diff.1; manual page for more information about the &man.diff.1;
         syntax and how file differences are shown.</para>
 
       <para>&man.mergemaster.8; will then show you each file that displays variances,
         and at this point you will have the option of either deleting the new file (referred
         to as the temporary file), install the temporary file in its unmodified state,
         merge the temporary file with the currently installed file, or view the
         &man.diff.1; results again.</para>
 
       <para>Choosing to delete the temporary will tell &man.mergemaster.8; that we
         wish to keep our current file unchanged, and to delete the one that is
         new.  This option is not the most recommended one, unless you see no
         reason to change the current file.  You can get help at any time by
         typing <option>?</option> at the mergemaster prompt.  If the user should
         choose to skip a file, it will be presented again after all other files
         have been worked with.</para>
 
       <para>Choosing to install the unmodified temporary file will replace the
         current file with the new one.  For most unmodified files, this is the best
         option.</para>
 
       <para>Choosing to merge the file will present you with a text editor,
         and the contents of both files.  You can now merge them by
         reviewing both files side by side on the screen, and choosing parts from
         both to create a finished product.  When the files are compared side by side,
         the <option>l</option> key will select the left contents and the
         <option>r</option> key will select contents from your right.
         The final output will be a file consisting of both parts, which can then be
         installed.  This option is customarily used for files where settings have been
         modified by the user.</para>
 
       <para>Choosing to view the diff results again, will show you the file differences
         just like &man.mergemaster.8; did before prompting you for an option.</para>
 
       <para>After &man.mergemaster.8; is complete with the system files you will be
         prompted for other options.  &man.mergemaster.8; will ask if you want to rebuild
         the password file, run <filename>MAKEDEV</filename> and finishing up with a
         removal of the left over temporary files.</para>
 
       <para>If you wish to do the update manually, however,
         you cannot just copy over the files from
 	<filename>/usr/src/etc</filename> to <filename>/etc</filename> and
 	have it work.  Some of these files must be <quote>installed</quote>
 	first.  This is because the <filename>/usr/src/etc</filename>
 	directory <emphasis>is not</emphasis> a copy of what your
 	<filename>/etc</filename> directory should look like.  In addition,
 	there  are files that should be in <filename>/etc</filename> that are
 	not in <filename>/usr/src/etc</filename>.</para>
 
       <para>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
         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 accidentally deleted
         <filename>/etc/magic</filename> as part of the upgrade or merge of
         <filename>/etc</filename>, the &man.file.1; command will stop working.
         In this case, the fix would be to run:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
 &prompt.root; <userinput/make all install/</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
 		  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/introduction/chapter.sgml b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
index 016129ce9b..571aab2861 100644
--- a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
@@ -1,905 +1,905 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="introduction">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured, reorganized, and parts
 	  rewritten by </contrib>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Introduction</title>
 
   <sect1>
     <title>Synopsis</title>
 
     <para>Thank you for your interest in FreeBSD!  The following chapter
       covers various items about the FreeBSD Project, such as its history,
       goals, development model, and so on.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How FreeBSD relates to other computer operating systems.</para>
       </listitem>
       <listitem>
 	<para>The history of the FreeBSD Project.</para>
       </listitem>
       <listitem>
 	<para>The goals of the FreeBSD Project.</para>
       </listitem>
       <listitem>
 	<para>The basics of the FreeBSD open-source development model.</para>
       </listitem>
       <listitem>
 	<para>And of course: where the name "FreeBSD" comes from.</para>
       </listitem>
     </itemizedlist>
 
   </sect1>
 
   <sect1 id="nutshell">
     <title>Welcome to FreeBSD!</title>
     <indexterm><primary>4.4BSD-Lite</primary></indexterm> 
 
     <para>FreeBSD is a 4.4BSD-Lite based operating system for the Intel
       architecture (x86) and DEC Alpha based systems.  Ports to other
       architectures are also underway.  For a brief overview of FreeBSD,
       see the <link linkend="nutshell">next section</link>.  You can also
       read about <link linkend="history">the history of FreeBSD</link>,
       or the <link linkend="relnotes">current release</link>.  If you
       are interested in contributing something to the Project (code,
       hardware, unmarked bills), see the <ulink
 	url="../../articles/contributing/index.html">Contributing to FreeBSD</ulink> article.</para>
 
     <sect2>
       <title>What Can FreeBSD Do?</title>
 
       <para>FreeBSD has many noteworthy features.  Some of these
         are:</para>
 
       <itemizedlist>
         <indexterm><primary>preemptive multitasking</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Preemptive multitasking</emphasis> with
 	    dynamic priority adjustment to ensure smooth and fair
 	    sharing of the computer between applications and users, even
 	    under the heaviest of loads.</para>
 	</listitem>
 
 	<indexterm><primary>multi-user facilities</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Multi-user facilities</emphasis> which allow many
 	    people to use a FreeBSD system simultaneously for a variety
 	    of things.  This means, for example, that system peripherals
 	    such as printers and tape drives are properly shared between
 	    all users on the system or the network and that individual
 	    resource limits can be placed on users or groups of users,
 	    protecting critical system resources from over-use.</para>
 	</listitem>
       
 	<indexterm><primary>TCP/IP networking</primary></indexterm>
 	<listitem>
 	  <para>Strong <emphasis>TCP/IP networking</emphasis> with
 	    support for industry standards such as SLIP, PPP, NFS, DHCP,
 	    and NIS.  This means that your FreeBSD machine can
 	    interoperate easily with other systems as well as act as an
 	    enterprise server, providing vital functions such as NFS
 	    (remote file access) and email services or putting your
 	    organization on the Internet with WWW, FTP, routing and
 	    firewall (security) services.</para>
 	</listitem>
 
 	<indexterm><primary>memory protection</primary></indexterm>      
 	<listitem>
 	  <para><emphasis>Memory protection</emphasis> ensures that
 	    applications (or users) cannot interfere with each other. One
 	    application crashing will not affect others in any way.</para>
 	</listitem>
       
 	<listitem>
 	  <para>FreeBSD is a <emphasis>32-bit</emphasis> operating
 	    system (<emphasis>64-bit</emphasis> on the Alpha) and was
 	    designed as such from the ground up.</para>
 	</listitem>
 
 	<indexterm>
     <primary>X Window System</primary>
     <seealso>XFree86</seealso>
   </indexterm>
 
 	<listitem>
 	  <para>The industry standard <emphasis>X Window System</emphasis>
 	    (X11R6) provides a graphical user interface (GUI) for the cost
 	    of a common VGA card and monitor and comes with full
 	    sources.</para>
 	</listitem>
 
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>Linux</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>SCO</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>SVR4</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>BSD/OS</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>NetBSD</secondary>
 	</indexterm>
 	<listitem>
 	  <para><emphasis>Binary compatibility</emphasis> with many
 	    programs built for Linux, SCO, SVR4, BSDI and NetBSD.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>Thousands of <emphasis>ready-to-run</emphasis>
 	    applications are available from the FreeBSD
 	    <emphasis>ports</emphasis> and <emphasis>packages</emphasis>
 	    collection.  Why search the net when you can find it all right
 	    here?</para>
 	</listitem>
       
 	<listitem>
 	  <para>Thousands of additional and
 	    <emphasis>easy-to-port</emphasis> applications are available
 	    on the Internet.  FreeBSD is source code compatible with most
 	    popular commercial Unix systems and thus most applications
 	    require few, if any, changes to compile.</para>
 	</listitem>
       
 	<indexterm><primary>virtual memory</primary></indexterm>
 	<listitem>
 	  <para>Demand paged <emphasis>virtual memory</emphasis> and
 	    <quote>merged VM/buffer cache</quote> design efficiently
 	    satisfies applications with large appetites for memory while
 	    still maintaining interactive response to other users.</para>
 	</listitem>
       
         <indexterm>
 	  <primary>Symetric Multi-Processing (SMP)</primary>
 	</indexterm>
 	<listitem>
 	  <para><emphasis>SMP</emphasis> support for machines with
 	    multiple CPUs.</para>
 	</listitem>
 
 	<indexterm>
 	  <primary>compilers</primary>
 	  <secondary>C</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>compilers</primary>
 	  <secondary>C++</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>compilers</primary>
 	  <secondary>Fortran</secondary>
 	</indexterm>
 	<listitem>
 	  <para>A full complement of <emphasis>C</emphasis>,
 	    <emphasis>C++</emphasis>, <emphasis>Fortran</emphasis>, and
 	    <emphasis>Perl</emphasis> development tools.
 	    Many additional languages for advanced research
 	    and development are also available in the ports and packages
 	    collection.</para>
 	</listitem>
 
 	<indexterm><primary>source code</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Source code</emphasis> for the entire system
 	    means you have the greatest degree of control over your
 	    environment.  Why be locked into a proprietary solution
 	    at the mercy of your vendor when you can have a truly open
 	    system?</para>
 	</listitem>
       
 	<listitem>
 	  <para>Extensive <emphasis>online
 	    documentation</emphasis>.</para>
 	</listitem>
       
 	<listitem>
 	  <para><emphasis>And many more!</emphasis></para>
 	</listitem>
       </itemizedlist>
     
       <indexterm><primary>4.4BSD-Lite</primary></indexterm>
       <indexterm>
         <primary>Computer Systems Resarch Group (CSRG)</primary>
       </indexterm>
       <indexterm><primary>U.C. Berkeley</primary></indexterm>
       <para>FreeBSD is based on the 4.4BSD-Lite release from Computer
         Systems Research Group (CSRG) at the University of California at
 	Berkeley, and carries on the distinguished tradition of BSD
 	systems development.  In addition to the fine work provided by
 	CSRG, the FreeBSD Project has put in many thousands of hours in
 	fine tuning the system for maximum performance and reliability in
 	real-life load situations.  As many of the commercial giants
 	struggle to field PC operating systems with such features,
 	performance and reliability, FreeBSD can offer them
 	<emphasis>now</emphasis>!</para>
 
       <para>The applications to which FreeBSD can be put are truly
         limited only by your own imagination.  From software development
 	to factory automation, inventory control to azimuth correction of
 	remote satellite antennae; if it can be done with a commercial
 	Unix product then it is more than likely that you can do it with
 	FreeBSD too!  FreeBSD also benefits significantly from the
 	literally thousands of high quality applications developed by
 	research centers and universities around the world, often
 	available at little to no cost. Commercial applications are also
 	available and appearing in greater numbers every day.</para>
 
       <para>Because the source code for FreeBSD itself is generally
         available, the system can also be customized to an almost unheard
 	of degree for special applications or projects, and in ways not
 	generally possible with operating systems from most major
 	commercial vendors.  Here is just a sampling of some of the
 	applications in which people are currently using FreeBSD:</para>
     
       <itemizedlist>
 	<listitem>
 	  <para><emphasis>Internet Services:</emphasis> The robust TCP/IP
 	    networking built into FreeBSD makes it an ideal platform for a
 	    variety of Internet services such as:</para>
 
 	  <itemizedlist>
 	    <indexterm><primary>FTP servers</primary></indexterm>
 	    <listitem>
 	      <para>FTP servers</para>
 	    </listitem>
 	  
 	    <indexterm><primary>web servers</primary></indexterm>
 	    <listitem>
 	      <para>World Wide Web servers (standard or secure
 	        [SSL])</para>
 	    </listitem>
 
 	    <indexterm><primary>firewall</primary></indexterm>
 	    <indexterm><primary>IP masquerading</primary></indexterm>
 	    <listitem>
 	      <para>Firewalls and NAT (<quote>IP masquerading</quote>)
 	        gateways</para>
 	    </listitem>
 	  
 	    <indexterm><primary>electronic mail</primary></indexterm>
 	    <listitem>
 	      <para>Electronic Mail servers</para>
 	    </listitem>
 	  
 	    <indexterm><primary>USENET</primary></indexterm>
 	    <listitem>
 	      <para>USENET News or Bulletin Board Systems</para>
 	    </listitem>
 	  
 	    <listitem>
 	      <para>And more...</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>With FreeBSD, you can easily start out small with an
 	    inexpensive 386 class PC and upgrade all the way up to a
 	    quad-processor Xeon with RAID storage as your enterprise
 	    grows.</para>
 	</listitem>
       
 	<listitem>
 	  <para><emphasis>Education:</emphasis>  Are you a student of
 	    computer science or a related engineering field?  There is no
 	    better way of learning about operating systems, computer
 	    architecture and networking than the hands on, under the hood
 	    experience that FreeBSD can provide.  A number of freely
 	    available CAD, mathematical and graphic design packages also
 	    make it highly useful to those whose primary interest in a
 	    computer is to get <emphasis>other</emphasis> work
 	    done!</para>
 	</listitem>
       
 	<listitem>
 	  <para><emphasis>Research:</emphasis>  With source code for the
 	    entire system available, FreeBSD is an excellent platform for
 	    research in operating systems as well as other branches of
 	    computer science.  FreeBSD's freely available nature also makes
 	    it possible for remote groups to collaborate on ideas or
 	    shared development without having to worry about special
 	    licensing agreements or limitations on what may be discussed
 	    in open forums.</para>
 	</listitem>
       
 	<indexterm><primary>router</primary></indexterm>
 	<indexterm><primary>DNS Server</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Networking:</emphasis>  Need a new router?  A
 	    name server (DNS)? A firewall to keep people out of your
 	    internal network?  FreeBSD can easily turn that unused 386 or
 	    486 PC sitting in the corner into an advanced router with
 	    sophisticated packet-filtering capabilities.</para>
 	</listitem>
       
 	<indexterm>
 	  <primary>X Window System</primary>
 	  <secondary>XFree86</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>X Window System</primary>
 	  <secondary>Accellerated-X</secondary>
 	</indexterm>
 	<listitem>
 	  <para><emphasis>X Window workstation:</emphasis> FreeBSD is a
 	    fine choice for an inexpensive X terminal solution, either
 	    using the freely available XFree86 server or one of the
 	    excellent commercial servers provided by X Inside.  Unlike an
 	    X terminal, FreeBSD allows many applications to be run
 	    locally, if desired, thus relieving the burden on a central
 	    server.  FreeBSD can even boot <quote>diskless</quote>, making
 	    individual workstations even cheaper and easier to
 	    administer.</para>
 	</listitem>
       
 	<indexterm><primary>GNU Compiler Collection</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Software Development:</emphasis>  The basic
 	    FreeBSD system comes with a full complement of development
 	    tools including the renowned GNU C/C++ compiler and
 	    debugger.</para>
 	</listitem>
       </itemizedlist>
     
       <para>FreeBSD is available in both source and binary form on CDROM
         and via anonymous FTP.  Please see <xref linkend="mirrors">
         for more information about obtaining FreeBSD.</para>
     </sect2>
 
     <sect2>
       <title>Who uses FreeBSD?</title>
 
       <indexterm>
 	<primary>Users</primary>
 	<secondary>Large sites running FreeBSD</secondary>
       </indexterm>
 
       <para>FreeBSD is used to power some of the biggest sites on the
         Internet, including:</para>
 
       <itemizedlist>
         <indexterm><primary>Yahoo!</primary></indexterm>
         <listitem>
 	  <para><ulink url="http://www.yahoo.com/">Yahoo!</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Apache</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.apache.org/">Apache</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Be, Inc.</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.be.com/">Be, Inc.</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Blue Mountain Arts</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.bluemountain.com/">Blue Mountain
 	    Arts</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Pair Networks</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.pair.com/">Pair
 	    Networks</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Whistle Communications</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.whistle.com/">Whistle
 	    Communications</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Microsoft</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.microsoft.com/">Microsoft</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Hotmail</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.hotmail.com/">Hotmail</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Sony Japan</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.sony.co.jp/">Sony
 	    Japan</ulink></para>
 	</listitem>
       </itemizedlist>
 
       <para>and many more.</para>
     </sect2>
 
   </sect1>
   
   <sect1 id="history">
     <title>About the FreeBSD Project</title>
 
     <para>The following section provides some background information on
       the project, including a brief history, project goals, and the
       development model of the project.</para>
 
     <sect2 id="intro-history">
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Jordan</firstname>
 	    <surname>Hubbard</surname>
 	    <contrib>Contributed by </contrib>
 	  </author>
 	</authorgroup>
       </sect2info>
 
       <title>A Brief History of FreeBSD</title>
 
       <indexterm><primary>386BSD Patchkit</primary></indexterm>
       <indexterm><primary>Hubbard, Jordan</primary></indexterm>
       <indexterm><primary>Williams, Nate</primary></indexterm>
       <indexterm><primary>Grimes, Rod</primary></indexterm>
       <indexterm>
         <primary>FreeBSD Project</primary>
         <secondary>History</secondary>
       </indexterm>
       <para>The FreeBSD project had its genesis in the early part of 1993,
 	partially as an outgrowth of the <quote>Unofficial 386BSD
         Patchkit</quote> by the patchkit's last 3 coordinators: Nate
 	Williams, Rod Grimes and myself.</para>
     
       <indexterm><primary>386BSD</primary></indexterm>
       <para>Our original goal was to produce an intermediate snapshot of
 	386BSD in order to fix a number of problems with it that the
 	patchkit mechanism just was not capable of solving.  Some of you
 	may remember the early working title for the project being
 	<quote>386BSD 0.5</quote> or <quote>386BSD Interim</quote> in
 	reference to that fact.</para>
     
       <indexterm><primary>Jolitz, Bill</primary></indexterm>
       <para>386BSD was Bill Jolitz's operating system, which had been up
 	to that point suffering rather severely from almost a year's worth
 	of neglect.  As the patchkit swelled ever more uncomfortably with
 	each passing day, we were in unanimous agreement that something
-	had to be done and decided to try and assist Bill by providing
+	had to be done and decided to assist Bill by providing
 	this interim <quote>cleanup</quote> snapshot.  Those plans came to
 	a rude halt when Bill Jolitz suddenly decided to withdraw his
 	sanction from the project without any clear indication of what
 	would be done instead.</para>
 
       <indexterm><primary>Greenman, David</primary></indexterm>
       <indexterm><primary>Walnut Creek CDROM</primary></indexterm>
       <para>It did not take us long to decide that the goal remained
 	worthwhile, even without Bill's support, and so we adopted the
 	name <quote>FreeBSD</quote>, coined by David Greenman.  Our initial
 	objectives were set after consulting with the system's current
 	users and, once it became clear that the project was on the road
 	to perhaps even becoming a reality, I contacted Walnut Creek CDROM
 	with an eye towards improving FreeBSD's distribution channels for
 	those many unfortunates without easy access to the Internet.
 	Walnut Creek CDROM not only supported the idea of distributing
 	FreeBSD on CD but also went so far as to provide the project with a
 	machine to work on and a fast Internet connection.  Without Walnut
 	Creek CDROM's almost unprecedented degree of faith in what was, at
 	the time, a completely unknown project, it is quite unlikely that
         FreeBSD would have gotten as far, as fast, as it has today.</para>
 
       <indexterm><primary>4.3BSD-Lite</primary></indexterm>
       <indexterm><primary>Net/2</primary></indexterm>
       <indexterm><primary>U.C. Berkeley</primary></indexterm>
       <indexterm><primary>386BSD</primary></indexterm>
       <indexterm><primary>Free Software Foundation</primary></indexterm>
       <para>The first CDROM (and general net-wide) distribution was
 	FreeBSD 1.0, released in December of 1993.  This was based on the
 	4.3BSD-Lite (<quote>Net/2</quote>) tape from U.C. Berkeley, with
 	many components also provided by 386BSD and the Free Software
 	Foundation.  It was a fairly reasonable success for a first
 	offering, and we followed it with the highly successful FreeBSD
 	1.1 release in May of 1994.</para>
 
       <indexterm><primary>Novell</primary></indexterm>
       <indexterm><primary>U.C. Berkeley</primary></indexterm>
       <indexterm><primary>Net/2</primary></indexterm>
       <indexterm><primary>AT&amp;amp;T</primary></indexterm>
       <para>Around this time, some rather unexpected storm clouds formed
 	on the horizon as Novell and U.C. Berkeley settled their
 	long-running lawsuit over the legal status of the Berkeley Net/2
 	tape.  A condition of that settlement was U.C. Berkeley's
 	concession that large parts of Net/2 were <quote>encumbered</quote>
 	code and the property of Novell, who had in turn acquired it from
 	AT&amp;T some time previously.  What Berkeley got in return was
 	Novell's <quote>blessing</quote> that the 4.4BSD-Lite release, when
 	it was finally released, would be declared unencumbered and all
 	existing Net/2 users would be strongly encouraged to switch.  This
 	included FreeBSD, and the project was given until the end of July
 	1994 to stop shipping its own Net/2 based product.  Under the
 	terms of that agreement, the project was allowed one last release
 	before the deadline, that release being FreeBSD 1.1.5.1.</para>
 
       <para>FreeBSD then set about the arduous task of literally
 	re-inventing itself from a completely new and rather incomplete
 	set of 4.4BSD-Lite bits.  The <quote>Lite</quote> releases were
 	light in part because Berkeley's CSRG had removed large chunks of
 	code required for actually constructing a bootable running system
 	(due to various legal requirements) and the fact that the Intel
 	port of 4.4 was highly incomplete.  It took the project until
 	November of 1994 to make this transition, at which point it
 	released FreeBSD 2.0 to the net and on CDROM (in late December).
 	Despite being still more than a little rough around the edges,
 	the release was a significant success and was followed by the
 	more robust and easier to install FreeBSD 2.0.5 release in June of
 	1995.</para>
 
       <para>We released FreeBSD 2.1.5 in August of 1996, and it appeared
 	to be popular enough among the ISP and commercial communities that
 	another release along the 2.1-STABLE branch was merited.  This was
 	FreeBSD 2.1.7.1, released in February 1997 and capping the end of
 	mainstream development on 2.1-STABLE.  Now in maintenance mode,
 	only security enhancements and other critical bug fixes will be
 	done on this branch (RELENG_2_1_0).</para>
 
       <para>FreeBSD 2.2 was branched from the development mainline
 	(<quote>-CURRENT</quote>) in November 1996 as the RELENG_2_2
 	branch, and the first full release (2.2.1) was released in April
 	1997.  Further releases along the 2.2 branch were done in the
 	summer and fall of '97, the last of which (2.2.8) appeared in
 	November 1998. The first official 3.0 release appeared in
 	October 1998 and spelled the beginning of the end for the 2.2
 	branch.</para>
 
       <para>The tree branched again on Jan 20, 1999, leading to the
 	4.0-CURRENT and 3.X-STABLE branches.  From 3.X-STABLE, 3.1 was
 	released on February 15, 1999, 3.2 on May 15, 1999, 3.3 on
 	September 16, 1999, 3.4 on December 20, 1999, and 3.5 on
 	June 24, 2000, which was followed a few days later by a minor
 	point release update to 3.5.1, to incorporate some last-minute
 	security fixes to Kerberos. This will be the final release in the
 	3.X branch.</para>
 
       <para>There was another branch on March 13, 2000, which saw the
 	emergence of the 4.X-STABLE branch, now considered to be the
 	"current -stable branch".  There have been several releases
 	from it so far: 4.0-RELEASE came out in March 2000, 4.1 was
 	released in July 2000, 4.2 in November 2000, 4.3 in April
 	2001, and 4.4 in September 2001.  There will be more releases
 	along the 4.X-stable (RELENG_4) branch well into 2002.</para>
 
       <para>Long-term development projects continue to take place in the
 	5.0-CURRENT (trunk) branch, and SNAPshot releases of 5.0 on
 	CDROM (and, of course, on the net) are continually made available
 	from <ulink url="ftp://current.FreeBSD.org/pub/FreeBSD/snapshots/">
 	the snapshot server</ulink> as work progresses.</para>
     </sect2>
       
     <sect2 id="goals">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Jordan</firstname>
 	    <surname>Hubbard</surname>
    	    <contrib>Contributed by </contrib>
 	  </author>
         </authorgroup>
       </sect2info>
 
       <title>FreeBSD Project Goals</title>
     
       <indexterm>
         <primary>FreeBSD Project</primary>
         <secondary>Goals</secondary>
       </indexterm>
       <para>The goals of the FreeBSD Project are 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, I believe, one of the most fundamental
 	goals of Free Software and one that we enthusiastically
 	support.</para>
 
       <indexterm>
         <primary>GNU General Public License (GPL)</primary>
       </indexterm>
       <indexterm>
         <primary>GNU Lesser General Public License (LGPL)</primary>
       </indexterm>
       <indexterm><primary>BSD Copyright</primary></indexterm>
       <para>That code in our source tree which falls under the GNU
         General Public License (GPL) or Library General Public License
         (LGPL) 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, prefer
         software submitted under the more relaxed BSD copyright when
         it is a reasonable option to do so.</para>
     </sect2>
   
     <sect2 id="development">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Satoshi</firstname>
 	    <surname>Asami</surname>
    	    <contrib>Contributed by </contrib>
 	  </author>
         </authorgroup>
       </sect2info>
 
       <title>The FreeBSD Development Model</title>
     
       <indexterm>
         <primary>FreeBSD Project</primary>
         <secondary>Development Model</secondary>
       </indexterm>
       <para>The development of FreeBSD is a very open and flexible
 	process, FreeBSD being literally built from the contributions
 	of hundreds of people around the world, as can be seen from
 	our our <ulink
 	url="../../articles/contributors/article.html">list of
 	contributors</ulink>.  We are constantly on the lookout for
 	new developers and ideas, and those interested in becoming
 	more closely involved with the project need simply contact us
 	at the &a.hackers;.  The &a.announce; is also available to
 	those wishing to make other FreeBSD users aware of major areas
 	of work.</para>
 
       <para>Useful things to know about the FreeBSD project and its
 	development process, whether working independently or in close
 	cooperation:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term>The CVS repository<anchor
 	    id="development-cvs-repository"></term>
 
 	  <indexterm>
       <primary>CVS</primary>
       <secondary>repository</secondary>
     </indexterm>
 	  <indexterm>
 	    <primary>Concurrent Versions System</primary>
       <see>CVS</see>
 	  </indexterm>
 	  <listitem>
 	    <para>The central source tree for FreeBSD is maintained by
 	      <ulink url="http://www.cvshome.org/">CVS</ulink>
 	      (Concurrent Versions System), a freely available source code
 	      control tool that comes bundled with FreeBSD.  The primary
 	      <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVS
 	      repository</ulink> resides on a machine in Santa Clara CA, USA
 	      from where it is replicated to numerous mirror machines
 	      throughout the world.  The CVS tree, as well as the <link
 	      linkend="current">-CURRENT</link> and <link
 	      linkend="stable">-STABLE</link> trees which are checked out
 	      of it, can be easily replicated to your own machine as well.
 	      Please refer to the <link linkend="synching">Synchronizing
 	      your source tree</link> section for more information on
 	      doing this.</para>
 	  </listitem>
 	</varlistentry>
       
 	<varlistentry>
 	  <term>The committers list<anchor
 	    id="development-committers"></term>
 	      
 	  <indexterm><primary>committers</primary></indexterm>
 	  <listitem>
 	    <para>The <firstterm>committers</firstterm>
 	      are the people who have <emphasis>write</emphasis> access to
 	      the CVS tree, and are thus authorized to make modifications
 	      to the FreeBSD source (the term <quote>committer</quote>
 	      comes from the &man.cvs.1; <command>commit</command>
 	      command, which is used to bring new changes into the CVS
 	      repository).  The best way of making submissions for review
 	      by the committers list is to use the &man.send-pr.1;
 	      command, though if something appears to be jammed in the
 	      system then you may also reach them by sending mail to
 	      the &a.committers;.</para>
 	  </listitem>
 	</varlistentry>
       
 	<varlistentry>
 	  <term>The FreeBSD core team<anchor id="development-core"></term>
 
 	  <indexterm><primary>core team</primary></indexterm>
 	  <listitem>
 	    <para>The <firstterm>FreeBSD core team</firstterm>
 	      would be equivalent to the board of directors if the FreeBSD
 	      Project were a company.  The primary task of the core team
 	      is to make sure the project, as a whole, is in good shape
 	      and is heading in the right directions.  Inviting dedicated
 	      and responsible developers to join our group of committers
 	      is one of the functions of the core team, as is the
 	      recruitment of new core team members as others move on.
 	      The current core team was elected from a pool of committer
 	      candidates in October 2000.  Elections are held every 2 years.
 	      </para>
 
 	    <para>Some core team members also have specific areas of
 	      responsibility, meaning that they are committed to
 	      ensuring that some large portion of the system works as
 	      advertised.  For a complete list of FreeBSD developers
 	      and their areas of responsibility, please see the <ulink
 	      url="../../articles/contributors/article.html">Contributors
 	      List</ulink></para>
 
 	    <note>
 	      <para>Most members of the core team are volunteers when it
 	        comes to FreeBSD development and do not benefit from the
 		project financially, so <quote>commitment</quote> should
 		also not be misconstrued as meaning <quote>guaranteed
 		support.</quote>  The <quote>board of directors</quote>
 		analogy above is not actually very accurate, and it may be
 		more suitable to say that these are the people who gave up
 		their lives in favor of FreeBSD against their better
 		judgment!</para>
 	    </note>
 	  </listitem>
 	</varlistentry>
       
 	<varlistentry>
 	  <term>Outside contributors</term>
 
 	  <indexterm><primary>contributors</primary></indexterm>
 	  <listitem>
 	    <para>Last, but definitely not least, the largest group of
 	      developers are the users themselves who provide feedback and
 	      bug fixes to us on an almost constant basis.  The primary
 	      way of keeping in touch with FreeBSD's more non-centralized
 	      development is to subscribe to the &a.hackers; (see <link
 	      linkend="eresources-mail">mailing list info</link>) where
 	      such things are discussed.</para>
 	  
 	    <para><citetitle><ulink
 	      url="../../articles/contributors/article.html">The
 	      FreeBSD Contributors List</ulink></citetitle> is a long
 	      and growing one, so why not join it by contributing
 	      something back to FreeBSD today?</para>
 
 	    <para>Providing code is not the only way of contributing to
 	      the project; for a more complete list of things that need
 	      doing, please refer to the <ulink
 	      url="../../../../index.html">FreeBSD Project web
 	      site</ulink>.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     
       <para>In summary, our development model is organized as a loose set
         of concentric circles.  The centralized model is designed for the
         convenience of the <emphasis>users</emphasis> of FreeBSD, who are
         thereby provided with an easy way of tracking one central code
 	base, not to keep potential contributors out! Our desire is to
 	present a stable operating system with a large set of coherent
 	<link linkend="ports">application programs</link> that the users
 	can easily install and use, and this model works very well in
 	accomplishing that.</para>
     
       <para>All we ask of those who would join us as FreeBSD developers is
         some of the same dedication its current people have to its
 	continued success!</para>
     </sect2>
 
     <sect2 id="relnotes">
       <title>The Current FreeBSD Release</title>
 
       <indexterm><primary>NetBSD</primary></indexterm>
       <indexterm><primary>OpenBSD</primary></indexterm>
       <indexterm><primary>386BSD</primary></indexterm>
       <indexterm><primary>Free Software Foundation</primary></indexterm>
       <indexterm><primary>U.C. Berkeley</primary></indexterm>
       <indexterm>
         <primary>Computer Systems Resarch Group (CSRG)</primary>
       </indexterm>
       <para>FreeBSD is a freely available, full source 4.4BSD-Lite based
         release for Intel i386, i486, Pentium, Pentium Pro, Celeron,
         Pentium II, Pentium III (or compatible) and DEC Alpha based computer
         systems.  It is based primarily on software from U.C. Berkeley's
         CSRG group, with some enhancements from NetBSD, OpenBSD, 386BSD, and
         the Free Software Foundation.</para>
 
       <para>Since our release of FreeBSD 2.0 in late 94, the performance,
         feature set, and stability of FreeBSD has improved dramatically.
         The largest change is a revamped virtual memory system with a merged
         VM/file buffer cache that not only increases performance, but also
         reduces FreeBSD's memory footprint, making a 5MB configuration a
         more acceptable minimum.  Other enhancements include full NIS client
         and server support, transaction TCP support, dial-on-demand PPP,
         integrated DHCP support, an improved SCSI subsystem, ISDN support,
         support for ATM, FDDI, Fast and Gigabit Ethernet (1000Mbit)
         adapters, improved support for the latest Adaptec controllers, and
         many hundreds of bug fixes.</para>
 
       <para>We have also taken the comments and suggestions of many of our
         users to heart and have attempted to provide what we hope is a more
         sane and easily understood installation process.  Your feedback on
         this (constantly evolving) process is especially welcome!</para>
 
       <para>In addition to the base distributions, FreeBSD offers a
         ported software collection with thousands of commonly
         sought-after programs.  At the time of this printing, there
         were over &os.numports; ports!  The list of ports ranges from
         http (WWW) servers, to games, languages, editors, and almost
         everything in between.  The entire ports collection requires
         approximately 100MB of storage, all ports being expressed as
         <quote>deltas</quote> to their original sources.  This makes
         it much easier for us to update ports, and greatly reduces the
         disk space demands made by the older 1.0 ports collection.  To
         compile a port, you simply change to the directory of the
         program you wish to install, type <command>make
         install</command>, and let the system do the rest.  The full
         original distribution for each port you build is retrieved
         dynamically off the CDROM or a local FTP site, so you need
         only enough disk space to build the ports you want.  Almost
         every port is also provided as a pre-compiled
         <quote>package</quote>, which can be installed with a simple
         command (<command>pkg_add</command>) by those who do not wish
         to compile their own ports from source.</para>
 
       <para>A number of additional documents which you may find very helpful
         in the process of installing and using FreeBSD may now also be found
         in the <filename>/usr/share/doc</filename> directory on any machine
         running FreeBSD 2.1 or later.  You may view the locally installed
         manuals with any HTML capable browser using the following
         URLs:</para>
 
       <variablelist>
         <varlistentry>
 	  <term>The FreeBSD Handbook</term>
 
 	  <listitem>
 	    <para><ulink
 	      url="file://localhost/usr/share/doc/handbook/index.html">/usr/share/doc/handbook/index.html</ulink></para>
 	  </listitem>
         </varlistentry>
       
         <varlistentry>
 	  <term>The FreeBSD FAQ</term>
 
 	  <listitem>
 	    <para><ulink
 	      url="file://localhost/usr/share/doc/faq/index.html">/usr/share/doc/faq/index.html</ulink></para>
 	  </listitem>
         </varlistentry>
       </variablelist>
     
       <para>You can also view the master (and most frequently updated)
         copies at <ulink
 	url="../../../../index.html">http://www.FreeBSD.org/</ulink>.</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/policies/chapter.sgml b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml
index cc06d59960..cbc67f6c8c 100644
--- a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml
@@ -1,437 +1,437 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="policies">
   <chapterinfo>
     <authorgroup>
       <firstname>Poul-Henning</firstname>
       <surname>Kamp</surname>
       <contrib>Contributed by </contrib>
     </authorgroup>
   </chapterinfo>
 
   <title>Source Tree Guidelines and Policies</title>
   
   <para>This chapter documents various guidelines and policies in force for
     the FreeBSD source tree.</para>
   
   <sect1 id="policies-maintainer">
     <title><makevar>MAINTAINER</makevar> on Makefiles</title>
     <indexterm><primary>ports maintainer</primary></indexterm>
     
     <para>June 1996.</para>
     
     <para>If a particular portion of the FreeBSD distribution is being
       maintained by a person or group of persons, they can communicate this
       fact to the world by adding a
 
       <programlisting>MAINTAINER= email-addresses</programlisting>
 
       line to the <filename>Makefile</filename>s covering this portion of the
       source tree.</para>
 
     <para>The semantics of this are as follows:</para>
     
     <para>The maintainer owns and is responsible for that code.  This means
       that he is responsible for fixing bugs and answer problem reports
       pertaining to that piece of the code, and in the case of contributed
       software, for tracking new versions, as appropriate.</para>
 
     <para>Changes to directories which have a maintainer defined shall be sent
       to the maintainer for review before being committed.  Only if the
       maintainer does not respond for an unacceptable period of time, to
       several emails, will it be acceptable to commit changes without review
-      by the maintainer.  However, it is suggested that you try and have the
+      by the maintainer.  However, it is suggested that you try to have the
       changes reviewed  by someone else if at all possible.</para>
 
     <para>It is of course not acceptable to add a person or group as
       maintainer unless they agree to assume this duty.  On the other hand it
       does not have to be a committer and it can easily be a group of
       people.</para>
   </sect1>
   
   <sect1 id="policies-contributed">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Poul-Henning</firstname>
 	  <surname>Kamp</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<author>
 	  <firstname>David</firstname>
 	  <surname>O'Brien</surname>
 	</author>
       </authorgroup>
       <!-- June 1996 -->
     </sect1info>
 
     <title>Contributed Software</title>
     
     <indexterm><primary>contributed software</primary></indexterm>
         
     <para>Some parts of the FreeBSD distribution consist of software that is
       actively being maintained outside the FreeBSD project.  For historical
       reasons, we call this <emphasis>contributed</emphasis> software.  Some
       examples are <command>perl</command>, <command>gcc</command> and 
       <command>patch</command>.</para>
 
     <para>Over the last couple of years, various methods have been used in
       dealing with this type of software and all have some number of
       advantages and drawbacks.  No clear winner has emerged.</para>
 
     <para>Since this is the case, after some debate one of these methods has
       been selected as the <quote>official</quote> method and will be required
       for future imports of software of this kind.  Furthermore, it is
       strongly suggested that existing contributed software converge on this
       model over time, as it has significant advantages over the old method,
       including the ability to easily obtain diffs relative to the
       <quote>official</quote> versions of the source by everyone (even without
       cvs access).  This will make it significantly easier to return changes
       to the primary developers of the contributed software.</para>
 
     <para>Ultimately, however, it comes down to the people actually doing the
       work.  If using this model is particularly unsuited to the package being
       dealt with, exceptions to these rules may be granted only with the
       approval of the core team and with the general consensus of the other
       developers.  The ability to maintain the package in the future will be a
       key issue in the decisions.</para>
 
     <note>
       <para>Because of some unfortunate design limitations with the RCS file
 	format and CVS's use of vendor branches, minor, trivial and/or
 	cosmetic changes are <emphasis>strongly discouraged</emphasis> on
 	files that are still tracking the vendor branch.  <quote>Spelling
 	fixes</quote> are explicitly included here under the
 	<quote>cosmetic</quote> category and are to be avoided for files with
 	revision 1.1.x.x.  The repository bloat impact from a single character
 	change can be rather dramatic.</para>
     </note>
     
     <para>The <application>Tcl</application> embedded programming
       language will be used as example of how this model works:</para>
 
     <para><filename>src/contrib/tcl</filename> contains the source as
       distributed by the maintainers of this package.  Parts that are entirely
       not applicable for FreeBSD can be removed.  In the case of Tcl, the
       <filename>mac</filename>, <filename>win</filename> and
       <filename>compat</filename> subdirectories were eliminated before the
       import</para>
 
     <para><filename>src/lib/libtcl</filename> contains only a "bmake style"
       <filename>Makefile</filename> that uses the standard
       <filename>bsd.lib.mk</filename> makefile rules to produce the library
       and install the documentation.</para>
 
     <para><filename>src/usr.bin/tclsh</filename> contains only a 
       <command>bmake</command> style
       <filename>Makefile</filename> which will produce and install the
       <command>tclsh</command> program and its associated man-pages using the
       standard <filename>bsd.prog.mk</filename> rules.</para>
 
     <para><filename>src/tools/tools/tcl_bmake</filename> contains a couple of
       shell-scripts that can be of help when the Tcl software needs updating.
       These are not part of the built or installed software.</para>
 
     <para>The important thing here is that the
       <filename>src/contrib/tcl</filename> directory is created according to
       the rules: It is supposed to contain the sources as distributed (on a
       proper CVS vendor-branch and without RCS keyword expansion) with as few
       FreeBSD-specific changes as possible.  The 'easy-import' tool on
       <hostid>freefall</hostid> will assist in doing the import, but if there
       are any doubts on
       how to go about it, it is imperative that you ask first and not blunder
       ahead and hope it <quote>works out</quote>.  CVS is not forgiving of
       import accidents and a fair amount of effort is required to back out
       major mistakes.</para>
     
     <para>Because of the previously mentioned design limitations with CVS's
       vendor branches, it is required that <quote>official</quote> patches from
       the vendor be applied to the original distributed sources and the result
       re-imported onto the vendor branch again.  Official patches should never
       be patched into the FreeBSD checked out version and "committed", as this
       destroys the vendor branch coherency and makes importing future versions
       rather difficult as there will be conflicts.</para>
 
     <para>Since many packages contain files that are meant for compatibility
       with other architectures and environments that FreeBSD, it is
       permissible to remove parts of the distribution tree that are of no
       interest to FreeBSD in order to save space.  Files containing copyright
       notices and release-note kind of information applicable to the remaining
       files shall <emphasis>not</emphasis> be removed.</para>
     
     <para>If it seems easier, the <command>bmake</command>
       <filename>Makefile</filename>s can be produced from the dist tree
       automatically by some utility, something which would hopefully make it
       even easier to upgrade to a new version.  If this is done, be sure to
       check in such utilities (as necessary) in the
       <filename>src/tools</filename> directory along with the port itself so
       that it is available to future maintainers.</para>
 
     <para>In the <filename>src/contrib/tcl</filename> level directory, a file
       called <filename>FREEBSD-upgrade</filename> should be added and it
       should states things like:</para>
     
     <itemizedlist>
       <listitem>
 	<para>Which files have been left out</para>
       </listitem>
       
       <listitem>
 	<para>Where the original distribution was obtained from and/or the
 	  official master site.</para>
       </listitem>
       
       <listitem>
 	<para>Where to send patches back to the original authors</para>
       </listitem>
       
       <listitem>
 	<para>Perhaps an overview of the FreeBSD-specific changes that have
 	  been made.</para>
       </listitem>
     </itemizedlist>
     
     <para>However, please do not import <filename>FREEBSD-upgrade</filename>
       with the contributed source. Rather you should <command>cvs add
 	FREEBSD-upgrade ; cvs ci</command> after the initial import.  Example
       wording from <filename>src/contrib/cpio</filename> is below:</para>
 
     <programlisting>This directory contains virgin sources of the original distribution files
 on a "vendor" branch.  Do not, under any circumstances, attempt to upgrade
 the files in this directory via patches and a cvs commit.  New versions or
 official-patch versions must be imported.  Please remember to import with
 "-ko" to prevent CVS from corrupting any vendor RCS Ids.
 
 For the import of GNU cpio 2.4.2, the following files were removed:
 
         INSTALL         cpio.info       mkdir.c             
         Makefile.in     cpio.texi       mkinstalldirs
 
 To upgrade to a newer version of cpio, when it is available:
         1. Unpack the new version into an empty directory.
            [Do not make ANY changes to the files.]
 
         2. Remove the files listed above and any others that don't apply to
            FreeBSD.
 
         3. Use the command:
                 cvs import -ko -m 'Virgin import of GNU cpio v&lt;version&gt;' \
                         src/contrib/cpio GNU cpio_&lt;version&gt;
 
            For example, to do the import of version 2.4.2, I typed:
                 cvs import -ko -m 'Virgin import of GNU v2.4.2' \
                         src/contrib/cpio GNU cpio_2_4_2
 
         4. Follow the instructions printed out in step 3 to resolve any
            conflicts between local FreeBSD changes and the newer version.
 
 Do not, under any circumstances, deviate from this procedure.
 
 To make local changes to cpio, simply patch and commit to the main
 branch (aka HEAD).  Never make local changes on the GNU branch.
 
 All local changes should be submitted to "cpio@gnu.ai.mit.edu" for
 inclusion in the next vendor release.
 
 obrien@FreeBSD.org - 30 March 1997</programlisting>
   </sect1>
 
   <sect1 id="policies-encumbered">
     <title>Encumbered Files</title>
 
     <para>It might occasionally be necessary to include an encumbered file in
       the FreeBSD source tree.  For example, if a device requires a small
       piece of binary code to be loaded to it before the device will operate,
       and we do not have the source to that code, then the binary file is said 
       to be encumbered.  The following policies apply to including encumbered
       files in the FreeBSD source tree.</para>
 
     <orderedlist>
       <listitem>
         <para>Any file which is interpreted or executed by the system CPU(s)
 	  and not in source format is encumbered.</para>
       </listitem>
 
       <listitem>
         <para>Any file with a license more restrictive than BSD or GNU is
 	  encumbered.</para>
       </listitem>
 
       <listitem>
         <para>A file which contains downloadable binary data for use by the
 	  hardware is not encumbered, unless (1) or (2) apply to it.  It must
 	  be stored in an architecture neutral ASCII format (file2c or
 	  uuencoding is recommended).</para>
       </listitem>
 
       <listitem>
         <para>Any encumbered file requires specific approval from the <link
 	    linkend="staff-core">Core team</link> before it is added to the
 	  CVS repository.</para>
       </listitem>
 
       <listitem>
         <para>Encumbered files go in <filename>src/contrib</filename> or
 	  <filename>src/sys/contrib</filename>.</para>
       </listitem>
 
       <listitem>
         <para>The entire module should be kept together.  There is no point in 
 	  splitting it, unless there is code-sharing with non-encumbered
 	  code.</para>
       </listitem>
 
       <listitem>
         <para>Object files are named
 	  <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para>
       </listitem>
 
       <listitem>
         <para>Kernel files:</para>
 
         <orderedlist>
           <listitem>
             <para>Should always be referenced in
               <filename>conf/files.*</filename> (for build simplicity).</para>
 	  </listitem>
 
           <listitem>
             <para>Should always be in <filename>LINT</filename>, but the <link 
               linkend="staff-core">Core team</link> decides per case if it
 	      should be commented out or not.  The <link
 	      linkend="staff-core">Core team</link> can, of course, change
 	      their minds later on.</para>
           </listitem>
 
           <listitem>
             <para>The <link linkend="staff-who">Release Engineer</link>
               decides whether or not it goes in to the release.</para>
           </listitem>
         </orderedlist>
       </listitem>
 
       <listitem>
         <para>User-land files:</para>
 
         <orderedlist>
           <listitem>
             <indexterm><primary>core team</primary></indexterm>
             <para>The <link linkend="staff-core">Core team</link> decides if
               the code should be part of <command>make world</command>.</para>
           </listitem>
          
           <listitem>
             <indexterm><primary>release engineer</primary></indexterm>
             <para>The <link linkend="staff-who">Release Engineer</link>
               decides if it goes in to the release.</para>
           </listitem>
         </orderedlist>
       </listitem>
     </orderedlist>
   </sect1>
   
   <sect1 id="policies-shlib">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Satoshi</firstname>
 	  <surname>Asami</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<author>
 	  <firstname>Peter</firstname>
 	  <surname>Wemm</surname>
 	</author>
 	<author>
 	  <firstname>David</firstname>
 	  <surname>O'Brien</surname>
 	</author>
       </authorgroup>
       <!-- 9 Dec 1996 -->
     </sect1info>
 
     <title>Shared Libraries</title>
 
     <para>If you are adding shared library support to a port or other piece of
       software that does not have one, the version numbers should follow these
       rules.  Generally, the resulting numbers will have nothing to do with
       the release version of the software.</para>
 
     <para>The three principles of shared library building are:</para>
     
     <itemizedlist>
       <listitem>
 	<para>Start from <literal>1.0</literal></para>
       </listitem>
       
       <listitem>
 	<para>If there is a change that is backwards compatible, bump minor
 	  number (note that ELF systems ignore the minor number)</para>
       </listitem>
       
       <listitem>
 	<para>If there is an incompatible change, bump major number</para>
       </listitem>
     </itemizedlist>
     
     <para>For instance, added functions and bugfixes result in the minor
       version number being bumped, while deleted functions, changed function
       call syntax etc.  will force the major version number to change.</para>
     
     <para>Stick to version numbers of the form major.minor
       (<replaceable>x</replaceable>.<replaceable>y</replaceable>).  Our a.out
       dynamic linker does not handle version numbers of the form
       <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
       well.  Any version number after the <replaceable>y</replaceable>
       (ie. the third digit) is totally ignored when comparing shared lib
       version numbers to decide which library to link with.  Given two shared
       libraries that differ only in the <quote>micro</quote> revision,
       <command>ld.so</command> will link with the higher one. Ie: if you link
       with <filename>libfoo.so.3.3.3</filename>, the linker only records
       <literal>3.3</literal> in the headers, and will link with anything
       starting with
       <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything &gt;=
 	3)</replaceable>.<replaceable>(highest
 	available)</replaceable>.</para>
     
     <note>
       <para><command>ld.so</command> will always use the highest
 	<quote>minor</quote> revision.  Ie: it will use
 	<filename>libc.so.2.2</filename> in preference to
 	<filename>libc.so.2.0</filename>, even if the program was initially
 	linked with <filename>libc.so.2.0</filename>.</para>
     </note>
 
     <para>In addition, our ELF dynamic linker does not handle minor version
     numbers at all.  However, one should still specify a major and minor
     version number as our <filename>Makefile</filename>s "do the right thing"
     based on the type of system.</para>
     
     <para>For non-port libraries, it is also our policy to change the shared
       library version number only once between releases.  In addition, it is
       our policy to change the major shared library version number only once
       between major OS releases.  Ie: X.0 to (X+1).0.  When you make a
       change to a system library that requires the version number to be
       bumped, check the <filename>Makefile</filename>'s commit logs. It is the
       responsibility of the committer to ensure that the first such change
       since the release will result in the shared library version number in
       the <filename>Makefile</filename> to be updated, and any subsequent
       changes will not.</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:
 -->