diff --git a/en_US.ISO8859-1/articles/formatting-media/article.sgml b/en_US.ISO8859-1/articles/formatting-media/article.sgml
index 6c546923f6..e9302ea61d 100644
--- a/en_US.ISO8859-1/articles/formatting-media/article.sgml
+++ b/en_US.ISO8859-1/articles/formatting-media/article.sgml
@@ -1,620 +1,620 @@
 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 ]>
-<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/formatting-media/article.sgml,v 1.17 2001/07/11 13:05:44 nik Exp $ -->
+<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/formatting-media/article.sgml,v 1.18 2001/07/11 13:07:38 nik Exp $ -->
 <article>
   <articleinfo>
     <title>Formatting Media For Use With FreeBSD</title>
 
     <subtitle>A Tutorial</subtitle>
 
     <authorgroup>
       <author>
 	<firstname>Doug</firstname>
 
 	<surname>White</surname>
 
 	<affiliation>
 	  <address>
 	    <email>dwhite@resnet.uoregon.edu</email>
 	  </address>
 	</affiliation>
       </author>
     </authorgroup>
 
     <pubdate>March 1997</pubdate>
 
     <abstract>
       <para>This document describes how to slice, partition, and
 	format hard disk drives and similar media for use with
 	FreeBSD.  The examples given have been tested under FreeBSD
 	2.2 and should work for other releases.  The text has been updated
 	for FreeBSD version 4.</para>
     </abstract>
   </articleinfo>
 
   <sect1>
     <title>Introduction & Definitions</title>
 
     <sect2>
       <title>Overview</title>
 
       <para>Successfully adding disks to an existing system is the
 	mark of an experienced system administrator.  Slicing,
 	partitioning, and adding disks requires a careful dance of
 	proper command and name syntax.  One slipped finger and an
 	entire disk could disappear in seconds.  This document is
 	written in an attempt to simplify this process and avoid
 	accidents.  Thankfully, enhancements to existing tools
 	(notably sysinstall) have greatly improved this process in
 	recent releases of FreeBSD.</para>
 
       <para>There are two possible modes of disk formatting:</para>
 
       <itemizedlist> 
 	<listitem>
 	  <para><firstterm>compatibility mode</firstterm>: Arranging a
 	    disk so that it has a slice table for use with other
 	    operating systems.</para>
 	</listitem>
 
 	<listitem>
 	  <para><firstterm>dedicated mode</firstterm>, sometimes called
 	    <firstterm>dangerously dedicated mode</firstterm>: Formatting a disk
 	    with no slice table.  This makes the process of adding disks easier,
 	    however non-FreeBSD operating systems may not accept the disk.  The
 	    term <emphasis>dangerously</emphasis> refers to the danger that the
 	    system may not recognize a disk formatted in this manner.</para>
 	    </listitem> </itemizedlist>
 
       <para>For most cases, dedicated mode is the easiest to set up
 	and use in existing systems, as a new disk is usually
 	dedicated entirely to FreeBSD.  However, compatibility mode
 	insures optimum interoperability with future installations at
 	a cost of increased complexity.</para>
 
       <para>In addition to selecting the mode, two methods of slicing
 	the disk are available.  One is using the system installation
 	tool <command>/stand/sysinstall</command>.  2.1.7-RELEASE and
 	later versions of <command>sysinstall</command> contain code
 	to ease setup of disks during normal system operation, mainly
 	allowing access to the Label and Partition editors and a Write
 	feature which will update just the selected disk and slice
 	without affecting other disks.  The other method is running
 	the tools manually from a root command line.  For 
 	dedicated mode, only three or four commands are involved while
 	<command>sysinstall</command> requires some
 	manipulation.</para>
     </sect2>
 
     <sect2>
       <title>Definitions</title>
 
-      <para>UNIX disk management over the centuries has invented many
+      <para>Unix disk management over the centuries has invented many
 	new definitions for old words.  The following glossary covers
 	the definitions used in this document and (hopefully) for
 	FreeBSD in general.</para>
 
 <!-- I'm tempted to use GLOSSARY here but will resort to a list for
 now. -->
 
       <itemizedlist>
 	<listitem>
 	  <para>compatibility mode:  Arranging a disk so that it has a
 	    slice table for use with other operating systems.  Oppose
 	    dedicated mode.</para>
 	</listitem>
 
 	<listitem>
 	  <para>(dangerously) dedicated mode:  Formatting a disk with no
 	    slice table.  This makes the process of adding disks
 	    easier, however non-FreeBSD operating systems may not
 	    accept the disk.  Oppose compatibility mode.</para>
 	</listitem>
 
 	<listitem>
 	  <para>disk:   A circular disc,  covered with magnetic or
 	    similarly manipulable material, spun by a motor under a
 	    head.  Data is stored on the disk by changing the pattern
 	    of magnetism on the disc, which can be later read.  Hard
-	    disks, CD-ROMs, Magneto-optical,and Zip/Jaz removables are
+	    disks, CDROMs, Magneto-optical,and Zip/Jaz removables are
 	    examples of disks.</para>
 	</listitem>
 
 	<listitem>
 	  <para>slice: A division of a disk.  Up to four slices are
 	    permitted on one disk in the PC standard.  Slices are
 	    composed of contiguous sectors.  Slices are recorded in a
 	    <quote>slice table</quote> used by the system BIOS to
 	    locate bootable partitions.  The slice table is usually
 	    called the <quote>partition table</quote> in DOS parlance.  Maintained by
 	    the fdisk utility.</para>
 	</listitem>
 
 	<listitem>
 	  <para>partition: A division of a slice.  Usually used in
 	    reference to divisions of the FreeBSD slice of a disk.
 	    Each filesystem and swap area on a disk resides in a
 	    partition.  Maintained using the disklabel utility.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>sector:  Smallest subdivision of a disk.  One sector
 	    usually represents 512 bytes of data.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Warnings & Pitfalls</title>
 
       <para>Building disks is not something to take lightly.  It is
 	quite possible to destroy the contents of other disks in your
 	system if the proper precautions are not taken.</para>
 
       <para><emphasis>Check your work carefully.</emphasis>  It is very simple
 	to destroy the incorrect disk when working with these
 	commands.  When in doubt consult the kernel boot output for
 	the proper device.</para>
 
       <para>Needless to say, we are not responsible for any damage to
 	any data or hardware that you may experience.  You work at
 	your own risk!</para>
     </sect2>
 
     <sect2>
       <title>Zip, Jaz, and Other Removables</title>
 
       <para>Removable disks can be formatted in the same way as normal
 	hard disks.  It is essential to have the disk drive connected
 	to the system and a disk placed in the drive during startup,
 	so the kernel can determine the drive's geometry.  Check the
 	<command>dmesg</command> output and make sure your device and
 	the disk's size is listed.  If the kernel reports 
 
 	<informalexample>
 	  <screen>Can't get the size</screen>
 	</informalexample>
 
 	then the disk was not in the drive.  In this case, you will
 	need to restart the machine before attempting to format
 	disks.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Formatting Disks in Dedicated Mode</title>
 
     <sect2>
       <title>Introduction</title>
 
       <para>This section details how to make disks that are totally
 	dedicated to FreeBSD.  Remember, dedicated mode disks sometimes
 	cannot be booted by the PC architecture.</para>
     </sect2>
 
     <sect2>
       <title>Making Dedicated Mode Disks using Sysinstall</title>
 
       <para><command>/stand/sysinstall</command>, the system
 	installation utility, has been expanded in recent versions to
 	make the process of dividing disks properly a less tiring
 	affair.  The fdisk and disklabel editors built into sysinstall
 	are GUI tools that remove much of the confusion from slicing
 	disks.  For FreeBSD versions 2.1.7 and later, this is perhaps
 	the simplest way to slice disks.</para>
 
       <procedure>
 	<step>
 	  <para>Start sysinstall as root by typing 
 
 	    <informalexample>
 	      <screen>&prompt.root; <userinput>/stand/sysinstall</userinput></screen>
 	    </informalexample> 
 
 	    from the command prompt.</para>
 	</step>
 
 	<step>
 	  <para>Select <command>Index</command>.</para>
 	</step>
 
 	<step>
 	  <para>Select <command>Partition</command>.</para>
 	</step>
 
 	<step>
 	  <para>Select the disk to edit with arrow keys and
 	    <keycap>SPACE</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>If you are using this entire disk for FreeBSD, select
 	    <command>A</command>.</para>
 	</step> 
 
 	<step>
 	  <para>When asked: 
 
 	    <informalexample>
 	      <screen>Do you want to do this with a true partition entry so as to remain
 cooperative with any future possible operating systems on the
 drive(s)?</screen>
 	    </informalexample>
 
 	    answer <command>No</command>.</para>
 	</step>
 
 	<step>
 	  <para>When asked if you still want to do this, answer
 	    <command>Yes</command>.</para>
 	</step> 
 
 	<step>
 	  <para>Select <command>Write</command>.</para>
 	</step>
 
 	<step>
 	  <para>When warned about writing on installed systems, answer
 	    <command>Yes</command>.</para>
 	</step> 
 
 	<step>
 	  <para><command>Quit</command>the FDISK Editor and
 	    <keycap>ESCAPE</keycap> back to the Index menu.</para>
 	</step>
 
 	<step>
 	  <para>Select <command>Label</command> from the Index
 	    menu.</para>
 	</step>
 
 	<step>
 	  <para>Label as desired.  For a single partition, enter
 	    <command>C</command> to Create a partition, accept the
 	    default size, partition type Filesystem, and a mountpoint
 	    (which isn't used).</para>
 	</step> 
 
 	<step>
 	  <para>Enter <command>W</command> when done and confirm to
 	    continue.  The filesystem will be newfs'd for you, unless
 	    you select otherwise (for new partitions you'll want to
 	    do this!).  You'll get the error: 
 
 	    <informalexample>
 	      <screen>Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory</screen>
 	    </informalexample>
 
 	    Ignore.</para>
 	</step>
 
 	<step>
 	  <para>Exit out by repeatedly pressing
 	    <keycap>ESCAPE</keycap>.</para>
 	</step>
       </procedure>
     </sect2>
 
     <sect2>
       <title>Making Dedicated Mode Disks Using the Command Line</title>
 
       <para>Execute the following commands, replacing <devicename>ad2</devicename> with the
 	disk name.</para>
 
       <informalexample>
 	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad2 count=2</userinput>
 &prompt.root; <userinput>disklabel /dev/ad2 | disklabel -B -R -r ad2 /dev/stdin</userinput>
 <lineannotation>We only want one partition, so using slice 'c' should be fine:</lineannotation>
 &prompt.root; <userinput>newfs /dev/ad2c</userinput></screen>
       </informalexample>
 
       <para>If you need to edit the disklabel to create multiple
 	partitions (such as swap), use the following: </para>
         
       <informalexample>
 	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad2 count=2</userinput>
 &prompt.root; <userinput>disklabel /dev/$d > /tmp/label</userinput>
 <lineannotation>Edit disklabel to add partitions:</lineannotation>
 &prompt.root; <userinput>vi /tmp/label</userinput>
 &prompt.root; <userinput>disklabel -B -R -r ad2 /tmp/label</userinput>
 <lineannotation>newfs partitions appropriately</lineannotation></screen>
       </informalexample>
 
       <para>Your disk is now ready for use.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Making Compatibility Mode Disks</title>
 
     <sect2>
       <title>Introduction</title>
 
       <para>The command line is the easiest way to make dedicated
 	disks, and the worst way to make compatibility disks.  The
 	command-line <command>fdisk</command> utility requires higher math skills and an
 	in-depth understanding of the slice table, which is more than
 	most people want to deal with.  Use sysinstall for
 	compatibility disks, as described below.</para>
     </sect2>
 
     <sect2>
       <title>Making Compatibility Mode Disks Using Sysinstall</title>
 
       <procedure>
 	<step>
 	  <para>Start sysinstall as root by typing 
 
 	    <informalexample>
 	      <screen>&prompt.root; <userinput>/stand/sysinstall</userinput></screen>
 	    </informalexample> 
 
 	    from the command prompt.</para>
 	</step>
 
 	<step>
 	  <para>Select <command>Index</command>.</para>
 	</step>
 
 	<step>
 	  <para>Select <command>Partition</command>.</para>
 	</step>
 
 	<step>
 	  <para>Select the disk to edit with arrow keys and
 	    <keycap>SPACE</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>If you are using this entire disk for FreeBSD, select
 	    <command>A</command>.</para>
 	</step> 
 
 	<step>
 	  <para>When asked: 
 
 	    <informalexample>
 	      <screen>Do you want to do this with a true partition entry so as to remain
 cooperative with any future possible operating systems on the
 drive(s)?</screen>
 	    </informalexample>
 
 	    answer <command>yes</command>.</para>
 	</step>
 
 	<step>
 	  <para>Select <command>Write</command>.</para>
 	</step>
 
 	<step>
 	  <para>When asked to install the boot manager, select None
 	    with <keycap>SPACE</keycap> then hit
 	    <keycap>ENTER</keycap> for OK.</para>
 	</step>
 
 	<step>
 	  <para><command>Quit</command> the FDISK Editor.</para>
 	</step>
 
 	<step>
 	  <para>You'll be asked about the boot manager, select
 	    <command>None</command> again. </para>
 	</step> 
 
 	<step>
 	  <para>Select <command>Label</command> from the Index
 	    menu.</para>
 	</step>  
 
 	<step>
 	  <para>Label as desired.  For a single partition, accept the
 	    default size, type filesystem, and a mountpoint (which
 	    isn't used).</para>
 	</step> 
 
 	<step>
 	  <para>The filesystem will be newfs'd for you, unless you
 	    select otherwise (for new partitions you'll want to do
 	    this!).  You'll get the error:
 
 	    <informalexample>
 	      <screen>Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory</screen> 
 	    </informalexample>
 
 	    Ignore.</para>
 	</step>
 
 	<step>
 	  <para>Exit out by repeatedly pressing
 	    <keycap>ESCAPE</keycap>.</para>
 	</step>
       </procedure>
 
       <para>Your new disk is now ready for use.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Other Disk Operations</title>
 
     <sect2>
       <title>Adding Swap Space</title>
 
       <para>As a system grows, it's need for swap space can also grow.
 	Although adding swap space to existing disks is very
 	difficult, a new disk can be partitioned with additional swap
 	space.</para>
 
       <para>To add swap space when adding a disk to a system:</para>
 
       <procedure>
 	<step>
 	  <para>When partitioning the disk, edit the disklabel and
 	    allocate the amount of swap space to add in partition `b'
 	    and the remainder in another partition, such as `a' or
 	    `e'.  The size is given in 512 byte blocks.</para>
 	</step>
 
 	<step>
 	  <para>When newfsing the drive, do NOT newfs the `c'
 	    partition.  Instead, newfs the partition where the
 	    non-swap space lies.</para>
 	</step> 
 
 	<step>
 	  <para>Add an entry to <filename>/etc/fstab</filename> as
 	    follows:</para>
 
 	  <informalexample>
 	    <programlisting>/dev/ad0b                       none            swap    sw 0 0
 	    </programlisting>
 	  </informalexample>
 	  
 	  <para>Change <filename>/dev/ad0b</filename> to the device of the newly added
 	    space.</para>
 	</step>
 
 	<step>
 	  <para>To make the new space immediately available, use the
 	    <command>swapon</command> command.
 
 	    <informalexample>
 	      <screen>&prompt.root; <userinput>swapon /dev/da0b</userinput>
 swapon:  added /dev/da0b as swap space</screen>
 	    </informalexample>
 	  </para>
 	</step>
       </procedure>
     </sect2>
 
     <sect2>
       <title>Copying the Contents of Disks</title>
 <!-- Should have specific tag -->
       
       <para>Submitted By:  Renaud Waldura
 	(<email>renaud@softway.com</email>) </para>
 
       <para>To move file from your original base disk to the fresh new
 	one, do:
 
 	<informalexample>
 	  <screen>&prompt.root; <userinput>mount /dev/ad2 /mnt</userinput>
 &prompt.root; <userinput>pax -r -w -p e /usr/home /mnt</userinput>
 &prompt.root; <userinput>umount /mnt</userinput>
 &prompt.root; <userinput>rm -rf /usr/home/*</userinput>
 &prompt.root; <userinput>mount /dev/ad2 /usr/home</userinput></screen>
 	</informalexample>
       </para>
     </sect2>
 
     <sect2>
       <title>Creating Striped Disks using CCD</title>
 
       <para>Commands Submitted By: Stan Brown
 	(<email>stanb@awod.com</email>) </para>
 
       <para>The Concatenated Disk Driver, or CCD, allows you to treat
 	several identical disks as a single disk.  Striping can result
 	in increased disk performance by distributing reads and writes
 	across the disks.  See the &man.ccd.4; and &man.ccdconfig.8;
 	man pages or the <ulink
 	  URL="http://stampede.cs.berkeley.edu/ccd/">CCD
 	  Homepage</ulink> for further details.</para>
 
       <para>You no longer need to build a special kernel to run ccd.  When you
 	run <command>ccdconfig</command>, it will load the KLD for you if the
 	kernel does not contain CCD support.</para>
 
       <para>You build CCDs on disk partitions of type
 	<emphasis>4.2BSD</emphasis>.  If you want to use the entire disk, you
 	still need to create a new partition.  For example, <userinput>disklabel
 	-e</userinput> might show:
 
       <informalexample>
 	<screen>#        size   offset    fstype   [fsize bsize bps/cpg]
   c: 60074784        0    unused        0     0     0   # (Cyl.    0 - 59597)</screen>
       </informalexample>
 
       <para>You shouldn't use partition <emphasis>c</emphasis> for the CCD,
       since it is of type <emphasis>unused</emphasis>.  Instead, create a new
       partition of exactly the same size, but with type
       <emphasis>4.2BSD</emphasis>:</para>
 
       <informalexample>
 	<screen>#        size   offset    fstype   [fsize bsize bps/cpg]
   c: 60074784        0    unused        0     0     0   # (Cyl.    0 - 59597)
 <userinput>   e: 60074784        0    4.2BSD        0     0     0   # (Cyl.    0 - 59597)</userinput></screen>
       </informalexample>
 
 	<para>To create a new CCD, execute the following commands.  This
 	describes how to add three disks together; simply add or remove devices
 	as necessary.  Remember that the disks to be striped must be
 	<emphasis>identical.</emphasis></para>
 
       <informalexample>
 	<screen>&prompt.root; <userinput>cd /dev ; sh MAKDEV ccd0</userinput>
 
 &prompt.root; <userinput>disklabel -r -w da0 auto</userinput>
 &prompt.root; <userinput>disklabel -r -w da1 auto</userinput>
 &prompt.root; <userinput>disklabel -r -w da2 auto</userinput>
 
 &prompt.root; <userinput>disklabel -e da0</userinput>
 <lineannotation>Add partition e with type 4.2BSD</lineannotation>
 &prompt.root; <userinput>disklabel -e da1</userinput>
 <lineannotation>Add partition e with type 4.2BSD</lineannotation>
 &prompt.root; <userinput>disklabel -e da2</userinput>
 <lineannotation>Add partition e with type 4.2BSD</lineannotation>
 
 &prompt.root; <userinput>ccdconfig ccd0 273 0 /dev/da0e /dev/da1e /dev/da2e</userinput>
 
 &prompt.root; <userinput>newfs /dev/ccd0c</userinput></screen>
       </informalexample>
 
       <para>The value 273 is the stripe size.  This is the number of disk
       sectors (of 512 bytes each) in each block of data on the CCD.  It should
       be at least 128 kB, and it should not be not be a power of 2.</para>
 
       <para>Now you can mount and use your CCD by referencing device
 	<filename>/dev/ccd0c</filename>.</para>
 
       <para>A more powerful and flexible alternative to CCD is Vinum.  See the
         <ulink URL="http://www.vinumvm.org/">Vinum Project home page</ulink>
         for further details.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Credits</title>
 
     <para>The author would like to thank the following individuals for
       their contributions to this project:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Darryl Okahata
 	  (<email>darrylo@hpnmhjw.sr.hp.com</email>) for his simple
 	  dedicated mode setup documentation which I have used
 	  repeatedly on FreeBSD-questions.</para>
       </listitem>
 
       <listitem>
 	<para>Jordan Hubbard (<email>jkh@FreeBSD.org</email>) for
 	  making sysinstall useful for this type of task.</para>
       </listitem>
 
       <listitem>
 	<para>John Fieber (<email>jfieber@indiana.edu</email>) for
 	  making information and examples of the DocBook DTD on which
 	  this document is based.</para>
       </listitem>
 
       <listitem>
 	<para>Greg Lehey (<email>grog@FreeBSD.org</email>) for
 	  checking my work and pointing out inaccuracies, as well as
 	  miscellaneous support.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/articles/freebsd-questions/article.sgml b/en_US.ISO8859-1/articles/freebsd-questions/article.sgml
index 063e52243e..77ad87601e 100644
--- a/en_US.ISO8859-1/articles/freebsd-questions/article.sgml
+++ b/en_US.ISO8859-1/articles/freebsd-questions/article.sgml
@@ -1,564 +1,564 @@
 <!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>How to get best results from the FreeBSD-questions mailing
       list</title>
 
     <author>
       <firstname>Greg</firstname>
       <surname>Lehey</surname>
 
       <affiliation>
 	<address><email>grog@FreeBSD.org</email></address>
       </affiliation>
     </author>
 
-    <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/freebsd-questions/article.sgml,v 1.3 2001/07/10 14:00:14 dd Exp $</pubdate>
+    <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/freebsd-questions/article.sgml,v 1.4 2001/07/13 16:34:19 nik Exp $</pubdate>
 
     <abstract>
       <para>This document provides useful information for people looking to
 	prepare an e-mail to the FreeBSD-questions mailing list.  Advice and
 	hints are given that will maximise the chance that the reader will
 	receive useful replies.</para>
 
       <para>This document is regularly posted to the FreeBSD-questions mailing
 	list.</para>
     </abstract>
   </articleinfo>
   
   <sect1>
     <title id="Introduction">Introduction</title>
     
     <para><literal>FreeBSD-questions</literal> is a mailing list maintained by
       the FreeBSD project to help people who have questions about the normal
       use of FreeBSD.  Another group, <literal>FreeBSD-hackers</literal>,
       discusses more advanced questions such as future development
       work.</para>
 
     <note>
       <para>The term <quote>hacker</quote> has nothing to do with breaking
 	into other people's computers.  The correct term for the latter
 	activity is <quote>cracker</quote>, but the popular press hasn't found
 	out yet.  The FreeBSD hackers disapprove strongly of cracking
 	security, and have nothing to do with it.  For a longer description of
 	hackers, see Eric Raymond's <ulink
 	url="http://www.tuxedo.org/~esr/faqs/hacker-howto.html">How To Become
 	A Hacker</ulink></para>
     </note>
     
     <para>This is a regular posting aimed to help both those seeking advice
       from FreeBSD-questions (the <quote>newcomers</quote>), and also those
       who answer the questions (the <quote>hackers</quote>).</para>
 
     <para>Inevitably there is some friction, which stems from the different
       viewpoints of the two groups.  The newcomers accuse the hackers of being
       arrogant, stuck-up, and unhelpful, while the hackers accuse the
       newcomers of being stupid, unable to read plain English, and expecting
       everything to be handed to them on a silver platter.  Of course, there's
       an element of truth in both these claims, but for the most part these
       viewpoints come from a sense of frustration.</para>
 
     <para>In this document, I'd like to do something to relieve this
       frustration and help everybody get better results from
       FreeBSD-questions.  In the following section, I recommend how to submit
       a question; after that, we'll look at how to answer one.</para>
   </sect1>
   
   <sect1>
     <title id="subscribe">How to subscribe to FreeBSD-questions</title>
 
     <para>FreeBSD-questions is a mailing list, so you need mail access.  Send
       a mail message to <email>majordomo@FreeBSD.org</email> with the single
       line:</para>
 
     <literallayout class="monospaced">subscribe FreeBSD-questions</literallayout>
     
     <para><application>majordomo</application> is an automatic program which
       maintains the mailing list, so you don't need a subject line.  If your
       mailer complains, however, you can put anything you like in the subject
       line.</para>
     
     <para>When you get the reply from <application>majordomo</application>
       telling you the details of the list, <emphasis>please save
       it</emphasis>. If you ever should want to leave the list, you'll need
       the information there.  See the next section for more details.</para>
   </sect1>
   
   <sect1>
     <title id="unsubscribe">How to unsubscribe from FreeBSD-questions</title>
 
     <para>When you subscribed to FreeBSD-questions, you got a welcome message
       from <email>Majordomo@FreeBSD.ORG</email>.  In this message, amongst
       other things, it told you how to unsubscribe.  Here's a typical
       message:</para>
 
     <literallayout class="monospaced">Welcome to the freebsd-questions mailing list!
 
 If you ever want to remove yourself from this mailing list, you can send
 mail to "Majordomo@FreeBSD.ORG" with the following command in the body
 of your email message:
 
 unsubscribe freebsd-questions Greg Lehey &lt;grog@lemis.de&gt;
 
 Here's the general information for the list you've subscribed to,
 in case you don't already have it:
 
 FREEBSD-QUESTIONS               User questions
 This is the mailing list for questions about FreeBSD.
 You should not send "how to" questions to the technical lists unless
 you consider the question to be pretty technical.</literallayout>
 
     <para>Normally, unsubscribing is even simpler than the message suggests:
       you don't need to specify your mail ID unless it is different from the
       one which you specified when you subscribed.</para>
 
     <para>If Majordomo replies and tells you (incorrectly) that you're not on
       the list, this may mean one of two things:</para>
 
     <orderedlist>
       <listitem>
 	<para>You have changed your mail ID since you subscribed.  That's
 	  where keeping the original message from <literal>majordomo</literal>
 	  comes in handy. For example, the sample message above shows my mail
 	  ID as <literal>grog@lemis.de</literal>.  Since then, I have changed
 	  it to <literal>grog@lemis.com</literal>.  If I were to try to remove
 	  <literal>grog@lemis.com</literal> from the list, it would fail: I
 	  would have to specify the name with which I joined.</para>
       </listitem>
 
       <listitem>
 	<para>You're subscribed to a mailing list which is subscribed to
 	  <literal>FreeBSD-questions</literal>.  If that's the case, you'll
 	  have to figure out which one it is and get your name taken off that
 	  one.  If you're not sure which one it might be, check the headers of
 	  the messages you receive from freebsd-questions: maybe there's a
 	  clue there.</para>
       </listitem>
     </orderedlist>
 
     <para>If you've done all this, and you still can't figure out what's going
       on, send a message to <email>Postmaster@FreeBSD.org</email>, and he will
       sort things out for you.  <emphasis>Don't</emphasis> send a message to
       FreeBSD-questions: they can't help you.</para>
   </sect1>
 
   <sect1>
     <title id="askwho">Should I ask <literal>-questions</literal> or
       <literal>-hackers</literal>?</title>
 
     <para>Two mailing lists handle general questions about FreeBSD,
       <literal>FreeBSD-questions</literal> and
       <literal>FreeBSD-hackers</literal>.  In some cases, it's not really
       clear which group you should ask.  The following criteria should help
       for 99% of all questions, however:</para>
     
     <orderedlist>
       <listitem>
 	<para>If the question is of a general nature, ask
 	  <literal>FreeBSD-questions</literal>.  Examples might be questions
 	  about installing FreeBSD or the use of a particular UNIX
 	  utility.</para>
       </listitem>
       
       <listitem>
 	<para>If you think the question relates to a bug, but you're not sure,
 	  or you don't know how to look for it, send the message to
 	  <literal>FreeBSD-questions</literal>.</para>
       </listitem>
       
       <listitem>
 	<para>If the question relates to a bug, and you're
 	  <emphasis>sure</emphasis> that it's a bug (for example, you can
 	  pinpoint the place in the code where it happens, and you maybe have
 	  a fix), then send the message to
 	  <literal>FreeBSD-hackers</literal>.</para>
       </listitem>
 
       <listitem>
 	<para>If the question relates to enhancements to FreeBSD, and you
 	  can make suggestions about how to implement them, then send the
 	  message to <literal>FreeBSD-hackers</literal>.</para>
       </listitem>
     </orderedlist>
 
     <para>There are also a number of other specialized mailing lists, for
       example <literal>FreeBSD-isp</literal>, which caters to the interests of
       ISPs (Internet Service Providers) who run FreeBSD.  If you happen to be
       an ISP, this doesn't mean you should automatically send your questions
       to <literal>FreeBSD-isp</literal>.  The criteria above still apply, and
       it's in your interest to stick to them, since you're more likely to get
       good results that way.</para>
   </sect1>
 
   <sect1>
     <title id="submit">How to submit a question</title>
   
     <para>When submitting a question to FreeBSD-questions, consider the
       following points:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Remember that nobody gets paid for answering a FreeBSD
 	  question. They do it of their own free will.  You can influence this
 	  free will positively by submitting a well-formulated question
 	  supplying as much relevant information as possible.  You can
 	  influence this free will negatively by submitting an incomplete,
 	  illegible, or rude question. It's perfectly possible to send a
 	  message to FreeBSD-questions and not get an answer even if you
 	  follow these rules.  It's much more possible to not get an answer if
 	  you don't.  In the rest of this document, we'll look at how to get
 	  the most out of your question to FreeBSD-questions.</para>
       </listitem>
       
       <listitem>
 	<para>Not everybody who answers FreeBSD questions reads every message:
 	  they look at the subject line and decide whether it interests them.
 	  Clearly, it's in your interest to specify a subject. ``FreeBSD
 	  problem'' or ``Help'' aren't enough.  If you provide no subject at
 	  all, many people won't bother reading it.  If your subject isn't
 	  specific enough, the people who can answer it may not read
 	  it.</para>
       </listitem>
 
       <listitem>
 	<para>Format your message so that it is	legible, and
 	    PLEASE DON'T SHOUT!!!!!.  We appreciate that a lot of people don't
 	    speak English as their first language, and we try to make
 	    allowances for that, but it's really painful to try to read a
 	    message written full of typos or without any line breaks.</para>
 	
 	<para>Don't underestimate the effect that a poorly formatted mail
 	  message has, not just on the FreeBSD-questions mailing list.
 	  Your mail message is all people see of you, and if it's poorly
 	  formatted, one line per paragraph, badly spelt, or full of
 	  errors, it will give people a poor impression of you.</para>
 
 	<para>A lot of badly formatted messages come from
 	  <ulink url="http://www.lemis.com/email.html">bad mailers or badly
 	  configured mailers</ulink>.  The following mailers are known to
 	  send out badly formatted messages without you finding out about
 	  them:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>cc:Mail</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Eudora</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>exmh</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Microsoft Exchange</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Microsoft Internet Mail</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Microsoft Outlook</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Netscape</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>As you can see, the mailers in the Microsoft world are frequent
 	  offenders.  If at all possible, use a UNIX mailer. If you must use a
 	  mailer under Microsoft environments, make sure it is set up
 	  correctly. Try not to use <acronym>MIME</acronym>: a lot of people
 	  use mailers which don't get on very well with
 	  <acronym>MIME</acronym>.</para>
       </listitem>
       
       <listitem>
 	<para>Make sure your time and time zone are set correctly.  This may
 	  seem a little silly, since your message still gets there, but many
 	  of the people you are trying to reach get several hundred messages a
 	  day.  They frequently sort the incoming messages by subject and by
 	  date, and if your message doesn't come before the first answer, they
 	  may assume they missed it and not bother to look.</para>
       </listitem>
 
       <listitem>
 	<para>Don't include unrelated questions in the same message.  Firstly,
 	  a long message tends to scare people off, and secondly, it's more
 	  difficult to get all the people who can answer all the questions to
 	  read the message.</para>
       </listitem>
 
       <listitem>
 	<para>Specify as much information as possible. This is a difficult
 	  area, and we need to expand on what information you need to submit,
 	  but here's a start:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>In nearly every case, it's important to know the version of
 	      FreeBSD you're running.  This is particularly the case for
 	      FreeBSD-CURRENT, where you should also specify the date of the
 	      sources, though of course you shouldn't be sending questions
 	      about -CURRENT to FreeBSD-questions.</para>
 	  </listitem>
 	  
 	  <listitem><para>With any problem which <emphasis>could</emphasis> be
 	      hardware related, tell us about your hardware.  In case of
 	      doubt, assume it's possible that it's hardware.  What kind of
 	      CPU are you using?  How fast?  What motherboard?  How much
 	      memory?  What peripherals?</para>
 
 	    <para>There's a judgement call here, of course, but the output of
 	      the &man.dmesg.8; command can frequently be very useful, since it
 	      tells not just what hardware you're running, but what version of
 	      FreeBSD as well.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>If you get error messages, don't say <quote>I get error
 		messages</quote>, say (for example) <quote>I get the error
 		message 'No route to host'</quote>.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If your system panics, don't say <quote>My system
 		panicked</quote>, say (for example) <quote>my system panicked
 		with the message 'free vnode isn't'</quote>.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you have difficulty installing FreeBSD, please tell us
 	      what hardware you have.  In particular, it's important to know
 	      the IRQs and I/O addresses of the boards installed in your
 	      machine.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you have difficulty getting PPP to run, describe the
 	      configuration.  Which version of PPP do you use?  What kind of
 	      authentication do you have?  Do you have a static or dynamic IP
 	      address?  What kind of messages do you get in the log
 	      file?</para>
 	  </listitem>
 	</itemizedlist>
       </listitem>
 
       <listitem>
           <para>A lot of the information you need to supply is the output of
 	  programs, such as &man.dmesg.8;, or console messages, which usually
 	  appear in <filename>/var/log/messages</filename>.  Don't try to copy
 	  this information by typing it in again; it's a real pain, and you're
 	  bound to make a mistake. To send log file contents, either make a
 	  copy of the file and use an editor to trim the information to what
 	  is relevant, or cut and paste into your message.  For the output of
 	  programs like &man.dmesg.8;, redirect the output to a file and
 	  include that.  For example,</para>
 
 	<screen>&prompt.user; <userinput>dmesg &gt; /tmp/dmesg.out</userinput></screen>
 
 	<para>This redirects the information to the file
 	  <filename>/tmp/dmesg.out</filename>.</para>
       </listitem>
       
       <listitem>
 	<para>If you do all this, and you still don't get an answer, there
 	  could be other reasons.  For example, the problem is so complicated
 	  that nobody knows the answer, or the person who does know the answer
 	  was offline.  If you don't get an answer after, say, a week, it
 	  might help to re-send the message.  If you don't get an answer to
 	  your second message, though, you're probably not going to get one
 	  from this forum.  Resending the same message again and again will
 	  only make you unpopular.</para>
       </listitem>
     </itemizedlist>
     
     <para>To summarize, let's assume you know the answer to the following
       question (yes, it's the same one in each case <literal>:-)</literal>.
       You choose which of these two questions you would be more prepared to
       answer:</para>
 
     <example>
       <title>Message 1</title>
 
       <literallayout class="monospaced">Subject: HELP!!?!??
 I just can't get hits damn silly FereBSD system to
 workd, and Im really good at this tsuff, but I have never seen
 anythign sho difficult to install, it jst wont work whatever I try
 so why don't y9ou guys tell me what I doing wrong.</literallayout>
     </example>
 
     <example>
       <title>Message 2</title>
 
     <literallayout class="monospaced">Subject: Problems installing FreeBSD
 
-I've just got the FreeBSD 2.1.5 CD-ROM from Walnut Creek, and I'm having a lot
+I've just got the FreeBSD 2.1.5 CDROM from Walnut Creek, and I'm having a lot
 of difficulty installing it.  I have a 66 MHz 486 with 16 MB of
 memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball
-disk and a Toshiba 3501XA CD-ROM drive.  The installation works just
+disk and a Toshiba 3501XA CDROM drive.  The installation works just
 fine, but when I try to reboot the system, I get the message
 ``Missing Operating System''.</literallayout>
     </example>
   </sect1>
 
   <sect1>
     <title id="followup">How to follow up to a question</title>
 
     <para>Often you will want to send in additional information to a question
       you have already sent.  The best way to do this is to reply to your
       original message.  This has three advantages:</para>
 
     <orderedlist>
       <listitem>
 	<para>You include the original message text, so people will know what
 	  you're talking about.  Don't forget to trim unnecessary text out,
 	  though.</para>
       </listitem>
       
       <listitem>
 	<para>The text in the subject line stays the same (you did remember to
 	  put one in, didn't you?).  Many mailers will sort messages by
 	  subject. This helps group messages together.</para>
       </listitem>
 
       <listitem>
 	<para>The message reference numbers in the header will refer to the
 	  previous message.  Some mailers, such as
 	  <ulink url="http://www.mutt.org/">mutt</ulink>, can
 	  <emphasis>thread</emphasis> messages, showing the exact
 	  relationships between the messages.</para>
       </listitem>
     </orderedlist>
   </sect1>
   
   <sect1>
     <title id="answer">How to answer a question</title>
 
 
     <para>Before you answer a question to FreeBSD-questions, consider:</para>
 
     <orderedlist>
       <listitem>
 	<para>A lot of the points on submitting questions also apply to
 	  answering questions.  Read them.</para>
       </listitem>
 
       <listitem>
 	<para>Has somebody already answered the question?  The easiest way to
 	  check this is to sort your incoming mail by subject: then
 	  (hopefully) you'll see the question followed by any answers, all
 	  together.</para>
 	
 	<para>If somebody has already answered it, it doesn't automatically
 	  mean that you shouldn't send another answer.  But it makes sense to
 	  read all the other answers first.</para>
       </listitem>
 
       <listitem>
 	<para>Do you have something to contribute beyond what has already been
 	  said?  In general, <quote>Yeah, me too</quote> answers don't help
 	  much, although there are exceptions, like when somebody is
 	  describing a problem he's having, and he doesn't know whether it's
 	  his fault or whether there's something wrong with the hardware or
 	  software.  If you do send a <quote>me too</quote> answer, you should
 	  also include any further relevant information.</para>
       </listitem>
 
       <listitem>
 	<para>Are you sure you understand the question?  Very frequently, the
 	  person who asks the question is confused or doesn't express himself
 	  very well.  Even with the best understanding of the system, it's
 	  easy to send a reply which doesn't answer the question.  This
 	  doesn't help: you'll leave the person who submitted the question
 	  more frustrated or confused than ever.  If nobody else answers, and
 	  you're not too sure either, you can always ask for more
 	  information.</para>
       </listitem>
 
       <listitem>
 	<para>Are you sure your answer is correct?
 	If not, wait a day or so. If nobody else comes up with a
 	better answer, you can still reply and say, for example, <quote>I
 	don't know if this is correct, but since nobody else has
-	replied, why don't you try replacing your ATAPI CD-ROM with
+	replied, why don't you try replacing your ATAPI CDROM with
 	a frog?</quote>.</para>
       </listitem>
 
       <listitem>
 	<para>Unless there's a good reason to do otherwise, reply to the
 	  sender and to FreeBSD-questions. Many people on the
 	  FreeBSD-questions are <quote>lurkers</quote>: they learn by reading
 	  messages sent and replied to by others. If you take a message which
 	  is of general interest off the list, you're depriving these people
 	  of their information. Be careful with group replies; lots of people
 	  send messages with hundreds of CCs. If this is the case, be sure to
 	  trim the Cc: lines appropriately.</para>
       </listitem>
       
       <listitem>
 	<para>Include relevant text from the original message. Trim it to the
 	  minimum, but don't overdo it.  It should still be possible for
 	  somebody who didn't read the original message to understand what
 	  you're talking about.</para>
       </listitem>
       
       <listitem>
 	<para>Use some technique to identify which text came from the original
 	  message, and which text you add.  I personally find that prepending
 	  <quote><literal>&gt; </literal></quote> to the original message
 	  works best.  Leaving white space after the
 	  <quote><literal>&gt; </literal></quote> and leave empty lines
 	  between your text and the original text both make the result more
 	  readable.</para>
       </listitem>
 
       <listitem>
 	<para>Put your response in the correct place (after the text to which
 	  it replies).  It's very difficult to read a thread of responses
 	  where each reply comes before the text to which it replies.</para>
       </listitem>
 
       <listitem>
 	<para>Most mailers change the subject line on a reply by prepending a
 	  text such as <quote>Re: </quote>.  If your mailer doesn't do it
 	  automatically, you should do it manually.</para>
       </listitem>
       
       <listitem>
 	<para>If the submitter didn't abide by format conventions (lines too
 	  long, inappropriate subject line), <emphasis>please</emphasis> fix
 	  it. In the case of an incorrect subject line (such as
 	  <quote>HELP!!??</quote>), change the subject line to (say)
 	  <quote>Re: Difficulties with sync PPP (was: HELP!!??)</quote>.  That
 	  way other people trying to follow the thread will have less
 	  difficulty following it.</para>
 
 	<para>In such cases, it's appropriate to say what you did and why you
 	  did it, but try not to be rude.  If you find you can't answer
 	  without being rude, don't answer.</para>
 
 	<para>If you just want to reply to a message because of its bad
 	  format, just reply to the submitter, not to the list.  You can just
 	  send him this message in reply, if you like.</para>
       </listitem>
     </orderedlist>
   </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/ipsec-must/article.sgml b/en_US.ISO8859-1/articles/ipsec-must/article.sgml
index 912364faf1..b51bc1d876 100644
--- a/en_US.ISO8859-1/articles/ipsec-must/article.sgml
+++ b/en_US.ISO8859-1/articles/ipsec-must/article.sgml
@@ -1,297 +1,297 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 
 <html>
   <head>
     <title>Independent Verification of IPSec Functionality in FreeBSD</title>
   </head>
   
   <body text="#000000" bgcolor="#FFFFFF">
     
     <h1>Independent Verification of IPsec Functionality Under FreeBSD 3.0</h1>
     
     <p align="center"><i>You installed IPsec and it seems to be working.&nbsp;
 	How do you know?  I describe a method for experimentally verifying
 	that IPsec is working</i></p>
     
     <h2>The Problem</h2>
     
     <p>First, let's assume you have <a href="#Installing IPsec">installed
 	<i>IPsec</i></a>. How do you know its <a href="#Caveat">working</a>?
       Sure, your connection won't work if its misconfigured, and it will work
       when you finally get it right. <i>Netstat</i> will list it. But can you
       independently confirm it?</p>
     
     <h2>The Solution</h2>
     
     <p>First, some crypto-relevent info theory:</p>
     
     <ol>
       <li>
 	<p>Encrypted data is uniformly distributed, ie, has maximal entropy
 	  per symbol.</p>
       </li>
       
       <li>
 	<p>Raw, uncompressed data is typically redundant, i.e., has
 	  sub-maximal entropy.</p>
       </li>
     </ol>
     
     <p>Suppose you could measure the entropy of the data to- and from- your
       network interface. Then you could see the difference between unencrypted
       data and encrypted data. This would be true even if some of the data
       in "encrypted mode" was not encrypted ---as the outermost IP header must
       be, if the packet is to be routable.</p>
     
     <h4><a name="MUST"></a>MUST</h4>
     
     <p>Ueli Maurer's "Universal Statistical Test for Random Bit Generators"
       ("MUST") quickly measures the entropy of a sample. It uses a
       compression-like algorithm. <a href="#Maurer's Universal Statistical
 	Test">The code is given below for a variant which measures successive
 	(~quarter megabyte) chunks of a file</a>.</p>
     
     <h4><a NAME="Tcpdump"></a>Tcpdump</h4>
     
     <p>We also need a way to capture the raw network data. A program called
       "<i>tcpdump</i>" lets you do this, if you have enabled the <i>Berkeley
 	Packet Filter</i> interface in your <a
 	href="#KERNELNAME">kernel's config file</a>.</p>
     
     <p>The command</p>
 
     <blockquote><b>tcpdump</b> <b>-c</b> 4000 <b>-s</b> 10000 <b>-w</b>
       <i>dumpfile.bin</i></blockquote>
     
     <p>will capture 4000 raw packets to <i>dumpfile.bin</i>. Up to 10,000
       bytes per packet will be captured in this example.</p>
     
     <h2>The Experiment</h2>
     
     <p>Here's the experiment. Open a window to an IPsec host and another
       window to an insecure host.</p>
     
     <p>Now start <a href="#Tcpdump">capturing packets</a>.</p>
     
     <p>In the "secure" window, run the unix command "yes", which will stream
       the "y" character.  After a while, stop this. Switch to the insecure
       window, and repeat.  After a while, stop.</p>
     
     <p>Now run <a href="#Maurer's Universal Statistical Test">MUST</a> on the
       captured packets. You should see something like the following.
       The important thing to note is that the secure connection has 93% (6.7)
       of the expected value (7.18), and the "normal" connection has 29% (2.1)
       of the expected value.</p>
 
     
     <pre>% tcpdump -c 4000 -s 10000 -w ipsecdemo.bin
 % uliscan ipsecdemo.bin
 
 Uliscan 21 Dec 98
 L=8 256 258560
 Measuring file ipsecdemo.bin
 Init done
 Expected value for L=8 is 7.1836656
 6.9396 --------------------------------------------------------
 6.6177 -----------------------------------------------------
 6.4100 ---------------------------------------------------
 2.1101 -----------------
 2.0838 -----------------
 2.0983 -----------------</pre>
 
     <h2><a NAME="Caveat"></a>Caveat</h2>
     
     <p>This experiment shows that IPsec <i>does</i> seem to be distributing the
       payload data <i>uniformly</i>, as encryption should. However, the
-      experiment described here <i>can not </i>detect many possible flaws in a
+      experiment described here <i>cannot </i>detect many possible flaws in a
       system (none of which do I have any evidence for). These include poor
       key generation or exchange, data or keys being visible to others, use of
       weak algorithms, kernel subversion, etc. Study the source; know the
       code.</p>
       
     <h2><a NAME="IPsec"></a>IPsec -Definition</h2>
 
     <p>Internet Protocol security extensions to IP v 4; required for IP v6.  A
       protocol for negotiating encryption and authentication at the IP
       (host-to-host) level. SSL secures only one application socket; SSH
       secures only a login; PGP secures only a specified file or
       message. IPsec encrypts everything between two hosts.</p>
     
     <h2><a NAME="Installing IPsec"></a>Installing IPsec</h2>
 
     <p>Starting from the BSD 3.0 stable release,</p>
     
     <ol>
       <li>
 	<p>install IPsec v0.04, rebuild, reinstall</p>
       </li>
 
       <li>
 	<p>run the administration tools (e.g, <i>ipsecadm</i>) and distribute
 	  keys (or use <i>Photuris</i> for key exchange)</p>
       </li>
 
       <li>
 	<p>set the routes (<i>rt</i>) up appropriately</p>
       </li>
     </ol>
     
     <p>You may want to make an "ipsec_setup" script containing the
       <i>ipsecadm</i> and <i>rt</i> commands which establish your IPsec
       tunnel. You can run this script automatically at boottime from your
       <i>/etc/rc.local</i> The ipsec_setup script will have to contain at
       least two <i>ipsecadm</i> commands and one <i>rt</i> command to be
       useful.</p>
 
     <h2><a NAME="KERNELNAME"></a>usr/src/sys/i386/conf/KERNELNAME</h2>
     
     <p>This needs to be present in the kernel config file in order to run
       IPsec. After adding it, run <i>config</i>, etc. and rebuild and
       reinstall.</p>
 
     <pre># The `bpfilter' pseudo-device enables the Berkeley Packet Filter. Be
 # aware of the legal and administrative consequences of enabling this
 # option. Heh heh. The number of devices determines the maximum number of
 # simultaneous BPF clients programs runnable.
 pseudo-device bpfilter 2 #Berkeley packet filter
 
 # IPSEC
 options IPSEC
 options "MD5"
 pseudo-device enc 1</pre>
 
     <h2><a name="Maurer's Universal Statistical Test"></a>Maurer's Universal Statistical Test (for block
       size=8 bits)</h2>
 
     <pre><![ CDATA [/*
   ULISCAN.c   ---blocksize of 8
 
   1 Oct 98
   1 Dec 98
   21 Dec 98       uliscan.c derived from ueli8.c
 
   This version has // comments removed for Sun cc
 
   This implements Ueli M Maurer's "Universal Statistical Test for Random
   Bit Generators" using L=8
 
   Accepts a filename on the command line; writes its results, with other
   info, to stdout.
 
   Handles input file exhaustion gracefully.
 
   Ref: J. Cryptology v 5 no 2, 1992 pp 89-105
   also on the web somewhere, which is where I found it.
 
   -David Honig
   honig@sprynet.com
 
   Usage:
   ULISCAN filename
   outputs to stdout
 */
 
 #define L 8
 #define V (1<<L)
 #define Q (10*V)
 #define K (100   *Q)
 #define MAXSAMP (Q + K)
 
 #include <stdio.h>
 #include <math.h>
 
 int main(argc, argv)
 int argc;
 char **argv;
 {
   FILE *fptr;
   int i,j;
   int b, c;
   int table[V];
   double sum = 0.0;
   int iproduct = 1;
   int run;
 
   extern double   log(/* double x */);
 
   printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP);
 
   if (argc < 2) {
     printf("Usage: Uliscan filename\n");
     exit(-1);
   } else {
     printf("Measuring file %s\n", argv[1]);
   }
 
   fptr = fopen(argv[1],"rb");
 
   if (fptr == NULL) {
     printf("Can't find %s\n", argv[1]);
     exit(-1);
   }
 
   for (i = 0; i < V; i++) {
     table[i] = 0;
   }
 
   for (i = 0; i < Q; i++) {
     b = fgetc(fptr);
     table[b] = i;
   }
 
   printf("Init done\n");
 
   printf("Expected value for L=8 is 7.1836656\n");
 
   run = 1;
 
   while (run) {
     sum = 0.0;
     iproduct = 1;
 
     if (run)
       for (i = Q; run && i < Q + K; i++) {
         j = i;
         b = fgetc(fptr);
 
         if (b < 0)
           run = 0;
 
         if (run) {
           if (table[b] > j)
             j += K;
 
           sum += log((double)(j-table[b]));
 
           table[b] = i;
         }
       }
 
     if (!run)
       printf("Premature end of file; read %d blocks.\n", i - Q);
 
     sum = (sum/((double)(i - Q))) /  log(2.0);
     printf("%4.4f ", sum);
 
     for (i = 0; i < (int)(sum*8.0 + 0.50); i++)
       printf("-");
 
     printf("\n");
 
     /* refill initial table */
     if (0) {
       for (i = 0; i < Q; i++) {
         b = fgetc(fptr);
         if (b < 0) {
           run = 0;
         } else {
           table[b] = i;
         }
       }
     }
   }
 }]]></pre>
   </body>
 </html>
 
 
diff --git a/en_US.ISO8859-1/articles/mh/article.sgml b/en_US.ISO8859-1/articles/mh/article.sgml
index b5f896203e..91025e8ff1 100644
--- a/en_US.ISO8859-1/articles/mh/article.sgml
+++ b/en_US.ISO8859-1/articles/mh/article.sgml
@@ -1,763 +1,763 @@
-<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/mh/article.sgml,v 1.11 2001/07/08 19:15:05 dannyboy Exp $ -->
+<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/mh/article.sgml,v 1.12 2001/07/11 13:13:41 nik Exp $ -->
 <!-- FreeBSD Documentation Project -->
 
 <!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN">
 <article>
   <articleinfo>
     <title>An MH Primer</title>
 
     <authorgroup>
       <author>
 	<firstname>Matt</firstname>
 
 	<surname>Midboe</surname>
 
 	<affiliation>
 	  <address>
 	    <email>matt@garply.com</email>
 	  </address>
 	</affiliation>
       </author>
     </authorgroup>
 
     <pubdate>v1.0, 16 January 1996</pubdate>
 
     <abstract>
       <para>This document contains an introduction to using MH on
 	FreeBSD</para>
     </abstract>
   </articleinfo>
 
   <sect1 id="mhintro">
     <title>Introduction</title>
 
     <para>MH started back in 1977 at the RAND Corporation, where the
       initial philosophies behind MH were developed. MH isn't so much
       a monolithic email program but a philosophy about how best to
       develop tools for reading email. The MH developers have done a
       great job adhering to the <acronym>KISS</acronym> principle: Keep It
       Simple Stupid.  Rather than have one large program for reading,
       sending and handling email they have written specialized
       programs for each part of your email life. One might liken MH to
       the specialization that one finds in insects and nature. Each
       tool in MH does one thing, and does it very well.</para>
 
     <para>Beyond just the various tools that one uses to handle their
       email MH has done an excellent job keeping the configuration of
       each of these tools consistent and uniform. In fact, if you are
       not quite sure how something is supposed to work or what the
       arguments for some command are supposed to be then you can
       generally guess and be right.  Each MH command is consistent
       about how it handles reading the configuration files and how it
       takes arguments on the command line.  One useful thing to
       remember is that you can always add a <option>-help</option> to
       the command to have it display the options for that
       command.</para>
 
     <para>The first thing that you need to do is to make sure that you
       have installed the MH package on your FreeBSD machine. If you
       installed from CDROM you should be able to execute the following
       to load mh:
 
       <informalexample>
 	<screen>&prompt.root; <userinput>pkg_add /cdrom/packages/mh-6.8.3.tgz</userinput></screen>
       </informalexample>
 
       You will notice that it created a <filename>/usr/local/lib/mh</filename>
       directory for you as well as adding several binaries to the
       <filename>/usr/local/bin</filename> directory. If you would prefer to
       compile it yourself then you can anonymous ftp it from <ulink
 	URL="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink
 	URL="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para>
 
     <para>This primer is not a full comprehensive explanation of how
       MH works. This is just intended to get you started on the road
       to happier, faster mail reading. You should read the man pages
       for the various commands. Also you might want to read the <ulink
 	URL="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also
       you can read the <ulink
 	URL="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mh-faq/part1/faq.html">FAQ
 	for MH</ulink>. The best resource for MH is the O'Reilly and
       Associates book written by Jerry Peek.</para>
   </sect1>
 
   <sect1>
     <title>Reading Mail</title>
 
     <para>This section covers how to use <command>inc</command>,
       <command>show</command>, <command>scan</command>, <command>next</command>,
       <command>prev</command>, <command>rmm</command>, <command>rmf</command>, and
       <command>msgchk</command>.  One of the best things about MH is the
       consistent interface between programs. A few things to keep in
       mind when using these commands is how to specify message lists.
       In the case of <command>inc</command> this doesn't really make any
       sense but with commands like <command>show</command> it is useful to
       know. </para>
 
     <para>A message list can consist of something like <parameter>23
 	20 16</parameter> which will act on messages 23, 20 and 16. This is
       fairly simple but you can do more useful things like
       <parameter>23-30</parameter> which will act on all the messages between
       23 and 30. You can also specify something like
       <parameter>cur:10</parameter> which will act on the current message and
       the next 9 messages. The <parameter>cur</parameter>, <parameter>last</parameter>,
       and <parameter>first</parameter> messages are special messages that refer
       to the current, last or first message in the folder.</para>
 
     <sect2 id="inc">
       <title><command>inc</command>, <command>msgchk</command>&mdash;read in your
 	new email or check it</title>
 
       <para>If you just type in <userinput>inc</userinput> and hit
 	<keycap>return</keycap> you will be well on your way to getting
 	started with MH. The first time you run <command>inc</command> it
 	will setup your account to use all the MH defaults and ask you
 	about creating a Mail directory. If you have mail waiting to
 	be downloaded you will see something that looks like:</para>
 
       <informalexample>
 	<screen>  29  01/15 Doug White         Re: Another Failed to boot problem&lt;&lt;On Mon, 15 J
   30  01/16 "Jordan K. Hubbar  Re: FBSD 2.1&lt;&lt;&gt; Do you want a library instead of
   31  01/16 Bruce Evans        Re: location of bad144 table&lt;&lt;&gt;&gt; &gt;It would appea
   32  01/16 "Jordan K. Hubbar  Re: video is up&lt;&lt;&gt; Anyway, mrouted won't run, ev
   33  01/16 Michael Smith      Re: FBSD 2.1&lt;&lt;Nate Williams stands accused of sa</screen>
       </informalexample>
 
       <para>This is the same thing you will see from a
 	<command>scan</command> (see <xref linkend="scan">). If you just run
 	<command>inc</command> with no arguments it will look on your
 	computer for email that is supposed to be coming to
 	you.</para>
 
       <para>A lot of people like to use POP for grabbing their email.
 	MH can do POP to grab your email. You will need to give
 	<command>inc</command> a few command line arguments.</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>inc -host mail.pop.org -user <replaceable>username</replaceable> -norpop</userinput></screen>
       </informalexample>
 
       <para>That tells <command>inc</command> to go to
 	<parameter>mail.pop.org</parameter> to download your email, and that
 	your username on their system is <replaceable>username</replaceable>. The
 	<option>-norpop</option> option tells <command>inc</command> to use
 	plain POP3 for downloading your email. MH has support for a
 	few different dialects of POP. More than likely you will never
 	ever need to use them though. While you can do more complex
 	things with inc such as audit files and scan format files this
 	will get you going.</para>
 
       <para>The <command>msgchk</command> command is used to get information
 	on whether or not you have new email. <command>msgchk</command> takes
 	the same <option>-host</option> and <option>-user</option>
 	options that <command>inc</command> takes.</para>
     </sect2>
 
     <sect2 id="show">
       <title><command>show</command>, <command>next</command> and
 	<command>prev</command>&mdash;displaying and moving through
 	email</title>
 
       <para><command>show</command> is to show a letter in your current
 	folder.  Like <command>inc</command>, <command>show</command> is a fairly
 	straightforward command. If you just type <userinput>show</userinput>
 	and hit <keycap>return</keycap> then it displays the current
 	message. You can also give specific message numbers to
 	show:</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>show 32 45 56</userinput></screen>
       </informalexample>
 
       <para>This would display message numbers 32, 45 and 56 right
 	after each other. Unless you change the default behavior
 	<command>show</command> basically just does a <command>more</command> on the
 	email message.</para>
 
       <para><command>next</command> is used to move onto the next message and
 	<command>prev</command> will go to the previous message. Both
 	commands have an implied <command>show</command> command so that when
 	you go to the next message it automatically displays
 	it.</para>
     </sect2>
 
     <sect2 id="scan">
       <title><command>scan</command>&mdash;shows you a scan of your
 	messages</title>
 
       <para><command>scan</command> will display a brief listing of the
 	messages in your current folder. This is an example of what
 	the <command>scan</command> command will give you.</para>
 
       <informalexample>
 	<screen>  30+ 01/16 Jordan K. Hubbar   Re: FBSD 2.1&lt;&lt;&gt; Do you want a library instead of
   31  01/16 Bruce Evans        Re: location of bad144 table&lt;&lt;&gt;&gt; &gt;It would appea
   32  01/16 Jordan K. Hubbar   Re: video is up&lt;&lt;&gt; Anyway, mrouted won't run, ev
   33  01/16 Michael Smith      Re: FBSD 2.1&lt;&lt;Nate Williams stands accused of sa</screen>
       </informalexample>
 
       <para>Like just about everything in MH this display is very
 	configurable.  This is the typical default display. It gives
 	you the message number, the date on the email, the sender, the
 	subject line, and a sentence fragment from the very beginning
 	of the email if it can fit it. The <literal>+</literal> means that
 	message is the current message, so if you do a
 	<command>show</command> it will display that message.</para>
 
       <para>One useful option for scan is the
 	<option>-reverse</option> option. This will list your messages
 	with the highest message number first and lowest message
 	number last. Another useful option with <command>scan</command> is to
 	have it read from a file. If you want to scan your incoming
 	mailbox on FreeBSD without having to <command>inc</command> it you
 	can do <command>scan -file
 	  /var/mail/<replaceable>username</replaceable></command>. This can be used
 	with any file that is in the <database>mbox</database> format.</para>
     </sect2>
 
     <sect2 id="rmm">
       <title><command>rmm</command> and <command>rmf</command>&mdash;remove the
 	current message or folder</title>
 
       <para><command>rmm</command> is used to remove a mail message. The
 	default is typically to not actually remove the message but to
 	rename the file to one that is ignored by the MH commands. You
 	will periodically need to go through and physically delete the
 	<quote>removed</quote> messages.</para>
 
       <para>The <command>rmf</command> command is used to remove folders.
 	This doesn't just rename the files but actually removes the
 	from the hard drive so you should be careful when you use this
 	command.</para>
     </sect2>
 
     <sect2 id="samplereading">
       <title>A typical session of reading with MH</title>
 
       <para>The first thing that you will want to do is
 	<command>inc</command> your new mail. So at a shell prompt just type
 	in <command>inc</command> and hit <keycap>return</keycap>.</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>inc</userinput>
 Incorporating new mail into inbox...
 
   36+ 01/19 Stephen L. Lange   Request...&lt;&lt;Please remove me as contact for pind
   37  01/19 Matt Thomas        Re: kern/950: Two PCI bridge chips fail (multipl
   38  01/19 Amancio Hasty Jr   Re: FreeBSD and VAT&lt;&lt;&gt;&gt;&gt; Bill Fenner said: &gt; In 
 &prompt.user;</screen>
       </informalexample>
 
       <para>This shows you the new email that has been added to your
 	mailbox. So the next thing to do is <command>show</command> the email
 	and move around.</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>show</userinput>
 Received: by sashimi.wwa.com (Smail3.1.29.1 #2)
         id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST
 Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST)
 From: "Stephen L. Lange" &lt;stvlange@wwa.com&gt;
 To: matt@garply.com
 Subject: Request...
 Message-Id: &lt;Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com&gt;
 Mime-Version: 1.0
 Content-Type: TEXT/PLAIN; charset=US-ASCII
 
 
 Please remove me as contact for pindat.com
 
 &prompt.user; <userinput>rmm</userinput>
 &prompt.user; <userinput>next</userinput>
 Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8
 .6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT
 Message-Id: &lt;199601191756.RAA24416@whydos.lkg.dec.com&gt;
 X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro
 tocol
 To: hsu@clinet.fi
 Cc: hackers@FreeBSD.org
 Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet 
  boards) 
 In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100."
              &lt;199601182318.AA11772@Sysiphos&gt; 
 X-Mailer: exmh version 1.5omega 10/6/94
 Date: Fri, 19 Jan 1996 17:56:40 +0000
 From: Matt Thomas &lt;matt@lkg.dec.com&gt;
 Sender: owner-hackers@FreeBSD.org
 Precedence: bulk
 
 
 This is due to a typo in pcireg.h (to
 which I am probably the guilty party).</screen>
       </informalexample>
 
       <para>The <command>rmm</command> removed the current message and the
 	<command>next</command> command moved me on to the next message.  Now
 	if I wanted to look at ten most recent messages so I could
 	read one of them here is what I would do:</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>scan last:10</userinput>
   26  01/16 maddy              Re: Testing some stuff&lt;&lt;yeah, well, Trinity has 
   27  01/17 Automatic digest   NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19
   28  01/17 Evans A Criswell   Re: Hey dude&lt;&lt;&gt;From matt@tempest.garply.com Tue 
   29  01/16 Karl Heuer         need configure/make volunteers&lt;&lt;The FSF is looki
   30  01/18 Paul Stephanouk    Re: [alt.religion.scientology] Raw Meat (humor)&lt;
   31  01/18 Bill Lenherr       Re: Linux NIS Solaris&lt;&lt;--- On Thu, 18 Jan 1996 1
   34  01/19 John Fieber        Re: Stuff for the email section?&lt;&lt;On Fri, 19 Jan
   35  01/19 support@foo.garpl  [garply.com #1138] parlor&lt;&lt;Hello. This is the Ne
   37+ 01/19 Matt Thomas        Re: kern/950: Two PCI bridge chips fail (multipl
   38  01/19 Amancio Hasty Jr   Re: FreeBSD and VAT&lt;&lt;&gt;&gt;&gt; Bill Fenner said: &gt; In 
 &prompt.user;</screen>
       </informalexample>
 
       <para>Then if I wanted to read message number 27 I would do a
 	<userinput>show 27</userinput> and it would be displayed. As you can
 	probably tell from this sample session MH is pretty easy to
 	use and looking through emails and displaying them is fairly
 	intuitive and easy.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Folders and Mail Searching</title>
 
     <para>Anybody who gets lots of email definitely wants to be able
       to prioritize, stamp, brief, de-brief, and number their emails
       in a variety of different ways. MH can do this better than just
       about anything. One thing that we haven't really talked about is
       the concept of folders. You have undoubtedly come across the
       folders concept using other email programs. MH has folders too.
       MH can even do sub-folders of a folder. One thing you should
       keep in mind with MH is that when you ran <command>inc</command> for
       the first time and it asked you if it could create a
       <filename>Mail</filename> directory it began storing everything in that
       directory. If you look at that directory you will find a
       directory named <filename>inbox</filename>. The <filename>inbox</filename>
       directory houses all of your incoming mail that hasn't been
       thrown anywhere else.</para>
 
     <para>Whenever you create a new folder a new directory is going to
       be created underneath your MH <filename>Mail</filename> directory, and
       messages in that folder are going to be stored in that
       directory.  When new email comes in that new email is thrown
       into your <filename>inbox</filename> directory with a file name that is
       equivalent to the message number.  So even if you didn't have
       any of the MH tools to read your email you could still use
-      standard UNIX commands to munge around in those directories and
+      standard Unix commands to munge around in those directories and
       just more your files. It's this simplicity that really gives you
       a lot of power with what you can do with your email.</para>
 
     <para>Just as you can use message lists like <parameter>23 16
 	42</parameter> with most MH commands there is a folder option you can
       specify with just about every MH command. If you do a
       <command>scan +freebsd</command> it will scan your <filename>freebsd</filename>
       folder, and your current folder will be changed to
       <filename>freebsd</filename>. If you do a <command>show +freebsd 23 16
 	42</command>, <command>show</command> is going to switch to your
       <filename>freebsd</filename> folder and display messages 23, 16 and 42.
       So remember that <option>+<replaceable>folder</replaceable></option> syntax. You
       will need to make sure you use it to make commands process
       different folders. Remember you default folder for mail is
       <filename>inbox</filename> so doing a <command>folder +inbox</command> should
       always get you back to your mail. Of course, in MH's infinite
       flexibility this can be changed but most places have probably
       left it as <command>inbox</command>.</para>
 
     <sect2>
       <title><command>pick</command>&mdash;search email that matches certain
 	criteria</title>
 
       <para><command>pick</command> is one of the more complex commands in
 	the MH system. So you might want to read the
 	<citerefentry><refentrytitle>pick</refentrytitle><manvolnum>1</manvolnum></citerefentry> man
 	page for a more thorough understanding. At its simplest level
 	you can do something like</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>pick -search pci</userinput>
 15
 42
 55
 56
 57</screen>
       </informalexample>
 
       <para>This will tell <command>pick</command> to look through every
 	single line in every message in your current folder and tell
 	you which message numbers it found the word <literal>pci</literal>
 	in. You can then <command>show</command> those messages and read them
 	if you wish or <command>rmm</command> them. You would have to specify
 	something like <command>show 15 42 55-57</command> to display them
 	though. A slightly more useful thing to do is this:</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>pick -search pci -seq pick</userinput>
 5 hits
 &prompt.user; <userinput>show pick</userinput></screen>
       </informalexample>
 
       <para>This will show you the same messages you just didn't have
 	to work as hard to do it. The <option>-seq</option> option is
 	really an abbreviation of <option>-sequence</option> and
 	<command>pick</command> is just a sequence which contains the message
 	numbers that matched. You can use sequences with just about
 	any MH command. So you could have done an <command>rmm pick</command>
 	and all those messages would be removed instead. You sequence
 	can be named anything. If you run pick again it will overwrite
 	the old sequence if you use the same name.</para>
 
       <para>Doing a <command>pick -search</command> can be a bit more
 	time consuming than just searching for message from someone,
 	or to someone. So <command>pick</command> allows you to use the
 	following predefined search criteria:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term><option>-to</option></term>
 
 	  <listitem>
 	    <para>search based upon who the message is to</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-cc</option></term>
 
 	  <listitem>
 	    <para>search based on who is in the cc list</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-from</option></term>
 
 	  <listitem>
 	    <para>search for who sent the message</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-subject</option></term>
 
 	  <listitem>
 	    <para>search for emails with this subject</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-date</option></term>
 
 	  <listitem>
 	    <para>find emails with a matching dat</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>--<replaceable>component</replaceable></option></term>
 
 	  <listitem>
 	    <para>search for any other component in the header. (i.e.
 	      <option>--reply-to</option> to find all emails with a certain
 	      reply-to in the header)</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
   
       <para>This allows you to do things like
 
 	<informalexample>
 	  <screen>&prompt.user; <userinput>pick -to freebsd-hackers@FreeBSD.org -seq hackers</userinput></screen>
 	</informalexample>
 
 	to get a list of all the email send to the FreeBSD hackers
 	mailing list. <command>pick</command> also allows you to group these
 	criteria in different ways using the following options:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>&hellip; <option>-and</option> &hellip;</para>
 	</listitem>
 
 	<listitem>
 	  <para>&hellip; <option>-or</option> &hellip</para>
 	</listitem>
 
 	<listitem>
 	  <para><option>-not</option> &hellip;</para>
 	</listitem>
 
 	<listitem>
 	  <para><option>-lbrace</option> &hellip;
 	    <option>-rbrace</option></para>
 	</listitem>
       </itemizedlist>
 
       <para>These commands allow you to do things like</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>pick -to freebsd-hackers -or -cc freebsd-hackers</userinput></screen>
       </informalexample>
 
       <para>That will grab all the email in your inbox that was sent
 	to freebsd-hackers or cc'd to that list. The brace options
 	allow you to group search criteria together. This is sometimes
 	very necessary as in the following example</para>
 
       <informalexample>
 	<screen>&prompt.user; <userinput>pick -lbrace -to freebsd-hackers -and 
   -not -cc freebsd-questions -rbrace -and -subject pci</userinput></screen>
       </informalexample>
 
       <para>Basically this says <quote>pick (to freebsd-hackers and
 	  not cc'd on freebsd-questions) and the subject is
 	  pci</quote>.  It should look through your folder and find
 	all messages sent to the freebsd-hackers list that aren't cc'd
 	to the freebsd-questions list that contain something on pci in
 	the subject line. Ordinarily you might have to worry about
 	something called operator precedence. Remember in math how you
 	evaluate from left to right and you do multiplication and
 	division first and addition and subtraction second? MH has the
 	same type of rules for <command>pick</command>. It's fairly complex
 	so you might want to study the man page. This document is just
 	to help you get acquainted with MH.</para>
     </sect2>
 
     <sect2>
       <title><command>folder</command>, <command>folders</command>,
 	<command>refile</command>&mdash;three useful programs for folder
 	maintenance</title>
 
       <para>There are three programs which are primarily just for
 	manipulating your folders. The <command>folder</command> program is
 	used to switch between folders, pack them, and list them. At
 	its simplest level you can do a <command>folder
 	+<replaceable>newfolder</replaceable></command> and you will be switched into
 	<replaceable>newfolder</replaceable>. From there on out all your MH
 	commands like <command>comp</command>, <command>repl</command>,
 	<command>scan</command>, and <command>show</command> will act on that
 	<command>newfolder</command> folder.</para>
 
       <para>Sometimes when you are reading and deleting messages you
 	will develop <quote>holes</quote> in your folders. If you do a
 	<command>scan</command> you might just see messages 34, 35, 36, 43,
 	55, 56, 57, 80. If you do a <command>folder -pack</command>
 	this will renumber all your messages so that there are no
 	holes. It doesn't actually delete any messages though. So you
 	may need to periodically go through and physically delete
 	<command>rmm</command>'d messages.</para>
 
       <para>If you need statistics on your folders you can do a
 	<command>folders</command> or <command>folder -all</command> to list
 	all your folders, how many messages they have, what the
 	current message is in each one and so on. This line of stats
 	it displays for all your folders is the same one you get when
 	you change to a folder with <command>folder +foldername</command>. A
 	<command>folders</command> command looks like this:</para>
 
       <informalexample>
 	<screen>                Folder      # of messages (  range  ); cur  msg  (other files)
               announce  has    1 message  (   1-   1).
                 drafts  has   no messages.
              f-hackers  has   43 messages (   1-  43).
            f-questions  has   16 messages (   1-  16).
                  inbox+ has   35 messages (   1-  38); cur=  37.
                  lists  has    8 messages (   1-   8).
              netfuture  has    1 message  (   1-   1).
                    out  has   31 messages (   1-  31).
               personal  has    6 messages (   1-   6).
                   todo  has   58 messages (   1-  58); cur=   1.
 
                      TOTAL=  199 messages in 13 folders.</screen>
       </informalexample>
   
       <para>The <command>refile</command> command is what you use to move
 	messages between folders. When you do something like
 	<command>refile 23 +netfuture</command> message number 23 is moved
 	into the <filename>netfuture</filename> folder. You could also do
 	something like <command>refile 23 +netfuture/latest</command> which
 	would put message number 23 in a subfolder called
 	<filename>latest</filename> under the <filename>netfuture</filename> folder.
 	If you want to keep a message in the current folder and link
 	it you can do a <command>refile -link 23 +netfuture</command>
 	which would keep 23 in your current <filename>inbox</filename> but
 	also list in your <filename>netfuture</filename> folder. You are
 	probably beginning to realize some of the really powerful
 	things you can do with MH.</para>
     </sect2>
   </sect1>
 
   <sect1>
     <title>Sending Mail</title>
 
     <para>Email is a two way street for most people so you want to be
       able to send something back. The way MH handles sending mail can
       be a bit difficult to follow at first, but it allows for
       incredible flexibility. The first thing MH does is to copy a
       components file into your outgoing email. A components file is
       basically a skeleton email letter with stuff like the To: and
       Subject: headers already in it.  You are then sent into your
       editor where you fill in the header information and then type
       the body of your message below the dashed lines in the message.
       Then to the <command>whatnow</command> program. When you are at the
       <prompt>What now?</prompt> prompt you can tell it to
       <command>send</command>, <command>list</command>, <command>edit</command>,
       <command>edit</command>, <command>push</command>, and <command>quit</command>. Most
       of these commands are self-explanatory. So the message sending
       process involves copying a component file, editing your email,
       and then telling the <command>whatnow</command> program what to do with
       your email.</para>
 
     <sect2>
       <title><command>comp</command>, <command>forw</command>,
 	<command>reply</command>&mdash;compose, forward or reply to a message
 	to someone</title>
 
       <para>The <command>comp</command> program has a few useful command line
 	options. The most important one to know right now is the
 	<option>-editor</option> option. When MH is installed the
 	default editor is usually a program called
 	<command>prompter</command> which comes with MH. It's not a very
 	exciting editor and basically just gets the job done. So when
 	you go to compose a message to someone you might want to use
 	<command>comp -editor /usr/bin/vi</command> or <command>comp -editor
 	/usr/local/bin/pico</command> instead. Once you have run
 	<emphasis>comp</emphasis> you are in your editor and you see
 	something that looks like this:</para>
 
       <informalexample>
 	<screen>To:
 cc:
 Subject:
 --------</screen>
       </informalexample>
 
       <para>You need to put the person you are sending the mail to
 	after the <literal>To:</literal> line. It works the same way for the
 	other headers also, so you would need to put your subject
 	after the <literal>Subject:</literal> line. Then you would just put
 	the body of your message after the dashed lines. It may seem a
 	bit simplistic since a lot of email programs have special
 	requesters that ask you for this information but there really
 	isn't any point to that. Plus this really gives you excellent
 	flexibility.</para>
 
       <informalexample>
 	<screen>To:<userinput>freebsd-rave@FreeBSD.org</userinput>
 cc:
 Subject:<userinput>And on the 8th day God created the FreeBSD core team</userinput>
 --------
 <userinput>Wow this is an amazing operating system. Thanks!</userinput></screen>
       </informalexample>
 
       <para>You can now save this message and exit your editor. You
 	will see the <prompt>What now?</prompt> prompt and you can type in
 	<userinput>send</userinput> or <userinput>s</userinput> and hit
 	<keycap>return</keycap>. Then the FreeBSD core team will receive
 	their just rewards. As I mentioned earlier you can also use
 	other commands, for example <command>quit</command> if you don't want
 	to send the message.</para>
 
       <para>The <command>forw</command> command is stunningly similar. The
 	big difference being that the message you are forwarding is
 	automatically included in the outgoing message. When you run
 	<command>forw</command> it will forward your current message. You can
 	always tell it to forward something else by doing something
 	like <command>forw 23</command> and then message number 23 will be
 	put in your outgoing message instead of the current message.
 	Beyond those small differences <command>forw</command> functions
 	exactly the same as <command>comp</command>. You go through the exact
 	same message sending process.</para>
 
       <para>The <command>repl</command> command will reply to whatever your
 	current message is, unless you give it a different message to
 	reply to. <command>repl</command> will do its best to go ahead and
 	fill in some of the email headers already. So you will notice
 	that the <literal>To:</literal> header already has the address of the
 	recipient in there. Also the <literal>Subject:</literal> line will
 	already be filled in.  You then go about the normal message
 	composition process and you are done. One useful command line
 	option to know here is the <option>-cc</option> option. You
 	can use <parameter>all</parameter>, <parameter>to</parameter>, <parameter>cc</parameter>,
 	<parameter>me</parameter> after the <option>-cc</option> option to have
 	<command>repl</command> automatically add the various addresses to
 	the cc list in the message. You have probably noticed that the
 	original message isn't included. This is because most MH
 	setups are configured to do this from the start.</para>
     </sect2>
 
     <sect2>
       <title><filename>components</filename>, and
 	<filename>replcomps</filename>&mdash;components files for
 	<command>comp</command> and <command>repl</command></title>
 
       <para>The <filename>components</filename> file is usually in
 	<filename>/usr/local/lib/mh</filename>. You can copy that file
 	into your MH Mail directory and edit to contain what you want
 	it to contain. It is a fairly basic file. You have various
 	email headers at the top, a dashed line and then nothing. The
 	<command>comp</command> command just copies this
 	<filename>components</filename> file and then edits it. You can add
 	any kind of valid RFC822 header you want. For instance you
 	could have something like this in your <filename>components</filename>
 	file:</para>
 
       <informalexample>
 	<screen>To:
 Fcc: out
 Subject:
 X-Mailer: MH 6.8.3
 X-Home-Page: http://www.FreeBSD.org/
 -------</screen>
       </informalexample>
 
       <para>MH would then copy this components file and throw you into
 	your editor. The <filename>components</filename> file is fairly
 	simple.  If you wanted to have a signature on those messages
 	you would just put your signature in that
 	<filename>components</filename> file.</para>
 
       <para>The <filename>replcomps</filename> file is a bit more complex. The
 	default <filename>replcomps</filename> looks like this:</para>
 
       <informalexample>
 	<screen>%(lit)%(formataddr %&lt;{reply-to}%?{from}%?{sender}%?{return-path}%&gt;)\
 %&lt;(nonnull)%(void(width))%(putaddr To: )\n%&gt;\
 %(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\
 %&lt;(nonnull)%(void(width))%(putaddr cc: )\n%&gt;\
 %&lt;{fcc}Fcc: %{fcc}\n%&gt;\
 %&lt;{subject}Subject: Re: %{subject}\n%&gt;\
 %&lt;{date}In-reply-to: Your message of "\
 %&lt;(nodate{date})%{date}%|%(pretty{date})%&gt;."%&lt;{message-id}
              %{message-id}%&gt;\n%&gt;\
 --------</screen>
       </informalexample>
 
       <para>It's in the same basic format as the
 	<filename>components</filename> file but it contains quite a few extra
 	formatting codes. The <literal>%(lit)</literal> command makes room
 	for the address. The <literal>%(formataddr</literal> is a function
 	that returns a proper email address. The next part is
 	<literal>%&lt;</literal> which means if and the
 	<literal>{reply-to}</literal> means the reply-to field in the
 	original message. So that might be translated this way:</para>
 
       <informalexample>
 	<screen>%&lt;<emphasis remap=bf>if</emphasis> {reply-to} <emphasis remap=bf>the original message has a reply-to</emphasis> 
 then give that to formataddr, %? <emphasis remap=bf>else</emphasis> {from} <emphasis remap=bf>take the
 from address</emphasis>, %? <emphasis remap=bf>else</emphasis> {sender} <emphasis remap=bf>take the sender address</emphasis>, %?
 <emphasis remap=bf>else</emphasis> {return-path} <emphasis remap=bf>take the return-path from the original
 message</emphasis>, %&gt; <emphasis remap=bf>endif</emphasis>.</screen>
       </informalexample>
   
       <para>As you can tell MH formatting can get rather involved. You
 	can probably decipher what most of the other functions and
 	variables mean. All of the information on writing these format
 	strings is in the MH-Format man page. The really nice thing is
 	that once you have built your customized
 	<filename>replcomps</filename> file you won't need to touch it again.
 	No other email program really gives you the power and
 	flexibility that MH gives you.</para>
     </sect2>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/articles/multi-os/article.sgml b/en_US.ISO8859-1/articles/multi-os/article.sgml
index a5da9b13a9..c04c9ee501 100644
--- a/en_US.ISO8859-1/articles/multi-os/article.sgml
+++ b/en_US.ISO8859-1/articles/multi-os/article.sgml
@@ -1,740 +1,740 @@
-<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/multi-os/article.sgml,v 1.16 2001/07/10 14:00:14 dd Exp $ -->
+<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/multi-os/article.sgml,v 1.17 2001/07/11 13:24:45 nik Exp $ -->
 <!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN">
 <article>
   <articleinfo>
     <title>Installing and Using FreeBSD With Other Operating Systems</title>
 
     <authorgroup>
       <author>
 	<firstname>Jay</firstname>
 
 	<surname>Richmond</surname>
 
 	<affiliation>
 	  <address>
 	    <email>jayrich@sysc.com</email>
 	  </address>
 	</affiliation>
       </author>
     </authorgroup>
 
     <pubdate>6 August 1996</pubdate>
 
     <abstract>
       <para>This document discusses how to make FreeBSD coexist nicely
 	with other popular operating systems such as Linux, MS-DOS,
 	OS/2, and Windows 95.  Special thanks to: Annelise Anderson
 	<email>andrsn@stanford.edu</email>, Randall Hopper
 	<email>rhh@ct.picker.com</email>, and Jordan K. Hubbard
 	<email>jkh@time.cdrom.com</email></para>
     </abstract>
   </articleinfo>
 
   <sect1>
     <title>Overview</title>
 
     <para>Most people can't fit these operating systems together
       comfortably without having a larger hard disk, so special
       information on large EIDE drives is included.  Because there are
       so many combinations of possible operating systems and hard disk
       configurations, the <xref linkend="ch5"> section may be of the
       most use to you.  It contains descriptions of specific working
       computer setups that use multiple operating systems.</para>
 
     <para>This document assumes that you have already made room on
       your hard disk for an additional operating system.  Any time you
       repartition your hard drive, you run the risk of destroying the
       data on the original partitions.  However, if your hard drive is
       completely occupied by DOS, you might find the FIPS utility
-      (included on the FreeBSD CD-ROM in the
+      (included on the FreeBSD CDROM in the
       <filename>\TOOLS</filename> directory or via <ulink
 	URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools">ftp</ulink>)
       useful.  It lets you repartition your hard disk without
       destroying the data already on it.  There is also a commercial
       program available called Partition Magic, which lets you size
       and delete partitions without consequence.</para>
   </sect1>
 
   <sect1 id="ch2">
     <title>Overview of Boot Managers</title>
 
     <para>These are just brief descriptions of some of the different
       boot managers you may encounter.  Depending on your computer
       setup, you may find it useful to use more than one of them on
       the same system.</para>
 
     <variablelist>
       <varlistentry>
 	<term>Boot Easy</term>
 
 	<listitem>
 	  <para>This is the default boot manager used with FreeBSD.
 	    It has the ability to boot most anything, including BSD,
 	    OS/2 (HPFS), Windows 95 (FAT and FAT32), and Linux.
 	    Partitions are selected with the function keys.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>OS/2 Boot Manager</term>
 
 	<listitem>
 	  <para>This will boot FAT, HPFS, FFS (FreeBSD), and EXT2
 	    (Linux).  It will also boot FAT32 partitions.  Partitions
 	    are selected using arrow keys.  The OS/2 Boot Manager is
 	    the only one to use its own separate partition, unlike the
 	    others which use the master boot record (MBR).  Therefore,
 	    it must be installed below the 1024th cylinder to avoid
 	    booting problems.  It can boot Linux using LILO when it is
 	    part of the boot sector, not the MBR.  Go to <ulink
 	      URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux
 	      HOWTOs</ulink> on the World Wide Web for more
 	    information on booting Linux with OS/2's boot
 	    manager.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>OS-BS</term>
 
 	<listitem>
 	  <para>This is an alternative to Boot Easy.  It gives you more
 	    control over the booting process, with the ability to set
 	    the default partition to boot and the booting timeout.
 	    The beta version of this programs allows you to boot by
 	    selecting the OS with your arrow keys.  It is included on
 	    the FreeBSD CD in the <filename>\TOOLS</filename>
 	    directory, and via <ulink
 	      URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools">ftp</ulink>.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>LILO, or LInux LOader</term>
 
 	<listitem>
 	  <para>This is a limited boot manager.  It will boot FreeBSD,
 	    though some customization work is required in the LILO
 	    configuration file.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <note id="fat32">
       <title>About FAT32</title>
 
       <para>FAT32 is the replacement to the FAT filesystem included in
 	Microsoft's OEM SR2 Beta release, which is expected to be
 	utilized on computers pre-loaded with Windows 95 towards the
 	end of 1996.  It converts the normal FAT file system and
 	allows you to use smaller cluster sizes for larger hard
 	drives.  FAT32 also modifies the traditional FAT boot sector
 	and allocation table, making it incompatible with some boot
 	managers.</para>
     </note>
   </sect1>
 
   <sect1 id="ch3">
     <title>A Typical Installation</title>
 
     <para>Let's say I have two large EIDE hard drives, and I want to
       install FreeBSD, Linux, and Windows 95 on them.</para>
 
     <para>Here's how I might do it using these hard disks:</para>
 
     <itemizedlist>
       <listitem>
 	<para><filename>/dev/wd0</filename> (first physical hard disk)</para>
       </listitem>
 
       <listitem>
 	<para><filename>/dev/wd1</filename> (second hard disk)</para>
       </listitem>
     </itemizedlist>
 
     <para>Both disks have 1416 cylinders.</para>
 
     <procedure>
       <step>
 	<para>I boot from a MS-DOS or Windows 95 boot disk that
 	  contains the <filename>FDISK.EXE</filename> utility and make a small
 	  50 meg primary partition (35-40 for Windows 95, plus a
 	  little breathing room) on the first disk.  Also create a
 	  larger partition on the second hard disk for my Windows
 	  applications and data.</para>
 	</step>
 
       <step>
 	<para>I reboot and install Windows 95 (easier said than done)
 	  on the <filename>C:</filename> partition.</para>
       </step>
 
       <step>
 	<para>The next thing I do is install Linux.  I'm not sure
 	  about all the distributions of Linux, but slackware includes
 	  LILO (see <xref linkend="ch2">).  When I am partitioning out
 	  my hard disk with Linux <command>fdisk</command>, I would
 	  put all of Linux on the first drive (maybe 300 megs for a
 	  nice root partition and some swap space).</para>
       </step>
 
       <step>
 	<para>After I install Linux, and are prompted about installing
 	  LILO, make SURE that I install it on the boot sector of my
 	  root Linux partition, not in the MBR (master boot
 	  record).</para>
       </step>
 
       <step>
 	<para>The remaining hard disk space can go to FreeBSD.  I also
 	  make sure that my FreeBSD root slice does not go beyond the
 	  1024th cylinder.  (The 1024th cylinder is 528 megs into the
 	  disk with our hypothetical 720MB disks).  I will use the
 	  rest of the hard drive (about 270 megs) for the
 	  <filename>/usr</filename> and <filename>/</filename> slices if I wish.  The
 	  rest of the second hard disk (size depends on the amount of
 	  my Windows application/data partition that I created in step
 	  1 can go to the <filename>/usr/src</filename> slice and swap
 	  space.</para>
       </step>
 
       <step>
 	<para>When viewed with the Windows 95 <command>fdisk</command>
 	  utility, my hard drives should now look something like this:
 
 	  <screen>---------------------------------------------------------------------
 
                   Display Partition Information
 
 Current fixed disk drive: 1
 
 Partition  Status  Type  Volume_Label  Mbytes  System  Usage
 C: 1          A   PRI DOS                50    FAT**     7%
    2          A   Non-DOS (Linux)       300             43%
 
 Total disk space is  696 Mbytes (1 Mbyte = 1048576 bytes)
 
 Press Esc to continue
 
 ---------------------------------------------------------------------
 
                   Display Partition Information
 
 Current fixed disk drive: 2
 
 Partition  Status  Type  Volume_Label  Mbytes  System  Usage
 D: 1          A   PRI DOS                420   FAT**    60%
 
 Total disk space is  696 Mbytes (1 Mbyte = 1048576 bytes)
 
 Press Esc to continue
 
 ---------------------------------------------------------------------</screen>
 	  ** May say FAT16 or FAT32 if you are using the OEM SR2
 	  update.  See <xref linkend="ch2">).</para>
       </step>
 
       <step>
 	<para>Install FreeBSD.  I make sure to boot with my first hard
 	  disk set at <quote>NORMAL</quote> in the BIOS.  If it is not,
 	  I'll have the enter my true disk geometry at boot time (to
 	  get this, boot Windows 95 and consult Microsoft Diagnostics
 	  (<filename>MSD.EXE</filename>), or check your BIOS) with the
 	  parameter <literal>hd0=1416,16,63</literal> where
 	  <replaceable>1416</replaceable> is the number of cylinders on my hard
 	  disk, <replaceable>16</replaceable> is the number of heads per track,
 	  and <replaceable>63</replaceable> is the number of sectors per track on
 	  the drive.</para>
       </step>
 
       <step>
 	<para>When partitioning out the hard disk, I make sure to
 	  install Boot Easy on the first disk.  I don't worry about
 	  the second disk, nothing is booting off of it.</para>
       </step>
 
       <step>
 	<para>When I reboot, Boot Easy should recognize my three
 	  bootable partitions as DOS (Windows 95), Linux, and BSD
 	  (FreeBSD).</para>
       </step>
     </procedure>
   </sect1>
 
   <sect1 id="ch4">
     <title>Special Considerations</title>
 
     <para>Most operating systems are very picky about where and how
       they are placed on the hard disk.  Windows 95 and DOS need to be
       on the first primary partition on the first hard disk.  OS/2 is
       the exception.  It can be installed on the first or second disk
       in a primary or extended partition.  If you are not sure, keep
       the beginning of the bootable partitions below the 1024th
       cylinder.</para>
 
     <para>If you install Windows 95 on an existing BSD system, it will
       <quote>destroy</quote> the MBR, and you will have to reinstall your
       previous boot manager.  Boot Easy can be reinstalled by using
       the BOOTINST.EXE utility included in the \TOOLS directory on the
-      CD-ROM, and via <ulink
+      CDROM, and via <ulink
 	URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools">ftp</ulink>.
       You can also re-start the installation process and go to the
       partition editor.  From there, mark the FreeBSD partition as
       bootable, select Boot Manager, and then type W to (W)rite out
       the information to the MBR.  You can now reboot, and Boot Easy
       should then recognize Windows 95 as DOS.</para>
 
     <para>Please keep in mind that OS/2 can read FAT and HPFS
       partitions, but not FFS (FreeBSD) or EXT2 (Linux) partitions.
       Likewise, Windows 95 can only read and write to FAT and FAT32
       (see <xref linkend="ch2">) partitions.  FreeBSD can read most
       file systems, but currently cannot read HPFS partitions.  Linux
       can read HPFS partitions, but can't write to them.  Recent
       versions of the Linux kernel (2.x) can read and write to Windows
       95 VFAT partitions (VFAT is what gives Windows 95 long file
       names - it's pretty much the same as FAT).  Linux can read and
       write to most file systems.  Got that?  I hope so.</para>
   </sect1>
 
   <sect1 id="ch5">
     <title>Examples</title>
 
     <para><emphasis>(section needs work, please send your example to
 	<email>jayrich@sysc.com</email>)</emphasis>.</para>
 
     <para>FreeBSD+Win95:  If you installed FreeBSD after Windows 95,
       you should see <literal>DOS</literal> on the Boot Easy menu.  This is
       Windows 95.  If you installed Windows 95 after FreeBSD, read
       <xref linkend="ch4"> above.  As long as your hard disk does not
       have 1024 cylinders you should not have a problem booting.  If
       one of your partitions goes beyond the 1024th cylinder however,
       and you get messages like <errorname>invalid system disk</errorname>
       under DOS (Windows 95) and FreeBSD will not boot, try looking
       for a setting in your BIOS called <quote>&gt; 1024 cylinder
 	support</quote> or <quote>NORMAL/LBA</quote> mode.  DOS may need LBA
       (Logical Block Addressing) in order to boot correctly.  If the
       idea of switching BIOS settings every time you boot up doesn't
       appeal to you, you can boot FreeBSD through DOS via the
       <filename>FBSDBOOT.EXE</filename> utility on the CD (It should find your
       FreeBSD partition and boot it.)</para>
 
     <para>FreeBSD+OS/2+Win95:  Nothing new here.  OS/2's boot manger
       can boot all of these operating systems, so that shouldn't be a
       problem.</para>
 
     <para>FreeBSD+Linux: You can also use Boot Easy to boot both
       operating systems.</para>
 
     <para>FreeBSD+Linux+Win95:  (see <xref linkend="ch3">)</para>
   </sect1>
 
   <sect1 id="sources">
     <title>Other Sources of Help</title>
 
     <para>There are many <ulink
 	URL="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux
 	HOW-TOs</ulink> that deal with multiple operating systems on
       the same hard disk.</para>
 
     <para>The <ulink
 	URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+DOS+Win95+OS2.html">Linux+DOS+Win95+OS2
 	mini-HOWTO</ulink> offers help on configuring the OS/2 boot
       manager, and the <ulink
 	URL="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+FreeBSD.html">Linux+FreeBSD
 	mini-HOWTO</ulink> might be interesting as well.  The <ulink
 	URL="http://www.in.net/~jkatz/win95/Linux-HOWTO.html">Linux-HOWTO</ulink>
       is also helpful.</para>
 
     <para>The <ulink
 	URL="http://www.dorsai.org/~dcl/publications/NTLDR_Hacking">NT
 	Loader Hacking Guide</ulink> provides good information on
       multibooting Windows NT, '95, and DOS with other operating
       systems.</para>
 
     <para>And Hale Landis's "How It Works" document pack contains some
       good info on all sorts of disk geometry and booting related
       topics.  You can find it at
       <ulink
 	URL="ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip">ftp://fission.dt.wdc.com/pub/otherdocs/pc_systems/how_it_works/allhiw.zip</ulink>.</para>
 
     <para>Finally, don't overlook FreeBSD's kernel documentation on
       the booting procedure, available in the kernel source
       distribution (it unpacks to <ulink
 	URL="file:/usr/src/sys/i386/boot/biosboot/README.386BSD">file:/usr/src/sys/i386/boot/biosboot/README.386BSD</ulink>.</para>
   </sect1>
 
   <sect1>
     <title>Technical Details</title>
 
     <para><emphasis>(Contributed by Randall Hopper,
 	<email>rhh@ct.picker.com</email>)</emphasis></para>
 
     <para>This section attempts to give you enough basic information
       about your hard disks and the disk booting process so that you
       can troubleshoot most problems you might encounter when getting
       set up to boot several operating systems.  It starts in pretty
       basic terms, so you may want to skim down in this section until
       it begins to look unfamiliar and then start reading.</para>
 
     <sect2>
       <title>Disk Primer</title>
 
       <para>Three fundamental terms are used to describe the location
 	of data on your hard disk: Cylinders, Heads, and Sectors.
 	It's not particularly important to know what these terms
 	relate to except to know that, together, they identify where
 	data is physically on your disk.</para>
 
       <para>Your disk has a particular number of cylinders, number of
 	heads, and number of sectors per cylinder-head (a
 	cylinder-head also known nown as a track).  Collectively this
 	information defines the "physical disk geometry" for your hard
 	disk.  There are typically 512 bytes per sector, and 63
 	sectors per track, with the number of cylinders and heads
 	varying widely from disk to disk.  Thus you can figure the
 	number of bytes of data that'll fit on your own disk by
 	calculating:</para>
 
 	<informalexample>
 	  <para>(# of cylinders) &times; (# heads) &times; (63
 	    sectors/track) &times; (512 bytes/sect)</para>
 	</informalexample>
 
       <para>For example, on my 1.6 Gig Western Digital AC31600 EIDE hard
 	disk,that's:</para>
 
 	<informalexample>
 	  <para>(3148 cyl) &times; (16 heads) &times; (63
 	    sectors/track) &times (512 bytes/sect)</para>
 	</informalexample>
 
       <para>which is 1,624,670,208 bytes, or around 1.6 Gig.</para>
 
       <para>You can find out the physical disk geometry (number of
 	cylinders, heads, and sectors/track counts) for your hard
 	disks using ATAID or other programs off the net.  Your hard
 	disk probably came with this information as well.  Be careful
 	though: if you're using BIOS LBA (see <xref
 	  linkend="limits">), you can't use just any program to get
 	the physical geometry.  This is because many programs (e.g.
 	<filename>MSD.EXE</filename> or FreeBSD fdisk) don't identify the
 	physical disk geometry; they instead report the
 	<firstterm>translated geometry</firstterm> (virtual numbers from using
 	LBA).  Stay tuned for what that means.</para>
 
       <para>One other useful thing about these terms.  Given 3
 	numbers&mdash;a cylinder number, a head number, and a
 	sector-within-track number&mdash;you identify a specific
 	absolute sector (a 512 byte block of data) on your disk.
 	Cylinders and Heads are numbered up from 0, and Sectors are
 	numbered up from 1.</para>
 
       <para>For those that are interested in more technical details,
 	information on disk geometry, boot sectors, BIOSes, etc. can
 	be found all over the net.  Query Lycos, Yahoo, etc. for
 	<literal>boot sector</literal> or <literal>master boot record</literal>.
 	Among the useful info you'll find are Hale Landis's
 	<citetitle>How It Works</citetitle> document pack.  See the <xref
 	  linkend="sources"> section for a few pointers to this
 	pack.</para>
 
       <para>Ok, enough terminology.  We're talking about booting
 	here.</para>
     </sect2>
 
     <sect2 id="booting">
       <title>The Booting Process</title>
 
       <para>On the first sector of your disk (Cyl 0, Head 0, Sector 1)
 	lives the Master Boot Record (MBR).  It contains a map of your
 	disk.  It identifies up to 4 <firstterm>partitions</firstterm>, each of
 	which is a contiguous chunk of that disk.  FreeBSD calls
 	partitions <firstterm>slices</firstterm> to avoid confusion with it's
 	own partitions, but we won't do that here.  Each partition can
 	contain its own operating system.</para>
 
       <para>Each partition entry in the MBR has a <firstterm>Partition
 	  ID</firstterm>, a <firstterm>Start Cylinder/Head/Sector</firstterm>, and an
 	<firstterm>End Cylinder/Head/Sector</firstterm>.  The Partition ID
 	tells what type of partition it is (what OS) and the Start/End
 	tells where it is.  <xref linkend="tbl-pid"> lists a
 	smattering of some common Partition IDs.</para>
 
       <table id="tbl-pid">
 	<title>Partition IDs</title>
 
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>ID (hex)</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>01</entry>
 	      <entry>Primary DOS12 (12-bit FAT)</entry>
 	    </row>
 
 	    <row>
 	      <entry>04</entry>
 	      <entry>Primary DOS16 (16-bit FAT)</entry>
 	    </row>
 
 	    <row>
 	      <entry>05</entry>
 	      <entry>Extended DOS</entry>
 	    </row>
 
 	    <row>
 	      <entry>06</entry>
 	      <entry>Primary big DOS (&gt; 32MB)</entry>
 	    </row>
 
 	    <row>
 	      <entry>0A</entry>
 	      <entry>OS/2</entry>
 	    </row>
 
 	    <row>
 	      <entry>83</entry>
 	      <entry>Linux (EXT2FS)</entry>
 	    </row>
 
 	    <row>
 	      <entry>A5</entry>
 	      <entry>FreeBSD, NetBSD, 386BSD (UFS)</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
       <para>Note that not all partitions are bootable (e.g. Extended
 	DOS).  Some are&mdash;some aren't.  What makes a partition
 	bootable is the configuration of the <firstterm>Partition Boot
 	  Sector</firstterm> that exists at the beginning of each
 	partition.</para>
 
       <para>When you configure your favorite boot manager, it looks up
 	the entries in the MBR partition tables of all your hard disks
 	and lets you name the entries in that list.  Then when you
 	boot, the boot manager is invoked by special code in the
 	Master Boot Sector of the first probed hard disk on your
 	system.  It looks at the MBR partition table entry
 	corresponding to the partition choice you made, uses the Start
 	Cylinder/Head/Sector information for that partition, loads up
 	the Partition Boot Sector for that partition, and gives it
 	control.  That Boot Sector for the partition itself contains
 	enough information to start loading the operating system on
 	that partition.</para>
 
       <para>One thing we just brushed past that's important to know.
 	All of your hard disks have MBRs.  However, the one that's
 	important is the one on the disk that's first probed by the
 	BIOS.  If you have only IDE hard disks, its the first IDE disk
 	(e.g. primary disk on first controller).  Similarly for SCSI
 	only systems.  If you have both IDE and SCSI hard disks
 	though, the IDE disk is typically probed first by the BIOS, so
 	the first IDE disk is the first probed disk.  The boot manager
 	you will install will be hooked into the MBR on this first
 	probed hard disk that we've just described.</para>
     </sect2>
 
     <sect2 id="limits">
       <title>Booting Limitations and Warnings</title>
 
       <para>Now the interesting stuff that you need to watch out
 	for.</para>
 
       <sect3>
 	<title>The dreaded 1024 cylinder limit and how BIOS LBA helps</title>
 
 	<para>The first part of the booting process is all done
 	  through the BIOS, (if that's a new term to you, the BIOS is
 	  a software chip on your system motherboard which provides
 	  startup code for your computer).  As such, this first part
 	  of the process is subject to the limitations of the BIOS
 	  interface.</para>
 
 	<para>The BIOS interface used to read the hard disk during
 	  this period (INT 13H, Subfunction 2) allocates 10 bits to
 	  the Cylinder Number, 8 bits to the Head Number, and 6 bits
 	  to the Sector Number.  This restricts users of this
 	  interface (i.e. boot managers hooked into your disk's MBR as
 	  well as OS loaders hooked into the Boot Sectors) to the
 	  following limits:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>1024 cylinders, max</para>
 	</listitem>
 
 	<listitem>
 	  <para>256 heads, max</para>
 	</listitem>
 
 	<listitem>
 	  <para>64 sectors/track, max (actually 63, <literal>0</literal>
 	    isn't available)</para>
 	</listitem>
       </itemizedlist>
 
 	<para>Now big hard disks have lots of cylinders but not a lot
 	  of heads, so invariably with big hard disks the number of
 	  cylinders is greater than 1024.  Given this and the BIOS
 	  interface as is, you can't boot off just anywhere on your
 	  hard disk.  The boot code (the boot manager and the OS
 	  loader hooked into all bootable partitions' Boot Sectors)
 	  has to reside below cylinder 1024.  In fact, if your hard
 	  disk is typical and has 16 heads, this equates to:</para>
 
 	<informalexample>
 	  <para>1024 cyl/disk &times; 16 heads/disk &times; 63
 	    sect/(cyl-head) &times; 512 bytes/sector</para>
 	</informalexample>
 
 	<para>which is around the often-mentioned 528MB limit.</para>
 
 	<para>This is where BIOS LBA (Logical Block Addressing) comes
 	  in.  BIOS LBA gives the user of the BIOS API calls access to
 	  physical cylinders above 1024 though the BIOS interfaces by
 	  redefining a cylinder.  That is, it remaps your cylinders
 	  and heads, making it appear through the BIOS as though the
 	  disk has fewer cylinders and more heads than it actually
 	  does.  In other words, it takes advantage of the fact that
 	  hard disks have relatively few heads and lots of cylinders
 	  by shifting the balance between number of cylinders and
 	  number of heads so that both numbers lie below the
 	  above-mentioned limits (1024 cylinders, 256 heads).</para>
 
 	<para>With BIOS LBA, the hard disk size limitation is
 	  virtually removed (well, pushed up to 8 Gigabytes anyway).
 	  If you have an LBA BIOS, you can put FreeBSD or any OS
 	  anywhere you want and not hit the 1024 cylinder
 	  limit.</para>
 
 	<para>To use my 1.6 Gig Western Digital as an example again,
 	  it's physical geometry is:</para>
 
 	<informalexample>
 	  <para>(3148 cyl, 16 heads, 63 sectors/track, 512
 	    bytes/sector)</para>
 	</informalexample>
 
 	<para>However, my BIOS LBA remaps this to:</para>
 
 	<informalexample>
 	  <para>(787 cyl, 64 heads, 63 sectors/track, 512
 	    bytes/sector)</para>
 	</informalexample>
 
 	<para>giving the same effective size disk, but with cylinder
 	  and head counts within the BIOS API's range (Incidentally, I
 	  have both Linux and FreeBSD existing on one of my hard disks
 	  above the 1024th physical cylinder, and both operating
 	  systems boot fine, thanks to BIOS LBA).</para>
       </sect3>
 
       <sect3>
 	<title>Boot Managers and Disk Allocation</title>
 
 	<para>Another gotcha to watch out when installing boot
 	  managers is allocating space for your boot manager.  It's
 	  best to be aware of this issue up front to save yourself
 	  from having to reinstall one or more of your OSs.</para>
 
 	<para>If you followed the discussion in <xref
 	    linkend="booting"> about the Master Boot Sector (where the
 	  MBR is), Partition Boot Sectors, and the booting process,
 	  you may have been wondering just exactly where on your hard
 	  disk that nifty boot manager is going to live.  Well, some
 	  boot managers are small enough to fit entirely within the
 	  Master Boot Sector (Cylinder 0, Head 0, Sector 0) along with
 	  the partition table.  Others need a bit more room and
 	  actually extend a few sectors past the Master Boot Sector in
 	  the Cylinder 0 Head 0 track, since that's typically
 	  free&hellip;typically.</para>
 
 	<para>That's the catch.  Some operating systems (FreeBSD
 	  included) let you start their partitions right after the
 	  Master Boot Sector at Cylinder 0, Head 0, Sector 2 if you
 	  want.  In fact, if you give FreeBSD's sysinstall a disk with
 	  an empty chunk up front or the whole disk empty, that's
 	  where it'll start the FreeBSD partition by default (at least
 	  it did when I fell into this trap).  Then when you go to
 	  install your boot manager, if it's one that occupies a few
 	  extra sectors after the MBR, it'll overwrite the front of
 	  the first partition's data.  In the case of FreeBSD, this
 	  overwrites the disk label, and renders your FreeBSD
 	  partition unbootable.</para>
 
 	<para>The easy way to avoid this problem (and leave yourself
 	  the flexibility to try different boot managers later) is
 	  just to always leave the first full track on your disk
 	  unallocated when you partition your disk.  That is, leave
 	  the space from Cylinder 0, Head 0, Sector 2 through Cylinder
 	  0, Head 0, Sector 63 unallocated, and start your first
 	  partition at Cylinder 0, Head 1, Sector 1.  For what it's
 	  worth, when you create a DOS partition at the front of your
 	  disk, DOS leaves this space open by default (this is why
 	  some boot managers assume it's free).  So creating a DOS
 	  partition up at the front of your disk avoids this problem
 	  altogether.  I like to do this myself, creating 1 Meg DOS
 	  partition up front, because it also avoids my primary DOS
 	  drive letters shifting later when I repartition.</para>
 
 	<para>For reference, the following boot managers use the
 	  Master Boot Sector to store their code and data:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>OS-BS 1.35</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Boot Easy</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>LILO</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>These boot managers use a few additional sectors after
 	  the Master Boot Sector:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>OS-BS 2.0 Beta 8 (sectors 2-5)</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>OS/2's boot manager</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>What if your machine won't boot?</title>
 
 	<para>At some point when installing boot managers, you might
 	  leave the MBR in a state such that your machine won't boot.
 	  This is unlikely, but possible when re-FDISKing underneath
 	  an already-installed boot manager.</para>
 
 	<para>If you have a bootable DOS partition on your disk, you
 	  can boot off a DOS floppy, and run:</para>
 
 	<informalexample>
 	  <screen>A:\> <userinput>FDISK /MBR</userinput></screen>
 	</informalexample>
 
 	<para>to put the original, simple DOS boot code back into the
 	  system.  You can then boot DOS (and DOS only) off the hard
 	  drive.  Alternatively, just re-run your boot manager
 	  installation program off a bootable floppy.</para>
       </sect3>
     </sect2>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/articles/new-users/article.sgml b/en_US.ISO8859-1/articles/new-users/article.sgml
index 90bccba82d..dbff31d29d 100644
--- a/en_US.ISO8859-1/articles/new-users/article.sgml
+++ b/en_US.ISO8859-1/articles/new-users/article.sgml
@@ -1,1034 +1,1034 @@
-<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/new-users/article.sgml,v 1.19 2001/06/23 06:56:59 dd Exp $ -->
+<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/new-users/article.sgml,v 1.20 2001/07/06 13:02:50 dd Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN">
 <article>
   <articleinfo>
     <title>For People New to Both FreeBSD and Unix</title>
 
     <authorgroup>
       <author>
 	<firstname>Annelise</firstname>
 
 	<surname>Anderson</surname>
 
 	<affiliation>
 	  <address><email>andrsn@andrsn.stanford.edu</email></address>
 	</affiliation>
       </author>
     </authorgroup>
 
     <pubdate>August 15, 1997</pubdate>
 
     <abstract>
       <para>Congratulations on installing FreeBSD! This introduction
 	is for people new to both FreeBSD <emphasis>and</emphasis>
 	Un*x&mdash;so it starts with basics.  It assumes you're using
 	version 2.0.5 or later of FreeBSD as distributed by BSDi
 	or FreeBSD.org, your system (for now) has a single user
 	(you)&mdash;and you're probably pretty good with DOS/Windows
 	or OS/2.</para>
     </abstract>
   </articleinfo>
 
   <sect1>
     <title>Logging in and Getting Out</title>
 
     <para>Log in (when you see <prompt
 	>login:</prompt>) as a user you created during
       installation or as <firstterm>root</firstterm>.  (Your FreeBSD
       installation will already have an account for root; root can go
       anywhere and do anything, including deleting essential files, so
       be careful!) The symbols &prompt.user; and &prompt.root; in the following stand for the
       prompt (yours may be different), with &prompt.user; indicating an ordinary
       user and &prompt.root; indicating root.</para>
 
     <para>To log out (and get a new <prompt
 	>login:</prompt> prompt) type</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>exit</userinput></screen>
     </informalexample>
 
     <para>as often as necessary.  Yes, press <keysym>enter</keysym>
       after commands, and remember that Unix is
       case-sensitive&mdash;<command>exit</command>, not
       <command>EXIT</command>.</para>
 
     <para>To shut down the machine type</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>/sbin/shutdown -h now</userinput></screen>
     </informalexample>
 
     <para>Or to reboot type</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>/sbin/shutdown -r now</userinput></screen>
     </informalexample>
 
     <para>or</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>/sbin/reboot</userinput></screen>
     </informalexample>
 
     <para>You can also reboot with
       <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo>.
       Give it a little time to do its work.  This is equivalent to
       <command>/sbin/reboot</command> in recent releases of FreeBSD
       and is much, much better than hitting the reset button.  You
       don't want to have to reinstall this thing, do you?</para>
   </sect1>
 
   <sect1>
     <title>Adding A User with Root Privileges</title>
 
     <para>If you didn't create any users when you installed the system
       and are thus logged in as root, you should probably create a
       user now with</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>adduser</userinput></screen>
     </informalexample>
 
     <para>The first time you use adduser, it might ask for some
       defaults to save.  You might want to make the default shell csh
       instead of sh, if it suggests sh as the default.  Otherwise just
       press enter to accept each default.  These defaults are saved in
       <filename>/etc/adduser.conf</filename>, an editable file.</para>
 
     <para>Suppose you create a user <emphasis>jack</emphasis> with
       full name <emphasis>Jack Benimble</emphasis>.  Give jack a
       password if security (even kids around who might pound on the
       keyboard) is an issue.  When it asks you if you want to invite
       jack into other groups, type <userinput>wheel</userinput></para>
 
     <informalexample>
       <screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput></screen>
     </informalexample>
 
     <para>This will make it possible to log in as
       <emphasis>jack</emphasis> and use the <command>su</command>
       command to become root.  Then you won't get scolded any more for
       logging in as root.</para>
 
     <para>You can quit <command>adduser</command> any time by typing
       <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>,
       and at the end you'll have a chance to approve your new user or
       simply type <keycap>n</keycap> for no.  You might want to create
       a second new user (jill?) so that when you edit jack's login
       files, you'll have a hot spare in case something goes
       wrong.</para>
 
     <para>Once you've done this, use <command>exit</command> to get
       back to a login prompt and log in as <emphasis>jack</emphasis>.
       In general, it's a good idea to do as much work as possible as
       an ordinary user who doesn't have the power&mdash;and
       risk&mdash;of root.</para>
 
     <para>If you already created a user and you want the user to be
       able to <command>su</command> to root, you can log in as root
       and edit the file <filename>/etc/group</filename>, adding jack
       to the first line (the group wheel).  But first you need to
       practice <command>vi</command>, the text editor--or use the
       simpler text editor, <command>ee</command>, installed on recent
       version of FreeBSD.</para>
 
     <para>To delete a user, use the <command>rmuser</command>
       command.</para>
   </sect1>
 
   <sect1>
     <title>Looking Around</title>
 
     <para>Logged in as an ordinary user, look around and try out some
       commands that will access the sources of help and information
       within FreeBSD.</para>
 
     <para>Here are some commands and what they do:</para>
 
     <variablelist>
       <varlistentry>
 	<term><command>id</command></term>
 
 	<listitem>
 	  <para>Tells you who you are!</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>pwd</command></term>
 
 	<listitem>
 	  <para>Shows you where you are&mdash;the current working
 	    directory.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>ls</command></term>
 
 	<listitem>
 	  <para>Lists the files in the current directory.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>ls <option>-F</option></command></term>
 
 	<listitem>
 	  <para>Lists the files in the current directory with a
 	    <literal>*</literal> after executables, a
 	    <literal>/</literal> after directories, and an
 	    <literal>@</literal> after symbolic links.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>ls <option>-l</option></command></term>
 
 	<listitem>
 	  <para>Lists the files in long format&mdash;size, date,
 	    permissions.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>ls <option>-a</option></command></term>
 
 	<listitem>
 	  <para>Lists hidden <quote>dot</quote> files with the others.
 	    If you're root, the <quote>dot</quote> files show up
 	    without the <option>-a</option> switch.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>cd</command></term>
 
 	<listitem>
 	  <para>Changes directories.  <command>cd
 	      <parameter>..</parameter></command> backs up one level;
 	    note the space after <command>cd</command>.  <command>cd
 	      <parameter>/usr/local</parameter></command> goes there.
 	    <command>cd <parameter>~</parameter></command> goes to
 	    the home directory of the person logged in&mdash;e.g.,
 	    <filename>/usr/home/jack</filename>.  Try <command>cd
 	      <parameter>/cdrom</parameter></command>, and then
 	    <command>ls</command>, to find out if your CDROM is
 	    mounted and working.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>view
 	    <replaceable>filename</replaceable></command></term>
 
 	<listitem>
 	  <para>Lets you look at a file (named
 	    <replaceable>filename</replaceable>) without changing it.
 	    Try <command>view
 	    <parameter>/etc/fstab</parameter></command>.
 	    <command>:q</command> to quit.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>cat
 	    <replaceable>filename</replaceable></command></term>
 
 	<listitem>
 	  <para>Displays <replaceable>filename</replaceable> on
 	    screen.  If it's too long and you can see only the end of
 	    it, press <keycap>ScrollLock</keycap> and use the
 	    <keycap>up-arrow</keycap> to move backward; you can use
 	    <keycap>ScrollLock</keycap> with man pages too.  Press
 	    <keycap>ScrollLock</keycap> again to quit scrolling.  You
 	    might want to try <command>cat</command> on some of the
 	    dot files in your home directory&mdash;<command>cat
 	      <parameter>.cshrc</parameter></command>, <command>cat
 	      <parameter>.login</parameter></command>, <command>cat
 	      <parameter>.profile</parameter></command>.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>You'll notice aliases in <filename>.cshrc</filename> for
       some of the <command>ls</command> commands (they're very
       convenient).  You can create other aliases by editing
       <filename>.cshrc</filename>.  You can make these aliases
       available to all users on the system by putting them in the
       system-wide csh configuration file,
       <filename>/etc/csh.cshrc</filename>.</para>
   </sect1>
 
   <sect1>
     <title>Getting Help and Information</title>
 
     <para>Here are some useful sources of help.
       <replaceable>Text</replaceable> stands for something of your
       choice that you type in&mdash;usually a command or
       filename.</para>
 
     <variablelist>
       <varlistentry>
 	<term><command>apropos
 	    <replaceable>text</replaceable></command></term>
 
 	<listitem>
 	  <para>Everything containing string
 	    <replaceable>text</replaceable> in the <database>whatis
 	    database</database>.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>man
 	    <replaceable>text</replaceable></command></term>
 
 	<listitem>
 	  <para>The man page for <replaceable>text</replaceable>.  The
 	    major source of documentation for Un*x systems.
 	    <command>man <parameter>ls</parameter></command> will tell
 	    you all the ways to use the <command>ls</command> command.
 	    Press <keycap>Enter</keycap> to move through text,
 	    <keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo>
 	    to go back a page,
 	    <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo>
 	    to go forward, <keycap>q</keycap> or
 	    <keycombo><keycap>Ctrl</keycap><keycap>c</keycap></keycombo>
 	    to quit.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>which
 	    <replaceable>text</replaceable></command></term>
 
 	<listitem>
 	  <para>Tells you where in the user's path the command
 	    <replaceable>text</replaceable> is found.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>locate
 	    <replaceable>text</replaceable></command></term>
 
 	<listitem>
 	  <para>All the paths where the string
 	    <replaceable>text</replaceable> is found.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>whatis
 	    <replaceable>text</replaceable></command></term>
 
 	<listitem>
 	  <para>Tells you what the command
 	    <replaceable>text</replaceable> does and its man page.
 	    Typing <command>whatis *</command> will tell you about all
 	    the binaries in the current directory.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>whereis
 	    <replaceable>text</replaceable></command></term>
 
 	<listitem>
 	  <para>Finds the file <replaceable>text</replaceable>, giving
 	    its full path.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>You might want to try using <command>whatis</command> on
       some common useful commands like <command>cat</command>,
       <command>more</command>, <command>grep</command>,
       <command>mv</command>, <command>find</command>,
       <command>tar</command>, <command>chmod</command>,
       <command>chown</command>, <command>date</command>, and
       <command>script</command>.  <command>more</command> lets you
       read a page at a time as it does in DOS, e.g., <command>ls -l |
 	more</command> or <command>more
 	<replaceable>filename</replaceable></command>.  The
       <literal>*</literal> works as a wildcard&mdash;e.g., <command>ls
 	w*</command> will show you files beginning with
       <literal>w</literal>.</para>
 
     <para>Are some of these not working very well?  Both
       <command>locate</command> and <command>whatis</command> depend
       on a database that's rebuilt weekly.  If your machine isn't
       going to be left on over the weekend (and running FreeBSD), you
       might want to run the commands for daily, weekly, and monthly
       maintenance now and then.  Run them as root and give each one
       time to finish before you start the next one, for now.</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>periodic daily</userinput>
 <lineannotation>output omitted</lineannotation>
 &prompt.root; <userinput>periodic weekly</userinput>
 <lineannotation>output omitted</lineannotation>
 &prompt.root; <userinput>periodic monthly</userinput>
 <lineannotation>output omitted</lineannotation></screen>
     </informalexample>
 
     <para>If you get tired of waiting, press
       <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to
       get another <firstterm>virtual console</firstterm>, and log in
       again.  After all, it's a multi-user, multi-tasking system.
       Nevertheless these commands will probably flash messages on your
       screen while they're running; you can type
       <command>clear</command> at the prompt to clear the screen.
       Once they've run, you might want to look at
       <filename>/var/mail/root</filename> and
       <filename>/var/log/messages</filename>.</para>
 
     <para>Running such commands is part of system
       administration&mdash;and as a single user of a Unix system,
       you're your own system administrator.  Virtually everything you
       need to be root to do is system administration.  Such
       responsibilities aren't covered very well even in those big fat
       books on Unix, which seem to devote a lot of space to pulling
       down menus in windows managers.  You might want to get one of
       the two leading books on systems administration, either Evi
       Nemeth et.al.'s <citetitle>UNIX System Administration
 	Handbook</citetitle> (Prentice-Hall, 1995, ISBN
       0-13-15051-7)&mdash;the second edition with the red cover; or
       &AElig;leen Frisch's <citetitle>Essential System
 	Administration</citetitle> (O'Reilly &amp; Associates, 1993,
       ISBN 0-937175-80-3).  I used Nemeth.</para>
   </sect1>
 
   <sect1>
     <title>Editing Text</title>
 
     <para>To configure your system, you need to edit text files.  Most
       of them will be in the <filename>/etc</filename> directory; and
       you'll need to <command>su</command> to root to be able to
       change them.  You can use the easy <command>ee</command>, but in
       the long run the text editor <command>vi</command> is worth
       learning.  There's an excellent tutorial on vi in
       <filename>/usr/src/contrib/nvi/docs/tutorial</filename> if you
       have that installed; otherwise you can get it by ftp to
       <hostid>ftp.cdrom.com</hostid> in the directory
       FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial.</para>
 
     <para>Before you edit a file, you should probably back it up.
       Suppose you want to edit <filename>/etc/rc.conf</filename>.  You
       could just use <command>cd /etc</command> to get to the
       <filename>/etc</filename> directory and do:</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>cp rc.conf rc.conf.orig</userinput></screen>
     </informalexample>
 
     <para>This would copy <filename>rc.conf</filename> to
       <filename>rc.conf.orig</filename>, and you could later copy
       <filename>rc.conf.orig</filename> to
       <filename>rc.conf</filename> to recover the original.  But even
       better would be moving (renaming) and then copying back:</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>mv rc.conf rc.conf.orig</userinput>
 &prompt.root; <userinput>cp rc.conf.orig rc.conf</userinput></screen>
     </informalexample>
 
     <para>because the <command>mv</command> command preserves the
       original date and owner of the file.  You can now edit
       <filename>rc.conf</filename>.  If you want the original back,
       you'd then <userinput>mv rc.conf rc.conf.myedit</userinput>
       (assuming you want to preserve your edited version) and
       then</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>mv rc.conf.orig rc.conf</userinput></screen>
     </informalexample>
 
     <para>to put things back the way they were.</para>
 
     <para>To edit a file, type</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>vi <replaceable>filename</replaceable></userinput></screen>
     </informalexample>
 
     <para>Move through the text with the arrow keys.
       <keycap>Esc</keycap> (the escape key) puts <command>vi</command>
       in command mode.  Here are some commands:</para>
 
     <variablelist>
       <varlistentry>
 	<term><command>x</command></term>
 
 	<listitem>
 	  <para>delete letter the cursor is on</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>dd</command></term>
 
 	<listitem>
 	  <para>delete the entire line (even if it wraps on the
 	    screen)</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>i</command></term>
 
 	<listitem>
 	  <para>insert text at the cursor</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>a</command></term>
 
 	<listitem>
 	  <para>insert text after the cursor</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>Once you type <command>i</command> or <command>a</command>,
       you can enter text.  <command>Esc</command> puts you back in
       command mode where you can type</para>
 
     <variablelist>
       <varlistentry>
 	<term><command>:w</command></term>
 
 	<listitem>
 	  <para>to write your changes to disk and continue
 	    editing</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>:wq</command></term>
 
 	<listitem>
 	  <para>to write and quit</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>:q!</command></term>
 
 	<listitem>
 	  <para>to quit without saving changes</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>/<replaceable>text</replaceable></command></term>
 
 	<listitem>
 	  <para>to move the cursor to <replaceable>text</replaceable>;
 	    <command>/<keycap>Enter</keycap></command> (the enter key)
 	    to find the next instance of
 	    <replaceable>text</replaceable>.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>G</command></term>
 
 	<listitem>
 	  <para>to go to the end of the file</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command><replaceable>n</replaceable>G</command></term>
 
 	<listitem>
 	  <para>to go to line <replaceable>n</replaceable> in the
 	    file, where <replaceable>n</replaceable> is a
 	    number</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo></term>
 
 	<listitem>
 	  <para>to redraw the screen</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo> and
 	  <keycombo><keycap>Ctrl</keycap><keycap>f</keycap></keycombo></term>
 
 	<listitem>
 	  <para>go back and forward a screen, as they do with
 	    <command>more</command> and <command>view</command>.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>Practice with <command>vi</command> in your home directory by
       creating a new file with <command>vi <replaceable>filename</replaceable></command>
       and adding and deleting text, saving the file, and calling it up
       again.  <command>vi</command> delivers some surprises because it's
       really quite complex, and sometimes you'll inadvertently issue a
       command that will do something you don't expect.  (Some people
       actually like <command>vi</command>&mdash;it's more powerful than DOS
       EDIT&mdash;find out about the <command>:r</command> command.) Use
       <keycap>Esc</keycap> one or more times to be sure you're in command
       mode and proceed from there when it gives you trouble, save
       often with <command>:w</command>, and use <command>:q!</command> to get out
       and start over (from your last <command>:w</command>) when you need
       to.</para>
 
     <para>Now you can <command>cd</command> to <filename>/etc</filename>,
       <command>su</command> to root, use <command>vi</command> to edit the file
       <filename>/etc/group</filename>, and add a user to wheel so the
       user has root privileges.  Just add a comma and the user's login
       name to the end of the first line in the file, press
       <keycap>Esc</keycap>, and use <command>:wq</command> to write the file to
       disk and quit.  Instantly effective.  (You didn't put a space
       after the comma, did you?)</para>
   </sect1>
 
   <sect1>
     <title>Printing Files from DOS</title>
 
     <para>At this point you probably don't have the printer working,
       so here's a way to create a file from a man page, move it to a
       floppy, and then print it from DOS.  Suppose you want to read
       carefully about changing permissions on files (pretty
       important).  You can use the command man chmod to read about it.
       The command</para>
 
     <informalexample>
       <screen>&prompt.user; <userinput>man chmod | col -b &gt; chmod.txt</></screen>
     </informalexample>
 
     <para>will remove formatting codes and send the man page to the
       <filename>chmod.txt</filename> file instead of showing it on
       your screen.  Now put a dos-formatted diskette in your floppy
       drive a, <command>su</command> to root, and type</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>/sbin/mount -t msdos /dev/fd0 /mnt</></screen>
     </informalexample>
 
     <para>to mount the floppy drive on
       <filename>/mnt</filename>.</para>
 
     <para>Now (you no longer need to be root, and you can type
       <command>exit</command> to get back to being user jack) you can go to
       the directory where you created chmod.txt and copy the file to
       the floppy with:</para>
 
     <informalexample>
       <screen>&prompt.user; <userinput>cp chmod.txt /mnt</></screen>
     </informalexample>
 
     <para>and use <command>ls /mnt</command> to get a directory
       listing of <filename>/mnt</filename>, which should show the file
       <filename>chmod.txt</filename>.</para>
 
     <para>You might especially want to make a file from
       <filename>/sbin/dmesg</filename> by typing</para>
 
     <informalexample>
       <screen>&prompt.user; <userinput>/sbin/dmesg &gt; dmesg.txt</></screen>
     </informalexample>
 
     <para>and copying <filename>dmesg.txt</filename> to the floppy.
       <command>/sbin/dmesg</command> is the boot log record, and it's
       useful to understand it because it shows what FreeBSD found when
       it booted up.  If you ask questions on
       <email>freebsd-questions@FreeBSD.org</email> or on a USENET
       group&mdash;like <quote>FreeBSD isn't finding my tape drive,
 	what do I do?</quote>&mdash;people will want to know what
       <command>dmesg</command> has to say.</para>
 
     <para>You can now dismount the floppy drive (as root) to get the
       disk out with</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>/sbin/umount /mnt</></screen>
     </informalexample>
 
     <para>and reboot to go to DOS.  Copy these files to a DOS
       directory, call them up with DOS EDIT, Windows Notepad or
       Wordpad, or a word processor, make a minor change so the file
       has to be saved, and print as you normally would from DOS or
       Windows.  Hope it works!  man pages come out best if printed
       with the dos <command>print</command> command.  (Copying files from
       FreeBSD to a mounted dos partition is in some cases still a
       little risky.)</para>
 
     <para>Getting the printer printing from FreeBSD involves creating
       an appropriate entry in <filename>/etc/printcap</filename> and
       creating a matching spool directory in
       <filename>/var/spool/output</filename>.  If your printer is on
       <hardware>lpt0</hardware> (what dos calls <hardware>LPT1</hardware>), you may
       only need to go to <filename>/var/spool/output</filename> and
       (as root) create the directory <filename>lpd</filename> by typing:
       <command> mkdir lpd</command>, if it doesn't already exist.
       Then the printer should respond if it's turned on when the
       system is booted, and lp or lpr should send a file to the
       printer.  Whether or not the file actually prints depends on
       configuring it, which is covered in the <ulink
 	URL="../../handbook/handbook.html">FreeBSD handbook.</ulink></para>
   </sect1>
 
   <sect1>
     <title>Other Useful Commands</title>
 
     <variablelist>
       <varlistentry>
 	<term><command>df</command></term>
 
 	<listitem>
 	  <para>shows file space and mounted systems.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>ps aux</command></term>
 
 	<listitem>
 	  <para>shows processes running.  <command>ps ax</command> is a
 	    narrower form.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>rm <replaceable>filename</replaceable></command></term>
 
 	<listitem>
 	  <para>remove <replaceable>filename</replaceable>.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>rm -R <replaceable>dir</replaceable></command></term>
 
 	<listitem>
 	  <para>removes a directory <replaceable>dir</replaceable> and all
 	    subdirectories&mdash;careful!</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>ls -R</command></term>
 
 	<listitem>
 	  <para>lists files in the current directory and all
 	    subdirectories; I used a variant, <command>ls -AFR &gt;
 	      where.txt</command>, to get a list of all the files in
 	    <filename>/</filename> and (separately)
 	    <filename>/usr</filename> before I found better ways to
 	    find files.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>passwd</command></term>
 
 	<listitem>
 	  <para>to change user's password (or root's password)</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>man hier</command></term>
 
 	<listitem>
 	  <para>man page on the Unix file system</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>Use <command>find</command> to locate filename in
       <filename>/usr</filename> or any of its subdirectories
       with</para>
 
     <informalexample>
       <screen>&prompt.user; <userinput>find /usr -name "<replaceable>filename</>"</></screen>
     </informalexample>
 
     <para>You can use <literal>*</literal> as a wildcard in
       <parameter>"<replaceable>filename</replaceable>"</parameter> (which should be in
       quotes).  If you tell find to search in <filename>/</filename>
       instead of <filename>/usr</filename> it will look for the
       file(s) on all mounted file systems, including the CDROM and the
       dos partition.</para>
 
     <para>An excellent book that explains Unix commands and utilities
       is Abrahams &amp; Larson, <citetitle>Unix for the
 	Impatient</citetitle> (2nd ed., Addison-Wesley, 1996).
       There's also a lot of Unix information on the Internet.  Try the
       <ulink URL="http://www.geek-girl.com/unix.html">Unix Reference
 	Desk</ulink>.</para>
   </sect1>
 
   <sect1>
     <title>Next Steps</title>
 
     <para>You should now have the tools you need to get around and
       edit files, so you can get everything up and running.  There is
       a great deal of information in the FreeBSD handbook (which is
       probably on your hard drive) and <ulink
 	URL="http://www.FreeBSD.org/">FreeBSD's web site</ulink>.  A
       wide variety of packages and ports are on the CDROM as well
       as the web site.  The handbook tells you more about how to use
       them (get the package if it exists, with <command>pkg_add
       /cdrom/packages/All/<replaceable>packagename</replaceable></command>, where
       <replaceable>packagename</replaceable> is the filename of the
-      package).  The cdrom has lists of the packages and ports with
+      package).  The CDROM has lists of the packages and ports with
       brief descriptions in <filename>cdrom/packages/index</filename>,
       <filename>cdrom/packages/index.txt</filename>, and
       <filename>cdrom/ports/index</filename>, with fuller descriptions
       in <filename>/cdrom/ports/*/*/pkg/DESCR</filename>, where the
       <literal>*</literal>s represent subdirectories of kinds of
       programs and program names respectively.</para>
 
     <para>If you find the handbook too sophisticated (what with
-      <command>lndir</command> and all) on installing ports from the cdrom,
+      <command>lndir</command> and all) on installing ports from the CDROM,
       here's what usually works:</para>
 
     <para>Find the port you want, say <command>kermit</command>.  There will
-      be a directory for it on the cdrom.  Copy the subdirectory to
+      be a directory for it on the CDROM.  Copy the subdirectory to
       <filename>/usr/local</filename> (a good place for software you
       add that should be available to all users) with:</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>cp -R /cdrom/ports/comm/kermit /usr/local</></screen>
     </informalexample>
 
     <para>This should result in a
       <filename>/usr/local/kermit</filename> subdirectory that has all
       the files that the <command>kermit</command> subdirectory on the
       CDROM has.</para>
 
     <para>Next, create the directory
       <filename>/usr/ports/distfiles</filename> if it doesn't already
       exist using <command>mkdir</command>.  Now check check
       <filename>/cdrom/ports/distfiles</filename> for a file with a
       name that indicates it's the port you want.  Copy that file to
       <filename>/usr/ports/distfiles</filename>; in recent versions
       you can skip this step, as FreeBSD will do it for you.  In the
       case of <command>kermit</command>, there is no distfile.</para>
 
     <para>Then <command>cd</command> to the subdirectory of
       <filename>/usr/local/kermit</filename> that has the file
       <filename>Makefile</filename>.  Type</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>make all install</></screen>
     </informalexample>
 
     <para>During this process the port will ftp to get any compressed
-      files it needs that it didn't find on the cdrom or in
+      files it needs that it didn't find on the CDROM or in
       <filename>/usr/ports/distfiles</filename>.  If you don't have
       your network running yet and there was no file for the port in
       <filename>/cdrom/ports/distfiles</filename>, you will have to
       get the distfile using another machine and copy it to
       <filename>/usr/ports/distfiles</filename> from a floppy or your
       dos partition.  Read <filename>Makefile</filename> (with <command>cat</command>
       or <command>more</command> or <command>view</command>) to find out where to go
       (the master distribution site) to get the file and what its name
       is.  Its name will be truncated when downloaded to DOS, and
       after you get it into <filename>/usr/ports/distfiles</filename>
       you'll have to rename it (with the <command>mv</command> command) to
       its original name so it can be found.  (Use binary file
       transfers!)  Then go back to
       <filename>/usr/local/kermit</filename>, find the directory with
       <filename>Makefile</filename>, and type <command>make all
 	install</command>.</para>
 
     <para>The other thing that happens when installing ports or
       packages is that some other program is needed.  If the
       installation stops with a message <errorname>can't find
 	unzip</errorname> or whatever, you might need to install the
       package or port for unzip before you continue.</para>
 
     <para>Once it's installed type <command>rehash</command> to make FreeBSD
       reread the files in the path so it knows what's there.  (If you
       get a lot of <errorname>path not found</errorname> messages when you use
       <command>whereis</command> or which, you might want to make additions
       to the list of directories in the path statement in
       <filename>.cshrc</filename> in your home directory.  The path
       statement in Unix does the same kind of work it does in DOS,
       except the current directory is not (by default) in the path for
       security reasons; if the command you want is in the directory
       you're in, you need to type <filename>./</filename> before the
       command to make it work; no space after the slash.)</para>
 
     <para>You might want to get the most recent version of Netscape
       from their <ulink URL="ftp://ftp.netscape.com">ftp site</ulink>.
       (Netscape requires the X Window System.) There's now a FreeBSD
       version, so look around carefully.  Just use <command>gunzip
 	<replaceable>filename</replaceable></command> and <command>tar xvf
 	<replaceable>filename</replaceable></command> on it, move the binary to
       <filename>/usr/local/bin</filename> or some other place binaries
       are kept, <command>rehash</command>, and then put the following lines
       in <filename>.cshrc</filename> in each user's home directory or
       (easier) in <filename>/etc/csh.cshrc</filename>, the
       system-wide csh start-up file:</para>
 
     <informalexample>
       <programlisting>setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB
 setenv XNLSPATH /usr/X11R6/lib/X11/nls</programlisting>
     </informalexample>
 
     <para>This assumes that the file <filename>XKeysymDB</filename> and the
       directory <filename>nls</filename> are in
       <filename>/usr/X11R6/lib/X11</filename>; if they're not, find
       them and put them there.</para>
 
     <para>If you originally got Netscape as a port using the CDROM (or
       ftp), don't replace <filename>/usr/local/bin/netscape</filename>
       with the new netscape binary; this is just a shell script that
       sets up the environment variables for you.  Instead rename the
       new binary to <filename>netscape.bin</filename> and replace the
       old binary, which is
       <filename>/usr/local/netscape/netscape</filename>.</para>
   </sect1>
 
   <sect1>
     <title>Your Working Environment</title>
 
     <para>Your shell is the most important part of your working
       environment.  In DOS, the usual shell is command.com.  The shell
       is what interprets the commands you type on the command line,
       and thus communicates with the rest of the operating system.
       You can also write shell scripts, which are like DOS batch
       files: a series of commands to be run without your
       intervention.</para>
 
     <para>Two shells come installed with FreeBSD: csh and sh.  csh is
       good for command-line work, but scripts should be written with
       sh (or bash).  You can find out what shell you have by typing
       <command>echo $SHELL</command>.</para>
 
     <para>The csh shell is okay, but tcsh does everything csh does and
       more.  It allows you to recall commands with the arrow keys
       and edit them.  It has tab-key completion of filenames (csh uses
       the escape key), and it lets you switch to the directory you
       were last in with <command>cd -</command>.  It's also much
       easier to alter your prompt with tcsh.  It makes life a lot
       easier.</para>
 
     <para>Here are the three steps for installing a new shell:</para>
 
     <procedure>
       <step>
 	<para>Install the shell as a port or a package, just as you
 	  would any other port or package.  Use
 	  <command>rehash</command> and <command>which tcsh</command>
 	  (assuming you're installing tcsh) to make sure it got
 	  installed.</para>
       </step>
 
       <step>
 	<para>As root, edit <filename>/etc/shells</filename>, adding a
 	  line in the file for the new shell, in this case
 	  /usr/local/bin/tcsh, and save the file.  (Some ports may do
 	  this for you.)</para>
       </step>
 
       <step>
 	<para>Use the <command>chsh</command> command to change your
 	  shell to tcsh permanently, or type <command>tcsh</command>
 	  at the prompt to change your shell without logging in
 	  again.</para>
       </step>
     </procedure>
 
     <note>
       <para>It can be dangerous to change root's shell to something
 	other than sh or csh on early versions of FreeBSD and many
 	other versions of Unix; you may not have a working shell when
 	the system puts you into single user mode.  The solution is to
 	use <command>su -m</command> to become root, which will give
 	you the tcsh as root, because the shell is part of the
 	environment.  You can make this permanent by adding it to your
 	<filename>.tcshrc</filename> file as an alias with
 	<programlisting>alias su su -m.</programlisting></para>
     </note>
 
     <para>When tcsh starts up, it will read the
       <filename>/etc/csh.cshrc</filename> and
       <filename>/etc/csh.login</filename> files, as does csh.  It will
       also read the <filename>.login</filename> file in your home
       directory and the <filename>.cshrc</filename> file as well,
       unless you provide a <filename>.tcshrc</filename> file.  This
       you can do by simply copying <filename>.cshrc</filename> to
       <filename>.tcshrc</filename>.</para>
 
     <para>Now that you've installed tcsh, you can adjust your prompt.
       You can find the details in the manual page for tcsh, but here
       is a line to put in your <filename>.tcshrc</filename> that will
       tell you how many commands you have typed, what time it is, and
       what directory you are in.  It also produces a
       <literal>></literal> if you're an ordinary user and a
       <literal>#</literal> if you're root, but tsch will do that in
       any case:</para>
 
     <para>set prompt = "%h %t %~ %# "</para>
 
     <para>This should go in the same place as the existing set prompt
       line if there is one, or under "if($?prompt) then" if not.
       Comment out the old line; you can always switch back to it if
       you prefer it.  Don't forget the spaces and quotes.  You can get
       the <filename>.tcshrc</filename> reread by typing
       <command>source .tcshrc</command>.</para>
 
     <para>You can get a listing of other environmental variables that
       have been set by typing <command>env</command> at the prompt.
       The result will show you your default editor, pager, and
       terminal type, among possibly many others.  A useful command if
       you log in from a remote location and can't run a program
       because the terminal isn't capable is <command>setenv TERM
       vt100</command>.</para>
   </sect1>
 
   <sect1>
     <title>Other</title>
 
     <para>As root, you can dismount the CDROM with
       <command>/sbin/umount /cdrom</command>, take it out of the drive,
       insert another one, and mount it with
       <command>/sbin/mount_cd9660 /dev/cd0a /cdrom</command> assuming
       <hardware>cd0a</hardware> is the device name for your CDROM drive.  The
-      most recent versions of FreeBSD let you mount the cdrom with
+      most recent versions of FreeBSD let you mount the CDROM with
       just <command>/sbin/mount /cdrom</command>.</para>
 
     <para>Using the live file system&mdash;the second of FreeBSD's
       CDROM disks&mdash;is useful if you've got limited space.  What
       is on the live file system varies from release to release.  You
-      might try playing games from the cdrom.  This involves using
+      might try playing games from the CDROM.  This involves using
       <command>lndir</command>, which gets installed with the X Window
       System, to tell the program(s) where to find the necessary
       files, because they're in the <filename>/cdrom</filename> file
       system instead of in <filename>/usr</filename> and its
       subdirectories, which is where they're expected to be.  Read
       <command>man lndir</command>.</para>
   </sect1>
 
   <sect1>
     <title>Comments Welcome</title>
 
     <para>If you use this guide I'd be interested in knowing where it
       was unclear and what was left out that you think should be
       included, and if it was helpful.  My thanks to Eugene W. Stark,
       professor of computer science at SUNY-Stony Brook, and John
       Fieber for helpful comments.</para>
 
     <para>Annelise Anderson,
 	<email>andrsn@andrsn.stanford.edu</email></para>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/articles/vm-design/article.sgml b/en_US.ISO8859-1/articles/vm-design/article.sgml
index ad0b7c8c9a..f932c5eb47 100644
--- a/en_US.ISO8859-1/articles/vm-design/article.sgml
+++ b/en_US.ISO8859-1/articles/vm-design/article.sgml
@@ -1,838 +1,838 @@
-<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/vm-design/article.sgml,v 1.4 2001/02/20 19:49:32 nik Exp $ -->
+<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/vm-design/article.sgml,v 1.5 2001/07/10 13:24:13 dd Exp $ -->
 <!-- FreeBSD Documentation Project -->
 
 <!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>Design elements of the FreeBSD VM system</title>
 
     <authorgroup>
       <author>
 	<firstname>Matthew</firstname>
 
 	<surname>Dillon</surname>
 
 	<affiliation>
 	  <address>
 	    <email>dillon@apollo.backplane.com</email>
 	  </address>
 	</affiliation>
       </author>
     </authorgroup>
 
     <abstract>
       <para>The title is really just a fancy way of saying that I am going to
 	attempt to describe the whole VM enchilada, hopefully in a way that
 	everyone can follow.  For the last year I have concentrated on a number
 	of major kernel subsystems within FreeBSD, with the VM and Swap
 	subsystems being the most interesting and NFS being &lsquo;a necessary
 	chore&rsquo;.  I rewrote only small portions of the code.  In the VM
 	arena the only major rewrite I have done is to the swap subsystem.
 	Most of my work was cleanup and maintenance, with only moderate code
 	rewriting and no major algorithmic adjustments within the VM
 	subsystem.  The bulk of the VM subsystem's theoretical base remains
 	unchanged and a lot of the credit for the modernization effort in the
 	last few years belongs to John Dyson and David Greenman.  Not being a
 	historian like Kirk I will not attempt to tag all the various features
 	with peoples names, since I will invariably get it wrong.</para>
     </abstract>
 
     <legalnotice>
       <para>This article was originally published in the January 2000 issue of 
 	<ulink url="http://www.daemonnews.org/">DaemonNews</ulink>.  This
 	version of the article may include updates from Matt and other authors
 	to reflect changes in FreeBSD's VM implementation.</para>
     </legalnotice>
   </articleinfo>
 
   <sect1>
     <title>Introduction</title>
 
     <para>Before moving along to the actual design let's spend a little time
       on the necessity of maintaining and modernizing any long-living
       codebase.  In the programming world, algorithms tend to be more
       important than code and it is precisely due to BSD's academic roots that
       a great deal of attention was paid to algorithm design from the
       beginning.  More attention paid to the design generally leads to a clean
       and flexible codebase that can be fairly easily modified, extended, or
       replaced over time.  While BSD is considered an &lsquo;old&rsquo;
       operating system by some people, those of us who work on it tend to view
       it more as a &lsquo;mature&rsquo; codebase which has various components
       modified, extended, or replaced with modern code.  It has evolved, and
       FreeBSD is at the bleeding edge no matter how old some of the code might
       be.  This is an important distinction to make and one that is
       unfortunately lost to many people.  The biggest error a programmer can
       make is to not learn from history, and this is precisely the error that
       many other modern operating systems have made.  NT is the best example
       of this, and the consequences have been dire.  Linux also makes this
       mistake to some degree&mdash;enough that we BSD folk can make small
       jokes about it every once in a while, anyway.  Linux's problem is simply
       one of a lack of experience and history to compare ideas against, a
       problem that is easily and rapidly being addressed by the Linux
       community in the same way it has been addressed in the BSD
       community&mdash;by continuous code development.  The NT folk, on the
-      other hand, repeatedly make the same mistakes solved by UNIX decades ago
+      other hand, repeatedly make the same mistakes solved by Unix decades ago
       and then spend years fixing them. Over and over again.  They have a
       severe case of &lsquo;not designed here&rsquo; and &lsquo;we are always
       right because our marketing department says so&rsquo;.  I have little
       tolerance for anyone who cannot learn from history.</para>
 
     <para>Much of the apparent complexity of the FreeBSD design, especially in
       the VM/Swap subsystem, is a direct result of having to solve serious
       performance issues that occur under various conditions.  These issues
       are not due to bad algorithmic design but instead rise from
       environmental factors.  In any direct comparison between platforms,
       these issues become most apparent when system resources begin to get
       stressed.  As I describe FreeBSD's VM/Swap subsystem the reader should
       always keep two points in mind.  First, the most important aspect of
       performance design is what is known as &ldquo;Optimizing the Critical
       Path&rdquo;.  It is often the case that performance optimizations add a
       little bloat to the code in order to make the critical path perform
       better.  Second, a solid, generalized design outperforms a
       heavily-optimized design over the long run.  While a generalized design
       may end up being slower than an heavily-optimized design when they are
       first implemented, the generalized design tends to be easier to adapt to
       changing conditions and the heavily-optimized design winds up having to
       be thrown away.  Any codebase that will survive and be maintainable for
       years must therefore be designed properly from the beginning even if it
       costs some performance.  Twenty years ago people were still arguing that
       programming in assembly was better than programming in a high-level
       language because it produced code that was ten times as fast.  Today,
       the fallibility of that argument is obvious&mdash;as are the parallels
       to algorithmic design and code generalization.</para>
   </sect1>
 
   <sect1>
     <title>VM Objects</title>
 
     <para>The best way to begin describing the FreeBSD VM system is to look at
       it from the perspective of a user-level process.  Each user process sees
       a single, private, contiguous VM address space containing several types
       of memory objects.  These objects have various characteristics.  Program
       code and program data are effectively a single memory-mapped file (the
       binary file being run), but program code is read-only while program data
       is copy-on-write.  Program BSS is just memory allocated and filled with
       zeros on demand, called demand zero page fill.  Arbitrary files can be
       memory-mapped into the address space as well, which is how the shared
       library mechanism works.  Such mappings can require modifications to
       remain private to the process making them.  The fork system call adds an
       entirely new dimension to the VM management problem on top of the
       complexity already given.</para>
 
     <para>A program binary data page (which is a basic copy-on-write page)
       illustrates the complexity.  A program binary contains a preinitialized
       data section which is initially mapped directly from the program file.
       When a program is loaded into a process's VM space, this area is
       initially memory-mapped and backed by the program binary itself,
       allowing the VM system to free/reuse the page and later load it back in
       from the binary.  The moment a process modifies this data, however, the
       VM system must make a private copy of the page for that process.  Since
       the private copy has been modified, the VM system may no longer free it,
       because there is no longer any way to restore it later on.</para>
 
     <para>You will notice immediately that what was originally a simple file
       mapping has become much more complex.  Data may be modified on a
       page-by-page basis whereas the file mapping encompasses many pages at
       once.  The complexity further increases when a process forks.  When a
       process forks, the result is two processes&mdash;each with their own
       private address spaces, including any modifications made by the original
       process prior to the call to <function>fork()</function>.  It would be
       silly for the VM system to make a complete copy of the data at the time
       of the <function>fork()</function> because it is quite possible that at
       least one of the two processes will only need to read from that page
       from then on, allowing the original page to continue to be used.  What
       was a private page is made copy-on-write again, since each process
       (parent and child) expects their own personal post-fork modifications to
       remain private to themselves and not effect the other.</para>
 
     <para>FreeBSD manages all of this with a layered VM Object model.  The
       original binary program file winds up being the lowest VM Object layer.
       A copy-on-write layer is pushed on top of that to hold those pages which
       had to be copied from the original file.  If the program modifies a data
       page belonging to the original file the VM system takes a fault and
       makes a copy of the page in the higher layer.  When a process forks,
       additional VM Object layers are pushed on.  This might make a little
       more sense with a fairly basic example.  A <function>fork()</function>
       is a common operation for any *BSD system, so this example will consider
       a program that starts up, and forks.  When the process starts, the VM
       system creates an object layer, let's call this A:</para>
 
     <mediaobject>
       <imageobject>
         <imagedata fileref="fig1" format="EPS">
       </imageobject>
 	
       <textobject>
 	<literallayout class="monospaced">+---------------+
 |       A       |
 +---------------+</literallayout>
       </textobject>
 
       <textobject>
 	<phrase>A picture</phrase>
       </textobject>
     </mediaobject>
 
     <para>A represents the file&mdash;pages may be paged in and out of the
       file's physical media as necessary.  Paging in from the disk is
       reasonable for a program, but we really don't want to page back out and
       overwrite the executable.  The VM system therefore creates a second
       layer, B, that will be physically backed by swap space:</para>
 
     <mediaobject>
       <imageobject>
         <imagedata fileref="fig2" format="EPS">
       </imageobject>
 
       <textobject>
 	<literallayout class="monospaced">+---------------+
 |       B       |	  
 +---------------+
 |       A       |
 +---------------+</literallayout>
       </textobject>
     </mediaobject>
 
     <para>On the first write to a page after this, a new page is created in B,
       and its contents are initialized from A.  All pages in B can be paged in
       or out to a swap device.  When the program forks, the VM system creates
       two new object layers&mdash;C1 for the parent, and C2 for the
       child&mdash;that rest on top of B:</para>
 
     <mediaobject>
       <imageobject>
         <imagedata fileref="fig3" format="EPS">
       </imageobject>
       
       <textobject>
 	<literallayout class="monospaced">+-------+-------+
 |   C1  |   C2  |
 +-------+-------+
 |       B       |
 +---------------+
 |       A       |
 +---------------+</literallayout>
       </textobject>
     </mediaobject>
 
     <para>In this case, let's say a page in B is modified by the original
       parent process.  The process will take a copy-on-write fault and
       duplicate the page in C1, leaving the original page in B untouched.
       Now, let's say the same page in B is modified by the child process.  The
       process will take a copy-on-write fault and duplicate the page in C2.
       The original page in B is now completely hidden since both C1 and C2
       have a copy and B could theoretically be destroyed if it does not
       represent a 'real' file).  However, this sort of optimization is not
       trivial to make because it is so fine-grained.  FreeBSD does not make
       this optimization.  Now, suppose (as is often the case) that the child
       process does an <function>exec()</function>.  Its current address space
       is usually replaced by a new address space representing a new file.  In
       this case, the C2 layer is destroyed:</para>
 
     <mediaobject>
       <imageobject>
         <imagedata fileref="fig4" format="EPS">
       </imageobject>
 
       <textobject>
 	<literallayout class="monospaced">+-------+
 |   C1  |
 +-------+-------+
 |       B       |
 +---------------+
 |       A       |
 +---------------+</literallayout>
       </textobject>
     </mediaobject>
 
     <para>In this case, the number of children of B drops to one, and all
       accesses to B now go through C1.  This means that B and C1 can be
       collapsed together.  Any pages in B that also exist in C1 are deleted
       from B during the collapse.  Thus, even though the optimization in the
       previous step could not be made, we can recover the dead pages when
       either of the processes exit or <function>exec()</function>.</para>
 
     <para>This model creates a number of potential problems.  The first is that
       you can wind up with a relatively deep stack of layered VM Objects which
       can cost scanning time and memory when you take a fault.  Deep
       layering can occur when processes fork and then fork again (either
       parent or child).  The second problem is that you can wind up with dead,
       inaccessible pages deep in the stack of VM Objects.  In our last example
       if both the parent and child processes modify the same page, they both
       get their own private copies of the page and the original page in B is
       no longer accessible by anyone.  That page in B can be freed.</para>
 
     <para>FreeBSD solves the deep layering problem with a special optimization
       called the &ldquo;All Shadowed Case&rdquo;.  This case occurs if either
       C1 or C2 take sufficient COW faults to completely shadow all pages in B.
       Lets say that C1 achieves this.  C1 can now bypass B entirely, so rather
       then have C1->B->A and C2->B->A we now have C1->A and C2->B->A.  But
       look what also happened&mdash;now B has only one reference (C2), so we
       can collapse B and C2 together.  The end result is that B is deleted
       entirely and we have C1->A and C2->A.  It is often the case that B will
       contain a large number of pages and neither C1 nor C2 will be able to
       completely overshadow it.  If we fork again and create a set of D
       layers, however, it is much more likely that one of the D layers will
       eventually be able to completely overshadow the much smaller dataset
       represented by C1 or C2.  The same optimization will work at any point in
       the graph and the grand result of this is that even on a heavily forked
       machine VM Object stacks tend to not get much deeper then 4.  This is
       true of both the parent and the children and true whether the parent is
       doing the forking or whether the children cascade forks.</para>
 
     <para>The dead page problem still exists in the case where C1 or C2 do not
       completely overshadow B.  Due to our other optimizations this case does
       not represent much of a problem and we simply allow the pages to be
       dead.  If the system runs low on memory it will swap them out, eating a
       little swap, but that's it.</para>
 
     <para>The advantage to the VM Object model is that
       <function>fork()</function> is extremely fast, since no real data
       copying need take place.  The disadvantage is that you can build a
       relatively complex VM Object layering that slows page fault handling
       down a little, and you spend memory managing the VM Object structures.
       The optimizations FreeBSD makes proves to reduce the problems enough
       that they can be ignored, leaving no real disadvantage.</para>
   </sect1>
 
   <sect1>
     <title>SWAP Layers</title>
 
     <para>Private data pages are initially either copy-on-write or zero-fill
       pages.  When a change, and therefore a copy, is made, the original
       backing object (usually a file) can no longer be used to save a copy of
       the page when the VM system needs to reuse it for other purposes.  This
       is where SWAP comes in.  SWAP is allocated to create backing store for
       memory that does not otherwise have it.  FreeBSD allocates the swap
       management structure for a VM Object only when it is actually needed.
       However, the swap management structure has had problems
       historically.</para>
 
     <para>Under FreeBSD 3.x the swap management structure preallocates an
       array that encompasses the entire object requiring swap backing
       store&mdash;even if only a few pages of that object are swap-backed.
       This creates a kernel memory fragmentation problem when large objects
       are mapped, or processes with large runsizes (RSS) fork.  Also, in order
       to keep track of swap space, a &lsquo;list of holes&rsquo; is kept in
       kernel memory, and this tends to get severely fragmented as well.  Since
       the 'list of holes' is a linear list, the swap allocation and freeing
       performance is a non-optimal O(n)-per-page.  It also requires kernel
       memory allocations to take place during the swap freeing process, and
       that creates low memory deadlock problems.  The problem is further
       exacerbated by holes created due to the interleaving algorithm.  Also,
       the swap block map can become fragmented fairly easily resulting in
       non-contiguous allocations. Kernel memory must also be allocated on the
       fly for additional swap management structures when a swapout occurs.  It
       is evident that there was plenty of room for improvement.</para>
 
     <para>For FreeBSD 4.x, I completely rewrote the swap subsystem.  With this
       rewrite, swap management structures are allocated through a hash table
       rather than a linear array giving them a fixed allocation size and much
       finer granularity.  Rather then using a linearly linked list to keep
       track of swap space reservations, it now uses a bitmap of swap blocks
       arranged in a radix tree structure with free-space hinting in the radix
       node structures.  This effectively makes swap allocation and freeing an
       O(1) operation.  The entire radix tree bitmap is also preallocated in
       order to avoid having to allocate kernel memory during critical low
       memory swapping operations.  After all, the system tends to swap when it
       is low on memory so we should avoid allocating kernel memory at such
       times in order to avoid potential deadlocks.  Finally, to reduce
       fragmentation the radix tree is capable of allocating large contiguous
       chunks at once, skipping over smaller fragmented chunks.  I did not take
       the final step of having an 'allocating hint pointer' that would trundle
       through a portion of swap as allocations were made in order to further
       guarantee contiguous allocations or at least locality of reference, but
       I ensured that such an addition could be made.</para>
   </sect1>
 
   <sect1>
     <title>When to free a page</title>
 
     <para>Since the VM system uses all available memory for disk caching,
       there are usually very few truly-free pages.  The VM system depends on
       being able to properly choose pages which are not in use to reuse for
       new allocations.  Selecting the optimal pages to free is possibly the
       single-most important function any VM system can perform because if it
       makes a poor selection, the VM system may be forced to unnecessarily
       retrieve pages from disk, seriously degrading system performance.</para>
 
     <para>How much overhead are we willing to suffer in the critical path to
       avoid freeing the wrong page?  Each wrong choice we make will cost us
       hundreds of thousands of CPU cycles and a noticeable stall of the
       affected processes, so we are willing to endure a significant amount of
       overhead in order to be sure that the right page is chosen.  This is why
       FreeBSD tends to outperform other systems when memory resources become
       stressed.</para>
 
     <para>The free page determination algorithm is built upon a history of the
       use of memory pages.  To acquire this history, the system takes advantage
       of a page-used bit feature that most hardware page tables have.</para>
 
     <para>In any case, the page-used bit is cleared and at some later point
       the VM system comes across the page again and sees that the page-used
       bit has been set.  This indicates that the page is still being actively
       used.  If the bit is still clear it is an indication that the page is not
       being actively used.  By testing this bit periodically, a use history (in
       the form of a counter) for the physical page is developed.  When the VM
       system later needs to free up some pages, checking this history becomes
       the cornerstone of determining the best candidate page to reuse.</para>
 
     <sidebar>
       <title>What if the hardware has no page-used bit?</title>
 
       <para>For those platforms that do not have this feature, the system
 	actually emulates a page-used bit.  It unmaps or protects a page,
 	forcing a page fault if the page is accessed again.  When the page
 	fault is taken, the system simply marks the page as having been used
 	and unprotects the page so that it may be used.  While taking such page
 	faults just to determine if a page is being used appears to be an
 	expensive proposition, it is much less expensive than reusing the page
 	for some other purpose only to find that a process needs it back and
 	then have to go to disk.</para>
     </sidebar>
 
     <para>FreeBSD makes use of several page queues to further refine the
       selection of pages to reuse as well as to determine when dirty pages
       must be flushed to their backing store.  Since page tables are dynamic
       entities under FreeBSD, it costs virtually nothing to unmap a page from
       the address space of any processes using it.  When a page candidate has
       been chosen based on the page-use counter, this is precisely what is
       done.  The system must make a distinction between clean pages which can
       theoretically be freed up at any time, and dirty pages which must first
       be written to their backing store before being reusable.  When a page
       candidate has been found it is moved to the inactive queue if it is
       dirty, or the cache queue if it is clean.  A separate algorithm based on
       the dirty-to-clean page ratio determines when dirty pages in the
       inactive queue must be flushed to disk.  Once this is accomplished, the
       flushed pages are moved from the inactive queue to the cache queue.  At
       this point, pages in the cache queue can still be reactivated by a VM
       fault at relatively low cost.  However, pages in the cache queue are
       considered to be &lsquo;immediately freeable&rsquo; and will be reused
       in an LRU (least-recently used) fashion when the system needs to
       allocate new memory.</para>
 
     <para>It is important to note that the FreeBSD VM system attempts to
       separate clean and dirty pages for the express reason of avoiding
       unnecessary flushes of dirty pages (which eats I/O bandwidth), nor does
       it move pages between the various page queues gratuitously when the
       memory subsystem is not being stressed.  This is why you will see some
       systems with very low cache queue counts and high active queue counts
       when doing a <command>systat -vm</command> command.  As the VM system
       becomes more stressed, it makes a greater effort to maintain the various
       page queues at the levels determined to be the most effective.  An urban
       myth has circulated for years that Linux did a better job avoiding
       swapouts than FreeBSD, but this in fact is not true.  What was actually
       occurring was that FreeBSD was proactively paging out unused pages in
       order to make room for more disk cache while Linux was keeping unused
       pages in core and leaving less memory available for cache and process
       pages.  I don't know whether this is still true today.</para>
   </sect1>
 
   <sect1>
     <title>Pre-Faulting and Zeroing Optimizations</title>
 
     <para>Taking a VM fault is not expensive if the underlying page is already
       in core and can simply be mapped into the process, but it can become
       expensive if you take a whole lot of them on a regular basis.  A good
       example of this is running a program such as &man.ls.1; or &man.ps.1;
       over and over again.  If the program binary is mapped into memory but
       not mapped into the page table, then all the pages that will be accessed
       by the program will have to be faulted in every time the program is run.
       This is unnecessary when the pages in question are already in the VM
       Cache, so FreeBSD will attempt to pre-populate a process's page tables
       with those pages that are already in the VM Cache.  One thing that
       FreeBSD does not yet do is pre-copy-on-write certain pages on exec.  For
       example, if you run the &man.ls.1; program while running <command>vmstat
 	1</command> you will notice that it always takes a certain number of
       page faults, even when you run it over and over again.  These are
       zero-fill faults, not program code faults (which were pre-faulted in
       already).  Pre-copying pages on exec or fork is an area that could use
       more study.</para>
 
     <para>A large percentage of page faults that occur are zero-fill faults.
       You can usually see this by observing the <command>vmstat -s</command>
       output.  These occur when a process accesses pages in its BSS area.  The
       BSS area is expected to be initially zero but the VM system does not
       bother to allocate any memory at all until the process actually accesses
       it.  When a fault occurs the VM system must not only allocate a new page,
       it must zero it as well.  To optimize the zeroing operation the VM system
       has the ability to pre-zero pages and mark them as such, and to request
       pre-zeroed pages when zero-fill faults occur.  The pre-zeroing occurs
       whenever the CPU is idle but the number of pages the system pre-zeros is
       limited in order to avoid blowing away the memory caches.  This is an
       excellent example of adding complexity to the VM system in order to
       optimize the critical path.</para>
   </sect1>
 
   <sect1>
     <title>Page Table Optimizations</title>
 
     <para>The page table optimizations make up the most contentious part of
       the FreeBSD VM design and they have shown some strain with the advent of
       serious use of <function>mmap()</function>.  I think this is actually a
       feature of most BSDs though I am not sure when it was first introduced.
       There are two major optimizations.  The first is that hardware page
       tables do not contain persistent state but instead can be thrown away at
       any time with only a minor amount of management overhead.  The second is
       that every active page table entry in the system has a governing
       <literal>pv_entry</literal> structure which is tied into the
       <literal>vm_page</literal> structure.  FreeBSD can simply iterate
       through those mappings that are known to exist while Linux must check
       all page tables that <emphasis>might</emphasis> contain a specific
       mapping to see if it does, which can achieve O(n^2) overhead in certain
       situations.  It is because of this that FreeBSD tends to make better
       choices on which pages to reuse or swap when memory is stressed, giving
       it better performance under load. However, FreeBSD requires kernel
       tuning to accommodate large-shared-address-space situations such as
       those that can occur in a news system because it may run out of
       <literal>pv_entry</literal> structures.</para>
 
     <para>Both Linux and FreeBSD need work in this area.  FreeBSD is trying to
       maximize the advantage of a potentially sparse active-mapping model (not
       all processes need to map all pages of a shared library, for example),
       whereas Linux is trying to simplify its algorithms.  FreeBSD generally
       has the performance advantage here at the cost of wasting a little extra
       memory, but FreeBSD breaks down in the case where a large file is
       massively shared across hundreds of processes.  Linux, on the other hand,
       breaks down in the case where many processes are sparsely-mapping the
       same shared library and also runs non-optimally when trying to determine
       whether a page can be reused or not.</para>
   </sect1>
 
   <sect1>
     <title>Page Coloring</title>
 
     <para>We'll end with the page coloring optimizations.  Page coloring is a
       performance optimization designed to ensure that accesses to contiguous
       pages in virtual memory make the best use of the processor cache.  In
       ancient times (i.e. 10+ years ago) processor caches tended to map
       virtual memory rather than physical memory.  This led to a huge number of
       problems including having to clear the cache on every context switch in
       some cases, and problems with data aliasing in the cache.  Modern
       processor caches map physical memory precisely to solve those problems.
       This means that two side-by-side pages in a processes address space may
       not correspond to two side-by-side pages in the cache.  In fact, if you
       aren't careful side-by-side pages in virtual memory could wind up using
       the same page in the processor cache&mdash;leading to cacheable data
       being thrown away prematurely and reducing CPU performance.  This is true
       even with multi-way set-associative caches (though the effect is
       mitigated somewhat).</para>
 
     <para>FreeBSD's memory allocation code implements page coloring
       optimizations, which means that the memory allocation code will attempt
       to locate free pages that are contiguous from the point of view of the
       cache.  For example, if page 16 of physical memory is assigned to page 0
       of a process's virtual memory and the cache can hold 4 pages, the page
       coloring code will not assign page 20 of physical memory to page 1 of a
       process's virtual memory.  It would, instead, assign page 21 of physical
       memory.  The page coloring code attempts to avoid assigning page 20
       because this maps over the same cache memory as page 16 and would result
       in non-optimal caching.  This code adds a significant amount of
       complexity to the VM memory allocation subsystem as you can well
       imagine, but the result is well worth the effort.  Page Coloring makes VM
       memory as deterministic as physical memory in regards to cache
       performance.</para>
   </sect1>
 
   <sect1>
     <title>Conclusion</title>
 
     <para>Virtual memory in modern operating systems must address a number of
       different issues efficiently and for many different usage patterns.  The
       modular and algorithmic approach that BSD has historically taken allows
       us to study and understand the current implementation as well as
       relatively cleanly replace large sections of the code.  There have been a
       number of improvements to the FreeBSD VM system in the last several
       years, and work is ongoing.</para>
   </sect1>
 
   <sect1>
     <title>Bonus QA session by Allen Briggs
       <email>briggs@ninthwonder.com</email></title>
 
     <qandaset>
       <qandaentry>
 	<question>
 	  <para>What is &ldquo;the interleaving algorithm&rdquo; that you
 	    refer to in your listing of the ills of the FreeBSD 3.x swap
 	    arrangements?</para>
 	</question>
 
 	<answer>
 	  <para>FreeBSD uses a fixed swap interleave which defaults to 4.  This
 	    means that FreeBSD reserves space for four swap areas even if you
 	    only have one, two, or three.  Since swap is interleaved the linear
 	    address space representing the &lsquo;four swap areas&rsquo; will be
 	    fragmented if you don't actually have four swap areas.  For
 	    example, if you have two swap areas A and B FreeBSD's address
 	    space representation for that swap area will be interleaved in
 	    blocks of 16 pages:</para>
 
 	  <literallayout>A B C D A B C D A B C D A B C D</literallayout>
 
 	  <para>FreeBSD 3.x uses a &lsquo;sequential list of free
 	    regions&rsquo; approach to accounting for the free swap areas.
 	    The idea is that large blocks of free linear space can be
 	    represented with a single list node
 	    (<filename>kern/subr_rlist.c</filename>).  But due to the
 	    fragmentation the sequential list winds up being insanely
 	    fragmented.  In the above example, completely unused swap will
 	    have A and B shown as &lsquo;free&rsquo; and C and D shown as
 	    &lsquo;all allocated&rsquo;.  Each A-B sequence requires a list
 	    node to account for because C and D are holes, so the list node
 	    cannot be combined with the next A-B sequence.</para>
 
 	  <para>Why do we interleave our swap space instead of just tack swap
 	    areas onto the end and do something fancier?  Because it's a whole
 	    lot easier to allocate linear swaths of an address space and have
 	    the result automatically be interleaved across multiple disks than
 	    it is to try to put that sophistication elsewhere.</para>
 
 	  <para>The fragmentation causes other problems.  Being a linear list
 	    under 3.x, and having such a huge amount of inherent
 	    fragmentation, allocating and freeing swap winds up being an O(N)
 	    algorithm instead of an O(1) algorithm.  Combined with other
 	    factors (heavy swapping) and you start getting into O(N^2) and
 	    O(N^3) levels of overhead, which is bad.  The 3.x system may also
 	    need to allocate KVM during a swap operation to create a new list
 	    node which can lead to a deadlock if the system is trying to
 	    pageout pages in a low-memory situation.</para>
 
 	  <para>Under 4.x we do not use a sequential list.  Instead we use a
 	    radix tree and bitmaps of swap blocks rather than ranged list
 	    nodes.  We take the hit of preallocating all the bitmaps required
 	    for the entire swap area up front but it winds up wasting less
 	    memory due to the use of a bitmap (one bit per block) instead of a
 	    linked list of nodes.  The use of a radix tree instead of a
 	    sequential list gives us nearly O(1) performance no matter how
 	    fragmented the tree becomes.</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
 	<question>
 	  <para>I don't get the following:</para>
 
 	  <blockquote>
 	    <para>It is important to note that the FreeBSD VM system attempts
 	      to separate clean and dirty pages for the express reason of
 	      avoiding unnecessary flushes of dirty pages (which eats I/O
 	      bandwidth), nor does it move pages between the various page
 	      queues gratuitously when the memory subsystem is not being
 	      stressed.  This is why you will see some systems with very low
 	      cache queue counts and high active queue counts when doing a
 	      <command>systat -vm</command> command.</para>
 	  </blockquote>
 	  
 	  <para>How is the separation of clean and dirty (inactive) pages
 	    related to the situation where you see low cache queue counts and
 	    high active queue counts in <command>systat -vm</command>?  Do the
 	    systat stats roll the active and dirty pages together for the
 	    active queue count?</para>
 	</question>
 
 	<answer>
 	  <para>Yes, that is confusing.  The relationship is
 	    &ldquo;goal&rdquo; verses &ldquo;reality&rdquo;.  Our goal is to
 	    separate the pages but the reality is that if we are not in a
 	    memory crunch, we don't really have to.</para>
 
 	  <para>What this means is that FreeBSD will not try very hard to
 	    separate out dirty pages (inactive queue) from clean pages (cache
 	    queue) when the system is not being stressed, nor will it try to
 	    deactivate pages (active queue -> inactive queue) when the system
 	    is not being stressed, even if they aren't being used.</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
 	<question>
 	  <para> In the &man.ls.1; / <command>vmstat 1</command> example,
 	    wouldn't some of the page faults be data page faults (COW from
 	    executable file to private page)?  I.e., I would expect the page
 	    faults to be some zero-fill and some program data.  Or are you
 	    implying that FreeBSD does do pre-COW for the program data?</para>
 	</question>
 
 	<answer>
 	  <para>A COW fault can be either zero-fill or program-data.  The
 	    mechanism is the same either way because the backing program-data
 	    is almost certainly already in the cache.  I am indeed lumping the
 	    two together.  FreeBSD does not pre-COW program data or zero-fill,
 	    but it <emphasis>does</emphasis> pre-map pages that exist in its
 	    cache.</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
 	<question>
 	  <para>In your section on page table optimizations, can you give a
 	    little more detail about <literal>pv_entry</literal> and
 	    <literal>vm_page</literal> (or should vm_page be
 	    <literal>vm_pmap</literal>&mdash;as in 4.4, cf. pp. 180-181 of
 	    McKusick, Bostic, Karel, Quarterman)?  Specifically, what kind of
 	    operation/reaction would require scanning the mappings?</para>
 
 	  <para>How does Linux do in the case where FreeBSD breaks down
 	    (sharing a large file mapping over many processes)?</para>
 	</question>
 
 	<answer>
 	  <para>A <literal>vm_page</literal> represents an (object,index#)
 	    tuple.  A <literal>pv_entry</literal> represents a hardware page
 	    table entry (pte).  If you have five processes sharing the same
 	    physical page, and three of those processes's page tables actually
 	    map the page, that page will be represented by a single
 	    <literal>vm_page</literal> structure and three
 	    <literal>pv_entry</literal> structures.</para>
 
 	  <para><literal>pv_entry</literal> structures only represent pages
 	    mapped by the MMU (one <literal>pv_entry</literal> represents one
 	    pte).  This means that when we need to remove all hardware
 	    references to a <literal>vm_page</literal> (in order to reuse the
 	    page for something else, page it out, clear it, dirty it, and so
 	    forth) we can simply scan the linked list of
 	    <literal>pv_entry</literal>'s associated with that
 	    <literal>vm_page</literal> to remove or modify the pte's from
 	    their page tables.</para>
 
 	  <para>Under Linux there is no such linked list.  In order to remove
 	    all the hardware page table mappings for a
 	    <literal>vm_page</literal> linux must index into every VM object
 	    that <emphasis>might</emphasis> have mapped the page.  For
 	    example, if you have 50 processes all mapping the same shared
 	    library and want to get rid of page X in that library, you need to
 	    index into the page table for each of those 50 processes even if
 	    only 10 of them have actually mapped the page.  So Linux is
 	    trading off the simplicity of its design against performance.
 	    Many VM algorithms which are O(1) or (small N) under FreeBSD wind
 	    up being O(N), O(N^2), or worse under Linux.  Since the pte's
 	    representing a particular page in an object tend to be at the same
 	    offset in all the page tables they are mapped in, reducing the
 	    number of accesses into the page tables at the same pte offset
 	    will often avoid blowing away the L1 cache line for that offset,
 	    which can lead to better performance.</para>
 
 	  <para>FreeBSD has added complexity (the <literal>pv_entry</literal>
 	    scheme) in order to increase performance (to limit page table
 	    accesses to <emphasis>only</emphasis> those pte's that need to be
 	    modified).</para>
 
 	  <para>But FreeBSD has a scaling problem that Linux does not in that
 	    there are a limited number of <literal>pv_entry</literal>
 	    structures and this causes problems when you have massive sharing
 	    of data.  In this case you may run out of
 	    <literal>pv_entry</literal> structures even though there is plenty
 	    of free memory available.  This can be fixed easily enough by
 	    bumping up the number of <literal>pv_entry</literal> structures in
 	    the kernel config, but we really need to find a better way to do
 	    it.</para>
 
 	  <para>In regards to the memory overhead of a page table verses the
 	    <literal>pv_entry</literal> scheme: Linux uses
 	    &lsquo;permanent&rsquo; page tables that are not throw away, but
 	    does not need a <literal>pv_entry</literal> for each potentially
 	    mapped pte.  FreeBSD uses &lsquo;throw away&rsquo; page tables but
 	    adds in a <literal>pv_entry</literal> structure for each
 	    actually-mapped pte.  I think memory utilization winds up being
 	    about the same, giving FreeBSD an algorithmic advantage with its
 	    ability to throw away page tables at will with very low
 	    overhead.</para>
 	</answer>
       </qandaentry>
 
       <qandaentry>
 	<question>
 	  <para>Finally, in the page coloring section, it might help to have a
 	    little more description of what you mean here.  I didn't quite
 	    follow it.</para>
 	</question>
 
 	<answer>
 	  <para>Do you know how an L1 hardware memory cache works?  I'll
 	    explain: Consider a machine with 16MB of main memory but only 128K
 	    of L1 cache.  Generally the way this cache works is that each 128K
 	    block of main memory uses the <emphasis>same</emphasis> 128K of
 	    cache.  If you access offset 0 in main memory and then offset
 	    offset 128K in main memory you can wind up throwing away the
 	    cached data you read from offset 0!</para>
 
 	  <para>Now, I am simplifying things greatly.  What I just described
 	    is what is called a &lsquo;direct mapped&rsquo; hardware memory
 	    cache.  Most modern caches are what are called
 	    2-way-set-associative or 4-way-set-associative caches.  The
 	    set-associatively allows you to access up to N different memory
 	    regions that overlap the same cache memory without destroying the
 	    previously cached data.  But only N.</para>
 
 	  <para>So if I have a 4-way set associative cache I can access offset
 	    0, offset 128K, 256K and offset 384K and still be able to access
 	    offset 0 again and have it come from the L1 cache.  If I then
 	    access offset 512K, however, one of the four previously cached
 	    data objects will be thrown away by the cache.</para>
 
 	  <para>It is extremely important&hellip;
 	    <emphasis>extremely</emphasis> important for most of a processor's
 	    memory accesses to be able to come from the L1 cache, because the
 	    L1 cache operates at the processor frequency.  The moment you have
 	    an L1 cache miss and have to go to the L2 cache or to main memory,
 	    the processor will stall and potentially sit twiddling its fingers
 	    for <emphasis>hundreds</emphasis> of instructions worth of time
 	    waiting for a read from main memory to complete.  Main memory (the
 	    dynamic ram you stuff into a computer) is
 	    <emphasis>slow</emphasis>, when compared to the speed of a modern
 	    processor core.</para>
 
 	  <para>Ok, so now onto page coloring: All modern memory caches are
 	    what are known as <emphasis>physical</emphasis> caches.  They
 	    cache physical memory addresses, not virtual memory addresses.
 	    This allows the cache to be left alone across a process context
 	    switch, which is very important.</para>
 
-	  <para>But in the UNIX world you are dealing with virtual address
+	  <para>But in the Unix world you are dealing with virtual address
 	    spaces, not physical address spaces.  Any program you write will
 	    see the virtual address space given to it.  The actual
 	    <emphasis>physical</emphasis> pages underlying that virtual
 	    address space are not necessarily physically contiguous! In fact,
 	    you might have two pages that are side by side in a processes
 	    address space which wind up being at offset 0 and offset 128K in
 	    <emphasis>physical</emphasis> memory.</para>
 
 	  <para>A program normally assumes that two side-by-side pages will be
 	    optimally cached.  That is, that you can access data objects in
 	    both pages without having them blow away each other's cache entry.
 	    But this is only true if the physical pages underlying the virtual
 	    address space are contiguous (insofar as the cache is
 	    concerned).</para>
 
 	  <para>This is what Page coloring does.  Instead of assigning
 	    <emphasis>random</emphasis> physical pages to virtual addresses,
 	    which may result in non-optimal cache performance , Page coloring
 	    assigns <emphasis>reasonably-contiguous</emphasis> physical pages
 	    to virtual addresses.  Thus programs can be written under the
 	    assumption that the characteristics of the underlying hardware
 	    cache are the same for their virtual address space as they would
 	    be if the program had been run directly in a physical address
 	    space.</para>
 
 	  <para>Note that I say &lsquo;reasonably&rsquo; contiguous rather
 	    than simply &lsquo;contiguous&rsquo;.  From the point of view of a
 	    128K direct mapped cache, the physical address 0 is the same as
 	    the physical address 128K.  So two side-by-side pages in your
 	    virtual address space may wind up being offset 128K and offset
 	    132K in physical memory, but could also easily be offset 128K and
 	    offset 4K in physical memory and still retain the same cache
 	    performance characteristics.  So page-coloring does
 	    <emphasis>not</emphasis> have to assign truly contiguous pages of
 	    physical memory to contiguous pages of virtual memory, it just
 	    needs to make sure it assigns contiguous pages from the point of
 	    view of cache performance and operation.</para>
 	</answer>
       </qandaentry>
     </qandaset>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/articles/zip-drive/article.sgml b/en_US.ISO8859-1/articles/zip-drive/article.sgml
index 4e1aeeacaa..a13c8430c1 100644
--- a/en_US.ISO8859-1/articles/zip-drive/article.sgml
+++ b/en_US.ISO8859-1/articles/zip-drive/article.sgml
@@ -1,267 +1,267 @@
 <!-- $FreeBSD -->
 
 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 ]>
 
 <article>
   <articleinfo>
     <title>ZIP Drives</title>
 
     <authorgroup>
       <author>
 	<firstname>Jason</firstname>
 	<surname>Bacon</surname>
 	
 	<affiliation>
 	  <address><email>acadix@execpc.com</email></address>
 	</affiliation>
       </author>
     </authorgroup>
   </articleinfo>
 
   <sect1>
     <title>ZIP Drive Basics</title>
 
     <para>ZIP disks are high capacity, removable, magnetic disks, which can be
       read or written by ZIP drives from iomega corporation.  ZIP disks are
       similar to floppy disks, except that they are much faster, and have a
       much greater capacity.  While floppy disks typically hold 1.44
       megabytes, ZIP disks are available in two sizes, namely 100 megabytes
       and 250 megabytes.  ZIP drives should not be confused with the
       super-floppy, a 120 megabyte floppy drive which also handles traditional
       1.44 megabyte floppies.</para>
 
     <para>IOMEGA also sells a higher capacity, higher performance drive
       called the JAZZ drive.  JAZZ drives come in 1 gigabyte and
       2 gigabyte sizes.</para>
 
     <para>ZIP drives are available as internal or external units, using one
     of three interfaces:</para>
     
     <orderedlist>
       <listitem>
 	<para>The SCSI (Small Computer Standard Interface) interface is the
 	  fastest, most sophisticated, most expandable, and most expensive
 	  interface.  The SCSI interface is used by all types of computers
 	  from PC's to RISC workstations to minicomputers, to connect all
 	  types of peripherals such as disk drives, tape drives, scanners, and
 	  so on.  SCSI ZIP drives may be internal or external, assuming your
 	  host adapter has an external connector.</para>
 	
 	<note>
 	  <para>If you are using an external SCSI device, it is important
 	    never to connect or disconnect it from the SCSI bus while the
 	    computer is running.  Doing so may cause file-system damage on the
 	    disks that remain connected.</para>
 	</note>
 	
 	<para>If you want maximum performance and easy setup, the SCSI
 	  interface is the best choice.  This will probably require adding a
 	  SCSI host adapter, since most PC's (except for high-performance
 	  servers) don't have built-in SCSI support.  Each SCSI host adapter
 	  can support either 7 or 15 SCSI devices, depending on the
 	  model.</para>
 	
 	<para>Each SCSI device has it's own controller, and these
 	  controllers are fairly intelligent and well standardized, (the
 	  second `S' in SCSI is for Standard) so from the operating system's
 	  point of view, all SCSI disk drives look about the same, as do all
 	  SCSI tape drives, etc.  To support SCSI devices, the operating
 	  system need only have a driver for the particular host adapter, and
 	  a generic driver for each type of device, i.e. a SCSI disk driver,
 	  SCSI tape driver, and so on.  There are some SCSI devices that can
 	  be better utilized with specialized drivers (e.g. DAT tape drives),
 	  but they tend to work OK with the generic driver, too.  It's just
 	  that the generic drivers may not support some of the special
 	  features.</para>
 	
 	<para>Using a SCSI zip drive is simply a matter of determining which
 	  device file in the <filename>/dev</filename> directory represents
 	  the ZIP drive. This can be determined by looking at the boot
 	  messages while FreeBSD is booting (or in
 	  <filename>/var/log/messages</filename> after booting), where you'll
 	  see a line something like this:</para>
 	
 	<programlisting>da1: &lt;IOMEGA ZIP 100 D.13&gt; Removable Direct Access SCSI-2 Device</programlisting>
 
 	<para>This means that the ZIP drive is represented by the file
 	  <filename>/dev/da1</filename>.</para>
       </listitem>
 
       <listitem>
 	 <para>The IDE (Integrated Drive Electronics) interface is a low-cost
 	  disk drive interface used by many desktop PC's.  Most IDE devices
 	  are strictly internal.</para>
 
 	<para>Performance of IDE ZIP drives is comparable to SCSI ZIP drives.
 	  (The IDE interface is not as fast as SCSI, but ZIP drives
 	  performance is limited mainly by the mechanics of the drive, not by
 	  the bus interface.)</para>
 	
 	<para>The drawback of the IDE interface is the limitations it imposes.
 	  Most IDE adapters can only support 2 devices, and IDE interfaces are
 	  not typically designed for the long term. For example, the original
 	  IDE interface would not support hard disks with more than 1024
 	  cylinders, which forced a lot of people to upgrade their hardware
 	  prematurely.  If you have plans to expand your PC by adding another
 	  disk, a tape drive, or scanner, you may want to invest in a SCSI
 	  host adapter and a SCSI ZIP drive to avoid problems in the
 	  future.</para>
 
 	<para>IDE devices in FreeBSD are prefixed with a <literal>w</literal>.
 	  For example, an IDE hard disk might be
-	  <filename>/dev/wd0</filename>, an IDE (ATAPI) cdrom might be
+	  <filename>/dev/wd0</filename>, an IDE (ATAPI) CDROM might be
 	  <filename>/dev/wcd1</filename>, and so on.</para>
       </listitem>
 
       <listitem>
 	<para>The parallel port interface is popular for portable external
 	  devices such as external ZIP drives and scanners, because virtually
 	  every computer has a standard parallel port (usually used for
 	  printers).  This makes things easy for people to transfer data
 	  between multiple computers by toting around their ZIP drive.</para>
 
 	<para>Performance will generally be slower than a SCSI or IDE ZIP
 	drive, since it is limited by the speed of the parallel port.
 	Parallel port speed varies considerably between various computers,
 	and can often be configured in the system BIOS.  Some machines
 	will also require BIOS configuration to operate the parallel
 	port in bidirectional mode.  (Parallel ports were originally
 	designed only for output to printers)</para>
       </listitem>
     </orderedlist>
   </sect1>
 
   <sect1>
     <title>Parallel ZIP: The <devicename>vpo</devicename> Driver</title>
 
     <para>To use a parallel-port ZIP drive under FreeBSD, the
       <devicename>vpo</devicename> driver must be configured into the kernel.
       Parallel port ZIP drives also have a built-in SCSI controller. The vpo
       driver allows the FreeBSD kernel to communicate with the ZIP drive's
       SCSI controller through the parallel port.</para>
     
     <para>Since the vpo driver is not a standard part of the kernel (as of
       FreeBSD 3.2), you will need to rebuild the kernel to enable this device.
       The process of building a kernel is outlined in detail in another
       section.  The following steps outline the process in brief for the
       purpose of enabling the vpo driver:</para>
     
     <orderedlist>
       <listitem>
 	<para>Run <command>/stand/sysinstall</command>, and install the kernel
 	  source code on your system.</para>
 
 	<screen>&prompt.root; <userinput>cd /sys/i386/conf</userinput>
 &prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
 
 	<para>Edit <filename>MYKERNEL</filename>, change the
 	  <literal>ident</literal> line to <literal>MYKERNEL</literal>, and
 	  uncomment the line describing the vpo driver.</para>
 	
 	<para>If you have a second parallel port, you may need to copy the
 	  section for <literal>ppc0</literal> to create a
 	  <literal>ppc1</literal> device.  The second parallel port usually
 	  uses IRQ 5 and address 378.  Only the IRQ is required in the config
 	  file.</para>
 
 	<para>If you're root hard disk is a SCSI disk, you might run into a
 	  problem with probing order, which will cause the system to attempt
 	  to use the ZIP drive as the root device.  This will cause a boot
 	  failure, unless you happen to have a FreeBSD root file-system on
 	  your ZIP disk!  In this case, you will need to <quote>wire
 	    down</quote> the root disk, i.e. force the kernel to bind a
 	  specific device to <filename>/dev/da0</filename>, the root SCSI
 	  disk.  It will then assign the ZIP disk to the next available SCSI
 	  disk, e.g. <literal>/dev/da1</literal>. To wire down your SCSI hard
 	  drive as <literal>da0</literal>, change the line
 
 	  <programlisting>device  da0</programlisting>
 
 	  to
 
 	  <programlisting>disk da0 at scbus0 target 0 unit 0</programlisting></para>
 
 	<para>You may need to change the target above to match the SCSI ID of
 	  your disk drive. You should also wire down the scbus0 entry to your
 	  controller.  For example, if you have an Adaptec 15xx controller,
 	  you would change
 	  
 	  <programlisting>controller scbus0</programlisting>
 
 	  to
 
 	  <programlisting>controller scbus0 at aha0</programlisting></para>
 
 	<para>Lastly, as long as you're editing the kernel config, you
 	  can take the opportunity to remove all the unnecessary drivers. This
 	  should be done with a great deal of caution, and only if you feel
 	  confident about making kernel modifications. Removing unnecessary
 	  drivers will reduce the kernel size, leaving more memory available
 	  for your applications.  To determine which drivers are not needed,
 	  go to the end of the file <filename>/var/log/messages</filename>, and look for lines
 	  reading "not found". Then, comment out these devices in your config
 	  file. You can also change other options to reduce the size and
 	  increase the speed of your kernel. Read the section on rebuilding
 	  your kernel for more complete information.</para>
       </listitem>
 
       <listitem>
 	<para>Now it's time to compile the kernel:</para>
 
 	<screen>&prompt.root; <userinput>/usr/sbin/config MYKERNEL</userinput>
 &prompt.root; <userinput>cd ../../compile/MYKERNEL</userinput>	  
 &prompt.root; <userinput>make clean depend && make all install</userinput></screen>
       </listitem>
     </orderedlist>
     
     <para>After the kernel is rebuilt, you'll need to reboot.  Make sure the
       ZIP drive is connected to the parallel port before the boot begins. You
       should see the ZIP drive show up in the boot messages as device vpo0 or
       vpo1, depending on which parallel port the drive is attached to.  It
       should also show which device file the ZIP drive has been bound to. This
       will be <filename>/dev/da0</filename> if you have no other SCSI disks in
       the system, or <filename>/dev/da1</filename> if you have a SCSI hard
       disk wired down as the root device.</para>
   </sect1>
 
   <sect1>
     <title>Mounting ZIP disks</title>
 
     <para>To access the ZIP disk, you simply mount it like any other disk
       device. The file-system is represented as slice 4 on the device, so for
       SCSI or parallel ZIP disks, you would use:</para>
     
     <screen>&prompt.root; <userinput>mount_msdos /dev/da1s4 /mnt</userinput></screen>
 
     <para>For IDE ZIP drives, use:</para>
     
     <screen>&prompt.root; <userinput>mount_msdos /dev/wd1s4 /mnt</userinput></screen>
 
     <para>It will also be helpful to update <filename>/etc/fstab</filename> to
       make mounting easier. Add a line like the following, edited to suit your
       system:
     
       <programlisting>/dev/da1s4  /zip msdos rw,noauto  0 0</programlisting>
     
       and create the directory <filename>/zip</filename>.</para>
     
     <para>Then, you can mount simply by typing 
 
       <screen>&prompt.root; <userinput>mount /zip</userinput></screen>
 
       and unmount by typing
 
       <screen>&prompt.root; <userinput>umount /zip</userinput></screen></para>
 
     <para>For more information on the format of
       <filename>/etc/fstab</filename>, see &man.fstab.5;.</para>
     
     <para>You can also create a FreeBSD file-system on the ZIP disk
     using &man.newfs.8;.  However, the disk will only be usable on a FreeBSD
     system, or perhaps a few other Unix clones that recognize FreeBSD
     file-systems.  (Definitely not DOS or Windows.)</para>
   </sect1>
 </article>
diff --git a/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml
index c68a55d85c..96f68a88c5 100644
--- a/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml
@@ -1,2479 +1,2479 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD$
+     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml,v 1.1 2001/05/02 01:56:01 murray Exp $
 -->
 
 <chapter id="isa-driver">
   <title>ISA device drivers</title>
 
   <para>
     <emphasis> 
       This chapter was written by &a.babkin; Modifications for the
       handbook made by &a.murray;, &a.wylie;, and &a.logo;.
     </emphasis>
   </para>
 
   <sect1>
     <title>Synopsis</title>
 
     <para>This chapter introduces the issues relevant to writing a
       driver for an ISA device.  The pseudo-code presented here is
       rather detailed and reminiscent of the real code but is still
       only pseudo-code. It avoids the details irrelevant to the
       subject of the discussion. The real-life examples can be found
       in the source code of real drivers. In particular the drivers
       "ep" and "aha" are good sources of information.</para>
   </sect1>
 
   <sect1>
     <title>Basic information</title>
 
     <para>A typical ISA driver would need the following include
       files:</para>
 
 <programlisting>#include &lt;sys/module.h&gt;
 #include &lt;sys/bus.h&gt;
 #include &lt;machine/bus.h&gt;
 #include &lt;machine/resource.h&gt;
 #include &lt;sys/rman.h&gt;
 
 #include &lt;isa/isavar.h&gt;
 #include &lt;isa/pnpvar.h&gt;</programlisting>
 
     <para>They describe the things specific to the ISA and generic
       bus subsystem.</para>
 
     <para>The bus subsystem is implemented in an object-oriented
       fashion, its main structures are accessed by associated method
       functions.</para>
 
     <para>The list of bus methods implemented by an ISA driver is like
       one for any other bus. For a hypothetical driver named "xxx"
       they would be:</para>
 
     <itemizedlist>
       <listitem>
         <para><function>static void xxx_isa_identify (driver_t *,
           device_t);</function> Normally used for bus drivers, not
           device drivers. But for ISA devices this method may have
           special use: if the device provides some device-specific
           (non-PnP) way to auto-detect devices this routine may
           implement it.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_probe (device_t
           dev);</function> Probe for a device at a known (or PnP)
           location. This routine can also accommodate device-specific
           auto-detection of parameters for partially configured
           devices.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_attach (device_t
           dev);</function> Attach and initialize device.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_detach (device_t
           dev);</function> Detach device before unloading the driver
           module.</para>
       </listitem>
 
       <listitem>
         <para><function>static int xxx_isa_shutdown (device_t
           dev);</function> Execute shutdown of the device before
           system shutdown.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_suspend (device_t
           dev);</function> Suspend the device before the system goes
           to the power-save state. May also abort transition to the
           power-save state.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_resume (device_t
  	  dev);</function> Resume the device activity after return
  	  from power-save state.</para>
       </listitem>
 
     </itemizedlist>
 
     <para><function>xxx_isa_probe()</function> and
       <function>xxx_isa_attach()</function> are mandatory, the rest of
       the routines are optional, depending on the device's
       needs.</para>
 
     <para>The driver is linked to the system with the following set of
       descriptions.</para>
 
 <programlisting>    /* table of supported bus methods */
     static device_method_t xxx_isa_methods[] = {
         /* list all the bus method functions supported by the driver */
         /* omit the unsupported methods */
         DEVMETHOD(device_identify,  xxx_isa_identify),
         DEVMETHOD(device_probe,     xxx_isa_probe),
         DEVMETHOD(device_attach,    xxx_isa_attach),
         DEVMETHOD(device_detach,    xxx_isa_detach),
         DEVMETHOD(device_shutdown,  xxx_isa_shutdown),
         DEVMETHOD(device_suspend,   xxx_isa_suspend),
         DEVMETHOD(device_resume,    xxx_isa_resume),
 
 	{ 0, 0 }
     };
 
     static driver_t xxx_isa_driver = {
         "xxx",
         xxx_isa_methods,
         sizeof(struct xxx_softc),
     };
 
 
     static devclass_t xxx_devclass;
 
     DRIVER_MODULE(xxx, isa, xxx_isa_driver, xxx_devclass,
         load_function, load_argument);</programlisting>
 
       <para>Here struct <structname>xxx_softc</structname> is a
         device-specific structure that contains private driver data
         and descriptors for the driver's resources.  The bus code
         automatically allocates one softc descriptor per device as
         needed.</para>
 
       <para>If the driver is implemented as a loadable module then
         <function>load_function()</function> is called to do
         driver-specific initialization or clean-up when the driver is
         loaded or unloaded and load_argument is passed as one of its
         arguments.  If the driver does not support dynamic loading (in
         other words it must always be linked into kernel) then these
         values should be set to 0 and the last definition would look
         like:</para>
 
       <programlisting> DRIVER_MODULE(xxx, isa, xxx_isa_driver,
        xxx_devclass, 0, 0);</programlisting>
 
       <para>If the driver is for a device which supports PnP then a
         table of supported PnP IDs must be defined.  The table
         consists of a list of PnP IDs supported by this driver and
         human-readable descriptions of the hardware types and models
         having these IDs. It looks like:</para>
 
 <programlisting>    static struct isa_pnp_id xxx_pnp_ids[] = {
         /* a line for each supported PnP ID */
         { 0x12345678,   "Our device model 1234A" },
         { 0x12345679,   "Our device model 1234B" },
         { 0,        NULL }, /* end of table */
     };</programlisting>
 
       <para>If the driver does not support PnP devices it still needs
         an empty PnP ID table, like:</para>
 
 <programlisting>    static struct isa_pnp_id xxx_pnp_ids[] = {
         { 0,        NULL }, /* end of table */
     };</programlisting>
 
     </sect1>
 
     <sect1>
       <title>Device_t pointer</title>
 
       <para><structname>Device_t</structname> is the pointer type for
 	the device structure. Here we consider only the methods
 	interesting from the device driver writer's standpoint.  The
 	methods to manipulate values in the device structure
 	are:</para>
 
       <itemizedlist>
 
         <listitem><para><function>device_t
 	  device_get_parent(dev)</function> Get the parent bus of a
 	  device.</para></listitem>
 
         <listitem><para><function>driver_t
 	  device_get_driver(dev)</function> Get pointer to its driver
 	  structure.</para></listitem>
 
 	<listitem><para><function>char
 	  *device_get_name(dev)</function> Get the driver name, such
 	  as "xxx" for our example.</para></listitem>
 
 	<listitem><para><function>int device_get_unit(dev)</function>
 	  Get the unit number (units are numbered from 0 for the
 	  devices associated with each driver).</para></listitem>
 
 	<listitem><para><function>char
 	  *device_get_nameunit(dev)</function> Get the device name
 	  including the unit number, such as "xxx0" , "xxx1" and so
 	  on.</para></listitem>
 
 	<listitem><para><function>char
 	  *device_get_desc(dev)</function> Get the device
 	  description. Normally it describes the exact model of device
 	  in human-readable form.</para></listitem>
 
 	<listitem><para><function>device_set_desc(dev,
 	  desc)</function> Set the description. This makes the device
 	  description point to the string desc which may not be
 	  deallocated or changed after that.</para></listitem>
 
 	<listitem><para><function>device_set_desc_copy(dev,
 	  desc)</function> Set the description. The description is
 	  copied into an internal dynamically allocated buffer, so the
 	  string desc may be changed afterwards without adverse
 	  effects.</para></listitem>
 
 	<listitem><para><function>void
 	  *device_get_softc(dev)</function> Get pointer to the device
 	  descriptor (struct <structname>xxx_softc</structname>)
 	  associated with this device.</para></listitem>
 
 	<listitem><para><function>u_int32_t
 	  device_get_flags(dev)</function> Get the flags specified for
 	  the device in the configuration file.</para></listitem>
 
       </itemizedlist>
 
       <para>A convenience function <function>device_printf(dev, fmt,
 	...)</function> may be used to print the messages from the
 	device driver. It automatically prepends the unitname and
 	colon to the message.</para>
 
       <para>The device_t methods are implemented in the file
         kern/bus_subr.c.</para>
 
     </sect1>
 
     <sect1>
       <title>Config file and the order of identifying and probing
 	during auto-configuration</title>
 
       <para>The ISA devices are described in the kernel config file
   	like:</para>
 
       <programlisting>device xxx0 at isa? port 0x300 irq 10 drq 5
        iomem 0xd0000 flags 0x1 sensitive</programlisting>
 
       <para>The values of port, IRQ and so on are converted to the
 	resource values associated with the device. They are optional,
 	depending on the device needs and abilities for
 	auto-configuration. For example, some devices don't need DRQ
 	at all and some allow the driver to read the IRQ setting from
 	the device configuration ports. If a machine has multiple ISA
 	buses the exact bus may be specified in the configuration
 	line, like "isa0" or "isa1", otherwise the device would be
 	searched for on all the ISA buses.</para>
 
       <para>"sensitive" is a resource requesting that this device must
 	be probed before all non-sensitive devices. It is supported
 	but does not seem to be used in any current driver.</para>
 
       <para>For legacy ISA devices in many cases the drivers are still
 	able to detect the configuration parameters. But each device
 	to be configured in the system must have a config line. If two
 	devices of some type are installed in the system but there is
 	only one configuration line for the corresponding driver, ie:
 	<programlisting>device xxx0 at isa?</programlisting> then only
 	one device will be configured.</para>
 
       <para>But for the devices supporting automatic identification by
 	the means of Plug-n-Play or some proprietary protocol one
 	configuration line is enough to configure all the devices in
 	the system, like the one above or just simply:</para>
 
       <programlisting>device xxx at isa?</programlisting>
 
       <para>If a driver supports both auto-identified and legacy
 	devices and both kinds are installed at once in one machine
 	then it's enough to describe in the config file the legacy
 	devices only. The auto-identified devices will be added
 	automatically.</para>
 
       <para>When an ISA bus is auto-configured the events happen as
   	follows:</para>
 
       <para>All the drivers' identify routines (including the PnP
 	identify routine which identifies all the PnP devices) are
 	called in random order.  As they identify the devices they add
 	them to the list on the ISA bus.  Normally the drivers'
 	identify routines associate their drivers with the new
 	devices. The PnP identify routine does not know about the
 	other drivers yet so it does not associate any with the new
 	devices it adds.</para>
 
       <para>The PnP devices are put to sleep using the PnP protocol to
         prevent them from being probed as legacy devices.</para>
 
       <para>The probe routines of non-PnP devices marked as
         "sensitive" are called.  If probe for a device went
         successfully, the attach routine is called for it.</para>
 
       <para>The probe and attach routines of all non-PNP devices are
   	called likewise.</para>
 
       <para>The PnP devices are brought back from the sleep state and
         assigned the resources they request: I/O and memory address
         ranges, IRQs and DRQs, all of them not conflicting with the
         attached legacy devices.</para>
 
       <para>Then for each PnP device the probe routines of all the
         present ISA drivers are called. The first one that claims the
         device gets attached.  It is possible that multiple drivers
         would claim the device with different priority, the
         highest-priority driver wins.  The probe routines must call
         <function>ISA_PNP_PROBE()</function> to compare the actual PnP
         ID with the list of the IDs supported by the driver and if the
         ID is not in the table return failure. That means that
         absolutely every driver, even the ones not supporting any PnP
         devices must call <function>ISA_PNP_PROBE()</function>, at
         least with an empty PnP ID table to return failure on unknown
         PnP devices.</para>
 
       <para>The probe routine returns a positive value (the error
         code) on error, zero or negative value on success.</para>
 
       <para>The negative return values are used when a PnP device
         supports multiple interfaces. For example, an older
         compatibility interface and a newer advanced interface which
         are supported by different drivers. Then both drivers would
         detect the device. The driver which returns a higher value in
         the probe routine takes precedence (in other words, the driver
         returning 0 has highest precedence, returning -1 is next,
         returning -2 is after it and so on). In result the devices
         which support only the old interface will be handled by the
         old driver (which should return -1 from the probe routine)
         while the devices supporting the new interface as well will be
         handled by the new driver (which should return 0 from the
         probe routine). If multiple drivers return the same value then
         the one called first wins. So if a driver returns value 0 it
         may be sure that it won the priority arbitration.</para>
 
       <para>The device-specific identify routines can also assign not
         a driver but a class of drivers to the device. Then all the
         drivers in the class are probed for this device, like the case
         with PnP. This feature is not implemented in any existing
         driver and is not considered further in this document.</para>
 
       <para>Because the PnP devices are disabled when probing the
         legacy devices they will not be attached twice (once as legacy
         and once as PnP).  But in case of device-dependent identify
         routines it's the responsibility of the driver to make sure
         that the same device won't be attached by the driver twice:
         once as legacy user-configured and once as
         auto-identified.</para>
 
       <para>Another practical consequence for the auto-identified
         devices (both PnP and device-specific) is that the flags can
         not be passed to them from the kernel configuration file. So
         they must either not use the flags at all or use the flags
         from the device unit 0 for all the auto-identified devices or
         use the sysctl interface instead of flags.</para>
 
       <para>Other unusual configurations may be accommodated by
         accessing the configuration resources directly with functions
         of families <function>resource_query_*()</function> and
         <function>resource_*_value()</function>. Their implementations
         are located in kern/subr_bus.h. The old IDE disk driver
         i386/isa/wd.c contains examples of such use. But the standard
         means of configuration must always be preferred. Leave parsing
         the configuration resources to the bus configuration
         code.</para>
 
     </sect1>
 
     <sect1>
       <title>Resources</title>
 
       <para>The information that a user enters into the kernel
         configuration file is processed and passed to the kernel as
         configuration resources. This information is parsed by the bus
         configuration code and transformed into a value of structure
         device_t and the bus resources associated with it. The drivers
         may access the configuration resources directly using
         functions resource_* for more complex cases of
         configuration. But generally it's not needed nor recommended,
         so this issue is not discussed further.</para>
 
       <para>The bus resources are associated with each device. They
         are identified by type and number within the type. For the ISA
         bus the following types are defined:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><emphasis>SYS_RES_IRQ</emphasis> - interrupt
 	    number</para>
 	</listitem>
 
 	<listitem>
 	  <para><emphasis>SYS_RES_DRQ</emphasis> - ISA DMA channel
 	    number</para>
 	</listitem>
 
 	<listitem>
 	  <para><emphasis>SYS_RES_MEMORY</emphasis> - range of
 	    device memory mapped into the system memory space
 	  </para>
 	</listitem>
 
 	<listitem>
 	  <para><emphasis>SYS_RES_IOPORT</emphasis> - range of
 	    device I/O registers</para>
         </listitem>
       </itemizedlist>
 
       <para>The enumeration within types starts from 0, so if a device
         has two memory regions if would have resources of type
         SYS_RES_MEMORY numbered 0 and 1.  The resource type has
         nothing to do with the C language type, all the resource
         values have the C language type "unsigned long" and must be
         cast as necessary. The resource numbers don't have to be
         contiguous although for ISA they normally would be. The
         permitted resource numbers for ISA devices are:</para>
 
       <programlisting>          IRQ: 0-1
           DRQ: 0-1
           MEMORY: 0-3
           IOPORT: 0-7</programlisting>
 
       <para>All the resources are represented as ranges, with a start
         value and count.  For IRQ and DRQ resources the count would be
         normally equal to 1. The values for memory refer to the
         physical addresses.</para>
 
       <para>Three types of activities can be performed on
         resources:</para>
 
       <itemizedlist>
 	<listitem><para>set/get</para></listitem>
 	<listitem><para>allocate/release</para></listitem>
 	<listitem><para>activate/deactivate</para></listitem>
       </itemizedlist>
 
       <para>Setting sets the range used by the resource. Allocation
         reserves the requested range that no other driver would be
         able to reserve it (and checking that no other driver reserved
         this range already). Activation makes the resource accessible
         to the driver doing whatever is necessary for that (for
         example, for memory it would be mapping into the kernel
         virtual address space).</para>
 
       <para>The functions to manipulate resources are:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><function>int bus_set_resource(device_t dev, int type,
             int rid, u_long start, u_long count)</function></para>
 
           <para>Set a range for a resource. Returns 0 if successful,
             error code otherwise.  Normally the only reason this
             function would return an error is value of type, rid,
             start or count out of permitted range.</para>
 
           <itemizedlist>
             <listitem>
               <para> dev - driver's device</para>
             </listitem>
             <listitem>
               <para> type - type of resource, SYS_RES_* </para>
             </listitem>
             <listitem>
               <para> rid - resource number (ID) within type </para>
             </listitem>
             <listitem>
               <para> start, count - resource range </para>
             </listitem>
           </itemizedlist>
         </listitem>
 
         <listitem>
           <para><function>int bus_get_resource(device_t dev, int type,
           int rid, u_long *startp, u_long *countp)</function></para>
 
           <para>Get the range of resource. Returns 0 if successful,
             error code if the resource is not defined yet.</para>
         </listitem>
 
         <listitem>
 	  <para><function>u_long bus_get_resource_start(device_t dev,
             int type, int rid) u_long bus_get_resource_count (device_t
             dev, int type, int rid)</function></para>
 
           <para>Convenience functions to get only the start or
             count. Return 0 in case of error, so if the resource start
             has 0 among the legitimate values it would be impossible
             to tell if the value is 0 or an error occurred.  Luckily,
             no ISA resources for add-on drivers may have a start value
             equal 0.</para>
         </listitem>
 
         <listitem>
           <para><function>void bus_delete_resource(device_t dev, int
             type, int rid)</function></para>
           <para> Delete a resource, make it undefined.</para>
         </listitem>
 
         <listitem>
           <para><function>struct resource *
             bus_alloc_resource(device_t dev, int type, int *rid,
             u_long start, u_long end, u_long count, u_int
             flags)</function></para>
 
           <para>Allocate a resource as a range of count values not
             allocated by anyone else, somewhere between start and
             end. Alas, alignment is not supported.  If the resource
             was not set yet it's automatically created. The special
             values of start 0 and end ~0 (all ones) means that the
             fixed values previously set by
             <function>bus_set_resource()</function> must be used
             instead: start and count as themselves and
             end=(start+count), in this case if the resource was not
             defined before then an error is returned.  Although rid is
             passed by reference it's not set anywhere by the resource
             allocation code of the ISA bus. (The other buses may use a
             different approach and modify it).</para>
         </listitem>
       </itemizedlist>
 
       <para>Flags are a bitmap, the flags interesting for the caller
         are:</para>
 
       <itemizedlist>
         <listitem>
           <para><emphasis>RF_ACTIVE</emphasis> - causes the resource
             to be automatically activated after allocation.</para>
         </listitem>
 
         <listitem>
           <para><emphasis>RF_SHAREABLE</emphasis> - resource may be
             shared at the same time by multiple drivers.</para>
         </listitem>
 
         <listitem>
           <para><emphasis>RF_TIMESHARE</emphasis> - resource may be
             time-shared by multiple drivers, i.e. allocated at the
             same time by many but activated only by one at any given
             moment of time.</para>
         </listitem>
 <!-- XXXDONT KNOW IT THESE SHOULD BE TWO SEPERATE LISTS OR NOT -->
         <listitem>
           <para>Returns 0 on error. The allocated values may be
             obtained from the returned handle using methods
             <function>rhand_*()</function>.</para>
         </listitem>
         <listitem>
           <para><function>int bus_release_resource(device_t dev, int
             type, int rid, struct resource *r)</function></para>
 	</listitem>
 
         <listitem>
           <para>Release the resource, r is the handle returned by
             <function>bus_alloc_resource()</function>.  Returns 0 on
             success, error code otherwise.</para>
         </listitem>
 
         <listitem>
           <para><function>int bus_activate_resource(device_t dev, int
             type, int rid, struct resource *r)</function>
             <function>int bus_deactivate_resource(device_t dev, int
             type, int rid, struct resource *r)</function></para>
         </listitem>
 
         <listitem>
           <para>Activate or deactivate resource. Return 0 on success,
             error code otherwise.  If the resource is time-shared and
             currently activated by another driver then EBUSY is
             returned.</para>
         </listitem>
 
         <listitem>
           <para><function>int bus_setup_intr(device_t dev, struct
             resource *r, int flags, driver_intr_t *handler, void *arg,
             void **cookiep)</function> <function>int
             bus_teardown_intr(device_t dev, struct resource *r, void
             *cookie)</function></para>
         </listitem>
 
         <listitem>
           <para>Associate or de-associate the interrupt handler with a
             device. Return 0 on success, error code otherwise.</para>
         </listitem>
 
         <listitem>
           <para>r - the activated resource handler describing the
             IRQ</para>
 	  <para>flags - the interrupt priority level, one of:</para>
 
           <itemizedlist>
             <listitem>
               <para><function>INTR_TYPE_TTY</function> - terminals and
                 other likewise character-type devices. To mask them
                 use <function>spltty()</function>.</para>
             </listitem>
             <listitem>
               <para><function>(INTR_TYPE_TTY |
                 INTR_TYPE_FAST)</function> - terminal type devices
                 with small input buffer, critical to the data loss on
                 input (such as the old-fashioned serial ports). To
                 mask them use <function>spltty()</function>.</para>
             </listitem>
             <listitem>
               <para><function>INTR_TYPE_BIO</function> - block-type
                 devices, except those on the CAM controllers. To mask
                 them use <function>splbio()</function>.</para>
             </listitem>
             <listitem>
               <para><function>INTR_TYPE_CAM</function> - CAM (Common
                 Access Method) bus controllers. To mask them use
                 <function>splcam()</function>.</para>
              </listitem>
              <listitem>
                <para><function>INTR_TYPE_NET</function> - network
                 interface controllers. To mask them use
                 <function>splimp()</function>.</para>
              </listitem>
              <listitem>
                <para><function>INTR_TYPE_MISC</function> -
                 miscellaneous devices.  There is no other way to mask
                 them than by <function>splhigh()</function> which
                 masks all interrupts.</para>
              </listitem>
           </itemizedlist>
         </listitem>
       </itemizedlist>
 
       <para>When an interrupt handler executes all the other
         interrupts matching its priority level will be masked. The
         only exception is the MISC level for which no other interrupts
         are masked and which is not masked by any other
         interrupt.</para>
 
       <itemizedlist>
         <listitem>
           <para><emphasis>handler</emphasis> - pointer to the handler
             function, the type driver_intr_t is defined as "void
             driver_intr_t(void *)"</para>
         </listitem>
         <listitem>
           <para><emphasis>arg</emphasis> - the argument passed to the
             handler to identify this particular device. It is cast
             from void* to any real type by the handler. The old
             convention for the ISA interrupt handlers was to use the
             unit number as argument, the new (recommended) convention
             is using a pointer to the device softc structure.</para>
         </listitem>
         <listitem>
           <para><emphasis>cookie[p]</emphasis> - the value received
             from <function>setup()</function> is used to identify the
             handler when passed to
             <function>teardown()</function></para>
         </listitem>
       </itemizedlist>
 
       <para>A number of methods is defined to operate on the resource
         handlers (struct resource *). Those of interest to the device
         driver writers are:</para>
 
       <itemizedlist>
         <listitem>
           <para><function>u_long rman_get_start(r) u_long
             rman_get_end(r)</function> Get the start and end of
             allocated resource range.</para>
         </listitem>
         <listitem>
           <para><function>void *rman_get_virtual(r)</function> Get
             the virtual address of activated memory resource.</para>
         </listitem>
       </itemizedlist>
 
     </sect1>
 
     <sect1>
       <title>Bus memory mapping</title>
 
       <para>In many cases data is exchanged between the driver and the
         device through the memory. Two variants are possible:</para>
 
       <para>(a) memory is located on the device card</para>
       <para>(b) memory is the main memory of computer</para>
 
       <para>In the case (a) the driver always copies the data back and
         forth between the on-card memory and the main memory as
         necessary. To map the on-card memory into the kernel virtual
         address space the physical address and length of the on-card
         memory must be defined as a SYS_RES_MEMORY resource. That
         resource can then be allocated and activated, and its virtual
         address obtained using
         <function>rman_get_virtual()</function>.  The older drivers
         used the function <function>pmap_mapdev()</function> for this
         purpose, which should not be used directly any more. Now it's
         one of the internal steps of resource activation.</para>
 
       <para>Most of the ISA cards will have their memory configured
         for physical location somewhere in range 640KB-1MB. Some of
         the ISA cards require larger memory ranges which should be
         placed somewhere under 16MB (because of the 24-bit address
         limitation on the ISA bus). In that case if the machine has
         more memory than the start address of the device memory (in
         other words, they overlap) a memory hole must be configured at
         the address range used by devices. Many BIOSes allow to
         configure a memory hole of 1MB starting at 14MB or
         15MB. FreeBSD can handle the memory holes properly if the BIOS
         reports them properly (old BIOSes may have this feature
         broken).</para>
 
       <para>In the case (b) just the address of the data is sent to
         the device, and the device uses DMA to actually access the
         data in the main memory. Two limitations are present: First,
         ISA cards can only access memory below 16MB.  Second, the
         contiguous pages in virtual address space may not be
         contiguous in physical address space, so the device may have
         to do scatter/gather operations. The bus subsystem provides
         ready solutions for some of these problems, the rest has to be
         done by the drivers themselves.</para>
 
       <para>Two structures are used for DMA memory allocation,
         bus_dma_tag_t and bus_dmamap_t. Tag describes the properties
         required for the DMA memory. Map represents a memory block
         allocated according to these properties. Multiple maps may be
         associated with the same tag.</para>
 
       <para>Tags are organized into a tree-like hierarchy with
         inheritance of the properties. A child tag inherits all the
         requirements of its parent tag or may make them more strict
         but never more loose.</para>
 
       <para>Normally one top-level tag (with no parent) is created for
         each device unit.  If multiple memory areas with different
         requirements are needed for each device then a tag for each of
         them may be created as a child of the parent tag.</para>
 
       <para>The tags can be used to create a map in two ways.</para>
 
       <para>First, a chunk of contiguous memory conformant with the
         tag requirements may be allocated (and later may be
         freed). This is normally used to allocate relatively
         long-living areas of memory for communication with the
         device. Loading of such memory into a map is trivial: it's
         always considered as one chunk in the appropriate physical
         memory range.</para>
 
       <para>Second, an arbitrary area of virtual memory may be loaded
         into a map. Each page of this memory will be checked for
         conformance to the map requirement.  If it conforms then it's
         left at it's original location. If it is not then a fresh
         conformant "bounce page" is allocated and used as intermediate
         storage. When writing the data from the non-conformant
         original pages they will be copied to their bounce pages first
         and then transferred from the bounce pages to the device. When
         reading the data would go from the device to the bounce pages
         and then copied to their non-conformant original pages. The
         process of copying between the original and bounce pages is
         called synchronization. This is normally used on per-transfer
         basis: buffer for each transfer would be loaded, transfer done
         and buffer unloaded.</para>
 
       <para>The functions working on the DMA memory are:</para>
 
       <itemizedlist>
         <listitem>
         <para><function>int bus_dma_tag_create(bus_dma_tag_t parent,
           bus_size_t alignment, bus_size_t boundary, bus_addr_t
           lowaddr, bus_addr_t highaddr, bus_dma_filter_t *filter, void
           *filterarg, bus_size_t maxsize, int nsegments, bus_size_t
           maxsegsz, int flags, bus_dma_tag_t *dmat)</function></para>
 
         <para>Create a new tag. Returns 0 on success, the error code
           otherwise.</para>
 
         <itemizedlist>
 	  <listitem>
             <para><emphasis>parent</emphasis> - parent tag, or NULL to
               create a top-level tag <emphasis>alignment</emphasis> -
               required physical alignment of the memory area to be
               allocated for this tag. Use value 1 for "no specific
               alignment". Applies only to the future
               <function>bus_dmamem_alloc()</function> but not
               <function>bus_dmamap_create()</function> calls.
               <emphasis>boundary</emphasis> - physical address
               boundary that must not be crossed when allocating the
               memory. Use value 0 for "no boundary". Applies only to
               the future <function>bus_dmamem_alloc()</function> but
               not <function>bus_dmamap_create()</function> calls.
               Must be power of 2. If the memory is planned to be used
               in non-cascaded DMA mode (i.e. the DMA addresses will be
               supplied not by the device itself but by the ISA DMA
               controller) then the boundary must be no larger than
               64KB (64*1024) due to the limitations of the DMA
               hardware.</para>
           </listitem>
 
           <listitem>
             <para><emphasis>lowaddr, highaddr</emphasis> - the names
               are slighlty misleading; these values are used to limit
               the permitted range of physical addresses used to
               allocate the memory.  The exact meaning varies depending
               on the planned future use:</para>
 
             <itemizedlist>
               <listitem>
                 <para>For <function>bus_dmamem_alloc()</function> all
                   the addresses from 0 to lowaddr-1 are considered
                   permitted, the higher ones are forbidden.</para>
               </listitem>
 
               <listitem>
                 <para>For <function>bus_dmamap_create()</function> all
                   the addresses outside the inclusive range [lowaddr;
                   highaddr] are considered accessible. The addresses
                   of pages inside the range are passed to the filter
                   function which decides if they are accessible. If no
                   filter function is supplied then all the range is
                   considered unaccessible.</para>
               </listitem>
 
               <listitem>
                 <para>For the ISA devices the normal values (with no
                   filter function) are:</para>
                 <para>lowaddr = BUS_SPACE_MAXADDR_24BIT</para>
                 <para>highaddr = BUS_SPACE_MAXADDR</para>
               </listitem>
             </itemizedlist>
 
           </listitem>
 
           <listitem>
             <para><emphasis>filter, filterarg</emphasis> - the filter
               function and its argument. If NULL is passed for filter
               then the whole range [lowaddr, highaddr] is considered
               unaccessible when doing
               <function>bus_dmamap_create()</function>.  Otherwise the
               physical address of each attempted page in range
               [lowaddr; highaddr] is passed to the filter function
               which decides if it is accessible. The prototype of the
               filter function is: <function>int filterfunc(void *arg,
               bus_addr_t paddr)</function> It must return 0 if the
               page is accessible, non-zero otherwise.</para>
           </listitem>
 
 	  <listitem>
             <para><emphasis>maxsize</emphasis> - the maximal size of
               memory (in bytes) that may be allocated through this
               tag. In case it's difficult to estimate or could be
               arbitrarily big, the value for ISA devices would be
               BUS_SPACE_MAXSIZE_24BIT.</para>
           </listitem>
 
 	  <listitem>
             <para><emphasis>nsegments</emphasis> - maximal number of
               scatter-gather segments supported by the device. If
               unrestricted then the value BUS_SPACE_UNRESTRICTED
               should be used. This value is recommended for the parent
               tags, the actual restrictions would then be specified
               for the descendant tags. Tags with nsegments equal to
               BUS_SPACE_UNRESTRICTED may not be used to actually load
               maps, they may be used only as parent tags. The
               practical limit for nsegments seems to be about 250-300,
               higher values will cause kernel stack overflow.  But
               anyway the hardware normally can't support that many
               scatter-gather buffers.</para>
           </listitem>
 
 	  <listitem>
             <para><emphasis>maxsegsz</emphasis> - maximal size of a
               scatter-gather segment supported by the device. The
               maximal value for ISA device would be
               BUS_SPACE_MAXSIZE_24BIT.</para>
           </listitem>
 
 	  <listitem>
             <para><emphasis>flags</emphasis> - a bitmap of flags. The
               only interesting flags are:</para>
 
 	    <itemizedlist>
 	      <listitem>
                 <para><emphasis>BUS_DMA_ALLOCNOW</emphasis> - requests
                   to allocate all the potentially needed bounce pages
                   when creating the tag</para>
               </listitem>
 
 	      <listitem>
 	        <para><emphasis>BUS_DMA_ISA</emphasis> - mysterious
                   flag used only on Alpha machines. It is not defined
                   for the i386 machines.  Probably it should be used
                   by all the ISA drivers for Alpha machines but it
                   looks like there are no such drivers yet.</para>
               </listitem>
 	    </itemizedlist>
 	  </listitem>
 
           <listitem>
             <para><emphasis>dmat</emphasis> - pointer to the storage
               for the new tag to be returned</para>
           </listitem>
 
 	</itemizedlist>
 
       </listitem>
 
       <listitem> <!-- Second entry in list alpha -->
         <para><function>int bus_dma_tag_destroy(bus_dma_tag_t
 	  dmat)</function></para>
 
         <para>Destroy a tag. Returns 0 on success, the error code
 	  otherwise.</para>
 
         <para>dmat - the tag to be destroyed</para>
 
       </listitem>
 
       <listitem> <!-- Third entry in list alpha -->
         <para><function>int bus_dmamem_alloc(bus_dma_tag_t dmat,
           void** vaddr, int flags, bus_dmamap_t
           *mapp)</function></para>
 
         <para>Allocate an area of contiguous memory described by the
           tag. The size of memory to be allocated is tag's maxsize.
           Returns 0 on success, the error code otherwise. The result
           still has to be loaded by
           <function>bus_dmamap_load()</function> before used to get
           the physical address of the memory.</para>
 
 <!-- XXX What it is Wylie, I got to here -->
 
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - the tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>vaddr</emphasis> - pointer to the storage
                   for the kernel virtual address of the allocated area
                   to be returned.
                  </para>
               </listitem>
               <listitem>
                 <para>
                   flags - a bitmap of flags. The only interesting flag is:
                 </para>
                 <itemizedlist>
                   <listitem>
                     <para>
                       <emphasis>BUS_DMA_NOWAIT</emphasis> - if the
                       memory is not immediately available return the
                       error. If this flag is not set then the routine
                       is allowed to sleep waiting until the memory
                       will become available.
                     </para>
                   </listitem>
                 </itemizedlist>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>mapp</emphasis> - pointer to the storage
                   for the new map to be returned
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
 
           <listitem> <!-- Fourth entry in list alpha -->
             <para>
               <function>void bus_dmamem_free(bus_dma_tag_t dmat, void
               *vaddr, bus_dmamap_t map)</function>
             </para>
             <para>
               Free the memory allocated by
               <function>bus_dmamem_alloc()</function>. As of now
               freeing of the memory allocated with ISA restrictions is
               not implemented.  Because of this the recommended model
               of use is to keep and re-use the allocated areas for as
               long as possible. Do not lightly free some area and then
               shortly allocate it again. That does not mean that
               <function>bus_dmamem_free()</function> should not be
               used at all: hopefully it will be properly implemented
               soon.
             </para>
 
             <itemizedlist>
               <listitem>
                 <para><emphasis>dmat</emphasis> - the tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>vaddr</emphasis> - the kernel virtual
                   address of the memory
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>map</emphasis> - the map of the memory (as
                   returned from
                   <function>bus_dmamem_alloc()</function>)
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
 
           <listitem> <!-- The fifth entry in list alpha -->
             <para>
               <function>int bus_dmamap_create(bus_dma_tag_t dmat, int
               flags, bus_dmamap_t *mapp)</function>
             </para>
             <para>
               Create a map for the tag, to be used in
               <function>bus_dmamap_load()</function> later.  Returns 0
               on success, the error code otherwise.
             </para>
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - the tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>flags</emphasis> - theoretically, a bit map
                   of flags. But no flags are defined yet, so as of now
                   it will be always 0.
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>mapp</emphasis> - pointer to the storage
                   for the new map to be returned
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
 
           <listitem> <!-- Sixth entry in the alpha list -->
             <para>
               <function>int bus_dmamap_destroy(bus_dma_tag_t dmat,
               bus_dmamap_t map)</function>
             </para>
             <para>
               Destroy a map. Returns 0 on success, the error code otherwise.
             </para>
 
             <itemizedlist>
               <listitem>
                 <para>
                   dmat - the tag to which the map is associated
                 </para>
               </listitem>
               <listitem>
                 <para>
                   map - the map to be destroyed
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
 
           <listitem> <!-- Seventh entry in list alpha -->
             <para>
               <function>int bus_dmamap_load(bus_dma_tag_t dmat,
               bus_dmamap_t map, void *buf, bus_size_t buflen,
               bus_dmamap_callback_t *callback, void *callback_arg, int
               flags)</function>
             </para>
             <para>
               Load a buffer into the map (the map must be previously
               created by <function>bus_dmamap_create()</function> or
               <function>bus_dmamem_alloc()</function>).  All the pages
               of the buffer are checked for conformance to the tag
               requirements and for those not conformant the bounce
               pages are allocated. An array of physical segment
               descriptors is built and passed to the callback
               routine. This callback routine is then expected to
               handle it in some way. The number of bounce buffers in
               the system is limited, so if the bounce buffers are
               needed but not immediately available the request will be
               queued and the callback will be called when the bounce
               buffers will become available. Returns 0 if the callback
               was executed immediately or EINPROGRESS if the request
               was queued for future execution. In the latter case the
               synchronization with queued callback routine is the
               responsibility of the driver.
             </para>
             <!--<blockquote>-->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - the tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>map</emphasis> - the map
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>buf</emphasis> - kernel virtual address of
                   the buffer
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>buflen</emphasis> - length of the buffer
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>callback</emphasis>,<function>
                   callback_arg</function> - the callback function and
                   its argument
                 </para>
               </listitem>
             </itemizedlist>
             <!--</blockquote>-->
             <para>
               The prototype of callback function is:
             </para>
             <para>
               <function>void callback(void *arg, bus_dma_segment_t
               *seg, int nseg, int error)</function>
             </para>
             <!--     <blockquote> -->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>arg</emphasis> - the same as callback_arg
                   passed to <function>bus_dmamap_load()</function>
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>seg</emphasis> - array of the segment
                   descriptors
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>nseg</emphasis> - number of descriptors in
                   array
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>error</emphasis> - indication of the
                   segment number overflow: if it's set to EFBIG then
                   the buffer did not fit into the maximal number of
                   segments permitted by the tag. In this case only the
                   permitted number of descriptors will be in the
                   array. Handling of this situation is up to the
                   driver: depending on the desired semantics it can
                   either consider this an error or split the buffer in
                   two and handle the second part separately
                 </para>
               </listitem>
             </itemizedlist>
             <!--     </blockquote>  -->
             <para>
               Each entry in the segments array contains the fields:
             </para>
 
             <!--   <blockquote> -->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>ds_addr</emphasis> - physical bus address
                   of the segment
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>ds_len</emphasis> - length of the segment
                 </para>
               </listitem>
             </itemizedlist>
             <!--   </blockquote>-->
           </listitem>
 
           <listitem> <!-- Eighth entry in alpha list -->
             <para>
               <function>void bus_dmamap_unload(bus_dma_tag_t dmat,
               bus_dmamap_t map)</function>
             </para>
             <para>unload the map.
             </para>
             <!--  <blockquote>  -->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>map</emphasis> - loaded map
                 </para>
               </listitem>
             </itemizedlist>
             <!--  </blockquote>  -->
           </listitem>
 
           <listitem> <!-- Ninth entry list alpha -->
             <para>
               <function>void bus_dmamap_sync (bus_dma_tag_t dmat,
               bus_dmamap_t map, bus_dmasync_op_t op)</function>
             </para>
             <para>
               Synchronise a loaded buffer with its bounce pages before
               and after physical transfer to or from device. This is
               the function that does all the necessary copying of data
               between the original buffer and its mapped version. The
               buffers must be synchronized both before and after doing
               the transfer.
             </para>
             <!--  <blockquote> -->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>map</emphasis> - loaded map
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>op</emphasis> - type of synchronization
                   operation to perform:
                 </para>
               </listitem>
             </itemizedlist>
             <!-- <blockquote> -->
             <itemizedlist>
               <listitem>
                 <para>
                   <function>BUS_DMASYNC_PREREAD</function> - before
                   reading from device into buffer
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <function>BUS_DMASYNC_POSTREAD</function> - after
                   reading from device into buffer
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <function>BUS_DMASYNC_PREWRITE</function> - before
                   writing the buffer to device
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <function>BUS_DMASYNC_POSTWRITE</function> - after
                   writing the buffer to device
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
         </itemizedlist>   <!-- End of list alpha -->
 <!-- </blockquote>
 </blockquote> -->
 
         <para>
           As of now PREREAD and POSTWRITE are null operations but that
           may change in the future, so they must not be ignored in the
           driver. Synchronization is not needed for the memory
           obtained from <function>bus_dmamem_alloc()</function>.
         </para>
         <para>
           Before calling the callback function from
           <function>bus_dmamap_load()</function> the segment array is
           stored in the stack. And it gets pre-allocated for the
           maximal number of segments allowed by the tag. Because of
           this the practical limit for the number of segments on i386
           architecture is about 250-300 (the kernel stack is 4KB minus
           the size of the user structure, size of a segment array
           entry is 8 bytes, and some space must be left). Because the
           array is allocated based on the maximal number this value
           must not be set higher than really needed. Fortunately, for
           most of hardware the maximal supported number of segments is
           much lower. But if the driver wants to handle buffers with a
           very large number of scatter-gather segments it should do
           that in portions: load part of the buffer, transfer it to
           the device, load next part of the buffer, and so on.
         </para>
         <para>
           Another practical consequence is that the number of segments
           may limit the size of the buffer. If all the pages in the
           buffer happen to be physically non-contiguous then the
           maximal supported buffer size for that fragmented case would
           be (nsegments * page_size). For example, if a maximal number
           of 10 segments is supported then on i386 maximal guaranteed
           supported buffer size would be 40K. If a higher size is
           desired then special tricks should be used in the driver.
         </para>
         <para>
           If the hardware does not support scatter-gather at all or
           the driver wants to support some buffer size even if it's
           heavily fragmented then the solution is to allocate a
           contiguous buffer in the driver and use it as intermediate
           storage if the original buffer does not fit.
         </para>
         <para>
           Below are the typical call sequences when using a map depend
           on the use of the map.  The characters -> are used to show
           the flow of time.
         </para>
         <para>
           For a buffer which stays practically fixed during all the
           time between attachment and detachment of a device:</para>
         <para>
           bus_dmamem_alloc -> bus_dmamap_load -> ...use buffer... ->
           -> bus_dmamap_unload -> bus_dmamem_free
         </para>
 
         <para>For a buffer that changes frequently and is passed from
         outside the driver:
 
 	<!-- XXX is this correct? -->
         <programlisting>          bus_dmamap_create ->
           -> bus_dmamap_load -> bus_dmamap_sync(PRE...) -> do transfer ->
           -> bus_dmamap_sync(POST...) -> bus_dmamap_unload ->
           ...
           -> bus_dmamap_load -> bus_dmamap_sync(PRE...) -> do transfer ->
           -> bus_dmamap_sync(POST...) -> bus_dmamap_unload ->
           -> bus_dmamap_destroy        </programlisting>
 
         </para>
         <para>
           When loading a map created by
           <function>bus_dmamem_alloc()</function> the passed address
           and size of the buffer must be the same as used in
           <function>bus_dmamem_alloc()</function>. In this case it is
           guaranteed that the whole buffer will be mapped as one
           segment (so the callback may be based on this assumption)
           and the request will be executed immediately (EINPROGRESS
           will never be returned).  All the callback needs to do in
           this case is to save the physical address.
         </para>
         <para>
           A typical example would be:
         </para>
 
         <programlisting>          static void
         alloc_callback(void *arg, bus_dma_segment_t *seg, int nseg, int error)
         {
           *(bus_addr_t *)arg = seg[0].ds_addr;
         }
 
           ...
           int error;
           struct somedata {
             ....
           };
           struct somedata *vsomedata; /* virtual address */
           bus_addr_t psomedata; /* physical bus-relative address */
           bus_dma_tag_t tag_somedata;
           bus_dmamap_t map_somedata;
           ...
 
           error=bus_dma_tag_create(parent_tag, alignment,
            boundary, lowaddr, highaddr, /*filter*/ NULL, /*filterarg*/ NULL,
            /*maxsize*/ sizeof(struct somedata), /*nsegments*/ 1,
            /*maxsegsz*/ sizeof(struct somedata), /*flags*/ 0,
            &#38;tag_somedata);
           if(error)
           return error;
 
           error = bus_dmamem_alloc(tag_somedata, &#38;vsomedata, /* flags*/ 0,
              &#38;map_somedata);
           if(error)
              return error;
 
           bus_dmamap_load(tag_somedata, map_somedata, (void *)vsomedata,
              sizeof (struct somedata), alloc_callback,
              (void *) &#38;psomedata, /*flags*/0);        </programlisting>
 
         <para>
           Looks a bit long and complicated but that's the way to do
           it. The practical consequence is: if multiple memory areas
           are allocated always together it would be a really good idea
           to combine them all into one structure and allocate as one
           (if the alignment and boundary limitations permit).
         </para>
         <para>
           When loading an arbitrary buffer into the map created by
           <function>bus_dmamap_create()</function> special measures
           must be taken to synchronize with the callback in case it
           would be delayed. The code would look like:
         </para>
 
         <programlisting>          {
            int s;
            int error;
 
            s = splsoftvm();
            error = bus_dmamap_load(
                dmat,
                dmamap,
                buffer_ptr,
                buffer_len,
                callback,
                /*callback_arg*/ buffer_descriptor,
                /*flags*/0);
            if (error == EINPROGRESS) {
                /*
                 * Do whatever is needed to ensure synchronization
                 * with callback. Callback is guaranteed not to be started
                 * until we do splx() or tsleep().
                 */
               }
            splx(s);
           }        </programlisting>
 
         <para>
           Two possible approaches for the processing of requests are:
         </para>
         <para>
           1. If requests are completed by marking them explicitly as
           done (such as the CAM requests) then it would be simpler to
           put all the further processing into the callback driver
           which would mark the request when it's done. Then not much
           extra synchronization is needed. For the flow control
           reasons it may be a good idea to freeze the request queue
           until this request gets completed.
         </para>
         <para>
           2. If requests are completed when the function returns (such
           as classic read or write requests on character devices) then
           a synchronization flag should be set in the buffer
           descriptor and <function>tsleep()</function> called.  Later
           when the callback gets called it will do it's processing and
           check this synchronization flag. If it's set then the
           callback should issue a wakeup. In this approach the
           callback function could either do all the needed processing
           (just like the previous case) or simply save the segments
           array in the buffer descriptor. Then after callback
           completes the calling function could use this saved segments
           array and do all the processing.
 
         </para>
      </sect1>
 <!--_________________________________________________________________________-->
 <!--~~~~~~~~~~~~~~~~~~~~END OF SECTION~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
 
      <sect1>
         <title>DMA</title>
         <!-- Section Marked up by Wylie -->
         <para>
           The Direct Memory Access (DMA) is implemented in the ISA bus
           through the DMA controller (actually, two of them but that's
           an irrelevant detail).  To make the early ISA devices simple
           and cheap the logic of the bus control and address
           generation was concentrated in the DMA controller.
           Fortunately, FreeBSD provides a set of functions that mostly
           hide the annoying details of the DMA controller from the
           device drivers.
         </para>
 
         <para>
           The simplest case is for the fairly intelligent
           devices. Like the bus master devices on PCI they can
           generate the bus cycles and memory addresses all by
           themselves. The only thing they really need from the DMA
           controller is bus arbitration. So for this purpose they
           pretend to be cascaded slave DMA controllers. And the only
           thing needed from the system DMA controller is to enable the
           cascaded mode on a DMA channel by calling the following
           function when attaching the driver:
         </para>
 
         <para>
           <function>void isa_dmacascade(int channel_number)</function>
         </para>
 
         <para>
           All the further activity is done by programming the
           device. When detaching the driver no DMA-related functions
           need to be called.
         </para>
 
         <para>
           For the simpler devices things get more complicated. The
           functions used are:
         </para>
 
         <itemizedlist>
 
           <listitem>
           <para>
             <function>int isa_dma_acquire(int chanel_number)</function>
           </para>
           <para>
                 Reserve a DMA channel. Returns 0 on success or EBUSY
                 if the channel was already reserved by this or a
                 different driver. Most of the ISA devices are not able
                 to share DMA channels anyway, so normally this
                 function is called when attaching a device. This
                 reservation was made redundant by the modern interface
                 of bus resources but still must be used in addition to
                 the latter. If not used then later, other DMA routines
                 will panic.
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>int isa_dma_release(int chanel_number)</function>
           </para>
           <para>
                 Release a previously reserved DMA channel. No
                 transfers must be in progress when the channel is
                 released (as well as the device must not try to
                 initiate transfer after the channel is released).
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>void isa_dmainit(int chan, u_int
             bouncebufsize)</function>
           </para>
           <para>
                 Allocate a bounce buffer for use with the specified
                 channel. The requested size of the buffer can't exceed
                 64KB. This bounce buffer will be automatically used
                 later if a transfer buffer happens to be not
                 physically contiguous or outside of the memory
                 accessible by the ISA bus or crossing the 64KB
                 boundary. If the transfers will be always done from
                 buffers which conform to these conditions (such as
                 those allocated by
                 <function>bus_dmamem_alloc()</function> with proper
                 limitations) then <function>isa_dmainit()</function>
                 does not have to be called. But it's quite convenient
                 to transfer arbitrary data using the DMA controller.
                 The bounce buffer will automatically care of the
                 scatter-gather issues.
           </para>
  <!-- <blockquote> -->
           <itemizedlist>
                 <listitem>
                   <para>
                     <emphasis>chan</emphasis> - channel number
                   </para>
                 </listitem>
                 <listitem>
                   <para>
                     <emphasis>bouncebufsize</emphasis> - size of the
                     bounce buffer in bytes
                   </para>
                 </listitem>
           </itemizedlist>
 <!-- </blockquote> -->
 <!--</para> -->
         </listitem>
 
         <listitem>
           <para>
             <function>void isa_dmastart(int flags, caddr_t addr, u_int
             nbytes, int chan)</function>
           </para>
           <para>
                 Prepare to start a DMA transfer. This function must be
                 called to set up the DMA controller before actually
                 starting transfer on the device. It checks that the
                 buffer is contiguous and falls into the ISA memory
                 range, if not then the bounce buffer is automatically
                 used. If bounce buffer is required but not set up by
                 <function>isa_dmainit()</function> or too small for
                 the requested transfer size then the system will
                 panic. In case of a write request with bounce buffer
                 the data will be automatically copied to the bounce
                 buffer.
           </para>
         </listitem>
         <listitem>
           <para>flags - a bitmask determining the type of operation to
           be done. The direction bits B_READ and B_WRITE are mutually
           exclusive.
           </para>
         <!--   <blockquote>  -->
           <itemizedlist>
             <listitem>
               <para>
                 B_READ - read from the ISA bus into memory
               </para>
             </listitem>
             <listitem>
               <para>
                 B_WRITE - write from the memory to the ISA bus
               </para>
             </listitem>
             <listitem>
               <para>
                 B_RAW - if set then the DMA controller will remember
                 the buffer and after the end of transfer will
                 automatically re-initialize itself to repeat transfer
                 of the same buffer again (of course, the driver may
                 change the data in the buffer before initiating
                 another transfer in the device). If not set then the
                 parameters will work only for one transfer, and
                 <function>isa_dmastart()</function> will have to be
                 called again before initiating the next
                 transfer. Using B_RAW makes sense only if the bounce
                 buffer is not used.
               </para>
             </listitem>
           </itemizedlist>
 <!--   </blockquote>  -->
         </listitem>
         <listitem>
           <para>
             addr - virtual address of the buffer
           </para>
         </listitem>
         <listitem>
           <para>
             nbytes - length of the buffer. Must be less or equal to
             64KB. Length of 0 is not allowed: the DMA controller will
             understand it as 64KB while the kernel code will
             understand it as 0 and that would cause unpredictable
             effects. For channels number 4 and higher the length must
             be even because these channels transfer 2 bytes at a
             time. In case of an odd length the last byte will not be
             transferred.
           </para>
         </listitem>
         <listitem>
           <para>
             chan - channel number
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>void isa_dmadone(int flags, caddr_t addr, int
             nbytes, int chan)</function>
           </para>
           <para>
             Synchronize the memory after device reports that transfer
             is done. If that was a read operation with a bounce buffer
             then the data will be copied from the bounce buffer to the
             original buffer. Arguments are the same as for
             <function>isa_dmastart()</function>. Flag B_RAW is
             permitted but it does not affect
             <function>isa_dmadone()</function> in any way.
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>int isa_dmastatus(int channel_number)</function>
           </para>
           <para>
             Returns the number of bytes left in the current transfer
             to be transferred.  In case the flag B_READ was set in
             <function>isa_dmastart()</function> the number returned
             will never be equal to zero. At the end of transfer it
             will be automatically reset back to the length of
             buffer. The normal use is to check the number of bytes
             left after the device signals that the transfer is
             completed.  If the number of bytes is not 0 then probably
             something went wrong with that transfer.
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>int isa_dmastop(int channel_number)</function>
           </para>
           <para>
             Aborts the current transfer and returns the number of
             bytes left untransferred.
           </para>
         </listitem>
        </itemizedlist>
      </sect1>
 
      <sect1>
      <title>xxx_isa_probe</title>
      <!-- Section marked up by Wylie -->
 
         <para>
           This function probes if a device is present. If the driver
           supports auto-detection of some part of device configuration
           (such as interrupt vector or memory address) this
           auto-detection must be done in this routine.
         </para>
 
         <para>
-          As for any other bus, if the device can not be detected or
+          As for any other bus, if the device cannot be detected or
           is detected but failed the self-test or some other problem
           happened then it returns a positive value of error. The
           value ENXIO must be returned if the device is not
           present. Other error values may mean other conditions. Zero
           or negative values mean success. Most of the drivers return
           zero as success.
         </para>
 
         <para>
           The negative return values are used when a PnP device
           supports multiple interfaces. For example, an older
           compatibility interface and a newer advanced interface which
           are supported by different drivers. Then both drivers would
           detect the device. The driver which returns a higher value
           in the probe routine takes precedence (in other words, the
           driver returning 0 has highest precedence, one returning -1
           is next, one returning -2 is after it and so on). In result
           the devices which support only the old interface will be
           handled by the old driver (which should return -1 from the
           probe routine) while the devices supporting the new
           interface as well will be handled by the new driver (which
           should return 0 from the probe routine).
         </para>
 
         <para>
           The device descriptor struct xxx_softc is allocated by the
           system before calling the probe routine. If the probe
           routine returns an error the descriptor will be
           automatically deallocated by the system. So if a probing
           error occurs the driver must make sure that all the
           resources it used during probe are deallocated and that
           nothing keeps the descriptor from being safely
           deallocated. If the probe completes successfully the
           descriptor will be preserved by the system and later passed
           to the routine <function>xxx_isa_attach()</function>. If a
           driver returns a negative value it can't be sure that it
           will have the highest priority and its attach routine will
           be called. So in this case it also must release all the
           resources before returning and if necessary allocate them
           again in the attach routine. When
           <function>xxx_isa_probe()</function> returns 0 releasing the
           resources before returning is also a good idea, a
           well-behaved driver should do so. But in case if there is
           some problem with releasing the resources the driver is
           allowed to keep resources between returning 0 from the probe
           routine and execution of the attach routine.
         </para>
 
         <para>
           A typical probe routine starts with getting the device
           descriptor and unit:
         </para>
 
         <programlisting>         struct xxx_softc *sc = device_get_softc(dev);
           int unit = device_get_unit(dev);
           int pnperror;
           int error = 0;
 
           sc->dev = dev; /* link it back */
           sc->unit = unit;        </programlisting>
 
         <para>
           Then check for the PnP devices. The check is carried out by
           a table containing the list of PnP IDs supported by this
           driver and human-readable descriptions of the device models
           corresponding to these IDs.
         </para>
 
         <programlisting>
         pnperror=ISA_PNP_PROBE(device_get_parent(dev), dev,
         xxx_pnp_ids); if(pnperror == ENXIO) return ENXIO;
         </programlisting>
 
         <para>
           The logic of ISA_PNP_PROBE is the following: If this card
           (device unit) was not detected as PnP then ENOENT will be
           returned. If it was detected as PnP but its detected ID does
           not match any of the IDs in the table then ENXIO is
           returned. Finally, if it has PnP support and it matches on
           of the IDs in the table, 0 is returned and the appropriate
           description from the table is set by
           <function>device_set_desc()</function>.
         </para>
 
         <para>
           If a driver supports only PnP devices then the condition
           would look like:
         </para>
 
         <programlisting>          if(pnperror != 0)
               return pnperror;        </programlisting>
 
         <para>
           No special treatment is required for the drivers which don't
           support PnP because they pass an empty PnP ID table and will
           always get ENXIO if called on a PnP card.
         </para>
 
         <para>
           The probe routine normally needs at least some minimal set
           of resources, such as I/O port number to find the card and
           probe it. Depending on the hardware the driver may be able
           to discover the other necessary resources automatically. The
           PnP devices have all the resources pre-set by the PnP
           subsystem, so the driver does not need to discover them by
           itself.
         </para>
 
         <para>
           Typically the minimal information required to get access to
           the device is the I/O port number. Then some devices allow
           to get the rest of information from the device configuration
           registers (though not all devices do that).  So first we try
           to get the port start value:
         </para>
 
         <programlisting> sc->port0 = bus_get_resource_start(dev,
         SYS_RES_IOPORT, 0 /*rid*/); if(sc->port0 == 0) return ENXIO;
         </programlisting>
 
         <para>
           The base port address is saved in the structure softc for
           future use.  If it will be used very often then calling the
           resource function each time would be prohibitively slow. If
           we don't get a port we just return an error.  Some device
           drivers can instead be clever and try to probe all the
           possible ports, like this:
         </para>
 
         <programlisting>          
           /* table of all possible base I/O port addresses for this device */
           static struct xxx_allports {
               u_short port; /* port address */
               short used; /* flag: if this port is already used by some unit */
           } xxx_allports = {
               { 0x300, 0 },
               { 0x320, 0 },
               { 0x340, 0 },
               { 0, 0 } /* end of table */
           };
 
           ...
           int port, i;
           ...
 
           port =  bus_get_resource_start(dev, SYS_RES_IOPORT, 0 /*rid*/);
           if(port !=0 ) {
               for(i=0; xxx_allports[i].port!=0; i++) {
                   if(xxx_allports[i].used || xxx_allports[i].port != port)
                       continue;
 
                   /* found it */
                   xxx_allports[i].used = 1;
                   /* do probe on a known port */
                   return xxx_really_probe(dev, port);
               }
               return ENXIO; /* port is unknown or already used */
           }
 
           /* we get here only if we need to guess the port */
           for(i=0; xxx_allports[i].port!=0; i++) {
               if(xxx_allports[i].used)
                   continue;
 
               /* mark as used - even if we find nothing at this port
                * at least we won't probe it in future
                */
                xxx_allports[i].used = 1;
 
               error = xxx_really_probe(dev, xxx_allports[i].port);
               if(error == 0) /* found a device at that port */
                   return 0;
           }
           /* probed all possible addresses, none worked */
           return ENXIO;</programlisting>
 
         <para>
           Of course, normally the driver's
           <function>identify()</function> routine should be used for
           such things. But there may be one valid reason why it may be
           better to be done in <function>probe()</function>: if this
           probe would drive some other sensitive device crazy.  The
           probe routines are ordered with consideration of the
           "sensitive" flag: the sensitive devices get probed first and
           the rest of devices later.  But the
           <function>identify()</function> routines are called before
           any probes, so they show no respect to the sensitive devices
           and may upset them.
         </para>
 
         <para>
           Now, after we got the starting port we need to set the port
           count (except for PnP devices) because the kernel does not
           have this information in the configuration file.
         </para>
 
         <programlisting>          
          if(pnperror /* only for non-PnP devices */
          &#38;&#38; bus_set_resource(dev, SYS_RES_IOPORT, 0, sc->port0, 
          XXX_PORT_COUNT)&lt;0)
              return ENXIO;</programlisting>
 
         <para>
           Finally allocate and activate a piece of port address space
           (special values of start and end mean "use those we set by
           <function>bus_set_resource()</function>"):
         </para>
 
         <programlisting>
           sc->port0_rid = 0;
           sc->port0_r = bus_alloc_resource(dev, SYS_RES_IOPORT,  
           &#38;sc->port0_rid,
               /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);
 
           if(sc->port0_r == NULL)
               return ENXIO;</programlisting>
 
         <para>
           Now having access to the port-mapped registers we can poke
           the device in some way and check if it reacts like it is
           expected to. If it does not then there is probably some
           other device or no device at all at this address.
         </para>
 
         <para>
           Normally drivers don't set up the interrupt handlers until
           the attach routine. Instead they do probes in the polling
           mode using the <function>DELAY()</function> function for
           timeout. The probe routine must never hang forever, all the
           waits for the device must be done with timeouts. If the
           device does not respond within the time it's probably broken
           or misconfigured and the driver must return error. When
           determining the timeout interval give the device some extra
           time to be on the safe side: although
           <function>DELAY()</function> is supposed to delay for the
           same amount of time on any machine it has some margin of
           error, depending on the exact CPU.
         </para>
 
         <para>
           If the probe routine really wants to check that the
           interrupts really work it may configure and probe the
           interrupts too. But that's not recommended.
         </para>
 
         <programlisting>          
           /* implemented in some very device-specific way */
           if(error = xxx_probe_ports(sc))
               goto bad; /* will deallocate the resources before returning */
         </programlisting>
 
         <para>
           The fucntion <function>xxx_probe_ports()</function> may also
           set the device description depending on the exact model of
           device it discovers.  But if there is only one supported
           device model this can be as well done in a hardcoded way.
           Of course, for the PnP devices the PnP support sets the
           description from the table automatically.
         </para>
 
 
         <programlisting>          if(pnperror)
               device_set_desc(dev, "Our device model 1234");
         </programlisting>
 
         <para>
           Then the probe routine should either discover the ranges of
           all the resources by reading the device configuration
           registers or make sure that they were set explicitly by the
           user. We will consider it with an example of on-board
           memory. The probe routine should be as non-intrusive as
           possible, so allocation and check of functionality of the
           rest of resources (besides the ports) would be better left
           to the attach routine.
         </para>
 
         <para>
           The memory address may be specified in the kernel
           configuration file or on some devices it may be
           pre-configured in non-volatile configuration registers.  If
           both sources are available and different, which one should
           be used?  Probably if the user bothered to set the address
           explicitly in the kernel configuration file they know what
           they're doing and this one should take precedence. An
           example of implementation could be:
         </para>
         <programlisting>          
           /* try to find out the config address first */
           sc->mem0_p = bus_get_resource_start(dev, SYS_RES_MEMORY, 0 /*rid*/);
           if(sc->mem0_p == 0) { /* nope, not specified by user */
               sc->mem0_p = xxx_read_mem0_from_device_config(sc);
 
 
           if(sc->mem0_p == 0)
                   /* can't get it from device config registers either */
                   goto bad;
           } else {
               if(xxx_set_mem0_address_on_device(sc) &lt; 0)
                   goto bad; /* device does not support that address */
           }
 
           /* just like the port, set the memory size,
            * for some devices the memory size would not be constant
            * but should be read from the device configuration registers instead
            * to accommodate different models of devices. Another option would
            * be to let the user set the memory size as "msize" configuration
            * resource which will be automatically handled by the ISA bus.
            */
            if(pnperror) { /* only for non-PnP devices */
               sc->mem0_size = bus_get_resource_count(dev, SYS_RES_MEMORY, 0 /*rid*/);
               if(sc->mem0_size == 0) /* not specified by user */
                   sc->mem0_size = xxx_read_mem0_size_from_device_config(sc);
 
               if(sc->mem0_size == 0) {
                   /* suppose this is a very old model of device without
                    * auto-configuration features and the user gave no preference,
                    * so assume the minimalistic case
                    * (of course, the real value will vary with the driver)
                    */
                   sc->mem0_size = 8*1024;
               }
 
               if(xxx_set_mem0_size_on_device(sc) &lt; 0)
                   goto bad; /* device does not support that size */
 
               if(bus_set_resource(dev, SYS_RES_MEMORY, /*rid*/0,
                       sc->mem0_p, sc->mem0_size)&lt;0)
                   goto bad;
           } else {
               sc->mem0_size = bus_get_resource_count(dev, SYS_RES_MEMORY, 0 /*rid*/);
           }        </programlisting>
 
         <para>
           Resources for IRQ and DRQ are easy to check by analogy.
         </para>
 
         <para>
           If all went well then release all the resources and return success.
         </para>
 
         <programlisting>          xxx_free_resources(sc);
           return 0;</programlisting>
 
         <para>
           Finally, handle the troublesome situations. All the
           resources should be deallocated before returning. We make
           use of the fact that before the structure softc is passed to
           us it gets zeroed out, so we can find out if some resource
           was allocated: then its descriptor is non-zero.
         </para>
 
         <programlisting>          bad:
 
           xxx_free_resources(sc);
           if(error)
                 return error;
           else /* exact error is unknown */
               return ENXIO;</programlisting>
 
         <para>
           That would be all for the probe routine. Freeing of
           resources is done from multiple places, so it's moved to a
           function which may look like:
         </para>
 
 <programlisting>static void
            xxx_free_resources(sc)
               struct xxx_softc *sc;
           {
               /* check every resource and free if not zero */
 
               /* interrupt handler */
               if(sc->intr_r) {
                   bus_teardown_intr(sc->dev, sc->intr_r, sc->intr_cookie);
                   bus_release_resource(sc->dev, SYS_RES_IRQ, sc->intr_rid,
                       sc->intr_r);
                   sc->intr_r = 0;
               }
 
               /* all kinds of memory maps we could have allocated */
               if(sc->data_p) {
                   bus_dmamap_unload(sc->data_tag, sc->data_map);
                   sc->data_p = 0;
               }
                if(sc->data) { /* sc->data_map may be legitimately equal to 0 */
                   /* the map will also be freed */
                   bus_dmamem_free(sc->data_tag, sc->data, sc->data_map);
                   sc->data = 0;
               }
               if(sc->data_tag) {
                   bus_dma_tag_destroy(sc->data_tag);
                   sc->data_tag = 0;
               }
 
               ... free other maps and tags if we have them ...
 
               if(sc->parent_tag) {
                   bus_dma_tag_destroy(sc->parent_tag);
                   sc->parent_tag = 0;
               }
 
               /* release all the bus resources */
               if(sc->mem0_r) {
                   bus_release_resource(sc->dev, SYS_RES_MEMORY, sc->mem0_rid,
                       sc->mem0_r);
                   sc->mem0_r = 0;
               }
               ...
               if(sc->port0_r) {
                   bus_release_resource(sc->dev, SYS_RES_IOPORT, sc->port0_rid,
                       sc->port0_r);
                   sc->port0_r = 0;
               }
           }</programlisting>
 
      </sect1>
 
      <sect1>
      <title>xxx_isa_attach</title>
      <!-- Section Marked up by Wylie -->
 
         <para>The attach routine actually connects the driver to the
         system if the probe routine returned success and the system
         had chosen to attach that driver.  If the probe routine
         returned 0 then the attach routine may expect to receive the
         device structure softc intact, as it was set by the probe
         routine. Also if the probe routine returns 0 it may expect
         that the attach routine for this device shall be called at
         some point in the future. If the probe routine returns a
         negative value then the driver may make none of these
         assumptions.
         </para>
 
         <para>The attach routine returns 0 if it completed successfully or
           error code otherwise.
         </para>
 
         <para>The attach routine starts just like the probe routine,
           with getting some frequently used data into more accessible
           variables.
         </para>
 
         <programlisting>          struct xxx_softc *sc = device_get_softc(dev);
           int unit = device_get_unit(dev);
           int error = 0;</programlisting>
 
         <para>Then allocate and activate all the necessary
           resources. Because normally the port range will be released
           before returning from probe, it has to be allocated
           again. We expect that the probe routine had properly set all
           the resource ranges, as well as saved them in the structure
           softc. If the probe routine had left some resource allocated
           then it does not need to be allocated again (which would be
           considered an error).
         </para>
 
         <programlisting>          sc->port0_rid = 0;
           sc->port0_r = bus_alloc_resource(dev, SYS_RES_IOPORT,  &#38;sc->port0_rid,
               /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);
 
           if(sc->port0_r == NULL)
                return ENXIO;
 
           /* on-board memory */
           sc->mem0_rid = 0;
           sc->mem0_r = bus_alloc_resource(dev, SYS_RES_MEMORY,  &#38;sc->mem0_rid,
               /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);
 
           if(sc->mem0_r == NULL)
                 goto bad;
 
           /* get its virtual address */
           sc->mem0_v = rman_get_virtual(sc->mem0_r);</programlisting>
 
         <para>The DMA request channel (DRQ) is allocated likewise. To
           initialize it use functions of the
           <function>isa_dma*()</function> family. For example:
         </para>
 
         <para><function>isa_dmacascade(sc->drq0);</function></para>
 
         <para>The interrupt request line (IRQ) is a bit
           special. Besides allocation the driver's interrupt handler
           should be associated with it. Historically in the old ISA
           drivers the argument passed by the system to the interrupt
           handler was the device unit number. But in modern drivers
           the convention suggests passing the pointer to structure
           softc. The important reason is that when the structures
           softc are allocated dynamically then getting the unit number
           from softc is easy while getting softc from unit number is
           difficult. Also this convention makes the drivers for
           different buses look more uniform and allows them to share
           the code: each bus gets its own probe, attach, detach and
           other bus-specific routines while the bulk of the driver
           code may be shared among them.
         </para>
 
         <programlisting>
           sc->intr_rid = 0;
           sc->intr_r = bus_alloc_resource(dev, SYS_RES_MEMORY,  &#38;sc->intr_rid,
                 /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);
 
           if(sc->intr_r == NULL)
               goto bad;
 
           /*
            * XXX_INTR_TYPE is supposed to be defined depending on the type of
            * the driver, for example as INTR_TYPE_CAM for a CAM driver
            */
           error = bus_setup_intr(dev, sc->intr_r, XXX_INTR_TYPE,
               (driver_intr_t *) xxx_intr, (void *) sc, &#38;sc->intr_cookie);
           if(error)
               goto bad;
 
         </programlisting>
 
 
         <para>If the device needs to make DMA to the main memory then
           this memory should be allocated like described before:
         </para>
 
         <programlisting>          error=bus_dma_tag_create(NULL, /*alignment*/ 4,
               /*boundary*/ 0, /*lowaddr*/ BUS_SPACE_MAXADDR_24BIT,
               /*highaddr*/ BUS_SPACE_MAXADDR, /*filter*/ NULL, /*filterarg*/ NULL,
               /*maxsize*/ BUS_SPACE_MAXSIZE_24BIT,
               /*nsegments*/ BUS_SPACE_UNRESTRICTED,
               /*maxsegsz*/ BUS_SPACE_MAXSIZE_24BIT, /*flags*/ 0,
               &#38;sc->parent_tag);
           if(error)
               goto bad;
 
           /* many things get inherited from the parent tag
            * sc->data is supposed to point to the structure with the shared data,
            * for example for a ring buffer it could be:
            * struct {
            *   u_short rd_pos;
            *   u_short wr_pos;
            *   char    bf[XXX_RING_BUFFER_SIZE]
            * } *data;
            */
           error=bus_dma_tag_create(sc->parent_tag, 1,
               0, BUS_SPACE_MAXADDR, 0, /*filter*/ NULL, /*filterarg*/ NULL,
               /*maxsize*/ sizeof(* sc->data), /*nsegments*/ 1,
               /*maxsegsz*/ sizeof(* sc->data), /*flags*/ 0,
               &#38;sc->data_tag);
           if(error)
               goto bad;
 
           error = bus_dmamem_alloc(sc->data_tag, &#38;sc->data, /* flags*/ 0,
               &#38;sc->data_map);
           if(error)
                goto bad;
 
           /* xxx_alloc_callback() just saves the physical address at
            * the pointer passed as its argument, in this case &#38;sc->data_p.
            * See details in the section on bus memory mapping.
            * It can be implemented like:
            *
            * static void
            * xxx_alloc_callback(void *arg, bus_dma_segment_t *seg,
            *     int nseg, int error)
            * {
            *    *(bus_addr_t *)arg = seg[0].ds_addr;
            * }
            */
           bus_dmamap_load(sc->data_tag, sc->data_map, (void *)sc->data,
               sizeof (* sc->data), xxx_alloc_callback, (void *) &#38;sc->data_p,
               /*flags*/0);</programlisting>
 
 
         <para>After all the necessary resources are allocated the
           device should be initialized. The initialization may include
           testing that all the expected features are functional.</para>
 
         <programlisting>          if(xxx_initialize(sc) &lt; 0)
                goto bad;        </programlisting>
 
 
         <para>The bus subsystem will automatically print on the
           console the device description set by probe. But if the
           driver wants to print some extra information about the
           device it may do so, for example:</para>
 
         <programlisting>
         device_printf(dev, "has on-card FIFO buffer of %d bytes\n", sc->fifosize);
         </programlisting>
 
         <para>If the initialization routine experiences any problems
           then printing messages about them before returning error is
           also recommended.</para>
 
         <para>The final step of the attach routine is attaching the
           device to its functional subsystem in the kernel. The exact
           way to do it depends on the type of the driver: a character
           device, a block device, a network device, a CAM SCSI bus
           device and so on.</para>
 
         <para>If all went well then return success.</para>
 
         <programlisting>          error = xxx_attach_subsystem(sc);
           if(error)
               goto bad;
 
           return 0;        </programlisting>
 
         <para>Finally, handle the troublesome situations. All the
           resources should be deallocated before returning an
           error. We make use of the fact that before the structure
           softc is passed to us it gets zeroed out, so we can find out
           if some resource was allocated: then its descriptor is
           non-zero.</para>
 
         <programlisting>          bad:
 
           xxx_free_resources(sc);
           if(error)
               return error;
           else /* exact error is unknown */
               return ENXIO;</programlisting>
 
         <para>That would be all for the attach routine.</para>
 
      </sect1>
 
 
      <sect1>
        <title>xxx_isa_detach</title>
 
         <para>
           If this function is present in the driver and the driver is
           compiled as a loadable module then the driver gets the
           ability to be unloaded. This is an important feature if the
           hardware supports hot plug. But the ISA bus does not support
           hot plug, so this feature is not particularly important for
           the ISA devices. The ability to unload a driver may be
           useful when debugging it, but in many cases installation of
           the new version of the driver would be required only after
           the old version somehow wedges the system and reboot will be
           needed anyway, so the efforts spent on writing the detach
           routine may not be worth it. Another argument is that
           unloading would allow upgrading the drivers on a production
           machine seems to be mostly theoretical. Installing a new
           version of a driver is a dangerous operation which should
           never be performed on a production machine (and which is not
           permitted when the system is running in secure mode).  Still
           the detach routine may be provided for the sake of
           completeness.
         </para>
 
         <para>
           The detach routine returns 0 if the driver was successfully
           detached or the error code otherwise.
         </para>
 
         <para>
           The logic of detach is a mirror of the attach. The first
           thing to do is to detach the driver from its kernel
           subsystem. If the device is currently open then the driver
           has two choices: refuse to be detached or forcibly close and
           proceed with detach. The choice used depends on the ability
           of the particular kernel subsystem to do a forced close and
           on the preferences of the driver's author. Generally the
           forced close seems to be the preferred alternative.
         <programlisting>          struct xxx_softc *sc = device_get_softc(dev);
           int error;
 
           error = xxx_detach_subsystem(sc);
           if(error)
               return error;</programlisting>
         </para>
         <para>
           Next the driver may want to reset the hardware to some
           consistent state.  That includes stopping any ongoing
           transfers, disabling the DMA channels and interrupts to
           avoid memory corruption by the device. For most of the
           drivers this is exactly what the shutdown routine does, so
           if it is included in the driver we can as well just call it.
         </para>
         <para><function>xxx_isa_shutdown(dev);</function></para>
 
         <para>
           And finally release all the resources and return success.
         <programlisting>          xxx_free_resources(sc);
           return 0;</programlisting>
 
         </para>
      </sect1>
 
      <sect1>
        <title>xxx_isa_shutdown</title>
 
         <para>
           This routine is called when the system is about to be shut
           down. It is expected to bring the hardware to some
           consistent state. For most of the ISA devices no special
           action is required, so the function is not really necessary
           because the device will be re-initialized on reboot
           anyway. But some devices have to be shut down with a special
           procedure, to make sure that they will be properly detected
           after soft reboot (this is especially true for many devices
           with proprietary identification protocols).  In any case
           disabling DMA and interrupts in the device registers and
           stopping any ongoing transfers is a good idea. The exact
           action depends on the hardware, so we don't consider it here
           in any details.
         </para>
 
         <para>
           xxx_intr
         </para>
 
         <para>
           The interrupt handler is called when an interrupt is
           received which may be from this particular device. The ISA
           bus does not support interrupt sharing (except some special
           cases) so in practice if the interrupt handler is called
           then the interrupt almost for sure came from its
           device. Still the interrupt handler must poll the device
           registers and make sure that the interrupt was generated by
           its device. If not it should just return.
         </para>
 
         <para>
           The old convention for the ISA drivers was getting the
           device unit number as an argument. It is obsolete, and the
           new drivers receive whatever argument was specified for them
           in the attach routine when calling
           <function>bus_setup_intr()</function>. By the new convention
           it should be the pointer to the structure softc. So the
           interrupt handler commonly starts as:
         </para>
 
         <programlisting>
           static void
           xxx_intr(struct xxx_softc *sc)
           {
 
         </programlisting>
 
         <para>
           It runs at the interrupt priority level specified by the
           interrupt type parameter of
           <function>bus_setup_intr()</function>. That means that all
           the other interrupts of the same type as well as all the
           software interrupts are disabled.
         </para>
 
         <para>
           To avoid races it is commonly written as a loop:
         </para>
 
         <programlisting>
           while(xxx_interrupt_pending(sc)) {
               xxx_process_interrupt(sc);
               xxx_acknowledge_interrupt(sc);
           }        </programlisting>
 
         <para>
           The interrupt handler has to acknowledge interrupt to the
           device only but not to the interrupt controller, the system
           takes care of the latter.
         </para>
 
      </sect1>
 </chapter>
diff --git a/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.sgml
index 72ee58a453..072aea5499 100644
--- a/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.sgml
@@ -1,1983 +1,1983 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml,v 1.3 2001/04/13 08:09:03 murray Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml,v 1.4 2001/06/13 11:35:56 tom Exp $
 -->
 
 <chapter id="scsi">
   <title>Common Access Method SCSI Controllers</title>
 
   <para><emphasis>This chapter was written by &a.babkin;
     Modifications for the handbook made by
     &a.murray;.</emphasis></para>
 
   <sect1>
     <title>Synopsis</title>
 
     <para>This document assumes that the reader has a general
       understanding of device drivers in FreeBSD and of the SCSI
       protocol.  Much of the information in this document was
       extracted from the drivers :</para>
 
      <itemizedlist>
 
        <listitem><para>ncr (<filename>/sys/pci/ncr.c</filename>) by
          Wolfgang Stanglmeier and Stefan Esser</para></listitem>
 
        <listitem><para>sym (<filename>/sys/pci/sym.c</filename>) by
          Gerard Roudier</para></listitem> 
 
        <listitem><para>aic7xxx
          (<filename>/sys/dev/aic7xxx/aic7xxx.c</filename>) by Justin
          T. Gibbs</para></listitem>
 
      </itemizedlist>
 
    <para>and from the CAM code itself (by Justing T. Gibbs, see
      <filename>/sys/cam/*</filename>).  When some solution looked the
      most logical and was essentially verbatim extracted from the code
      by Justin Gibbs, I marked it as "recommended".</para>
 
    <para>The document is illustrated with examples in
      pseudo-code. Although sometimes the examples have many details
      and look like real code, it's still pseudo-code.  It was written
      to demonstrate the concepts in an understandable way.  For a real
      driver other approaches may be more modular and efficient.  It
      also abstracts from the hardware details, as well as issues that
      would cloud the demonstrated concepts or that are supposed to be
      described in the other chapters of the developers handbook. Such
      details are commonly shown as calls to functions with descriptive
      names, comments or pseudo-statements. Fortunately real life
      full-size examples with all the details can be found in the real
      drivers.</para>
 
   </sect1>
 
   <sect1>
     <title>General architecture</title>
 
     <para>CAM stands for Common Access Method. It's a generic way to
       address the I/O buses in a SCSI-like way. This allows a
       separation of the generic device drivers from the drivers
       controlling the I/O bus: for example the disk driver becomes able
       to control disks on both SCSI, IDE, and/or any other bus so the
       disk driver portion does not have to be rewritten (or copied and
       modified) for every new I/O bus. Thus the two most important
       active entities are:</para>
 
     <itemizedlist>
       <listitem><para><emphasis>Peripheral Modules</emphasis> -  a
         driver for peripheral devices (disk, tape, CDROM,
         etc.)</para></listitem>
       <listitem><para><emphasis>SCSI Interface Modules </emphasis>(SIM)
         - a Host Bus Adapter drivers for connecting to an I/O bus such
         as SCSI or IDE.</para></listitem>
     </itemizedlist>
 
     <para>A peripheral driver receives requests from the OS, converts
       them to a sequence of SCSI commands and passes these SCSI
       commands to a SCSI Interface Module. The SCSI Interface Module
       is responsible for passing these commands to the actual hardware
       (or if the actual hardware is not SCSI but, for example, IDE
       then also converting the SCSI commands to the native commands of
       the hardware).</para>
 
     <para>Because we are interested in writing a SCSI adapter driver
       here, from this point on we will consider everything from the
       SIM standpoint.</para>
 
     <para>A typical SIM driver needs to include the following
       CAM-related header files:</para>
 
 <programlisting>#include &lt;cam/cam.h&gt;
 #include &lt;cam/cam_ccb.h&gt;
 #include &lt;cam/cam_sim.h&gt;
 #include &lt;cam/cam_xpt_sim.h&gt;
 #include &lt;cam/cam_debug.h&gt;
 #include &lt;cam/scsi/scsi_all.h&gt;</programlisting>
 
     <para>The first thing each SIM driver must do is register itself
       with the CAM subsystem. This is done during the driver's
       <function>xxx_attach()</function> function (here and further
       xxx_ is used to denote the unique driver name prefix). The
       <function>xxx_attach()</function> function itself is called by
       the system bus auto-configuration code which we don't describe
       here.</para>
 
     <para>This is achieved in multiple steps: first it's necessary to
       allocate the queue of requests associated with this SIM:</para>
 
 <programlisting>    struct cam_devq *devq;
 
     if(( devq = cam_simq_alloc(SIZE) )==NULL) {
         error; /* some code to handle the error */
     }</programlisting>
 
     <para>Here SIZE is the size of the queue to be allocated, maximal
       number of requests it could contain. It's the number of requests
       that the SIM driver can handle in parallel on one SCSI
       card. Commonly it can be calculated as:</para>
 
 <programlisting>SIZE = NUMBER_OF_SUPPORTED_TARGETS * MAX_SIMULTANEOUS_COMMANDS_PER_TARGET</programlisting>
 
     <para>Next we create a descriptor of our SIM:</para>
 
 <programlisting>    struct cam_sim *sim;
 
     if(( sim = cam_sim_alloc(action_func, poll_func, driver_name,
             softc, unit, max_dev_transactions, 
             max_tagged_dev_transactions, devq) )==NULL) {
         cam_simq_free(devq);
         error; /* some code to handle the error */
     }</programlisting>
 
     <para>Note that if we are not able to create a SIM descriptor we
       free the <structname>devq</structname> also because we can do
       nothing else with it and we want to conserve memory.</para>
 
     <para>If a SCSI card has multiple SCSI buses on it then each bus
       requires its own <structname>cam_sim</structname>
       structure.</para>
 
     <para>An interesting question is what to do if a SCSI card has
       more than one SCSI bus, do we need one
       <structname>devq</structname> structure per card or per SCSI
       bus?  The answer given in the comments to the CAM code is:
       either way, as the driver's author prefers.</para>
 
     <para>The arguments are :
       <itemizedlist>
 
         <listitem><para><function>action_func</function> - pointer to
           the driver's <function>xxx_action</function> function.
 	  <funcSynopsis><funcPrototype>
 	  <funcDef>static void
             <function>xxx_action</function>
 	  </funcDef>
 	    <paramdef>
 	      <parameter>struct cam_sim *sim</parameter>,
   	      <parameter>union ccb *ccb</parameter>
 	    </paramdef>
 	  </funcPrototype></funcSynopsis>
 	  </para></listitem>
 
         <listitem><para><function>poll_func</function> - pointer to
           the driver's <function>xxx_poll()</function>
 	  <funcSynopsis><funcPrototype>
 	  <funcDef>static void
 	    <function>xxx_poll</function>
 	  </funcDef>
 	    <paramdef>
 	      <parameter>struct cam_sim *sim</parameter>
 	    </paramdef>
 	  </funcPrototype></funcSynopsis>
 	  </para></listitem>
 
         <listitem><para>driver_name - the name of the actual driver,
           such as "ncr" or "wds"</para></listitem>
 
         <listitem><para><structName>softc</structName> - pointer to the
           driver's internal descriptor for this SCSI card. This
           pointer will be used by the driver in future to get private
           data.</para></listitem>
 
         <listitem><para>unit - the controller unit number, for example
           for controller "wds0" this number will be
           0</para></listitem>
 
         <listitem><para>max_dev_transactions - maximal number of
           simultaneous transactions per SCSI target in the non-tagged
           mode. This value will be almost universally equal to 1, with
           possible exceptions only for the non-SCSI cards. Also the
           drivers that hope to take advantage by preparing one
           transaction while another one is executed may set it to 2
           but this does not seem to be worth the
           complexity.</para></listitem>
 
         <listitem><para>max_tagged_dev_transactions - the same thing,
           but in the tagged mode.  Tags are the SCSI way to initiate
           multiple transactions on a device: each transaction is
           assigned a unique tag and the transaction is sent to the
           device. When the device completes some transaction it sends
           back the result together with the tag so that the SCSI
           adapter (and the driver) can tell which transaction was
           completed. This argument is also known as the maximal tag
           depth. It depends on the abilities of the SCSI
           adapter.</para></listitem>
       </itemizedlist>
     </para>
 
     <para>Finally we register the SCSI buses associated with our SCSI
       adapter:</para>
 
 <programlisting>    if(xpt_bus_register(sim, bus_number) != CAM_SUCCESS) {
         cam_sim_free(sim, /*free_devq*/ TRUE);
         error; /* some code to handle the error */
     }</programlisting>
 
     <para>If there is one <structName>devq</structName> structure per
       SCSI bus (i.e. we consider a card with multiple buses as
       multiple cards with one bus each) then the bus number will
       always be 0, otherwise each bus on the SCSI card should be get a
       distinct number. Each bus needs its own separate structure
       cam_sim.</para>
 
     <para>After that our controller is completely hooked to the CAM
       system. The value of <structName>devq</structName> can be
       discarded now: sim will be passed as an argument in all further
       calls from CAM and devq can be derived from it.</para>
 
     <para>CAM provides the framework for such asynchronous
       events. Some events originate from the lower levels (the SIM
       drivers), some events originate from the peripheral drivers,
       some events originate from the CAM subsystem itself.  Any driver
       can register callbacks for some types of the asynchronous
       events, so that it would be notified if these events
       occur.</para>
 
     <para>A typical example of such an event is a device reset. Each
       transaction and event identifies the devices to which it applies
       by the means of "path". The target-specific events normally
       occur during a transaction with this device. So the path from
       that transaction may be re-used to report this event (this is
       safe because the event path is copied in the event reporting
       routine but not deallocated nor passed anywhere further). Also
       it's safe to allocate paths dynamically at any time including
       the interrupt routines, although that incurs certain overhead,
       and a possible problem with this approach is that there may be
       no free memory at that time.  For a bus reset event we need to
       define a wildcard path including all devices on the bus.  So we
       can create the path for the future bus reset events in advance
       and avoid problems with the future memory shortage:</para>
 
 <programlisting>    struct cam_path *path;
 
     if(xpt_create_path(&amp;path, /*periph*/NULL,
                 cam_sim_path(sim), CAM_TARGET_WILDCARD,
                 CAM_LUN_WILDCARD) != CAM_REQ_CMP) {
         xpt_bus_deregister(cam_sim_path(sim));
         cam_sim_free(sim, /*free_devq*/TRUE);
         error; /* some code to handle the error */
     }
 
     softc->wpath = path;
     softc->sim = sim;</programlisting>
 
     <para>As you can see the path includes:</para>
 
     <itemizedlist>
       <listitem><para>ID of the peripheral driver (NULL here because we have
         none)</para></listitem>
 
       <listitem><para>ID of the SIM driver
         (<function>cam_sim_path(sim)</function>)</para></listitem>
 
       <listitem><para>SCSI target number of the device (CAM_TARGET_WILDCARD
         means "all devices")</para></listitem>
 
       <listitem><para>SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means
         "all LUNs")</para></listitem>
     </itemizedlist>
 
     <para>If the driver can't allocate this path it won't be able to
       work normally, so in that case we dismantle that SCSI
       bus.</para>
 
     <para>And we save the path pointer in the
       <structName>softc</structName> structure for future use. After
       that we save the value of sim (or we can also discard it on the
       exit from <function>xxx_probe()</function> if we wish).</para>
 
     <para>That's all for a minimalistic initialization. To do things
       right there is one more issue left. </para>
 
     <para>For a SIM driver there is one particularly interesting
       event: when a target device is considered lost. In this case
       resetting the SCSI negotiations with this device may be a good
       idea. So we register a callback for this event with CAM. The
       request is passed to CAM by requesting CAM action on a CAM
       control block for this type of request:</para>
 
 <programlisting>    struct ccb_setasync csa;
 
     xpt_setup_ccb(&amp;csa.ccb_h, path, /*priority*/5);
     csa.ccb_h.func_code = XPT_SASYNC_CB;
     csa.event_enable = AC_LOST_DEVICE;
     csa.callback = xxx_async;
     csa.callback_arg = sim;
     xpt_action((union ccb *)&amp;csa);</programlisting>
 
     <para>Now we take a look at the <function>xxx_action()</function>
       and <function>xxx_poll()</function> driver entry points.</para>
 
     <para>
     <funcSynopsis><funcPrototype>
       <funcDef>static void
       <function>xxx_action</function>
       </funcDef>
       <paramdef>
         <parameter>struct cam_sim *sim</parameter>,
         <parameter>union ccb *ccb</parameter>
       </paramdef>
     </funcPrototype></funcSynopsis>
     </para>
 
     <para>Do some action on request of the CAM subsystem. Sim
       describes the SIM for the request, CCB is the request
       itself. CCB stands for "CAM Control Block". It is a union of
       many specific instances, each describing arguments for some type
       of transactions. All of these instances share the CCB header
       where the common part of arguments is stored.</para>
 
     <para>CAM supports the SCSI controllers working in both initiator
       ("normal") mode and target (simulating a SCSI device) mode. Here
       we only consider the part relevant to the initiator mode.</para>
 
     <para>There are a few function and macros (in other words,
       methods) defined to access the public data in the struct sim:</para>
 
     <itemizedlist>
       <listitem><para><function>cam_sim_path(sim)</function> - the
       path ID (see above)</para></listitem>
 
       <listitem><para><function>cam_sim_name(sim)</function> - the
       name of the sim</para></listitem>
 
       <listitem><para><function>cam_sim_softc(sim)</function> - the
       pointer to the softc (driver private data)
       structure</para></listitem>
 
       <listitem><para><function> cam_sim_unit(sim)</function> - the
       unit number</para></listitem>
 
       <listitem><para><function> cam_sim_bus(sim)</function> - the bus
       ID</para></listitem>
     </itemizedlist>
 
     <para>To identify the device, <function>xxx_action()</function> can
       get the unit number and pointer to its structure softc using
       these functions.</para>
 
     <para>The type of request is stored in
       <structField>ccb-&gt;ccb_h.func_code</structField>. So generally
       <function>xxx_action()</function> consists of a big
       switch:</para>
 
 <programlisting>    struct xxx_softc *softc = (struct xxx_softc *) cam_sim_softc(sim);
     struct ccb_hdr *ccb_h = &amp;ccb->ccb_h;
     int unit = cam_sim_unit(sim);
     int bus = cam_sim_bus(sim);
 
     switch(ccb_h->func_code) {
     case ...:
         ...
     default:
         ccb_h->status = CAM_REQ_INVALID;
         xpt_done(ccb);
         break;
     }</programlisting>
 
     <para>As can be seen from the default case (if an unknown command
       was received) the return code of the command is set into
       <structField>ccb-&gt;ccb_h.status</structField> and the completed
       CCB is returned back to CAM by calling
       <function>xpt_done(ccb)</function>. </para>
 
     <para><function>xpt_done()</function> does not have to be called
       from <function>xxx_action()</function>: For example an I/O
       request may be enqueued inside the SIM driver and/or its SCSI
       controller.  Then when the device would post an interrupt
       signaling that the processing of this request is complete
       <function>xpt_done()</function> may be called from the interrupt
       handling routine.</para>
 
     <para>Actually, the CCB status is not only assigned as a return
       code but a CCB has some status all the time. Before CCB is
       passed to the <function>xxx_action()</function> routine it gets
       the status CCB_REQ_INPROG meaning that it's in progress.  There
       are a surprising number of status values defined in
       <filename>/sys/cam/cam.h</filename> which should be able to
       represent the status of a request in great detail.  More
       interesting yet, the status is in fact a "bitwise or" of an
       enumerated status value (the lower 6 bits) and possible
       additional flag-like bits (the upper bits).  The enumerated
       values will be discussed later in more detail.  The summary of
       them can be found in the Errors Summary section.  The possible
       status flags are:</para>
 
     <itemizedlist>
 
       <listitem><para><emphasis>CAM_DEV_QFRZN</emphasis> - if the
         SIM driver gets a serious error (for example, the device does
         not respond to the selection or breaks the SCSI protocol) when
         processing a CCB it should freeze the request queue by calling
         <function>xpt_freeze_simq()</function>, return the other
         enqueued but not processed yet CCBs for this device back to
         the CAM queue, then set this flag for the troublesome CCB and
         call <function>xpt_done()</function>. This flag causes the CAM
         subsystem to unfreeze the queue after it handles the
         error.</para></listitem>
 
       <listitem><para><emphasis>CAM_AUTOSNS_VALID</emphasis> - if
         the device returned an error condition and the flag
         CAM_DIS_AUTOSENSE is not set in CCB the SIM driver must
         execute the REQUEST SENSE command automatically to extract the
         sense (extended error information) data from the device. If
         this attempt was successful the sense data should be saved in
         the CCB and this flag set.</para></listitem>
 
       <listitem><para><emphasis>CAM_RELEASE_SIMQ</emphasis> - like
         CAM_DEV_QFRZN but used in case there is some problem (or
         resource shortage) with the SCSI controller itself. Then all
         the future requests to the controller should be stopped by
         <function>xpt_freeze_simq()</function>.  The controller queue
         will be restarted after the SIM driver overcomes the shortage
         and informs CAM by returning some CCB with this flag
         set.</para></listitem>
 
       <listitem><para><emphasis>CAM_SIM_QUEUED</emphasis> - when SIM
         puts a CCB into its request queue this flag should be set (and
         removed when this CCB gets dequeued before being returned back
         to CAM). This flag is not used anywhere in the CAM code now,
         so its purpose is purely diagnostic.</para></listitem>
 
     </itemizedlist>
 
     <para>The function <function>xxx_action()</function> is not
       allowed to sleep, so all the synchronization for resource access
       must be done using SIM or device queue freezing.  Besides the
       aforementioned flags the CAM subsystem provides functions
       <function>xpt_selease_simq()</function> and
       <function>xpt_release_devq()</function> to unfreeze the queues
       directly, without passing a CCB to CAM.</para>
 
     <para>The CCB header contains the following fields:</para>
 
     <itemizedlist>
 
       <listitem><para><emphasis>path</emphasis> - path ID for the
       request</para></listitem>
 
       <listitem><para><emphasis>target_id</emphasis> - target device
       ID for the request</para></listitem>
 
       <listitem><para><emphasis>target_lun</emphasis> - LUN ID of
       the target device</para></listitem>
 
       <listitem><para><emphasis>timeout</emphasis> - timeout
       interval for this command, in milliseconds</para></listitem>
 
       <listitem><para><emphasis>timeout_ch</emphasis> - a
       convenience place for the SIM driver to store the timeout handle
       (the CAM subsystem itself does not make any assumptions about
       it)</para></listitem>
 
       <listitem><para><emphasis>flags</emphasis> - various bits of
       information about the request spriv_ptr0, spriv_ptr1 - fields
       reserved for private use by the SIM driver (such as linking to
       the SIM queues or SIM private control blocks); actually, they
       exist as unions: spriv_ptr0 and spriv_ptr1 have the type (void
       *), spriv_field0 and spriv_field1 have the type unsigned long,
       sim_priv.entries[0].bytes and sim_priv.entries[1].bytes are byte
       arrays of the size consistent with the other incarnations of the
       union and sim_priv.bytes is one array, twice
       bigger.</para></listitem>
 
     </itemizedlist>
 
     <para>The recommended way of using the SIM private fields of CCB
       is to define some meaningful names for them and use these
       meaningful names in the driver, like:</para>
 
 <programlisting>#define ccb_some_meaningful_name    sim_priv.entries[0].bytes
 #define ccb_hcb spriv_ptr1 /* for hardware control block */</programlisting>
 
     <para>The most common initiator mode requests are:</para>
     <itemizedlist>
       <listitem><para><emphasis>XPT_SCSI_IO</emphasis> - execute an
       I/O transaction</para>
 
       <para>The instance "struct ccb_scsiio csio" of the union ccb is
         used to transfer the arguments. They are:</para>
 
       <itemizedlist>
         <listitem><para><emphasis>cdb_io</emphasis> - pointer to
           the SCSI command buffer or the buffer
   	  itself</para></listitem>
 
 	<listitem><para><emphasis>cdb_len</emphasis> - SCSI
 	  command length</para></listitem>
 
 	<listitem><para><emphasis>data_ptr</emphasis> - pointer to
 	  the data buffer (gets a bit complicated if scatter/gather is
 	  used)</para></listitem>
 
 	<listitem><para><emphasis>dxfer_len</emphasis> - length of
 	  the data to transfer</para></listitem>
 
 	<listitem><para><emphasis>sglist_cnt</emphasis> - counter
 	  of the scatter/gather segments</para></listitem>
 
 	<listitem><para><emphasis>scsi_status</emphasis> - place
 	  to return the SCSI status</para></listitem>
 
 	<listitem><para><emphasis>sense_data</emphasis> - buffer
           for the SCSI sense information if the command returns an
           error (the SIM driver is supposed to run the REQUEST SENSE
           command automatically in this case if the CCB flag
           CAM_DIS_AUTOSENSE is not set)</para></listitem>
 
 	<listitem><para><emphasis>sense_len</emphasis> - the
           length of that buffer (if it happens to be higher than size
           of sense_data the SIM driver must silently assume the
           smaller value) resid, sense_resid - if the transfer of data
           or SCSI sense returned an error these are the returned
           counters of the residual (not transferred) data. They do not
           seem to be especially meaningful, so in a case when they are
           difficult to compute (say, counting bytes in the SCSI
           controller's FIFO buffer) an approximate value will do as
           well. For a successfully completed transfer they must be set
           to zero.</para></listitem>
 
 	<listitem><para><emphasis>tag_action</emphasis> - the kind
 	  of tag to use:
 	  
 	  <itemizedlist>
 	  <listitem><para>CAM_TAG_ACTION_NONE - don't use tags for this
 	  transaction</para></listitem>
 	  <listitem><para>MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG,
 	  MSG_ORDERED_Q_TAG - value equal to the appropriate tag
 	  message (see /sys/cam/scsi/scsi_message.h); this gives only
 	  the tag type, the SIM driver must assign the tag value
 	  itself</para></listitem>
 	  </itemizedlist>
 
 	  </para></listitem>
 
       </itemizedlist>
 
       <para>The general logic of handling this request is the
         following:</para>
 
       <para>The first thing to do is to check for possible races, to
         make sure that the command did not get aborted when it was
         sitting in the queue:</para>
 
 <programlisting>    struct ccb_scsiio *csio = &amp;ccb->csio;
 
     if ((ccb_h->status &amp; CAM_STATUS_MASK) != CAM_REQ_INPROG) {
         xpt_done(ccb);
         return;
     }</programlisting>
 
       <para>Also we check that the device is supported at all by our
         controller:</para>
 
 <programlisting>    if(ccb_h->target_id > OUR_MAX_SUPPORTED_TARGET_ID
     || cch_h->target_id == OUR_SCSI_CONTROLLERS_OWN_ID) {
         ccb_h->status = CAM_TID_INVALID;
         xpt_done(ccb);
         return;
     }
     if(ccb_h->target_lun > OUR_MAX_SUPPORTED_LUN) {
         ccb_h->status = CAM_LUN_INVALID;
         xpt_done(ccb);
         return;
     }</programlisting>
 
       <para>Then allocate whatever data structures (such as
         card-dependent hardware control block) we need to process this
         request. If we can't then freeze the SIM queue and remember
         that we have a pending operation, return the CCB back and ask
         CAM to re-queue it. Later when the resources become available
         the SIM queue must be unfrozen by returning a ccb with the
         CAM_SIMQ_RELEASE bit set in its status. Otherwise, if all went
         well, link the CCB with the hardware control block (HCB) and
         mark it as queued.</para>
 
 <programlisting>    struct xxx_hcb *hcb = allocate_hcb(softc, unit, bus);
 
     if(hcb == NULL) {
         softc->flags |= RESOURCE_SHORTAGE;
         xpt_freeze_simq(sim, /*count*/1);
         ccb_h->status = CAM_REQUEUE_REQ;
         xpt_done(ccb);
         return;
     }
 
     hcb->ccb = ccb; ccb_h->ccb_hcb = (void *)hcb;
     ccb_h->status |= CAM_SIM_QUEUED;</programlisting>
 
       <para>Extract the target data from CCB into the hardware control
         block. Check if we are asked to assign a tag and if yes then
         generate an unique tag and build the SCSI tag messages. The
         SIM driver is also responsible for negotiations with the
         devices to set the maximal mutually supported bus width,
         synchronous rate and offset.</para>
 
 <programlisting>    hcb->target = ccb_h->target_id; hcb->lun = ccb_h->target_lun;
     generate_identify_message(hcb);
     if( ccb_h->tag_action != CAM_TAG_ACTION_NONE )
         generate_unique_tag_message(hcb, ccb_h->tag_action);
     if( !target_negotiated(hcb) )
         generate_negotiation_messages(hcb);</programlisting>
 
       <para>Then set up the SCSI command. The command storage may be
         specified in the CCB in many interesting ways, specified by
         the CCB flags.  The command buffer can be contained in CCB or
         pointed to, in the latter case the pointer may be physical or
         virtual. Since the hardware commonly needs physical address we
         always convert the address to the physical one.</para>
 
       <para>A NOT-QUITE RELATED NOTE: Normally this is done by a call
         to vtophys(), but for the PCI device (which account for most
         of the SCSI controllers now) drivers' portability to the Alpha
         architecture the conversion must be done by vtobus() instead
         due to special Alpha quirks.  [IMHO it would be much better to
         have two separate functions, vtop() and ptobus() then vtobus()
         would be a simple superposition of them.]  In case if a
         physical address is requested it's OK to return the CCB with
         the status CAM_REQ_INVALID, the current drivers do that.  But
         it's also possible to compile the Alpha-specific piece of
         code, as in this example (there should be a more direct way to
         do that, without conditional compilation in the drivers). If
         necessary a physical address can be also converted or mapped
         back to a virtual address but with big pain, so we don't do
         that.</para>
 
 <programlisting>    if(ccb_h->flags &amp; CAM_CDB_POINTER) {
         /* CDB is a pointer */
         if(!(ccb_h->flags &amp; CAM_CDB_PHYS)) {
             /* CDB pointer is virtual */
             hcb->cmd = vtobus(csio->cdb_io.cdb_ptr);
         } else {
             /* CDB pointer is physical */
 #if defined(__alpha__)
             hcb->cmd = csio->cdb_io.cdb_ptr | alpha_XXX_dmamap_or ;
 #else
             hcb->cmd = csio->cdb_io.cdb_ptr ;
 #endif
         }
     } else {
         /* CDB is in the ccb (buffer) */
         hcb->cmd = vtobus(csio->cdb_io.cdb_bytes);
     }
     hcb->cmdlen = csio->cdb_len;</programlisting>
 
       <para>Now it's time to set up the data. Again, the data storage
         may be specified in the CCB in many interesting ways,
         specified by the CCB flags.  First we get the direction of the
         data transfer. The simplest case is if there is no data to
         transfer:</para>
 
 <programlisting>    int dir = (ccb_h->flags &amp; CAM_DIR_MASK);
 
     if (dir == CAM_DIR_NONE)
         goto end_data;</programlisting>
 
       <para>Then we check if the data is in one chunk or in a
         scatter-gather list, and the addresses are physical or
         virtual. The SCSI controller may be able to handle only a
         limited number of chunks of limited length.  If the request
         hits this limitation we return an error. We use a special
         function to return the CCB to handle in one place the HCB
         resource shortages. The functions to add chunks are
         driver-dependent, and here we leave them without detailed
         implementation. See description of the SCSI command (CDB)
         handling for the details on the address-translation issues.
         If some variation is too difficult or impossible to implement
         with a particular card it's OK to return the status
         CAM_REQ_INVALID. Actually, it seems like the scatter-gather
         ability is not used anywhere in the CAM code now. But at least
         the case for a single non-scattered virtual buffer must be
         implemented, it's actively used by CAM.</para>
 
 <programlisting>    int rv;
     
     initialize_hcb_for_data(hcb);
 
     if((!(ccb_h->flags &amp; CAM_SCATTER_VALID)) { 
         /* single buffer */
         if(!(ccb_h->flags &amp; CAM_DATA_PHYS)) {
             rv = add_virtual_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir);
             }
         } else {
             rv = add_physical_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir);
         }
     } else {
         int i;
         struct bus_dma_segment *segs;
         segs = (struct bus_dma_segment *)csio->data_ptr;
 
         if ((ccb_h->flags &amp; CAM_SG_LIST_PHYS) != 0) {
             /* The SG list pointer is physical */
             rv = setup_hcb_for_physical_sg_list(hcb, segs, csio->sglist_cnt);
         } else if (!(ccb_h->flags &amp; CAM_DATA_PHYS)) {
             /* SG buffer pointers are virtual */
             for (i = 0; i < csio->sglist_cnt; i++) {
                 rv = add_virtual_chunk(hcb, segs[i].ds_addr, 
                     segs[i].ds_len, dir);
                 if (rv != CAM_REQ_CMP)
                     break;
             }
         } else {
             /* SG buffer pointers are physical */
             for (i = 0; i < csio->sglist_cnt; i++) {
                 rv = add_physical_chunk(hcb, segs[i].ds_addr, 
                     segs[i].ds_len, dir);
                 if (rv != CAM_REQ_CMP)
                     break;
             }
         }
     }
     if(rv != CAM_REQ_CMP) {
         /* we expect that add_*_chunk() functions return CAM_REQ_CMP
          * if they added a chunk successfully, CAM_REQ_TOO_BIG if
          * the request is too big (too many bytes or too many chunks),
          * CAM_REQ_INVALID in case of other troubles
          */
         free_hcb_and_ccb_done(hcb, ccb, rv);
         return;
     }
     end_data:</programlisting>
 
     <para>If disconnection is disabled for this CCB we pass this
       information to the hcb:</para>
 
 <programlisting>    if(ccb_h->flags &amp; CAM_DIS_DISCONNECT)
         hcb_disable_disconnect(hcb);</programlisting>
 
     <para>If the controller is able to run REQUEST SENSE command all
       by itself then the value of the flag CAM_DIS_AUTOSENSE should
       also be passed to it, to prevent automatic REQUEST SENSE if the
       CAM subsystem does not want it.</para>
 
     <para>The only thing left is to set up the timeout, pass our hcb
       to the hardware and return, the rest will be done by the
       interrupt handler (or timeout handler).</para>
 
 <programlisting>    ccb_h->timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, 
         (ccb_h->timeout * hz) / 1000); /* convert milliseconds to ticks */
     put_hcb_into_hardware_queue(hcb);
     return;</programlisting>
 
     <para>And here is a possible implementation of the function
     returning CCB:</para>
 
 <programlisting>    static void
     free_hcb_and_ccb_done(struct xxx_hcb *hcb, union ccb *ccb, u_int32_t status)
     {
         struct xxx_softc *softc = hcb->softc;
 
         ccb->ccb_h.ccb_hcb = 0;
         if(hcb != NULL) {
             untimeout(xxx_timeout, (caddr_t) hcb, ccb->ccb_h.timeout_ch);
             /* we're about to free a hcb, so the shortage has ended */
             if(softc->flags &amp; RESOURCE_SHORTAGE)  {
                 softc->flags &amp;= ~RESOURCE_SHORTAGE;
                 status |= CAM_RELEASE_SIMQ;
             }
             free_hcb(hcb); /* also removes hcb from any internal lists */
         }
         ccb->ccb_h.status = status | 
             (ccb->ccb_h.status &amp; ~(CAM_STATUS_MASK|CAM_SIM_QUEUED));
         xpt_done(ccb);
     }</programlisting>
     </listitem>
 
     <listitem><para><emphasis>XPT_RESET_DEV</emphasis> - send the SCSI "BUS
     DEVICE RESET" message to a device</para>
 
     <para>There is no data transferred in CCB except the header and
       the most interesting argument of it is target_id. Depending on
       the controller hardware a hardware control block just like for
       the XPT_SCSI_IO request may be constructed (see XPT_SCSI_IO
       request description) and sent to the controller or the SCSI
       controller may be immediately programmed to send this RESET
       message to the device or this request may be just not supported
       (and return the status CAM_REQ_INVALID).  Also on completion of
       the request all the disconnected transactions for this target
       must be aborted (probably in the interrupt routine).</para>
 
     <para>Also all the current negotiations for the target are lost on
       reset, so they might be cleaned too. Or they clearing may be
       deferred, because anyway the target would request re-negotiation
       on the next transaction.</para></listitem>
 
     <listitem><para><emphasis>XPT_RESET_BUS</emphasis> - send the RESET signal
       to the SCSI bus</para>
 
     <para>No arguments are passed in the CCB, the only interesting
       argument is the SCSI bus indicated by the struct sim
       pointer.</para>
 
     <para>A minimalistic implementation would forget the SCSI
       negotiations for all the devices on the bus and return the
       status CAM_REQ_CMP.</para>
 
     <para>The proper implementation would in addition actually reset
       the SCSI bus (possible also reset the SCSI controller) and mark
       all the CCBs being processed, both those in the hardware queue
       and those being disconnected, as done with the status
       CAM_SCSI_BUS_RESET. Like:</para>
 
 <programlisting>    int targ, lun;
     struct xxx_hcb *h, *hh;
     struct ccb_trans_settings neg;
     struct cam_path *path;
 
     /* The SCSI bus reset may take a long time, in this case its completion
      * should be checked by interrupt or timeout. But for simplicity
      * we assume here that it's really fast.
      */
     reset_scsi_bus(softc);
 
     /* drop all enqueued CCBs */
     for(h = softc->first_queued_hcb; h != NULL; h = hh) {
         hh = h->next;
         free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
     }
 
     /* the clean values of negotiations to report */
     neg.bus_width = 8;
     neg.sync_period = neg.sync_offset = 0;
     neg.valid = (CCB_TRANS_BUS_WIDTH_VALID
         | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID);
 
     /* drop all disconnected CCBs and clean negotiations  */
     for(targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) {
         clean_negotiations(softc, targ);
 
         /* report the event if possible */
         if(xpt_create_path(&amp;path, /*periph*/NULL,
                 cam_sim_path(sim), targ,
                 CAM_LUN_WILDCARD) == CAM_REQ_CMP) {
             xpt_async(AC_TRANSFER_NEG, path, &amp;neg);
             xpt_free_path(path);
         }
 
         for(lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) 
             for(h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) {
                 hh=h->next;
                 free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
             }
     }
 
     ccb->ccb_h.status = CAM_REQ_CMP;
     xpt_done(ccb);
 
     /* report the event */
     xpt_async(AC_BUS_RESET, softc->wpath, NULL);
     return;</programlisting>
 
     <para>Implementing the SCSI bus reset as a function may be a good
       idea because it would be re-used by the timeout function as a
       last resort if the things go wrong.</para></listitem>
 
     <listitem><para><emphasis>XPT_ABORT</emphasis> - abort the specified
       CCB</para>
 
     <para>The arguments are transferred in the instance "struct
       ccb_abort cab" of the union ccb. The only argument field in it
       is:</para>
 
     <para><emphasis>abort_ccb</emphasis> - pointer to the CCB to be
       aborted</para>
 
     <para>If the abort is not supported just return the status
       CAM_UA_ABORT.  This is also the easy way to minimally implement
       this call, return CAM_UA_ABORT in any case.</para>
 
     <para>The hard way is to implement this request honestly. First
       check that abort applies to a SCSI transaction:</para>
 
 <programlisting>    struct ccb *abort_ccb;
     abort_ccb = ccb->cab.abort_ccb;
 
     if(abort_ccb->ccb_h.func_code != XPT_SCSI_IO) {
         ccb->ccb_h.status = CAM_UA_ABORT;
         xpt_done(ccb);
         return;
     }</programlisting>
 
     <para>Then it's necessary to find this CCB in our queue. This can
       be done by walking the list of all our hardware control blocks
       in search for one associated with this CCB:</para>
 
 <programlisting>    struct xxx_hcb *hcb, *h;
 
     hcb = NULL;
 
     /* We assume that softc->first_hcb is the head of the list of all
      * HCBs associated with this bus, including those enqueued for 
      * processing, being processed by hardware and disconnected ones.
      */
     for(h = softc->first_hcb; h != NULL; h = h->next) {
         if(h->ccb == abort_ccb) {
             hcb = h;
             break;
         }
     }
 
     if(hcb == NULL) {
         /* no such CCB in our queue */
         ccb->ccb_h.status = CAM_PATH_INVALID; 
         xpt_done(ccb);
         return;
     }
 
     hcb=found_hcb;</programlisting>
 
     <para>Now we look at the current processing status of the HCB. It
       may be either sitting in the queue waiting to be sent to the
       SCSI bus, being transferred right now, or disconnected and
       waiting for the result of the command, or actually completed by
       hardware but not yet marked as done by software.  To make sure
       that we don't get in any races with hardware we mark the HCB as
       being aborted, so that if this HCB is about to be sent to the
       SCSI bus the SCSI controller will see this flag and skip
       it.</para>
 
 <programlisting>    int hstatus;
 
     /* shown as a function, in case special action is needed to make
      * this flag visible to hardware 
      */
     set_hcb_flags(hcb, HCB_BEING_ABORTED);
 
     abort_again:
 
     hstatus = get_hcb_status(hcb);
     switch(hstatus) {
     case HCB_SITTING_IN_QUEUE:
         remove_hcb_from_hardware_queue(hcb);
         /* FALLTHROUGH */
     case HCB_COMPLETED:
         /* this is an easy case */
         free_hcb_and_ccb_done(hcb, abort_ccb, CAM_REQ_ABORTED);
         break;</programlisting>
 
     <para>If the CCB is being transferred right now we would like to
       signal to the SCSI controller in some hardware-dependent way
       that we want to abort the current transfer. The SCSI controller
       would set the SCSI ATTENTION signal and when the target responds
       to it send an ABORT message. We also reset the timeout to make
       sure that the target is not sleeping forever.  If the command
       would not get aborted in some reasonable time like 10 seconds
       the timeout routine would go ahead and reset the whole SCSI bus.
       Because the command will be aborted in some reasonable time we
       can just return the abort request now as successfully completed,
       and mark the aborted CCB as aborted (but not mark it as done
       yet).</para>
 
 <programlisting>    case HCB_BEING_TRANSFERRED:
         untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch);
         abort_ccb->ccb_h.timeout_ch = 
             timeout(xxx_timeout, (caddr_t) hcb, 10 * hz);
         abort_ccb->ccb_h.status = CAM_REQ_ABORTED;
         /* ask the controller to abort that HCB, then generate
          * an interrupt and stop
          */
         if(signal_hardware_to_abort_hcb_and_stop(hcb) < 0) {
             /* oops, we missed the race with hardware, this transaction
              * got off the bus before we aborted it, try again */
             goto abort_again;
         }
 
         break;</programlisting>
 
     <para>If the CCB is in the list of disconnected then set it up as
       an abort request and re-queue it at the front of hardware
       queue. Reset the timeout and report the abort request to be
       completed.</para>
 
 <programlisting>    case HCB_DISCONNECTED:
         untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch);
         abort_ccb->ccb_h.timeout_ch = 
             timeout(xxx_timeout, (caddr_t) hcb, 10 * hz);
         put_abort_message_into_hcb(hcb);
         put_hcb_at_the_front_of_hardware_queue(hcb);
         break;
     }
     ccb->ccb_h.status = CAM_REQ_CMP;
     xpt_done(ccb);
     return;</programlisting>
 
     <para>That's all for the ABORT request, although there is one more
       issue.  Because the ABORT message cleans all the ongoing
       transactions on a LUN we have to mark all the other active
       transactions on this LUN as aborted.  That should be done in the
       interrupt routine, after the transaction gets aborted.</para>
 
     <para>Implementing the CCB abort as a function may be quite a good
       idea, this function can be re-used if an I/O transaction times
       out. The only difference would be that the timed out transaction
       would return the status CAM_CMD_TIMEOUT for the timed out
       request. Then the case XPT_ABORT would be small, like
       that:</para>
 
 <programlisting>    case XPT_ABORT:
         struct ccb *abort_ccb;
         abort_ccb = ccb->cab.abort_ccb;
 
         if(abort_ccb->ccb_h.func_code != XPT_SCSI_IO) {
             ccb->ccb_h.status = CAM_UA_ABORT;
             xpt_done(ccb);
             return;
         }
         if(xxx_abort_ccb(abort_ccb, CAM_REQ_ABORTED) < 0)
             /* no such CCB in our queue */
             ccb->ccb_h.status = CAM_PATH_INVALID; 
         else
             ccb->ccb_h.status = CAM_REQ_CMP;
         xpt_done(ccb);
         return;</programlisting>
     </listitem>
 
     <listitem><para><emphasis>XPT_SET_TRAN_SETTINGS</emphasis> - explicitly
       set values of SCSI transfer settings</para>
 
     <para>The arguments are transferred in the instance "struct ccb_trans_setting cts" 
 of the union ccb:</para>
 
     <itemizedlist>
       <listitem><para><emphasis>valid</emphasis> - a bitmask showing
       which settings should be updated:</para></listitem>
 
       <listitem><para><emphasis>CCB_TRANS_SYNC_RATE_VALID</emphasis>
       - synchronous transfer rate</para></listitem>
 
       <listitem><para><emphasis>CCB_TRANS_SYNC_OFFSET_VALID</emphasis>
       - synchronous offset</para></listitem>
 
       <listitem><para><emphasis>CCB_TRANS_BUS_WIDTH_VALID</emphasis>
       - bus width</para></listitem>
 
       <listitem><para><emphasis>CCB_TRANS_DISC_VALID</emphasis> -
       set enable/disable disconnection</para></listitem> 
 
       <listitem><para><emphasis>CCB_TRANS_TQ_VALID</emphasis> - set
       enable/disable tagged queuing</para></listitem> 
 
       <listitem><para><emphasis>flags</emphasis> - consists of two
       parts, binary arguments and identification of
       sub-operations.  The binary arguments are :</para>
       <itemizedlist>
         <listitem><para><emphasis>CCB_TRANS_DISC_ENB</emphasis> - enable disconnection</para></listitem>
 	<listitem><para><emphasis>CCB_TRANS_TAG_ENB</emphasis> -
 	enable tagged queuing</para></listitem>
       </itemizedlist>
       </listitem>
 
       <listitem><para>the sub-operations are:</para>
       <itemizedlist>
         <listitem><para><emphasis>CCB_TRANS_CURRENT_SETTINGS</emphasis>
         - change the current negotiations</para></listitem>
 
 	<listitem><para><emphasis>CCB_TRANS_USER_SETTINGS</emphasis>
         - remember the desired user values sync_period, sync_offset -
         self-explanatory, if sync_offset==0 then the asynchronous mode
         is requested bus_width - bus width, in bits (not
         bytes)</para></listitem>
       </itemizedlist>
       </listitem>
 
     </itemizedlist>
 
     <para>Two sets of negotiated parameters are supported, the user
       settings and the current settings. The user settings are not
       really used much in the SIM drivers, this is mostly just a piece
       of memory where the upper levels can store (and later recall)
       its ideas about the parameters.  Setting the user parameters
       does not cause re-negotiation of the transfer rates. But when
       the SCSI controller does a negotiation it must never set the
       values higher than the user parameters, so it's essentially the
       top boundary.</para>
 
     <para>The current settings are, as the name says,
       current. Changing them means that the parameters must be
       re-negotiated on the next transfer.  Again, these "new current
       settings" are not supposed to be forced on the device, just they
       are used as the initial step of negotiations.  Also they must be
       limited by actual capabilities of the SCSI controller: for
       example, if the SCSI controller has 8-bit bus and the request
       asks to set 16-bit wide transfers this parameter must be
       silently truncated to 8-bit transfers before sending it to the
       device.</para>
 
     <para>One caveat is that the bus width and synchronous parameters
       are per target while the disconnection and tag enabling
       parameters are per lun.</para>
 
     <para>The recommended implementation is to keep 3 sets of
       negotiated (bus width and synchronous transfer)
       parameters:</para>
 
     <itemizedlist>
       <listitem><para><emphasis>user</emphasis> - the user set, as
       above</para></listitem>
 
       <listitem><para><emphasis>current</emphasis> - those actually
       in effect</para></listitem>
 
       <listitem><para><emphasis>goal</emphasis> - those requested by
       setting of the "current" parameters</para></listitem>
     </itemizedlist>
 
     <para>The code looks like:</para>
 
 <programlisting>    struct ccb_trans_settings *cts;
     int targ, lun;
     int flags;
 
     cts = &amp;ccb->cts;
     targ = ccb_h->target_id;
     lun = ccb_h->target_lun;
     flags = cts->flags;
     if(flags &amp; CCB_TRANS_USER_SETTINGS) {
         if(flags &amp; CCB_TRANS_SYNC_RATE_VALID)
             softc->user_sync_period[targ] = cts->sync_period;
         if(flags &amp; CCB_TRANS_SYNC_OFFSET_VALID)
             softc->user_sync_offset[targ] = cts->sync_offset;
         if(flags &amp; CCB_TRANS_BUS_WIDTH_VALID)
             softc->user_bus_width[targ] = cts->bus_width;
 
         if(flags &amp; CCB_TRANS_DISC_VALID) {
             softc->user_tflags[targ][lun] &amp;= ~CCB_TRANS_DISC_ENB;
             softc->user_tflags[targ][lun] |= flags &amp; CCB_TRANS_DISC_ENB;
         }
         if(flags &amp; CCB_TRANS_TQ_VALID) {
             softc->user_tflags[targ][lun] &amp;= ~CCB_TRANS_TQ_ENB;
             softc->user_tflags[targ][lun] |= flags &amp; CCB_TRANS_TQ_ENB;
         }
     }
     if(flags &amp; CCB_TRANS_CURRENT_SETTINGS) {
         if(flags &amp; CCB_TRANS_SYNC_RATE_VALID)
             softc->goal_sync_period[targ] = 
                 max(cts->sync_period, OUR_MIN_SUPPORTED_PERIOD);
         if(flags &amp; CCB_TRANS_SYNC_OFFSET_VALID)
             softc->goal_sync_offset[targ] = 
                 min(cts->sync_offset, OUR_MAX_SUPPORTED_OFFSET);
         if(flags &amp; CCB_TRANS_BUS_WIDTH_VALID)
             softc->goal_bus_width[targ] = min(cts->bus_width, OUR_BUS_WIDTH);
 
         if(flags &amp; CCB_TRANS_DISC_VALID) {
             softc->current_tflags[targ][lun] &amp;= ~CCB_TRANS_DISC_ENB;
             softc->current_tflags[targ][lun] |= flags &amp; CCB_TRANS_DISC_ENB;
         }
         if(flags &amp; CCB_TRANS_TQ_VALID) {
             softc->current_tflags[targ][lun] &amp;= ~CCB_TRANS_TQ_ENB;
             softc->current_tflags[targ][lun] |= flags &amp; CCB_TRANS_TQ_ENB;
         }
     }
     ccb->ccb_h.status = CAM_REQ_CMP;
     xpt_done(ccb);
     return;</programlisting>
 
     <para>Then when the next I/O request will be processed it will
       check if it has to re-negotiate, for example by calling the
       function target_negotiated(hcb).  It can be implemented like
       this:</para>
 
 <programlisting>    int
     target_negotiated(struct xxx_hcb *hcb)
     {
         struct softc *softc = hcb->softc;
         int targ = hcb->targ;
 
         if( softc->current_sync_period[targ] != softc->goal_sync_period[targ]
         || softc->current_sync_offset[targ] != softc->goal_sync_offset[targ]
         || softc->current_bus_width[targ] != softc->goal_bus_width[targ] )
             return 0; /* FALSE */
         else
             return 1; /* TRUE */
     }</programlisting>
 
     <para>After the values are re-negotiated the resulting values must
       be assigned to both current and goal parameters, so for future
       I/O transactions the current and goal parameters would be the
       same and <function>target_negotiated()</function> would return
       TRUE. When the card is initialized (in
       <function>xxx_attach()</function>) the current negotiation
       values must be initialized to narrow asynchronous mode, the goal
       and current values must be initialized to the maximal values
       supported by controller.</para></listitem>
 
     <listitem><para><emphasis>XPT_GET_TRAN_SETTINGS</emphasis> - get values of
     SCSI transfer settings</para>
 
     <para>This operations is the reverse of
       XPT_SET_TRAN_SETTINGS. Fill up the CCB instance "struct
       ccb_trans_setting cts" with data as requested by the flags
       CCB_TRANS_CURRENT_SETTINGS or CCB_TRANS_USER_SETTINGS (if both
       are set then the existing drivers return the current
       settings). Set all the bits in the valid field.</para></listitem>
 
     <listitem><para><emphasis>XPT_CALC_GEOMETRY</emphasis> - calculate logical
       (BIOS) geometry of the disk</para>
 
     <para>The arguments are transferred in the instance "struct
       ccb_calc_geometry ccg" of the union ccb:</para>
 
     <itemizedlist>
 
       <listitem><para><emphasis>block_size</emphasis> - input, block
       (A.K.A sector) size in bytes</para></listitem>
 
       <listitem><para><emphasis>volume_size</emphasis> - input,
       volume size in bytes</para></listitem>
 
       <listitem><para><emphasis>cylinders</emphasis> - output,
       logical cylinders</para></listitem>
 
       <listitem><para><emphasis>heads</emphasis> - output, logical
       heads</para></listitem>
 
       <listitem><para><emphasis>secs_per_track</emphasis> - output,
       logical sectors per track</para></listitem>
 
     </itemizedlist>
 
     <para>If the returned geometry differs much enough from what the
       SCSI controller BIOS thinks and a disk on this SCSI controller
       is used as bootable the system may not be able to boot. The
       typical calculation example taken from the aic7xxx driver
       is:</para>
 
 <programlisting>    struct    ccb_calc_geometry *ccg;
     u_int32_t size_mb;
     u_int32_t secs_per_cylinder;
     int   extended;
 
     ccg = &amp;ccb->ccg;
     size_mb = ccg->volume_size
         / ((1024L * 1024L) / ccg->block_size);
     extended = check_cards_EEPROM_for_extended_geometry(softc);
 
     if (size_mb > 1024 &amp;&amp; extended) {
         ccg->heads = 255;
         ccg->secs_per_track = 63;
     } else {
         ccg->heads = 64;
         ccg->secs_per_track = 32;
     }
     secs_per_cylinder = ccg->heads * ccg->secs_per_track;
     ccg->cylinders = ccg->volume_size / secs_per_cylinder;
     ccb->ccb_h.status = CAM_REQ_CMP;
     xpt_done(ccb);
     return;</programlisting>
 
     <para>This gives the general idea, the exact calculation depends
       on the quirks of the particular BIOS. If BIOS provides no way
       set the "extended translation" flag in EEPROM this flag should
       normally be assumed equal to 1. Other popular geometries
       are:</para>
 
 <programlisting>    128 heads, 63 sectors - Symbios controllers
     16 heads, 63 sectors - old controllers</programlisting>
 
     <para>Some system BIOSes and SCSI BIOSes fight with each other
       with variable success, for example a combination of Symbios
       875/895 SCSI and Phoenix BIOS can give geometry 128/63 after
       power up and 255/63 after a hard reset or soft reboot.</para>
     </listitem>
 
     <listitem><para><emphasis>XPT_PATH_INQ</emphasis> - path inquiry, in other
       words get the SIM driver and SCSI controller (also known as HBA
       - Host Bus Adapter) properties</para>
 
     <para>The properties are returned in the instance "struct
 ccb_pathinq cpi" of the union ccb:</para>
 
     <itemizedlist>
 
       <listitem><para>version_num - the SIM driver version number, now
       all drivers use 1</para></listitem>
 
       <listitem><para>hba_inquiry - bitmask of features supported by
       the controller:</para></listitem>
 
       <listitem><para>PI_MDP_ABLE - supports MDP message (something
       from SCSI3?)</para></listitem>
 
       <listitem><para>PI_WIDE_32 - supports 32 bit wide
       SCSI</para></listitem>
 
       <listitem><para>PI_WIDE_16 - supports 16 bit wide
       SCSI</para></listitem>
 
       <listitem><para>PI_SDTR_ABLE - can negotiate synchronous
       transfer rate</para></listitem>
 
       <listitem><para>PI_LINKED_CDB - supports linked
       commands</para></listitem>
 
       <listitem><para>PI_TAG_ABLE - supports tagged
       commands</para></listitem>
 
       <listitem><para>PI_SOFT_RST - supports soft reset alternative
         (hard reset and soft reset are mutually exclusive within a
         SCSI bus)</para></listitem>
 
       <listitem><para>target_sprt - flags for target mode support, 0
         if unsupported</para></listitem>
 
       <listitem><para>hba_misc - miscellaneous controller
         features:</para></listitem>
 
       <listitem><para>PIM_SCANHILO - bus scans from high ID to low
         ID</para></listitem>
 
       <listitem><para>PIM_NOREMOVE - removable devices not included in
         scan</para></listitem>
 
       <listitem><para>PIM_NOINITIATOR - initiator role not
         supported</para></listitem>
 
       <listitem><para>PIM_NOBUSRESET - user has disabled initial BUS
         RESET</para></listitem>
 
       <listitem><para>hba_eng_cnt - mysterious HBA engine count,
         something related to compression, now is always set to
         0</para></listitem>
 
       <listitem><para>vuhba_flags - vendor-unique flags, unused
         now</para></listitem>
 
       <listitem><para>max_target - maximal supported target ID (7 for
         8-bit bus, 15 for 16-bit bus, 127 for Fibre
         Channel)</para></listitem>
 
       <listitem><para>max_lun - maximal supported LUN ID (7 for older
         SCSI controllers, 63 for newer ones)</para></listitem>
 
       <listitem><para>async_flags - bitmask of installed Async
         handler, unused now</para></listitem>
 
       <listitem><para>hpath_id - highest Path ID in the subsystem,
         unused now</para></listitem>
 
       <listitem><para>unit_number - the controller unit number,
         cam_sim_unit(sim)</para></listitem>
 
       <listitem><para>bus_id - the bus number,
         cam_sim_bus(sim)</para></listitem>
 
       <listitem><para>initiator_id - the SCSI ID of the controller
         itself</para></listitem>
 
       <listitem><para>base_transfer_speed - nominal transfer speed in
         KB/s for asynchronous narrow transfers, equals to 3300 for
         SCSI</para></listitem>
 
       <listitem><para>sim_vid - SIM driver's vendor id, a
         zero-terminated string of maximal length SIM_IDLEN including
         the terminating zero</para></listitem>
 
       <listitem><para>hba_vid - SCSI controller's vendor id, a
         zero-terminated string of maximal length HBA_IDLEN including
         the terminating zero</para></listitem>
 
       <listitem><para>dev_name - device driver name, a zero-terminated
         string of maximal length DEV_IDLEN including the terminating
         zero, equal to cam_sim_name(sim)</para></listitem>
 
     </itemizedlist>
 
     <para>The recommended way of setting the string fields is using
     strncpy, like:</para>
 
 <programlisting>    strncpy(cpi->dev_name, cam_sim_name(sim), DEV_IDLEN);</programlisting>
 
     <para>After setting the values set the status to CAM_REQ_CMP and mark the
 CCB as done.</para>
     </listitem>
     </itemizedlist>
 
   </sect1>
 
   <sect1>
     <title>Polling</title>
 
     <funcSynopsis><funcPrototype>
     <funcDef>static void
       <function>xxx_poll</function>
     </funcDef>
     <paramdef>
       <parameter>struct cam_sim *sim</parameter>
     </paramdef>
     </funcPrototype></funcSynopsis>
 
     <para>The poll function is used to simulate the interrupts when
       the interrupt subsystem is not functioning (for example, when
       the system has crashed and is creating the system dump). The CAM
       subsystem sets the proper interrupt level before calling the
       poll routine. So all it needs to do is to call the interrupt
       routine (or the other way around, the poll routine may be doing
       the real action and the interrupt routine would just call the
       poll routine). Why bother about a separate function then ?
       Because of different calling conventions. The
       <function>xxx_poll</function> routine gets the struct cam_sim
       pointer as its argument when the PCI interrupt routine by common
       convention gets pointer to the struct
       <structName>xxx_softc</structName> and the ISA interrupt routine
       gets just the device unit number. So the poll routine would
       normally look as:</para>
 
 <programlisting>static void 
 xxx_poll(struct cam_sim *sim)
 {
     xxx_intr((struct xxx_softc *)cam_sim_softc(sim)); /* for PCI device */
 }</programlisting>
 
     <para>or</para>
 
 <programlisting>static void 
 xxx_poll(struct cam_sim *sim)
 {
     xxx_intr(cam_sim_unit(sim)); /* for ISA device */
 }</programlisting>
 
   </sect1>
 
   <sect1>
     <title>Asynchronous Events</title>
 
     <para>If an asynchronous event callback has been set up then the
       callback function should be defined.</para>
 
 <programlisting>static void
 ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)</programlisting>
 
     <itemizedlist>
       <listitem><para>callback_arg - the value supplied when registering the
       callback</para></listitem>
 
       <listitem><para>code - identifies the type of event</para></listitem>
 
       <listitem><para>path - identifies the devices to which the event
       applies</para></listitem>
 
       <listitem><para>arg - event-specific argument</para></listitem>
     </itemizedlist>
 
     <para>Implementation for a single type of event, AC_LOST_DEVICE,
       looks like:</para>
 
 <programlisting>    struct xxx_softc *softc;
     struct cam_sim *sim;
     int targ;
     struct ccb_trans_settings neg;
 
     sim = (struct cam_sim *)callback_arg;
     softc = (struct xxx_softc *)cam_sim_softc(sim);
     switch (code) {
     case AC_LOST_DEVICE:
         targ = xpt_path_target_id(path);
         if(targ <= OUR_MAX_SUPPORTED_TARGET) {
             clean_negotiations(softc, targ);
             /* send indication to CAM */
             neg.bus_width = 8;
             neg.sync_period = neg.sync_offset = 0;
             neg.valid = (CCB_TRANS_BUS_WIDTH_VALID
                 | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID);
             xpt_async(AC_TRANSFER_NEG, path, &amp;neg);
         }
         break;
     default:
         break;
     }</programlisting>
 
   </sect1>
 
   <sect1>
     <title>Interrupts</title>
 
     <para>The exact type of the interrupt routine depends on the type
       of the peripheral bus (PCI, ISA and so on) to which the SCSI
       controller is connected.</para>
 
     <para>The interrupt routines of the SIM drivers run at the
       interrupt level splcam. So <function>splcam()</function> should
       be used in the driver to synchronize activity between the
       interrupt routine and the rest of the driver (for a
       multiprocessor-aware driver things get yet more interesting but
       we ignore this case here). The pseudo-code in this document
       happily ignores the problems of synchronization. The real code
       must not ignore them. A simple-minded approach is to set
       <function>splcam()</function> on the entry to the other routines
       and reset it on return thus protecting them by one big critical
       section. To make sure that the interrupt level will be always
       restored a wrapper function can be defined, like:</para>
 
 <programlisting>    static void 
     xxx_action(struct cam_sim *sim, union ccb *ccb)
     {
         int s;
         s = splcam();
         xxx_action1(sim, ccb);
         splx(s);
     }
 
     static void 
     xxx_action1(struct cam_sim *sim, union ccb *ccb)
     {
         ... process the request ...
     }</programlisting>
 
     <para>This approach is simple and robust but the problem with it
       is that interrupts may get blocked for a relatively long time
       and this would negatively affect the system's performance. On
       the other hand the functions of the <function>spl()</function>
       family have rather high overhead, so vast amount of tiny
       critical sections may not be good either.</para>
 
     <para>The conditions handled by the interrupt routine and the
       details depend very much on the hardware. We consider the set of
       "typical" conditions.</para>
 
     <para>First, we check if a SCSI reset was encountered on the bus
       (probably caused by another SCSI controller on the same SCSI
       bus). If so we drop all the enqueued and disconnected requests,
       report the events and re-initialize our SCSI controller. It is
       important that during this initialization the controller won't
       issue another reset or else two controllers on the same SCSI bus
       could ping-pong resets forever.  The case of fatal controller
       error/hang could be handled in the same place, but it will
       probably need also sending RESET signal to the SCSI bus to reset
       the status of the connections with the SCSI devices.</para>
 
 <programlisting>    int fatal=0;
     struct ccb_trans_settings neg;
     struct cam_path *path;
 
     if( detected_scsi_reset(softc)
     || (fatal = detected_fatal_controller_error(softc)) ) {
         int targ, lun;
         struct xxx_hcb *h, *hh;
 
         /* drop all enqueued CCBs */
         for(h = softc->first_queued_hcb; h != NULL; h = hh) {
             hh = h->next;
             free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
         }
 
         /* the clean values of negotiations to report */
         neg.bus_width = 8;
         neg.sync_period = neg.sync_offset = 0;
         neg.valid = (CCB_TRANS_BUS_WIDTH_VALID
             | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID);
 
         /* drop all disconnected CCBs and clean negotiations  */
         for(targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) {
             clean_negotiations(softc, targ);
 
             /* report the event if possible */
             if(xpt_create_path(&amp;path, /*periph*/NULL,
                     cam_sim_path(sim), targ,
                     CAM_LUN_WILDCARD) == CAM_REQ_CMP) {
                 xpt_async(AC_TRANSFER_NEG, path, &amp;neg);
                 xpt_free_path(path);
             }
 
             for(lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) 
                 for(h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) {
                     hh=h->next;
                     if(fatal)
                         free_hcb_and_ccb_done(h, h->ccb, CAM_UNREC_HBA_ERROR);
                     else
                         free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
                 }
         }
 
         /* report the event */
         xpt_async(AC_BUS_RESET, softc->wpath, NULL);
 
         /* re-initialization may take a lot of time, in such case
          * its completion should be signaled by another interrupt or
          * checked on timeout - but for simplicity we assume here that
          * it's really fast
          */
         if(!fatal) {
             reinitialize_controller_without_scsi_reset(softc); 
         } else {
             reinitialize_controller_with_scsi_reset(softc); 
         }
         schedule_next_hcb(softc);
         return;
     }</programlisting>
 
     <para>If interrupt is not caused by a controller-wide condition
       then probably something has happened to the current hardware
       control block. Depending on the hardware there may be other
       non-HCB-related events, we just do not consider them here.  Then
       we analyze what happened to this HCB:</para>
 
 <programlisting>    struct xxx_hcb *hcb, *h, *hh;
     int hcb_status, scsi_status;
     int ccb_status;
     int targ;
     int lun_to_freeze;
 
     hcb = get_current_hcb(softc);
     if(hcb == NULL) {
         /* either stray interrupt or something went very wrong
          * or this is something hardware-dependent
          */
         handle as necessary;
         return;
     }
 
     targ = hcb->target;
     hcb_status = get_status_of_current_hcb(softc);</programlisting>
 
     <para>First we check if the HCB has completed and if so we check
       the returned SCSI status.</para>
 
 <programlisting>    if(hcb_status == COMPLETED) {
         scsi_status = get_completion_status(hcb);</programlisting>
 
     <para>Then look if this status is related to the REQUEST SENSE
       command and if so handle it in a simple way.</para>
 
 <programlisting>        if(hcb->flags &amp; DOING_AUTOSENSE) {
             if(scsi_status == GOOD) { /* autosense was successful */
                 hcb->ccb->ccb_h.status |= CAM_AUTOSNS_VALID;
                 free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR);
             } else {
         autosense_failed:
                 free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_AUTOSENSE_FAIL);
             }
             schedule_next_hcb(softc);
             return;
         }</programlisting>
 
     <para>Else the command itself has completed, pay more attention to
       details.  If auto-sense is not disabled for this CCB and the
       command has failed with sense data then run REQUEST SENSE
       command to receive that data.</para>
 
 <programlisting>        hcb->ccb->csio.scsi_status = scsi_status;
         calculate_residue(hcb);
 
         if( (hcb->ccb->ccb_h.flags &amp; CAM_DIS_AUTOSENSE)==0
         &amp;&amp; ( scsi_status == CHECK_CONDITION 
                 || scsi_status == COMMAND_TERMINATED) ) {
             /* start auto-SENSE */
             hcb->flags |= DOING_AUTOSENSE;
             setup_autosense_command_in_hcb(hcb);
             restart_current_hcb(softc);
             return;
         }
         if(scsi_status == GOOD)
             free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_REQ_CMP);
         else
             free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR);
         schedule_next_hcb(softc);
         return;
     }</programlisting>
 
     <para>One typical thing would be negotiation events: negotiation
       messages received from a SCSI target (in answer to our
       negotiation attempt or by target's initiative) or the target is
       unable to negotiate (rejects our negotiation messages or does
       not answer them).</para>
 
 <programlisting>    switch(hcb_status) {
     case TARGET_REJECTED_WIDE_NEG:
         /* revert to 8-bit bus */
         softc->current_bus_width[targ] = softc->goal_bus_width[targ] = 8;
         /* report the event */
         neg.bus_width = 8; 
         neg.valid = CCB_TRANS_BUS_WIDTH_VALID;
         xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &amp;neg);
         continue_current_hcb(softc);
         return;
     case TARGET_ANSWERED_WIDE_NEG:
         {
             int wd;
 
             wd = get_target_bus_width_request(softc);
             if(wd <= softc->goal_bus_width[targ]) { 
                 /* answer is acceptable */
                 softc->current_bus_width[targ] = 
                 softc->goal_bus_width[targ] = neg.bus_width = wd;
 
                 /* report the event */
                 neg.valid = CCB_TRANS_BUS_WIDTH_VALID;
                 xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &amp;neg);
             } else {
                 prepare_reject_message(hcb);
             }
         }
         continue_current_hcb(softc);
         return;
     case TARGET_REQUESTED_WIDE_NEG:
         {
             int wd;
 
             wd = get_target_bus_width_request(softc);
             wd = min (wd, OUR_BUS_WIDTH);
             wd = min (wd, softc->user_bus_width[targ]);
 
             if(wd != softc->current_bus_width[targ]) {
                 /* the bus width has changed */
                 softc->current_bus_width[targ] = 
                 softc->goal_bus_width[targ] = neg.bus_width = wd;
 
                 /* report the event */
                 neg.valid = CCB_TRANS_BUS_WIDTH_VALID;
                 xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &amp;neg);
             }
             prepare_width_nego_rsponse(hcb, wd);
         }
         continue_current_hcb(softc);
         return;
     }</programlisting>
 
     <para>Then we handle any errors that could have happened during
       auto-sense in the same simple-minded way as before. Otherwise we
       look closer at the details again.</para>
 
 <programlisting>    if(hcb->flags &amp; DOING_AUTOSENSE)
         goto autosense_failed;
 
     switch(hcb_status) {</programlisting>
 
     <para>The next event we consider is unexpected disconnect. Which
       is considered normal after an ABORT or BUS DEVICE RESET message
       and abnormal in other cases.</para>
 
 <programlisting>    case UNEXPECTED_DISCONNECT:
         if(requested_abort(hcb)) {
             /* abort affects all commands on that target+LUN, so 
              * mark all disconnected HCBs on that target+LUN as aborted too
              */
             for(h = softc->first_discon_hcb[hcb->target][hcb->lun]; 
                     h != NULL; h = hh) {
                 hh=h->next;
                 free_hcb_and_ccb_done(h, h->ccb, CAM_REQ_ABORTED);
             }
             ccb_status = CAM_REQ_ABORTED;
         } else if(requested_bus_device_reset(hcb)) {
             int lun;
 
             /* reset affects all commands on that target, so 
              * mark all disconnected HCBs on that target+LUN as reset
              */
 
             for(lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) 
                 for(h = softc->first_discon_hcb[hcb->target][lun]; 
                         h != NULL; h = hh) {
                     hh=h->next;
                     free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
                 }
 
             /* send event */
             xpt_async(AC_SENT_BDR, hcb->ccb->ccb_h.path_id, NULL);
 
             /* this was the CAM_RESET_DEV request itself, it's completed */
             ccb_status = CAM_REQ_CMP; 
         } else {
             calculate_residue(hcb);
             ccb_status = CAM_UNEXP_BUSFREE; 
             /* request the further code to freeze the queue */
             hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;
             lun_to_freeze = hcb->lun;
         }
         break;</programlisting>
 
     <para>If the target refuses to accept tags we notify CAM about
       that and return back all commands for this LUN:</para>
 
 <programlisting>    case TAGS_REJECTED:
         /* report the event */
         neg.flags = 0 &amp; ~CCB_TRANS_TAG_ENB; 
         neg.valid = CCB_TRANS_TQ_VALID;
         xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &amp;neg);
 
         ccb_status = CAM_MSG_REJECT_REC; 
         /* request the further code to freeze the queue */
         hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;
         lun_to_freeze = hcb->lun;
         break;</programlisting>
 
     <para>Then we check a number of other conditions, with processing
       basically limited to setting the CCB status:</para>
 
 <programlisting>    case SELECTION_TIMEOUT:
         ccb_status = CAM_SEL_TIMEOUT; 
         /* request the further code to freeze the queue */
         hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;
         lun_to_freeze = CAM_LUN_WILDCARD;
         break;
     case PARITY_ERROR:
         ccb_status = CAM_UNCOR_PARITY; 
         break;
     case DATA_OVERRUN:
     case ODD_WIDE_TRANSFER:
         ccb_status = CAM_DATA_RUN_ERR; 
         break;
     default:
         /* all other errors are handled in a generic way */
         ccb_status = CAM_REQ_CMP_ERR; 
         /* request the further code to freeze the queue */
         hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;
         lun_to_freeze = CAM_LUN_WILDCARD;
         break;
     }</programlisting>
 
     <para>Then we check if the error was serious enough to freeze the
       input queue until it gets proceeded and do so if it is:</para>
 
 <programlisting>    if(hcb->ccb->ccb_h.status &amp; CAM_DEV_QFRZN) {
         /* freeze the queue */
         xpt_freeze_devq(ccb->ccb_h.path, /*count*/1);
 
         /* re-queue all commands for this target/LUN back to CAM */
 
         for(h = softc->first_queued_hcb; h != NULL; h = hh) {
             hh = h->next;
 
             if(targ == h->targ 
             &amp;&amp; (lun_to_freeze == CAM_LUN_WILDCARD || lun_to_freeze == h->lun) )
                 free_hcb_and_ccb_done(h, h->ccb, CAM_REQUEUE_REQ);
         }
     }
     free_hcb_and_ccb_done(hcb, hcb->ccb, ccb_status);
     schedule_next_hcb(softc);
     return;</programlisting>
 
     <para>This concludes the generic interrupt handling although
       specific controllers may require some additions.</para>
 
   </sect1>
 
   <sect1>
     <title>Errors Summary</title>
 
     <para>When executing an I/O request many things may go wrong. The
       reason of error can be reported in the CCB status with great
       detail. Examples of use are spread throughout this document. For
       completeness here is the summary of recommended responses for
       the typical error conditions:</para>
 
     <itemizedlist>
 
       <listitem><para><emphasis>CAM_RESRC_UNAVAIL</emphasis> - some
-        resource is temporarily unavailable and the SIM driver can not
+        resource is temporarily unavailable and the SIM driver cannot
         generate an event when it will become available. An example of
         this resource would be some intra-controller hardware resource
         for which the controller does not generate an interrupt when
         it becomes available.</para></listitem>
  
       <listitem><para><emphasis>CAM_UNCOR_PARITY</emphasis> -
         unrecovered parity error occurred</para></listitem>
 
       <listitem><para><emphasis>CAM_DATA_RUN_ERR</emphasis> - data
         overrun or unexpected data phase (going in other direction
         than specified in CAM_DIR_MASK) or odd transfer length for
         wide transfer</para></listitem>
 
       <listitem><para><emphasis>CAM_SEL_TIMEOUT</emphasis> - selection
         timeout occurred (target does not respond)</para></listitem>
 
       <listitem><para><emphasis>CAM_CMD_TIMEOUT</emphasis> - command
         timeout occurred (the timeout function ran)</para></listitem>
 
       <listitem><para><emphasis>CAM_SCSI_STATUS_ERROR</emphasis> - the
         device returned error</para></listitem>
 
       <listitem><para><emphasis>CAM_AUTOSENSE_FAIL</emphasis> - the
         device returned error and the REQUEST SENSE COMMAND
         failed</para></listitem>
 
       <listitem><para><emphasis>CAM_MSG_REJECT_REC</emphasis> - MESSAGE
         REJECT message was received</para></listitem>
 
       <listitem><para><emphasis>CAM_SCSI_BUS_RESET</emphasis> - received
         SCSI bus reset</para></listitem>
 
       <listitem><para><emphasis>CAM_REQ_CMP_ERR</emphasis> -
         "impossible" SCSI phase occurred or something else as weird or
         just a generic error if further detail is not
         available</para></listitem>
 
       <listitem><para><emphasis>CAM_UNEXP_BUSFREE</emphasis> -
         unexpected disconnect occurred</para></listitem>
 
       <listitem><para><emphasis>CAM_BDR_SENT</emphasis> - BUS DEVICE
         RESET message was sent to the target</para></listitem>
 
       <listitem><para><emphasis>CAM_UNREC_HBA_ERROR</emphasis> -
         unrecoverable Host Bus Adapter Error</para></listitem>
 
       <listitem><para><emphasis>CAM_REQ_TOO_BIG</emphasis> - the request
         was too large for this controller</para></listitem>
 
       <listitem><para><emphasis>CAM_REQUEUE_REQ</emphasis> - this
         request should be re-queued to preserve transaction ordering.
         This typically occurs when the SIM recognizes an error that
         should freeze the queue and must place other queued requests
         for the target at the sim level back into the XPT
         queue. Typical cases of such errors are selection timeouts,
         command timeouts and other like conditions. In such cases the
         troublesome command returns the status indicating the error,
         the and the other commands which have not be sent to the bus
         yet get re-queued.</para></listitem>
 
       <listitem><para><emphasis>CAM_LUN_INVALID</emphasis> - the LUN
         ID in the request is not supported by the SCSI
         controller</para></listitem>
 
       <listitem><para><emphasis>CAM_TID_INVALID</emphasis> - the
         target ID in the request is not supported by the SCSI
         controller</para></listitem>
     </itemizedlist>
   </sect1>
 
   <sect1>
     <title>Timeout Handling</title>
 
     <para>When the timeout for an HCB expires that request should be
       aborted, just like with an XPT_ABORT request. The only
       difference is that the returned status of aborted request should
       be CAM_CMD_TIMEOUT instead of CAM_REQ_ABORTED (that's why
       implementation of the abort better be done as a function). But
       there is one more possible problem: what if the abort request
       itself will get stuck? In this case the SCSI bus should be
       reset, just like with an XPT_RESET_BUS request (and the idea
       about implementing it as a function called from both places
       applies here too). Also we should reset the whole SCSI bus if a
       device reset request got stuck. So after all the timeout
       function would look like:</para>
 
 <programlisting>static void
 xxx_timeout(void *arg)
 {
     struct xxx_hcb *hcb = (struct xxx_hcb *)arg;
     struct xxx_softc *softc;
     struct ccb_hdr *ccb_h;
 
     softc = hcb->softc;
     ccb_h = &amp;hcb->ccb->ccb_h;
 
     if(hcb->flags &amp; HCB_BEING_ABORTED
     || ccb_h->func_code == XPT_RESET_DEV) {
         xxx_reset_bus(softc);
     } else {
         xxx_abort_ccb(hcb->ccb, CAM_CMD_TIMEOUT);
     }
 }</programlisting>
 
     <para>When we abort a request all the other disconnected requests
       to the same target/LUN get aborted too. So there appears a
       question, should we return them with status CAM_REQ_ABORTED or
       CAM_CMD_TIMEOUT ?  The current drivers use CAM_CMD_TIMEOUT. This
       seems logical because if one request got timed out then probably
       something really bad is happening to the device, so if they
       would not be disturbed they would time out by themselves.</para>
 
   </sect1>
 
 </chapter>
diff --git a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
index 2c1519e6b4..b7a44cc989 100644
--- a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml
@@ -1,1587 +1,1587 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml,v 1.1 2001/05/14 02:52:43 murray Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml,v 1.2 2001/07/06 13:02:53 dd Exp $
 -->
 
 <chapter id="ipv6">
   <title>IPv6 Internals</title>
 
   <sect1 id="ipv6-implementation">
     <title>IPv6/IPsec Implementation</title>
 
     <para><emphasis>Contributed by &a.shin;, 5 March
         2000.</emphasis></para>
 
     <para>This section should explain IPv6 and IPsec related implementation
     internals.  These functionalities are derived from <ulink
     url="http://www.kame.net">KAME project</ulink></para>
 
     <sect2 id="ipv6details">
       <title>IPv6</title>
 
       <sect3>
         <title>Conformance</title>
 
         <para>The IPv6 related functions conforms, or tries to conform to
 	the latest set of IPv6 specifications.  For future reference we list
 	some of the relevant documents below (<emphasis>NOTE</emphasis>: this
 	is not a complete list - this is too hard to maintain...).</para>
 
         <para>For details please refer to specific chapter in the document,
 	RFCs, manpages, or comments in the source code.</para>
 
         <para>Conformance tests have been performed on the KAME STABLE kit
         at TAHI project.  Results can be viewed at <ulink
 	url="http://www.tahi.org/report/KAME/">http://www.tahi.org/report/KAME/
 	</ulink>.  We also attended Univ. of New Hampshire IOL tests (<ulink
 	url="http://www.iol.unh.edu/">http://www.iol.unh.edu/</ulink>) in the
 	past, with our past snapshots.</para>
 
         <itemizedlist>
           <listitem>
 	    <para>RFC1639: FTP Operation Over Big Address Records
 	    (FOOBAR)</para>
 	    <itemizedlist>
 	      <listitem>
 	        <para>RFC2428 is preferred over RFC1639.  FTP clients will
 		first try RFC2428, then RFC1639 if failed.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem> 
 
           <listitem>
 	    <para>RFC1886: DNS Extensions to support IPv6</para>
 	  </listitem>
 
           <listitem>
 	    <para>RFC1933: Transition Mechanisms for IPv6 Hosts and
 	    Routers</para>
 	    <itemizedlist>
               <listitem>
 	        <para>IPv4 compatible address is not supported.</para>
 	      </listitem>
               <listitem>
 	        <para>automatic tunneling (described in 4.3 of this RFC) is not
 		supported.</para>
 	      </listitem>
               <listitem>
 	        <para>&man.gif.4; interface implements IPv[46]-over-IPv[46]
 		tunnel in a generic way, and it covers "configured tunnel"
 		described in the spec.  See <link linkend="gif">23.5.1.5</link>
 		in this document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
             <para>RFC1981: Path MTU Discovery for IPv6</para>
           </listitem>
 
           <listitem>
             <para>RFC2080: RIPng for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
                 <para>usr.sbin/route6d support this.</para>
               </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
             <para>RFC2292: Advanced Sockets API for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>For supported library functions/kernel APIs, see
 		<filename>sys/netinet6/ADVAPI</filename>.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2362: Protocol Independent Multicast-Sparse
 	    Mode (PIM-SM)</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>RFC2362 defines packet formats for PIM-SM.
 		<filename>draft-ietf-pim-ipv6-01.txt</filename> is
 		written based on this.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2373: IPv6 Addressing Architecture</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>supports node required addresses, and conforms to
 		the scope requirement.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2374: An IPv6 Aggregatable Global Unicast Address
 	    Format</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>supports 64-bit length of Interface ID.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2375: IPv6 Multicast Address Assignments</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>Userland applications use the well-known addresses
 		assigned in the RFC.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2428: FTP Extensions for IPv6 and NATs</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>RFC2428 is preferred over RFC1639.  FTP clients will
 		first try RFC2428, then RFC1639 if failed.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2460: IPv6 specification</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2461: Neighbor discovery for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="neighbor-discovery">23.5.1.2</link>
 		in this document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2462: IPv6 Stateless Address Autoconfiguration</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="ipv6-pnp">23.5.1.4</link> in this
 		document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2463: ICMPv6 for IPv6 specification</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="icmpv6">23.5.1.9</link> in this
 		document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2464: Transmission of IPv6 Packets over Ethernet
 	    Networks</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2465: MIB for IPv6: Textual Conventions and General
 	    Group</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>Necessary statistics are gathered by the kernel.  Actual
 		IPv6 MIB support is provided as a patchkit for ucd-snmp.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2466: MIB for IPv6: ICMPv6 group</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>Necessary statistics are gathered by the kernel.  Actual
 		IPv6 MIB support is provided as patchkit for ucd-snmp.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2467: Transmission of IPv6 Packets over FDDI
 	    Networks</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2497: Transmission of IPv6 packet over ARCnet
 	    Networks</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2553: Basic Socket Interface Extensions for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>IPv4 mapped address (3.7) and special behavior of IPv6
 		wildcard bind socket (3.8) are supported.  See <link
 		linkend="ipv6-wildcard-socket">23.5.1.12</link>
 		in this document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2675: IPv6 Jumbograms</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="ipv6-jumbo">23.5.1.7</link> in
 		this document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para>RFC2710: Multicast Listener Discovery for IPv6</para>
           </listitem>
 
           <listitem>
 	    <para>RFC2711: IPv6 router alert option</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-ipngwg-router-renum-08</filename>: Router
 	    renumbering for IPv6</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-ipngwg-icmp-namelookups-02</filename>:
 	    IPv6 Name Lookups Through ICMP</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-ipngwg-icmp-name-lookups-03</filename>:
 	    IPv6 Name Lookups Through ICMP</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-pim-ipv6-01.txt</filename>:
 	    PIM for IPv6</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>&man.pim6dd.8; implements dense mode.  &man.pim6sd.8;
 		implements sparse mode.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-itojun-ipv6-tcp-to-anycast-00</filename>:
 	    Disconnecting TCP connection toward IPv6 anycast address</para>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-yamamoto-wideipv6-comm-model-00</filename>
 	    </para>
 	    <itemizedlist>
 	      <listitem>
 		<para>See <link linkend="ipv6-sas">23.5.1.6</link> in this
 		document for details.</para>
 	      </listitem>
 	    </itemizedlist>
           </listitem>
 
           <listitem>
 	    <para><filename>draft-ietf-ipngwg-scopedaddr-format-00.txt
 	    </filename>: An Extension of Format for IPv6 Scoped
 	    Addresses</para>
           </listitem>
         </itemizedlist>
       </sect3>
 
       <sect3 id="neighbor-discovery">
         <title>Neighbor Discovery</title>
 
         <para>Neighbor Discovery is fairly stable.  Currently Address
 	Resolution, Duplicated Address Detection, and Neighbor Unreachability
 	Detection are supported.  In the near future we will be adding Proxy
 	Neighbor Advertisement support in the kernel and Unsolicited Neighbor
 	Advertisement transmission command as admin tool.</para>
 
         <para>If DAD fails, the address will be marked "duplicated" and
 	message will be generated to syslog (and usually to console).  The
 	"duplicated" mark can be checked with &man.ifconfig.8;.  It is
 	administrators' responsibility to check for and recover from DAD
 	failures.  The behavior should be improved in the near future.</para>
 
         <para>Some of the network driver loops multicast packets back to itself,
         even if instructed not to do so (especially in promiscuous mode).
         In such cases DAD may fail, because DAD engine sees inbound NS packet
         (actually from the node itself) and considers it as a sign of duplicate.
         You may want to look at #if condition marked "heuristics" in
         sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
         fragment in "heuristics" section is not spec conformant).</para>
 
         <para>Neighbor Discovery specification (RFC2461) does not talk about
 	neighbor cache handling in the following cases:</para>
 
 	<orderedlist>
           <listitem>
 	    <para>when there was no neighbor cache entry, node
 	    received unsolicited RS/NS/NA/redirect packet without
 	    link-layer address</para>
           </listitem>
           <listitem>
             <para>neighbor cache handling on medium without link-layer
 	    address (we need a neighbor cache entry for IsRouter bit)</para>
           </listitem>
 	</orderedlist>
 
         <para>For first case, we implemented workaround based on discussions
 	on IETF ipngwg mailing list.  For more details, see the comments in
 	the source code and email thread started from (IPng 7155), dated
 	Feb 6 1999.</para>
 
         <para>IPv6 on-link determination rule (RFC2461) is quite different
 	from assumptions in BSD network code.  At this moment, no on-link
 	determination rule is supported where default router list is empty
 	(RFC2461, section 5.2, last sentence in 2nd paragraph - note that
 	the spec misuse the word "host" and "node" in several places in
 	the section).</para>
 
         <para>To avoid possible DoS attacks and infinite loops, only 10
 	options on ND packet is accepted now.  Therefore, if you have 20
 	prefix options attached to RA, only the first 10 prefixes will be
 	recognized.  If this troubles you, please ask it on FREEBSD-CURRENT
 	mailing list and/or modify nd6_maxndopt in
 	<filename>sys/netinet6/nd6.c</filename>.  If there are high demands
 	we may provide sysctl knob for the variable.</para>
       </sect3>
      
       <sect3 id="ipv6-scope-index">
         <title>Scope Index</title>
 
 	<para>IPv6 uses scoped addresses.  Therefore, it is very important to
 	specify scope index (interface index for link-local address, or
 	site index for site-local address) with an IPv6 address.  Without
 	scope index, scoped IPv6 address is ambiguous to the kernel, and
 	kernel will not be able to determine the outbound interface for a
 	packet.</para>
 
 	<para>Ordinary userland applications should use advanced API
 	(RFC2292) to specify scope index, or interface index.  For similar
 	purpose, sin6_scope_id member in sockaddr_in6 structure is defined
 	in RFC2553.  However, the semantics for sin6_scope_id is rather vague.
 	If you care about portability of your application, we suggest you to
 	use advanced API rather than sin6_scope_id.</para>
 
 	<para>In the kernel, an interface index for link-local scoped address is
 	embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address.  For
 	example, you may see something like:
 	</para>
 
 	<screen>	fe80:1::200:f8ff:fe01:6317
 	</screen>
 
 	<para>in the routing table and interface address structure (struct
 	in6_ifaddr).  The address above is a link-local unicast address
 	which belongs to a network interface whose interface identifier is 1.
 	The embedded index enables us to identify IPv6 link local
 	addresses over multiple interfaces effectively and with only a
 	little code change.</para>
 
 	<para>Routing daemons and configuration programs, like &man.route6d.8;
 	and &man.ifconfig.8;, will need to manipulate the "embedded" scope
 	index.  These programs use routing sockets and ioctls (like
 	SIOCGIFADDR_IN6) and the kernel API will return IPv6 addresses with
 	2nd 16bit-word filled in.  The APIs are for manipulating kernel
 	internal structure.  Programs that use these APIs have to be prepared
 	about differences in kernels anyway.</para>
 
 	<para>When you specify scoped address to the command line, NEVER write
 	the embedded form (such as ff02:1::1 or fe80:2::fedc).  This is not
 	supposed to work.  Always use standard form, like ff02::1 or
 	fe80::fedc, with command line option for specifying interface (like
 	<command>ping6 -I ne0 ff02::1</command>).  In general, if a command
 	does not have command line option to specify outgoing interface, that
 	command is not ready to accept scoped address.  This may seem to be
 	opposite from IPv6's premise to support "dentist office" situation.
 	We believe that specifications need some improvements for this.</para>
 
 	<para>Some of the userland tools support extended numeric IPv6 syntax,
 	as documented in
 	<filename>draft-ietf-ipngwg-scopedaddr-format-00.txt</filename>.  You
 	can specify outgoing link, by using name of the outgoing interface
 	like "fe80::1%ne0".  This way you will be able to specify link-local
 	scoped address without much trouble.</para>
 
 	<para>To use this extension in your program, you'll need to use
 	&man.getaddrinfo.3;, and &man.getnameinfo.3; with NI_WITHSCOPEID.
 	The implementation currently assumes 1-to-1 relationship between a
 	link and an interface, which is stronger than what specs say.</para>
       </sect3>
 
       <sect3 id="ipv6-pnp">
 	<title>Plug and Play</title>
 
 	<para>Most of the IPv6 stateless address autoconfiguration is implemented
 	in the kernel.  Neighbor Discovery functions are implemented in the
 	kernel as a whole.  Router Advertisement (RA) input for hosts is
 	implemented in the kernel.  Router Solicitation (RS) output for
 	endhosts, RS input for routers, and RA output for routers are
 	implemented in the userland.</para>
 
         <sect4>
 	  <title>Assignment of link-local, and special addresses</title>
 
  	  <para>IPv6 link-local address is generated from IEEE802 address
 	  (ethernet MAC address).  Each of interface is assigned an IPv6
 	  link-local address automatically, when the interface becomes up
 	  (IFF_UP).  Also, direct route for the link-local address is added
 	  to routing table.</para>
 
 	  <para>Here is an output of netstat command:</para>
 
 <screen>Internet6:
 Destination                   Gateway                   Flags      Netif Expire
 fe80:1::%ed0/64               link#1                    UC          ed0
 fe80:2::%ep0/64               link#2                    UC          ep0</screen>
 
 	  <para>Interfaces that has no IEEE802 address (pseudo interfaces
 	  like tunnel interfaces, or ppp interfaces) will borrow IEEE802
 	  address from other interfaces, such as ethernet interfaces,
 	  whenever possible.  If there is no IEEE802 hardware attached,
 	  last-resort pseudorandom value, which is from MD5(hostname), will
 	  be used as source of link-local address.  If it is not suitable
 	  for your usage, you will need to configure the link-local address
 	  manually.</para>
 
 	  <para>If an interface is not capable of handling IPv6 (such as
 	  lack of multicast support), link-local address will not be
 	  assigned to that interface.  See section 2 for details.</para>
 
 	  <para>Each interface joins the solicited multicast address and the
 	  link-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317
 	  and ff02::1, respectively, on the link the interface is attached).
 	  In addition to a link-local address, the loopback address (::1)
 	  will be assigned to the loopback interface.  Also, ::1/128 and
 	  ff01::/32 are automatically added to routing table, and loopback
 	  interface joins node-local multicast group ff01::1.</para>
         </sect4>
 
         <sect4>
 	  <title>Stateless address autoconfiguration on hosts</title>
 
 	  <para>In IPv6 specification, nodes are separated into two categories:
 	  <emphasis>routers</emphasis> and <emphasis>hosts</emphasis>.  Routers
 	  forward packets addressed to others, hosts does not forward the
 	  packets.  net.inet6.ip6.forwarding defines whether this node is
 	  router or host (router if it is 1, host if it is 0).</para>
 
 	  <para>When a host hears Router Advertisement from the router, a host
 	  may autoconfigure itself by stateless address autoconfiguration.
 	  This behavior can be controlled by net.inet6.ip6.accept_rtadv (host
 	  autoconfigures itself if it is set to 1).  By autoconfiguration,
 	  network address prefix for the receiving interface (usually global
 	  address prefix) is added.  Default route is also configured.
 	  Routers periodically generate Router Advertisement packets.  To
 	  request an adjacent router to generate RA packet, a host can
 	  transmit Router Solicitation.  To generate a RS packet at any time,
 	  use the <emphasis>rtsol</emphasis> command.  &man.rtsold.8; daemon is
 	  also available.  &man.rtsold.8; generates Router Solicitation whenever
 	  necessary, and it works great for nomadic usage (notebooks/laptops).
 	  If one wishes to ignore Router Advertisements, use sysctl to set
 	  net.inet6.ip6.accept_rtadv to 0.</para>
 
 	  <para>To generate Router Advertisement from a router, use the
 	  &man.rtadvd.8 daemon.</para>
 
 	  <para>Note that, IPv6 specification assumes the following items, and
 	  nonconforming cases are left unspecified:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>Only hosts will listen to router advertisements</para>
 	    </listitem>
 	    <listitem>
 	      <para>Hosts have single network interface (except loopback)</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv
 	  on routers, or multi-interface host.  A misconfigured node can
 	  behave strange (nonconforming configuration allowed for those who
 	  would like to do some experiments).</para>
 
 	  <para>To summarize the sysctl knob:</para>
 
         <screen>	accept_rtadv	forwarding	role of the node
 	---		---		---
 	0		0		host (to be manually configured)
 	0		1		router
 	1		0		autoconfigured host
 					(spec assumes that host has single
 					interface only, autoconfigured host
 					with multiple interface is
 					out-of-scope)
 	1		1		invalid, or experimental
 					(out-of-scope of spec)</screen>
 
 	  <para>RFC2462 has validation rule against incoming RA prefix
 	  information option, in 5.5.3 (e).  This is to protect hosts from
 	  malicious (or misconfigured) routers that advertise very short
 	  prefix lifetime.  There was an update from Jim Bound to ipngwg
 	  mailing list (look for "(ipng 6712)" in the archive) and it is
 	  implemented Jim's update.</para>
 
 	  <para>See <link linkend="neighbor-discovery">23.5.1.2</link> in
 	  the document for relationship between DAD and
 	  autoconfiguration.</para>
         </sect4>
       </sect3>
 
       <sect3 id="gif">
 	<title>Generic tunnel interface</title>
 
 	<para>GIF (Generic InterFace) is a pseudo interface for configured
 	tunnel.  Details are described in &man.gif.4;.  Currently</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>v6 in v6</para>
 	  </listitem>
 	  <listitem>
 	    <para>v6 in v4</para>
 	  </listitem>
 	  <listitem>
 	    <para>v4 in v6</para>
 	  </listitem>
 	  <listitem>
 	    <para>v4 in v4</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>are available.  Use &man.gifconfig.8; to assign physical (outer)
 	source and destination address to gif interfaces.  Configuration that
 	uses same address family for inner and outer IP header (v4 in v4, or
 	v6 in v6) is dangerous.  It is very easy to configure interfaces and
 	routing tables to perform infinite level of tunneling.
 	<emphasis>Please be warned</emphasis>.</para>
 
 	<para>gif can be configured to be ECN-friendly.  See <link
 	linkend="ipsec-ecn">23.5.4.5</link> for ECN-friendliness of
 	tunnels, and &man.gif.4; for how to configure.</para>
 
 	<para>If you would like to configure an IPv4-in-IPv6 tunnel with gif
 	interface, read &man.gif.4; carefully.  You will need to
 	remove IPv6 link-local address automatically assigned to the gif
 	interface.</para>
       </sect3>
 
       <sect3 id="ipv6-sas">
 	<title>Source Address Selection</title>
 
 	<para>Current source selection rule is scope oriented (there are some
 	exceptions - see below).  For a given destination, a source IPv6
 	address is selected by the following rule:</para>
 
 	<orderedlist>
 	  <listitem>
   	    <para>If the source address is explicitly specified by
 	    the user (e.g.  via the advanced API), the specified address
 	    is used.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If there is an address assigned to the outgoing
 	    interface (which is usually determined by looking up the
 	    routing table) that has the same scope as the destination
 	    address, the address is used.</para>
 
 	    <para>This is the most typical case.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If there is no address that satisfies the above
 	    condition, choose a global address assigned to one of
 	    the interfaces on the sending node.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If there is no address that satisfies the above condition,
 	    and destination address is site local scope, choose a site local
 	    address assigned to one of the interfaces on the sending node.
 	    </para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If there is no address that satisfies the above condition,
 	    choose the address associated with the routing table entry for the
 	    destination.  This is the last resort, which may cause scope
 	    violation.</para>
 	  </listitem>
 	</orderedlist>
 
 	<para>For instance, ::1 is selected for ff01::1,
 	fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b (note
 	that embedded interface index - described in <link
 	linkend="ipv6-scope-index">23.5.1.3</link> - helps us
 	choose the right source address.  Those embedded indices will not
 	be on the wire).  If the outgoing interface has multiple address for
 	the scope, a source is selected longest match basis (rule 3).  Suppose
 	3ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
 	are given to the outgoing interface.  3ffe:501:808:1:200:f8ff:fe01:6317
 	is chosen as the source for the destination 3ffe:501:800::1.</para>
 
 	<para>Note that the above rule is not documented in the IPv6 spec.
 	It is considered "up to implementation" item.  There are some cases
 	where we do not use the above rule.  One example is connected TCP
 	session, and we use the address kept in tcb as the source.  Another
 	example is source address for Neighbor Advertisement.  Under the spec
 	(RFC2461 7.2.2) NA's source should be the target address of the
 	corresponding NS's target.  In this case we follow the spec rather
 	than the above longest-match rule.</para>
 
 	<para>For new connections (when rule 1 does not apply), deprecated
 	addresses (addresses with preferred lifetime = 0) will not be chosen
 	as source address if other choices are available.  If no other choices
 	are available, deprecated address will be used as a last resort.  If
 	there are multiple choice of deprecated addresses, the above scope
 	rule will be used to choose from those deprecated addresses.  If you
 	would like to prohibit the use of deprecated address for some reason,
 	configure net.inet6.ip6.use_deprecated to 0.  The issue related to
 	deprecated address is described in RFC2462 5.5.4 (NOTE: there is
 	some debate underway in IETF ipngwg on how to use "deprecated"
 	address).</para>
       </sect3>
 
       <sect3 id="ipv6-jumbo">
 	<title>Jumbo Payload</title>
 
 	<para>The Jumbo Payload hop-by-hop option is implemented and can
 	be used to send IPv6 packets with payloads longer than 65,535 octets.
 	But currently no physical interface whose MTU is more than 65,535 is
 	supported, so such payloads can be seen only on the loopback
 	interface (i.e. lo0).</para>
 
 	<para>If you want to try jumbo payloads, you first have to reconfigure
 	the kernel so that the MTU of the loopback interface is more than
 	65,535 bytes; add the following to the kernel configuration file:</para>
 
 	<para><literal>
 	  options		"LARGE_LOMTU"		#To test jumbo payload
 	</literal></para>
 
 	<para>and recompile the new kernel.</para>
 
 	<para>Then you can test jumbo payloads by the &man.ping6.8; command
 	with -b and -s options.  The -b option must be specified to enlarge
 	the size of the socket buffer and the -s option specifies the length
 	of the packet, which should be more than 65,535.  For example,
 	type as follows:</para>
 
 	<para><userinput>
 	  &prompt.user; <command>ping6 -b 70000 -s 68000 ::1</command>
 	</userinput></para>
 
 	<para>The IPv6 specification requires that the Jumbo Payload option
 	must not be used in a packet that carries a fragment header.  If
 	this condition is broken, an ICMPv6 Parameter Problem message must
 	be sent to the sender.  specification is followed, but you cannot
 	usually see an ICMPv6 error caused by this requirement.</para>
 
 	<para>When an IPv6 packet is received, the frame length is checked and
 	compared to the length specified in the payload length field of the
 	IPv6 header or in the value of the Jumbo Payload option, if any.  If
 	the former is shorter than the latter, the packet is discarded and
 	statistics are incremented. You can see the statistics as output of
 	&man.netstat.8; command with `-s -p ip6' option:</para>
 
 	<screen>	  &prompt.user; <command>netstat -s -p ip6</command>
 	  ip6:
 		(snip)
 		1 with data size < data length</screen>
 
 	<para>So, kernel does not send an ICMPv6 error unless the erroneous
 	packet is an actual Jumbo Payload, that is, its packet size is more
 	than 65,535 bytes.  As described above, currently no physical interface
 	with such a huge MTU is supported, so it rarely returns an
 	ICMPv6 error.</para>
 
 	<para>TCP/UDP over jumbogram is not supported at this moment.  This
 	is because we have no medium (other than loopback) to test this.
 	Contact us if you need this.</para>
 
 	<para>IPsec does not work on jumbograms.  This is due to some
 	specification twists in supporting AH with jumbograms (AH header
 	size influences payload length, and this makes it real hard to
 	authenticate inbound packet with jumbo payload option as well as AH).
 	</para>
 
 	<para>There are fundamental issues in *BSD support for jumbograms.
 	We would like to address those, but we need more time to finalize
 	these.  To name a few:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>mbuf pkthdr.len field is typed as "int" in 4.4BSD, so
 	    it will not hold jumbogram with len &gt; 2G on 32bit architecture
 	    CPUs.  If we would like to support jumbogram properly, the field
 	    must be expanded to hold 4G + IPv6 header + link-layer header.
 	    Therefore, it must be expanded to at least int64_t
 	    (u_int32_t is NOT enough).</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>We mistakingly use "int" to hold packet length in many
 	    places.  We need to convert them into larger integral type.
 	    It needs a great care, as we may experience overflow during
 	    packet length computation.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>We mistakingly check for ip6_plen field of IPv6 header
 	    for packet payload length in various places.  We should be
 	    checking mbuf pkthdr.len instead.  ip6_input() will perform
 	    sanity check on jumbo payload option on input, and we can
 	    safely use mbuf pkthdr.len afterwards.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>TCP code needs a careful update in bunch of places, of
 	    course.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Loop prevention in header processing</title>
 
 	<para>IPv6 specification allows arbitrary number of extension headers
 	to be placed onto packets.  If we implement IPv6 packet processing
 	code in the way BSD IPv4 code is implemented, kernel stack may
 	overflow due to long function call chain.  sys/netinet6 code
 	is carefully designed to avoid kernel stack overflow.  Because of
 	this, sys/netinet6 code defines its own protocol switch
 	structure, as "struct ip6protosw" (see
 	<filename>netinet6/ip6protosw.h</filename>).  There is no such
 	update to IPv4 part (sys/netinet) for compatibility, but small
 	change is added to its pr_input() prototype. So "struct ipprotosw"
 	is also defined.  Because of this, if you receive IPsec-over-IPv4
 	packet with massive number of IPsec headers, kernel stack may blow
 	up.  IPsec-over-IPv6 is okay.  (Off-course, for those all IPsec
 	headers to be processed, each such IPsec header must pass each
 	IPsec check. So an anonymous attacker won't be able to do such an
 	attack.)</para>
       </sect3>
 
       <sect3 id="icmpv6">
 	<title>ICMPv6</title>
 
 	<para>After RFC2463 was published, IETF ipngwg has decided to
 	disallow ICMPv6 error packet against ICMPv6 redirect, to prevent
 	ICMPv6 storm on a network medium.  This is already implemented
 	into the kernel.</para>
       </sect3>
 
       <sect3>
 	<title>Applications</title>
 
 	<para>For userland programming, we support IPv6 socket API as
-	specified in RFC2553, RFC2292 and upcoming internet drafts.</para>
+	specified in RFC2553, RFC2292 and upcoming Internet drafts.</para>
 
 	<para>TCP/UDP over IPv6 is available and quite stable.  You can
 	enjoy &man.telnet.1;, &man.ftp.1;, &man.rlogin.1;, &man.rsh.1;,
 	&man.ssh.1, etc.  These applications are protocol independent.
 	That is, they automatically chooses IPv4 or IPv6 according to DNS.
 	</para>
       </sect3>
 
       <sect3>
 	<title>Kernel Internals</title>
 
 	<para>While ip_forward() calls ip_output(), ip6_forward() directly
 	calls if_output() since routers must not divide IPv6 packets into
 	fragments.</para>
 
 	<para>ICMPv6 should contain the original packet as long as possible
 	up to 1280.  UDP6/IP6 port unreach, for instance, should contain
 	all extension headers and the *unchanged* UDP6 and IP6 headers.
 	So, all IP6 functions except TCP never convert network byte
 	order into host byte order, to save the original packet.</para>
 
 	<para>tcp_input(), udp6_input() and icmp6_input() can't assume that
 	IP6 header is preceding the transport headers due to extension
 	headers.  So, in6_cksum() was implemented to handle packets whose IP6
 	header and transport header is not continuous.  TCP/IP6 nor UDP6/IP6
 	header structure don't exist for checksum calculation.</para>
 
 	<para>To process IP6 header, extension headers and transport headers
 	easily, network drivers are now required to store packets in one
 	internal mbuf or one or more external mbufs.  A typical old driver
 	prepares two internal mbufs for 96 - 204 bytes data, however, now
 	such packet data is stored in one external mbuf.</para>
 
 	<para><command>netstat -s -p ip6</command> tells you whether or not
 	your driver conforms such requirement.  In the following example,
 	"cce0" violates the requirement. (For more information, refer to
 	Section 2.)</para>
 
 	<screen>Mbuf statistics:
                 317 one mbuf
                 two or more mbuf::
                         lo0 = 8
 			cce0 = 10
                 3282 one ext mbuf
                 0 two or more ext mbuf
 	</screen>
 
 	<para>Each input function calls IP6_EXTHDR_CHECK in the beginning to
 	check if the region between IP6 and its header is continuous.
 	IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has M_LOOP flag,
 	that is, the packet comes from the loopback interface.  m_pullup()
 	is never called for packets coming from physical network interfaces.
 	</para>
 
 	<para>Both IP and IP6 reassemble functions never call m_pullup().</para>
       </sect3>
 
       <sect3 id="ipv6-wildcard-socket">
 	<title>IPv4 mapped address and IPv6 wildcard socket</title>
 
 	<para>RFC2553 describes IPv4 mapped address (3.7) and special behavior
 	of IPv6 wildcard bind socket (3.8).  The spec allows you to:</para>
 	<itemizedlist>
 	  <listitem>
 	    <para>Accept IPv4 connections by AF_INET6 wildcard bind
 	    socket.</para>
 	  </listitem>
 	  <listitem>
 	    <para>Transmit IPv4 packet over AF_INET6 socket by using
 	    special form of the address like ::ffff:10.1.1.1.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>but the spec itself is very complicated and does not specify
 	how the socket layer should behave.  Here we call the former one
 	"listening side" and the latter one "initiating side", for
 	reference purposes.</para>
 
 	<para>You can perform wildcard bind on both of the address families,
 	on the same port.</para>
 
 	<para>The following table show the behavior of FreeBSD 4.x.</para>
 
 	<screen>listening side          initiating side
                 (AF_INET6 wildcard      (connection to ::ffff:10.1.1.1)
                 socket gets IPv4 conn.)
                 ---                     ---
 FreeBSD 4.x     configurable            supported
                 default: enabled
 	</screen>
 
 	<para>The following sections will give you more details, and how you can
 	configure the behavior.</para>
 
 	<para>Comments on listening side:</para>
 
 	<para>It looks that RFC2553 talks too little on wildcard bind issue,
 	especially on the port space issue, failure mode and relationship
 	between AF_INET/INET6 wildcard bind.  There can be several separate
 	interpretation for this RFC which conform to it but behaves differently.
 	So, to implement portable application you should assume nothing
 	about the behavior in the kernel.  Using &man.getaddrinfo.3; is the
 	safest way.  Port number space and wildcard bind issues were discussed
 	in detail on ipv6imp mailing list, in mid March 1999 and it looks
 	that there's no concrete consensus (means, up to implementers).
 	You may want to check the mailing list archives.</para>
 
 	<para>If a server application would like to accept IPv4 and IPv6
 	connections, there will be two alternatives.</para>
 
 	<para>One is using AF_INET and AF_INET6 socket (you'll need two
 	sockets).  Use &man.getaddrinfo.3; with AI_PASSIVE into ai_flags,
 	and &man.socket.2; and &man.bind.2; to all the addresses returned.
 	By opening multiple sockets, you can accept connections onto the
 	socket with proper address family.  IPv4 connections will be
 	accepted by AF_INET socket, and IPv6 connections will be accepted
 	by AF_INET6 socket.</para>
 
 	<para>Another way is using one AF_INET6 wildcard bind socket.  Use
 	&man.getaddrinfo.3; with AI_PASSIVE into ai_flags and with
 	AF_INET6 into ai_family, and set the 1st argument hostname to
 	NULL. And &man.socket.2; and &man.bind.2; to the address returned.
 	(should be IPv6 unspecified addr).  You can accept either of IPv4
 	and IPv6 packet via this one socket.</para>
 
 	<para>To support only IPv6 traffic on AF_INET6 wildcard binded socket
 	portably, always check the peer address when a connection is made
 	toward AF_INET6 listening socket.  If the address is IPv4 mapped
 	address, you may want to reject the connection.  You can check the
 	condition by using IN6_IS_ADDR_V4MAPPED() macro.</para>
 
 	<para>To resolve this issue more easily, there is system dependent
 	&man.setsockopt.2; option, IPV6_BINDV6ONLY, used like below.</para>
 
 	<screen>	int on;
 
 	setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
 		   (char *)&amp;on, sizeof (on)) < 0));
 	</screen>
 
 	<para>When this call succeed, then this socket only receive IPv6
 	packets.</para>
 
 	<para>Comments on initiating side:</para>
 
 	<para>Advise to application implementers: to implement a portable
 	IPv6 application (which works on multiple IPv6 kernels), we believe
 	that the following is the key to the success:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>NEVER hardcode AF_INET nor AF_INET6.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use &man.getaddrinfo.3; and &man.getnameinfo.3;
 	    throughout the system.  Never use gethostby*(), getaddrby*(),
 	    inet_*() or getipnodeby*(). (To update existing applications
 	    to be IPv6 aware easily, sometime getipnodeby*() will be
 	    useful. But if possible, try to rewrite the code to use
 	    &man.getaddrinfo.3; and &man.getnameinfo.3;.)</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you would like to connect to destination, use
 	    &man.getaddrinfo.3; and try all the destination returned,
 	    like &man.telnet.1; does.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Some of the IPv6 stack is shipped with buggy
 	    &man.getaddrinfo.3;.  Ship a minimal working version with
 	    your application and use that as last resort.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>If you would like to use AF_INET6 socket for both IPv4 and
 	IPv6 outgoing connection, you will need to use &man.getipnodebyname.3;.
 	When you would like to update your existing application to be IPv6
 	aware with minimal effort, this approach might be chosen. But please
 	note that it is a temporal solution, because &man.getipnodebyname.3;
 	itself is not recommended as it does not handle scoped IPv6 addresses
 	at all.  For IPv6 name resolution, &man.getaddrinfo.3; is the
 	preferred API. So you should rewrite your application to use
 	&man.getaddrinfo.3;, when you get the time to do it.</para>
 
 	<para>When writing applications that make outgoing connections,
 	story goes much simpler if you treat AF_INET and AF_INET6 as totally
 	separate address family.  {set,get}sockopt issue goes simpler,
 	DNS issue will be made simpler.  We do not recommend you to rely
 	upon IPv4 mapped address.</para>
 
 	<sect4>
 	  <title>unified tcp and inpcb code</title>
 
 	  <para>FreeBSD 4.x uses shared tcp code between IPv4 and IPv6
 	  (from sys/netinet/tcp*) and separate udp4/6 code.  It uses
 	  unified inpcb structure.</para>
 
 	  <para>The platform can be configured to support IPv4 mapped address.
 	  Kernel configuration is summarized as follows:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>By default, AF_INET6 socket will grab IPv4
 	      connections in certain condition, and can initiate
 	      connection to IPv4 destination embedded in IPv4 mapped
 	      IPv6 address.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>You can disable it on entire system with sysctl like
 	      below.</para>
 
 	      <para>
 	        <command>sysctl -w net.inet6.ip6.mapped_addr=0</command>
 	      </para>
 
 	    </listitem>
 	  </itemizedlist>
 
 	  <sect5>
 	    <title>listening side</title>
 
 	    <para>Each socket can be configured to support special AF_INET6
 	    wildcard bind (enabled by default).  You can disable it on
 	    each socket basis with &man.setsockopt.2; like below.</para>
 
 	<screen>	int on;
 
 	setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
 		   (char *)&amp;on, sizeof (on)) < 0));
 	</screen>
 
 	    <para>Wildcard AF_INET6 socket grabs IPv4 connection if and only
 	    if the following conditions are satisfied:</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para>there's no AF_INET socket that matches the IPv4
 		connection</para>
 	      </listitem>
 
 	      <listitem>
 		<para>the AF_INET6 socket is configured to accept IPv4
 		traffic, i.e.  getsockopt(IPV6_BINDV6ONLY) returns 0.</para>
 	      </listitem>
 	    </itemizedlist>
 
 	    <para>There's no problem with open/close ordering.</para>
 	  </sect5>
 
 	  <sect5>
 	    <title>initiating side</title>
 
 	    <para>FreeBSD 4.x supports outgoing connection to IPv4 mapped
 	    address (::ffff:10.1.1.1), if the node is configured to support
 	    IPv4 mapped address.</para>
 	  </sect5>
 	</sect4>
       </sect3>
 
       <sect3>
 	<title>sockaddr_storage</title>
 
 	<para>When RFC2553 was about to be finalized, there was discussion on
 	how struct sockaddr_storage members are named.  One proposal is to
 	prepend "__" to the members (like "__ss_len") as they should not be
 	touched.  The other proposal was that don't prepend it (like "ss_len")
 	as we need to touch those members directly.  There was no clear
 	consensus on it.</para>
 
 	<para>As a result, RFC2553 defines struct sockaddr_storage as
 	follows:</para>
 
 	<screen>	struct sockaddr_storage {
 		u_char	__ss_len;	/* address length */
 		u_char	__ss_family;	/* address family */
 		/* and bunch of padding */
 	};
 	</screen>
 
 	<para>On the contrary, XNET draft defines as follows:</para>
 
 	<screen>	struct sockaddr_storage {
 		u_char	ss_len;		/* address length */
 		u_char	ss_family;	/* address family */
 		/* and bunch of padding */
 	};
 	</screen>
 
 	<para>In December 1999, it was agreed that RFC2553bis should pick
 	the latter (XNET) definition.</para>
 
 	<para>Current implementation conforms to XNET definition, based on
 	RFC2553bis discussion.</para>
 
 	<para>If you look at multiple IPv6 implementations, you will be able
 	to see both definitions.  As an userland programmer, the most
 	portable way of dealing with it is to:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>ensure ss_family and/or ss_len are available on the
 	    platform, by using GNU autoconf,</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>have -Dss_family=__ss_family to unify all occurrences
 	    (including header file) into __ss_family, or</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>never touch __ss_family.  cast to sockaddr * and use sa_family
 	    like:</para>
 
 	    <screen>	struct sockaddr_storage ss;
 	family = ((struct sockaddr *)&amp;ss)->sa_family
 	    </screen>
 
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Network Drivers</title>
 
       <para>Now following two items are required to be supported by standard
       drivers:</para>
 
       <orderedlist>
         <listitem>
           <para>mbuf clustering requirement. In this stable release, we
           changed MINCLSIZE into MHLEN+1 for all the operating systems
           in order to make all the drivers behave as we expect.</para>
         </listitem>
 
         <listitem>
           <para>multicast.  If &man.ifmcstat.8; yields no multicast group for
           a interface, that interface has to be patched.</para>
         </listitem>
       </orderedlist>
    
       <para>If any of the driver don't support the requirements, then
       the driver can't be used for IPv6 and/or IPsec communication.  If
       you find any problem with your card using IPv6/IPsec, then, please
       report it to <email>freebsd-bugs@FreeBSD.org</email>.</para>
 
       <para>(NOTE: In the past we required all PCMCIA drivers to have a
       call to in6_ifattach().  We have no such requirement any more)</para>
     </sect2>
 
     <sect2>
 	<title>Translator</title>
 
 	<para>We categorize IPv4/IPv6 translator into 4 types:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><emphasis>Translator A</emphasis> --- It is used in the early
 	    stage of transition to make it possible to establish a
 	    connection from an IPv6 host in an IPv6 island to an IPv4 host
 	    in the IPv4 ocean.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><emphasis>Translator B</emphasis> --- It is used in the early
 	    stage of transition to make it possible to establish a connection
 	    from an IPv4 host in the IPv4 ocean to an IPv6 host in an
 	    IPv6 island.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><emphasis>Translator C</emphasis> --- It is used in the late
 	    stage of transition to make it possible to establish a
 	    connection from an IPv4 host in an IPv4 island to an IPv6 host
 	    in the IPv6 ocean.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><emphasis>Translator D</emphasis> --- It is used in the late
 	    stage of transition to make it possible to establish a
 	    connection from an IPv6 host in the IPv6 ocean to an IPv4 host
 	    in an IPv4 island.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>TCP relay translator for category A is supported.  This is called
 	"FAITH".  We also provide IP header translator for category A.
 	(The latter is not yet put into FreeBSD 4.x yet.)</para>
 
       <sect3>
 	<title>FAITH TCP relay translator</title>
 
 	<para>FAITH system uses TCP relay daemon called &man.faithd.8; helped
 	by the kernel.  FAITH will reserve an IPv6 address prefix, and relay
 	TCP connection toward that prefix to IPv4 destination.</para>
 
 	<para>For example, if the reserved IPv6 prefix is
 	3ffe:0501:0200:ffff::, and the IPv6 destination for TCP connection
 	is 3ffe:0501:0200:ffff::163.221.202.12, the connection will be
 	relayed toward IPv4 destination 163.221.202.12.</para>
 
 	<screen>	destination IPv4 node (163.221.202.12)
 	  ^
 	  | IPv4 tcp toward 163.221.202.12
 	FAITH-relay dual stack node
 	  ^
 	  | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
 	source IPv6 node
 	</screen>
   
 	<para>&man.faithd.8; must be invoked on FAITH-relay dual stack
 	node.</para>
 
 	<para>For more details, consult
 	<filename>src/usr.sbin/faithd/README</filename></para>
       </sect3>
     </sect2>
 
     <sect2 id="ipsec-implementation">
       <title>IPsec</title>
 
       <para>IPsec is mainly organized by three components.</para>
 
       <orderedlist>
 	<listitem>
 	  <para>Policy Management</para>
 	</listitem>
 
 	<listitem>
 	  <para>Key Management</para>
 	</listitem>
 
 	<listitem>
 	  <para>AH and ESP handling</para>
 	</listitem>
       </orderedlist>
 
       <sect3>
 	<title>Policy Management</title>
 
 	<para>The kernel implements experimental policy management code.
 	There are two way to manage security policy.  One is to configure
 	per-socket policy using &man.setsockopt.2;.  In this cases, policy
 	configuration is described in &man.ipsec.set.policy.3;.  The other
 	is to configure kernel packet filter-based policy using PF_KEY
 	interface, via &man.setkey.8;.</para>
 
 	<para>The policy entry is not re-ordered with its
 	indexes, so the order of entry when you add is very significant.</para>
       </sect3>
 
       <sect3>
 	<title>Key Management</title>
 
 	<para>The key management code implemented in this kit (sys/netkey)
 	is a home-brew PFKEY v2 implementation.  This conforms to RFC2367.
 	</para>
 
 	<para>The home-brew IKE daemon, "racoon" is included in the
 	kit (kame/kame/racoon).  Basically you'll need to run racoon as
 	daemon, then setup a policy to require keys (like
 	<command>ping -P 'out ipsec esp/transport//use'</command>).
 	The kernel will contact racoon daemon as necessary to exchange
 	keys.</para>
       </sect3>
 
       <sect3>
 	<title>AH and ESP handling</title>
 
 	<para>IPsec module is implemented as "hooks" to the standard IPv4/IPv6
 	processing.  When sending a packet, ip{,6}_output() checks if ESP/AH
 	processing is required by checking if a matching SPD (Security
 	Policy Database) is found.  If ESP/AH is needed,
 	{esp,ah}{4,6}_output() will be called and mbuf will be updated
 	accordingly.  When a packet is received, {esp,ah}4_input() will be
 	called based on protocol number, i.e. (*inetsw[proto])().
 	{esp,ah}4_input() will decrypt/check authenticity of the packet,
 	and strips off daisy-chained header and padding for ESP/AH.  It is
 	safe to strip off the ESP/AH header on packet reception, since we
 	will never use the received packet in "as is" form.</para>
 
 	<para>By using ESP/AH, TCP4/6 effective data segment size will be
 	affected by extra daisy-chained headers inserted by ESP/AH.  Our
 	code takes care of the case.</para>
 
 	<para>Basic crypto functions can be found in directory "sys/crypto".
 	ESP/AH transform are listed in {esp,ah}_core.c with wrapper functions.
 	If you wish to add some algorithm, add wrapper function in
 	{esp,ah}_core.c, and add your crypto algorithm code into
 	sys/crypto.</para>
 
 	<para>Tunnel mode is partially supported in this release, with the
 	following restrictions:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>IPsec tunnel is not combined with GIF generic tunneling
 	    interface.  It needs a great care because we may create an
 	    infinite loop between ip_output() and tunnelifp->if_output().
 	    Opinion varies if it is better to unify them, or not.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>MTU and Don't Fragment bit (IPv4) considerations need more
 	    checking, but basically works fine.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Authentication model for AH tunnel must be revisited.
 	    We'll need to improve the policy management engine,
 	    eventually.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Conformance to RFCs and IDs</title>
 
 	<para>The IPsec code in the kernel conforms (or, tries to conform)
 	to the following standards:</para>
 
     	<para>"old IPsec" specification documented in
 	<filename>rfc182[5-9].txt</filename></para>
     
     	<para>"new IPsec" specification documented in
 	<filename>rfc240[1-6].txt</filename>,
 	<filename>rfc241[01].txt</filename>, <filename>rfc2451.txt</filename>
 	and <filename>draft-mcdonald-simple-ipsec-api-01.txt</filename>
 	(draft expired, but you can take from <ulink
 	url="ftp://ftp.kame.net/pub/internet-drafts/">
 	ftp://ftp.kame.net/pub/internet-drafts/</ulink>).
 	(NOTE: IKE specifications, <filename>rfc241[7-9].txt</filename> are
 	implemented in userland, as "racoon" IKE daemon)</para>
 
 	<para>Currently supported algorithms are:</para>
 	<itemizedlist>
 	  <listitem>
 	    <para>old IPsec AH</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>null crypto checksum (no document, just for
 		debugging)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed MD5 with 128bit crypto checksum
 		(<filename>rfc1828.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed SHA1 with 128bit crypto checksum
 		(no document)</para>
 	      </listitem>
 	      <listitem>
 		<para>HMAC MD5 with 128bit crypto checksum
 		(<filename>rfc2085.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>HMAC SHA1 with 128bit crypto checksum
 		(no document)</para>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 
 	  <listitem>
             <para>old IPsec ESP</para>
 	    <itemizedlist>
 	      <listitem>
 	        <para>null encryption (no document, similar to
 		<filename>rfc2410.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 	        <para>DES-CBC mode (<filename>rfc1829.txt</filename>)</para>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 
 	  <listitem>
 	    <para>new IPsec AH</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>null crypto checksum (no document,
 		just for debugging)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed MD5 with 96bit crypto checksum
 		(no document)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed SHA1 with 96bit crypto checksum
 		(no document)</para>
 	      </listitem>
 	      <listitem>
 		<para>HMAC MD5 with 96bit crypto checksum
 		(<filename>rfc2403.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>HMAC SHA1 with 96bit crypto checksum
 		(<filename>rfc2404.txt</filename>)</para>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 
 	  <listitem>
             <para>new IPsec ESP</para>
 	    <itemizedlist>
 	      <listitem>
 		<para>null encryption
 		(<filename>rfc2410.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>DES-CBC with derived IV
 		(<filename>draft-ietf-ipsec-ciph-des-derived-01.txt</filename>,
 		draft expired)</para>
 	      </listitem>
 	      <listitem>
 		<para>DES-CBC with explicit IV
 		(<filename>rfc2405.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>3DES-CBC with explicit IV
 		(<filename>rfc2451.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>BLOWFISH CBC
 		(<filename>rfc2451.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>CAST128 CBC
 		(<filename>rfc2451.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>RC5 CBC
 		(<filename>rfc2451.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>each of the above can be combined with:</para>
 	 	<itemizedlist>
 		  <listitem>
 	    	    <para>ESP authentication with HMAC-MD5(96bit)</para>
 		  </listitem>
 		  <listitem>
 	            <para>ESP authentication with HMAC-SHA1(96bit)</para>
 		  </listitem>
 	        </itemizedlist>
 	      </listitem>
 	    </itemizedlist>
 	  </listitem>
 	</itemizedlist>
 
 	<para>The following algorithms are NOT supported:</para>
 	<itemizedlist>
 	  <listitem>
 
 	    <para>old IPsec AH</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para>HMAC MD5 with 128bit crypto checksum + 64bit
 		replay prevention (<filename>rfc2085.txt</filename>)</para>
 	      </listitem>
 	      <listitem>
 		<para>keyed SHA1 with 160bit crypto checksum + 32bit padding
 		(<filename>rfc1852.txt</filename>)</para>
 	      </listitem>
 	    </itemizedlist>
 
 	  </listitem>
 	</itemizedlist>
 
 	<para>IPsec (in kernel) and IKE (in userland as "racoon") has been
 	tested at several interoperability test events, and it is known to
 	interoperate with many other implementations well.  Also, current
 	IPsec implementation as quite wide coverage for IPsec crypto
 	algorithms documented in RFC (we cover algorithms without intellectual
 	property issues only).</para>
       </sect3>
 
       <sect3 id="ipsec-ecn">
 	<title>ECN consideration on IPsec tunnels</title>
 
 	<para>ECN-friendly IPsec tunnel is supported as described in
 	<filename>draft-ipsec-ecn-00.txt</filename>.</para>
 
 	<para>Normal IPsec tunnel is described in RFC2401.  On encapsulation,
 	IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
 	IP header to outer IP header.  On decapsulation outer IP header
 	will be simply dropped.  The decapsulation rule is not compatible
 	with ECN, since ECN bit on the outer IP TOS/traffic class field will be
 	lost.</para>
 
 	<para>To make IPsec tunnel ECN-friendly, we should modify encapsulation
 	and decapsulation procedure.  This is described in <ulink
 	url="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt">
 	http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</ulink>,
 	chapter 3.</para>
 
 	<para>IPsec tunnel implementation can give you three behaviors, by
 	setting net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some
 	value:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>RFC2401: no consideration for ECN (sysctl value -1)</para>
 	  </listitem>
 	  <listitem>
 	    <para>ECN forbidden (sysctl value 0)</para>
 	  </listitem>
 	  <listitem>
 	    <para>ECN allowed (sysctl value 1)</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>Note that the behavior is configurable in per-node manner,
 	not per-SA manner (draft-ipsec-ecn-00 wants per-SA configuration,
 	but it looks too much for me).</para>
 
 	<para>The behavior is summarized as follows (see source code for
 	more detail):</para>
 
 	<screen>
                 encapsulate                     decapsulate
                 ---                             ---
 RFC2401         copy all TOS bits               drop TOS bits on outer
                 from inner to outer.            (use inner TOS bits as is)
 
 ECN forbidden   copy TOS bits except for ECN    drop TOS bits on outer
                 (masked with 0xfc) from inner   (use inner TOS bits as is)
                 to outer.  set ECN bits to 0.
 
 ECN allowed     copy TOS bits except for ECN    use inner TOS bits with some
                 CE (masked with 0xfe) from      change.  if outer ECN CE bit
                 inner to outer.                 is 1, enable ECN CE bit on
                 set ECN CE bit to 0.            the inner.
 
 	</screen>
 
 	<para>General strategy for configuration is as follows:</para>
 	<itemizedlist>
 	  <listitem>
 	    <para>if both IPsec tunnel endpoint are capable of ECN-friendly
 	    behavior, you'd better configure both end to "ECN allowed"
 	    (sysctl value 1).</para>
 	  </listitem>
 	  <listitem>
             <para>if the other end is very strict about TOS bit, use "RFC2401"
             (sysctl value -1).</para>
 	  </listitem>
 	  <listitem>
 	    <para>in other cases, use "ECN forbidden" (sysctl value 0).</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>The default behavior is "ECN forbidden" (sysctl value 0).</para>
 
 	<para>For more information, please refer to:</para>
 
 	<para><ulink
 	url="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt">
 	http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</ulink>,
 	RFC2481 (Explicit Congestion Notification),
 	src/sys/netinet6/{ah,esp}_input.c</para>
 
 	<para>(Thanks goes to Kenjiro Cho <email>kjc@csl.sony.co.jp</email>
 	for detailed analysis)</para>
       </sect3>
 
       <sect3>
 	<title>Interoperability</title>
 
 	<para>Here are (some of) platforms that KAME code have tested
 	IPsec/IKE interoperability in the past.  Note that both ends may
 	have modified their implementation, so use the following list just
 	for reference purposes.</para>
 
 	<para>Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure),
 	Ericsson ACC, FreeS/WAN, HITACHI, IBM AIX, IIJ, Intel,
 	Microsoft WinNT, NIST (linux IPsec + plutoplus), Netscreen, OpenBSD,
 	RedCreek, Routerware, SSH, Secure Computing, Soliton, Toshiba,
 	VPNet, Yamaha RT100i</para>
       </sect3>
     </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml
index c68a55d85c..96f68a88c5 100644
--- a/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml
@@ -1,2479 +1,2479 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD$
+     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml,v 1.1 2001/05/02 01:56:01 murray Exp $
 -->
 
 <chapter id="isa-driver">
   <title>ISA device drivers</title>
 
   <para>
     <emphasis> 
       This chapter was written by &a.babkin; Modifications for the
       handbook made by &a.murray;, &a.wylie;, and &a.logo;.
     </emphasis>
   </para>
 
   <sect1>
     <title>Synopsis</title>
 
     <para>This chapter introduces the issues relevant to writing a
       driver for an ISA device.  The pseudo-code presented here is
       rather detailed and reminiscent of the real code but is still
       only pseudo-code. It avoids the details irrelevant to the
       subject of the discussion. The real-life examples can be found
       in the source code of real drivers. In particular the drivers
       "ep" and "aha" are good sources of information.</para>
   </sect1>
 
   <sect1>
     <title>Basic information</title>
 
     <para>A typical ISA driver would need the following include
       files:</para>
 
 <programlisting>#include &lt;sys/module.h&gt;
 #include &lt;sys/bus.h&gt;
 #include &lt;machine/bus.h&gt;
 #include &lt;machine/resource.h&gt;
 #include &lt;sys/rman.h&gt;
 
 #include &lt;isa/isavar.h&gt;
 #include &lt;isa/pnpvar.h&gt;</programlisting>
 
     <para>They describe the things specific to the ISA and generic
       bus subsystem.</para>
 
     <para>The bus subsystem is implemented in an object-oriented
       fashion, its main structures are accessed by associated method
       functions.</para>
 
     <para>The list of bus methods implemented by an ISA driver is like
       one for any other bus. For a hypothetical driver named "xxx"
       they would be:</para>
 
     <itemizedlist>
       <listitem>
         <para><function>static void xxx_isa_identify (driver_t *,
           device_t);</function> Normally used for bus drivers, not
           device drivers. But for ISA devices this method may have
           special use: if the device provides some device-specific
           (non-PnP) way to auto-detect devices this routine may
           implement it.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_probe (device_t
           dev);</function> Probe for a device at a known (or PnP)
           location. This routine can also accommodate device-specific
           auto-detection of parameters for partially configured
           devices.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_attach (device_t
           dev);</function> Attach and initialize device.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_detach (device_t
           dev);</function> Detach device before unloading the driver
           module.</para>
       </listitem>
 
       <listitem>
         <para><function>static int xxx_isa_shutdown (device_t
           dev);</function> Execute shutdown of the device before
           system shutdown.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_suspend (device_t
           dev);</function> Suspend the device before the system goes
           to the power-save state. May also abort transition to the
           power-save state.</para>
       </listitem>
 
       <listitem>
 	<para><function>static int xxx_isa_resume (device_t
  	  dev);</function> Resume the device activity after return
  	  from power-save state.</para>
       </listitem>
 
     </itemizedlist>
 
     <para><function>xxx_isa_probe()</function> and
       <function>xxx_isa_attach()</function> are mandatory, the rest of
       the routines are optional, depending on the device's
       needs.</para>
 
     <para>The driver is linked to the system with the following set of
       descriptions.</para>
 
 <programlisting>    /* table of supported bus methods */
     static device_method_t xxx_isa_methods[] = {
         /* list all the bus method functions supported by the driver */
         /* omit the unsupported methods */
         DEVMETHOD(device_identify,  xxx_isa_identify),
         DEVMETHOD(device_probe,     xxx_isa_probe),
         DEVMETHOD(device_attach,    xxx_isa_attach),
         DEVMETHOD(device_detach,    xxx_isa_detach),
         DEVMETHOD(device_shutdown,  xxx_isa_shutdown),
         DEVMETHOD(device_suspend,   xxx_isa_suspend),
         DEVMETHOD(device_resume,    xxx_isa_resume),
 
 	{ 0, 0 }
     };
 
     static driver_t xxx_isa_driver = {
         "xxx",
         xxx_isa_methods,
         sizeof(struct xxx_softc),
     };
 
 
     static devclass_t xxx_devclass;
 
     DRIVER_MODULE(xxx, isa, xxx_isa_driver, xxx_devclass,
         load_function, load_argument);</programlisting>
 
       <para>Here struct <structname>xxx_softc</structname> is a
         device-specific structure that contains private driver data
         and descriptors for the driver's resources.  The bus code
         automatically allocates one softc descriptor per device as
         needed.</para>
 
       <para>If the driver is implemented as a loadable module then
         <function>load_function()</function> is called to do
         driver-specific initialization or clean-up when the driver is
         loaded or unloaded and load_argument is passed as one of its
         arguments.  If the driver does not support dynamic loading (in
         other words it must always be linked into kernel) then these
         values should be set to 0 and the last definition would look
         like:</para>
 
       <programlisting> DRIVER_MODULE(xxx, isa, xxx_isa_driver,
        xxx_devclass, 0, 0);</programlisting>
 
       <para>If the driver is for a device which supports PnP then a
         table of supported PnP IDs must be defined.  The table
         consists of a list of PnP IDs supported by this driver and
         human-readable descriptions of the hardware types and models
         having these IDs. It looks like:</para>
 
 <programlisting>    static struct isa_pnp_id xxx_pnp_ids[] = {
         /* a line for each supported PnP ID */
         { 0x12345678,   "Our device model 1234A" },
         { 0x12345679,   "Our device model 1234B" },
         { 0,        NULL }, /* end of table */
     };</programlisting>
 
       <para>If the driver does not support PnP devices it still needs
         an empty PnP ID table, like:</para>
 
 <programlisting>    static struct isa_pnp_id xxx_pnp_ids[] = {
         { 0,        NULL }, /* end of table */
     };</programlisting>
 
     </sect1>
 
     <sect1>
       <title>Device_t pointer</title>
 
       <para><structname>Device_t</structname> is the pointer type for
 	the device structure. Here we consider only the methods
 	interesting from the device driver writer's standpoint.  The
 	methods to manipulate values in the device structure
 	are:</para>
 
       <itemizedlist>
 
         <listitem><para><function>device_t
 	  device_get_parent(dev)</function> Get the parent bus of a
 	  device.</para></listitem>
 
         <listitem><para><function>driver_t
 	  device_get_driver(dev)</function> Get pointer to its driver
 	  structure.</para></listitem>
 
 	<listitem><para><function>char
 	  *device_get_name(dev)</function> Get the driver name, such
 	  as "xxx" for our example.</para></listitem>
 
 	<listitem><para><function>int device_get_unit(dev)</function>
 	  Get the unit number (units are numbered from 0 for the
 	  devices associated with each driver).</para></listitem>
 
 	<listitem><para><function>char
 	  *device_get_nameunit(dev)</function> Get the device name
 	  including the unit number, such as "xxx0" , "xxx1" and so
 	  on.</para></listitem>
 
 	<listitem><para><function>char
 	  *device_get_desc(dev)</function> Get the device
 	  description. Normally it describes the exact model of device
 	  in human-readable form.</para></listitem>
 
 	<listitem><para><function>device_set_desc(dev,
 	  desc)</function> Set the description. This makes the device
 	  description point to the string desc which may not be
 	  deallocated or changed after that.</para></listitem>
 
 	<listitem><para><function>device_set_desc_copy(dev,
 	  desc)</function> Set the description. The description is
 	  copied into an internal dynamically allocated buffer, so the
 	  string desc may be changed afterwards without adverse
 	  effects.</para></listitem>
 
 	<listitem><para><function>void
 	  *device_get_softc(dev)</function> Get pointer to the device
 	  descriptor (struct <structname>xxx_softc</structname>)
 	  associated with this device.</para></listitem>
 
 	<listitem><para><function>u_int32_t
 	  device_get_flags(dev)</function> Get the flags specified for
 	  the device in the configuration file.</para></listitem>
 
       </itemizedlist>
 
       <para>A convenience function <function>device_printf(dev, fmt,
 	...)</function> may be used to print the messages from the
 	device driver. It automatically prepends the unitname and
 	colon to the message.</para>
 
       <para>The device_t methods are implemented in the file
         kern/bus_subr.c.</para>
 
     </sect1>
 
     <sect1>
       <title>Config file and the order of identifying and probing
 	during auto-configuration</title>
 
       <para>The ISA devices are described in the kernel config file
   	like:</para>
 
       <programlisting>device xxx0 at isa? port 0x300 irq 10 drq 5
        iomem 0xd0000 flags 0x1 sensitive</programlisting>
 
       <para>The values of port, IRQ and so on are converted to the
 	resource values associated with the device. They are optional,
 	depending on the device needs and abilities for
 	auto-configuration. For example, some devices don't need DRQ
 	at all and some allow the driver to read the IRQ setting from
 	the device configuration ports. If a machine has multiple ISA
 	buses the exact bus may be specified in the configuration
 	line, like "isa0" or "isa1", otherwise the device would be
 	searched for on all the ISA buses.</para>
 
       <para>"sensitive" is a resource requesting that this device must
 	be probed before all non-sensitive devices. It is supported
 	but does not seem to be used in any current driver.</para>
 
       <para>For legacy ISA devices in many cases the drivers are still
 	able to detect the configuration parameters. But each device
 	to be configured in the system must have a config line. If two
 	devices of some type are installed in the system but there is
 	only one configuration line for the corresponding driver, ie:
 	<programlisting>device xxx0 at isa?</programlisting> then only
 	one device will be configured.</para>
 
       <para>But for the devices supporting automatic identification by
 	the means of Plug-n-Play or some proprietary protocol one
 	configuration line is enough to configure all the devices in
 	the system, like the one above or just simply:</para>
 
       <programlisting>device xxx at isa?</programlisting>
 
       <para>If a driver supports both auto-identified and legacy
 	devices and both kinds are installed at once in one machine
 	then it's enough to describe in the config file the legacy
 	devices only. The auto-identified devices will be added
 	automatically.</para>
 
       <para>When an ISA bus is auto-configured the events happen as
   	follows:</para>
 
       <para>All the drivers' identify routines (including the PnP
 	identify routine which identifies all the PnP devices) are
 	called in random order.  As they identify the devices they add
 	them to the list on the ISA bus.  Normally the drivers'
 	identify routines associate their drivers with the new
 	devices. The PnP identify routine does not know about the
 	other drivers yet so it does not associate any with the new
 	devices it adds.</para>
 
       <para>The PnP devices are put to sleep using the PnP protocol to
         prevent them from being probed as legacy devices.</para>
 
       <para>The probe routines of non-PnP devices marked as
         "sensitive" are called.  If probe for a device went
         successfully, the attach routine is called for it.</para>
 
       <para>The probe and attach routines of all non-PNP devices are
   	called likewise.</para>
 
       <para>The PnP devices are brought back from the sleep state and
         assigned the resources they request: I/O and memory address
         ranges, IRQs and DRQs, all of them not conflicting with the
         attached legacy devices.</para>
 
       <para>Then for each PnP device the probe routines of all the
         present ISA drivers are called. The first one that claims the
         device gets attached.  It is possible that multiple drivers
         would claim the device with different priority, the
         highest-priority driver wins.  The probe routines must call
         <function>ISA_PNP_PROBE()</function> to compare the actual PnP
         ID with the list of the IDs supported by the driver and if the
         ID is not in the table return failure. That means that
         absolutely every driver, even the ones not supporting any PnP
         devices must call <function>ISA_PNP_PROBE()</function>, at
         least with an empty PnP ID table to return failure on unknown
         PnP devices.</para>
 
       <para>The probe routine returns a positive value (the error
         code) on error, zero or negative value on success.</para>
 
       <para>The negative return values are used when a PnP device
         supports multiple interfaces. For example, an older
         compatibility interface and a newer advanced interface which
         are supported by different drivers. Then both drivers would
         detect the device. The driver which returns a higher value in
         the probe routine takes precedence (in other words, the driver
         returning 0 has highest precedence, returning -1 is next,
         returning -2 is after it and so on). In result the devices
         which support only the old interface will be handled by the
         old driver (which should return -1 from the probe routine)
         while the devices supporting the new interface as well will be
         handled by the new driver (which should return 0 from the
         probe routine). If multiple drivers return the same value then
         the one called first wins. So if a driver returns value 0 it
         may be sure that it won the priority arbitration.</para>
 
       <para>The device-specific identify routines can also assign not
         a driver but a class of drivers to the device. Then all the
         drivers in the class are probed for this device, like the case
         with PnP. This feature is not implemented in any existing
         driver and is not considered further in this document.</para>
 
       <para>Because the PnP devices are disabled when probing the
         legacy devices they will not be attached twice (once as legacy
         and once as PnP).  But in case of device-dependent identify
         routines it's the responsibility of the driver to make sure
         that the same device won't be attached by the driver twice:
         once as legacy user-configured and once as
         auto-identified.</para>
 
       <para>Another practical consequence for the auto-identified
         devices (both PnP and device-specific) is that the flags can
         not be passed to them from the kernel configuration file. So
         they must either not use the flags at all or use the flags
         from the device unit 0 for all the auto-identified devices or
         use the sysctl interface instead of flags.</para>
 
       <para>Other unusual configurations may be accommodated by
         accessing the configuration resources directly with functions
         of families <function>resource_query_*()</function> and
         <function>resource_*_value()</function>. Their implementations
         are located in kern/subr_bus.h. The old IDE disk driver
         i386/isa/wd.c contains examples of such use. But the standard
         means of configuration must always be preferred. Leave parsing
         the configuration resources to the bus configuration
         code.</para>
 
     </sect1>
 
     <sect1>
       <title>Resources</title>
 
       <para>The information that a user enters into the kernel
         configuration file is processed and passed to the kernel as
         configuration resources. This information is parsed by the bus
         configuration code and transformed into a value of structure
         device_t and the bus resources associated with it. The drivers
         may access the configuration resources directly using
         functions resource_* for more complex cases of
         configuration. But generally it's not needed nor recommended,
         so this issue is not discussed further.</para>
 
       <para>The bus resources are associated with each device. They
         are identified by type and number within the type. For the ISA
         bus the following types are defined:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><emphasis>SYS_RES_IRQ</emphasis> - interrupt
 	    number</para>
 	</listitem>
 
 	<listitem>
 	  <para><emphasis>SYS_RES_DRQ</emphasis> - ISA DMA channel
 	    number</para>
 	</listitem>
 
 	<listitem>
 	  <para><emphasis>SYS_RES_MEMORY</emphasis> - range of
 	    device memory mapped into the system memory space
 	  </para>
 	</listitem>
 
 	<listitem>
 	  <para><emphasis>SYS_RES_IOPORT</emphasis> - range of
 	    device I/O registers</para>
         </listitem>
       </itemizedlist>
 
       <para>The enumeration within types starts from 0, so if a device
         has two memory regions if would have resources of type
         SYS_RES_MEMORY numbered 0 and 1.  The resource type has
         nothing to do with the C language type, all the resource
         values have the C language type "unsigned long" and must be
         cast as necessary. The resource numbers don't have to be
         contiguous although for ISA they normally would be. The
         permitted resource numbers for ISA devices are:</para>
 
       <programlisting>          IRQ: 0-1
           DRQ: 0-1
           MEMORY: 0-3
           IOPORT: 0-7</programlisting>
 
       <para>All the resources are represented as ranges, with a start
         value and count.  For IRQ and DRQ resources the count would be
         normally equal to 1. The values for memory refer to the
         physical addresses.</para>
 
       <para>Three types of activities can be performed on
         resources:</para>
 
       <itemizedlist>
 	<listitem><para>set/get</para></listitem>
 	<listitem><para>allocate/release</para></listitem>
 	<listitem><para>activate/deactivate</para></listitem>
       </itemizedlist>
 
       <para>Setting sets the range used by the resource. Allocation
         reserves the requested range that no other driver would be
         able to reserve it (and checking that no other driver reserved
         this range already). Activation makes the resource accessible
         to the driver doing whatever is necessary for that (for
         example, for memory it would be mapping into the kernel
         virtual address space).</para>
 
       <para>The functions to manipulate resources are:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><function>int bus_set_resource(device_t dev, int type,
             int rid, u_long start, u_long count)</function></para>
 
           <para>Set a range for a resource. Returns 0 if successful,
             error code otherwise.  Normally the only reason this
             function would return an error is value of type, rid,
             start or count out of permitted range.</para>
 
           <itemizedlist>
             <listitem>
               <para> dev - driver's device</para>
             </listitem>
             <listitem>
               <para> type - type of resource, SYS_RES_* </para>
             </listitem>
             <listitem>
               <para> rid - resource number (ID) within type </para>
             </listitem>
             <listitem>
               <para> start, count - resource range </para>
             </listitem>
           </itemizedlist>
         </listitem>
 
         <listitem>
           <para><function>int bus_get_resource(device_t dev, int type,
           int rid, u_long *startp, u_long *countp)</function></para>
 
           <para>Get the range of resource. Returns 0 if successful,
             error code if the resource is not defined yet.</para>
         </listitem>
 
         <listitem>
 	  <para><function>u_long bus_get_resource_start(device_t dev,
             int type, int rid) u_long bus_get_resource_count (device_t
             dev, int type, int rid)</function></para>
 
           <para>Convenience functions to get only the start or
             count. Return 0 in case of error, so if the resource start
             has 0 among the legitimate values it would be impossible
             to tell if the value is 0 or an error occurred.  Luckily,
             no ISA resources for add-on drivers may have a start value
             equal 0.</para>
         </listitem>
 
         <listitem>
           <para><function>void bus_delete_resource(device_t dev, int
             type, int rid)</function></para>
           <para> Delete a resource, make it undefined.</para>
         </listitem>
 
         <listitem>
           <para><function>struct resource *
             bus_alloc_resource(device_t dev, int type, int *rid,
             u_long start, u_long end, u_long count, u_int
             flags)</function></para>
 
           <para>Allocate a resource as a range of count values not
             allocated by anyone else, somewhere between start and
             end. Alas, alignment is not supported.  If the resource
             was not set yet it's automatically created. The special
             values of start 0 and end ~0 (all ones) means that the
             fixed values previously set by
             <function>bus_set_resource()</function> must be used
             instead: start and count as themselves and
             end=(start+count), in this case if the resource was not
             defined before then an error is returned.  Although rid is
             passed by reference it's not set anywhere by the resource
             allocation code of the ISA bus. (The other buses may use a
             different approach and modify it).</para>
         </listitem>
       </itemizedlist>
 
       <para>Flags are a bitmap, the flags interesting for the caller
         are:</para>
 
       <itemizedlist>
         <listitem>
           <para><emphasis>RF_ACTIVE</emphasis> - causes the resource
             to be automatically activated after allocation.</para>
         </listitem>
 
         <listitem>
           <para><emphasis>RF_SHAREABLE</emphasis> - resource may be
             shared at the same time by multiple drivers.</para>
         </listitem>
 
         <listitem>
           <para><emphasis>RF_TIMESHARE</emphasis> - resource may be
             time-shared by multiple drivers, i.e. allocated at the
             same time by many but activated only by one at any given
             moment of time.</para>
         </listitem>
 <!-- XXXDONT KNOW IT THESE SHOULD BE TWO SEPERATE LISTS OR NOT -->
         <listitem>
           <para>Returns 0 on error. The allocated values may be
             obtained from the returned handle using methods
             <function>rhand_*()</function>.</para>
         </listitem>
         <listitem>
           <para><function>int bus_release_resource(device_t dev, int
             type, int rid, struct resource *r)</function></para>
 	</listitem>
 
         <listitem>
           <para>Release the resource, r is the handle returned by
             <function>bus_alloc_resource()</function>.  Returns 0 on
             success, error code otherwise.</para>
         </listitem>
 
         <listitem>
           <para><function>int bus_activate_resource(device_t dev, int
             type, int rid, struct resource *r)</function>
             <function>int bus_deactivate_resource(device_t dev, int
             type, int rid, struct resource *r)</function></para>
         </listitem>
 
         <listitem>
           <para>Activate or deactivate resource. Return 0 on success,
             error code otherwise.  If the resource is time-shared and
             currently activated by another driver then EBUSY is
             returned.</para>
         </listitem>
 
         <listitem>
           <para><function>int bus_setup_intr(device_t dev, struct
             resource *r, int flags, driver_intr_t *handler, void *arg,
             void **cookiep)</function> <function>int
             bus_teardown_intr(device_t dev, struct resource *r, void
             *cookie)</function></para>
         </listitem>
 
         <listitem>
           <para>Associate or de-associate the interrupt handler with a
             device. Return 0 on success, error code otherwise.</para>
         </listitem>
 
         <listitem>
           <para>r - the activated resource handler describing the
             IRQ</para>
 	  <para>flags - the interrupt priority level, one of:</para>
 
           <itemizedlist>
             <listitem>
               <para><function>INTR_TYPE_TTY</function> - terminals and
                 other likewise character-type devices. To mask them
                 use <function>spltty()</function>.</para>
             </listitem>
             <listitem>
               <para><function>(INTR_TYPE_TTY |
                 INTR_TYPE_FAST)</function> - terminal type devices
                 with small input buffer, critical to the data loss on
                 input (such as the old-fashioned serial ports). To
                 mask them use <function>spltty()</function>.</para>
             </listitem>
             <listitem>
               <para><function>INTR_TYPE_BIO</function> - block-type
                 devices, except those on the CAM controllers. To mask
                 them use <function>splbio()</function>.</para>
             </listitem>
             <listitem>
               <para><function>INTR_TYPE_CAM</function> - CAM (Common
                 Access Method) bus controllers. To mask them use
                 <function>splcam()</function>.</para>
              </listitem>
              <listitem>
                <para><function>INTR_TYPE_NET</function> - network
                 interface controllers. To mask them use
                 <function>splimp()</function>.</para>
              </listitem>
              <listitem>
                <para><function>INTR_TYPE_MISC</function> -
                 miscellaneous devices.  There is no other way to mask
                 them than by <function>splhigh()</function> which
                 masks all interrupts.</para>
              </listitem>
           </itemizedlist>
         </listitem>
       </itemizedlist>
 
       <para>When an interrupt handler executes all the other
         interrupts matching its priority level will be masked. The
         only exception is the MISC level for which no other interrupts
         are masked and which is not masked by any other
         interrupt.</para>
 
       <itemizedlist>
         <listitem>
           <para><emphasis>handler</emphasis> - pointer to the handler
             function, the type driver_intr_t is defined as "void
             driver_intr_t(void *)"</para>
         </listitem>
         <listitem>
           <para><emphasis>arg</emphasis> - the argument passed to the
             handler to identify this particular device. It is cast
             from void* to any real type by the handler. The old
             convention for the ISA interrupt handlers was to use the
             unit number as argument, the new (recommended) convention
             is using a pointer to the device softc structure.</para>
         </listitem>
         <listitem>
           <para><emphasis>cookie[p]</emphasis> - the value received
             from <function>setup()</function> is used to identify the
             handler when passed to
             <function>teardown()</function></para>
         </listitem>
       </itemizedlist>
 
       <para>A number of methods is defined to operate on the resource
         handlers (struct resource *). Those of interest to the device
         driver writers are:</para>
 
       <itemizedlist>
         <listitem>
           <para><function>u_long rman_get_start(r) u_long
             rman_get_end(r)</function> Get the start and end of
             allocated resource range.</para>
         </listitem>
         <listitem>
           <para><function>void *rman_get_virtual(r)</function> Get
             the virtual address of activated memory resource.</para>
         </listitem>
       </itemizedlist>
 
     </sect1>
 
     <sect1>
       <title>Bus memory mapping</title>
 
       <para>In many cases data is exchanged between the driver and the
         device through the memory. Two variants are possible:</para>
 
       <para>(a) memory is located on the device card</para>
       <para>(b) memory is the main memory of computer</para>
 
       <para>In the case (a) the driver always copies the data back and
         forth between the on-card memory and the main memory as
         necessary. To map the on-card memory into the kernel virtual
         address space the physical address and length of the on-card
         memory must be defined as a SYS_RES_MEMORY resource. That
         resource can then be allocated and activated, and its virtual
         address obtained using
         <function>rman_get_virtual()</function>.  The older drivers
         used the function <function>pmap_mapdev()</function> for this
         purpose, which should not be used directly any more. Now it's
         one of the internal steps of resource activation.</para>
 
       <para>Most of the ISA cards will have their memory configured
         for physical location somewhere in range 640KB-1MB. Some of
         the ISA cards require larger memory ranges which should be
         placed somewhere under 16MB (because of the 24-bit address
         limitation on the ISA bus). In that case if the machine has
         more memory than the start address of the device memory (in
         other words, they overlap) a memory hole must be configured at
         the address range used by devices. Many BIOSes allow to
         configure a memory hole of 1MB starting at 14MB or
         15MB. FreeBSD can handle the memory holes properly if the BIOS
         reports them properly (old BIOSes may have this feature
         broken).</para>
 
       <para>In the case (b) just the address of the data is sent to
         the device, and the device uses DMA to actually access the
         data in the main memory. Two limitations are present: First,
         ISA cards can only access memory below 16MB.  Second, the
         contiguous pages in virtual address space may not be
         contiguous in physical address space, so the device may have
         to do scatter/gather operations. The bus subsystem provides
         ready solutions for some of these problems, the rest has to be
         done by the drivers themselves.</para>
 
       <para>Two structures are used for DMA memory allocation,
         bus_dma_tag_t and bus_dmamap_t. Tag describes the properties
         required for the DMA memory. Map represents a memory block
         allocated according to these properties. Multiple maps may be
         associated with the same tag.</para>
 
       <para>Tags are organized into a tree-like hierarchy with
         inheritance of the properties. A child tag inherits all the
         requirements of its parent tag or may make them more strict
         but never more loose.</para>
 
       <para>Normally one top-level tag (with no parent) is created for
         each device unit.  If multiple memory areas with different
         requirements are needed for each device then a tag for each of
         them may be created as a child of the parent tag.</para>
 
       <para>The tags can be used to create a map in two ways.</para>
 
       <para>First, a chunk of contiguous memory conformant with the
         tag requirements may be allocated (and later may be
         freed). This is normally used to allocate relatively
         long-living areas of memory for communication with the
         device. Loading of such memory into a map is trivial: it's
         always considered as one chunk in the appropriate physical
         memory range.</para>
 
       <para>Second, an arbitrary area of virtual memory may be loaded
         into a map. Each page of this memory will be checked for
         conformance to the map requirement.  If it conforms then it's
         left at it's original location. If it is not then a fresh
         conformant "bounce page" is allocated and used as intermediate
         storage. When writing the data from the non-conformant
         original pages they will be copied to their bounce pages first
         and then transferred from the bounce pages to the device. When
         reading the data would go from the device to the bounce pages
         and then copied to their non-conformant original pages. The
         process of copying between the original and bounce pages is
         called synchronization. This is normally used on per-transfer
         basis: buffer for each transfer would be loaded, transfer done
         and buffer unloaded.</para>
 
       <para>The functions working on the DMA memory are:</para>
 
       <itemizedlist>
         <listitem>
         <para><function>int bus_dma_tag_create(bus_dma_tag_t parent,
           bus_size_t alignment, bus_size_t boundary, bus_addr_t
           lowaddr, bus_addr_t highaddr, bus_dma_filter_t *filter, void
           *filterarg, bus_size_t maxsize, int nsegments, bus_size_t
           maxsegsz, int flags, bus_dma_tag_t *dmat)</function></para>
 
         <para>Create a new tag. Returns 0 on success, the error code
           otherwise.</para>
 
         <itemizedlist>
 	  <listitem>
             <para><emphasis>parent</emphasis> - parent tag, or NULL to
               create a top-level tag <emphasis>alignment</emphasis> -
               required physical alignment of the memory area to be
               allocated for this tag. Use value 1 for "no specific
               alignment". Applies only to the future
               <function>bus_dmamem_alloc()</function> but not
               <function>bus_dmamap_create()</function> calls.
               <emphasis>boundary</emphasis> - physical address
               boundary that must not be crossed when allocating the
               memory. Use value 0 for "no boundary". Applies only to
               the future <function>bus_dmamem_alloc()</function> but
               not <function>bus_dmamap_create()</function> calls.
               Must be power of 2. If the memory is planned to be used
               in non-cascaded DMA mode (i.e. the DMA addresses will be
               supplied not by the device itself but by the ISA DMA
               controller) then the boundary must be no larger than
               64KB (64*1024) due to the limitations of the DMA
               hardware.</para>
           </listitem>
 
           <listitem>
             <para><emphasis>lowaddr, highaddr</emphasis> - the names
               are slighlty misleading; these values are used to limit
               the permitted range of physical addresses used to
               allocate the memory.  The exact meaning varies depending
               on the planned future use:</para>
 
             <itemizedlist>
               <listitem>
                 <para>For <function>bus_dmamem_alloc()</function> all
                   the addresses from 0 to lowaddr-1 are considered
                   permitted, the higher ones are forbidden.</para>
               </listitem>
 
               <listitem>
                 <para>For <function>bus_dmamap_create()</function> all
                   the addresses outside the inclusive range [lowaddr;
                   highaddr] are considered accessible. The addresses
                   of pages inside the range are passed to the filter
                   function which decides if they are accessible. If no
                   filter function is supplied then all the range is
                   considered unaccessible.</para>
               </listitem>
 
               <listitem>
                 <para>For the ISA devices the normal values (with no
                   filter function) are:</para>
                 <para>lowaddr = BUS_SPACE_MAXADDR_24BIT</para>
                 <para>highaddr = BUS_SPACE_MAXADDR</para>
               </listitem>
             </itemizedlist>
 
           </listitem>
 
           <listitem>
             <para><emphasis>filter, filterarg</emphasis> - the filter
               function and its argument. If NULL is passed for filter
               then the whole range [lowaddr, highaddr] is considered
               unaccessible when doing
               <function>bus_dmamap_create()</function>.  Otherwise the
               physical address of each attempted page in range
               [lowaddr; highaddr] is passed to the filter function
               which decides if it is accessible. The prototype of the
               filter function is: <function>int filterfunc(void *arg,
               bus_addr_t paddr)</function> It must return 0 if the
               page is accessible, non-zero otherwise.</para>
           </listitem>
 
 	  <listitem>
             <para><emphasis>maxsize</emphasis> - the maximal size of
               memory (in bytes) that may be allocated through this
               tag. In case it's difficult to estimate or could be
               arbitrarily big, the value for ISA devices would be
               BUS_SPACE_MAXSIZE_24BIT.</para>
           </listitem>
 
 	  <listitem>
             <para><emphasis>nsegments</emphasis> - maximal number of
               scatter-gather segments supported by the device. If
               unrestricted then the value BUS_SPACE_UNRESTRICTED
               should be used. This value is recommended for the parent
               tags, the actual restrictions would then be specified
               for the descendant tags. Tags with nsegments equal to
               BUS_SPACE_UNRESTRICTED may not be used to actually load
               maps, they may be used only as parent tags. The
               practical limit for nsegments seems to be about 250-300,
               higher values will cause kernel stack overflow.  But
               anyway the hardware normally can't support that many
               scatter-gather buffers.</para>
           </listitem>
 
 	  <listitem>
             <para><emphasis>maxsegsz</emphasis> - maximal size of a
               scatter-gather segment supported by the device. The
               maximal value for ISA device would be
               BUS_SPACE_MAXSIZE_24BIT.</para>
           </listitem>
 
 	  <listitem>
             <para><emphasis>flags</emphasis> - a bitmap of flags. The
               only interesting flags are:</para>
 
 	    <itemizedlist>
 	      <listitem>
                 <para><emphasis>BUS_DMA_ALLOCNOW</emphasis> - requests
                   to allocate all the potentially needed bounce pages
                   when creating the tag</para>
               </listitem>
 
 	      <listitem>
 	        <para><emphasis>BUS_DMA_ISA</emphasis> - mysterious
                   flag used only on Alpha machines. It is not defined
                   for the i386 machines.  Probably it should be used
                   by all the ISA drivers for Alpha machines but it
                   looks like there are no such drivers yet.</para>
               </listitem>
 	    </itemizedlist>
 	  </listitem>
 
           <listitem>
             <para><emphasis>dmat</emphasis> - pointer to the storage
               for the new tag to be returned</para>
           </listitem>
 
 	</itemizedlist>
 
       </listitem>
 
       <listitem> <!-- Second entry in list alpha -->
         <para><function>int bus_dma_tag_destroy(bus_dma_tag_t
 	  dmat)</function></para>
 
         <para>Destroy a tag. Returns 0 on success, the error code
 	  otherwise.</para>
 
         <para>dmat - the tag to be destroyed</para>
 
       </listitem>
 
       <listitem> <!-- Third entry in list alpha -->
         <para><function>int bus_dmamem_alloc(bus_dma_tag_t dmat,
           void** vaddr, int flags, bus_dmamap_t
           *mapp)</function></para>
 
         <para>Allocate an area of contiguous memory described by the
           tag. The size of memory to be allocated is tag's maxsize.
           Returns 0 on success, the error code otherwise. The result
           still has to be loaded by
           <function>bus_dmamap_load()</function> before used to get
           the physical address of the memory.</para>
 
 <!-- XXX What it is Wylie, I got to here -->
 
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - the tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>vaddr</emphasis> - pointer to the storage
                   for the kernel virtual address of the allocated area
                   to be returned.
                  </para>
               </listitem>
               <listitem>
                 <para>
                   flags - a bitmap of flags. The only interesting flag is:
                 </para>
                 <itemizedlist>
                   <listitem>
                     <para>
                       <emphasis>BUS_DMA_NOWAIT</emphasis> - if the
                       memory is not immediately available return the
                       error. If this flag is not set then the routine
                       is allowed to sleep waiting until the memory
                       will become available.
                     </para>
                   </listitem>
                 </itemizedlist>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>mapp</emphasis> - pointer to the storage
                   for the new map to be returned
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
 
           <listitem> <!-- Fourth entry in list alpha -->
             <para>
               <function>void bus_dmamem_free(bus_dma_tag_t dmat, void
               *vaddr, bus_dmamap_t map)</function>
             </para>
             <para>
               Free the memory allocated by
               <function>bus_dmamem_alloc()</function>. As of now
               freeing of the memory allocated with ISA restrictions is
               not implemented.  Because of this the recommended model
               of use is to keep and re-use the allocated areas for as
               long as possible. Do not lightly free some area and then
               shortly allocate it again. That does not mean that
               <function>bus_dmamem_free()</function> should not be
               used at all: hopefully it will be properly implemented
               soon.
             </para>
 
             <itemizedlist>
               <listitem>
                 <para><emphasis>dmat</emphasis> - the tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>vaddr</emphasis> - the kernel virtual
                   address of the memory
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>map</emphasis> - the map of the memory (as
                   returned from
                   <function>bus_dmamem_alloc()</function>)
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
 
           <listitem> <!-- The fifth entry in list alpha -->
             <para>
               <function>int bus_dmamap_create(bus_dma_tag_t dmat, int
               flags, bus_dmamap_t *mapp)</function>
             </para>
             <para>
               Create a map for the tag, to be used in
               <function>bus_dmamap_load()</function> later.  Returns 0
               on success, the error code otherwise.
             </para>
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - the tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>flags</emphasis> - theoretically, a bit map
                   of flags. But no flags are defined yet, so as of now
                   it will be always 0.
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>mapp</emphasis> - pointer to the storage
                   for the new map to be returned
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
 
           <listitem> <!-- Sixth entry in the alpha list -->
             <para>
               <function>int bus_dmamap_destroy(bus_dma_tag_t dmat,
               bus_dmamap_t map)</function>
             </para>
             <para>
               Destroy a map. Returns 0 on success, the error code otherwise.
             </para>
 
             <itemizedlist>
               <listitem>
                 <para>
                   dmat - the tag to which the map is associated
                 </para>
               </listitem>
               <listitem>
                 <para>
                   map - the map to be destroyed
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
 
           <listitem> <!-- Seventh entry in list alpha -->
             <para>
               <function>int bus_dmamap_load(bus_dma_tag_t dmat,
               bus_dmamap_t map, void *buf, bus_size_t buflen,
               bus_dmamap_callback_t *callback, void *callback_arg, int
               flags)</function>
             </para>
             <para>
               Load a buffer into the map (the map must be previously
               created by <function>bus_dmamap_create()</function> or
               <function>bus_dmamem_alloc()</function>).  All the pages
               of the buffer are checked for conformance to the tag
               requirements and for those not conformant the bounce
               pages are allocated. An array of physical segment
               descriptors is built and passed to the callback
               routine. This callback routine is then expected to
               handle it in some way. The number of bounce buffers in
               the system is limited, so if the bounce buffers are
               needed but not immediately available the request will be
               queued and the callback will be called when the bounce
               buffers will become available. Returns 0 if the callback
               was executed immediately or EINPROGRESS if the request
               was queued for future execution. In the latter case the
               synchronization with queued callback routine is the
               responsibility of the driver.
             </para>
             <!--<blockquote>-->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - the tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>map</emphasis> - the map
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>buf</emphasis> - kernel virtual address of
                   the buffer
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>buflen</emphasis> - length of the buffer
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>callback</emphasis>,<function>
                   callback_arg</function> - the callback function and
                   its argument
                 </para>
               </listitem>
             </itemizedlist>
             <!--</blockquote>-->
             <para>
               The prototype of callback function is:
             </para>
             <para>
               <function>void callback(void *arg, bus_dma_segment_t
               *seg, int nseg, int error)</function>
             </para>
             <!--     <blockquote> -->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>arg</emphasis> - the same as callback_arg
                   passed to <function>bus_dmamap_load()</function>
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>seg</emphasis> - array of the segment
                   descriptors
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>nseg</emphasis> - number of descriptors in
                   array
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>error</emphasis> - indication of the
                   segment number overflow: if it's set to EFBIG then
                   the buffer did not fit into the maximal number of
                   segments permitted by the tag. In this case only the
                   permitted number of descriptors will be in the
                   array. Handling of this situation is up to the
                   driver: depending on the desired semantics it can
                   either consider this an error or split the buffer in
                   two and handle the second part separately
                 </para>
               </listitem>
             </itemizedlist>
             <!--     </blockquote>  -->
             <para>
               Each entry in the segments array contains the fields:
             </para>
 
             <!--   <blockquote> -->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>ds_addr</emphasis> - physical bus address
                   of the segment
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>ds_len</emphasis> - length of the segment
                 </para>
               </listitem>
             </itemizedlist>
             <!--   </blockquote>-->
           </listitem>
 
           <listitem> <!-- Eighth entry in alpha list -->
             <para>
               <function>void bus_dmamap_unload(bus_dma_tag_t dmat,
               bus_dmamap_t map)</function>
             </para>
             <para>unload the map.
             </para>
             <!--  <blockquote>  -->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>map</emphasis> - loaded map
                 </para>
               </listitem>
             </itemizedlist>
             <!--  </blockquote>  -->
           </listitem>
 
           <listitem> <!-- Ninth entry list alpha -->
             <para>
               <function>void bus_dmamap_sync (bus_dma_tag_t dmat,
               bus_dmamap_t map, bus_dmasync_op_t op)</function>
             </para>
             <para>
               Synchronise a loaded buffer with its bounce pages before
               and after physical transfer to or from device. This is
               the function that does all the necessary copying of data
               between the original buffer and its mapped version. The
               buffers must be synchronized both before and after doing
               the transfer.
             </para>
             <!--  <blockquote> -->
             <itemizedlist>
               <listitem>
                 <para>
                   <emphasis>dmat</emphasis> - tag
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>map</emphasis> - loaded map
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <emphasis>op</emphasis> - type of synchronization
                   operation to perform:
                 </para>
               </listitem>
             </itemizedlist>
             <!-- <blockquote> -->
             <itemizedlist>
               <listitem>
                 <para>
                   <function>BUS_DMASYNC_PREREAD</function> - before
                   reading from device into buffer
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <function>BUS_DMASYNC_POSTREAD</function> - after
                   reading from device into buffer
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <function>BUS_DMASYNC_PREWRITE</function> - before
                   writing the buffer to device
                 </para>
               </listitem>
               <listitem>
                 <para>
                   <function>BUS_DMASYNC_POSTWRITE</function> - after
                   writing the buffer to device
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
         </itemizedlist>   <!-- End of list alpha -->
 <!-- </blockquote>
 </blockquote> -->
 
         <para>
           As of now PREREAD and POSTWRITE are null operations but that
           may change in the future, so they must not be ignored in the
           driver. Synchronization is not needed for the memory
           obtained from <function>bus_dmamem_alloc()</function>.
         </para>
         <para>
           Before calling the callback function from
           <function>bus_dmamap_load()</function> the segment array is
           stored in the stack. And it gets pre-allocated for the
           maximal number of segments allowed by the tag. Because of
           this the practical limit for the number of segments on i386
           architecture is about 250-300 (the kernel stack is 4KB minus
           the size of the user structure, size of a segment array
           entry is 8 bytes, and some space must be left). Because the
           array is allocated based on the maximal number this value
           must not be set higher than really needed. Fortunately, for
           most of hardware the maximal supported number of segments is
           much lower. But if the driver wants to handle buffers with a
           very large number of scatter-gather segments it should do
           that in portions: load part of the buffer, transfer it to
           the device, load next part of the buffer, and so on.
         </para>
         <para>
           Another practical consequence is that the number of segments
           may limit the size of the buffer. If all the pages in the
           buffer happen to be physically non-contiguous then the
           maximal supported buffer size for that fragmented case would
           be (nsegments * page_size). For example, if a maximal number
           of 10 segments is supported then on i386 maximal guaranteed
           supported buffer size would be 40K. If a higher size is
           desired then special tricks should be used in the driver.
         </para>
         <para>
           If the hardware does not support scatter-gather at all or
           the driver wants to support some buffer size even if it's
           heavily fragmented then the solution is to allocate a
           contiguous buffer in the driver and use it as intermediate
           storage if the original buffer does not fit.
         </para>
         <para>
           Below are the typical call sequences when using a map depend
           on the use of the map.  The characters -> are used to show
           the flow of time.
         </para>
         <para>
           For a buffer which stays practically fixed during all the
           time between attachment and detachment of a device:</para>
         <para>
           bus_dmamem_alloc -> bus_dmamap_load -> ...use buffer... ->
           -> bus_dmamap_unload -> bus_dmamem_free
         </para>
 
         <para>For a buffer that changes frequently and is passed from
         outside the driver:
 
 	<!-- XXX is this correct? -->
         <programlisting>          bus_dmamap_create ->
           -> bus_dmamap_load -> bus_dmamap_sync(PRE...) -> do transfer ->
           -> bus_dmamap_sync(POST...) -> bus_dmamap_unload ->
           ...
           -> bus_dmamap_load -> bus_dmamap_sync(PRE...) -> do transfer ->
           -> bus_dmamap_sync(POST...) -> bus_dmamap_unload ->
           -> bus_dmamap_destroy        </programlisting>
 
         </para>
         <para>
           When loading a map created by
           <function>bus_dmamem_alloc()</function> the passed address
           and size of the buffer must be the same as used in
           <function>bus_dmamem_alloc()</function>. In this case it is
           guaranteed that the whole buffer will be mapped as one
           segment (so the callback may be based on this assumption)
           and the request will be executed immediately (EINPROGRESS
           will never be returned).  All the callback needs to do in
           this case is to save the physical address.
         </para>
         <para>
           A typical example would be:
         </para>
 
         <programlisting>          static void
         alloc_callback(void *arg, bus_dma_segment_t *seg, int nseg, int error)
         {
           *(bus_addr_t *)arg = seg[0].ds_addr;
         }
 
           ...
           int error;
           struct somedata {
             ....
           };
           struct somedata *vsomedata; /* virtual address */
           bus_addr_t psomedata; /* physical bus-relative address */
           bus_dma_tag_t tag_somedata;
           bus_dmamap_t map_somedata;
           ...
 
           error=bus_dma_tag_create(parent_tag, alignment,
            boundary, lowaddr, highaddr, /*filter*/ NULL, /*filterarg*/ NULL,
            /*maxsize*/ sizeof(struct somedata), /*nsegments*/ 1,
            /*maxsegsz*/ sizeof(struct somedata), /*flags*/ 0,
            &#38;tag_somedata);
           if(error)
           return error;
 
           error = bus_dmamem_alloc(tag_somedata, &#38;vsomedata, /* flags*/ 0,
              &#38;map_somedata);
           if(error)
              return error;
 
           bus_dmamap_load(tag_somedata, map_somedata, (void *)vsomedata,
              sizeof (struct somedata), alloc_callback,
              (void *) &#38;psomedata, /*flags*/0);        </programlisting>
 
         <para>
           Looks a bit long and complicated but that's the way to do
           it. The practical consequence is: if multiple memory areas
           are allocated always together it would be a really good idea
           to combine them all into one structure and allocate as one
           (if the alignment and boundary limitations permit).
         </para>
         <para>
           When loading an arbitrary buffer into the map created by
           <function>bus_dmamap_create()</function> special measures
           must be taken to synchronize with the callback in case it
           would be delayed. The code would look like:
         </para>
 
         <programlisting>          {
            int s;
            int error;
 
            s = splsoftvm();
            error = bus_dmamap_load(
                dmat,
                dmamap,
                buffer_ptr,
                buffer_len,
                callback,
                /*callback_arg*/ buffer_descriptor,
                /*flags*/0);
            if (error == EINPROGRESS) {
                /*
                 * Do whatever is needed to ensure synchronization
                 * with callback. Callback is guaranteed not to be started
                 * until we do splx() or tsleep().
                 */
               }
            splx(s);
           }        </programlisting>
 
         <para>
           Two possible approaches for the processing of requests are:
         </para>
         <para>
           1. If requests are completed by marking them explicitly as
           done (such as the CAM requests) then it would be simpler to
           put all the further processing into the callback driver
           which would mark the request when it's done. Then not much
           extra synchronization is needed. For the flow control
           reasons it may be a good idea to freeze the request queue
           until this request gets completed.
         </para>
         <para>
           2. If requests are completed when the function returns (such
           as classic read or write requests on character devices) then
           a synchronization flag should be set in the buffer
           descriptor and <function>tsleep()</function> called.  Later
           when the callback gets called it will do it's processing and
           check this synchronization flag. If it's set then the
           callback should issue a wakeup. In this approach the
           callback function could either do all the needed processing
           (just like the previous case) or simply save the segments
           array in the buffer descriptor. Then after callback
           completes the calling function could use this saved segments
           array and do all the processing.
 
         </para>
      </sect1>
 <!--_________________________________________________________________________-->
 <!--~~~~~~~~~~~~~~~~~~~~END OF SECTION~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
 
      <sect1>
         <title>DMA</title>
         <!-- Section Marked up by Wylie -->
         <para>
           The Direct Memory Access (DMA) is implemented in the ISA bus
           through the DMA controller (actually, two of them but that's
           an irrelevant detail).  To make the early ISA devices simple
           and cheap the logic of the bus control and address
           generation was concentrated in the DMA controller.
           Fortunately, FreeBSD provides a set of functions that mostly
           hide the annoying details of the DMA controller from the
           device drivers.
         </para>
 
         <para>
           The simplest case is for the fairly intelligent
           devices. Like the bus master devices on PCI they can
           generate the bus cycles and memory addresses all by
           themselves. The only thing they really need from the DMA
           controller is bus arbitration. So for this purpose they
           pretend to be cascaded slave DMA controllers. And the only
           thing needed from the system DMA controller is to enable the
           cascaded mode on a DMA channel by calling the following
           function when attaching the driver:
         </para>
 
         <para>
           <function>void isa_dmacascade(int channel_number)</function>
         </para>
 
         <para>
           All the further activity is done by programming the
           device. When detaching the driver no DMA-related functions
           need to be called.
         </para>
 
         <para>
           For the simpler devices things get more complicated. The
           functions used are:
         </para>
 
         <itemizedlist>
 
           <listitem>
           <para>
             <function>int isa_dma_acquire(int chanel_number)</function>
           </para>
           <para>
                 Reserve a DMA channel. Returns 0 on success or EBUSY
                 if the channel was already reserved by this or a
                 different driver. Most of the ISA devices are not able
                 to share DMA channels anyway, so normally this
                 function is called when attaching a device. This
                 reservation was made redundant by the modern interface
                 of bus resources but still must be used in addition to
                 the latter. If not used then later, other DMA routines
                 will panic.
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>int isa_dma_release(int chanel_number)</function>
           </para>
           <para>
                 Release a previously reserved DMA channel. No
                 transfers must be in progress when the channel is
                 released (as well as the device must not try to
                 initiate transfer after the channel is released).
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>void isa_dmainit(int chan, u_int
             bouncebufsize)</function>
           </para>
           <para>
                 Allocate a bounce buffer for use with the specified
                 channel. The requested size of the buffer can't exceed
                 64KB. This bounce buffer will be automatically used
                 later if a transfer buffer happens to be not
                 physically contiguous or outside of the memory
                 accessible by the ISA bus or crossing the 64KB
                 boundary. If the transfers will be always done from
                 buffers which conform to these conditions (such as
                 those allocated by
                 <function>bus_dmamem_alloc()</function> with proper
                 limitations) then <function>isa_dmainit()</function>
                 does not have to be called. But it's quite convenient
                 to transfer arbitrary data using the DMA controller.
                 The bounce buffer will automatically care of the
                 scatter-gather issues.
           </para>
  <!-- <blockquote> -->
           <itemizedlist>
                 <listitem>
                   <para>
                     <emphasis>chan</emphasis> - channel number
                   </para>
                 </listitem>
                 <listitem>
                   <para>
                     <emphasis>bouncebufsize</emphasis> - size of the
                     bounce buffer in bytes
                   </para>
                 </listitem>
           </itemizedlist>
 <!-- </blockquote> -->
 <!--</para> -->
         </listitem>
 
         <listitem>
           <para>
             <function>void isa_dmastart(int flags, caddr_t addr, u_int
             nbytes, int chan)</function>
           </para>
           <para>
                 Prepare to start a DMA transfer. This function must be
                 called to set up the DMA controller before actually
                 starting transfer on the device. It checks that the
                 buffer is contiguous and falls into the ISA memory
                 range, if not then the bounce buffer is automatically
                 used. If bounce buffer is required but not set up by
                 <function>isa_dmainit()</function> or too small for
                 the requested transfer size then the system will
                 panic. In case of a write request with bounce buffer
                 the data will be automatically copied to the bounce
                 buffer.
           </para>
         </listitem>
         <listitem>
           <para>flags - a bitmask determining the type of operation to
           be done. The direction bits B_READ and B_WRITE are mutually
           exclusive.
           </para>
         <!--   <blockquote>  -->
           <itemizedlist>
             <listitem>
               <para>
                 B_READ - read from the ISA bus into memory
               </para>
             </listitem>
             <listitem>
               <para>
                 B_WRITE - write from the memory to the ISA bus
               </para>
             </listitem>
             <listitem>
               <para>
                 B_RAW - if set then the DMA controller will remember
                 the buffer and after the end of transfer will
                 automatically re-initialize itself to repeat transfer
                 of the same buffer again (of course, the driver may
                 change the data in the buffer before initiating
                 another transfer in the device). If not set then the
                 parameters will work only for one transfer, and
                 <function>isa_dmastart()</function> will have to be
                 called again before initiating the next
                 transfer. Using B_RAW makes sense only if the bounce
                 buffer is not used.
               </para>
             </listitem>
           </itemizedlist>
 <!--   </blockquote>  -->
         </listitem>
         <listitem>
           <para>
             addr - virtual address of the buffer
           </para>
         </listitem>
         <listitem>
           <para>
             nbytes - length of the buffer. Must be less or equal to
             64KB. Length of 0 is not allowed: the DMA controller will
             understand it as 64KB while the kernel code will
             understand it as 0 and that would cause unpredictable
             effects. For channels number 4 and higher the length must
             be even because these channels transfer 2 bytes at a
             time. In case of an odd length the last byte will not be
             transferred.
           </para>
         </listitem>
         <listitem>
           <para>
             chan - channel number
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>void isa_dmadone(int flags, caddr_t addr, int
             nbytes, int chan)</function>
           </para>
           <para>
             Synchronize the memory after device reports that transfer
             is done. If that was a read operation with a bounce buffer
             then the data will be copied from the bounce buffer to the
             original buffer. Arguments are the same as for
             <function>isa_dmastart()</function>. Flag B_RAW is
             permitted but it does not affect
             <function>isa_dmadone()</function> in any way.
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>int isa_dmastatus(int channel_number)</function>
           </para>
           <para>
             Returns the number of bytes left in the current transfer
             to be transferred.  In case the flag B_READ was set in
             <function>isa_dmastart()</function> the number returned
             will never be equal to zero. At the end of transfer it
             will be automatically reset back to the length of
             buffer. The normal use is to check the number of bytes
             left after the device signals that the transfer is
             completed.  If the number of bytes is not 0 then probably
             something went wrong with that transfer.
           </para>
         </listitem>
 
         <listitem>
           <para>
             <function>int isa_dmastop(int channel_number)</function>
           </para>
           <para>
             Aborts the current transfer and returns the number of
             bytes left untransferred.
           </para>
         </listitem>
        </itemizedlist>
      </sect1>
 
      <sect1>
      <title>xxx_isa_probe</title>
      <!-- Section marked up by Wylie -->
 
         <para>
           This function probes if a device is present. If the driver
           supports auto-detection of some part of device configuration
           (such as interrupt vector or memory address) this
           auto-detection must be done in this routine.
         </para>
 
         <para>
-          As for any other bus, if the device can not be detected or
+          As for any other bus, if the device cannot be detected or
           is detected but failed the self-test or some other problem
           happened then it returns a positive value of error. The
           value ENXIO must be returned if the device is not
           present. Other error values may mean other conditions. Zero
           or negative values mean success. Most of the drivers return
           zero as success.
         </para>
 
         <para>
           The negative return values are used when a PnP device
           supports multiple interfaces. For example, an older
           compatibility interface and a newer advanced interface which
           are supported by different drivers. Then both drivers would
           detect the device. The driver which returns a higher value
           in the probe routine takes precedence (in other words, the
           driver returning 0 has highest precedence, one returning -1
           is next, one returning -2 is after it and so on). In result
           the devices which support only the old interface will be
           handled by the old driver (which should return -1 from the
           probe routine) while the devices supporting the new
           interface as well will be handled by the new driver (which
           should return 0 from the probe routine).
         </para>
 
         <para>
           The device descriptor struct xxx_softc is allocated by the
           system before calling the probe routine. If the probe
           routine returns an error the descriptor will be
           automatically deallocated by the system. So if a probing
           error occurs the driver must make sure that all the
           resources it used during probe are deallocated and that
           nothing keeps the descriptor from being safely
           deallocated. If the probe completes successfully the
           descriptor will be preserved by the system and later passed
           to the routine <function>xxx_isa_attach()</function>. If a
           driver returns a negative value it can't be sure that it
           will have the highest priority and its attach routine will
           be called. So in this case it also must release all the
           resources before returning and if necessary allocate them
           again in the attach routine. When
           <function>xxx_isa_probe()</function> returns 0 releasing the
           resources before returning is also a good idea, a
           well-behaved driver should do so. But in case if there is
           some problem with releasing the resources the driver is
           allowed to keep resources between returning 0 from the probe
           routine and execution of the attach routine.
         </para>
 
         <para>
           A typical probe routine starts with getting the device
           descriptor and unit:
         </para>
 
         <programlisting>         struct xxx_softc *sc = device_get_softc(dev);
           int unit = device_get_unit(dev);
           int pnperror;
           int error = 0;
 
           sc->dev = dev; /* link it back */
           sc->unit = unit;        </programlisting>
 
         <para>
           Then check for the PnP devices. The check is carried out by
           a table containing the list of PnP IDs supported by this
           driver and human-readable descriptions of the device models
           corresponding to these IDs.
         </para>
 
         <programlisting>
         pnperror=ISA_PNP_PROBE(device_get_parent(dev), dev,
         xxx_pnp_ids); if(pnperror == ENXIO) return ENXIO;
         </programlisting>
 
         <para>
           The logic of ISA_PNP_PROBE is the following: If this card
           (device unit) was not detected as PnP then ENOENT will be
           returned. If it was detected as PnP but its detected ID does
           not match any of the IDs in the table then ENXIO is
           returned. Finally, if it has PnP support and it matches on
           of the IDs in the table, 0 is returned and the appropriate
           description from the table is set by
           <function>device_set_desc()</function>.
         </para>
 
         <para>
           If a driver supports only PnP devices then the condition
           would look like:
         </para>
 
         <programlisting>          if(pnperror != 0)
               return pnperror;        </programlisting>
 
         <para>
           No special treatment is required for the drivers which don't
           support PnP because they pass an empty PnP ID table and will
           always get ENXIO if called on a PnP card.
         </para>
 
         <para>
           The probe routine normally needs at least some minimal set
           of resources, such as I/O port number to find the card and
           probe it. Depending on the hardware the driver may be able
           to discover the other necessary resources automatically. The
           PnP devices have all the resources pre-set by the PnP
           subsystem, so the driver does not need to discover them by
           itself.
         </para>
 
         <para>
           Typically the minimal information required to get access to
           the device is the I/O port number. Then some devices allow
           to get the rest of information from the device configuration
           registers (though not all devices do that).  So first we try
           to get the port start value:
         </para>
 
         <programlisting> sc->port0 = bus_get_resource_start(dev,
         SYS_RES_IOPORT, 0 /*rid*/); if(sc->port0 == 0) return ENXIO;
         </programlisting>
 
         <para>
           The base port address is saved in the structure softc for
           future use.  If it will be used very often then calling the
           resource function each time would be prohibitively slow. If
           we don't get a port we just return an error.  Some device
           drivers can instead be clever and try to probe all the
           possible ports, like this:
         </para>
 
         <programlisting>          
           /* table of all possible base I/O port addresses for this device */
           static struct xxx_allports {
               u_short port; /* port address */
               short used; /* flag: if this port is already used by some unit */
           } xxx_allports = {
               { 0x300, 0 },
               { 0x320, 0 },
               { 0x340, 0 },
               { 0, 0 } /* end of table */
           };
 
           ...
           int port, i;
           ...
 
           port =  bus_get_resource_start(dev, SYS_RES_IOPORT, 0 /*rid*/);
           if(port !=0 ) {
               for(i=0; xxx_allports[i].port!=0; i++) {
                   if(xxx_allports[i].used || xxx_allports[i].port != port)
                       continue;
 
                   /* found it */
                   xxx_allports[i].used = 1;
                   /* do probe on a known port */
                   return xxx_really_probe(dev, port);
               }
               return ENXIO; /* port is unknown or already used */
           }
 
           /* we get here only if we need to guess the port */
           for(i=0; xxx_allports[i].port!=0; i++) {
               if(xxx_allports[i].used)
                   continue;
 
               /* mark as used - even if we find nothing at this port
                * at least we won't probe it in future
                */
                xxx_allports[i].used = 1;
 
               error = xxx_really_probe(dev, xxx_allports[i].port);
               if(error == 0) /* found a device at that port */
                   return 0;
           }
           /* probed all possible addresses, none worked */
           return ENXIO;</programlisting>
 
         <para>
           Of course, normally the driver's
           <function>identify()</function> routine should be used for
           such things. But there may be one valid reason why it may be
           better to be done in <function>probe()</function>: if this
           probe would drive some other sensitive device crazy.  The
           probe routines are ordered with consideration of the
           "sensitive" flag: the sensitive devices get probed first and
           the rest of devices later.  But the
           <function>identify()</function> routines are called before
           any probes, so they show no respect to the sensitive devices
           and may upset them.
         </para>
 
         <para>
           Now, after we got the starting port we need to set the port
           count (except for PnP devices) because the kernel does not
           have this information in the configuration file.
         </para>
 
         <programlisting>          
          if(pnperror /* only for non-PnP devices */
          &#38;&#38; bus_set_resource(dev, SYS_RES_IOPORT, 0, sc->port0, 
          XXX_PORT_COUNT)&lt;0)
              return ENXIO;</programlisting>
 
         <para>
           Finally allocate and activate a piece of port address space
           (special values of start and end mean "use those we set by
           <function>bus_set_resource()</function>"):
         </para>
 
         <programlisting>
           sc->port0_rid = 0;
           sc->port0_r = bus_alloc_resource(dev, SYS_RES_IOPORT,  
           &#38;sc->port0_rid,
               /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);
 
           if(sc->port0_r == NULL)
               return ENXIO;</programlisting>
 
         <para>
           Now having access to the port-mapped registers we can poke
           the device in some way and check if it reacts like it is
           expected to. If it does not then there is probably some
           other device or no device at all at this address.
         </para>
 
         <para>
           Normally drivers don't set up the interrupt handlers until
           the attach routine. Instead they do probes in the polling
           mode using the <function>DELAY()</function> function for
           timeout. The probe routine must never hang forever, all the
           waits for the device must be done with timeouts. If the
           device does not respond within the time it's probably broken
           or misconfigured and the driver must return error. When
           determining the timeout interval give the device some extra
           time to be on the safe side: although
           <function>DELAY()</function> is supposed to delay for the
           same amount of time on any machine it has some margin of
           error, depending on the exact CPU.
         </para>
 
         <para>
           If the probe routine really wants to check that the
           interrupts really work it may configure and probe the
           interrupts too. But that's not recommended.
         </para>
 
         <programlisting>          
           /* implemented in some very device-specific way */
           if(error = xxx_probe_ports(sc))
               goto bad; /* will deallocate the resources before returning */
         </programlisting>
 
         <para>
           The fucntion <function>xxx_probe_ports()</function> may also
           set the device description depending on the exact model of
           device it discovers.  But if there is only one supported
           device model this can be as well done in a hardcoded way.
           Of course, for the PnP devices the PnP support sets the
           description from the table automatically.
         </para>
 
 
         <programlisting>          if(pnperror)
               device_set_desc(dev, "Our device model 1234");
         </programlisting>
 
         <para>
           Then the probe routine should either discover the ranges of
           all the resources by reading the device configuration
           registers or make sure that they were set explicitly by the
           user. We will consider it with an example of on-board
           memory. The probe routine should be as non-intrusive as
           possible, so allocation and check of functionality of the
           rest of resources (besides the ports) would be better left
           to the attach routine.
         </para>
 
         <para>
           The memory address may be specified in the kernel
           configuration file or on some devices it may be
           pre-configured in non-volatile configuration registers.  If
           both sources are available and different, which one should
           be used?  Probably if the user bothered to set the address
           explicitly in the kernel configuration file they know what
           they're doing and this one should take precedence. An
           example of implementation could be:
         </para>
         <programlisting>          
           /* try to find out the config address first */
           sc->mem0_p = bus_get_resource_start(dev, SYS_RES_MEMORY, 0 /*rid*/);
           if(sc->mem0_p == 0) { /* nope, not specified by user */
               sc->mem0_p = xxx_read_mem0_from_device_config(sc);
 
 
           if(sc->mem0_p == 0)
                   /* can't get it from device config registers either */
                   goto bad;
           } else {
               if(xxx_set_mem0_address_on_device(sc) &lt; 0)
                   goto bad; /* device does not support that address */
           }
 
           /* just like the port, set the memory size,
            * for some devices the memory size would not be constant
            * but should be read from the device configuration registers instead
            * to accommodate different models of devices. Another option would
            * be to let the user set the memory size as "msize" configuration
            * resource which will be automatically handled by the ISA bus.
            */
            if(pnperror) { /* only for non-PnP devices */
               sc->mem0_size = bus_get_resource_count(dev, SYS_RES_MEMORY, 0 /*rid*/);
               if(sc->mem0_size == 0) /* not specified by user */
                   sc->mem0_size = xxx_read_mem0_size_from_device_config(sc);
 
               if(sc->mem0_size == 0) {
                   /* suppose this is a very old model of device without
                    * auto-configuration features and the user gave no preference,
                    * so assume the minimalistic case
                    * (of course, the real value will vary with the driver)
                    */
                   sc->mem0_size = 8*1024;
               }
 
               if(xxx_set_mem0_size_on_device(sc) &lt; 0)
                   goto bad; /* device does not support that size */
 
               if(bus_set_resource(dev, SYS_RES_MEMORY, /*rid*/0,
                       sc->mem0_p, sc->mem0_size)&lt;0)
                   goto bad;
           } else {
               sc->mem0_size = bus_get_resource_count(dev, SYS_RES_MEMORY, 0 /*rid*/);
           }        </programlisting>
 
         <para>
           Resources for IRQ and DRQ are easy to check by analogy.
         </para>
 
         <para>
           If all went well then release all the resources and return success.
         </para>
 
         <programlisting>          xxx_free_resources(sc);
           return 0;</programlisting>
 
         <para>
           Finally, handle the troublesome situations. All the
           resources should be deallocated before returning. We make
           use of the fact that before the structure softc is passed to
           us it gets zeroed out, so we can find out if some resource
           was allocated: then its descriptor is non-zero.
         </para>
 
         <programlisting>          bad:
 
           xxx_free_resources(sc);
           if(error)
                 return error;
           else /* exact error is unknown */
               return ENXIO;</programlisting>
 
         <para>
           That would be all for the probe routine. Freeing of
           resources is done from multiple places, so it's moved to a
           function which may look like:
         </para>
 
 <programlisting>static void
            xxx_free_resources(sc)
               struct xxx_softc *sc;
           {
               /* check every resource and free if not zero */
 
               /* interrupt handler */
               if(sc->intr_r) {
                   bus_teardown_intr(sc->dev, sc->intr_r, sc->intr_cookie);
                   bus_release_resource(sc->dev, SYS_RES_IRQ, sc->intr_rid,
                       sc->intr_r);
                   sc->intr_r = 0;
               }
 
               /* all kinds of memory maps we could have allocated */
               if(sc->data_p) {
                   bus_dmamap_unload(sc->data_tag, sc->data_map);
                   sc->data_p = 0;
               }
                if(sc->data) { /* sc->data_map may be legitimately equal to 0 */
                   /* the map will also be freed */
                   bus_dmamem_free(sc->data_tag, sc->data, sc->data_map);
                   sc->data = 0;
               }
               if(sc->data_tag) {
                   bus_dma_tag_destroy(sc->data_tag);
                   sc->data_tag = 0;
               }
 
               ... free other maps and tags if we have them ...
 
               if(sc->parent_tag) {
                   bus_dma_tag_destroy(sc->parent_tag);
                   sc->parent_tag = 0;
               }
 
               /* release all the bus resources */
               if(sc->mem0_r) {
                   bus_release_resource(sc->dev, SYS_RES_MEMORY, sc->mem0_rid,
                       sc->mem0_r);
                   sc->mem0_r = 0;
               }
               ...
               if(sc->port0_r) {
                   bus_release_resource(sc->dev, SYS_RES_IOPORT, sc->port0_rid,
                       sc->port0_r);
                   sc->port0_r = 0;
               }
           }</programlisting>
 
      </sect1>
 
      <sect1>
      <title>xxx_isa_attach</title>
      <!-- Section Marked up by Wylie -->
 
         <para>The attach routine actually connects the driver to the
         system if the probe routine returned success and the system
         had chosen to attach that driver.  If the probe routine
         returned 0 then the attach routine may expect to receive the
         device structure softc intact, as it was set by the probe
         routine. Also if the probe routine returns 0 it may expect
         that the attach routine for this device shall be called at
         some point in the future. If the probe routine returns a
         negative value then the driver may make none of these
         assumptions.
         </para>
 
         <para>The attach routine returns 0 if it completed successfully or
           error code otherwise.
         </para>
 
         <para>The attach routine starts just like the probe routine,
           with getting some frequently used data into more accessible
           variables.
         </para>
 
         <programlisting>          struct xxx_softc *sc = device_get_softc(dev);
           int unit = device_get_unit(dev);
           int error = 0;</programlisting>
 
         <para>Then allocate and activate all the necessary
           resources. Because normally the port range will be released
           before returning from probe, it has to be allocated
           again. We expect that the probe routine had properly set all
           the resource ranges, as well as saved them in the structure
           softc. If the probe routine had left some resource allocated
           then it does not need to be allocated again (which would be
           considered an error).
         </para>
 
         <programlisting>          sc->port0_rid = 0;
           sc->port0_r = bus_alloc_resource(dev, SYS_RES_IOPORT,  &#38;sc->port0_rid,
               /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);
 
           if(sc->port0_r == NULL)
                return ENXIO;
 
           /* on-board memory */
           sc->mem0_rid = 0;
           sc->mem0_r = bus_alloc_resource(dev, SYS_RES_MEMORY,  &#38;sc->mem0_rid,
               /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);
 
           if(sc->mem0_r == NULL)
                 goto bad;
 
           /* get its virtual address */
           sc->mem0_v = rman_get_virtual(sc->mem0_r);</programlisting>
 
         <para>The DMA request channel (DRQ) is allocated likewise. To
           initialize it use functions of the
           <function>isa_dma*()</function> family. For example:
         </para>
 
         <para><function>isa_dmacascade(sc->drq0);</function></para>
 
         <para>The interrupt request line (IRQ) is a bit
           special. Besides allocation the driver's interrupt handler
           should be associated with it. Historically in the old ISA
           drivers the argument passed by the system to the interrupt
           handler was the device unit number. But in modern drivers
           the convention suggests passing the pointer to structure
           softc. The important reason is that when the structures
           softc are allocated dynamically then getting the unit number
           from softc is easy while getting softc from unit number is
           difficult. Also this convention makes the drivers for
           different buses look more uniform and allows them to share
           the code: each bus gets its own probe, attach, detach and
           other bus-specific routines while the bulk of the driver
           code may be shared among them.
         </para>
 
         <programlisting>
           sc->intr_rid = 0;
           sc->intr_r = bus_alloc_resource(dev, SYS_RES_MEMORY,  &#38;sc->intr_rid,
                 /*start*/ 0, /*end*/ ~0, /*count*/ 0, RF_ACTIVE);
 
           if(sc->intr_r == NULL)
               goto bad;
 
           /*
            * XXX_INTR_TYPE is supposed to be defined depending on the type of
            * the driver, for example as INTR_TYPE_CAM for a CAM driver
            */
           error = bus_setup_intr(dev, sc->intr_r, XXX_INTR_TYPE,
               (driver_intr_t *) xxx_intr, (void *) sc, &#38;sc->intr_cookie);
           if(error)
               goto bad;
 
         </programlisting>
 
 
         <para>If the device needs to make DMA to the main memory then
           this memory should be allocated like described before:
         </para>
 
         <programlisting>          error=bus_dma_tag_create(NULL, /*alignment*/ 4,
               /*boundary*/ 0, /*lowaddr*/ BUS_SPACE_MAXADDR_24BIT,
               /*highaddr*/ BUS_SPACE_MAXADDR, /*filter*/ NULL, /*filterarg*/ NULL,
               /*maxsize*/ BUS_SPACE_MAXSIZE_24BIT,
               /*nsegments*/ BUS_SPACE_UNRESTRICTED,
               /*maxsegsz*/ BUS_SPACE_MAXSIZE_24BIT, /*flags*/ 0,
               &#38;sc->parent_tag);
           if(error)
               goto bad;
 
           /* many things get inherited from the parent tag
            * sc->data is supposed to point to the structure with the shared data,
            * for example for a ring buffer it could be:
            * struct {
            *   u_short rd_pos;
            *   u_short wr_pos;
            *   char    bf[XXX_RING_BUFFER_SIZE]
            * } *data;
            */
           error=bus_dma_tag_create(sc->parent_tag, 1,
               0, BUS_SPACE_MAXADDR, 0, /*filter*/ NULL, /*filterarg*/ NULL,
               /*maxsize*/ sizeof(* sc->data), /*nsegments*/ 1,
               /*maxsegsz*/ sizeof(* sc->data), /*flags*/ 0,
               &#38;sc->data_tag);
           if(error)
               goto bad;
 
           error = bus_dmamem_alloc(sc->data_tag, &#38;sc->data, /* flags*/ 0,
               &#38;sc->data_map);
           if(error)
                goto bad;
 
           /* xxx_alloc_callback() just saves the physical address at
            * the pointer passed as its argument, in this case &#38;sc->data_p.
            * See details in the section on bus memory mapping.
            * It can be implemented like:
            *
            * static void
            * xxx_alloc_callback(void *arg, bus_dma_segment_t *seg,
            *     int nseg, int error)
            * {
            *    *(bus_addr_t *)arg = seg[0].ds_addr;
            * }
            */
           bus_dmamap_load(sc->data_tag, sc->data_map, (void *)sc->data,
               sizeof (* sc->data), xxx_alloc_callback, (void *) &#38;sc->data_p,
               /*flags*/0);</programlisting>
 
 
         <para>After all the necessary resources are allocated the
           device should be initialized. The initialization may include
           testing that all the expected features are functional.</para>
 
         <programlisting>          if(xxx_initialize(sc) &lt; 0)
                goto bad;        </programlisting>
 
 
         <para>The bus subsystem will automatically print on the
           console the device description set by probe. But if the
           driver wants to print some extra information about the
           device it may do so, for example:</para>
 
         <programlisting>
         device_printf(dev, "has on-card FIFO buffer of %d bytes\n", sc->fifosize);
         </programlisting>
 
         <para>If the initialization routine experiences any problems
           then printing messages about them before returning error is
           also recommended.</para>
 
         <para>The final step of the attach routine is attaching the
           device to its functional subsystem in the kernel. The exact
           way to do it depends on the type of the driver: a character
           device, a block device, a network device, a CAM SCSI bus
           device and so on.</para>
 
         <para>If all went well then return success.</para>
 
         <programlisting>          error = xxx_attach_subsystem(sc);
           if(error)
               goto bad;
 
           return 0;        </programlisting>
 
         <para>Finally, handle the troublesome situations. All the
           resources should be deallocated before returning an
           error. We make use of the fact that before the structure
           softc is passed to us it gets zeroed out, so we can find out
           if some resource was allocated: then its descriptor is
           non-zero.</para>
 
         <programlisting>          bad:
 
           xxx_free_resources(sc);
           if(error)
               return error;
           else /* exact error is unknown */
               return ENXIO;</programlisting>
 
         <para>That would be all for the attach routine.</para>
 
      </sect1>
 
 
      <sect1>
        <title>xxx_isa_detach</title>
 
         <para>
           If this function is present in the driver and the driver is
           compiled as a loadable module then the driver gets the
           ability to be unloaded. This is an important feature if the
           hardware supports hot plug. But the ISA bus does not support
           hot plug, so this feature is not particularly important for
           the ISA devices. The ability to unload a driver may be
           useful when debugging it, but in many cases installation of
           the new version of the driver would be required only after
           the old version somehow wedges the system and reboot will be
           needed anyway, so the efforts spent on writing the detach
           routine may not be worth it. Another argument is that
           unloading would allow upgrading the drivers on a production
           machine seems to be mostly theoretical. Installing a new
           version of a driver is a dangerous operation which should
           never be performed on a production machine (and which is not
           permitted when the system is running in secure mode).  Still
           the detach routine may be provided for the sake of
           completeness.
         </para>
 
         <para>
           The detach routine returns 0 if the driver was successfully
           detached or the error code otherwise.
         </para>
 
         <para>
           The logic of detach is a mirror of the attach. The first
           thing to do is to detach the driver from its kernel
           subsystem. If the device is currently open then the driver
           has two choices: refuse to be detached or forcibly close and
           proceed with detach. The choice used depends on the ability
           of the particular kernel subsystem to do a forced close and
           on the preferences of the driver's author. Generally the
           forced close seems to be the preferred alternative.
         <programlisting>          struct xxx_softc *sc = device_get_softc(dev);
           int error;
 
           error = xxx_detach_subsystem(sc);
           if(error)
               return error;</programlisting>
         </para>
         <para>
           Next the driver may want to reset the hardware to some
           consistent state.  That includes stopping any ongoing
           transfers, disabling the DMA channels and interrupts to
           avoid memory corruption by the device. For most of the
           drivers this is exactly what the shutdown routine does, so
           if it is included in the driver we can as well just call it.
         </para>
         <para><function>xxx_isa_shutdown(dev);</function></para>
 
         <para>
           And finally release all the resources and return success.
         <programlisting>          xxx_free_resources(sc);
           return 0;</programlisting>
 
         </para>
      </sect1>
 
      <sect1>
        <title>xxx_isa_shutdown</title>
 
         <para>
           This routine is called when the system is about to be shut
           down. It is expected to bring the hardware to some
           consistent state. For most of the ISA devices no special
           action is required, so the function is not really necessary
           because the device will be re-initialized on reboot
           anyway. But some devices have to be shut down with a special
           procedure, to make sure that they will be properly detected
           after soft reboot (this is especially true for many devices
           with proprietary identification protocols).  In any case
           disabling DMA and interrupts in the device registers and
           stopping any ongoing transfers is a good idea. The exact
           action depends on the hardware, so we don't consider it here
           in any details.
         </para>
 
         <para>
           xxx_intr
         </para>
 
         <para>
           The interrupt handler is called when an interrupt is
           received which may be from this particular device. The ISA
           bus does not support interrupt sharing (except some special
           cases) so in practice if the interrupt handler is called
           then the interrupt almost for sure came from its
           device. Still the interrupt handler must poll the device
           registers and make sure that the interrupt was generated by
           its device. If not it should just return.
         </para>
 
         <para>
           The old convention for the ISA drivers was getting the
           device unit number as an argument. It is obsolete, and the
           new drivers receive whatever argument was specified for them
           in the attach routine when calling
           <function>bus_setup_intr()</function>. By the new convention
           it should be the pointer to the structure softc. So the
           interrupt handler commonly starts as:
         </para>
 
         <programlisting>
           static void
           xxx_intr(struct xxx_softc *sc)
           {
 
         </programlisting>
 
         <para>
           It runs at the interrupt priority level specified by the
           interrupt type parameter of
           <function>bus_setup_intr()</function>. That means that all
           the other interrupts of the same type as well as all the
           software interrupts are disabled.
         </para>
 
         <para>
           To avoid races it is commonly written as a loop:
         </para>
 
         <programlisting>
           while(xxx_interrupt_pending(sc)) {
               xxx_process_interrupt(sc);
               xxx_acknowledge_interrupt(sc);
           }        </programlisting>
 
         <para>
           The interrupt handler has to acknowledge interrupt to the
           device only but not to the interrupt controller, the system
           takes care of the latter.
         </para>
 
      </sect1>
 </chapter>
diff --git a/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml
index 72ee58a453..072aea5499 100644
--- a/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml
@@ -1,1983 +1,1983 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml,v 1.3 2001/04/13 08:09:03 murray Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml,v 1.4 2001/06/13 11:35:56 tom Exp $
 -->
 
 <chapter id="scsi">
   <title>Common Access Method SCSI Controllers</title>
 
   <para><emphasis>This chapter was written by &a.babkin;
     Modifications for the handbook made by
     &a.murray;.</emphasis></para>
 
   <sect1>
     <title>Synopsis</title>
 
     <para>This document assumes that the reader has a general
       understanding of device drivers in FreeBSD and of the SCSI
       protocol.  Much of the information in this document was
       extracted from the drivers :</para>
 
      <itemizedlist>
 
        <listitem><para>ncr (<filename>/sys/pci/ncr.c</filename>) by
          Wolfgang Stanglmeier and Stefan Esser</para></listitem>
 
        <listitem><para>sym (<filename>/sys/pci/sym.c</filename>) by
          Gerard Roudier</para></listitem> 
 
        <listitem><para>aic7xxx
          (<filename>/sys/dev/aic7xxx/aic7xxx.c</filename>) by Justin
          T. Gibbs</para></listitem>
 
      </itemizedlist>
 
    <para>and from the CAM code itself (by Justing T. Gibbs, see
      <filename>/sys/cam/*</filename>).  When some solution looked the
      most logical and was essentially verbatim extracted from the code
      by Justin Gibbs, I marked it as "recommended".</para>
 
    <para>The document is illustrated with examples in
      pseudo-code. Although sometimes the examples have many details
      and look like real code, it's still pseudo-code.  It was written
      to demonstrate the concepts in an understandable way.  For a real
      driver other approaches may be more modular and efficient.  It
      also abstracts from the hardware details, as well as issues that
      would cloud the demonstrated concepts or that are supposed to be
      described in the other chapters of the developers handbook. Such
      details are commonly shown as calls to functions with descriptive
      names, comments or pseudo-statements. Fortunately real life
      full-size examples with all the details can be found in the real
      drivers.</para>
 
   </sect1>
 
   <sect1>
     <title>General architecture</title>
 
     <para>CAM stands for Common Access Method. It's a generic way to
       address the I/O buses in a SCSI-like way. This allows a
       separation of the generic device drivers from the drivers
       controlling the I/O bus: for example the disk driver becomes able
       to control disks on both SCSI, IDE, and/or any other bus so the
       disk driver portion does not have to be rewritten (or copied and
       modified) for every new I/O bus. Thus the two most important
       active entities are:</para>
 
     <itemizedlist>
       <listitem><para><emphasis>Peripheral Modules</emphasis> -  a
         driver for peripheral devices (disk, tape, CDROM,
         etc.)</para></listitem>
       <listitem><para><emphasis>SCSI Interface Modules </emphasis>(SIM)
         - a Host Bus Adapter drivers for connecting to an I/O bus such
         as SCSI or IDE.</para></listitem>
     </itemizedlist>
 
     <para>A peripheral driver receives requests from the OS, converts
       them to a sequence of SCSI commands and passes these SCSI
       commands to a SCSI Interface Module. The SCSI Interface Module
       is responsible for passing these commands to the actual hardware
       (or if the actual hardware is not SCSI but, for example, IDE
       then also converting the SCSI commands to the native commands of
       the hardware).</para>
 
     <para>Because we are interested in writing a SCSI adapter driver
       here, from this point on we will consider everything from the
       SIM standpoint.</para>
 
     <para>A typical SIM driver needs to include the following
       CAM-related header files:</para>
 
 <programlisting>#include &lt;cam/cam.h&gt;
 #include &lt;cam/cam_ccb.h&gt;
 #include &lt;cam/cam_sim.h&gt;
 #include &lt;cam/cam_xpt_sim.h&gt;
 #include &lt;cam/cam_debug.h&gt;
 #include &lt;cam/scsi/scsi_all.h&gt;</programlisting>
 
     <para>The first thing each SIM driver must do is register itself
       with the CAM subsystem. This is done during the driver's
       <function>xxx_attach()</function> function (here and further
       xxx_ is used to denote the unique driver name prefix). The
       <function>xxx_attach()</function> function itself is called by
       the system bus auto-configuration code which we don't describe
       here.</para>
 
     <para>This is achieved in multiple steps: first it's necessary to
       allocate the queue of requests associated with this SIM:</para>
 
 <programlisting>    struct cam_devq *devq;
 
     if(( devq = cam_simq_alloc(SIZE) )==NULL) {
         error; /* some code to handle the error */
     }</programlisting>
 
     <para>Here SIZE is the size of the queue to be allocated, maximal
       number of requests it could contain. It's the number of requests
       that the SIM driver can handle in parallel on one SCSI
       card. Commonly it can be calculated as:</para>
 
 <programlisting>SIZE = NUMBER_OF_SUPPORTED_TARGETS * MAX_SIMULTANEOUS_COMMANDS_PER_TARGET</programlisting>
 
     <para>Next we create a descriptor of our SIM:</para>
 
 <programlisting>    struct cam_sim *sim;
 
     if(( sim = cam_sim_alloc(action_func, poll_func, driver_name,
             softc, unit, max_dev_transactions, 
             max_tagged_dev_transactions, devq) )==NULL) {
         cam_simq_free(devq);
         error; /* some code to handle the error */
     }</programlisting>
 
     <para>Note that if we are not able to create a SIM descriptor we
       free the <structname>devq</structname> also because we can do
       nothing else with it and we want to conserve memory.</para>
 
     <para>If a SCSI card has multiple SCSI buses on it then each bus
       requires its own <structname>cam_sim</structname>
       structure.</para>
 
     <para>An interesting question is what to do if a SCSI card has
       more than one SCSI bus, do we need one
       <structname>devq</structname> structure per card or per SCSI
       bus?  The answer given in the comments to the CAM code is:
       either way, as the driver's author prefers.</para>
 
     <para>The arguments are :
       <itemizedlist>
 
         <listitem><para><function>action_func</function> - pointer to
           the driver's <function>xxx_action</function> function.
 	  <funcSynopsis><funcPrototype>
 	  <funcDef>static void
             <function>xxx_action</function>
 	  </funcDef>
 	    <paramdef>
 	      <parameter>struct cam_sim *sim</parameter>,
   	      <parameter>union ccb *ccb</parameter>
 	    </paramdef>
 	  </funcPrototype></funcSynopsis>
 	  </para></listitem>
 
         <listitem><para><function>poll_func</function> - pointer to
           the driver's <function>xxx_poll()</function>
 	  <funcSynopsis><funcPrototype>
 	  <funcDef>static void
 	    <function>xxx_poll</function>
 	  </funcDef>
 	    <paramdef>
 	      <parameter>struct cam_sim *sim</parameter>
 	    </paramdef>
 	  </funcPrototype></funcSynopsis>
 	  </para></listitem>
 
         <listitem><para>driver_name - the name of the actual driver,
           such as "ncr" or "wds"</para></listitem>
 
         <listitem><para><structName>softc</structName> - pointer to the
           driver's internal descriptor for this SCSI card. This
           pointer will be used by the driver in future to get private
           data.</para></listitem>
 
         <listitem><para>unit - the controller unit number, for example
           for controller "wds0" this number will be
           0</para></listitem>
 
         <listitem><para>max_dev_transactions - maximal number of
           simultaneous transactions per SCSI target in the non-tagged
           mode. This value will be almost universally equal to 1, with
           possible exceptions only for the non-SCSI cards. Also the
           drivers that hope to take advantage by preparing one
           transaction while another one is executed may set it to 2
           but this does not seem to be worth the
           complexity.</para></listitem>
 
         <listitem><para>max_tagged_dev_transactions - the same thing,
           but in the tagged mode.  Tags are the SCSI way to initiate
           multiple transactions on a device: each transaction is
           assigned a unique tag and the transaction is sent to the
           device. When the device completes some transaction it sends
           back the result together with the tag so that the SCSI
           adapter (and the driver) can tell which transaction was
           completed. This argument is also known as the maximal tag
           depth. It depends on the abilities of the SCSI
           adapter.</para></listitem>
       </itemizedlist>
     </para>
 
     <para>Finally we register the SCSI buses associated with our SCSI
       adapter:</para>
 
 <programlisting>    if(xpt_bus_register(sim, bus_number) != CAM_SUCCESS) {
         cam_sim_free(sim, /*free_devq*/ TRUE);
         error; /* some code to handle the error */
     }</programlisting>
 
     <para>If there is one <structName>devq</structName> structure per
       SCSI bus (i.e. we consider a card with multiple buses as
       multiple cards with one bus each) then the bus number will
       always be 0, otherwise each bus on the SCSI card should be get a
       distinct number. Each bus needs its own separate structure
       cam_sim.</para>
 
     <para>After that our controller is completely hooked to the CAM
       system. The value of <structName>devq</structName> can be
       discarded now: sim will be passed as an argument in all further
       calls from CAM and devq can be derived from it.</para>
 
     <para>CAM provides the framework for such asynchronous
       events. Some events originate from the lower levels (the SIM
       drivers), some events originate from the peripheral drivers,
       some events originate from the CAM subsystem itself.  Any driver
       can register callbacks for some types of the asynchronous
       events, so that it would be notified if these events
       occur.</para>
 
     <para>A typical example of such an event is a device reset. Each
       transaction and event identifies the devices to which it applies
       by the means of "path". The target-specific events normally
       occur during a transaction with this device. So the path from
       that transaction may be re-used to report this event (this is
       safe because the event path is copied in the event reporting
       routine but not deallocated nor passed anywhere further). Also
       it's safe to allocate paths dynamically at any time including
       the interrupt routines, although that incurs certain overhead,
       and a possible problem with this approach is that there may be
       no free memory at that time.  For a bus reset event we need to
       define a wildcard path including all devices on the bus.  So we
       can create the path for the future bus reset events in advance
       and avoid problems with the future memory shortage:</para>
 
 <programlisting>    struct cam_path *path;
 
     if(xpt_create_path(&amp;path, /*periph*/NULL,
                 cam_sim_path(sim), CAM_TARGET_WILDCARD,
                 CAM_LUN_WILDCARD) != CAM_REQ_CMP) {
         xpt_bus_deregister(cam_sim_path(sim));
         cam_sim_free(sim, /*free_devq*/TRUE);
         error; /* some code to handle the error */
     }
 
     softc->wpath = path;
     softc->sim = sim;</programlisting>
 
     <para>As you can see the path includes:</para>
 
     <itemizedlist>
       <listitem><para>ID of the peripheral driver (NULL here because we have
         none)</para></listitem>
 
       <listitem><para>ID of the SIM driver
         (<function>cam_sim_path(sim)</function>)</para></listitem>
 
       <listitem><para>SCSI target number of the device (CAM_TARGET_WILDCARD
         means "all devices")</para></listitem>
 
       <listitem><para>SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means
         "all LUNs")</para></listitem>
     </itemizedlist>
 
     <para>If the driver can't allocate this path it won't be able to
       work normally, so in that case we dismantle that SCSI
       bus.</para>
 
     <para>And we save the path pointer in the
       <structName>softc</structName> structure for future use. After
       that we save the value of sim (or we can also discard it on the
       exit from <function>xxx_probe()</function> if we wish).</para>
 
     <para>That's all for a minimalistic initialization. To do things
       right there is one more issue left. </para>
 
     <para>For a SIM driver there is one particularly interesting
       event: when a target device is considered lost. In this case
       resetting the SCSI negotiations with this device may be a good
       idea. So we register a callback for this event with CAM. The
       request is passed to CAM by requesting CAM action on a CAM
       control block for this type of request:</para>
 
 <programlisting>    struct ccb_setasync csa;
 
     xpt_setup_ccb(&amp;csa.ccb_h, path, /*priority*/5);
     csa.ccb_h.func_code = XPT_SASYNC_CB;
     csa.event_enable = AC_LOST_DEVICE;
     csa.callback = xxx_async;
     csa.callback_arg = sim;
     xpt_action((union ccb *)&amp;csa);</programlisting>
 
     <para>Now we take a look at the <function>xxx_action()</function>
       and <function>xxx_poll()</function> driver entry points.</para>
 
     <para>
     <funcSynopsis><funcPrototype>
       <funcDef>static void
       <function>xxx_action</function>
       </funcDef>
       <paramdef>
         <parameter>struct cam_sim *sim</parameter>,
         <parameter>union ccb *ccb</parameter>
       </paramdef>
     </funcPrototype></funcSynopsis>
     </para>
 
     <para>Do some action on request of the CAM subsystem. Sim
       describes the SIM for the request, CCB is the request
       itself. CCB stands for "CAM Control Block". It is a union of
       many specific instances, each describing arguments for some type
       of transactions. All of these instances share the CCB header
       where the common part of arguments is stored.</para>
 
     <para>CAM supports the SCSI controllers working in both initiator
       ("normal") mode and target (simulating a SCSI device) mode. Here
       we only consider the part relevant to the initiator mode.</para>
 
     <para>There are a few function and macros (in other words,
       methods) defined to access the public data in the struct sim:</para>
 
     <itemizedlist>
       <listitem><para><function>cam_sim_path(sim)</function> - the
       path ID (see above)</para></listitem>
 
       <listitem><para><function>cam_sim_name(sim)</function> - the
       name of the sim</para></listitem>
 
       <listitem><para><function>cam_sim_softc(sim)</function> - the
       pointer to the softc (driver private data)
       structure</para></listitem>
 
       <listitem><para><function> cam_sim_unit(sim)</function> - the
       unit number</para></listitem>
 
       <listitem><para><function> cam_sim_bus(sim)</function> - the bus
       ID</para></listitem>
     </itemizedlist>
 
     <para>To identify the device, <function>xxx_action()</function> can
       get the unit number and pointer to its structure softc using
       these functions.</para>
 
     <para>The type of request is stored in
       <structField>ccb-&gt;ccb_h.func_code</structField>. So generally
       <function>xxx_action()</function> consists of a big
       switch:</para>
 
 <programlisting>    struct xxx_softc *softc = (struct xxx_softc *) cam_sim_softc(sim);
     struct ccb_hdr *ccb_h = &amp;ccb->ccb_h;
     int unit = cam_sim_unit(sim);
     int bus = cam_sim_bus(sim);
 
     switch(ccb_h->func_code) {
     case ...:
         ...
     default:
         ccb_h->status = CAM_REQ_INVALID;
         xpt_done(ccb);
         break;
     }</programlisting>
 
     <para>As can be seen from the default case (if an unknown command
       was received) the return code of the command is set into
       <structField>ccb-&gt;ccb_h.status</structField> and the completed
       CCB is returned back to CAM by calling
       <function>xpt_done(ccb)</function>. </para>
 
     <para><function>xpt_done()</function> does not have to be called
       from <function>xxx_action()</function>: For example an I/O
       request may be enqueued inside the SIM driver and/or its SCSI
       controller.  Then when the device would post an interrupt
       signaling that the processing of this request is complete
       <function>xpt_done()</function> may be called from the interrupt
       handling routine.</para>
 
     <para>Actually, the CCB status is not only assigned as a return
       code but a CCB has some status all the time. Before CCB is
       passed to the <function>xxx_action()</function> routine it gets
       the status CCB_REQ_INPROG meaning that it's in progress.  There
       are a surprising number of status values defined in
       <filename>/sys/cam/cam.h</filename> which should be able to
       represent the status of a request in great detail.  More
       interesting yet, the status is in fact a "bitwise or" of an
       enumerated status value (the lower 6 bits) and possible
       additional flag-like bits (the upper bits).  The enumerated
       values will be discussed later in more detail.  The summary of
       them can be found in the Errors Summary section.  The possible
       status flags are:</para>
 
     <itemizedlist>
 
       <listitem><para><emphasis>CAM_DEV_QFRZN</emphasis> - if the
         SIM driver gets a serious error (for example, the device does
         not respond to the selection or breaks the SCSI protocol) when
         processing a CCB it should freeze the request queue by calling
         <function>xpt_freeze_simq()</function>, return the other
         enqueued but not processed yet CCBs for this device back to
         the CAM queue, then set this flag for the troublesome CCB and
         call <function>xpt_done()</function>. This flag causes the CAM
         subsystem to unfreeze the queue after it handles the
         error.</para></listitem>
 
       <listitem><para><emphasis>CAM_AUTOSNS_VALID</emphasis> - if
         the device returned an error condition and the flag
         CAM_DIS_AUTOSENSE is not set in CCB the SIM driver must
         execute the REQUEST SENSE command automatically to extract the
         sense (extended error information) data from the device. If
         this attempt was successful the sense data should be saved in
         the CCB and this flag set.</para></listitem>
 
       <listitem><para><emphasis>CAM_RELEASE_SIMQ</emphasis> - like
         CAM_DEV_QFRZN but used in case there is some problem (or
         resource shortage) with the SCSI controller itself. Then all
         the future requests to the controller should be stopped by
         <function>xpt_freeze_simq()</function>.  The controller queue
         will be restarted after the SIM driver overcomes the shortage
         and informs CAM by returning some CCB with this flag
         set.</para></listitem>
 
       <listitem><para><emphasis>CAM_SIM_QUEUED</emphasis> - when SIM
         puts a CCB into its request queue this flag should be set (and
         removed when this CCB gets dequeued before being returned back
         to CAM). This flag is not used anywhere in the CAM code now,
         so its purpose is purely diagnostic.</para></listitem>
 
     </itemizedlist>
 
     <para>The function <function>xxx_action()</function> is not
       allowed to sleep, so all the synchronization for resource access
       must be done using SIM or device queue freezing.  Besides the
       aforementioned flags the CAM subsystem provides functions
       <function>xpt_selease_simq()</function> and
       <function>xpt_release_devq()</function> to unfreeze the queues
       directly, without passing a CCB to CAM.</para>
 
     <para>The CCB header contains the following fields:</para>
 
     <itemizedlist>
 
       <listitem><para><emphasis>path</emphasis> - path ID for the
       request</para></listitem>
 
       <listitem><para><emphasis>target_id</emphasis> - target device
       ID for the request</para></listitem>
 
       <listitem><para><emphasis>target_lun</emphasis> - LUN ID of
       the target device</para></listitem>
 
       <listitem><para><emphasis>timeout</emphasis> - timeout
       interval for this command, in milliseconds</para></listitem>
 
       <listitem><para><emphasis>timeout_ch</emphasis> - a
       convenience place for the SIM driver to store the timeout handle
       (the CAM subsystem itself does not make any assumptions about
       it)</para></listitem>
 
       <listitem><para><emphasis>flags</emphasis> - various bits of
       information about the request spriv_ptr0, spriv_ptr1 - fields
       reserved for private use by the SIM driver (such as linking to
       the SIM queues or SIM private control blocks); actually, they
       exist as unions: spriv_ptr0 and spriv_ptr1 have the type (void
       *), spriv_field0 and spriv_field1 have the type unsigned long,
       sim_priv.entries[0].bytes and sim_priv.entries[1].bytes are byte
       arrays of the size consistent with the other incarnations of the
       union and sim_priv.bytes is one array, twice
       bigger.</para></listitem>
 
     </itemizedlist>
 
     <para>The recommended way of using the SIM private fields of CCB
       is to define some meaningful names for them and use these
       meaningful names in the driver, like:</para>
 
 <programlisting>#define ccb_some_meaningful_name    sim_priv.entries[0].bytes
 #define ccb_hcb spriv_ptr1 /* for hardware control block */</programlisting>
 
     <para>The most common initiator mode requests are:</para>
     <itemizedlist>
       <listitem><para><emphasis>XPT_SCSI_IO</emphasis> - execute an
       I/O transaction</para>
 
       <para>The instance "struct ccb_scsiio csio" of the union ccb is
         used to transfer the arguments. They are:</para>
 
       <itemizedlist>
         <listitem><para><emphasis>cdb_io</emphasis> - pointer to
           the SCSI command buffer or the buffer
   	  itself</para></listitem>
 
 	<listitem><para><emphasis>cdb_len</emphasis> - SCSI
 	  command length</para></listitem>
 
 	<listitem><para><emphasis>data_ptr</emphasis> - pointer to
 	  the data buffer (gets a bit complicated if scatter/gather is
 	  used)</para></listitem>
 
 	<listitem><para><emphasis>dxfer_len</emphasis> - length of
 	  the data to transfer</para></listitem>
 
 	<listitem><para><emphasis>sglist_cnt</emphasis> - counter
 	  of the scatter/gather segments</para></listitem>
 
 	<listitem><para><emphasis>scsi_status</emphasis> - place
 	  to return the SCSI status</para></listitem>
 
 	<listitem><para><emphasis>sense_data</emphasis> - buffer
           for the SCSI sense information if the command returns an
           error (the SIM driver is supposed to run the REQUEST SENSE
           command automatically in this case if the CCB flag
           CAM_DIS_AUTOSENSE is not set)</para></listitem>
 
 	<listitem><para><emphasis>sense_len</emphasis> - the
           length of that buffer (if it happens to be higher than size
           of sense_data the SIM driver must silently assume the
           smaller value) resid, sense_resid - if the transfer of data
           or SCSI sense returned an error these are the returned
           counters of the residual (not transferred) data. They do not
           seem to be especially meaningful, so in a case when they are
           difficult to compute (say, counting bytes in the SCSI
           controller's FIFO buffer) an approximate value will do as
           well. For a successfully completed transfer they must be set
           to zero.</para></listitem>
 
 	<listitem><para><emphasis>tag_action</emphasis> - the kind
 	  of tag to use:
 	  
 	  <itemizedlist>
 	  <listitem><para>CAM_TAG_ACTION_NONE - don't use tags for this
 	  transaction</para></listitem>
 	  <listitem><para>MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG,
 	  MSG_ORDERED_Q_TAG - value equal to the appropriate tag
 	  message (see /sys/cam/scsi/scsi_message.h); this gives only
 	  the tag type, the SIM driver must assign the tag value
 	  itself</para></listitem>
 	  </itemizedlist>
 
 	  </para></listitem>
 
       </itemizedlist>
 
       <para>The general logic of handling this request is the
         following:</para>
 
       <para>The first thing to do is to check for possible races, to
         make sure that the command did not get aborted when it was
         sitting in the queue:</para>
 
 <programlisting>    struct ccb_scsiio *csio = &amp;ccb->csio;
 
     if ((ccb_h->status &amp; CAM_STATUS_MASK) != CAM_REQ_INPROG) {
         xpt_done(ccb);
         return;
     }</programlisting>
 
       <para>Also we check that the device is supported at all by our
         controller:</para>
 
 <programlisting>    if(ccb_h->target_id > OUR_MAX_SUPPORTED_TARGET_ID
     || cch_h->target_id == OUR_SCSI_CONTROLLERS_OWN_ID) {
         ccb_h->status = CAM_TID_INVALID;
         xpt_done(ccb);
         return;
     }
     if(ccb_h->target_lun > OUR_MAX_SUPPORTED_LUN) {
         ccb_h->status = CAM_LUN_INVALID;
         xpt_done(ccb);
         return;
     }</programlisting>
 
       <para>Then allocate whatever data structures (such as
         card-dependent hardware control block) we need to process this
         request. If we can't then freeze the SIM queue and remember
         that we have a pending operation, return the CCB back and ask
         CAM to re-queue it. Later when the resources become available
         the SIM queue must be unfrozen by returning a ccb with the
         CAM_SIMQ_RELEASE bit set in its status. Otherwise, if all went
         well, link the CCB with the hardware control block (HCB) and
         mark it as queued.</para>
 
 <programlisting>    struct xxx_hcb *hcb = allocate_hcb(softc, unit, bus);
 
     if(hcb == NULL) {
         softc->flags |= RESOURCE_SHORTAGE;
         xpt_freeze_simq(sim, /*count*/1);
         ccb_h->status = CAM_REQUEUE_REQ;
         xpt_done(ccb);
         return;
     }
 
     hcb->ccb = ccb; ccb_h->ccb_hcb = (void *)hcb;
     ccb_h->status |= CAM_SIM_QUEUED;</programlisting>
 
       <para>Extract the target data from CCB into the hardware control
         block. Check if we are asked to assign a tag and if yes then
         generate an unique tag and build the SCSI tag messages. The
         SIM driver is also responsible for negotiations with the
         devices to set the maximal mutually supported bus width,
         synchronous rate and offset.</para>
 
 <programlisting>    hcb->target = ccb_h->target_id; hcb->lun = ccb_h->target_lun;
     generate_identify_message(hcb);
     if( ccb_h->tag_action != CAM_TAG_ACTION_NONE )
         generate_unique_tag_message(hcb, ccb_h->tag_action);
     if( !target_negotiated(hcb) )
         generate_negotiation_messages(hcb);</programlisting>
 
       <para>Then set up the SCSI command. The command storage may be
         specified in the CCB in many interesting ways, specified by
         the CCB flags.  The command buffer can be contained in CCB or
         pointed to, in the latter case the pointer may be physical or
         virtual. Since the hardware commonly needs physical address we
         always convert the address to the physical one.</para>
 
       <para>A NOT-QUITE RELATED NOTE: Normally this is done by a call
         to vtophys(), but for the PCI device (which account for most
         of the SCSI controllers now) drivers' portability to the Alpha
         architecture the conversion must be done by vtobus() instead
         due to special Alpha quirks.  [IMHO it would be much better to
         have two separate functions, vtop() and ptobus() then vtobus()
         would be a simple superposition of them.]  In case if a
         physical address is requested it's OK to return the CCB with
         the status CAM_REQ_INVALID, the current drivers do that.  But
         it's also possible to compile the Alpha-specific piece of
         code, as in this example (there should be a more direct way to
         do that, without conditional compilation in the drivers). If
         necessary a physical address can be also converted or mapped
         back to a virtual address but with big pain, so we don't do
         that.</para>
 
 <programlisting>    if(ccb_h->flags &amp; CAM_CDB_POINTER) {
         /* CDB is a pointer */
         if(!(ccb_h->flags &amp; CAM_CDB_PHYS)) {
             /* CDB pointer is virtual */
             hcb->cmd = vtobus(csio->cdb_io.cdb_ptr);
         } else {
             /* CDB pointer is physical */
 #if defined(__alpha__)
             hcb->cmd = csio->cdb_io.cdb_ptr | alpha_XXX_dmamap_or ;
 #else
             hcb->cmd = csio->cdb_io.cdb_ptr ;
 #endif
         }
     } else {
         /* CDB is in the ccb (buffer) */
         hcb->cmd = vtobus(csio->cdb_io.cdb_bytes);
     }
     hcb->cmdlen = csio->cdb_len;</programlisting>
 
       <para>Now it's time to set up the data. Again, the data storage
         may be specified in the CCB in many interesting ways,
         specified by the CCB flags.  First we get the direction of the
         data transfer. The simplest case is if there is no data to
         transfer:</para>
 
 <programlisting>    int dir = (ccb_h->flags &amp; CAM_DIR_MASK);
 
     if (dir == CAM_DIR_NONE)
         goto end_data;</programlisting>
 
       <para>Then we check if the data is in one chunk or in a
         scatter-gather list, and the addresses are physical or
         virtual. The SCSI controller may be able to handle only a
         limited number of chunks of limited length.  If the request
         hits this limitation we return an error. We use a special
         function to return the CCB to handle in one place the HCB
         resource shortages. The functions to add chunks are
         driver-dependent, and here we leave them without detailed
         implementation. See description of the SCSI command (CDB)
         handling for the details on the address-translation issues.
         If some variation is too difficult or impossible to implement
         with a particular card it's OK to return the status
         CAM_REQ_INVALID. Actually, it seems like the scatter-gather
         ability is not used anywhere in the CAM code now. But at least
         the case for a single non-scattered virtual buffer must be
         implemented, it's actively used by CAM.</para>
 
 <programlisting>    int rv;
     
     initialize_hcb_for_data(hcb);
 
     if((!(ccb_h->flags &amp; CAM_SCATTER_VALID)) { 
         /* single buffer */
         if(!(ccb_h->flags &amp; CAM_DATA_PHYS)) {
             rv = add_virtual_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir);
             }
         } else {
             rv = add_physical_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir);
         }
     } else {
         int i;
         struct bus_dma_segment *segs;
         segs = (struct bus_dma_segment *)csio->data_ptr;
 
         if ((ccb_h->flags &amp; CAM_SG_LIST_PHYS) != 0) {
             /* The SG list pointer is physical */
             rv = setup_hcb_for_physical_sg_list(hcb, segs, csio->sglist_cnt);
         } else if (!(ccb_h->flags &amp; CAM_DATA_PHYS)) {
             /* SG buffer pointers are virtual */
             for (i = 0; i < csio->sglist_cnt; i++) {
                 rv = add_virtual_chunk(hcb, segs[i].ds_addr, 
                     segs[i].ds_len, dir);
                 if (rv != CAM_REQ_CMP)
                     break;
             }
         } else {
             /* SG buffer pointers are physical */
             for (i = 0; i < csio->sglist_cnt; i++) {
                 rv = add_physical_chunk(hcb, segs[i].ds_addr, 
                     segs[i].ds_len, dir);
                 if (rv != CAM_REQ_CMP)
                     break;
             }
         }
     }
     if(rv != CAM_REQ_CMP) {
         /* we expect that add_*_chunk() functions return CAM_REQ_CMP
          * if they added a chunk successfully, CAM_REQ_TOO_BIG if
          * the request is too big (too many bytes or too many chunks),
          * CAM_REQ_INVALID in case of other troubles
          */
         free_hcb_and_ccb_done(hcb, ccb, rv);
         return;
     }
     end_data:</programlisting>
 
     <para>If disconnection is disabled for this CCB we pass this
       information to the hcb:</para>
 
 <programlisting>    if(ccb_h->flags &amp; CAM_DIS_DISCONNECT)
         hcb_disable_disconnect(hcb);</programlisting>
 
     <para>If the controller is able to run REQUEST SENSE command all
       by itself then the value of the flag CAM_DIS_AUTOSENSE should
       also be passed to it, to prevent automatic REQUEST SENSE if the
       CAM subsystem does not want it.</para>
 
     <para>The only thing left is to set up the timeout, pass our hcb
       to the hardware and return, the rest will be done by the
       interrupt handler (or timeout handler).</para>
 
 <programlisting>    ccb_h->timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, 
         (ccb_h->timeout * hz) / 1000); /* convert milliseconds to ticks */
     put_hcb_into_hardware_queue(hcb);
     return;</programlisting>
 
     <para>And here is a possible implementation of the function
     returning CCB:</para>
 
 <programlisting>    static void
     free_hcb_and_ccb_done(struct xxx_hcb *hcb, union ccb *ccb, u_int32_t status)
     {
         struct xxx_softc *softc = hcb->softc;
 
         ccb->ccb_h.ccb_hcb = 0;
         if(hcb != NULL) {
             untimeout(xxx_timeout, (caddr_t) hcb, ccb->ccb_h.timeout_ch);
             /* we're about to free a hcb, so the shortage has ended */
             if(softc->flags &amp; RESOURCE_SHORTAGE)  {
                 softc->flags &amp;= ~RESOURCE_SHORTAGE;
                 status |= CAM_RELEASE_SIMQ;
             }
             free_hcb(hcb); /* also removes hcb from any internal lists */
         }
         ccb->ccb_h.status = status | 
             (ccb->ccb_h.status &amp; ~(CAM_STATUS_MASK|CAM_SIM_QUEUED));
         xpt_done(ccb);
     }</programlisting>
     </listitem>
 
     <listitem><para><emphasis>XPT_RESET_DEV</emphasis> - send the SCSI "BUS
     DEVICE RESET" message to a device</para>
 
     <para>There is no data transferred in CCB except the header and
       the most interesting argument of it is target_id. Depending on
       the controller hardware a hardware control block just like for
       the XPT_SCSI_IO request may be constructed (see XPT_SCSI_IO
       request description) and sent to the controller or the SCSI
       controller may be immediately programmed to send this RESET
       message to the device or this request may be just not supported
       (and return the status CAM_REQ_INVALID).  Also on completion of
       the request all the disconnected transactions for this target
       must be aborted (probably in the interrupt routine).</para>
 
     <para>Also all the current negotiations for the target are lost on
       reset, so they might be cleaned too. Or they clearing may be
       deferred, because anyway the target would request re-negotiation
       on the next transaction.</para></listitem>
 
     <listitem><para><emphasis>XPT_RESET_BUS</emphasis> - send the RESET signal
       to the SCSI bus</para>
 
     <para>No arguments are passed in the CCB, the only interesting
       argument is the SCSI bus indicated by the struct sim
       pointer.</para>
 
     <para>A minimalistic implementation would forget the SCSI
       negotiations for all the devices on the bus and return the
       status CAM_REQ_CMP.</para>
 
     <para>The proper implementation would in addition actually reset
       the SCSI bus (possible also reset the SCSI controller) and mark
       all the CCBs being processed, both those in the hardware queue
       and those being disconnected, as done with the status
       CAM_SCSI_BUS_RESET. Like:</para>
 
 <programlisting>    int targ, lun;
     struct xxx_hcb *h, *hh;
     struct ccb_trans_settings neg;
     struct cam_path *path;
 
     /* The SCSI bus reset may take a long time, in this case its completion
      * should be checked by interrupt or timeout. But for simplicity
      * we assume here that it's really fast.
      */
     reset_scsi_bus(softc);
 
     /* drop all enqueued CCBs */
     for(h = softc->first_queued_hcb; h != NULL; h = hh) {
         hh = h->next;
         free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
     }
 
     /* the clean values of negotiations to report */
     neg.bus_width = 8;
     neg.sync_period = neg.sync_offset = 0;
     neg.valid = (CCB_TRANS_BUS_WIDTH_VALID
         | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID);
 
     /* drop all disconnected CCBs and clean negotiations  */
     for(targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) {
         clean_negotiations(softc, targ);
 
         /* report the event if possible */
         if(xpt_create_path(&amp;path, /*periph*/NULL,
                 cam_sim_path(sim), targ,
                 CAM_LUN_WILDCARD) == CAM_REQ_CMP) {
             xpt_async(AC_TRANSFER_NEG, path, &amp;neg);
             xpt_free_path(path);
         }
 
         for(lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) 
             for(h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) {
                 hh=h->next;
                 free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
             }
     }
 
     ccb->ccb_h.status = CAM_REQ_CMP;
     xpt_done(ccb);
 
     /* report the event */
     xpt_async(AC_BUS_RESET, softc->wpath, NULL);
     return;</programlisting>
 
     <para>Implementing the SCSI bus reset as a function may be a good
       idea because it would be re-used by the timeout function as a
       last resort if the things go wrong.</para></listitem>
 
     <listitem><para><emphasis>XPT_ABORT</emphasis> - abort the specified
       CCB</para>
 
     <para>The arguments are transferred in the instance "struct
       ccb_abort cab" of the union ccb. The only argument field in it
       is:</para>
 
     <para><emphasis>abort_ccb</emphasis> - pointer to the CCB to be
       aborted</para>
 
     <para>If the abort is not supported just return the status
       CAM_UA_ABORT.  This is also the easy way to minimally implement
       this call, return CAM_UA_ABORT in any case.</para>
 
     <para>The hard way is to implement this request honestly. First
       check that abort applies to a SCSI transaction:</para>
 
 <programlisting>    struct ccb *abort_ccb;
     abort_ccb = ccb->cab.abort_ccb;
 
     if(abort_ccb->ccb_h.func_code != XPT_SCSI_IO) {
         ccb->ccb_h.status = CAM_UA_ABORT;
         xpt_done(ccb);
         return;
     }</programlisting>
 
     <para>Then it's necessary to find this CCB in our queue. This can
       be done by walking the list of all our hardware control blocks
       in search for one associated with this CCB:</para>
 
 <programlisting>    struct xxx_hcb *hcb, *h;
 
     hcb = NULL;
 
     /* We assume that softc->first_hcb is the head of the list of all
      * HCBs associated with this bus, including those enqueued for 
      * processing, being processed by hardware and disconnected ones.
      */
     for(h = softc->first_hcb; h != NULL; h = h->next) {
         if(h->ccb == abort_ccb) {
             hcb = h;
             break;
         }
     }
 
     if(hcb == NULL) {
         /* no such CCB in our queue */
         ccb->ccb_h.status = CAM_PATH_INVALID; 
         xpt_done(ccb);
         return;
     }
 
     hcb=found_hcb;</programlisting>
 
     <para>Now we look at the current processing status of the HCB. It
       may be either sitting in the queue waiting to be sent to the
       SCSI bus, being transferred right now, or disconnected and
       waiting for the result of the command, or actually completed by
       hardware but not yet marked as done by software.  To make sure
       that we don't get in any races with hardware we mark the HCB as
       being aborted, so that if this HCB is about to be sent to the
       SCSI bus the SCSI controller will see this flag and skip
       it.</para>
 
 <programlisting>    int hstatus;
 
     /* shown as a function, in case special action is needed to make
      * this flag visible to hardware 
      */
     set_hcb_flags(hcb, HCB_BEING_ABORTED);
 
     abort_again:
 
     hstatus = get_hcb_status(hcb);
     switch(hstatus) {
     case HCB_SITTING_IN_QUEUE:
         remove_hcb_from_hardware_queue(hcb);
         /* FALLTHROUGH */
     case HCB_COMPLETED:
         /* this is an easy case */
         free_hcb_and_ccb_done(hcb, abort_ccb, CAM_REQ_ABORTED);
         break;</programlisting>
 
     <para>If the CCB is being transferred right now we would like to
       signal to the SCSI controller in some hardware-dependent way
       that we want to abort the current transfer. The SCSI controller
       would set the SCSI ATTENTION signal and when the target responds
       to it send an ABORT message. We also reset the timeout to make
       sure that the target is not sleeping forever.  If the command
       would not get aborted in some reasonable time like 10 seconds
       the timeout routine would go ahead and reset the whole SCSI bus.
       Because the command will be aborted in some reasonable time we
       can just return the abort request now as successfully completed,
       and mark the aborted CCB as aborted (but not mark it as done
       yet).</para>
 
 <programlisting>    case HCB_BEING_TRANSFERRED:
         untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch);
         abort_ccb->ccb_h.timeout_ch = 
             timeout(xxx_timeout, (caddr_t) hcb, 10 * hz);
         abort_ccb->ccb_h.status = CAM_REQ_ABORTED;
         /* ask the controller to abort that HCB, then generate
          * an interrupt and stop
          */
         if(signal_hardware_to_abort_hcb_and_stop(hcb) < 0) {
             /* oops, we missed the race with hardware, this transaction
              * got off the bus before we aborted it, try again */
             goto abort_again;
         }
 
         break;</programlisting>
 
     <para>If the CCB is in the list of disconnected then set it up as
       an abort request and re-queue it at the front of hardware
       queue. Reset the timeout and report the abort request to be
       completed.</para>
 
 <programlisting>    case HCB_DISCONNECTED:
         untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch);
         abort_ccb->ccb_h.timeout_ch = 
             timeout(xxx_timeout, (caddr_t) hcb, 10 * hz);
         put_abort_message_into_hcb(hcb);
         put_hcb_at_the_front_of_hardware_queue(hcb);
         break;
     }
     ccb->ccb_h.status = CAM_REQ_CMP;
     xpt_done(ccb);
     return;</programlisting>
 
     <para>That's all for the ABORT request, although there is one more
       issue.  Because the ABORT message cleans all the ongoing
       transactions on a LUN we have to mark all the other active
       transactions on this LUN as aborted.  That should be done in the
       interrupt routine, after the transaction gets aborted.</para>
 
     <para>Implementing the CCB abort as a function may be quite a good
       idea, this function can be re-used if an I/O transaction times
       out. The only difference would be that the timed out transaction
       would return the status CAM_CMD_TIMEOUT for the timed out
       request. Then the case XPT_ABORT would be small, like
       that:</para>
 
 <programlisting>    case XPT_ABORT:
         struct ccb *abort_ccb;
         abort_ccb = ccb->cab.abort_ccb;
 
         if(abort_ccb->ccb_h.func_code != XPT_SCSI_IO) {
             ccb->ccb_h.status = CAM_UA_ABORT;
             xpt_done(ccb);
             return;
         }
         if(xxx_abort_ccb(abort_ccb, CAM_REQ_ABORTED) < 0)
             /* no such CCB in our queue */
             ccb->ccb_h.status = CAM_PATH_INVALID; 
         else
             ccb->ccb_h.status = CAM_REQ_CMP;
         xpt_done(ccb);
         return;</programlisting>
     </listitem>
 
     <listitem><para><emphasis>XPT_SET_TRAN_SETTINGS</emphasis> - explicitly
       set values of SCSI transfer settings</para>
 
     <para>The arguments are transferred in the instance "struct ccb_trans_setting cts" 
 of the union ccb:</para>
 
     <itemizedlist>
       <listitem><para><emphasis>valid</emphasis> - a bitmask showing
       which settings should be updated:</para></listitem>
 
       <listitem><para><emphasis>CCB_TRANS_SYNC_RATE_VALID</emphasis>
       - synchronous transfer rate</para></listitem>
 
       <listitem><para><emphasis>CCB_TRANS_SYNC_OFFSET_VALID</emphasis>
       - synchronous offset</para></listitem>
 
       <listitem><para><emphasis>CCB_TRANS_BUS_WIDTH_VALID</emphasis>
       - bus width</para></listitem>
 
       <listitem><para><emphasis>CCB_TRANS_DISC_VALID</emphasis> -
       set enable/disable disconnection</para></listitem> 
 
       <listitem><para><emphasis>CCB_TRANS_TQ_VALID</emphasis> - set
       enable/disable tagged queuing</para></listitem> 
 
       <listitem><para><emphasis>flags</emphasis> - consists of two
       parts, binary arguments and identification of
       sub-operations.  The binary arguments are :</para>
       <itemizedlist>
         <listitem><para><emphasis>CCB_TRANS_DISC_ENB</emphasis> - enable disconnection</para></listitem>
 	<listitem><para><emphasis>CCB_TRANS_TAG_ENB</emphasis> -
 	enable tagged queuing</para></listitem>
       </itemizedlist>
       </listitem>
 
       <listitem><para>the sub-operations are:</para>
       <itemizedlist>
         <listitem><para><emphasis>CCB_TRANS_CURRENT_SETTINGS</emphasis>
         - change the current negotiations</para></listitem>
 
 	<listitem><para><emphasis>CCB_TRANS_USER_SETTINGS</emphasis>
         - remember the desired user values sync_period, sync_offset -
         self-explanatory, if sync_offset==0 then the asynchronous mode
         is requested bus_width - bus width, in bits (not
         bytes)</para></listitem>
       </itemizedlist>
       </listitem>
 
     </itemizedlist>
 
     <para>Two sets of negotiated parameters are supported, the user
       settings and the current settings. The user settings are not
       really used much in the SIM drivers, this is mostly just a piece
       of memory where the upper levels can store (and later recall)
       its ideas about the parameters.  Setting the user parameters
       does not cause re-negotiation of the transfer rates. But when
       the SCSI controller does a negotiation it must never set the
       values higher than the user parameters, so it's essentially the
       top boundary.</para>
 
     <para>The current settings are, as the name says,
       current. Changing them means that the parameters must be
       re-negotiated on the next transfer.  Again, these "new current
       settings" are not supposed to be forced on the device, just they
       are used as the initial step of negotiations.  Also they must be
       limited by actual capabilities of the SCSI controller: for
       example, if the SCSI controller has 8-bit bus and the request
       asks to set 16-bit wide transfers this parameter must be
       silently truncated to 8-bit transfers before sending it to the
       device.</para>
 
     <para>One caveat is that the bus width and synchronous parameters
       are per target while the disconnection and tag enabling
       parameters are per lun.</para>
 
     <para>The recommended implementation is to keep 3 sets of
       negotiated (bus width and synchronous transfer)
       parameters:</para>
 
     <itemizedlist>
       <listitem><para><emphasis>user</emphasis> - the user set, as
       above</para></listitem>
 
       <listitem><para><emphasis>current</emphasis> - those actually
       in effect</para></listitem>
 
       <listitem><para><emphasis>goal</emphasis> - those requested by
       setting of the "current" parameters</para></listitem>
     </itemizedlist>
 
     <para>The code looks like:</para>
 
 <programlisting>    struct ccb_trans_settings *cts;
     int targ, lun;
     int flags;
 
     cts = &amp;ccb->cts;
     targ = ccb_h->target_id;
     lun = ccb_h->target_lun;
     flags = cts->flags;
     if(flags &amp; CCB_TRANS_USER_SETTINGS) {
         if(flags &amp; CCB_TRANS_SYNC_RATE_VALID)
             softc->user_sync_period[targ] = cts->sync_period;
         if(flags &amp; CCB_TRANS_SYNC_OFFSET_VALID)
             softc->user_sync_offset[targ] = cts->sync_offset;
         if(flags &amp; CCB_TRANS_BUS_WIDTH_VALID)
             softc->user_bus_width[targ] = cts->bus_width;
 
         if(flags &amp; CCB_TRANS_DISC_VALID) {
             softc->user_tflags[targ][lun] &amp;= ~CCB_TRANS_DISC_ENB;
             softc->user_tflags[targ][lun] |= flags &amp; CCB_TRANS_DISC_ENB;
         }
         if(flags &amp; CCB_TRANS_TQ_VALID) {
             softc->user_tflags[targ][lun] &amp;= ~CCB_TRANS_TQ_ENB;
             softc->user_tflags[targ][lun] |= flags &amp; CCB_TRANS_TQ_ENB;
         }
     }
     if(flags &amp; CCB_TRANS_CURRENT_SETTINGS) {
         if(flags &amp; CCB_TRANS_SYNC_RATE_VALID)
             softc->goal_sync_period[targ] = 
                 max(cts->sync_period, OUR_MIN_SUPPORTED_PERIOD);
         if(flags &amp; CCB_TRANS_SYNC_OFFSET_VALID)
             softc->goal_sync_offset[targ] = 
                 min(cts->sync_offset, OUR_MAX_SUPPORTED_OFFSET);
         if(flags &amp; CCB_TRANS_BUS_WIDTH_VALID)
             softc->goal_bus_width[targ] = min(cts->bus_width, OUR_BUS_WIDTH);
 
         if(flags &amp; CCB_TRANS_DISC_VALID) {
             softc->current_tflags[targ][lun] &amp;= ~CCB_TRANS_DISC_ENB;
             softc->current_tflags[targ][lun] |= flags &amp; CCB_TRANS_DISC_ENB;
         }
         if(flags &amp; CCB_TRANS_TQ_VALID) {
             softc->current_tflags[targ][lun] &amp;= ~CCB_TRANS_TQ_ENB;
             softc->current_tflags[targ][lun] |= flags &amp; CCB_TRANS_TQ_ENB;
         }
     }
     ccb->ccb_h.status = CAM_REQ_CMP;
     xpt_done(ccb);
     return;</programlisting>
 
     <para>Then when the next I/O request will be processed it will
       check if it has to re-negotiate, for example by calling the
       function target_negotiated(hcb).  It can be implemented like
       this:</para>
 
 <programlisting>    int
     target_negotiated(struct xxx_hcb *hcb)
     {
         struct softc *softc = hcb->softc;
         int targ = hcb->targ;
 
         if( softc->current_sync_period[targ] != softc->goal_sync_period[targ]
         || softc->current_sync_offset[targ] != softc->goal_sync_offset[targ]
         || softc->current_bus_width[targ] != softc->goal_bus_width[targ] )
             return 0; /* FALSE */
         else
             return 1; /* TRUE */
     }</programlisting>
 
     <para>After the values are re-negotiated the resulting values must
       be assigned to both current and goal parameters, so for future
       I/O transactions the current and goal parameters would be the
       same and <function>target_negotiated()</function> would return
       TRUE. When the card is initialized (in
       <function>xxx_attach()</function>) the current negotiation
       values must be initialized to narrow asynchronous mode, the goal
       and current values must be initialized to the maximal values
       supported by controller.</para></listitem>
 
     <listitem><para><emphasis>XPT_GET_TRAN_SETTINGS</emphasis> - get values of
     SCSI transfer settings</para>
 
     <para>This operations is the reverse of
       XPT_SET_TRAN_SETTINGS. Fill up the CCB instance "struct
       ccb_trans_setting cts" with data as requested by the flags
       CCB_TRANS_CURRENT_SETTINGS or CCB_TRANS_USER_SETTINGS (if both
       are set then the existing drivers return the current
       settings). Set all the bits in the valid field.</para></listitem>
 
     <listitem><para><emphasis>XPT_CALC_GEOMETRY</emphasis> - calculate logical
       (BIOS) geometry of the disk</para>
 
     <para>The arguments are transferred in the instance "struct
       ccb_calc_geometry ccg" of the union ccb:</para>
 
     <itemizedlist>
 
       <listitem><para><emphasis>block_size</emphasis> - input, block
       (A.K.A sector) size in bytes</para></listitem>
 
       <listitem><para><emphasis>volume_size</emphasis> - input,
       volume size in bytes</para></listitem>
 
       <listitem><para><emphasis>cylinders</emphasis> - output,
       logical cylinders</para></listitem>
 
       <listitem><para><emphasis>heads</emphasis> - output, logical
       heads</para></listitem>
 
       <listitem><para><emphasis>secs_per_track</emphasis> - output,
       logical sectors per track</para></listitem>
 
     </itemizedlist>
 
     <para>If the returned geometry differs much enough from what the
       SCSI controller BIOS thinks and a disk on this SCSI controller
       is used as bootable the system may not be able to boot. The
       typical calculation example taken from the aic7xxx driver
       is:</para>
 
 <programlisting>    struct    ccb_calc_geometry *ccg;
     u_int32_t size_mb;
     u_int32_t secs_per_cylinder;
     int   extended;
 
     ccg = &amp;ccb->ccg;
     size_mb = ccg->volume_size
         / ((1024L * 1024L) / ccg->block_size);
     extended = check_cards_EEPROM_for_extended_geometry(softc);
 
     if (size_mb > 1024 &amp;&amp; extended) {
         ccg->heads = 255;
         ccg->secs_per_track = 63;
     } else {
         ccg->heads = 64;
         ccg->secs_per_track = 32;
     }
     secs_per_cylinder = ccg->heads * ccg->secs_per_track;
     ccg->cylinders = ccg->volume_size / secs_per_cylinder;
     ccb->ccb_h.status = CAM_REQ_CMP;
     xpt_done(ccb);
     return;</programlisting>
 
     <para>This gives the general idea, the exact calculation depends
       on the quirks of the particular BIOS. If BIOS provides no way
       set the "extended translation" flag in EEPROM this flag should
       normally be assumed equal to 1. Other popular geometries
       are:</para>
 
 <programlisting>    128 heads, 63 sectors - Symbios controllers
     16 heads, 63 sectors - old controllers</programlisting>
 
     <para>Some system BIOSes and SCSI BIOSes fight with each other
       with variable success, for example a combination of Symbios
       875/895 SCSI and Phoenix BIOS can give geometry 128/63 after
       power up and 255/63 after a hard reset or soft reboot.</para>
     </listitem>
 
     <listitem><para><emphasis>XPT_PATH_INQ</emphasis> - path inquiry, in other
       words get the SIM driver and SCSI controller (also known as HBA
       - Host Bus Adapter) properties</para>
 
     <para>The properties are returned in the instance "struct
 ccb_pathinq cpi" of the union ccb:</para>
 
     <itemizedlist>
 
       <listitem><para>version_num - the SIM driver version number, now
       all drivers use 1</para></listitem>
 
       <listitem><para>hba_inquiry - bitmask of features supported by
       the controller:</para></listitem>
 
       <listitem><para>PI_MDP_ABLE - supports MDP message (something
       from SCSI3?)</para></listitem>
 
       <listitem><para>PI_WIDE_32 - supports 32 bit wide
       SCSI</para></listitem>
 
       <listitem><para>PI_WIDE_16 - supports 16 bit wide
       SCSI</para></listitem>
 
       <listitem><para>PI_SDTR_ABLE - can negotiate synchronous
       transfer rate</para></listitem>
 
       <listitem><para>PI_LINKED_CDB - supports linked
       commands</para></listitem>
 
       <listitem><para>PI_TAG_ABLE - supports tagged
       commands</para></listitem>
 
       <listitem><para>PI_SOFT_RST - supports soft reset alternative
         (hard reset and soft reset are mutually exclusive within a
         SCSI bus)</para></listitem>
 
       <listitem><para>target_sprt - flags for target mode support, 0
         if unsupported</para></listitem>
 
       <listitem><para>hba_misc - miscellaneous controller
         features:</para></listitem>
 
       <listitem><para>PIM_SCANHILO - bus scans from high ID to low
         ID</para></listitem>
 
       <listitem><para>PIM_NOREMOVE - removable devices not included in
         scan</para></listitem>
 
       <listitem><para>PIM_NOINITIATOR - initiator role not
         supported</para></listitem>
 
       <listitem><para>PIM_NOBUSRESET - user has disabled initial BUS
         RESET</para></listitem>
 
       <listitem><para>hba_eng_cnt - mysterious HBA engine count,
         something related to compression, now is always set to
         0</para></listitem>
 
       <listitem><para>vuhba_flags - vendor-unique flags, unused
         now</para></listitem>
 
       <listitem><para>max_target - maximal supported target ID (7 for
         8-bit bus, 15 for 16-bit bus, 127 for Fibre
         Channel)</para></listitem>
 
       <listitem><para>max_lun - maximal supported LUN ID (7 for older
         SCSI controllers, 63 for newer ones)</para></listitem>
 
       <listitem><para>async_flags - bitmask of installed Async
         handler, unused now</para></listitem>
 
       <listitem><para>hpath_id - highest Path ID in the subsystem,
         unused now</para></listitem>
 
       <listitem><para>unit_number - the controller unit number,
         cam_sim_unit(sim)</para></listitem>
 
       <listitem><para>bus_id - the bus number,
         cam_sim_bus(sim)</para></listitem>
 
       <listitem><para>initiator_id - the SCSI ID of the controller
         itself</para></listitem>
 
       <listitem><para>base_transfer_speed - nominal transfer speed in
         KB/s for asynchronous narrow transfers, equals to 3300 for
         SCSI</para></listitem>
 
       <listitem><para>sim_vid - SIM driver's vendor id, a
         zero-terminated string of maximal length SIM_IDLEN including
         the terminating zero</para></listitem>
 
       <listitem><para>hba_vid - SCSI controller's vendor id, a
         zero-terminated string of maximal length HBA_IDLEN including
         the terminating zero</para></listitem>
 
       <listitem><para>dev_name - device driver name, a zero-terminated
         string of maximal length DEV_IDLEN including the terminating
         zero, equal to cam_sim_name(sim)</para></listitem>
 
     </itemizedlist>
 
     <para>The recommended way of setting the string fields is using
     strncpy, like:</para>
 
 <programlisting>    strncpy(cpi->dev_name, cam_sim_name(sim), DEV_IDLEN);</programlisting>
 
     <para>After setting the values set the status to CAM_REQ_CMP and mark the
 CCB as done.</para>
     </listitem>
     </itemizedlist>
 
   </sect1>
 
   <sect1>
     <title>Polling</title>
 
     <funcSynopsis><funcPrototype>
     <funcDef>static void
       <function>xxx_poll</function>
     </funcDef>
     <paramdef>
       <parameter>struct cam_sim *sim</parameter>
     </paramdef>
     </funcPrototype></funcSynopsis>
 
     <para>The poll function is used to simulate the interrupts when
       the interrupt subsystem is not functioning (for example, when
       the system has crashed and is creating the system dump). The CAM
       subsystem sets the proper interrupt level before calling the
       poll routine. So all it needs to do is to call the interrupt
       routine (or the other way around, the poll routine may be doing
       the real action and the interrupt routine would just call the
       poll routine). Why bother about a separate function then ?
       Because of different calling conventions. The
       <function>xxx_poll</function> routine gets the struct cam_sim
       pointer as its argument when the PCI interrupt routine by common
       convention gets pointer to the struct
       <structName>xxx_softc</structName> and the ISA interrupt routine
       gets just the device unit number. So the poll routine would
       normally look as:</para>
 
 <programlisting>static void 
 xxx_poll(struct cam_sim *sim)
 {
     xxx_intr((struct xxx_softc *)cam_sim_softc(sim)); /* for PCI device */
 }</programlisting>
 
     <para>or</para>
 
 <programlisting>static void 
 xxx_poll(struct cam_sim *sim)
 {
     xxx_intr(cam_sim_unit(sim)); /* for ISA device */
 }</programlisting>
 
   </sect1>
 
   <sect1>
     <title>Asynchronous Events</title>
 
     <para>If an asynchronous event callback has been set up then the
       callback function should be defined.</para>
 
 <programlisting>static void
 ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)</programlisting>
 
     <itemizedlist>
       <listitem><para>callback_arg - the value supplied when registering the
       callback</para></listitem>
 
       <listitem><para>code - identifies the type of event</para></listitem>
 
       <listitem><para>path - identifies the devices to which the event
       applies</para></listitem>
 
       <listitem><para>arg - event-specific argument</para></listitem>
     </itemizedlist>
 
     <para>Implementation for a single type of event, AC_LOST_DEVICE,
       looks like:</para>
 
 <programlisting>    struct xxx_softc *softc;
     struct cam_sim *sim;
     int targ;
     struct ccb_trans_settings neg;
 
     sim = (struct cam_sim *)callback_arg;
     softc = (struct xxx_softc *)cam_sim_softc(sim);
     switch (code) {
     case AC_LOST_DEVICE:
         targ = xpt_path_target_id(path);
         if(targ <= OUR_MAX_SUPPORTED_TARGET) {
             clean_negotiations(softc, targ);
             /* send indication to CAM */
             neg.bus_width = 8;
             neg.sync_period = neg.sync_offset = 0;
             neg.valid = (CCB_TRANS_BUS_WIDTH_VALID
                 | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID);
             xpt_async(AC_TRANSFER_NEG, path, &amp;neg);
         }
         break;
     default:
         break;
     }</programlisting>
 
   </sect1>
 
   <sect1>
     <title>Interrupts</title>
 
     <para>The exact type of the interrupt routine depends on the type
       of the peripheral bus (PCI, ISA and so on) to which the SCSI
       controller is connected.</para>
 
     <para>The interrupt routines of the SIM drivers run at the
       interrupt level splcam. So <function>splcam()</function> should
       be used in the driver to synchronize activity between the
       interrupt routine and the rest of the driver (for a
       multiprocessor-aware driver things get yet more interesting but
       we ignore this case here). The pseudo-code in this document
       happily ignores the problems of synchronization. The real code
       must not ignore them. A simple-minded approach is to set
       <function>splcam()</function> on the entry to the other routines
       and reset it on return thus protecting them by one big critical
       section. To make sure that the interrupt level will be always
       restored a wrapper function can be defined, like:</para>
 
 <programlisting>    static void 
     xxx_action(struct cam_sim *sim, union ccb *ccb)
     {
         int s;
         s = splcam();
         xxx_action1(sim, ccb);
         splx(s);
     }
 
     static void 
     xxx_action1(struct cam_sim *sim, union ccb *ccb)
     {
         ... process the request ...
     }</programlisting>
 
     <para>This approach is simple and robust but the problem with it
       is that interrupts may get blocked for a relatively long time
       and this would negatively affect the system's performance. On
       the other hand the functions of the <function>spl()</function>
       family have rather high overhead, so vast amount of tiny
       critical sections may not be good either.</para>
 
     <para>The conditions handled by the interrupt routine and the
       details depend very much on the hardware. We consider the set of
       "typical" conditions.</para>
 
     <para>First, we check if a SCSI reset was encountered on the bus
       (probably caused by another SCSI controller on the same SCSI
       bus). If so we drop all the enqueued and disconnected requests,
       report the events and re-initialize our SCSI controller. It is
       important that during this initialization the controller won't
       issue another reset or else two controllers on the same SCSI bus
       could ping-pong resets forever.  The case of fatal controller
       error/hang could be handled in the same place, but it will
       probably need also sending RESET signal to the SCSI bus to reset
       the status of the connections with the SCSI devices.</para>
 
 <programlisting>    int fatal=0;
     struct ccb_trans_settings neg;
     struct cam_path *path;
 
     if( detected_scsi_reset(softc)
     || (fatal = detected_fatal_controller_error(softc)) ) {
         int targ, lun;
         struct xxx_hcb *h, *hh;
 
         /* drop all enqueued CCBs */
         for(h = softc->first_queued_hcb; h != NULL; h = hh) {
             hh = h->next;
             free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
         }
 
         /* the clean values of negotiations to report */
         neg.bus_width = 8;
         neg.sync_period = neg.sync_offset = 0;
         neg.valid = (CCB_TRANS_BUS_WIDTH_VALID
             | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID);
 
         /* drop all disconnected CCBs and clean negotiations  */
         for(targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) {
             clean_negotiations(softc, targ);
 
             /* report the event if possible */
             if(xpt_create_path(&amp;path, /*periph*/NULL,
                     cam_sim_path(sim), targ,
                     CAM_LUN_WILDCARD) == CAM_REQ_CMP) {
                 xpt_async(AC_TRANSFER_NEG, path, &amp;neg);
                 xpt_free_path(path);
             }
 
             for(lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) 
                 for(h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) {
                     hh=h->next;
                     if(fatal)
                         free_hcb_and_ccb_done(h, h->ccb, CAM_UNREC_HBA_ERROR);
                     else
                         free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
                 }
         }
 
         /* report the event */
         xpt_async(AC_BUS_RESET, softc->wpath, NULL);
 
         /* re-initialization may take a lot of time, in such case
          * its completion should be signaled by another interrupt or
          * checked on timeout - but for simplicity we assume here that
          * it's really fast
          */
         if(!fatal) {
             reinitialize_controller_without_scsi_reset(softc); 
         } else {
             reinitialize_controller_with_scsi_reset(softc); 
         }
         schedule_next_hcb(softc);
         return;
     }</programlisting>
 
     <para>If interrupt is not caused by a controller-wide condition
       then probably something has happened to the current hardware
       control block. Depending on the hardware there may be other
       non-HCB-related events, we just do not consider them here.  Then
       we analyze what happened to this HCB:</para>
 
 <programlisting>    struct xxx_hcb *hcb, *h, *hh;
     int hcb_status, scsi_status;
     int ccb_status;
     int targ;
     int lun_to_freeze;
 
     hcb = get_current_hcb(softc);
     if(hcb == NULL) {
         /* either stray interrupt or something went very wrong
          * or this is something hardware-dependent
          */
         handle as necessary;
         return;
     }
 
     targ = hcb->target;
     hcb_status = get_status_of_current_hcb(softc);</programlisting>
 
     <para>First we check if the HCB has completed and if so we check
       the returned SCSI status.</para>
 
 <programlisting>    if(hcb_status == COMPLETED) {
         scsi_status = get_completion_status(hcb);</programlisting>
 
     <para>Then look if this status is related to the REQUEST SENSE
       command and if so handle it in a simple way.</para>
 
 <programlisting>        if(hcb->flags &amp; DOING_AUTOSENSE) {
             if(scsi_status == GOOD) { /* autosense was successful */
                 hcb->ccb->ccb_h.status |= CAM_AUTOSNS_VALID;
                 free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR);
             } else {
         autosense_failed:
                 free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_AUTOSENSE_FAIL);
             }
             schedule_next_hcb(softc);
             return;
         }</programlisting>
 
     <para>Else the command itself has completed, pay more attention to
       details.  If auto-sense is not disabled for this CCB and the
       command has failed with sense data then run REQUEST SENSE
       command to receive that data.</para>
 
 <programlisting>        hcb->ccb->csio.scsi_status = scsi_status;
         calculate_residue(hcb);
 
         if( (hcb->ccb->ccb_h.flags &amp; CAM_DIS_AUTOSENSE)==0
         &amp;&amp; ( scsi_status == CHECK_CONDITION 
                 || scsi_status == COMMAND_TERMINATED) ) {
             /* start auto-SENSE */
             hcb->flags |= DOING_AUTOSENSE;
             setup_autosense_command_in_hcb(hcb);
             restart_current_hcb(softc);
             return;
         }
         if(scsi_status == GOOD)
             free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_REQ_CMP);
         else
             free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR);
         schedule_next_hcb(softc);
         return;
     }</programlisting>
 
     <para>One typical thing would be negotiation events: negotiation
       messages received from a SCSI target (in answer to our
       negotiation attempt or by target's initiative) or the target is
       unable to negotiate (rejects our negotiation messages or does
       not answer them).</para>
 
 <programlisting>    switch(hcb_status) {
     case TARGET_REJECTED_WIDE_NEG:
         /* revert to 8-bit bus */
         softc->current_bus_width[targ] = softc->goal_bus_width[targ] = 8;
         /* report the event */
         neg.bus_width = 8; 
         neg.valid = CCB_TRANS_BUS_WIDTH_VALID;
         xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &amp;neg);
         continue_current_hcb(softc);
         return;
     case TARGET_ANSWERED_WIDE_NEG:
         {
             int wd;
 
             wd = get_target_bus_width_request(softc);
             if(wd <= softc->goal_bus_width[targ]) { 
                 /* answer is acceptable */
                 softc->current_bus_width[targ] = 
                 softc->goal_bus_width[targ] = neg.bus_width = wd;
 
                 /* report the event */
                 neg.valid = CCB_TRANS_BUS_WIDTH_VALID;
                 xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &amp;neg);
             } else {
                 prepare_reject_message(hcb);
             }
         }
         continue_current_hcb(softc);
         return;
     case TARGET_REQUESTED_WIDE_NEG:
         {
             int wd;
 
             wd = get_target_bus_width_request(softc);
             wd = min (wd, OUR_BUS_WIDTH);
             wd = min (wd, softc->user_bus_width[targ]);
 
             if(wd != softc->current_bus_width[targ]) {
                 /* the bus width has changed */
                 softc->current_bus_width[targ] = 
                 softc->goal_bus_width[targ] = neg.bus_width = wd;
 
                 /* report the event */
                 neg.valid = CCB_TRANS_BUS_WIDTH_VALID;
                 xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &amp;neg);
             }
             prepare_width_nego_rsponse(hcb, wd);
         }
         continue_current_hcb(softc);
         return;
     }</programlisting>
 
     <para>Then we handle any errors that could have happened during
       auto-sense in the same simple-minded way as before. Otherwise we
       look closer at the details again.</para>
 
 <programlisting>    if(hcb->flags &amp; DOING_AUTOSENSE)
         goto autosense_failed;
 
     switch(hcb_status) {</programlisting>
 
     <para>The next event we consider is unexpected disconnect. Which
       is considered normal after an ABORT or BUS DEVICE RESET message
       and abnormal in other cases.</para>
 
 <programlisting>    case UNEXPECTED_DISCONNECT:
         if(requested_abort(hcb)) {
             /* abort affects all commands on that target+LUN, so 
              * mark all disconnected HCBs on that target+LUN as aborted too
              */
             for(h = softc->first_discon_hcb[hcb->target][hcb->lun]; 
                     h != NULL; h = hh) {
                 hh=h->next;
                 free_hcb_and_ccb_done(h, h->ccb, CAM_REQ_ABORTED);
             }
             ccb_status = CAM_REQ_ABORTED;
         } else if(requested_bus_device_reset(hcb)) {
             int lun;
 
             /* reset affects all commands on that target, so 
              * mark all disconnected HCBs on that target+LUN as reset
              */
 
             for(lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) 
                 for(h = softc->first_discon_hcb[hcb->target][lun]; 
                         h != NULL; h = hh) {
                     hh=h->next;
                     free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET);
                 }
 
             /* send event */
             xpt_async(AC_SENT_BDR, hcb->ccb->ccb_h.path_id, NULL);
 
             /* this was the CAM_RESET_DEV request itself, it's completed */
             ccb_status = CAM_REQ_CMP; 
         } else {
             calculate_residue(hcb);
             ccb_status = CAM_UNEXP_BUSFREE; 
             /* request the further code to freeze the queue */
             hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;
             lun_to_freeze = hcb->lun;
         }
         break;</programlisting>
 
     <para>If the target refuses to accept tags we notify CAM about
       that and return back all commands for this LUN:</para>
 
 <programlisting>    case TAGS_REJECTED:
         /* report the event */
         neg.flags = 0 &amp; ~CCB_TRANS_TAG_ENB; 
         neg.valid = CCB_TRANS_TQ_VALID;
         xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &amp;neg);
 
         ccb_status = CAM_MSG_REJECT_REC; 
         /* request the further code to freeze the queue */
         hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;
         lun_to_freeze = hcb->lun;
         break;</programlisting>
 
     <para>Then we check a number of other conditions, with processing
       basically limited to setting the CCB status:</para>
 
 <programlisting>    case SELECTION_TIMEOUT:
         ccb_status = CAM_SEL_TIMEOUT; 
         /* request the further code to freeze the queue */
         hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;
         lun_to_freeze = CAM_LUN_WILDCARD;
         break;
     case PARITY_ERROR:
         ccb_status = CAM_UNCOR_PARITY; 
         break;
     case DATA_OVERRUN:
     case ODD_WIDE_TRANSFER:
         ccb_status = CAM_DATA_RUN_ERR; 
         break;
     default:
         /* all other errors are handled in a generic way */
         ccb_status = CAM_REQ_CMP_ERR; 
         /* request the further code to freeze the queue */
         hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN;
         lun_to_freeze = CAM_LUN_WILDCARD;
         break;
     }</programlisting>
 
     <para>Then we check if the error was serious enough to freeze the
       input queue until it gets proceeded and do so if it is:</para>
 
 <programlisting>    if(hcb->ccb->ccb_h.status &amp; CAM_DEV_QFRZN) {
         /* freeze the queue */
         xpt_freeze_devq(ccb->ccb_h.path, /*count*/1);
 
         /* re-queue all commands for this target/LUN back to CAM */
 
         for(h = softc->first_queued_hcb; h != NULL; h = hh) {
             hh = h->next;
 
             if(targ == h->targ 
             &amp;&amp; (lun_to_freeze == CAM_LUN_WILDCARD || lun_to_freeze == h->lun) )
                 free_hcb_and_ccb_done(h, h->ccb, CAM_REQUEUE_REQ);
         }
     }
     free_hcb_and_ccb_done(hcb, hcb->ccb, ccb_status);
     schedule_next_hcb(softc);
     return;</programlisting>
 
     <para>This concludes the generic interrupt handling although
       specific controllers may require some additions.</para>
 
   </sect1>
 
   <sect1>
     <title>Errors Summary</title>
 
     <para>When executing an I/O request many things may go wrong. The
       reason of error can be reported in the CCB status with great
       detail. Examples of use are spread throughout this document. For
       completeness here is the summary of recommended responses for
       the typical error conditions:</para>
 
     <itemizedlist>
 
       <listitem><para><emphasis>CAM_RESRC_UNAVAIL</emphasis> - some
-        resource is temporarily unavailable and the SIM driver can not
+        resource is temporarily unavailable and the SIM driver cannot
         generate an event when it will become available. An example of
         this resource would be some intra-controller hardware resource
         for which the controller does not generate an interrupt when
         it becomes available.</para></listitem>
  
       <listitem><para><emphasis>CAM_UNCOR_PARITY</emphasis> -
         unrecovered parity error occurred</para></listitem>
 
       <listitem><para><emphasis>CAM_DATA_RUN_ERR</emphasis> - data
         overrun or unexpected data phase (going in other direction
         than specified in CAM_DIR_MASK) or odd transfer length for
         wide transfer</para></listitem>
 
       <listitem><para><emphasis>CAM_SEL_TIMEOUT</emphasis> - selection
         timeout occurred (target does not respond)</para></listitem>
 
       <listitem><para><emphasis>CAM_CMD_TIMEOUT</emphasis> - command
         timeout occurred (the timeout function ran)</para></listitem>
 
       <listitem><para><emphasis>CAM_SCSI_STATUS_ERROR</emphasis> - the
         device returned error</para></listitem>
 
       <listitem><para><emphasis>CAM_AUTOSENSE_FAIL</emphasis> - the
         device returned error and the REQUEST SENSE COMMAND
         failed</para></listitem>
 
       <listitem><para><emphasis>CAM_MSG_REJECT_REC</emphasis> - MESSAGE
         REJECT message was received</para></listitem>
 
       <listitem><para><emphasis>CAM_SCSI_BUS_RESET</emphasis> - received
         SCSI bus reset</para></listitem>
 
       <listitem><para><emphasis>CAM_REQ_CMP_ERR</emphasis> -
         "impossible" SCSI phase occurred or something else as weird or
         just a generic error if further detail is not
         available</para></listitem>
 
       <listitem><para><emphasis>CAM_UNEXP_BUSFREE</emphasis> -
         unexpected disconnect occurred</para></listitem>
 
       <listitem><para><emphasis>CAM_BDR_SENT</emphasis> - BUS DEVICE
         RESET message was sent to the target</para></listitem>
 
       <listitem><para><emphasis>CAM_UNREC_HBA_ERROR</emphasis> -
         unrecoverable Host Bus Adapter Error</para></listitem>
 
       <listitem><para><emphasis>CAM_REQ_TOO_BIG</emphasis> - the request
         was too large for this controller</para></listitem>
 
       <listitem><para><emphasis>CAM_REQUEUE_REQ</emphasis> - this
         request should be re-queued to preserve transaction ordering.
         This typically occurs when the SIM recognizes an error that
         should freeze the queue and must place other queued requests
         for the target at the sim level back into the XPT
         queue. Typical cases of such errors are selection timeouts,
         command timeouts and other like conditions. In such cases the
         troublesome command returns the status indicating the error,
         the and the other commands which have not be sent to the bus
         yet get re-queued.</para></listitem>
 
       <listitem><para><emphasis>CAM_LUN_INVALID</emphasis> - the LUN
         ID in the request is not supported by the SCSI
         controller</para></listitem>
 
       <listitem><para><emphasis>CAM_TID_INVALID</emphasis> - the
         target ID in the request is not supported by the SCSI
         controller</para></listitem>
     </itemizedlist>
   </sect1>
 
   <sect1>
     <title>Timeout Handling</title>
 
     <para>When the timeout for an HCB expires that request should be
       aborted, just like with an XPT_ABORT request. The only
       difference is that the returned status of aborted request should
       be CAM_CMD_TIMEOUT instead of CAM_REQ_ABORTED (that's why
       implementation of the abort better be done as a function). But
       there is one more possible problem: what if the abort request
       itself will get stuck? In this case the SCSI bus should be
       reset, just like with an XPT_RESET_BUS request (and the idea
       about implementing it as a function called from both places
       applies here too). Also we should reset the whole SCSI bus if a
       device reset request got stuck. So after all the timeout
       function would look like:</para>
 
 <programlisting>static void
 xxx_timeout(void *arg)
 {
     struct xxx_hcb *hcb = (struct xxx_hcb *)arg;
     struct xxx_softc *softc;
     struct ccb_hdr *ccb_h;
 
     softc = hcb->softc;
     ccb_h = &amp;hcb->ccb->ccb_h;
 
     if(hcb->flags &amp; HCB_BEING_ABORTED
     || ccb_h->func_code == XPT_RESET_DEV) {
         xxx_reset_bus(softc);
     } else {
         xxx_abort_ccb(hcb->ccb, CAM_CMD_TIMEOUT);
     }
 }</programlisting>
 
     <para>When we abort a request all the other disconnected requests
       to the same target/LUN get aborted too. So there appears a
       question, should we return them with status CAM_REQ_ABORTED or
       CAM_CMD_TIMEOUT ?  The current drivers use CAM_CMD_TIMEOUT. This
       seems logical because if one request got timed out then probably
       something really bad is happening to the device, so if they
       would not be disturbed they would time out by themselves.</para>
 
   </sect1>
 
 </chapter>
diff --git a/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml
index 4657f5ddd5..80bb0de490 100644
--- a/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml
@@ -1,514 +1,514 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml,v 1.8 2001/06/13 11:36:07 tom Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml,v 1.9 2001/06/13 18:18:58 murray Exp $
 -->
 
     <chapter id="secure">
       <title>Secure Programming</title>
 
       <para>This chapter was written by &a.murray;.</para>
 
       <sect1><title>Synopsis</title>
  
       <para>This chapter describes some of the security issues that
       have plagued Unix programmers for decades and some of the new
       tools available to help programmers avoid writing exploitable
       code.</para>
       </sect1>
 
       <sect1 id="secure-philosophy"><title>Secure Design
       Methodology</title>
 
       <para>Writing secure applications takes a very scrutinous and
       pessimistic outlook on life.  Applications should be run with
       the principle of <quote>least privilege</quote> so that no
       process is ever running with more than the bare minimum access
       that it needs to accomplish its function.  Previously tested
       code should be reused whenever possible to avoid common
       mistakes that others may have already fixed.</para>
 
       <para>One of the pitfalls of the Unix environment is how easy it
       is to make assumptions about the sanity of the environment.
       Applications should never trust user input (in all its forms),
       system resources, inter-process communication, or the timing of
       events.  Unix processes do not execute synchronously so logical
       operations are rarely atomic.</para>
       </sect1>
 
       <sect1><title>Buffer Overflows</title> 
 
       <para>Buffer Overflows have been around since the very
       beginnings of the Von-Neuman <xref linkend="COD"> architecture.
 
       <indexterm><primary>buffer overflow</primary></indexterm> 
       <indexterm><primary>Von-Neuman</primary></indexterm>
 
       They first gained widespread notoriety in 1988 with the Morris
       Internet worm.  Unfortunately, the same basic attack remains
 
       <indexterm><primary>Morris Internet worm</primary></indexterm>
 
       effective today.  Of the 17 CERT security advisories of 1999, 10
 
       <indexterm>
         <primary>CERT</primary><secondary>security advisories</secondary>
       </indexterm>
 
       of them were directly caused by buffer-overflow software bugs.
       By far the most common type of buffer overflow attack is based
       on corrupting the stack.</para>
 
       <indexterm><primary>stack</primary></indexterm> 
       <indexterm><primary>arguments</primary></indexterm> 
 
       <para>Most modern computer systems use a stack to pass arguments
       to procedures and to store local variables.  A stack is a last
       in first out (LIFO) buffer in the high memory area of a process
       image.  When a program invokes a function a new "stack frame" is
    
       <indexterm><primary>LIFO</primary></indexterm>
       <indexterm>
         <primary>process image</primary>
 	  <secondary>stack pointer</secondary>
       </indexterm>
 
       created.  This stack frame consists of the arguments passed to
       the function as well as a dynamic amount of local variable
       space.  The "stack pointer" is a register that holds the current
 
       <indexterm><primary>stack frame</primary></indexterm>
       <indexterm><primary>stack pointer</primary></indexterm>
 
       location of the top of the stack.  Since this value is
       constantly changing as new values are pushed onto the top of the
       stack, many implementations also provide a "frame pointer" that
       is located near the beginning of a stack frame so that local
       variables can more easily be addressed relative to this
       value. <xref linkend="COD"> The return address for function
 
       <indexterm><primary>frame pointer</primary></indexterm> 
       <indexterm>
         <primary>process image</primary>
         <secondary>frame pointer</secondary>
       </indexterm>
       <indexterm><primary>return address</primary></indexterm> 
       <indexterm><primary>stack-overflow</primary></indexterm>
 
       calls is also stored on the stack, and this is the cause of
       stack-overflow exploits since overflowing a local variable in a
       function can overwrite the return address of that function,
       potentially allowing a malicious user to execute any code he or
       she wants.</para>
 
       <para>Although stack-based attacks are by far the most common,
       it would also be possible to overrun the stack with a heap-based
       (malloc/free) attack.</para>
 
       <para>The C programming language does not perform automatic
       bounds checking on arrays or pointers as many other languages
       do.  In addition, the standard C library is filled with a
       handful of very dangerous functions.</para>
 
       <informaltable>
         <tgroup cols=2>
           <tbody>
           <row><entry><function>strcpy</function>(char *dest, const char
           *src)</entry>
           <entry><simpara>May overflow the dest buffer</simpara></entry>
           </row>
 
           <row><entry><function>strcat</function>(char *dest, const char
           *src)</entry>
           <entry><simpara>May overflow the dest buffer</simpara></entry>
           </row>
 
           <row><entry><function>getwd</function>(char *buf)</entry>
           <entry><simpara>May overflow the buf buffer</simpara></entry>
           </row>
 
           <row><entry><function>gets</function>(char *s)</entry>
           <entry><simpara>May overflow the s buffer</simpara></entry>
           </row>
 
           <row><entry><function>[vf]scanf</function>(const char *format,
           ...)</entry>
           <entry><simpara>May overflow its arguments.</simpara></entry>
           </row>
 
           <row><entry><function>realpath</function>(char *path, char
           resolved_path[])</entry>
           <entry><simpara>May overflow the path buffer</simpara></entry>
           </row>
 
           <row><entry><function>[v]sprintf</function>(char *str, const char
           *format, ...)</entry>
           <entry><simpara>May overflow the str buffer.</simpara></entry>
           </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <sect2><title>Example Buffer Overflow</title>
 
       <para>The following example code contains a buffer overflow
       designed to overwrite the return address and skip the
       instruction immediately following the function call.  (Inspired
       by <xref linkend="Phrack">)</para>
 
 <programlisting>#include <sgmltag>stdio.h</sgmltag>
 
 void manipulate(char *buffer) {
   char newbuffer[80];
   strcpy(newbuffer,buffer);
 }
 
 int main() {
   char ch,buffer[4096];
   int i=0;
 
   while ((buffer[i++] = getchar()) != '\n') {};
   
   i=1;
   manipulate(buffer);
   i=2;
   printf("The value of i is : %d\n",i);
   return 0;
 }</programlisting>
 
       <para>Let us examine what the memory image of this process would
       look like if we were to input 160 spaces into our little program
       before hitting return.</para> 
 
       <para>[XXX figure here!]</para>
 
       <para>Obviously more malicious input can be devised to execute
       actual compiled instructions (such as exec(/bin/sh)).</para>
       </sect2>
 
       <sect2><title>Avoiding Buffer Overflows</title>
 
       <para>The most straightforward solution to the problem of
       stack-overflows is to always use length restricted memory and
       string copy functions.  <function>strncpy</function> and
       <function>strncat</function> are part of the standard C library.
 
       <indexterm>
         <primary>string copy functions</primary>
 	  <secondary>strncpy</secondary>
       </indexterm>      
       <indexterm>
         <primary>string copy functions</primary>
 	  <secondary>strncat</secondary>
       </indexterm>      
 
       These functions accept a length value as a parameter which
       should be no larger than the size of the destination buffer.
       These functions will then copy up to `length' bytes from the
       source to the destination.  However there are a number of
       problems with these functions.  Neither function guarantees NUL
       termination if the size of the input buffer is as large as the
 
       <indexterm><primary>NUL termination</primary></indexterm>
 
       destination.  The length parameter is also used inconsistently
       between strncpy and strncat so it is easy for programmers to get
       confused as to their proper usage.  There is also a significant
       performance loss compared to <function>strcpy</function> when
       copying a short string into a large buffer since
       <function>strncpy</function> NUL fills up the size
       specified.</para>
 
       <para>In OpenBSD, another memory copy implementation has been
 
       <indexterm><primary>OpenBSD</primary></indexterm>
 
       created to get around these problem.  The
       <function>strlcpy</function> and <function>strlcat</function>
       functions guarantee that they will always null terminate the
       destination string when given a non-zero length argument.  For
       more information about these functions see <xref
       linkend="OpenBSD">.  The OpenBSD <function>strlcpy</function> and
       <function>strlcat</function> instructions have been in FreeBSD
       since 3.3.</para>
 
       <indexterm>
         <primary>string copy functions</primary>
 	  <secondary>strlcpy</secondary>
       </indexterm>
 
       <indexterm>
 	<primary>string copy functions</primary>
           <secondary>strlcat</secondary>
       </indexterm>
 
         <sect3><title>Compiler based run-time bounds checking</title>
 
 	<indexterm><primary>bounds checking</primary>
 	<secondary>compiler-based</secondary></indexterm>
 
         <para>Unfortunately there is still a very large assortment of
         code in public use which blindly copies memory around without
         using any of the bounded copy routines we just discussed.
         Fortunately, there is another solution.  Several compiler
         add-ons and libraries exist to do Run-time bounds checking in
         C/C++.</para> 
 
 	<indexterm><primary>StackGuard</primary></indexterm> 
 	<indexterm><primary>gcc</primary></indexterm>  
 
         <para>StackGuard is one such add-on that is implemented as a
         small patch to the gcc code generator.  From the StackGuard
         website, http://immunix.org/stackguard.html :
         <blockquote><para>"StackGuard detects and defeats stack
         smashing attacks by protecting the return address on the stack
         from being altered.  StackGuard places a "canary" word next to
         the return address when a function is called.  If the canary
         word has been altered when the function returns, then a stack
         smashing attack has been attempted, and the program responds
         by emitting an intruder alert into syslog, and then
         halts."</para></blockquote> 
 
         <blockquote><para>"StackGuard is implemented as a small patch
         to the gcc code generator, specifically the function_prolog()
         and function_epilog() routines.  function_prolog() has been
         enhanced to lay down canaries on the stack when functions
         start, and function_epilog() checks canary integrity when the
         function exits.  Any attempt at corrupting the return address
         is thus detected before the function
         returns."</para></blockquote>
         </para>
 
         <indexterm><primary>buffer overflow</primary></indexterm>
 
         <para>Recompiling your application with StackGuard is an
         effective means of stopping most buffer-overflow attacks, but
         it can still be compromised.</para>
 
         </sect3>
 
         <sect3><title>Library based run-time bounds checking</title>
 
   	<indexterm>
 	  <primary>bounds checking</primary>
 	  <secondary>library-based</secondary>
 	</indexterm>
 
         <para>Compiler-based mechanisms are completely useless for
         binary-only software for which you cannot recompile.  For
         these situations there are a number of libraries which
         re-implement the unsafe functions of the C-library
         (<function>strcpy</function>, <function>fscanf</function>,
         <function>getwd</function>, etc..) and ensure that these
         functions can never write past the stack pointer.</para>
 
         <itemizedlist>
         <listitem><simpara>libsafe</simpara></listitem>
         <listitem><simpara>libverify</simpara></listitem>
         <listitem><simpara>libparnoia</simpara></listitem>
         </itemizedlist>
 
 	<para>Unfortunately these library-based defenses have a number
         of shortcomings.  These libraries only protect against a very
         small set of security related issues and they neglect to fix
         the actual problem.  These defenses may fail if the
         application was compiled with -fomit-frame-pointer.  Also, the
         LD_PRELOAD and LD_LIBRARY_PATH environment variables can be
         overwritten/unset by the user.</para>
         </sect3>
 
         </sect2>
       </sect1>
 
       <sect1><title>SetUID issues</title>
 
       <indexterm><primary>seteuid</primary></indexterm>
 
       <para>There are at least 6 different IDs associated with any
       given process.  Because of this you have to be very careful with
       the access that your process has at any given time.  In
       particular, all seteuid applications should give up their
       privileges as soon as it is no longer required.</para>
 
       <indexterm>
         <primary>user IDs</primary>
           <secondary>real user ID</secondary>
       </indexterm>
       <indexterm>
         <primary>user IDs</primary>
           <secondary>effective user ID</secondary>
       </indexterm>
 
       <para>The real user ID can only be changed by a superuser
       process.  The <application>login</application> program sets this
       when a user initially logs in and it is seldom changed.</para>
 
       <para>The effective user ID is set by the
       <function>exec()</function> functions if a program has its
       seteuid bit set.  An application can call
       <function>seteuid()</function> at any time to set the effective
       user ID to either the real user ID or the saved set-user-ID.
       When the effective user ID is set by <function>exec()</function>
       functions, the previous value is saved in the saved set-user-ID.</para>
 
       </sect1>
 
       <sect1 id="secure-chroot"><title>Limiting your program's environment</title>
 
       <indexterm><primary>chroot()</primary></indexterm>
 
       <para>The traditional method of restricting a process
       is with the <function>chroot()</function> system call.  This
       system call changes the root directory from which all other
       paths are referenced for a process and any child processes.  For
       this call to succeed the process must have execute (search)
       permission on the directory being referenced.  The new
       environment does not actually take effect until you
       <function>chdir()</function> into your new environment.  It
       should also be noted that a process can easily break out of a
       chroot environment if it has root privilege.  This could be
       accomplished by creating device nodes to read kernel memory,
       attaching a debugger to a process outside of the jail, or in
       many other creative ways.</para>
       
       <para>The behavior of the <function>chroot()</function> system
       call can be controlled somewhat with the
       kern.chroot_allow_open_directories <command>sysctl</command>
       variable.  When this value is set to 0,
       <function>chroot()</function> will fail with EPERM if there are
       any directories open.  If set to the default value of 1, then
       <function>chroot()</function> will fail with EPERM if there are
       any directories open and the process is already subject to a
       <function>chroot()</function> call.  For any other value, the
       check for open directories will be bypassed completely.</para>
 
       <sect2><title>FreeBSD's jail functionality</title>
 
       <indexterm><primary>jail</primary></indexterm>
 
       <para>The concept of a Jail extends upon the
       <function>chroot()</function> by limiting the powers of the
       superuser to create a true `virtual server'.  Once a prison is
       setup all network communication must take place through the
       specified IP address, and the power of "root privilege" in this
       jail is severely constrained.</para>
 
       <para>While in a prison, any tests of superuser power within the
       kernel using the <function>suser()</function> call will fail.
       However, some calls to <function>suser()</function> have been
       changed to a new interface <function>suser_xxx()</function>.
       This function is responsible for recognizing or denying access
       to superuser power for imprisoned processes.</para>
 
       <para>A superuser process within a jailed environment has the
       power to : </para>
       <itemizedlist>
       <listitem><simpara>Manipulate credential with
         <function>setuid</function>, <function>seteuid</function>,
         <function>setgid</function>, <function>setegid</function>,
         <function>setgroups</function>, <function>setreuid</function>,
         <function>setregid</function>, <function>setlogin</function></simpara></listitem>
       <listitem><simpara>Set resource limits with <function>setrlimit</function></simpara></listitem>
       <listitem><simpara>Modify some sysctl nodes
         (kern.hostname)</simpara></listitem>
       <listitem><simpara><function>chroot()</function></simpara></listitem>
       <listitem><simpara>Set flags on a vnode:
         <function>chflags</function>,
         <function>fchflags</function></simpara></listitem>
       <listitem><simpara>Set attributes of a vnode such as file
         permission, owner, group, size, access time, and modification
         time.</simpara></listitem>
       <listitem><simpara>Bind to privileged ports in the Internet
         domain (ports < 1024)</simpara></listitem>
       </itemizedlist>
 
       <para><function>Jail</function> is a very useful tool for
       running applications in a secure environment but it does have
       some shortcomings.  Currently, the IPC mechanisms have not been
       converted to the <function>suser_xxx</function> so applications
-      such as MySQL can not be run within a jail.  Superuser access
+      such as MySQL cannot be run within a jail.  Superuser access
       may have a very limited meaning within a jail, but there is
       no way to specify exactly what "very limited" means.</para>
       </sect2>
 
       <sect2><title>POSIX.1e Process Capabilities</title>
 
       <indexterm><primary>POSIX.1e Process Capabilities</primary></indexterm>
       <indexterm><primary>TrustedBSD</primary></indexterm>
 
       <para>Posix has released a working draft that adds event
       auditing, access control lists, fine grained privileges,
       information labeling, and mandatory access control.</para>
       <para>This is a work in progress and is the focus of the <ulink
       url="http://www.trustedbsd.org">TrustedBSD</ulink> project.  Some
       of the initial work has been committed to FreeBSD-current
       (cap_set_proc(3)).</para>
 
       </sect2>
 
       </sect1>
 
       <sect1><title>Trust</title>
 
       <para>An application should never assume that anything about the
       users environment is sane.  This includes (but is certainly not
       limited to) : user input, signals, environment variables,
       resources, IPC, mmaps, the file system working directory, file
       descriptors, the # of open files, etc.</para>
 
       <indexterm><primary>positive filtering</primary></indexterm>
       <indexterm><primary>data validation</primary></indexterm>
 
       <para>You should never assume that you can catch all forms of
       invalid input that a user might supply.  Instead, your
       application should use positive filtering to only allow a
       specific subset of inputs that you deem safe.  Improper data
       validation has been the cause of many exploits, especially with
       CGI scripts on the world wide web.  For filenames you need to be
       extra careful about paths ("../", "/"), symbolic links, and
       shell escape characters.</para>
 
       <indexterm><primary>Perl Taint mode</primary></indexterm>
 
       <para>Perl has a really cool feature called "Taint" mode which
       can be used to prevent scripts for using data derived outside
       the program in an unsafe way.  This mode will check command line
       arguments, environment variables, locale information, the
       results of certain syscalls (<function>readdir()</function>,
       <function>readlink()</function>,
       <function>getpwxxx()</function>, and all file input.</para>
 
       </sect1>
 
       <sect1 id="secure-race-conditions">
       <title>Race Conditions</title>
 
       <para>A race condition is anomalous behavior caused by the
       unexpected dependence on the relative timing of events.  In
       other words, a programmer incorrectly assumed that a particular
       event would always happen before another.</para>
 
       <indexterm><primary>race conditions</primary>
       <secondary>signals</secondary></indexterm>
 
       <indexterm><primary>race conditions</primary>
       <secondary>access checks</secondary></indexterm>
 
       <indexterm><primary>race conditions</primary>
       <secondary>file opens</secondary></indexterm>
 
       <para>Some of the common causes of race conditions are signals,
       access checks, and file opens.  Signals are asynchronous events
       by nature so special care must be taken in dealing with them.
       Checking access with <function>access(2)</function> then
       <function>open(2)</function> is clearly non-atomic.  Users can
       move files in between the two calls.  Instead, privileged
       applications should <function>seteuid()</function> and then call
       <function>open()</function> directly.  Along the same lines, an
       application should always set a proper umask before
       <function>open()</function> to obviate the need for spurious
       <function>chmod()</function> calls.</para>
 
       </sect1>
 
      </chapter>
diff --git a/en_US.ISO8859-1/books/faq/book.sgml b/en_US.ISO8859-1/books/faq/book.sgml
index a1311a79d8..76487ff398 100644
--- a/en_US.ISO8859-1/books/faq/book.sgml
+++ b/en_US.ISO8859-1/books/faq/book.sgml
@@ -1,12487 +1,12487 @@
 <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
 
 <!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN">
 %bookinfo;
 
 <!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
 %mailing-lists;
 ]>
 
 <book>
   <bookinfo>
     <title>Frequently Asked Questions for FreeBSD 2.X, 3.X and 4.X</title>
 
     <corpauthor>The FreeBSD Documentation Project</corpauthor>
 
-    <pubdate>$FreeBSD: doc/en_US.ISO8859-1/books/faq/book.sgml,v 1.243 2001/07/06 13:02:56 dd Exp $</pubdate>
+    <pubdate>$FreeBSD: doc/en_US.ISO8859-1/books/faq/book.sgml,v 1.244 2001/07/10 14:39:25 nik Exp $</pubdate>
 
     <copyright>
       <year>1995</year>
       <year>1996</year>
       <year>1997</year>
       <year>1998</year>
       <year>1999</year>
       <year>2000</year>
       <year>2001</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="http://www.FreeBSD.org/">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="http://www.FreeBSD.org/search/search.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="http://www.FreeBSD.org/">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="http://www.FreeBSD.org/gallery/gallery.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 are the goals of FreeBSD?</para>
         </question>
 
         <answer>
           <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, 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="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 and/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>For those of our readers whose first language is not
             English, it may be 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/4.3-RELEASE/">4.3</ulink>
             is the latest <emphasis>STABLE</emphasis> version; it was
             released in April, 2001. This is also the latest
             <emphasis>RELEASE</emphasis> version.</para>
 
           <para>Briefly explained, <emphasis>-STABLE</emphasis> is aimed
             at the ISP or other corporate 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 you should only use
             <emphasis>-CURRENT</emphasis> if you are sure that you are
             prepared for its increased volatility (relative to
             <emphasis>-STABLE</emphasis>, that is).</para>
 
           <para>Releases are only 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 are sometimes
             treated with contempt.</para>
 
           <para>Every day, <ulink
             URL="http://www.FreeBSD.org/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 and/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
             snaphosts.</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/stable.html">-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; ... 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 4.3-RELEASE, which was released
             in April 2001.</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 the changes made have settled down
             sufficiently to avoid compromising the stability of the
             release.  Many users regard this caution as one of the best
             things about FreeBSD, although it can be a little frustrating
             when waiting for all the latest goodies to become
             available...</para>
 
           <para>Releases are made about every 4 months on average.</para>
 
           <para>For people needing (or wanting) a little more excitement,
             binary snapshots are made every day... see 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="../handbook/staff.html#STAFF-CORE">core team</ulink> of
             9 people. There is a much larger team of more than 200 <ulink
             URL="../handbook/staff-committers.html">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, 4.3-RELEASE can be
                 found in the <ulink
                 URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/4.3-RELEASE/">4.3-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="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="http://www.FreeBSD.org/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
                 EFNet is a FreeBSD forum, but do not go there for tech
                 support or to try and get folks there to help you avoid
                 the pain of reading man pages or doing your own research.
                 It is a chat channel, first and foremost, and topics there
                 are just as likely to involve sex, sports or nuclear
                 weapons as they are FreeBSD.  You Have Been Warned!
                 Available at server <hostid>irc.chat.org</hostid>.</para>
             </listitem>
 
             <listitem>
               <para>Channel <emphasis>#FreeBSDhelp</emphasis> on
                 EFNet is a channel dedicated to helping FreeBSD users. They
                 are much more sympathetic to questions then
                 <emphasis>#FreeBSD</emphasis> is.</para>
             </listitem>
 
             <listitem>
               <para>Channel <literal>#FreeBSD</literal> on
                 DALNET 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
                 UNDERNET 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
             *all* 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="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>
         </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 categorised in a number of different
             ways.  These include:</para>
 
           <itemizedlist>
             <listitem>
               <para>The document's name, such as <literal>faq</literal>, or
                 <literal>handbook</literal>.</para>
             </listitem>
 
             <listitem>
               <para>The document's language and encoding.  These are based on
                 the locale names you will find under
                 <filename>/usr/share/locale</filename> on your FreeBSD
                 system.  The current languages and encodings that we have for
                 documentation are as follows:</para>
 
               <informaltable frame="none">
                 <tgroup cols="2">
                   <thead>
                     <row>
                       <entry>Name</entry>
 
                       <entry>Meaning</entry>
                     </row>
                   </thead>
 
                   <tbody>
                     <row>
                       <entry><literal>en_US.ISO8859-1</literal></entry>
 
                       <entry>US English</entry>
                     </row>
 
                     <row>
                       <entry><literal>de_DE.ISO8859-1</literal></entry>
 
                       <entry>German</entry>
                     </row>
 
                     <row>
                       <entry><literal>es_ES.ISO8859-1</literal></entry>
 
                       <entry>Spanish</entry>
                     </row>
 
                     <row>
                       <entry><literal>fr_FR.ISO8859-1</literal></entry>
 
                       <entry>French</entry>
                     </row>
 
                     <row>
                       <entry><literal>ja_JP.eucJP</literal></entry>
 
                       <entry>Japanese (EUC encoding)</entry>
                     </row>
 
                     <row>
                       <entry><literal>ru_RU.KOI8-R</literal></entry>
 
                       <entry>Russian (KOI8-R encoding)</entry>
                     </row>
 
                     <row>
                       <entry><literal>zh_TW.Big5</literal></entry>
 
                       <entry>Chinese (Big5 encoding)</entry>
                     </row>
                   </tbody>
                 </tgroup>
               </informaltable>
 
               <note>
                 <para>Some documents may not be available in all
                   languages.</para>
               </note>
             </listitem>
 
             <listitem>
               <para>The document's format.  We produce the documentation in a
                 number of different output formats to try and make it as
                 flexible as possible.  The current formats are;</para>
 
               <informaltable frame="none">
                 <tgroup cols="2">
                   <thead>
                     <row>
                       <entry>Format</entry>
 
                       <entry>Meaning</entry>
                     </row>
                   </thead>
 
                   <tbody>
                     <row>
                       <entry><literal>html-split</literal></entry>
 
                       <entry>A collection of small, linked, HTML
                         files.</entry>
                     </row>
 
                     <row>
                       <entry><literal>html</literal></entry>
 
                       <entry>One large HTML file containing the entire
                         document</entry>
                     </row>
 
                     <row>
                       <entry><literal>pdb</literal></entry>
 
                       <entry>Palm Pilot database format, for use with the
                         <ulink URL="http://www.iSilo.com/">iSilo</ulink>
                         reader.</entry>
                     </row>
 
                     <row>
                       <entry><literal>pdf</literal></entry>
 
                       <entry>Adobe's Portable Document Format</entry>
                     </row>
 
                     <row>
                       <entry><literal>ps</literal></entry>
 
                       <entry>Postscript</entry>
                     </row>
 
                     <row>
                       <entry><literal>rtf</literal></entry>
 
                       <entry>Microsoft's Rich Text Format<footnote>
                           <para>Page numbers are not automatically updated
                             when loading this format in to Word.  Press
                             <keycap>CTRL</keycap>+<keycap>A</keycap>,
                             <keycap>CTRL</keycap>+<keycap>END</keycap>,
                             <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>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>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>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="become-web-mirror">
           <para>How do I become a FreeBSD Web mirror?</para>
         </question>
 
         <answer>
           <para>Certainly!  There are multiple ways to mirror the Web
             pages.</para>
 
 
 
           <itemizedlist>
             <listitem>
               <para>Using <application>CVSup</application>:
                 You can retrieve the formatted files
                 using <application>CVSup</application>, and connecting to
                 a <application>CVSup</application> server.</para>
 
               <para>To retrieve the webpages, please look at the example
                 supfile, which can be found in
                 <filename>/usr/share/examples/cvsup/www-supfile</filename>.
               </para>
 
             </listitem>
 
             <listitem>
               <para>Using ftp mirror:  You can download the FTP server's
                 copy of the web site sources using your favorite ftp mirror
                 tool.  Keep in mind that you have to build these sources before
                 publishing them.  Simply start at
                 ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/www.</para>
             </listitem>
           </itemizedlist>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="other-info-sources">
           <para>What other sources of information are there?</para>
         </question>
 
         <answer>
           <para>The following newsgroups contain pertinent discussion for
             FreeBSD users:</para>
 
 
 
           <itemizedlist>
             <listitem>
               <para><ulink
                 URL="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</ulink>
                 (moderated)</para>
             </listitem>
 
             <listitem>
               <para><ulink
                 URL="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</ulink></para>
             </listitem>
 
             <listitem>
               <para><ulink
                 URL="news:comp.unix.bsd.misc">comp.unix.bsd.misc</ulink></para>
             </listitem>
           </itemizedlist>
 
           <para>Web resources:</para>
 
 
 
           <itemizedlist>
             <listitem>
               <para>The <ulink
                 URL="http://www.FreeBSD.org/">FreeBSD Home Page</ulink>.</para>
             </listitem>
 
             <listitem>
               <para><anchor id="pao">If you have a laptop, be sure and see
                 <ulink URL="http://www.jp.FreeBSD.org/PAO/">Tatsumi
                 Hosokawa's Mobile Computing page</ulink> in Japan.</para>
             </listitem>
 
             <listitem>
               <para><anchor id="smp">For information on SMP (Symmetric
                 MultiProcessing), please see the <ulink
                 URL="http://people.FreeBSD.org/~fsmp/SMP/SMP.html">SMP support page</ulink>.</para>
             </listitem>
 
             <listitem>
               <para><anchor id="multimedia">For information on FreeBSD
                 multimedia applications, please see the <ulink
                 URL="http://people.FreeBSD.org/~faulkner/multimedia/mm.html">multimedia</ulink>
                 page.  If you are interested specifically in the <ulink
                 URL="http://people.FreeBSD.org/~ahasty/Bt848.html">Bt848</ulink>
                 video capture chip, then follow that link.</para>
             </listitem>
           </itemizedlist>
 
           <para>The FreeBSD handbook also has a fairly complete <ulink
             URL="../handbook/bibliography.html">bibliography</ulink>
             section which is worth reading if you are looking for actual
             books to buy.</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 base support
             for a wide variety of hardware which needed more space, and
             thus for 3.x and 4.x we now use two floppy images, namely
             <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 accomodate 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 the section on
             <xref linkend="hardware" remap="Hardware compatibility"></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.  Newer versions of FreeBSD, like
             2.2, need at least 5MB to install on a new system.</para>
 
           <para>All versions of FreeBSD, including 3.0, will
-            <emphasis>run</emphasis> in 4MB of RAM, they just can not run the
+            <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 always just swap your
             disk into a system which has &gt;4MB, install onto it and then
             swap it back.</para>
 
           <para>There are also situations in which FreeBSD 2.1.7 will not
             install in 4 MB. To be exact: it does 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.</para>
 
           <para>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.</para>
 
           <para>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
             get the 4MB out again.</para>
 
           <para>You may 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 succeeded in booting with 2
             MB (the system was almost unusable though :-))</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
             <link linkend="custrel">here</link>.</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="http://www.FreeBSD.org/tutorials/multi-os/">
             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 CD-ROM) and choose the
+              <para>Boot the FreeBSD boot floppy (or CDROM) and choose the
                 <quote>Fixit</quote> menu item. Select either the Fixit
-                floppy or CD-ROM #2 (the <quote>live</quote> file system
+                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><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 by 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="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 coverdisk 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 OS's 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 CD-ROM, but the install program says no
-            CD-ROM is found.  Where did it go?</para>
+          <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 CD-ROM
-            drive.  Many PCs now ship with the CD-ROM as the slave device on
+          <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  CD-ROM to boot from it, but why FreeBSD can not see it 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 CD-ROM is either the
+          <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>Connect the two computers using a Laplink parallel cable
             to use this feature:</para>
 
           <table>
             <title>Wiring a parallel cable for networking</title>
 
             <tgroup cols="5">
               <thead>
                 <row>
                   <entry>A-name</entry>
 
                   <entry>A-End</entry>
 
                   <entry>B-End</entry>
 
                   <entry>Descr.</entry>
 
                   <entry>Post/Bit</entry>
                 </row>
               </thead>
 
               <tbody>
                 <row>
                   <entry><literallayout>DATA0
 -ERROR</literallayout></entry>
 
                   <entry><literallayout>2
 15</literallayout></entry>
 
                   <entry><literallayout>15
 2</literallayout></entry>
 
                   <entry>Data</entry>
 
                   <entry><literallayout>0/0x01
 1/0x08</literallayout></entry>
                 </row>
 
                 <row>
                   <entry><literallayout>DATA1
 +SLCT</literallayout></entry>
 
                   <entry><literallayout>3
 13</literallayout></entry>
 
                   <entry><literallayout>13
 3</literallayout></entry>
 
                   <entry>Data</entry>
 
                   <entry><literallayout>0/0x02
 1/0x10</literallayout></entry>
                 </row>
 
                 <row>
                   <entry><literallayout>DATA2
 +PE</literallayout></entry>
 
                   <entry><literallayout>4
 12</literallayout></entry>
 
                   <entry><literallayout>12
 4</literallayout></entry>
 
                   <entry>Data</entry>
 
                   <entry><literallayout>0/0x04
 1/0x20</literallayout></entry>
                 </row>
 
                 <row>
                   <entry><literallayout>DATA3
 -ACK</literallayout></entry>
 
                   <entry><literallayout>5
 10</literallayout></entry>
 
                   <entry><literallayout>10
 5</literallayout></entry>
 
                   <entry>Strobe</entry>
 
                   <entry><literallayout>0/0x08
 1/0x40</literallayout></entry>
                 </row>
 
                 <row>
                   <entry><literallayout>DATA4
 BUSY</literallayout></entry>
 
                   <entry><literallayout>6
 11</literallayout></entry>
 
                   <entry><literallayout>11
 6</literallayout></entry>
 
                   <entry>Data</entry>
 
                   <entry><literallayout>0/0x10
 1/0x80</literallayout></entry>
                 </row>
 
                 <row>
                   <entry>GND</entry>
 
                   <entry>18-25</entry>
 
                   <entry>18-25</entry>
 
                   <entry>GND</entry>
 
                   <entry>-</entry>
                 </row>
               </tbody>
             </tgroup>
           </table>
 
           <para>See also <link linkend="pao">this note</link> on the
             Mobile Computing page.</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 - I 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 seems to cause a lot of confusion for some reason.
             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>quote</quote> physical geometry is usually the
             geometry that they have worked out results in the least wasted
             space. For IDE disks, FreeBSD does work in terms of C/H/S, but
             all modern drives will convert this into block references
             internally as well.</para>
 
           <para>All that matters is the <emphasis>logical</emphasis>
             geometry - the answer that the BIOS gets when it asks
             <quote>what is your geometry?</quote> and then uses 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 (*not* 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 correct geometry should then be detected (and you can
             always remove the DOS partition in the partition editor if you
             do not want to keep it, or leave it around for programming
             network cards and the like).</para>
 
           <para>Alternatively, there is a freely available utility
             distributed with FreeBSD called <filename>pfdisk.exe</filename>
             (located in the <filename>tools</filename> subdirectory on the
             FreeBSD CDROM or on the various FreeBSD ftp sites) which 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
+            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; manpage 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 vice 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 maxiumum 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="tb-on-floppy">
           <para>How can I put 1TB files on my floppy?</para>
         </question>
 
         <answer>
           <para>I keep several virtual ones on floppies :-).  The maxiumum
             file size is not closely related to the maximum disk size. The
             maximum disk size is 1TB. It is a feature that the file size
             can be larger than the disk size.</para>
 
           <para>The following example creates a file of size 8T-1 using a
             whole 32K of disk space (3 indirect blocks and 1 data block) on
             a small root partition. The dd command requires a dd that works
             with large files.</para>
 
           <screen>&prompt.user; <userinput>cat foo</userinput>
 df .
 dd if=/dev/zero of=z bs=1 seek=`echo 2^43 - 2 | bc` count=1
 ls -l z
 du z
 df .
 &prompt.user; <userinput>sh foo</userinput>
 Filesystem  1024-blocks     Used    Avail Capacity  Mounted on
 /dev/da0a         64479    27702    31619    47%    /
 1+0 records in
 1+0 records out
 1 bytes transferred in 0.000187 secs (5346 bytes/sec)
 -rw-r--r--  1 bde  bin  8796093022207 Sep  7 16:04 z
 32        z
 Filesystem  1024-blocks     Used    Avail Capacity  Mounted on
 /dev/da0a         64479    27734    31587    47%    /</screen>
 
           <para>Bruce Evans, September 1998</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/">releng4.FreeBSD.org</ulink>.</para>
 
           <para>If you wish to upgrade using source, please see the <ulink
             URL="http://www.FreeBSD.org/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.  The more severe the security profile, the less
             programs will be enabled by default; this is one of the basic
             principles of security: do not run anything except what you
             must.</para>
 
           <para>Please note that the security profile is just a default
             setting.  All programs can be enabled and disabled after you have
             installed FreeBSD by editing or adding the appropriate line(s)
             to <filename>/etc/rc.conf</filename>.  For more information on
             the latter, please see the &man.rc.conf.5; manual page.</para>
 
           <para>Following is a table that describes what each security
             profile does.  The columns are the choices you have for a
             security profile, and the rows are the program or feature that
             is enabled or disabled.</para>
 
           <table>
             <title>Possible security profiles</title>
 
              <tgroup cols=5>
                <thead>
                  <row>
                    <entry></entry>
 
                    <entry>Extreme</entry>
 
                    <entry>High</entry>
 
                    <entry>Moderate</entry>
 
                    <entry>Low</entry>
                  </row>
                </thead>
 
                <tbody>
                  <row>
                    <entry>&man.inetd.8;</entry>
 
                    <entry>NO</entry>
 
                    <entry>NO</entry>
 
                    <entry>YES</entry>
 
                    <entry>YES</entry>
                  </row>
 
                  <row>
                    <entry>&man.sendmail.8;</entry>
 
                    <entry>NO</entry>
 
                    <entry>YES</entry>
 
                    <entry>YES</entry>
 
                    <entry>YES</entry>
                  </row>
 
                  <row>
                    <entry>&man.sshd.8;</entry>
 
                    <entry>NO</entry>
 
                    <entry>YES</entry>
 
                    <entry>YES</entry>
 
                    <entry>YES</entry>
                  </row>
 
                  <row>
                    <entry>&man.portmap.8;</entry>
 
                    <entry>NO</entry>
 
                    <entry>NO</entry>
 
 		<entry>MAYBE <footnote>
 		    <para>The portmapper is enabled if the machine has been
 		      configured as an NFS client or server earlier in the
 		      installation.</para>
 		  </footnote>
 		</entry>
 
                    <entry>YES</entry>
                  </row>
 
                  <row>
                    <entry>NFS server</entry>
 
                    <entry>NO</entry>
 
                    <entry>NO</entry>
 
                    <entry>YES</entry>
 
                    <entry>YES</entry>
                  </row>
 
                  <row>
                    <entry>&man.securelevel.8;</entry>
 
 		  <entry>YES (2) <footnote>
 		      <para>If you choose a security profile that sets the
 			securelevel (Extreme or High), you must be aware of the
 			implications.  Please read the &man.init.8; manual page
 			and pay particular attention to the meanings of the
 			security levels, or you may have significant trouble
 			later!</para>
 		      </footnote>
 		      </entry>
 
                    <entry>YES (1)</entry>
 
                    <entry>NO</entry>
 
                    <entry>NO</entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
 
              <warning>
                <para>The security profile is not a silver bullet!  Setting
                  it high does not mean you do not have to keep up with security
                  issues by reading an appropriate <ulink
                  url="../handbook/eresources.html#ERESOURCES-MAIL">mailing
                  list</ulink>, using good passwords and passphrases, and
                  generally adhering to good security practices.  It simply
                  sets up the desired security to convenience ratio out of
                  the box.</para>
              </warning>
 
              <note>
                <para>The security profile mechanism is meant to be used
                  when you first install FreeBSD.  If you already have
                  FreeBSD installed, it would probably be more beneficial to
                  simply enable or disable the desired functionality.  If
                  you really want to use a security profile, you can re-run
                  &man.sysinstall.8; to set it.</para>
              </note>
         </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 <email>freebsd-sparc@FreeBSD.org</email> <link
             linkend="mailing"> mailing list</link> if you are interested
             in joining that project.  Most recent additions to the list of
             upcoming platforms are IA-64 and PowerPC, join the
             <email>freebsd-ia64@FreeBSD.org</email> and/or
             <email>freebsd-ppc@FreeBSD.org</email> <link
             linkend="mailing">mailing lists</link> for more information.
             For general discussion on new architectures, join
             the <email>freebsd-platforms@FreeBSD.org</email>
             <link linkend="mailing">mailing list</link>.</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="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 <ulink
             URL="../handbook/install.html#INSTALL-HW">Handbook</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="supported-cdrom-drives">
-          <para>Which CD-ROM drives are supported by FreeBSD?</para>
+          <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 CD-ROM interfaces are also
+          <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 CD-ROM</para>
+                <para>Sound Blaster Non-SCSI CDROM</para>
               </listitem>
 
               <listitem>
-                <para>Matsushita/Panasonic CD-ROM</para>
+                <para>Matsushita/Panasonic CDROM</para>
               </listitem>
 
               <listitem>
-                <para>ATAPI compatible IDE CD-ROMs</para>
+                <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">this note on removable
             drives</link>, and <link linkend="disklabel">this note on
             <quote>formatting</quote></link>.</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 the 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-hw.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 existence
             of the 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>USB device support was added to FreeBSD 3.1.  However, it
             is still in a preliminary state and may not always work as of
             version 3.2. If you want to experiment with the USB mouse
             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  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>.  And check out
             <link linkend="pao">this note</link> on the Mobile Computing
             page.</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
-                CD-ROMs, SCSI or joysticks on these cards, except for the
+                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-hw.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 it's 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>How come FreeBSD cannot find 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="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 doesn't my 3Com PCI network card 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>How come FreeBSD does 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>How come FreeBSD does 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 can not use a
+              <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's 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="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.  By default,
             &man.mount.8;
             will assume the filesystem is of type <literal>ufs</literal>.
             You want to mount a CDROM filesystem, and you do this by
             specifying the <option>-t cd9660</option> option to
             &man.mount.8;.  This does, of course, assume that the
             CDROM contains an ISO 9660 filesystem, which is what most CDROMs
             have.  As of 1.1R, FreeBSD automatically understands the Rock
             Ridge (long filename) extensions as well.</para>
 
           <para>As an example, if you want to mount the CDROM device,
             <devicename>/dev/cd0c</devicename>, under <filename>/mnt</filename>,
             you would execute:</para>
 
           <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0c /mnt</userinput></screen>
 
           <para>Note that your device name (<devicename>/dev/cd0c</devicename>
             in this example) could be different, depending on the CDROM
             interface. Note that the <option>-t cd9660</option> option just
             causes the &man.mount.cd9660.8; command to be
             executed, and so the above example could be shortened
             to:</para>
 
           <screen>&prompt.root; <userinput>mount_cd9660 /dev/cd0c /mnt</userinput></screen>
         </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. Feed the drive
             something, and/or check its master/slave status if it is IDE
             (ATAPI). It can take a couple of seconds for a CDROM drive to
             notice that it has been fed, so be patient.</para>
 
-          <para>Sometimes a SCSI CD-ROM may be missed because it had not
-            enough time to answer the bus reset. If you have a SCSI CD-ROM
+          <para>Sometimes a SCSI CDROM may be missed because it had not
+            enough time to answer the bus reset. If you have a SCSI CDROM
             please try to add the following symbol into your kernel
             configuration file and recompile.</para>
 
           <programlisting>options "SCSI_DELAY=15"</programlisting>
         </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>Most likely your CDROM uses the <quote>Joliet</quote>
             extension for storing information about files and directories.
             This extension specifies that all filenames are stored using
             Unicode two-byte characters.  Currently, efforts are under way
             to introduce a generic Unicode interface into the FreeBSD
             kernel, but since that is not ready yet, the CD9660 driver does
             not have the ability to decode the characters in the
             filenames.</para>
 
           <para>As a temporary solution, starting with FreeBSD 4.3, a
             special hook has been added into the CD9660 driver to allow the
             user to load an appropriate conversion table on the fly.
             Modules for some of the common encodings are available via the
             <filename>sysutils/cd9660_unicode</filename> port.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="printer-slow">
           <para>My printer is ridiculously slow. What can I do?</para>
         </question>
 
         <answer>
           <para>If it is parallel, and the only problem is that it is terribly
             slow, try setting your printer port into <quote>polled</quote>
             mode:</para>
 
           <screen>&prompt.root; <userinput>lptcontrol -p</userinput></screen>
 
           <para>Some newer HP printers are claimed not to work correctly in
             interrupt mode, apparently due to some (not yet exactly
             understood) timing problem.</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 *not* 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 ls.c in to ls.o. If
             you next 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="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>How come FreeBSD uses only 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="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="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 doesn't 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
             timekeeping.</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 has a lot
             of work has been done to make the 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,
             aren't you?) 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="file-table-full">
           <para>Why does <errorname>file: table is full</errorname> show up
             repeatedly in dmesg?</para>
         </question>
         <answer>
           <para>
             This error is caused when you have exhausted the number of
             available file descriptors on your system.  The file table in
             memory is full.
           </para>
           <para>The solution:</para>
           <para>
             Manually adjust the <varname>kern.maxfiles</varname> kernel limit
             setting.
           </para>
           <screen>&prompt.root; <userinput>sysctl -w kern.maxfiles=n</userinput></screen>
           <para>Adjust <varname>n</varname> according to your system needs.
             Each open file, socket, or fifo uses one file descriptor.
             A large-scale server may easily require tens of thousands of
             file descriptors (10,000+), depending on the kind and number
             of services running concurrently.</para>
           <para>The number of default file descriptors set in the kernel is
             dictated by the</para>
           <programlisting>maxusers        32</programlisting>
           <para><varname>maxusers</varname> line in your kernel
             config file.  Increasing this will proportionally increase
             <varname>kern.maxfiles</varname>.
           </para>
           <para>You can see what <varname>kern.maxfiles</varname> is
             currently set to by:
           </para>
           <screen>&prompt.root; <userinput>sysctl kern.maxfiles</userinput>
 kern.maxfiles: 1064</screen>
         </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
 	    <literal>kern.timecounter.hardware</literal>
 	      &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
 	    <literal>kern.timecounter.hardware</literal>
 	      &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>
     </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="http://www.FreeBSD.org/commercial/commercial.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>You can purchase ApplixWare for FreeBSD <ulink
  	        url="http://www.wccdrom.com/titles/freebsd/applix.phtml">here</ulink>.
                 </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>developement
             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="http://www.FreeBSD.org/ports/">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>
             sells 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="http://www.FreeBSD.org/commercial/software_bycat.html#CATEGORY_DATABASE">
             Commercial Vendors</ulink> section of FreeBSD's Web site.</para>
 
           <para>Also see the <ulink
             URL="http://www.FreeBSD.org/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="http://www.FreeBSD.org/ports/">the ports
             page</ulink> for info on software packages ported to FreeBSD.
             The list currently tops 3400 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="minimal-sh">
           <para>Why is <command>/bin/sh</command> so minimal?  Why doesn't
             FreeBSD 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="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 inn 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 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="http://www.FreeBSD.org/java/">
             http://www.FreeBSD.org/java/</ulink>.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ports-3x">
           <para>Why can't I 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="http://www.FreeBSD.org/ports/">
             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>If you want to run some aout applications like
             Netscape Navigator on an Elf'ened machine such as 3.1-R or
             later, it would need <filename>/usr/libexec/ld.so</filename>
             and some aout libs. They are included in the compat22
             distribution. Use <filename>/stand/sysinstall</filename> or
             <filename>install.sh</filename> in the compat22 subdirectory
             and install it. Also read ERRATAs for 3.1-R and 3.2-R.</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>Unfortunately, there is no easy way to update installed
             ports. The &man.pkg.version.1; command can be used
             to generate a script that will update the installed ports with
             a newer 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 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>
     </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>It is recommended that you make a dated snapshot
 	        of your kernel
                 in <filename>kernel.YYMMDD</filename> after you get it all
                 working, that way if you do something dire the next time
                 you play with your configuration you can boot that kernel
                 instead of having to go all the way back to
                 <filename>kernel.GENERIC</filename>. This is particularly
                 important if you are now booting off a controller that is not
                 supported in the GENERIC kernel.</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="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="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="../tutorials/formatting-media/">
             www.FreeBSD.org</ulink>.</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="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="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="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="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="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
             harddisk(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 BIOSsen, including those from
             AWARD (eg. 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's 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="add-swap-space">
           <para>How can I add more swap space?</para>
         </question>
 
         <answer>
 
           <para>The best way is to increase the size of your swap partition,
             or take advantage of this convenient excuse to add another
             disk. The general rule of thumb is to have around 2x the swap
             space as you have main memory. However, if you have a very
             small amount of main memory you may want to configure swap
             beyond that. It is also a good idea to configure sufficient
             swap relative to anticipated future memory upgrades so you do
             not have to futz with your swap configuration later.</para>
 
           <para>Adding swap onto a separate disk makes things faster than
             simply adding swap onto the same disk. As an example, if you
             are compiling source located on one disk, and the swap is on
             another disk, this is much faster than both swap and compile on
             the same disk. This is true for SCSI disks specifically.</para>
 
           <para>When you have several disks, configuring a swap partition on
             each one is usually beneficial, even if you wind up putting
             swap on a work disk. Typically, each fast disk in your system
             should have some swap configured. FreeBSD supports up to 4
             interleaved swap devices by default. When configuring multiple
             swap partitions you generally want to make them all about the
             same size, but people sometimes make their primary swap
             partition larger in order to accomodate a kernel core dump. Your
             primary swap partition must be at least as large as main memory
             in order to be able to accomodate a kernel core.</para>
 
           <para>IDE drives are not able to allow access to both drives on
             the same channel at the same time (FreeBSD does not support mode
             4, so all IDE disk I/O is <quote>programmed</quote>).
 	    It is still suggested that you put your swap partition on a
 	    separate driver, however: the drives are so cheap, it is not
 	    worth worrying about.</para>
 
           <para>Swapping over NFS is only recommended if you do not have a
             local disk to swap to. Swapping over NFS is slow and
             inefficient in FreeBSD releases prior to 4.x, but reasonably
             fast in releases greater or equal to 4.0. Even so, it will be
             limited to the network bandwidth available and puts an
             additional burden on the NFS server.</para>
 
           <para>Here is an example for 64Mb vn-swap
             (<filename>/usr/swap0</filename>, though of course you can use
             any name that you want).</para>
 
           <para>Make sure your kernel was built with the line</para>
 
           <programlisting>pseudo-device   vn 1   #Vnode driver (turns a file into a device)</programlisting>
 
           <para>in your config-file.  The GENERIC kernel already contains
             this.</para>
 
 	  <orderedlist>
 	    <listitem>
 	      <para>create a vn-device</para>
 	      <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV vn0</userinput></screen>
 	    </listitem>
 
 	    <listitem>
 	      <para>create a swapfile (<filename>/usr/swap0</filename>)</para>
 
 	      <screen>&prompt.root; <userinput>dd if=/dev/zero of=/usr/swap0 bs=1024k count=64</userinput></screen>
 	    </listitem>
 
 	    <listitem>
 	      <para>set proper permissions on (<filename>/usr/swap0</filename>)</para>
 
 	      <screen>&prompt.root; <userinput>chmod 0600 /usr/swap0</userinput></screen>
 	    </listitem>
 
 	    <listitem>
 	      <para>enable the swap file in <filename>/etc/rc.conf</filename></para>
 
 	      <programlisting>swapfile="/usr/swap0"   # Set to name of swapfile if aux swapfile desired.</programlisting>
 	    </listitem>
 
 	    <listitem>
 	      <para>reboot the machine</para>
 	    </listitem>
 	  </orderedlist>
 
           <para>To enable the swap file immediately, type</para>
 
           <screen>&prompt.root; <userinput>vnconfig -e /dev/vn0b /usr/swap0 swap</userinput></screen>
         </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>ports/print/pnm2ppa</filename> port supports it.
 	    From <ulink
 	    url="http://www.freebsd.org/cgi/url.cgi?ports/print/pnm2ppa/pkg-descr">its
 	    package description</ulink>:</para>
 
 	  <blockquote>
 	    <para>This software creates output using the PPA (printer
 	      performance architecture) protocol.  This protocol is used by
 	      some HP "Windows-only" printers, including the HP Deskjet
 	      820C series, the HP DeskJet 720 series, and the HP DeskJet
 	      1000 series.  [...]</para>
 
 	    <para>WWW: <ulink
 	      url="http://pnm2ppa.sourceforge.net/">http://pnm2ppa.sourceforge.net/</ulink></para>
 	  </blockquote>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="keyboard-mappings">
           <para>How can I correct the keyboard mappings for my system?</para>
         </question>
 
         <answer>
           <para>The kbdcontrol program has an option to load a keyboard
             map file. Under <filename>/usr/share/syscons/keymaps</filename>
             are a number of map files. Choose the one relevant to your
             system and load it.</para>
 
           <screen>&prompt.root; <userinput>kbdcontrol -l uk.iso</userinput></screen>
 
           <para>Both the <filename>/usr/share/syscons/keymaps</filename>
             and the <filename>.kbd</filename> extension are assumed by
             &man.kbdcontrol.1;.</para>
 
           <para>This can be configured in <filename>/etc/sysconfig</filename>
             (or
             &man.rc.conf.5;).  See the appropriate comments in this
             file.</para>
 
           <para>In 2.0.5R and later, everything related to text fonts,
             keyboard mapping is in
             <filename>/usr/share/examples/syscons</filename>.</para>
 
           <para>The following mappings are currently supported:</para>
 
             <itemizedlist>
               <listitem>
                 <para>Belgian ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>Brazilian 275 keyboard Codepage 850</para>
               </listitem>
 
               <listitem>
                 <para>Brazilian 275 keyboard ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>Danish Codepage 865</para>
               </listitem>
 
               <listitem>
                 <para>Danish ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>French ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>German Codepage 850</para>
               </listitem>
 
               <listitem>
                 <para>German ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>Italian ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>Japanese 106</para>
               </listitem>
 
               <listitem>
                 <para>Japanese 106x</para>
               </listitem>
 
               <listitem>
                 <para>Latin American</para>
               </listitem>
 
               <listitem>
                 <para>Norwegian ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>Polish ISO-8859-2 (programmer's)</para>
               </listitem>
 
               <listitem>
                 <para>Russian Codepage 866 (alternative)</para>
               </listitem>
 
               <listitem>
                 <para>Russian koi8-r (shift)</para>
               </listitem>
 
               <listitem>
                 <para>Russian koi8-r</para>
               </listitem>
 
               <listitem>
                 <para>Spanish ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>Swedish Codepage 850</para>
               </listitem>
 
               <listitem>
                 <para>Swedish ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>Swiss-German ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>United Kingdom Codepage 850</para>
               </listitem>
 
               <listitem>
                 <para>United Kingdom ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>United States of America ISO-8859-1</para>
               </listitem>
 
               <listitem>
                 <para>United States of America dvorak</para>
               </listitem>
 
               <listitem>
                 <para>United States of America dvorakx</para>
               </listitem>
             </itemizedlist>
         </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>How come I cannot 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="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't I 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's 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="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
 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 CD-ROM mounted, do:</para>
+            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/sendmail.cf</userinput></screen>
 
           <para>A typical <filename>.mc</filename> file might look
             like:</para>
 
 
           <programlisting>include(`../m4/cf.m4')
 VERSIONID(`<replaceable>Your version number</replaceable>')
 OSTYPE(bsd4.4)
 
 FEATURE(nodns)
 FEATURE(nocanonify)
 FEATURE(mailertable)
 
 define(`UUCP_RELAY', <replaceable>your.uucp.relay</replaceable>)
 define(`UUCP_MAX_SIZE', 200000)
 
 MAILER(local)
 MAILER(smtp)
 MAILER(uucp)
 
 Cw    <replaceable>your.alias.host.name</replaceable>
 Cw    <replaceable>youruucpnodename.UUCP</replaceable></programlisting>
 
           <para>The <literal>nodns</literal> and
             <literal>nocanonify</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/mailertable</filename>.  A typical example of
             this gender again:</para>
 
           <programlisting>#
 # makemap hash /etc/mailertable.db &lt; /etc/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>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>0 foo@interface-business.de</userinput>
 rewrite: ruleset  0   input: foo @ interface-business . de
 ...
 rewrite: ruleset  0 returns: $# uucp-dom $@ if-bus $: foo \
 &lt; @ interface-business . de &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
+            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 <application>ppp</application> connection to the
-            internet, you will probably be given a mailbox on your ISPs
+            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>Needless to say, 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, don't forget to
             restart <application>sendmail</application> after updating <filename>sendmail.cf</filename>.</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="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>
+          <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>How come I cannot 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 than 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
+          <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 can not modify the address
+          <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
+          <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="http://www.FreeBSD.org/search/">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="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,
+                <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>vfs.usermount=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
+            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="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="http://www.freebsd.org/tutorials/formatting-media/index.html">
             formatting-media tutorial</ulink> for details on this
             process.</para>
 
           <para>Now you have got 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>) and symbolic links tend to
             screw that up.  You need to use tools that understand
             these things, which means &man.dump.8; and &man.tar.1;.
 	    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</userinput>
 &prompt.root; <userinput>cd /mnt</userinput>
 &prompt.root; <userinput>dump 0uaf - / | restore xf -</userinput></screen>
 
 
           <para>If you are going to rearrange your partitions -
             say, splitting one into two, or combing two into one,
             you may find yourself needing to move everything under
             a subdirectory to a new location.  Since &man.dump.8;
             works with file systems, it cannot do this.  So you use
             &man.tar.1;.  The general command to move
             <filename>/old</filename> to <filename>/new</filename>
             for &man.tar.1; is:</para>
 
           <screen>&prompt.root; <userinput>(cd /old; tar cf - .) | (cd /new; tar xpf -)</userinput></screen>
 
           <para>If <filename>/old</filename> has file systems
             mounted on that, and you
             do not want to move that data or unmount them, you just
             add the 'l' flag to the first &man.tar.1;:</para>
 
           <screen>&prompt.root; <userinput>(cd /old; tar clf - .) | (cd /new; tar xpf -).</userinput></screen>
 
           <para>You might prefer &man.cpio.1;, &man.pax.1;, or cpdup
             (in ports/sysutils/cpdup) to &man.tar.1;.</para>
         </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 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't I 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 doesn't SSH authentication through
 	    <filename>.shosts</filename> 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>
     </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(tm) 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 doesn't my mouse 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
                       automatic protocol recognition and button mapping
                       Translation</title>
 
                     <programlisting>Section "InputDevice"
    Identifier      "Mouse1"
    Driver          "mouse"
    Option          "Protocol" "auto"
    Option          "Device" "/dev/psm0"
    Option          "Buttons" "5"
    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>
 
                 <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>
                 </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
                 keypresses 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 virtualterminal 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 don't,
             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 popup 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>How come my PS/2 mouse from MouseSystems does not seem
             to 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="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 Windows(tm) 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>Windows(tm)</quote> keyboards are
             standard then the keycodes for the 3 keys are</para>
 
           <itemizedlist>
             <listitem>
               <para>115 - Windows(tm) key, between the left-hand Ctrl and
                 Alt keys</para>
             </listitem>
 
             <listitem>
               <para>116 - Windows(tm) 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 Windows(tm) 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 Windows(tm) 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>
     </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>Internet standards and good engineering practice prohibit
             us from providing packet forwarding by default in FreeBSD. You
             can however enable this feature by changing the following
             variable to <literal>YES</literal> in
             &man.rc.conf.5;:</para>
 
           <programlisting>gateway_enable=YES          # Set to YES if this host will be a gateway</programlisting>
 
           <para>This option will put the
             &man.sysctl.8; variable
             <filename>net.inet.ip.forwarding</filename>
             to <literal>1</literal>.</para>
 
           <para>In most cases, you will also need to run a routing process
             to tell other systems on your network about your router;
             FreeBSD comes with the standard BSD routing daemon
             &man.routed.8;
             or for more complex situations you may want to try
             <application>GaTeD</application> (available from <ulink
             URL="http://www.gated.org/">http://www.gated.org/</ulink>)
             which supports FreeBSD as of 3_5Alpha7.</para>
 
           <para>It is our duty to warn you that, even when FreeBSD is
             configured in this way, it does not completely comply with
             the Internet standard requirements for routers; however,
             it comes close enough for ordinary usage.</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 ppp contains a <option>-nat</option> option. If
             you run <application>ppp</application> 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="http://www.FreeBSD.org/tutorials/ppp/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="latest-bind">
           <para>Why does recompiling the latest BIND from ISC fail?</para>
         </question>
 
         <answer>
           <para>There is a conflict between the
             <filename>cdefs.h</filename> file in the distribution and the
             one shipped with FreeBSD. Just remove
             <filename>compat/include/sys/cdefs.h</filename>.</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
             <application>slirp</application> 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
+            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>Get a laplink cable. Make sure both computer have a kernel
             with lpt driver support.</para>
 
           <screen>&prompt.root; <userinput>dmesg | grep lp</userinput>
 lpt0 at 0x378-0x37f irq 7 on isa
 lpt0: Interrupt-driven
 lp0: TCP/IP capable interface</screen>
 
           <para>Plug in the laplink cable into the parallel interface.</para>
 
           <para>Configure the network interface parameters for lp0 on both
             sites as root. For example, if you want connect the host max
             with moritz</para>
 
           <programlisting>                 max &lt;-----&gt; moritz
 IP Address    10.0.0.1      10.0.0.2</programlisting>
 
           <para>on max start</para>
 
             <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.1 10.0.0.2</userinput></screen>
 
           <para>on moritz start</para>
 
           <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.2 10.0.0.1</userinput></screen>
 
 
           <para>Thats all! Please read also the manpages
             &man.lp.4; and &man.lpt.4; .</para>
 
           <para>You should also add the hosts to
             <filename>/etc/hosts</filename>.</para>
 
           <programlisting>127.0.0.1               localhost.my.domain localhost
 10.0.0.1                max.my.domain max
 10.0.0.2                moritz.my.domain</programlisting>
 
 
           <para>To check if it works do:</para>
 
           <para>on max:</para>
 
 
           <screen>&prompt.root; <userinput>ifconfig lp</userinput>0
 lp0: flags=8851&lt;UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
         inet 10.0.0.1 --&gt; 10.0.0.2 netmask 0xff000000
 &prompt.root; <userinput>netstat -r</userinput>
 Routing tables
 
 Internet:
 Destination        Gateway          Flags     Refs     Use      Netif Expire
 moritz             max              UH          4   127592       lp0
 &prompt.root; <userinput>ping -c 4 moritz</userinput>
 PING moritz (10.0.0.2): 56 data bytes
 64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
 
 --- moritz ping statistics ---
 4 packets transmitted, 4 packets received, 0% packet loss
 round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms</screen>
 
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="create-dev-net">
           <para>How come I cannot create a <devicename>/dev/ed0</devicename>
             device?</para>
         </question>
 
         <answer>
 
           <para>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 setup Ethernet aliases?</para>
         </question><answer>
 
           <para>Add <literal>netmask 0xffffffff</literal> to your
             &man.ifconfig.8; command-line like the following:</para>
 
           <screen>&prompt.root; <userinput>ifconfig ed0 alias 204.141.95.2 netmask 0xffffffff</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't I 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't I 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 this
             passage from the &man.exports.5; manual page
             correctly:</para>
 
           <blockquote>
             <para>Each line in the file (other than comment
               lines that begin with a #) specifies the mount point(s)
               and export flags within one local server filesystem for
               one or more hosts.  A host may be specified only once
               for each local filesystem on the server and there may be
               only one default entry for each server filesystem that
               applies to all other hosts.</para>
           </blockquote>
 
           <para>This is made more clear by an example of a common
             mistake. If everything above <filename>/usr</filename> is
             part of one filesystem (there are no mounts above
             <filename>/usr</filename>) the following exports list is
             not valid:</para>
 
           <programlisting>/usr/src   client
 /usr/ports client</programlisting>
 
           <para>There are two lines specifying properties for one
             filesystem, <filename>/usr</filename>, exported to the
             same host, <hostid>client</hostid>. The correct format
             is:</para>
 
           <programlisting>/usr/src /usr/ports  client</programlisting>
 
           <para>To rephrase the passage from the manual page, the
             properties of one filesystem exported to a given host
             (world-wide exports are treated like another unique host)
             must all occur on one line. And yes, this does cause
             limitation in how you can export filesystems without ugly
             workarounds, but for most people, this is not an
             issue.</para>
 
           <para>The following is an example of a valid export list,
             where <filename>/usr</filename> and
             <filename>/exports</filename> are local
             filesystems:</para>
 
           <programlisting># Export src and ports to client01 and client02, but only
 # client01 has root privileges on it
 /usr/src /usr/ports -maproot=0    client01
 /usr/src /usr/ports               client02
 # The "client" machines have root and can mount anywhere
 # up /exports. The world can mount /exports/obj read-only
 /exports -alldirs -maproot=0      client01 client02
 /exports/obj -ro</programlisting>
         </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,
             mbone.  If you are looking for the conference tools
             <command>vic</command> and <command>vat</command>,
             look there!</para>
 
           <para>For more information, see the <ulink
             URL="http://www.mbone.com/">Mbone Information Web</ulink>.</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.bar.edu and
             you wish to reach a host called <hostid>mumble</hostid> in the
             <hostid role="domainname">bar.edu</hostid> domain, you will
             have to refer to it by the fully-qualified domain name, <hostid
             role="fqdn">mumble.bar.edu</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.bar.edu</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.bar.edu</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.bar.edu bar.edu</programlisting>
 
           <para>instead of the previous</para>
 
           <programlisting>domain foo.bar.edu</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>The answer to this depends mostly on your rule set and
             processor speed. For most applications dealing with ethernet
             and small rule sets, the answer is, negligible. For those of
             you that need actual measurements to satisfy your curiosity,
             read on.</para>
 
           <para>The following measurements were made using 2.2.5-STABLE
             on a 486-66.  IPFW was modified to measure the time spent
             within the <literal>ip_fw_chk</literal> routine, displaying
             the results to the console every 1000 packets.</para>
 
           <para>Two rule sets, each with 1000 rules were tested.  The
             first set was designed to demonstrate a worst case scenario
             by repeating the rule:</para>
 
           <screen>&prompt.root; <userinput>ipfw add deny tcp from any to any 55555</userinput></screen>
 
           <para>This demonstrates worst case by causing most of IPFW's
             packet check routine to be executed before finally deciding
             that the packet does not match the rule (by virtue of the port
             number). Following the 999th iteration of this rule was an
             <literal>allow ip from any to any</literal>.</para>
 
           <para>The second set of rules were designed to abort the rule
             check quickly:</para>
 
           <screen>&prompt.root; <userinput>ipfw add deny ip from 1.2.3.4 to 1.2.3.4</userinput></screen>
 
           <para>The nonmatching source IP address for the above rule causes
             these rules to be skipped very quickly.  As before, the 1000th
             rule was an <literal>allow ip from any to any</literal>.</para>
 
           <para>The per-packet processing overhead in the former case was
             approximately 2.703ms/packet, or roughly 2.7 microseconds per
             rule. Thus the theoretical packet processing limit with these
             rules is around 370 packets per second. Assuming 10Mbps
             ethernet and a ~1500 byte packet size, we would only be able to
             achieve a 55.5% bandwidth utilization.</para>
 
           <para>For the latter case each packet was processed in
             approximately 1.172ms, or roughly 1.2 microseconds per rule.
             The theoretical packet processing limit here would be about
             853 packets per second, which could consume 10Mbps ethernet
             bandwidth.</para>
 
           <para>The excessive number of rules tested and the nature of
             those rules do not provide a real-world scenario -- they were
             used only to generate the timing information presented here.
             Here are a few things to keep in mind when building an
             efficient rule set:</para>
 
             <itemizedlist>
               <listitem>
                 <para>Place an <literal>established</literal> rule early
                   on to handle the majority of TCP traffic.  Do not put any
                   <literal>allow tcp</literal> statements before this
                   rule.</para>
               </listitem>
 
               <listitem>
                 <para>Place heavily triggered rules earlier in the rule
                   set than those rarely used (<emphasis>without
                   changing the permissiveness of the firewall</emphasis>,
                   of course).  You can see which rules are used most often
                   by examining the packet counting statistics with
                   <command>ipfw -a l</command>.</para>
               </listitem>
             </itemizedlist>
         </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/">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 commandline to call socket instead, like so:</para>
 
           <programlisting>ftp stream tcp nowait nobody /usr/local/bin/socket socket <replaceable>ftp.foo.com</replaceable> <replaceable>ftp</replaceable></programlisting>
 
           <para>where <replaceable>ftp.foo.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 two bandwidth management tools available for
             FreeBSD. <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="extra-named-port">
 	  <para>BIND (<command>named</command>) is listening on port 53 and
 	    some other high-numbered port.  Has my host been
 	    compromised?</para>
 	</question>
 
 	<answer>
 	  <para>Probably not.  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="bpf-not-configured">
           <para>Why do I get <literal>/dev/bpf0: device not
             configured</literal>?</para>
         </question>
 
         <answer>
           <para>The Berkeley Packet Filter (&man.bpf.4;)
             driver needs to be enabled before running programs that
             utilize it.  Add this to your kernel config file and build
             a new kernel:</para>
 
           <programlisting>pseudo-device bpfilter        # Berkeley Packet Filter</programlisting>
 
           <para>Secondly, after rebooting you will have to create the
             device node. This can be accomplished by a change to the
             <filename>/dev</filename> directory, followed by the execution
             of:</para>
 
           <screen>&prompt.root; <userinput>sh MAKEDEV bpf0</userinput></screen>
 
           <para>Please see the <ulink
             URL="../handbook/kernelconfig-nodes.html">
             handbook's 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>sharity light</application>
             package in the ports collection.</para>
 
 <!-- XXX update for bp's SMBFS in CURRENT, when it is imported! -->
         </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>
     </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
             <application>ppp</application> 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 ppp 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 won't &man.ppp.8; 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 haven't got 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
             <application>ppp</application> 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 ppp using pppctl. 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 ppp 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 ppp 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 ppp hangs, find the ppp 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
             <application>ppp</application> 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 ppp 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 ppp 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 getty exiting and ppp starting,
             the client-side ppp starts sending Line Control Protocol (LCP)
             packets.  Because ECHO is still switched on for the port on
             the server, the client ppp 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 ppp sends LCP packets, sees the same magic in the
             reflected packet and NAKs it. It also sees the NAK reflect
             (which also means ppp 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 ppp 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 ppp 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 ppp to be passive for 3 seconds, and then to
             start sending LCP requests.  If the peer starts sending
           requests during this period, ppp 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 'till the connection is
             closed.  What is wrong?</para>
         </question>
 
         <answer>
           <para>There is currently an implementation mis-feature in
             <application>ppp</application> where it does not associate
             LCP, CCP &amp; IPCP responses with their original requests. As
             a result, if one <application>ppp</application>
             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 'till 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
             <application>ppp</application> 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
             <application>ppp</application> 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 <application>ppp</application>,
             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, <application>ppp</application> executes a
             shell (or if you have passed any arguments,
             <application>ppp</application> 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
             <application>ppp</application> 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 ppp can continue to
             service the link.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="ppp-nullmodem">
           <para>How come &man.ppp.8; over a null-modem cable never exits?</para>
         </question>
 
         <answer>
           <para>There is no way for <application>ppp</application> 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 <application>ppp</application> 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
             <application>ppp</application> 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 ppp 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 doesn't &man.ppp.8; 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 ppp 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 <application>ppp</application> 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>"</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 ppp runs with an effective user id of 0,
             the operating system will not write ppps core image to disk
             before terminating it.  If, however ppp
             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 ppp installed.
             You will have to be <username>root</username> to run ppp as all of its privileges
             have been revoked.  When you start ppp, take a careful note
             of what your current directory was at the time.</para>
 
           <para>Now, if and when ppp 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
             <application>ppp</application> 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.
             <application>ppp</application> then reads the packet and establishes a
             connection. If, as a result of
             <application>ppp</application>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 <application>ppp</application> 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 <application>ppp</application> is
             doing (with the help of
             &man.libalias.3; and ppp'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. <application>ppp</application> 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 <application>ppp</application>
             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 don't most games 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 ppp 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>
             </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
             <application>ppp</application> 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 ppp 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>1450</quote>
             (more accurately it should be <quote>1464</quote> to fit TCP
             packets into a PPPoE frame perfectly but the
             <quote>1450</quote> gives you a margin of error for other IP
             protocols you may encounter).  This registry key is reported to
             have moved to
             <literal>Tcpip\Parameters\Interfaces\<replaceable>ID for adapter</replaceable>\MTU</literal>
             in Windows 2000.</para>
 
           <para>Refer to <ulink
             URL="http://search.support.microsoft.com/kb">Microsoft Knowledge
             Base</ulink> documents <quote>Q158474 - Windows TCPIP Registry
             Entries</quote> and <quote>Q120642 - TCPIP & NBT Configuration
             Parameters for Windows NT</quote> for more information on
             changing Windoze MTU to work with a FreeBSD/NAT/PPPoE
             router.</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 <application>ppp</application>
             (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 <application>ppp</application>, 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
             <application>ppp</application>, 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've 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 dialout 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't I 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>How come the <literal>&lt;@&gt;</literal> sign for the pn
             capability does 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
+          <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>How come FreeBSD cannot seem to 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
             truely 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; labelled 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>
+            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 won't chmod 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 <emphasis>still</emphasis>
             restricted to 8 characters?</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>
+            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="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">
             Handbook entry on CVSup</ulink></para>
         </answer>
       </qandaentry>
 
       <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's a funny old business we're 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 don't 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="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 doesn't mean you should stop
             others from building one just because you don't 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 1960'ies, 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>
 
       <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>
 
           <para><emphasis>This entry is Copyright (c) 1999 &a.des;.
             Please do not reproduce without attribution.</emphasis></para>
         </answer>
       </qandaentry>
     </qandaset>
   </chapter>
 
   <chapter id="advanced">
     <title>Advanced Topics</title>
 
     <qandaset>
       <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>To make a release you need to do three things: First,
             you need to be running a kernel with the
             &man.vn.4;
             driver configured in.  Add this to your kernel config file
             and build a new kernel:</para>
 
           <programlisting>pseudo-device vn         #Vnode driver (turns a file into a device)</programlisting>
 
           <para>Second, you have to have the whole CVS repository at
             hand.  To get this you can use <ulink
             URL="../handbook/synching.html#CVSUP">CVSUP</ulink> but in
             your supfile set the release name to cvs and remove any tag or
             date fields:</para>
 
           <programlisting>*default prefix=/home/ncvs
 *default base=/a
 *default host=cvsup.FreeBSD.org
 *default release=cvs
 *default delete compress use-rel-suffix
 
 ## Main Source Tree
 src-all
 src-eBones
 src-secure
 
 # Other stuff
 ports-all
 www
 doc-all</programlisting>
 
           <para>Then run <command>cvsup -g supfile</command> to suck all
             the good bits onto your box...</para>
 
           <para>Finally, you need a chunk of empty space to build into.
             Let's say it is in <filename>/some/big/filesystem</filename>,
             and from the example above you have got the CVS repository in
             <filename>/home/ncvs</filename>:</para>
 
           <screen>&prompt.root; <userinput>setenv CVSROOT /home/ncvs</userinput> # or export CVSROOT=/home/ncvs
 &prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make buildworld</userinput>
 &prompt.root; <userinput>cd /usr/src/release</userinput>
 &prompt.root; <userinput>make release BUILDNAME=3.0-MY-SNAP CHROOTDIR=/some/big/filesystem/release</userinput></screen>
 
             <note>
               <para>Please note that you <emphasis>do not</emphasis>
                 need to build world if you already have a populated
                 <filename>/usr/obj</filename>.</para>
             </note>
 
           <para>An entire release will be built in
             <filename>/some/big/filesystem/release</filename> and you
             will have a full FTP-type installation in
             <filename>/some/big/filesystem/release/R/ftp</filename> when
             you are done.  If you want to build your SNAP along some other
             branch than -CURRENT, you can also add
             <literal>RELEASETAG=SOMETAG</literal> to the make release
             command line above, e.g. <literal>RELEASETAG=RELENG_2_2</literal>
             would build an up-to-the- minute 2.2-STABLE snapshot.</para>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question id="custom-install-disks">
           <para>How do I create customized installation disks?</para>
         </question>
 
         <answer>
           <para>The entire process of creating installation disks and
             source and binary archives is automated by various targets in
             <filename>/usr/src/release/Makefile</filename>. The information
             there should be enough to get you started. However, it should
             be said that this involves doing a <command>make
             world</command> and will therefore take up a lot of time and
             disk space.</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>How come when my system boots, it says <quote>(bus speed
             defaulted)</quote>?</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 <ulink
             URL="../handbook/contrib.html">The Handbook entry on how to
             submit code.</ulink></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.com
 Date: Sun, 20 Sep 1998 15:22:50 -0400 (EDT)
 Cc: current@FreeBSD.org</programlisting>
 
           <para><emphasis>[&lt;ben@rosengart.com&gt; 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 id="bibliography">
     <title>Bibliography</title>
 
     <biblioentry id="biblio-44sysman">
       <biblioset relation="book">
         <title>4.4BSD System Manager's Manual</title>
 
         <corpauthor>Computer Systems Research Group, University of
           California, Berkeley</corpauthor>
 
         <publisher>
           <publishername>O'Reilly and Associates</publishername>
         </publisher>
 
         <edition>1st Edition</edition>
 
         <pubdate>June 1994</pubdate>
 
         <pagenums>804 pages</pagenums>
 
         <isbn>ISBN 1-56592-080-5</isbn>
       </biblioset>
     </biblioentry>
 
     <biblioentry id="biblio-44userman">
       <biblioset relation="book">
         <title>4.4BSD User's Reference Manual</title>
 
         <corpauthor>Computer Systems Research Group, University of
           California, Berkeley</corpauthor>
 
         <publisher>
           <publishername>O'Reilly and Associates</publishername>
         </publisher>
 
         <edition>1st Edition</edition>
 
         <pubdate>June 1994</pubdate>
 
         <pagenums>905 pages</pagenums>
 
         <isbn>ISBN 1-56592-075-9</isbn>
       </biblioset>
     </biblioentry>
 
     <biblioentry id="biblio-44suppman">
       <biblioset relation="book">
         <title>4.4BSD User's Supplementary Documents</title>
 
         <corpauthor>Computer Systems Research Group, University of
           California, Berkeley</corpauthor>
 
         <publisher>
           <publishername>O'Reilly and Associates</publishername>
         </publisher>
 
         <edition>1st Edition</edition>
 
         <pubdate>June 1994</pubdate>
 
         <pagenums>712 pages</pagenums>
 
         <isbn>ISBN 1-56592-076-7</isbn>
       </biblioset>
     </biblioentry>
 
     <biblioentry id="biblio-44progman">
       <biblioset relation="book">
         <title>4.4BSD Programmer's Reference Manual</title>
 
         <corpauthor>Computer Systems Research Group, University of
           California, Berkeley</corpauthor>
 
         <publisher>
           <publishername>O'Reilly and Associates</publishername>
         </publisher>
 
         <edition>1st Edition</edition>
 
         <pubdate>June 1994</pubdate>
 
         <pagenums>866 pages</pagenums>
 
         <isbn>ISBN 1-56592-078-3</isbn>
       </biblioset>
     </biblioentry>
 
     <biblioentry id="biblio-44progsupp">
       <biblioset relation="book">
         <title>4.4BSD Programmer's Supplementary Documents</title>
 
         <corpauthor>Computer Systems Research Group, University of
           California, Berkeley</corpauthor>
 
         <publisher>
           <publishername>O'Reilly and Associates</publishername>
         </publisher>
 
         <edition>1st Edition</edition>
 
         <pubdate>June 1994</pubdate>
 
         <pagenums>596 pages</pagenums>
 
         <isbn>ISBN 1-56592-079-1</isbn>
       </biblioset>
     </biblioentry>
 
     <biblioentry id="biblio-44kernel">
       <biblioset relation="book">
         <title>The Design and Implementation of the 4.4BSD Operating System</title>
 
         <authorgroup>
           <author>
             <firstname>M. K.</firstname>
 
             <surname>McKusick</surname>
           </author>
 
           <author>
             <firstname>Kirk</firstname>
 
             <surname>Marshall</surname>
           </author>
 
           <author>
             <firstname>Keith</firstname>
 
             <surname>Bostic</surname>
           </author>
 
           <author>
             <firstname>Michael J</firstname>
 
             <surname>Karels</surname>
           </author>
 
           <author>
             <firstname>John</firstname>
 
             <surname>Quarterman</surname>
           </author>
         </authorgroup>
 
         <publisher>
           <publishername>Addison-Wesley</publishername>
 
           <address>
             <city>Reading</city>
             <state>MA</state>
           </address>
         </publisher>
 
         <pubdate>1996</pubdate>
 
         <isbn>ISBN 0-201-54979-4</isbn>
       </biblioset>
     </biblioentry>
 
     <biblioentry id="biblio-nemeth3rd">
       <biblioset relation="book">
         <title>Unix System Administration Handbook</title>
 
         <authorgroup>
           <author>
             <firstname>Evi</firstname>
 
             <surname>Nemeth</surname>
           </author>
 
           <author>
             <firstname>Garth</firstname>
 
             <surname>Snyder</surname>
           </author>
 
           <author>
             <firstname>Scott</firstname>
 
             <surname>Seebass</surname>
           </author>
 
           <author>
             <firstname>Trent R.</firstname>
 
             <surname>Hein</surname>
           </author>
 
           <author>
             <firstname>John</firstname>
 
             <surname>Quarterman</surname>
           </author>
         </authorgroup>
 
         <publisher>
           <publishername>Prentice-Hall</publishername>
         </publisher>
 
         <edition>3rd edition</edition>
 
         <pubdate>2000</pubdate>
 
         <isbn>ISBN 0-13-020601-6</isbn>
       </biblioset>
     </biblioentry>
 
     <biblioentry id="lehey3rd">
       <biblioset relation="book">
         <title>The Complete FreeBSD</title>
 
         <author>
           <firstname>Greg</firstname>
 
           <surname>Lehey</surname>
         </author>
 
         <publisher>
           <publishername>Walnut Creek</publishername>
         </publisher>
 
         <edition>3rd edition</edition>
 
         <pubdate>June 1999</pubdate>
 
         <pagenums>773 pages</pagenums>
 
         <isbn>ISBN 1-57176-246-9</isbn>
       </biblioset>
     </biblioentry>
 
     <biblioentry id="biblio-handbook">
       <biblioset relation="book">
         <title>The FreeBSD Handbook</title>
 
         <corpauthor>FreeBSD Documentation Project</corpauthor>
 
         <publisher>
           <publishername>BSDi</publishername>
         </publisher>
 
         <edition>1st Edition</edition>
 
         <pubdate>November 1999</pubdate>
 
         <pagenums>489 pages</pagenums>
 
         <isbn>ISBN 1-57176-241-8</isbn>
       </biblioset>
     </biblioentry>
 
     <biblioentry id="biblio-mckusick-1">
       <abbrev>McKusick et al, 1994</abbrev>
 
       <biblioset relation="manual">
         <title>Berkeley Software Architecture Manual, 4.4BSD
           Edition</title>
 
         <authorgroup>
           <author>
             <firstname>M. K.</firstname>
 
             <surname>McKusick</surname>
           </author>
 
           <author>
             <firstname>M. J.</firstname>
 
             <surname>Karels</surname>
           </author>
 
           <author>
             <firstname>S. J.</firstname>
 
             <surname>Leffler</surname>
           </author>
 
           <author>
             <firstname>W. N.</firstname>
 
             <surname>Joy</surname>
           </author>
 
           <author>
             <firstname>R. S.</firstname>
 
             <surname>Faber</surname>
           </author>
         </authorgroup>
 
         <pagenums>5:1-42</pagenums>
       </biblioset>
     </biblioentry>
   </bibliography>
 </book>
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index 0f7a2f4f35..0147832960 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -1,2600 +1,2600 @@
 <!-- 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: doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.25 2001/07/13 20:49:09 nik Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.26 2001/07/15 11:17:05 nik Exp $
 -->
 
 <chapter id="sgml-markup">
   <title>SGML Markup</title>
 
   <para>This chapter describes the two markup languages you will encounter
     when you contribute to the FreeBSD documentation project.  Each section
     describes the markup language, and details the markup that you are likely
     to want to use, or that is already in use.</para>
 
   <para>These markup languages contain a large number of elements, and it can
     be confusing sometimes to know which element to use for a particular
     situation.  This section goes through the elements you are most likely to
     need, and gives examples of how you would use them.</para>
   
   <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
     that would just reiterate the documentation for each language.  The aim of
     this section is to list those elements more likely to be useful to you.
     If you have a question about how best to markup a particular piece of
     content, please post it to the FreeBSD Documentation Project mailing list
     <email>freebsd-doc@FreeBSD.org</email>.</para>
 
   <note>
     <title>Inline vs. block</title>
     
     <para>In the remainder of this document, when describing elements,
       <emphasis>inline</emphasis> means that the element can occur within a
       block element, and does not cause a line break.  A
       <emphasis>block</emphasis> element, by comparison, will cause a line
       break (and other processing) when it is encountered.</para>
   </note>
   
   <sect1>
     <title>HTML</title>
     
     <para>HTML, the HyperText Markup Language, is the markup language of
       choice on the World Wide Web.  More information can be found at
       &lt;URL:<ulink
 	url="http://www.w3.org/">http://www.w3.org/</ulink>&gt;.</para>
 
     <para>HTML is used to markup pages on the FreeBSD web site.  It should not
       (generally) be used to mark up other documention, since DocBook offers a
       far richer set of elements to choose from.  Consequently, you will
       normally only encounter HTML pages if you are writing for the web
       site.</para>
 
     <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the
       latest, 4.0 (available in both <emphasis>strict</emphasis> and
       <emphasis>loose</emphasis> variants).</para>
 	  
     <para>The HTML DTDs are available from the ports collection in the
       <filename>textproc/html</filename> port.  They are automatically
       installed as part of the <filename>textproc/docproj</filename>
       port.</para>
 
     <sect2>
       <title>Formal Public Identifier (FPI)</title>
 
       <para>There are a number of HTML FPIs, depending upon the version (also
 	known as the level) of HTML that you want to declare your document to
 	be compliant with.</para>
 
       <para>The majority of HTML documents on the FreeBSD web site comply with
 	the loose version of HTML 4.0.</para>
 
       <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
     </sect2>
 
     <sect2>
       <title>Sectional elements</title>
 
       <para>An HTML document is normally split in to two sections.  The first
 	section, called the <emphasis>head</emphasis>, contains
 	meta-information about the document, such as its title, the name of
 	the author, the parent document, and so on.  The second section, the
 	<emphasis>body</emphasis>, contains the content that will be displayed
 	to the user.</para>
 
       <para>These sections are indicated with <sgmltag>head</sgmltag> and
 	<sgmltag>body</sgmltag> elements respectively.  These elements are
 	contained within the top-level <sgmltag>html</sgmltag> element.</para>
 
       <example>
 	<title>Normal HTML document structure</title>
 
 	<programlisting>&lt;html>
   &lt;head>
 	  &lt;title><replaceable>The document's title</replaceable>&lt;/title>
   &lt;/head>
 
   &lt;body>
 
     &hellip;
 
   &lt;/body>
 &lt;/html></programlisting>
       </example>
     </sect2>
     
     <sect2>
       <title>Block elements</title>
 
       <sect3>
 	<title>Headings</title>
 
 	<para>HTML allows you to denote headings in your document, at up to
 	  six different levels.</para>
 
 	<para>The largest and most prominent heading is <sgmltag>h1</sgmltag>,
 	  then <sgmltag>h2</sgmltag>, continuing down to
 	  <sgmltag>h6</sgmltag>.</para>
 
 	<para>The element's content is the text of the heading.</para>
 
 	<example>
 	  <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<h1>First section</h1>
 
 <!-- Document introduction goes here -->
 
 <h2>This is the heading for the first section</h2>
 
 <!-- Content for the first section goes here -->
 
 <h3>This is the heading for the first sub-section</h3>
 
 <!-- Content for the first sub-section goes here -->
 
 <h2>This is the heading for the second section</h2>
 
 <!-- Content for the second section goes here -->]]></programlisting>	    
 	</example>
 	
 	<para>Generally, an HTML page should have one first level heading
 	  (<sgmltag>h1</sgmltag>).  This can contain many second level
 	  headings (<sgmltag>h2</sgmltag>), which can in turn contain many
 	  third level headings.  Each
 	  <sgmltag>h<replaceable>n</replaceable></sgmltag> element should have
 	  the same element, but one further up the hierarchy, preceeding it.
 	  Leaving gaps in the numbering is to be avoided.</para>
 
 	<example>
 	  <title>Bad ordering of
 	    <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<h1>First section</h1>
 
 <!-- Document introduction -->
 
 <h3>Sub-section</h3>
 
 <!-- This is bad, <h2> has been left out -->]]></programlisting>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Paragraphs</title>
 
 	<para>HTML supports a single paragraph element,
 	  <sgmltag>p</sgmltag>.</para>
 
 	<example>
 	  <title><sgmltag>p</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>This is a paragraph.  It can contain just about any
   other element.</p>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Block quotations</title>
 
 	<para>A block quotation is an extended quotation from another document
 	  that should not appear within the current paragraph.</para>
 
 	<example>
 	  <title><sgmltag>blockquote</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>A small excerpt from the US Constitution:</p>
 
 <blockquote>We the People of the United States, in Order to form
   a more perfect Union, establish Justice, insure domestic
   Tranquility, provide for the common defence, promote the general
   Welfare, and secure the Blessings of Liberty to ourselves and our
   Posterity, do ordain and establish this Constitution for the
   United States of America.</blockquote>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Lists</title>
 
 	<para>You can present the user with three types of lists, ordered,
 	  unordered, and definition.</para>
 
 	<para>Typically, each entry in an ordered list will be numbered, while
 	  each entry in an unordered list will be preceded by a bullet point.
 	  Definition lists are composed of two sections for each entry.  The
 	  first section is the term being defined, and the second section is
 	  the definition of the term.</para>
 
 	<para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
 	  element, unordered lists by the <sgmltag>ul</sgmltag> element, and
 	  definition lists by the <sgmltag>dl</sgmltag> element.</para>
 
 	<para>Ordered and unordered lists contain listitems, indicated by the
 	  <sgmltag>li</sgmltag> element.  A listitem can contain textual
 	  content, or it may be further wrapped in one or more
 	  <sgmltag>p</sgmltag> elements.</para>
 
 	<para>Definition lists contain definition terms
 	  (<sgmltag>dt</sgmltag>) and definition descriptions
 	  (<sgmltag>dd</sgmltag>).  A definition term can only contain inline
 	  elements.  A definition description can contain other block
 	  elements.</para>
 
 	<example>
 	  <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>An unordered list.  Listitems will probably be
   preceeded by bullets.</p>
 
 <ul>
   <li>First item</li>
 
   <li>Second item</li>
 
   <li>Third item</li>
 </ul>
 
 <p>An ordered list, with list items consisting of multiple
   paragraphs.  Each item (note: not each paragraph) will be
   numbered.</p>
 
 <ol>
   <li><p>This is the first item.  It only has one paragraph.</p></li>
 
   <li><p>This is the first paragraph of the second item.</p>
 
     <p>This is the second paragraph of the second item.</p></li>
 
   <li><p>This is the first and only paragraph of the third
     item.</p></li>
 </ol>]]></programlisting>
 	</example>
 
 	<example>
 	  <title>Definition lists with <sgmltag>dl</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<dl>
   <dt>Term 1</dt>
 
   <dd><p>Paragraph 1 of definition 1.</p></dd>
 
     <p>Paragraph 2 of definition 1.</p></dd>
 
   <dt>Term 2</dt>
 
   <dd><p>Paragraph 1 of definition 2.</p></dd>
 
   <dt>Term 3</dt>
 
   <dd>Paragraph 1 of definition 3.  Note that the &lt;p&gt;
     element is not required in the single paragraph case.</dd>
 </dl>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Pre-formatted text</title>
 
 	<para>You can indicate that text should be shown to the user exactly
 	  as it is in the file.  Typically, this means that the text is shown
 	  in a fixed font, multiple spaces are not merged in to one, and line
 	  breaks in the text are significant.</para>
 
 	<para>In order to do this, wrap the content in the
 	  <sgmltag>pre</sgmltag> element.</para>
 
 	<example>
 	  <title><sgmltag>pre</sgmltag></title>
 
 	  <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail
 	    message;</para>
 
 	  <programlisting><![ CDATA [<pre>  From: nik@FreeBSD.org
   To: freebsd-doc@FreeBSD.org
   Subject: New documentation available
 
   There's a new copy of my primer for contributers to the FreeBSD
   Documentation Project available at
 
     <URL:http://people.FreeBSD.org/~nik/primer/index.html>
 
   Comments appreciated.
 
   N</pre>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Tables</title>
 
 	<note>
 	  <para>Most text-mode browsers (such as Lynx) do not render tables
 	    particularly effectively.  If you are relying on the tabular
 	    display of your content, you should consider using alternative
 	    markup to prevent confusion.</para>
 	</note>
 
 	<para>Mark up tabular information using the <sgmltag>table</sgmltag>
 	  element.  A table consists of one or more table rows
 	  (<sgmltag>tr</sgmltag>), each containing one or more cells of table
 	  data (<sgmltag>td</sgmltag>).  Each cell can contain other block
 	  elements, such as paragraphs or lists.  It can also contain another
 	  table (this nesting can repeat indefinitely).  If the cell only
 	  contains one paragraph then you do not need to include the
 	  <sgmltag>p</sgmltag> element.</para>
 
 	<example>
 	  <title>Simple use of <sgmltag>table</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>This is a simple 2x2 table.</p>
 
 <table>
   <tr>
     <td>Top left cell</td>
 
     <td>Top right cell</td>
   </tr>
 
   <tr>
     <td>Bottom left cell</td>
 
     <td>Bottom right cell</td>
   </tr>
 </table>]]></programlisting></example>
 
 	<para>A cell can span multiple rows and columns.  To indicate this,
 	  add the <literal>rowspan</literal> and/or <literal>colspan</literal>
 	  attributes, with values indicating the number of rows of columns
 	  that should be spanned.</para>
 
 	<example>
 	  <title>Using <literal>rowspan</literal></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>One tall thin cell on the left, two short cells next to
   it on the right.</p>
 
 <table>
   <tr>
     <td rowspan="2">Long and thin</td>
   </tr>
 
   <tr>
     <td>Top cell</td>
 
     <td>Bottom cell</td>
   </tr>
 </table>]]></programlisting>
 	</example>
 
 	<example>
 	  <title>Using <literal>colspan</literal></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>One long cell on top, two short cells below it.</p>
 
 <table>
   <tr>
     <td colspan="2">Top cell</td>
   </tr>
 
   <tr>
     <td>Bottom left cell</td>
 
     <td>Bottom right cell</td>
   </tr>
 </table>]]></programlisting>
 	</example>
 
 	<example>
 	  <title>Using <literal>rowspan</literal> and
 	    <literal>colspan</literal> together</title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of
   cells merged in to one.  The other cells are normal.</p>
 
 <table>
   <tr>
     <td colspan="2" rowspan="2">Top left large cell</td>
 
     <td>Top right cell</td>
   </tr>
 
   <tr>
     <!-- Because the large cell on the left merges in to
          this row, the first <td> will occur on its
          right -->
 	    
     <td>Middle right cell</td>
   </tr>
 
   <tr>
     <td>Bottom left cell</td>
 
     <td>Bottom middle cell</td>
 
     <td>Bottom right cell</td>
   </tr>
 </table>]]></programlisting>
 	</example>
       </sect3>
     </sect2>
 
     <sect2>
       <title>In-line elements</title>
 
       <sect3>
 	<title>Emphasising information</title>
 
 	<para>You have two levels of emphasis available in HTML,
 	  <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
 	  <sgmltag>em</sgmltag> is for a normal level of emphasis and
 	  <sgmltag>strong</sgmltag> indicates stronger emphasis.</para>
 
 	<para>Typically, <sgmltag>em</sgmltag> is rendered in italic and
 	  <sgmltag>strong</sgmltag> is rendered in bold.  This is not always
 	  the case, however, and you should not rely on it.</para>
 
 	<example>
 	  <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p><em>This</em> has been emphasised, while
   <strong>this</strong> has been strongly emphasised.</p>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Bold and italics</title>
 
 	<para>Because HTML includes presentational markup, you can also
 	  indicate that particular content should be rendered in bold or
 	  italic.  The elements are <sgmltag>b</sgmltag> and
 	  <sgmltag>i</sgmltag> respectively.</para>
 
 	<example>
 	  <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title>
 
 	  <programlisting><![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is
   in italics.</p>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Indicating fixed pitch text</title>
 
 	<para>If you have content that should be rendered in a fixed pitch
 	  (typewriter) typeface, use <sgmltag>tt</sgmltag> (for
 	  &ldquo;teletype&rdquo;).</para>
 
 	<example>
 	  <title><sgmltag>tt</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>This document was originally written by
   Nik Clayton, who can be reached by e-mail as
   <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Content size</title>
 
 	<para>You can indicate that content should be shown in a larger or
 	  smaller font.  There are three ways of doing this.</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag>
 	      around the content you wish to change size.  These tags can be
 	      nested, so <literal>&lt;big&gt;&lt;big&gt;This is much
 		bigger&lt;/big&gt;&lt;/big&gt;</literal> is possible.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
 	      attribute set to <literal>+1</literal> or <literal>-1</literal>
 	      respectively.  This has the same effect as using
 	      <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>.  However,
 	      the use of this approach is deprecated.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
 	    attribute set to a number between 1 and 7.  The default font size
 	      is <literal>3</literal>.  This approach is deprecated.</para>
 	  </listitem>
 	</orderedlist>
 
 	<example>
 	  <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and
 	    <sgmltag>font</sgmltag></title>
 
 	  <para>The following fragments all do the same thing.</para>
 
 	  <programlisting><![ CDATA [<p>This text is <small>slightly smaller</small>.  But
   this text is <big>slightly bigger</big>.</p>
 
 <p>This text is <font size="-1">slightly smaller</font>.  But
   this text is <font size="+1">slightly bigger</font.</p>
 
 <p>This text is <font size="2">slightly smaller</font>.  But
   this text is <font size="4">slightly bigger</font>.</p>]]></programlisting>
 	</example>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Links</title>
 
       <note>
 	<para>Links are also in-line elements.</para>
       </note>
 
       <sect3>
 	<title>Linking to other documents on the WWW</title>
 
 	<para>In order to include a link to another document on the WWW you
 	  must know the URL of the document you want to link to.</para>
 
 	<para>The link is indicated with <sgmltag>a</sgmltag>, and the
 	  <literal>href</literal> attribute contains the URL of the target
 	  document.  The content of the element becomes the link, and is
 	  normally indicated to the user in some way (underlining, change of
 	  colour, different mouse cursor when over the link, and so
 	  on).</para>
 
 	<example>
 	  <title>Using <literal>&lt;a href="..."&gt;</literal></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p>More information is available at the
   <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting>
 	</example>
 
 	<para>These links will take the user to the top of the chosen
 	  document.</para>
       </sect3>
       
       <sect3>
 	<title>Linking to other parts of documents</title>
 
 	<para>Linking to a point within another document (or within the same
 	  document) requires that the document author include anchors that you
 	  can link to.</para>
 
 	<para>Anchors are indicated with <sgmltag>a</sgmltag> and the
 	  <literal>name</literal> attribute instead of
 	  <literal>href</literal>.</para>
 
 	<example>
 	  <title>Using <literal>&lt;a name="..."&gt;</literal></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<p><a name="para1">This</a> paragraph can be referenced
   in other links with the name <tt>para1</tt>.</p>]]></programlisting>
 	</example>
 
 	<para>To link to a named part of a document, write a normal link to
 	  that document, but include the name of the anchor after a
 	  <literal>#</literal> symbol.</para>
 
 	<example>
 	  <title>Linking to a named part of another document</title>
 
 	  <para>Assume that the <literal>para1</literal> example resides in a
 	    document called <filename>foo.html</filename>.</para>
 
 	  <programlisting><![ CDATA [<p>More information can be found in the
   <a href="foo.html#para1">first paragraph</a> of
   <tt>foo.html</tt>.</p>]]></programlisting>
 	</example>
 
 	<para>If you are linking to a named anchor within the same document
 	  then you can omit the document's URL, and just include the name of
 	  the anchor (with the preceeding <literal>#</literal>).</para>
 
 	<example>
 	  <title>Linking to a named part of the same document</title>
 
 	  <para>Assume that the <literal>para1</literal> example resides in
 	    this document</para>
 
 	  <programlisting><![ CDATA [<p>More information can be found in the
   <a href="#para1">first paragraph</a> of this
   document.</p>]]></programlisting>
 	</example>
       </sect3>
     </sect2>
   </sect1>
   
   <sect1>
     <title>DocBook</title>
 
     <para>DocBook was designed by the <ulink
 	url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be
       a DTD for writing technical documentation.  As such, and unlike LinuxDoc
       and HTML, DocBook is very heavily oriented towards markup that
       describes <emphasis>what</emphasis> something is, rather than describing
       <emphasis>how</emphasis> it should be presented.</para>
 
     <note>
       <title><literal>formal</literal> vs. <literal>informal</literal></title>
 
       <para>Some elements may exist in two forms, <emphasis>formal</emphasis>
 	and <emphasis>informal</emphasis>.  Typically, the formal version of
 	the element will consist of a title followed by the information
 	version of the element.  The informal version will not have a
 	title.</para>
     </note>
     
     <para>The DocBook DTD is available from the ports collection in the
       <filename>textproc/docbook</filename> port.  It is automatically
       installed as part of the <filename>textproc/docproj</filename>
       port.</para>
     
     <sect2>
       <title>FreeBSD extensions</title>
 
       <para>The FreeBSD Documentation Project has extended the DocBook DTD by
 	adding some new elements.  These elements serve to make some of the
 	markup more precise.</para>
 
       <para>Where a FreeBSD specific element is listed below it is clearly
 	marked.</para>
 
       <para>Throughout the rest of this document, the term
 	&ldquo;DocBook&rdquo; is used to mean the FreeBSD extended DocBook
 	DTD.</para>
       
       <note>
 	<para>There is nothing about these extensions that is FreeBSD
 	  specific, it was just felt that they were useful enhancements for
 	  this particular project.  Should anyone from any of the other *nix
 	  camps (NetBSD, OpenBSD, Linux, &hellip;) be interested in
 	  collaborating on a standard DocBook extension set, please get in
 	  touch with Nik Clayton <email>nik@FreeBSD.org</email>.</para>
       </note>
 
       <para>The FreeBSD extensions are not (currently) in the ports
 	collection.  They are stored in the FreeBSD CVS tree, as <ulink
 	url="http://www.freebsd.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>Formal Public Identifier (FPI)</title>
 
       <para>In compliance with the DocBook guidelines for writing FPIs for
 	  DocBook customisations, the FPI for the FreeBSD extended DocBook DTD
 	  is;</para>
 
 	<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
     </sect2>
 
     <sect2>
       <title>Document structure</title>
 
       <para>DocBook allows you to structure your documentation in several
 	ways.  In the FreeBSD Documentation Project we are using two primary
 	types of DocBook document: the book and the article.</para>
 
       <para>A book is organised into <sgmltag>chapter</sgmltag>s.  This is a
 	mandatory requirement.  There may be <sgmltag>part</sgmltag>s between
 	the book and the chapter to provide another layer of organisation.
 	The Handbook is arranged in this way.</para>
 
       <para>A chapter may (or may not) contain one or more sections.  These
 	are indicated with the <sgmltag>sect1</sgmltag> element.  If a section
 	contains another section then use the <sgmltag>sect2</sgmltag>
 	element, and so on, up to <sgmltag>sect5</sgmltag>.</para>
 
       <para>Chapters and sections contain the remainder of the content.</para>
 
       <para>An article is simpler than a book, and does not use chapters.
 	Instead, the content of an article is organised into one or more
 	sections, using the same <sgmltag>sect1</sgmltag> (and
 	<sgmltag>sect2</sgmltag> and so on) elements that are used in
 	books.</para>
 
       <para>Obviously, you should consider the nature of the documentation you 
 	are writing in order to decide whether it is best marked up as a book
 	or an article.  Articles are well suited to information that does not
 	need to be broken down into several chapters, and that is, relatively 
 	speaking, quite short, at up to 20-25 pages of content.  Books are
 	best suited to information that can be broken up into several
 	chapters, possibly with appendices and similar content as well.</para>
 
       <para>The <ulink url="http://www.FreeBSD.org/tutorials/">FreeBSD
 	  tutorials</ulink> are all marked up as articles, while this
 	document, the <ulink url="http://www.FreeBSD.org/FAQ/">FreeBSD
 	  FAQ</ulink>, and the <ulink
 	  url="http://www.FreeBSD.org/handbook/">FreeBSD Handbook</ulink> are
 	all marked up as books.</para>
 
       <sect3>
 	<title>Starting a book</title>
 
 	<para>The content of the book is contained within the
 	  <sgmltag>book</sgmltag> element.  As well as containing structural
 	  markup, this element can contain elements that include additional
 	  information about the book.  This is either meta-information, used
 	  for reference purposes, or additional content used to produce a
 	  title page.</para>
 
 	<para>This additional information should be contained within
 	  <sgmltag>bookinfo</sgmltag>.</para>
 
 	<example>
 	  <title>Boilerplate <sgmltag>book</sgmltag> with
 	    <sgmltag>bookinfo</sgmltag></title>
 
 	  <!-- Can't put this in a marked section because of the
                replaceable elements -->
 	  <programlisting>&lt;book>
   &lt;bookinfo>
     &lt;title><replaceable>Your title here</replaceable>&lt;/title>
     
     &lt;author>
       &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
       &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
       &lt;affiliation>
         &lt;address>&lt;email><replaceable>Your e-mail address</replaceable>&lt;/email>&lt;/address>
       &lt;/affiliation>
     &lt;/author>
 
     &lt;copyright>
       &lt;year><replaceable>1998</replaceable>&lt;/year>
       &lt;holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
     &lt;/copyright>
 
     &lt;pubdate role="rcs">&#36;Date&#36;&lt;/pubdate>
 
     &lt;releaseinfo>&#36;Id&#36;&lt;/releaseinfo>
 
     &lt;abstract>
       &lt;para><replaceable>Include an abstract of the book's contents here.</replaceable>&lt;/para>
     &lt;/abstract>
   &lt;/bookinfo>
 
   &hellip;
 
 &lt;/book></programlisting>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Starting an article</title>
 
 	<para>The content of the article is contained within the
 	  <sgmltag>article</sgmltag> element.  As well as containing
 	  structural markup, this element can contain elements that include
 	  additional information about the article.  This is either
 	  meta-information, used for reference purposes, or additional content
 	  used to produce a title page.</para>
 
 	<para>This additional information should be contained within
 	  <sgmltag>articleinfo</sgmltag>.</para>
 
 	<example>
 	  <title>Boilerplate <sgmltag>article</sgmltag> with
 	    <sgmltag>articleinfo</sgmltag></title>
 
 	  <!-- Can't put this in a marked section because of the
                replaceable elements -->
 	  <programlisting>&lt;article>
   &lt;articleinfo>
     &lt;title><replaceable>Your title here</replaceable>&lt;/title>
     
     &lt;author>
       &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
       &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
       &lt;affiliation>
         &lt;address>&lt;email><replaceable>Your e-mail address</replaceable>&lt;/email>&lt;/address>
       &lt;/affiliation>
     &lt;/author>
 
     &lt;copyright>
       &lt;year><replaceable>1998</replaceable>&lt;/year>
       &lt;holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
     &lt;/copyright>
 
     &lt;pubdate role="rcs">&#36;Date&#36;&lt;/pubdate>
 
     &lt;releaseinfo>&#36;Id&#36;&lt;/releaseinfo>
 
     &lt;abstract>
       &lt;para><replaceable>Include an abstract of the article's contents here.</replaceable>&lt;/para>
     &lt;/abstract>
   &lt;/articleinfo>
 
   &hellip;
 
 &lt;/article></programlisting>
 	</example>	
       </sect3>
       <sect3>
 	<title>Indicating chapters</title>
 
 	<para>Use <sgmltag>chapter</sgmltag> to mark up your chapters.  Each
 	  chapter has a mandatory <sgmltag>title</sgmltag>.  Articles do not
 	  contain chapters, they are reserved for books.</para>
 
 	<example>
 	  <title>A simple chapter</title>
 
 	  <programlisting><![ CDATA [<chapter>
   <title>The chapter's title</title>
 
   ...
 </chapter>]]></programlisting>
 	</example>
 
 	<para>A chapter cannot be empty; it must contain elements in addition
 	  to <sgmltag>title</sgmltag>.  If you need to include an empty
 	  chapter then just use an empty paragraph.</para>
 
 	<example>
 	  <title>Empty chapters</title>
 
 	  <programlisting><![ CDATA [<chapter>
   <title>This is an empty chapter</title>
 
   <para></para>
 </chapter>]]></programlisting>	    
 	</example>
       </sect3>
 
       <sect3>
 	<title>Sections below chapters</title>
 
 	<para>In books, chapters may (but do not need to) be broken up into
 	  sections, subsections, and so on.  In articles, sections are the
 	  main structural element, and each  article must contain at least one
 	  section.  Use the
 	  <sgmltag>sect<replaceable>n</replaceable></sgmltag> element.  The
 	  <replaceable>n</replaceable> indicates the section number, which
 	  identifies the section level.</para>
 
 	<para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is
 	  <sgmltag>sect1</sgmltag>.  You can have one or more of these in a
 	  chapter.  They can contain one or more <sgmltag>sect2</sgmltag>
 	  elements, and so on, down to <sgmltag>sect5</sgmltag>.</para>
 
 	<example>
 	  <title>Sections in chapters</title>
 
 	  <programlisting><![ RCDATA [<chapter>
   <title>A sample chapter</title>
 
   <para>Some text in the chapter.</para>
 
   <sect1>
     <title>First section (1.1)</title>
 
     &hellip;
   </sect1>
 
   <sect1>
     <title>Second section (1.2)</title>
 
     <sect2>
       <title>First sub-section (1.2.1)</title>
 
       <sect3>
         <title>First sub-sub-section (1.2.1.1)</title>
 
         &hellip;
       </sect3>
     </sect2>
 
     <sect2>
       <title>Second sub-section (1.2.2)</title>
 
       &hellip;
     </sect2>
   </sect1>
 </chapter>]]></programlisting>
 	</example>
 	
 	<note>
 	  <para>This example includes section numbers in the section titles.
 	    You should not do this in your documents.  Adding the section
 	    numbers is carried out the by the stylesheets (of which more
 	    later), and you do not need to manage them yourself.</para>
 	</note>
       </sect3>
       
       <sect3>
 	<title>Subdividing using <sgmltag>part</sgmltag>s</title>
 
 	<para>You can introduce another layer of organisation between
 	  <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or
 	  more <sgmltag>part</sgmltag>s.  This cannot be done in an
 	  <sgmltag>article</sgmltag>.</para>
 
 	<programlisting><![ CDATA [<part>
   <title>Introduction</title>
 
   <chapter>
     <title>Overview</title>
 
     ...
   </chapter>
 
   <chapter>
     <title>What is FreeBSD?</title>
 
     ...
   </chapter>
 
   <chapter>
     <title>History</title>
 
     ...
   </chapter>
 </part>]]></programlisting>
       </sect3>
     </sect2>
     
     <sect2>
       <title>Block elements</title>
       
       <sect3>
 	<title>Paragraphs</title>
 	
 	<para>DocBook supports three types of paragraphs:
 	  <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and
 	  <sgmltag>simpara</sgmltag>.</para>
 	
 	<para>Most of the time you will only need to use
 	  <sgmltag>para</sgmltag>.  <sgmltag>formalpara</sgmltag> includes a
 	  <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag>
 	  disallows some elements from within <sgmltag>para</sgmltag>.  Stick
 	  with <sgmltag>para</sgmltag>.</para>
 	  
 	<example>
 	  <title><sgmltag>para</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>This is a paragraph.  It can contain just about any
   other element.</para> ]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>This is a paragraph.  It can contain just about any other
 	    element.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Block quotations</title>
 	
 	<para>A block quotation is an extended quotation from another document
 	  that should not appear within the current paragraph.  You will
 	  probably only need it infrequently.</para>
 	
 	<para>Blockquotes can optionally contain a title and an attribution
 	  (or they can be left untitled and unattributed).</para>
 
 	<example>
 	  <title><sgmltag>blockquote</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>A small excerpt from the US Constitution;</para>
 	      
 <blockquote>
   <title>Preamble to the Constitution of the United States</title>
 
   <attribution>Copied from a web site somewhere</attribution>
 	    
   <para>We the People of the United States, in Order to form a more perfect
     Union, establish Justice, insure domestic Tranquility, provide for the
     common defence, promote the general Welfare, and secure the Blessings
     of Liberty to ourselves and our Posterity, do ordain and establish this
     Constitution for the United States of America.</para>
 </blockquote>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <blockquote>
 	    <title>Preamble to the Constitution of the United States</title>
 	    
 	    <attribution>Copied from a web site somewhere</attribution>
 	    
 	    <para>We the People of the United States, in Order to form a more
 	      perfect Union, establish Justice, insure domestic Tranquility,
 	      provide for the common defence, promote the general Welfare, and
 	      secure the Blessings of Liberty to ourselves and our Posterity,
 	      do ordain and establish this Constitution for the United States
 	      of America.</para>
 	  </blockquote>	  
 	</example>
       </sect3>
       
       <sect3>
 	<title>Tips, notes, warnings, cautions, important information and
 	  sidebars.</title>
 	  
 	<para>You may need to include extra information separate from the
 	  main body of the text.  Typically this is &ldquo;meta&rdquo;
 	  information that the user should be aware of.</para>
 	
 	<para>Depending on the nature of the information, one of
 	  <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>,
 	  <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and
 	  <sgmltag>important</sgmltag> should be used.  Alternatively, if the
 	  information is related to the main text but is not one of the above,
 	  use <sgmltag>sidebar</sgmltag>.</para>
 
 	<para>The circumstances in which to choose one of these elements over
 	  another is unclear.  The DocBook documentation suggests;</para>
 	
 	<itemizedlist>
 	  <listitem>
 	    <para>A Note is for information that should be heeded by all
 	      readers.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>An Important element is a variation on Note.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>A Caution is for information regarding possible data loss
 	      or software damage.</para>
 	  </listitem>
 	  
 	  <listitem>
 	    <para>A Warning is for information regarding possible hardware
 	      damage or injury to life or limb.</para>
 	  </listitem>
 	</itemizedlist>
 	
 	<example>
 	  <title><sgmltag>warning</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<warning>
   <para>Installing FreeBSD may make you want to delete Windows from your
     harddisk.</para>
 </warning>]]></programlisting>
 	  </example>
 	  
 	<!-- Need to do this outside of the example -->
 	<warning>
 	  <para>Installing FreeBSD may make you want to delete Windows from
 	    your harddisk.</para>
 	</warning>	  
       </sect3>
       
       <sect3>
 	<title>Lists and procedures</title>
 	
 	<para>You will often need to list pieces of information to the user,
 	  or present them with a number of steps that must be carried out in
 	  order to accomplish a particular goal.</para>
 	
 	<para>In order to do this, use <sgmltag>itemizedlist</sgmltag>,
 	  <sgmltag>orderedlist</sgmltag>, or
 	  <sgmltag>procedure</sgmltag><footnote><para>There are other types of
 	      list element in DocBook, but we're not concerned with those at
 	      the moment.</para>
 	  </footnote>
 	</para>
 	  
 	<para><sgmltag>itemizedlist</sgmltag> and
 	  <sgmltag>orderedlist</sgmltag> are similar to their counterparts in
 	  HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>.  Each one
 	  consists of one or more <sgmltag>listitem</sgmltag> elements, and
 	  each <sgmltag>listitem</sgmltag> contains one or more block
 	  elements.  The <sgmltag>listitem</sgmltag> elements are analagous to
 	  HTML's <sgmltag>li</sgmltag> tags.  However, unlike HTML, they are
 	  required.</para>
 	
 	<para><sgmltag>procedure</sgmltag> is slightly different.  It consists
 	  of <sgmltag>step</sgmltag>s, which may in turn consists of more
 	  <sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s.  Each
 	  <sgmltag>step</sgmltag> contains block elements.</para>
 
 	<example>
 	  <title><sgmltag>itemizedlist</sgmltag>,
 	    <sgmltag>orderedlist</sgmltag>, and
 	    <sgmltag>procedure</sgmltag></title>
 	  
 	  <para>Use:</para>
 	    
 	  <programlisting><![ CDATA [<itemizedlist>
   <listitem>
     <para>This is the first itemized item.</para>
   </listitem>
 
   <listitem>
     <para>This is the second itemized item.</para>
   </listitem>
 </itemizedlist>
 
 <orderedlist>
   <listitem>
     <para>This is the first ordered item.</para>
   </listitem>
 
   <listitem>
     <para>This is the second ordered item.</para>
   </listitem>
 </orderedlist>
 
 <procedure>
   <step>
     <para>Do this.</para>
   </step>
 
   <step>
     <para>Then do this.</para>
   </step>
 
   <step>
     <para>And now do this.</para>
   </step>
 </procedure>]]></programlisting>
 	  
 	  <para>Appearance:</para>
 	  
 	  <itemizedlist>
 	    <listitem>
 	      <para>This is the first itemized item.</para>
 	    </listitem>
 	    
 	    <listitem>
 	      <para>This is the second itemized item.</para>
 	    </listitem>
 	  </itemizedlist>
 	  
 	  <orderedlist>
 	    <listitem>
 	      <para>This is the first ordered item.</para>
 	    </listitem>
 	    
 	    <listitem>
 	      <para>This is the second ordered item.</para>
 	    </listitem>
 	  </orderedlist>
 	</example>
 
 	<!-- Can't have <procedure> inside <example>, so this is a cheat -->
 	
 	<procedure>
 	  <step>
 	    <para>Do this.</para>
 	  </step>
 	  
 	  <step>
 	    <para>Then do this.</para>
 	  </step>
 	  
 	  <step>
 	    <para>And now do this.</para>
 	  </step>
 	</procedure>	  
       </sect3>
       
       <sect3>
 	<title>Showing file samples</title>
 	
 	<para>If you want to show a fragment of a file (or perhaps a complete
 	  file) to the user, wrap it in the <sgmltag>programlisting</sgmltag>
 	  element.</para>
 	  
 	<para>White space and line breaks within
 	  <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis>
 	  significant.  In particular, this means that the opening tag should
 	  appear on the same line as the first line of the output, and the
 	  closing tag should appear on the same line as the last line of the
 	  output, otherwise spurious blank lines may be included.</para>
 	  
 	<example>
 	  <title><sgmltag>programlisting</sgmltag></title>
 	    
 	  <para>Use:</para>
 	    
 	  <programlisting><![ CDATA[<para>When you have finished, your program should look like
   this;</para>
 
 <programlisting>#include &lt;stdio.h&gt;
 
 int
 main(void)
 {
     printf("hello, world\n");
 }</programlisting>]]></programlisting>
 
 	  <para>Notice how the angle brackets in the
 	    <literal>#include</literal> line need to be referenced by their
 	    entities instead of being included literally.</para>
 	    
 	  <para>Appearance:</para>
 	    
 	  <para>When you have finished, your program should look like
 	    this;</para>
 	    
 	  <programlisting>#include &lt;stdio.h&gt;
 
 int
 main(void)
 {
     printf("hello, world\n");
 }</programlisting>	    
 	</example>
       </sect3>
 
       <sect3>
 	<title>Callouts</title>
 
 	<para>A callout is a mechanism for referring back to an earlier piece
 	  of text or specific position within an earlier example without
 	  linking to it within the text.</para>
 
 	<para>To do this, mark areas of interest in your example
 	  (<sgmltag>programlisting</sgmltag>,
 	  <sgmltag>literallayout</sgmltag>, or whatever) with the
 	  <sgmltag>co</sgmltag> element.  Each element must have a unique
 	  <literal>id</literal> assigned to it.  After the example include a
 	  <sgmltag>calloutlist</sgmltag> that refers back to the example and
 	  provides additional commentary.</para>
 	
 	<example>
 	  <title><sgmltag>co</sgmltag> and
 	    <sgmltag>calloutlist</sgmltag></title>
 
 	  <programlisting><![ CDATA[<para>When you have finished, your program should look like
   this;</para>
 
 <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">
 
 int <co id="co-ex-return">
 main(void)
 {
     printf("hello, world\n"); <co id="co-ex-printf">
 }</programlisting>
 
 <calloutlist>
   <callout arearefs="co-ex-include">
     <para>Includes the standard IO header file.</para>
   </callout>
 
   <callout arearefs="co-ex-return">
     <para>Specifies that <function>main()</function> returns an
       int.</para>
   </callout>
 
   <callout arearefs="co-ex-printf">
     <para>The <function>printf()</function> call that writes
       <literal>hello, world</literal> to standard output.</para>
   </callout>
 </calloutlist>]]></programlisting>
 
 	  <para>Appearance:</para>
 
 	  <para>When you have finished, your program should look like
 	    this;</para>
 
 	  <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">
 
 int <co id="co-ex-return">
 main(void)
 {
     printf("hello, world\n"); <co id="co-ex-printf">
 }</programlisting>
 
 	  <calloutlist>
 	    <callout arearefs="co-ex-include">
 	      <para>Includes the standard IO header file.</para>
 	    </callout>
 	    
 	    <callout arearefs="co-ex-return">
 	      <para>Specifies that <function>main()</function> returns an
 		int.</para>
 	    </callout>
 	    
 	    <callout arearefs="co-ex-printf">
 	      <para>The <function>printf()</function> call that writes
 		<literal>hello, world</literal> to standard output.</para>
 	    </callout>
 	  </calloutlist>	  
 	</example>
       </sect3>
       
       <sect3>
 	<title>Tables</title>
 	
 	<para>Unlike HTML, you do not need to use tables for layout purposes,
 	  as the stylesheet handles those issues for you.  Instead, just use
 	  tables for marking up tabular data.</para>
 
 	<para>In general terms (and see the DocBook documentation for more
 	  detail) a table (which can be either formal or informal) consists of
 	  a <sgmltag>table</sgmltag> element.  This contains at least one
 	  <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute)
 	  the number of columns in this table group.  Within the tablegroup
 	  you can then have one <sgmltag>thead</sgmltag> element, which
 	  contains elements for the table headings (column headings), and one
 	  <sgmltag>tbody</sgmltag> which contains the body of the
 	  table.</para>
 
 	<para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag>
 	  contain <sgmltag>row</sgmltag> elements, which in turn contain
 	  <sgmltag>entry</sgmltag> elements.  Each <sgmltag>entry</sgmltag>
 	  element specifies one cell in the table.</para>
 	  
 	<example>
 	  <title><sgmltag>informaltable</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<informaltable>
   <tgroup cols="2">
     <thead>
       <row>
         <entry>This is column head 1</entry>
         <entry>This is column head 2</entry>
       </row>
     </thead>
 
     <tbody>
       <row>
         <entry>Row 1, column 1</entry>
         <entry>Row 1, column 2</entry>
       </row>
 
       <row>
         <entry>Row 2, column 1</entry>
         <entry>Row 2, column 2</entry>
       </row>
     </tbody>
   </tgroup>
 </informaltable>]]></programlisting>
 	  
 	  <para>Appearance:</para>
 	  
 	  <informaltable>
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>This is column head 1</entry>
 		  <entry>This is column head 2</entry>
 		</row>
 	      </thead>
 	      
 	      <tbody>
 		<row>
 		  <entry>Row 1, column 1</entry>
 		  <entry>Row 1, column 2</entry>
 		</row>
 		
 		<row>
 		  <entry>Row 2, column 1</entry>
 		  <entry>Row 2, column 2</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 	</example>
 	
 	<para>If you don't want a border around the table the
 	  <literal>frame</literal> attribute can be added to the
 	  <sgmltag>informaltable</sgmltag> element with a value of
 	  <literal>none</literal> (i.e., <literal>&lt;informaltable
 	    frame="none"&gt;</literal>).</para>
 
 	<example>
 	  <title>Tables where <literal>frame="none"</literal></title>
 	  
 	  <para>Appearance:</para>
 	
 	  <informaltable frame="none">
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>This is column head 1</entry>
 		  <entry>This is column head 2</entry>
 		</row>
 	      </thead>
 	      
 	      <tbody>
 		<row>
 		  <entry>Row 1, column 1</entry>
 		  <entry>Row 1, column 2</entry>
 		</row>
 		
 		<row>
 		  <entry>Row 2, column 1</entry>
 		  <entry>Row 2, column 2</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Examples for the user to follow</title>
 	
 	<para>A lot of the time you need to show examples for the user to
 	  follow.  Typically, these will consist of dialogs with the computer;
 	  the user types in a command, the user gets a response back, they
 	  type in another command, and so on.</para>
 	  
 	<para>A number of distinct elements and entities come in to play
 	  here.</para>
 	
 	<variablelist>
 	  <varlistentry>
 	    <term><sgmltag>screen</sgmltag></term>
 	    
 	    <listitem>
 	      <para>Everything the user sees in this example will be on the
 		computer screen, so the next element is
 		<sgmltag>screen</sgmltag>.</para>
 		
 	      <para>Within <sgmltag>screen</sgmltag>, white space is
 		significant.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><sgmltag>prompt</sgmltag>,
 	      <literal>&amp;prompt.root;</literal> and
 	      <literal>&amp;prompt.user;</literal></term>
 	    
 	    <listitem>
 	      <para>Some of the things the user will be seeing on the screen
 		are prompts from the computer (either from the OS, command
 		shell, or application.  These should be marked up using
 		<sgmltag>prompt</sgmltag>.</para>
 
 	      <para>As a special case, the two shell prompts for the normal
 		user and the root user have been provided as entities.  Every
 		time you want to indicate the user is at a shell prompt, use
 		one of <literal>&amp;prompt.root;</literal> and
 		<literal>&amp;prompt.user;</literal> as necessary.  They do
 		not need to be inside <sgmltag>prompt</sgmltag>.</para>
 
 	      <note>
 		<para><literal>&amp;prompt.root;</literal> and
 		  <literal>&amp;prompt.user;</literal> are FreeBSD
 		  extensions to DocBook, and are not part of the original
 		  DTD.</para>
 	      </note>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><sgmltag>userinput</sgmltag></term>
 	    
 	    <listitem>
 	      <para>When displaying text that the user should type in, wrap it
 		in <sgmltag>userinput</sgmltag> tags.  It will probably be
 		displayed differently to the user.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 	  
 	<example>
 	  <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and
 	    <sgmltag>userinput</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<screen>&prompt.user; <userinput>ls -1</userinput>
 foo1
 foo2
 foo3
 &prompt.user; <userinput>ls -1 | grep foo2</userinput>
 foo2
 &prompt.user; <userinput>su</userinput>
 <prompt>Password: </prompt>
 &prompt.root; <userinput>cat foo2</userinput>
 This is the file called 'foo2'</screen>]]></programlisting>
 	  
 	  <para>Appearance:</para>
 	
 	  <screen>&prompt.user; <userinput>ls -1</userinput>
 foo1
 foo2
 foo3
 &prompt.user; <userinput>ls -1 | grep foo2</userinput>
 foo2
 &prompt.user; <userinput>su</userinput>
 <prompt>Password: </prompt>
 &prompt.root; <userinput>cat foo2</userinput>
 This is the file called 'foo2'</screen>
 	</example>
 	
 	<note>
 	  <para>Even though we are displaying the contents of the file
 	    <filename>foo2</filename>, it is <emphasis>not</emphasis> marked
 	    up as <sgmltag>programlisting</sgmltag>.  Reserve
 	    <sgmltag>programlisting</sgmltag> for showing fragments of files
 	    outside the context of user actions.</para>
 	</note>
       </sect3>
     </sect2>
     
     <sect2>
       <title>In-line elements</title>
       
       <sect3>
 	<title>Emphasising information</title>
 	
 	<para>When you want to emphasise a particular word or phrase, use
 	  <sgmltag>emphasis</sgmltag>.  This may be presented as italic, or
 	  bold, or might be spoken differently with a text-to-speech
 	  system.</para>
 	
 	<para>There is no way to change the presentation of the emphasis
 	  within your document, no equivalent of HTML's <sgmltag>b</sgmltag>
 	  and <sgmltag>i</sgmltag>.  If the information you are presenting is
 	  important then consider presenting it in
 	  <sgmltag>important</sgmltag> rather than
 	  <sgmltag>emphasis</sgmltag>.</para>
 	  
 	<example>
 	  <title><sgmltag>emphasis</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis>
   premiere Unix like operating system for the Intel architecture.</para>]]></programlisting>
 	  
 	  <para>Appearance:</para>
 	
 	  <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix
 	    like operating system for the Intel architecture.</para>
 	</example>
       </sect3>
 
       <sect3>
 	<title>Keys, mouse buttons, and combinations</title>
 
 	<para>To refer to a specific key on the keyboard, use
 	  <sgmltag>keycap</sgmltag>.  To refer to a mouse button, use
 	  <sgmltag>mousebutton</sgmltag>.  And to refer to combinations of key
 	  presses or mouse clicks, wrap them all in
 	  <sgmltag>keycombo</sgmltag>.</para>
 
 	<para><sgmltag>keycombo</sgmltag> has an attribute called
 	  <literal>action</literal>, which may be one of
 	  <literal>click</literal>, <literal>double-click</literal>,
 	  <literal>other</literal>, <literal>press</literal>,
 	  <literal>seq</literal>, or <literal>simul</literal>.  The last two
 	  values denote whether the keys or buttons should be pressed in
 	  sequence, or simultaneously.</para>
 
 	<para>The stylesheets automatically add any connecting symbols, such
 	  as <literal>+</literal>, between the key names, when wrapped in
 	  <sgmltag>keycombo</sgmltag>.</para>
 	
 	<example>
 	  <title>Keys, mouse buttons, and combinations</title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>To switch to the second virtual terminal, press 
   <keycombo action="simul"><keycap>Alt</keycap>
     <keycap>F1</keycap></keycombo>.</para>
 
 <para>To exit <command>vi</command> without saving your work, type
   <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
     <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
 
 <para>My window manager is configured so that
   <keycombo action="simul"><keycap>Alt</keycap>
     <mousebutton>right</mousebutton>
   </keycombo> mouse button is used to move windows.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>To switch to the second virtual terminal, press 
 	    <keycombo action="simul"><keycap>Alt</keycap>
 	      <keycap>F1</keycap></keycombo>.</para>
 
 	  <para>To exit <command>vi</command> without saving your work, type
 	    <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
 	      <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>
 
 	  <para>My window manager is configured so that
 	    <keycombo action="simul"><keycap>Alt</keycap>
 	      <mousebutton>right</mousebutton>
 	    </keycombo> mouse button is used to move windows.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Applications, commands, options, and cites</title>
 	
 	<para>You will frequently want to refer to both applications and
 	  commands when writing for the Handbook.  The distinction between
 	  them is simple: an application is the name for a suite (or possibly
 	  just 1) of programs that fulfil a particular task.  A command is the
 	  name of a program that the user can run.</para>
 
 	<para>In addition, you will occasionally need to list one or more of
 	  the options that a command might take.</para>
 	
 	<para>Finally, you will often want to list a command with its manual
 	  section number, in the &ldquo;command(number)&rdquo; format so
 	  common in Unix manuals.</para>
 	
 	<para>Mark up application names with
 	  <sgmltag>application</sgmltag>.</para>
 	
 	<para>When you want to list a command with its manual section number
 	  (which should be most of the time) the DocBook element is 
 	  <sgmltag>citerefentry</sgmltag>.  This will contain a further two
 	  elements, <sgmltag>refentrytitle</sgmltag> and
 	  <sgmltag>manvolnum</sgmltag>.  The content of
 	  <sgmltag>refentrytitle</sgmltag> is the name of the command, and the
 	  content of <sgmltag>manvolnum</sgmltag> is the manual page
 	  section.</para>
 
 	<para>This can be cumbersome to write, and so a series of <link
 	    linkend="sgml-primer-general-entities">general entities</link>
 	  have been created to make this easier.  Each entity takes the form
 	  <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
 
 	<para>The file that contains these entities is in
 	  <filename>doc/share/sgml/man-refs.ent</filename>, and can be
 	  referred to using this FPI:</para>
 
 	<programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
 
 	<para>Therefore, the introduction to your documentation will probably
 	  look like this:</para>
 
 	<programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 
 &lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
 %man;
 
 &hellip;
 
 ]&gt;</programlisting>
 
 	<para>Use <sgmltag>command</sgmltag> when you want to include a
 	  command name &ldquo;in-line&rdquo; but present it as something the
 	  user should type in.</para>
 
 	<para>Use <sgmltag>option</sgmltag> to mark up a command's
 	  options.</para>
 
 	<para>This can be confusing, and sometimes the choice is not always
 	  clear.  Hopefully this example makes it clearer.</para>
 
 	<example>
 	  <title>Applications, commands, and options.</title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para><application>Sendmail</application> is the most
   widely used Unix mail application.</para>
 
 <para><application>Sendmail</application> includes the
   <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry>, &man.mailq.8;, and &man.newaliases.8;
   programs.</para>
 
 <para>One of the command line parameters to <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry>, <option>-bp</option>, will display the current
   status of messages in the mail queue.  Check this on the command
   line by running <command>sendmail -bp</command>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para><application>Sendmail</application> is the most widely used
 	    Unix mail application.</para>
 	  
 	  <para><application>Sendmail</application> includes the
 	    <citerefentry>
 	      <refentrytitle>sendmail</refentrytitle>
 	      <manvolnum>8</manvolnum>
 	    </citerefentry>, <citerefentry>
 	      <refentrytitle>mailq</refentrytitle>
 	      <manvolnum>8</manvolnum>
 	    </citerefentry>, and <citerefentry>
 	      <refentrytitle>newaliases</refentrytitle>
 	      <manvolnum>8</manvolnum>
 	    </citerefentry> programs.</para>
 	  
 	  <para>One of the command line parameters to <citerefentry>
 	      <refentrytitle>sendmail</refentrytitle>
 	      <manvolnum>8</manvolnum>
 	    </citerefentry>, <option>-bp</option>, will display the current
 	    status of messages in the mail queue.  Check this on the command
 	    line by running <command>sendmail -bp</command>.</para>
 	</example>
 
 	<note>
 	  <para>Notice how the
 	    <literal>&amp;man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para>
 	</note>
       </sect3>
       
       <sect3>
 	<title>Files, directories, extensions</title>
 	
 	<para>Whenever you wish to refer to the name of a file, a directory,
 	  or a file extension, use <sgmltag>filename</sgmltag>.</para>
 	  
 	<example>
 	  <title><sgmltag>filename</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be
   found in <filename>/usr/doc/en/handbook/</filename>.  The first
   file is called <filename>handbook.sgml</filename> in that
   directory.  You should also see a <filename>Makefile</filename>
   and a number of files with a <filename>.ent</filename>
   extension.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>The SGML source for the Handbook in English can be found in
 	    <filename>/usr/doc/en/handbook/</filename>.  The first file is
 	    called <filename>handbook.sgml</filename> in that directory.  You
 	    should also see a <filename>Makefile</filename> and a number of
 	    files with a <filename>.ent</filename> extension.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Devices</title>
 	
 	<note>
 	  <title>FreeBSD extension</title>
 	  
 	  <para>These elements are part of the FreeBSD extension to DocBook,
 	    and do not exist in the original DocBook DTD.</para>
 	</note>
 	
 	<para>When referring to devices you have two choices.  You can either
 	  refer to the device as it appears in <filename>/dev</filename>, or
 	  you can use the name of the device as it appears in the kernel.  For
 	  this latter course, use <sgmltag>devicename</sgmltag>.</para>
 	  
 	<para>Sometimes you will not have a choice.  Some devices, such as
 	  networking cards, do not have entries in <filename>/dev</filename>,
 	  or the entries are markedly different from those entries.</para>
 	  
 	<example>
 	  <title><sgmltag>devicename</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para><devicename>sio</devicename> is used for serial
   communication in FreeBSD.  <devicename>sio</devicename> manifests
   through a number of entries in <filename>/dev</filename>, including
   <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>
 
 <para>By contrast, the networking devices, such as
   <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.
 
 <para>In MS-DOS, the first floppy drive is referred to as
   <devicename>a:</devicename>.  In FreeBSD it is
   <filename>/dev/fd0</filename>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	    
 	  <para><devicename>sio</devicename> is used for serial communication
 	    in FreeBSD.  <devicename>sio</devicename> manifests through a
 	    number of entries in <filename>/dev</filename>, including
 	    <filename>/dev/ttyd0</filename> and
 	    <filename>/dev/cuaa0</filename>.</para>
 	  
 	  <para>By contrast, the networking devices, such as
 	    <devicename>ed0</devicename> do not appear in
 	    <filename>/dev</filename>.</para>
 	    
 	  <para>In MS-DOS, the first floppy drive is referred to as
 	    <devicename>a:</devicename>.  In FreeBSD it is
 	    <filename>/dev/fd0</filename>.</para>	  
 	</example>
       </sect3>
 	
       <sect3>
 	<title>Hosts, domains, IP addresses, and so forth</title>
 	
 	<note>
 	  <title>FreeBSD extension</title>
 	  
 	  <para>These elements are part of the FreeBSD extension to DocBook,
 	    and do not exist in the original DocBook DTD.</para>
 	</note>
 	
 	<para>You can markup identification information for networked
 	  computers (hosts) in several ways, depending on the nature of the
 	  information.  All of them use <sgmltag>hostid</sgmltag> as the
 	  element, with the <literal>role</literal> attribute selecting the
 	  type of the marked up information.</para>
 	  
 	<variablelist>
 	  <varlistentry>
 	    <term>No role attribute, or
 	      <literal>role="hostname"</literal></term>
 	    
 	    <listitem>
 	      <para>With no role attribute (i.e.,
 		<sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the
 		marked up information is the simple hostname, such as
 		<literal>freefall</literal> or <literal>wcarchive</literal>.
 		You can explicitly specify this with
 		<literal>role="hostname"</literal>.</para>
 	    </listitem>
 	  </varlistentry>
 	    
 	  <varlistentry>
 	    <term><literal>role="domainname"</literal></term>
 	    
 	    <listitem>
 	      <para>The text is a domain name, such as
 		<literal>FreeBSD.org</literal> or
 		<literal>ngo.org.uk</literal>.  There is no hostname
 		component.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><literal>role="fqdn"</literal></term>
 	    
 	    <listitem>
 	      <para>The text is a Fully Qualified Domain Name, with both
 		hostname and domain name parts.</para>
 	    </listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>role="ipaddr"</literal></term>
 	    
 	    <listitem>
 	      <para>The text is an IP address, probably expressed as a dotted
 		quad.</para>
 	    </listitem>
 	  </varlistentry>
 
           <varlistentry>
             <term><literal>role="ip6addr"</literal></term>
 
             <listitem>
               <para>The text is an IPv6 address.</para>
             </listitem>
           </varlistentry>
 	  
 	  <varlistentry>
 	    <term><literal>role="netmask"</literal></term>
 	    
 	    <listitem>
 	      <para>The text is a network mask, which might be expressed as a
 		dotted quad, a hexadecimal string, or as a
 		<literal>/</literal> followed by a number.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><literal>role="mac"</literal></term>
 	    
 	    <listitem>
 	      <para>The text is an ethernet MAC address, expressed as a series
 		of 2 digit hexadecimal numbers separated by colons.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 	  
 	<example>
 	  <title><sgmltag>hostid</sgmltag> and roles</title>
 	    
 	  <para>Use:</para>
 	    
 	  <programlisting><![ CDATA [<para>The local machine can always be referred to by the
   name <hostid>localhost</hostid>, which will have the IP address
   <hostid role="ipaddr">127.0.0.1</hostid>.</para>
 
 <para>The <hostid role="domainname">FreeBSD.org</hostid> domain
   contains a number of different hosts, including
   <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
   <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>
 
 <para>When adding an IP alias to an interface (using
   <command>ifconfig</command>) <emphasis>always</emphasis> use a
   netmask of <hostid role="netmask">255.255.255.255</hostid>
   (which can also be expressed as <hostid
     role="netmask">0xffffffff</hostid>.</para>
 
 <para>The MAC address uniquely identifies every network card
   in existence.  A typical MAC address looks like <hostid
     role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>The local machine can always be referred to by the name
 	    <hostid>localhost</hostid>, which will have the IP address <hostid
 	      role="ipaddr">127.0.0.1</hostid>.</para>
 
 	  <para>The <hostid role="domainname">FreeBSD.org</hostid> domain
 	    contains a number of different hosts, including <hostid
 	      role="fqdn">freefall.FreeBSD.org</hostid> and <hostid
 	      role="fqdn">bento.FreeBSD.org</hostid>.</para>
 
 	  <para>When adding an IP alias to an interface (using
 	    <command>ifconfig</command>) <emphasis>always</emphasis> use a
 	    netmask of <hostid role="netmask">255.255.255.255</hostid> (which
 	    can also be expressed as <hostid
 	      role="netmask">0xffffffff</hostid>.</para>
 
 	  <para>The MAC address uniquely identifies every network card in
 	    existence.  A typical MAC address looks like <hostid
 	      role="mac">08:00:20:87:ef:d0</hostid>.</para>	  
 	</example>
       </sect3>
       
       <sect3>
 	<title>Usernames</title>
 	
 	<note>
 	  <title>FreeBSD extension</title>
 	  
 	  <para>These elements are part of the FreeBSD extension to DocBook,
 	    and do not exist in the original DocBook DTD.</para>
 	</note>
 	
 	<para>When you need to refer to a specific username, such as
 	  <literal>root</literal> or <literal>bin</literal>, use
 	  <sgmltag>username</sgmltag>.</para>
 	
 	<example>
 	  <title><sgmltag>username</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>To carry out most system administration functions you
   will need to be <username>root</username>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>To carry out most system administration functions you will
 	    need to be <username>root</username>.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title>Describing <filename>Makefile</filename>s</title>
 	
 	<note>
 	  <title>FreeBSD extension</title>
 	  
 	  <para>These elements are part of the FreeBSD extension to DocBook,
 	    and do not exist in the original DocBook DTD.</para>
 	</note>
 	
 	<para>Two elements exist to describe parts of
 	  <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and
 	  <sgmltag>makevar</sgmltag>.</para>
 	  
 	<para><sgmltag>maketarget</sgmltag> identifies a build target exported
 	  by a <filename>Makefile</filename> that can be given as a parameter
 	  to <command>make</command>.  <sgmltag>makevar</sgmltag> identifies a
 	  variable that can be set (in the environment, on the
 	  <command>make</command> command line, or within the
 	  <filename>Makefile</filename>) to influence the process.</para>
 
 	<example>
 	  <title><sgmltag>maketarget</sgmltag> and
 	    <sgmltag>makevar</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>Two common targets in a <filename>Makefile</filename>
   are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>
 
 <para>Typically, invoking <maketarget>all</maketarget> will rebuild the
   application, and invoking <maketarget>clean</maketarget> will remove
   the temporary files (<filename>.o</filename> for example) created by
   the build process.</para>
 
 <para><maketarget>clean</maketarget> may be controlled by a number of
   variables, including <makevar>CLOBBER</makevar> and
   <makevar>RECURSE</makevar>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>Two common targets in a <filename>Makefile</filename> are
 	    <maketarget>all</maketarget> and
 	    <maketarget>clean</maketarget>.</para>
 	    
 	  <para>Typically, invoking <maketarget>all</maketarget> will rebuild
 	    the application, and invoking <maketarget>clean</maketarget> will
 	    remove the temporary files (<filename>.o</filename> for example)
 	    created by the build process.</para>
 	    
 	  <para><maketarget>clean</maketarget> may be controlled by a number
 	    of variables, including <makevar>CLOBBER</makevar> and
 	    <makevar>RECURSE</makevar>.</para>	  
 	</example>
       </sect3>
       
       <sect3>
 	<title>Literal text</title>
 	
 	<para>You will often need to include &ldquo;literal&rdquo; text in the
 	  Handbook.  This is text that is excerpted from another file, or
 	  which should be copied from the Handbook into another file
 	  verbatim.</para>
 
 	<para>Some of the time, <sgmltag>programlisting</sgmltag> will be
 	  sufficient to denote this text.  <sgmltag>programlisting</sgmltag>
 	  is not always appropriate, particularly when you want to include a
 	  portion of a file &ldquo;in-line&rdquo; with the rest of the
 	  paragraph.</para>
 
 	<para>On these occasions, use <sgmltag>literal</sgmltag>.</para>
 	
 	<example>
 	  <title><sgmltag>literal</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel
   configuration file determines the size of many system tables, and is
   a rough guide to how many simultaneous logins the system will
   support.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>The <literal>maxusers 10</literal> line in the kernel
 	    configuration file determines the size of many system tables, and
 	    is a rough guide to how many simultaneous logins the system will
 	    support.</para>
 	</example>
       </sect3>
 	
       <sect3>
 	<title>Showing items that the user <emphasis>must</emphasis> fill
 	  in</title>
 	
 	<para>There will often be times when you want to show the user what to
 	  do, or refer to a file, or command line, or similar, where the user
-	  can not simply copy the examples that you provide, but must instead
+	  cannot simply copy the examples that you provide, but must instead
 	  include some information themselves.</para>
 	
 	<para><sgmltag>replaceable</sgmltag> is designed for this eventuality.
 	  Use it <emphasis>inside</emphasis> other elements to indicate parts
 	  of that element's content that the user must replace.</para>
 	
 	<example>
 	  <title><sgmltag>replaceable</sgmltag></title>
 	  
 	  <para>Use:</para>
 	  
 	  <programlisting><![ CDATA [<informalexample>
   <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
 </informalexample>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
 	  </informalexample>
 	  
 	  <para><sgmltag>replaceable</sgmltag> can be used in many different
 	    elements, including <sgmltag>literal</sgmltag>.  This example also
 	    shows that <sgmltag>replaceable</sgmltag> should only be wrapped
 	    around the content that the user <emphasis>is</emphasis> meant to
 	    provide.  The other content should be left alone.</para>
 	    
 	  <para>Use:</para>
 	    
 	  <programlisting><![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal>
   line in the kernel configuration file determines the size of many system
   tables, and is a rough guide to how many simultaneous logins the system will
   support.</para>
 
 <para>For a desktop workstation, <literal>32</literal> is a good value
   for <replaceable>n</replaceable>.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 	  
 	  <para>The <literal>maxusers <replaceable>n</replaceable></literal>
 	    line in the kernel configuration file determines the size of many
 	    system tables, and is a rough guide to how many simultaneous
 	    logins the system will support.</para>
 
 	  <para>For a desktop workstation, <literal>32</literal> is a good
 	    value for <replaceable>n</replaceable>.</para>	  
 	</example>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Images</title>
 
       <important>
 	<para>Image support in the documentation is currently extremely
 	  experimental.  I think the mechanisms described here are unlikely to
 	  change, but that's not guaranteed.</para>
 
 	<para>You will also need to install the
 	  <filename>graphics/ImageMagick</filename> port, which is used to
 	  convert between the different image formats.  This is a big port,
 	  and most of it is not required.  However, while we're working on the
 	  <filename>Makefile</filename>s and other infrastructure it makes
 	  things easier.  This port is <emphasis>not</emphasis> in the
 	  <filename>textproc/docproj</filename> meta port, you must install it
 	  by hand.</para>
 
 	<para>The best example of what follows in practice is the
 	  <filename>en_US.ISO8859-1/articles/vm-design/</filename> document.
 	  If you're unsure of the description that follows, take a look at the
 	  files in that directory to see how everything hangs togther.
 	  Experiment with creating different formatted versions of the
 	  document to see how the image markup appears in the formatted
 	  output.</para>
       </important>
 
       <sect3>
 	<title>Image formats</title>
 
 	<para>We currently support two formats for images.  The format you
 	  should use will depend on the nature of your image.</para>
 
 	<para>For images that are primarily vector based, such as network
 	  diagrams, timelines, and similar, use Encapsulated Postscript, and
 	  make sure that your images have the <filename>.eps</filename>
 	  extension.</para>
 
 	<para>For bitmaps, such as screen captures, use the Portable Network
 	  Graphic format, and make sure that your images have the
 	  <filename>.png</filename> extension.</para>
 
 	<para>These are the <emphasis>only</emphasis> formats in which images
 	  should be committed to the CVS repository.</para>
 
 	<para>Use the right format for the right image.  It is to be expected
 	  that your documentation will have a mix of EPS and PNG images.  The
 	  <filename>Makefile</filename>s ensure that the correct format image
 	  is chosen depending on the output format that you use for your
 	  documentation.  <emphasis>Do not commit the same image to the
 	    repository in two different formats</emphasis>.</para>
 
 	<important>
 	  <para>It is anticipated that the Documentation Project will switch to
 	    using the Scalable Vector Graphic (SVG) format for vector images.
 	    However, the current state of SVG capable editing tools makes this
 	    impractical.</para>
 	</important>
       </sect3>
 
       <sect3>
 	<title>Markup</title>
 
 	<para>The markup for an image is relatively simple.  First, markup a
 	  <sgmltag>mediaobject</sgmltag>.  The <sgmltag>mediaobject</sgmltag>
 	  can contain other, more specific objects.  We are concerned with
 	  two, the <sgmltag>imageobject</sgmltag> and the
 	  <sgmltag>textobject</sgmltag>.</para>
 
 	<para>You should include one <sgmltag>imageobject</sgmltag>, and two
 	  <sgmltag>textobject</sgmltag> elements.  The
 	  <sgmltag>imageobject</sgmltag> will point to the name of the image
 	  file that will be used (without the extension).  The
 	  <sgmltag>textobject</sgmltag> elements contain information that will
 	  be presented to the user as well as, or instead of, the
 	  image.</para>
 
 	<para>There are two circumstances where this can happen.</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>When the reader is viewing the documentation in HTML.  In
 	      this case, each image will need to have associated alternate
 	      text to show the user, typically whilst the image is loading, or
 	      if they hover the mouse pointer over the image.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>When the reader is viewing the documentation in plain text.
 	      In this case, each image should have an ASCII art equivalent to
 	      show the user.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>An example will probably make things easier to understand.
 	  Suppose you have an image, called <filename>fig1</filename>, that
 	  you want to include in the document.  This image is of a rectangle
 	  with an A inside it.  The markup for this would be as
 	  follows.</para>
 
 	<programlisting>&lt;mediaobject>
   &lt;imageobject>
     &lt;imagedata fileref="fig1"> <co id="co-image-ext">
   &lt;/imageobject>
 
   &lt;textobject>
     &lt;literallayout class="monospaced">+---------------+ <co id="co-image-literal">
 |       A       |
 +---------------+&lt;/literallayout>
   &lt;/textobject>
 
   &lt;textobject>
     &lt;phrase>A picture&lt;/phrase> <co id="co-image-phrase">
   &lt;/textobject>
 &lt;/mediaobject></programlisting>
 
 	<calloutlist>
 	  <callout arearefs="co-image-ext">
 	    <para>Include an <sgmltag>imagedata</sgmltag> element inside the
 	      <sgmltag>imageobject</sgmltag> element.  The
 	      <literal>fileref</literal> attribute should contain the filename
 	      of the image to include, without the extension.  The stylesheets
 	      will work out which extension should be added to the filename
 	      automatically.</para>
 	  </callout>
 
 	  <callout arearefs="co-image-literal">
 	    <para>The first <sgmltag>textobject</sgmltag> should contain a
 	      <sgmltag>literallayout</sgmltag> element, where the
 	      <literal>class</literal> attribute is set to
 	      <literal>monospaced</literal>.  This is your opportunity to
 	      demonstrate your ASCII art skills.  This content will be used if
 	      the document is converted to plain text.</para>
 
 	    <para>Notice how the first and last lines of the content of the
 	      <sgmltag>literallayout</sgmltag> element butt up next to the
 	      element's tags.  This ensures no extraneous white space is
 	      included.</para>
 	  </callout>
 
 	  <callout arearefs="co-image-phrase">
 	    <para>The second <sgmltag>textobject</sgmltag> should contain a
 	      single <sgmltag>phrase</sgmltag> element.  The contents of this
 	      will become the <literal>alt</literal> attribute for the image
 	      when this document is converted to HTML.</para>
 	  </callout>
 	</calloutlist>
       </sect3>
 
       <sect3>
 	<title><filename>Makefile</filename> entries</title>
 
 	<para>Your images must be listed in the
 	  <filename>Makefile</filename> in the <makevar>IMAGES</makevar>
 	  variable.  This variable should contain the name of all your
 	  <emphasis>source</emphasis> images.  For example, if you have
 	  created three figures, <filename>fig1.eps</filename>,
 	  <filename>fig2.png</filename>, <filename>fig3.png</filename>, then
 	  your <filename>Makefile</filename> should have lines like this in
 	  it.</para>
 
 	<programlisting>&hellip;
 IMAGES= fig1.eps fig2.png fig3.png
 &hellip;</programlisting>
 
 	<para>or</para>
 
 	<programlisting>&hellip;
 IMAGES=  fig1.eps
 IMAGES+= fig2.png
 IMAGES+= fig3.png
 &hellip;</programlisting>
 
 	<para>Again, the <filename>Makefile</filename> will work out the
 	  complete list of images it needs to build your source document, you
 	  only need to list the image files <emphasis>you</emphasis>
 	  provided.</para>
       </sect3>
 
       <sect3>
 	<title>Images and chapters in subdirectories</title>
 
 	<para>You must be careful when you separate your documentation in to
 	  smaller files (see <xref linkend="sgml-primer-include-using-gen-entities">) in
 	  different directories.</para>
 	  
 	<para>Suppose you have a book with three chapters, and the chapters
 	  are stored in their own directories, called
 	  <filename>chapter1/chapter.sgml</filename>,
 	  <filename>chapter2/chapter.sgml</filename>, and
 	  <filename>chapter3/chapter.sgml</filename>.  If each chapter has
 	  images associated with it, I suggest you place those images in each
 	  chapter's subdirectory (<filename>chapter1/</filename>,
 	  <filename>chapter2/</filename>, and
 	  <filename>chapter3/</filename>).</para>
 
 	<para>However, if you do this you must include the directory names in
 	  the <makevar>IMAGES</makevar> variable in the
 	  <filename>Makefile</filename>, <emphasis>and</emphasis> you must
 	  include the directory name in the <sgmltag>imagedata</sgmltag>
 	  element in your document.</para>
 
 	<para>For example, if you have <filename>chapter1/fig1.png</filename>,
 	  then <filename>chapter1/chapter.sgml</filename> should
 	  contain</para>
 
 	<programlisting>&lt;mediaobject>
   &lt;imageobject>
     &lt;imagedata fileref="chapter1/fig1"> <co id="co-image-dir">
   &lt;/imageobject>
 
   &hellip;
 
 &lt;/mediaobject></programlisting>
 	
 	<calloutlist>
 	  <callout arearefs="co-image-dir">
 	    <para>The directory name must be included in the
 	      <literal>fileref</literal> attribute</para>
 	  </callout>
 	</calloutlist>
 
 	<para>The <filename>Makefile</filename> must contain</para>
 
 	<programlisting>&hellip;
 IMAGES=  chapter1/fig1.png
 &hellip;</programlisting>
 
 	<para>Then everything should just work.</para>
       </sect3>
     </sect2>
     
     <sect2>
       <title>Links</title>
 
       <note>
 	<para>Links are also in-line elements.</para>
       </note>
 
       <sect3>
 	<title>Linking to other parts of the same document</title>
 
 	<para>Linking within the same document requires you to specify
 	  where you are linking from (i.e., the text the user will click, or
 	  otherwise indicate, as the source of the link) and where you are
 	  linking to (the link's destination).</para>
 
 	<para>Each element within DocBook has an attribute called
 	  <literal>id</literal>.  You can place text in this attribute to
 	  uniquely name the element it is attached to.</para>
 
 	  <para>This value will be used when you specify the link
 	  source.</para>
 
 	<para>Normally, you will only be linking to chapters or sections, so
 	  you would add the <literal>id</literal> attribute to these
 	  elements.</para>
 
 	<example>
 	  <title><literal>id on chapters and sections</literal></title>
 
 	  <programlisting><![ CDATA [<chapter id="chapter1">
   <title>Introduction</title>
 
   <para>This is the introduction.  It contains a subsection,
     which is identified as well.</para>
 
   <sect1 id="chapter1-sect1">
     <title>Sub-sect 1</title>
 
     <para>This is the subsection.</para>
   </sect1>
 </chapter>]]></programlisting>
 	</example>
 	
 	<para>Obviously, you should use more descriptive values.  The values
 	  must be unique within the document (i.e., not just the file, but the
 	  document the file might be included in as well).  Notice how the
 	  <literal>id</literal> for the subsection is constructed by appending
 	  text to the <literal>id</literal> of the chapter.  This helps to
 	  ensure that they are unique.</para>
 
 	<para>If you want to allow the user to jump into a specific portion of
 	  the document (possibly in the middle of a paragraph or an example),
 	  use <sgmltag>anchor</sgmltag>.  This element has no content, but
 	  takes an <literal>id</literal> attribute.</para>
 
 	<example>
 	  <title><sgmltag>anchor</sgmltag></title>
 
 	  <programlisting><![ CDATA [<para>This paragraph has an embedded
   <anchor id="para1">link target in it.  It won't show up in
   the document.</para>]]></programlisting>
 	</example>
 	
 	<para>When you want to provide the user with a link they can activate
 	  (probably by clicking) to go to a section of the document that has
 	  an <literal>id</literal> attribute, you can use either
 	  <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para>
 
 	<para>Both of these elements have a <literal>linkend</literal>
 	  attribute.  The value of this attribute should be the value that you
 	  have used in a <literal>id</literal> attribute (it does not matter
 	  if that value has not yet occurred in your document; this will work
 	  for forward links as well as backward links).</para>
 	
 	<para>If you use <sgmltag>xref</sgmltag> then you have no control over
 	  the text of the link.  It will be generated for you.</para>
 	
 	<example>
 	  <title>Using <sgmltag>xref</sgmltag></title>
 
 	  <para>Assume that this fragment appears somewhere in a document that
 	    includes the <literal>id</literal> example;</para>
 	  
 	  <programlisting><![ CDATA [<para>More information can be found
   in <xref linkend="chapter1">.</para>
 
 <para>More specific information can be found
   in <xref linkend="chapter1-sect1">.</para>]]></programlisting>
 
 	  <para>The text of the link will be generated automatically, and will
 	    look like (<emphasis>emphasised</emphasis> text indicates the text
 	    that will be the link);</para>
 
 	  <blockquote>
 	    <para>More information can be found in <emphasis>Chapter
 		One</emphasis>.</para>
 
 	    <para>More specific information can be found in <emphasis>the
 		section called Sub-sect 1</emphasis>.</para>
 	  </blockquote>
 	</example>
 	
 	<para>Notice how the text from the link is derived from the section
 	  title or the chapter number.</para>
 
 	<note>
-	  <para>This means that you <emphasis>can not</emphasis> use
+	  <para>This means that you <emphasis>cannot</emphasis> use
 	    <sgmltag>xref</sgmltag> to link to an <literal>id</literal>
 	    attribute on an <sgmltag>anchor</sgmltag> element.  The
 	    <sgmltag>anchor</sgmltag> has no content, so the
-	    <sgmltag>xref</sgmltag> can not generate the text for the
+	    <sgmltag>xref</sgmltag> cannot generate the text for the
 	    link.</para>
 	</note>
 	
 	<para>If you want to control the text of the link then use
 	  <sgmltag>link</sgmltag>.  This element wraps content, and the
 	  content will be used for the link.</para>
 
 	<example>
 	  <title>Using <sgmltag>link</sgmltag></title>
 
 	  <para>Assume that this fragment appears somewhere in a document that
 	    includes the <literal>id</literal> example.</para>
 
 	  <programlisting><![ CDATA [<para>More information can be found in
   <link linkend="chapter1">the first chapter</link>.</para>
 
 <para>More specific information can be found in
   <link linkend="chapter1-sect1>this</link> section.</para>]]></programlisting>
 	  
 	  <para>This will generate the following
 	    (<emphasis>emphasised</emphasis> text indicates the text that will
 	    be the link);</para>
 	  
 	  <blockquote>
 	    <para>More information can be found in <emphasis>the first
 		chapter</emphasis>.</para>
 	    
 	    <para>More specific information can be found in
 	      <emphasis>this</emphasis> section.</para>
 	  </blockquote>
 	</example>
 	
 	<note>
 	  <para>That last one is a bad example.  Never use words like
 	    &ldquo;this&rdquo; or &ldquo;here&rdquo; as the source for the
 	    link.  The reader will need to hunt around the surrounding context
 	    to see where the link is actually taking them.</para>
 	</note>
 
 	<note>
 	  <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to
 	    include a link to an <literal>id</literal> on an
 	    <sgmltag>anchor</sgmltag> element, since the
 	    <sgmltag>link</sgmltag> content defines the text that will be used
 	    for the link.</para>
 	</note>
       </sect3>
 
       <sect3>
 	<title>Linking to documents on the WWW</title>
 
 	<para>Linking to external documents is much simpler, as long as you
 	  know the URL of the document you want to link to.  Use
 	  <sgmltag>ulink</sgmltag>.  The <literal>url</literal> attribute is
 	  the URL of the page that the link points to, and the content of the
 	  element is the text that will be displayed for the user to
 	  activate.</para>
 
 	<example>
 	  <title><sgmltag>ulink</sgmltag></title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<para>Of course, you could stop reading this document and
   go to the <ulink url="http://www.FreeBSD.org/">FreeBSD
   home page</ulink> instead.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 
 	  <para>Of course, you could stop reading this document and go to the
 	    <ulink url="http://www.FreeBSD.org/">FreeBSD home page</ulink>
 	    instead.</para>
 	</example>
       </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/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
index b65fb4fb76..f464eb36cc 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,1556 +1,1556 @@
 <!-- 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: doc/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml,v 1.17 2001/04/17 16:16:19 nik Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml,v 1.18 2001/07/13 20:49:35 nik Exp $
 -->
 
 <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 &ldquo;typewriter&rdquo; style 
       font for viewing on screen, but as &ldquo;italics&rdquo; 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 can not.  For this we need
+      computer processing the document cannot.  For this we need
       markup.</para>
     
     <para>&ldquo;Markup&rdquo; is commonly used to describe &ldquo;adding
       value&rdquo; or &ldquo;increasing cost&rdquo;.  The term takes on both
       these meanings when applied to text.  Markup is additional text included 
       in the document, distinguished from the document's content in some way,
       so that programs that process the document can read the markup and use
       it when making decisions about the document.  Editors can hide the
       markup from the user, so the user is not distracted by it.</para>
 
     <para>The extra information stored in the markup <emphasis>adds
 	value</emphasis> to the document.  Adding the markup to the document
       must typically be done by a person&mdash;after all, if computers could
       recognise the text sufficiently well to add the markup then there would
       be no need to add it in the first place.  This <emphasis>increases the
 	cost</emphasis> (i.e., the effort required) to create the
 	document.</para>
 
     <para>The previous example is actually represented in this document like
       this;</para>
 
     <programlisting><![ CDATA [
 <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
 
 <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting>
 
     <para>As you can see, the markup is clearly separate from the
       content.</para>
 
     <para>Obviously, if you are going to use markup you need to define what
       your markup means, and how it should be interpreted.  You will need a
       markup language that you can follow when marking up your
       documents.</para>
     
    <para>Of course, one markup language might not be enough.  A markup
       language for technical documentation has very different requirements
       than a markup language that was to be used for cookery recipes.  This,
       in turn, would be very different from a markup language used to describe
       poetry.  What you really need is a first language that you use to write
       these other markup languages.  A <emphasis>meta markup
 	language</emphasis>.</para>
     
     <para>This is exactly what the Standard Generalised Markup Language (SGML)
       is.  Many markup languages have been written in SGML, including the two
       most used by the FDP, HTML and DocBook.</para>
     
     <para>Each language definition is more properly called a Document Type
       Definition (DTD).  The DTD specifies the name of the elements that can
       be used, what order they appear in (and whether some markup can be used
       inside other markup) and related information.  A DTD is sometimes
       referred to as an <emphasis>application</emphasis> of SGML.</para>
 
     <para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis>
       specification of all the elements that are allowed to appear, the order
       in which they should appear, which elements are mandatory, which are
       optional, and so forth. This makes it possible to write an SGML
       <emphasis>parser</emphasis> which reads in both the DTD and a document
       which claims to conform to the DTD.  The parser can then confirm whether
       or not all the elements required by the DTD are in the document in the
       right order, and whether there are any errors in the markup.  This is
       normally referred to as <quote>validating  the document</quote>.</para>
 
     <note>
       <para>This processing simply confirms that the choice of elements, their 
 	ordering, and so on, conforms to that listed in the DTD.  It does
 	<emphasis>not</emphasis> check that you have used
 	<emphasis>appropriate</emphasis> markup for the content.  If you were
 	to try and mark up all the filenames in your document as function
 	names, the parser would not flag this as an error (assuming, of
 	course, that your DTD defines elements for filenames and functions,
 	and that they are allowed to appear in the same place).</para>
     </note>
     
     <para>It is likely that most of your contributions to the Documentation
       Project will consist of content marked up in either HTML or DocBook,
       rather than alterations to the DTDs.  For this reason this book will
       not touch on how to write a DTD.</para>
   </sect1>
   
   <sect1 id="sgml-primer-elements">
     <title>Elements, tags, and attributes</title>
 
     <para>All the DTDs written in SGML share certain characteristics.  This is
       hardly surprising, as the philosophy behind SGML will inevitably show
       through. One of the most obvious manifestations of this philisophy 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 &ldquo;book&rdquo; 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 &ldquo;chunking&rdquo; 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 differentation 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 knowledgable about SGML) refers
 	to &ldquo;the &lt;p&gt; tag&rdquo; they mean the literal text
 	consisting of the three characters <literal>&lt;</literal>,
 	<literal>p</literal>, and <literal>&gt;</literal>.  But the phrase
 	&ldquo;the &lt;p&gt; element&rdquo; 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 occurence 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'm 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>
 
     <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>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>.</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
 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</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>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 occured
 	    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 don't need to know this, but it's useful background, and
 	  might help you debug problems when your SGML processor can't 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 &ldquo;ISO&rdquo; 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 hasn't been registered the
 	      owner string is <literal>-//FreeBSD</literal>.  And as you can
 	      see, the W3C are not a registered owner either.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Keyword</replaceable></term>
 	  
 	  <listitem>
 	    <para>There are several keywords that indicate the type of
 	      information in the file.  Some of the most common keywords are
 	      <literal>DTD</literal>, <literal>ELEMENT</literal>,
 	      <literal>ENTITIES</literal>, and <literal>TEXT</literal>.
 	      <literal>DTD</literal> is used only for DTD files,
 	      <literal>ELEMENT</literal> is usually used for DTD fragments
 	      that contain only entity or element declarations.
 	      <literal>TEXT</literal> is used for SGML content (text and
 	      tags).</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Description</replaceable></term>
 	  
 	  <listitem>
 	    <para>Any description you want to supply for the contents of this
 	      file.  This may include version numbers or any short text that
 	      is meaningful to you and unique for the SGML system.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Language</replaceable></term>
 	  
 	  <listitem>
 	    <para>This is an ISO two-character code that identifies the native
 	      language for the file.  <literal>EN</literal> is used for
 	      English.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <sect3>
 	<title><filename>catalog</filename> files</title>
 	
 	<para>If you use the syntax above and try and process this document
 	  using an SGML processor, the processor will need to have some way of
 	  turning the FPI into the name of the file on your computer that
 	  contains the DTD.</para>
 	
 	<para>In order to do this it can use a catalog file.  A catalog file
 	  (typically called <filename>catalog</filename>) contains lines that
 	  map FPIs to filenames.  For example, if the catalog file contained
 	  the line;</para>
 	
 	<programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"</programlisting>
 
 	<para>The SGML processor would know to look up the DTD from
 	  <filename>strict.dtd</filename> in the <filename>4.0</filename>
 	  subdirectory of whichever directory held the
 	  <filename>catalog</filename> file that contained that line.</para>
 
 	<para>Look at the contents of
 	  <filename>/usr/local/share/sgml/html/catalog</filename>.  This is
 	  the catalog file for the HTML DTDs that will have been installed as
 	  part of the <filename>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 don't
 	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
       &ldquo;<literal>--</literal>&rdquo;.  The first occurence 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>Errorneous 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 can not use general entities in an SGML context (although you
+      <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; can not normally appear in an SGML document.  When the SGML
+	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 won't 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
       &ldquo;marked sections&rdquo;.</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 &ldquo;content model&rdquo;.</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 &ldquo;Character Data&rdquo;.
 	  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 &ldquo;Entity references and
 	  character data&rdquo; 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>
 
 	<!-- 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's
       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 isn't 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 wasn't to
 	  appear in the hard-copy.</para>
 
 	<para>Create a parameter entity, and set it's 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/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
index aa432bd05c..c52f577af6 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,3859 +1,3859 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.56 2001/07/14 23:40:27 murray Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.57 2001/07/17 00:11:17 chern Exp $
 -->
 
 <chapter id="advanced-networking">
   <title>Advanced Networking</title>
 
   <sect1>
     <title>Synopsis</title>
 
     <para>The following chapter will cover some of the more frequently
-      used network services on UNIX systems.  This, of course, will
+      used network services on Unix systems.  This, of course, will
       pertain to configuring said services on your FreeBSD system.</para>
   </sect1>
 
   <sect1 id="routing">
     <title>Gateways and Routes</title>
     
     <para><emphasis>Contributed by &a.gryphon;. 6 October
 	1995.</emphasis></para>
 
     <indexterm><primary>route</primary></indexterm>
     <indexterm><primary>routing</primary></indexterm>
     <indexterm><primary>gateway</primary></indexterm>
     <indexterm><primary>subnet</primary></indexterm>
     <para>For one machine to be able to find another, there must be a
       mechanism in place to describe how to get from one to the other. This is
       called Routing.  A <quote>route</quote> is a defined pair of addresses: a
       <quote>destination</quote> and a <quote>gateway</quote>.  The pair
       indicates that if you are trying to get to this
       <emphasis>destination</emphasis>, send along through this
       <emphasis>gateway</emphasis>.  There are three types of destinations:
       individual hosts, subnets, and <quote>default</quote>.  The
       <quote>default route</quote> is used if none of the other routes apply.
       We will talk a little bit more about default routes later on.  There are
       also three types of gateways: individual hosts, interfaces (also called
       <quote>links</quote>), and ethernet hardware addresses.</para>
 
     <sect2>
       <title>An example</title>
       
       <para>To illustrate different aspects of routing, we will use the
 	following example which is the output of the command <command>netstat
 	  -r</command>:</para>
 	  
       <screen>Destination      Gateway            Flags     Refs     Use     Netif Expire
 
 default          outside-gw         UGSc       37      418      ppp0
 localhost        localhost          UH          0      181       lo0
 test0            0:e0:b5:36:cf:4f   UHLW        5    63288       ed0     77
 10.20.30.255     link#1             UHLW        1     2421 
 foobar.com       link#1             UC          0        0 
 host1            0:e0:a8:37:8:1e    UHLW        3     4601       lo0
 host2            0:e0:a8:37:8:1e    UHLW        0        5       lo0 =>
 host2.foobar.com link#1             UC          0        0
 224              link#1             UC          0        0</screen>
 	  
       <indexterm><primary>default route</primary></indexterm>
       <para>The first two lines specify the default route (which we will cover
 	in the next section) and the <hostid>localhost</hostid> route.</para>
 	  
       <indexterm><primary>loopback device</primary></indexterm>
       <para>The interface (<literal>Netif</literal> column) that it specifies
 	to use for <literal>localhost</literal> is
 	<devicename>lo0</devicename>, also known as the loopback device.  This
 	says to keep all traffic for this destination internal, rather than
 	sending it out over the LAN, since it will only end up back where it
 	started anyway.</para>
       
       <indexterm>
         <primary>Ethernet</primary>
         <secondary>MAC address</secondary>
       </indexterm>
       <para>The next thing that stands out are the <hostid
 	  role="mac">0:e0:...</hostid> addresses.  These are ethernet hardware
 	addresses.  FreeBSD will automatically identify any hosts
 	(<hostid>test0</hostid> in the example) on the local ethernet and add
 	a route for that host, directly to it over the ethernet interface,
 	<devicename>ed0</devicename>.  There is also a timeout
 	(<literal>Expire</literal> column) associated with this type of route,
 	which is used if we fail to hear from the host in a specific amount of
 	time.  In this case the route will be automatically deleted.  These
 	hosts are identified using a mechanism known as RIP (Routing
 	Information Protocol), which figures out routes to local hosts based
 	upon a shortest path determination.</para>
 
       <indexterm><primary>subnet</primary></indexterm>	  
       <para>FreeBSD will also add subnet routes for the local subnet (<hostid
 	  role="ipaddr">10.20.30.255</hostid> is the broadcast address for the
 	subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid
 	  role="domainname">foobar.com</hostid> is the domain name associated
 	with that subnet).  The designation <literal>link#1</literal> refers
 	to the first ethernet card in the machine.  You will notice no
 	additional interface is specified for those.</para>
 	  
       <para>Both of these groups (local network hosts and local subnets) have
 	their routes automatically configured by a daemon called
 	<command>routed</command>.  If this is not run, then only routes which
 	are statically defined (ie. entered explicitly) will exist.</para>
 	  
       <para>The <literal>host1</literal> line refers to our host, which it
 	knows by ethernet address.  Since we are the sending host, FreeBSD
 	knows to use the loopback interface (<devicename>lo0</devicename>)
 	rather than sending it out over the ethernet interface.</para>
 	  
       <para>The two <literal>host2</literal> lines are an example of what
 	happens when we use an ifconfig alias (see the section of ethernet for
 	reasons why we would do this).  The <literal>=&gt;</literal> symbol
 	after the <devicename>lo0</devicename> interface says that not only
 	are we using the loopback (since this is address also refers to the
 	local host), but specifically it is an alias.  Such routes only show
 	up on the host that supports the alias; all other hosts on the local
 	network will simply have a <literal>link#1</literal> line for
 	such.</para>
 	  
       <para>The final line (destination subnet <literal>224</literal>) deals
 	with MultiCasting, which will be covered in a another section.</para>
 	  
       <para>The other column that we should talk about are the
 	<literal>Flags</literal>.  Each route has different attributes that
 	are described in the column.  Below is a short table of some of these
 	flags and their meanings:</para>
 	  
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <tbody>
 	    <row>
 	      <entry>U</entry>
 	      <entry>Up: The route is active.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>H</entry>
 	      <entry>Host: The route destination is a single host.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>G</entry>
 	      <entry>Gateway: Send anything for this destination on to this
 		remote system, which will figure out from there where to send
 		it.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>S</entry>
 	      <entry>Static: This route was configured manually, not
 		automatically generated by the system.</entry>
 	    </row>
 	      
 	    <row>
 	      <entry>C</entry>
 	      <entry>Clone: Generates a new route based upon this route for
 		machines we connect to. This type of route is normally used
 		for local networks.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>W</entry>
 	      <entry>WasCloned: Indicated a route that was auto-configured
 		based upon a local area network (Clone) route.</entry>
 	    </row>
 	      
 	    <row>
 	      <entry>L</entry>
 	      <entry>Link: Route involves references to ethernet
 		hardware.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
     
     <sect2>
       <title>Default routes</title>
       
       <indexterm><primary>default route</primary></indexterm>	  
       <para>When the local system needs to make a connection to remote host,
 	it checks the routing table to determine if a known path exists.  If
 	the remote host falls into a subnet that we know how to reach (Cloned
 	routes), then the system checks to see if it can connect along that
 	interface.</para>
 	  
       <para>If all known paths fail, the system has one last option: the
 	<quote>default</quote> route.  This route is a special type of gateway
 	route (usually the only one present in the system), and is always
 	marked with a <literal>c</literal> in the flags field.  For hosts on a
 	local area network, this gateway is set to whatever machine has a
 	direct connection to the outside world (whether via PPP link, or your
 	hardware device attached to a dedicated data line).</para>
       
       <para>If you are configuring the default route for a machine which
 	itself is functioning as the gateway to the outside world, then the
 	default route will be the gateway machine at your Internet Service
 	Provider's (ISP) site.</para>
 	  
       <para>Let us look at an example of default routes.  This is a common
 	configuration:</para>
 	    
       <literallayout>
 [Local2]  &lt;--ether--&gt;  [Local1]  &lt;--PPP--&gt; [ISP-Serv]  &lt;--ether--&gt;  [T1-GW]
       </literallayout>
 	  
       <para>The hosts <hostid>Local1</hostid> and <hostid>Local2</hostid> are
 	at your site, with the formed being your PPP connection to your ISP's
 	Terminal Server.  Your ISP has a local network at their site, which
 	has, among other things, the server where you connect and a hardware
 	device (T1-GW) attached to the ISP's Internet feed.</para>
       
       <para>The default routes for each of your machines will be:</para>
       
       <informaltable frame="none">
 	<tgroup cols="3">
 	  <thead>
 	    <row>
 	      <entry>host</entry>
 	      <entry>default gateway</entry>
 	      <entry>interface</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	      <entry>Local2</entry>
 	      <entry>Local1</entry>
 	      <entry>ethernet</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>Local1</entry>
 	      <entry>T1-GW</entry>
 	      <entry>PPP</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
       
       <para>A common question is <quote>Why (or how) would we set the T1-GW to
 	be the default gateway for Local1, rather than the ISP server it is
 	connected to?</quote>.</para>
 	  
       <para>Remember, since the PPP interface is using an address on the ISP's
 	local network for your side of the connection, routes for any other
 	machines on the ISP's local network will be automatically generated.
 	Hence, you will already know how to reach the T1-GW machine, so there
 	is no need for the intermediate step of sending traffic to the ISP
 	server.</para>
 	  
       <para>As a final note, it is common to use the address <hostid
 	  role="ipaddr">...1</hostid> as the gateway address for your local
 	network.  So (using the same example), if your local class-C address
 	space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was
 	using <hostid role="ipaddr">10.9.9</hostid> then the default routes
 	would be:</para>
 	  
       <literallayout>
 Local2 (10.20.30.2)             --&gt;  Local1 (10.20.30.1)
 Local1 (10.20.30.1, 10.9.9.30)  --&gt;  T1-GW (10.9.9.1)
       </literallayout>
     </sect2>
     
     <sect2>
       <title>Dual homed hosts</title>
       <indexterm><primary>dual homed hosts</primary></indexterm>	        
       <para>There is one other type of configuration that we should cover, and
 	that is a host that sits on two different networks. Technically, any
 	machine functioning as a gateway (in the example above, using a PPP
 	connection) counts as a dual-homed host.  But the term is really only
 	used to refer to a machine that sits on two local-area
 	networks.</para>
 	  
       <para>In one case, the machine as two ethernet cards, each having an
 	address on the separate subnets.  Alternately, the machine may only
 	have one ethernet card, and be using ifconfig aliasing.  The former is
 	used if two physically separate ethernet networks are in use, the
 	latter if there is one physical network segment, but two logically
 	separate subnets.</para>
 	  
       <para>Either way, routing tables are set up so that each subnet knows
 	that this machine is the defined gateway (inbound route) to the other
 	subnet.  This configuration, with the machine acting as a Bridge
 	between the two subnets, is often used when we need to implement
 	packet filtering or firewall security in either or both
 	directions.</para>
     </sect2>
     
     <sect2>
       <title>Routing propagation</title>
       <indexterm><primary>routing propogation</primary></indexterm>
       <para>We have already talked about how we define our routes to the
 	outside world, but not about how the outside world finds us.</para>
 	  
       <para>We already know that routing tables can be set up so that all
 	traffic for a particular address space (in our examples, a class-C
 	subnet) can be sent to a particular host on that network, which will
 	forward the packets inbound.</para>
 	  
       <para>When you get an address space assigned to your site, your service
 	provider will set up their routing tables so that all traffic for your
 	subnet will be sent down your PPP link to your site.  But how do sites
 	across the country know to send to your ISP?</para>
 	  
       <para>There is a system (much like the distributed DNS information) that
 	keeps track of all assigned address-spaces, and defines their point of
 	connection to the Internet Backbone.  The <quote>Backbone</quote> are
 	the main trunk lines that carry Internet traffic across the country,
 	and around the world.  Each backbone machine has a copy of a master
 	set of tables, which direct traffic for a particular network to a
 	specific backbone carrier, and from there down the chain of service
 	providers until it reaches your network.</para>
 	  
       <para>It is the task of your service provider to advertise to the
 	backbone sites that they are the point of connection (and thus the
 	path inward) for your site.  This is known as route
 	propagation.</para>
     </sect2>
     
     <sect2>
       <title>Troubleshooting</title>
       <indexterm><primary>traceroute</primary></indexterm>      
       <para>Sometimes, there is a problem with routing propagation, and some
 	sites are unable to connect to you.  Perhaps the most useful command
 	for trying to figure out where a routing is breaking down is the
 	  &man.traceroute.8; command.  It is equally useful if you cannot seem
 	to make a connection to a remote machine (i.e. &man.ping.8;
 	fails).</para>
 	  
       <para>The &man.traceroute.8; command is run with the name of the remote
 	host you are trying to connect to.  It will show the gateway hosts
 	along the path of the attempt, eventually either reaching the target
 	host, or terminating because of a lack of connection.</para>
 	  
       <para>For more information, see the manual page for
 	  &man.traceroute.8;.</para>
     </sect2>
   </sect1>
 
   <sect1 id="bridging">
     <title>Bridging</title>
 
     <para><emphasis>Written by Steve Peterson
 	<email>steve@zpfe.com</email></emphasis>.</para>
 
     <sect2>
       <title>Introduction</title>
       <indexterm><primary>IP subnet</primary></indexterm>
       <indexterm><primary>bridge</primary></indexterm>
       <para>It is sometimes useful to divide one physical network (i.e., an
 	Ethernet segment) into two separate network segments, without having
 	to create IP subnets and use a router to connect the segments
 	together.  A device that connects two networks together in this
 	fashion is called a bridge. and a FreeBSD system with two network
 	interface cards can act as a bridge.</para>
 
       <para>The bridge works by learning the MAC layer addresses (i.e.,
 	Ethernet addresses) of the devices on each of its network interfaces.
 	It forwards traffic between two networks only when its source and
 	destination are on different networks.</para>
 
       <para>In many respects, a bridge is like an Ethernet switch with very
 	few ports.</para>
     </sect2>
 
     <sect2>
       <title>Situations where bridging is appropriate</title>
 
       <para>There are two common situations in which a bridge is used
 	today.</para>
       
       <sect3>
 	<title>High traffic on a segment</title>
 
 	<para>Situation one is where your physical network segment is
 	  overloaded with traffic, but you don't want for whatever reason to
 	  subnet the network and interconnect the subnets with a
 	  router.</para>
 
 	<para>Let's consider an example of a newspaper where the Editorial and
 	  Production departments are on the same subnetwork.  The Editorial
 	  users all use server A for file service, and the Production users
 	  are on server B.  An Ethernet is used to connect all users together,
 	  and high loads on the network are slowing things down.</para>
 
 	<para>If the Editorial users could be segregated on one network
 	  segment and the Production users on another, the two network
 	  segments could be connected with a bridge.  Only the network traffic
 	  destined for interfaces on the "other" side of the bridge would be
 	  sent to the other network, reducing congestion on each network
 	  segment.</para>
       </sect3>
 
       <sect3>
 	<title>Filtering/traffic shaping firewall</title>
 	<indexterm><primary>firewall</primary></indexterm>
 	<indexterm><primary>IP Masquerading</primary></indexterm>
 
 	<para>The second common situation is where firewall functionality is
 	  needed without IP Masquerading (NAT).</para>
 
 	<para>An example is a small company that is connected via DSL or ISDN
 	  to their ISP.  They have a 13 address global IP allocation for their
 	  ISP and have 10 PCs on their network.  In this situation, using a
 	  router-based firewall is difficult because of subnetting
 	  issues.</para>
 
 	<indexterm><primary>router</primary></indexterm>
 	<indexterm><primary>DSL</primary></indexterm>
 	<indexterm><primary>ISDN</primary></indexterm>
 	<para>A bridge-based firewall can be configured and dropped into the
 	  path just downstream of their DSL/ISDN router without any IP
 	  numbering issues.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Configuring a bridge</title>
 
       <sect3>
 	<title>Network interface card selection</title>
 
 	<para>A bridge requires at least two network cards to function.
 	  Unfortunately, not all network interface cards as of FreeBSD 4.0
 	  support bridging.  Read &man.bridge.4; for details on the cards that
 	  are supported.</para>
 
 	<para>Install and test the two network cards before continuing.</para>
       </sect3>
 
       <sect3>
 	<title>Kernel configuration changes</title>
 	<indexterm><primary>kernel configuration</primary></indexterm>
 	<indexterm>
 	  <primary>kernel configuration</primary>
 	  <secondary>options BRIDGE</secondary>
 	</indexterm>
 
 	<para>To enable kernel support for bridging, add the</para>
 
 	<programlisting>options BRIDGE</programlisting>
 
 	<para>statement to your kernel configuration file, and rebuild your
 	  kernel.</para>
       </sect3>
 
       <sect3>
 	<title>Firewall support</title>
 	<indexterm><primary>firewall</primary></indexterm>
 	<para>If you are planning to use the bridge as a firewall, you will
 	  need to add the IPFIREWALL option as well.  Read <xref
 	    linkend="firewalls"> for general information on configuring the
 	  bridge as a firewall.</para>
 
 	<para>If you need to allow non-IP packets (such as ARP) to flow
 	  through the bridge, there is an undocumented firewall option that
 	  must be set. This option is
 	  <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal>.  Note that this
 	  changes the default rule for the firewall to accept any packet.
 	  Make sure you know how this changes the meaning of your ruleset
 	  before you set it.</para>
       </sect3>
 
       <sect3>
 	<title>Traffic shaping support</title>
 
 	<para>If you want to use the bridge as a traffic shaper, you will need
 	  to add the <literal>DUMMYNET</literal> option to your kernel
 	  configuration.  Read &man.dummynet.4; for further
 	  information.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Enabling the bridge</title>
 
       <para>Add the line</para>
 
       <programlisting>net.link.ether.bridge=1</programlisting>
 
       <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at
 	runtime.  If you want the bridged packets to be filtered by ipfw, you
 	should also add</para>
 
       <programlisting>net.link.ether.bridge_ipfw=1</programlisting>
 
       <para>as well.</para>
     </sect2>
 
     <sect2>
       <title>Performance</title>
 
       <para>My bridge/firewall is a Pentium 90 with one 3Com 3C900B and one
 	3C905B.  The protected side of the network runs at 10mbps half duplex
 	and the connection between the bridge and my router (a Cisco 675) runs
 	at 100mbps full duplex.  With no filtering enabled, I've found that
 	the bridge adds about 0.4 milliseconds of latency to pings from the
 	protected 10mbps network to the Cisco 675.</para>
     </sect2>
 
     <sect2>
       <title>Other information</title>
 
       <para>If you want to be able to telnet into the bridge from the network,
 	it is OK to assign one of the network cards an IP address.  The
 	consensus is that assigning both cards an address is a bad
 	idea.</para>
 
       <para>If you have multiple bridges on your network, there cannot be more
 	than one path between any two workstations.  Technically, this means
 	that there is no support for spanning tree link management.</para>
     </sect2>
   </sect1>
   
   <sect1 id="nfs">
     <title>NFS</title>
 
     <para><emphasis>Written by &a.unfurl;, 4 March 2000.</emphasis></para>
     <indexterm><primary>NFS</primary></indexterm>
     <para>Among the many different file systems that FreeBSD supports is
       a very unique type, the Network File System or NFS.  NFS allows you
       to share directories and files on one machine with one or more other
       machines via the network they are attached to.  Using NFS, users and
       programs can access files on remote systems as if they were local
       files.</para>
 
     <para>NFS has several benefits:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Local workstations don't need as much disk space because
 	  commonly used data can be stored on a single machine and still
 	  remain accessible to everyone on the network.</para>
       </listitem>
 
       <listitem>
 	<para>There is no need for users to have unique home directories
 	  on every machine on your network.  Once they have an established
 	  directory that is available via NFS it can be accessed from
 	  anywhere.</para>
       </listitem>
 
       <listitem>
 	<para>Storage devices such as floppies and CDROM drives can be
 	  used by other machines on the network eliminating the need for
 	  extra hardware.</para>
       </listitem>
     </itemizedlist>
 
     <sect2>
       <title>How It Works</title>
 
       <para>NFS is composed of two sides &ndash; a client side and a
 	server side.  Think of it as a want/have relationship.  The client
 	<emphasis>wants</emphasis> the data that the server side
 	<emphasis>has</emphasis>.  The server shares its data with the
 	client.  In order for this system to function properly a few
 	processes have to be configured and running properly.</para>
 
       <para>The server has to be running the following daemons:</para>
       <indexterm>
         <primary>NFS</primary>
         <secondary>server</secondary>
       </indexterm>
       <indexterm><primary>portmap</primary></indexterm>
       <indexterm><primary>mountd</primary></indexterm>
       <indexterm><primary>nfsd</primary></indexterm>
       <itemizedlist>
         <listitem>
 	  <para><command>nfsd</command> - The NFS Daemon which services
 	    requests from NFS clients.</para>
 	</listitem>
 
         <listitem>
 	  <para><command>mountd</command> - The NFS Mount Daemon which
 	    actually carries  out requests that nfsd passes on to
 	    it.</para>
 	</listitem>
 
 	<listitem>
 	  <para><command>portmap</command> - The portmapper daemon which
 	    allows NFS clients to find out which port the NFS server is
 	    using.</para>
 	</listitem>
       </itemizedlist>
 
       <para>The client side only needs to run a single daemon:</para>
       <indexterm>
         <primary>NFS</primary>
         <secondary>client</secondary>
       </indexterm>
       <indexterm><primary>nfsiod</primary></indexterm>
       <itemizedlist>
         <listitem>
 	  <para><command>nfsiod</command> - The NFS async I/O Daemon which
 	    services requests from its NFS server.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Configuring NFS</title>
       <indexterm>
         <primary>NFS</primary>
         <secondary>configuration</secondary>
       </indexterm>
 
       <para>Luckily for us, on a FreeBSD system this setup is a snap.  The
 	processes that need to be running can all be run at boot time with
 	a few modifications to your <filename>/etc/rc.conf</filename>
 	file.</para>
 
       <para>On the NFS server make sure you have:</para>
 
       <programlisting>portmap_enable="YES"
 nfs_server_enable="YES"
 nfs_server_flags="-u -t -n 4"
 mountd_flags="-r"</programlisting>
 
       <para><command>mountd</command> is automatically run whenever the
 	NFS server is enabled.  The <option>-u</option> and
 	<option>-t</option> flags to <command>nfsd</command> tell it to
 	serve UDP and TCP clients.  The <option>-n 4</option> flag tells
 	<command>nfsd</command> to start 4 copies of itself.</para>
 
       <para>On the client, make sure you have:</para>
 
       <programlisting>nfs_client_enable="YES"
 nfs_client_flags="-n 4"</programlisting>
 
       <para>Like <command>nfsd</command>, the <option>-n 4</option> tells
 	<command>nfsiod</command> to start 4 copies of itself.</para>
 
       <para>The last configuration step requires that you create a file
 	called <filename>/etc/exports</filename>.  The exports file
 	specifies which file systems on your server will be shared
 	(a.k.a., <quote>exported</quote>) and with what clients they will
 	be shared.  Each line in the file specifies a file system to be
 	shared.  There are a handful of options that can be used in this
 	file but only a few will be mentioned here.  You can find out
 	about the rest in the &man.exports.5; man page.</para>
 
       <para>Here are a few example <filename>/etc/exports</filename>
 	entries:</para>
 
       <indexterm>
         <primary>NFS</primary>
         <secondary>exporting filesystems</secondary>
       </indexterm>
       <para>The following line exports <filename>/cdrom</filename> to
 	three silly machines that have the same domain name as the server
 	(hence the lack of a domain name for each) or have entries in your
 	<filename>/etc/hosts</filename> file.  The <option>-ro</option>
 	flag makes the shared file system read-only.  With this flag, the
 	remote system will not be able to make any changes to the
 	shared file system.</para>
 
       <programlisting>/cdrom -ro moe larry curly</programlisting>
 
       <para>The following line exports <filename>/home</filename> to three
 	hosts by IP address.  This is a useful setup if you have a
 	private network but do not have DNS running.  The
 	<option>-alldirs</option> flag allows all the directories below
 	the specified file system to be exported as well.</para>
 
       <programlisting>/home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4</programlisting>
 
       <para>The following line exports <filename>/a</filename> to two
 	machines that have different domain names than the server.  The
 	<option>-maproot=0</option> flag allows
         the root user on the remote system to write to the shared
         file system as root.  Without the -maproot=0 flag even if
         someone has root access on the remote system they won't
         be able to modify files on the shared file system.</para>
 
       <programlisting>/a  -maproot=0  host.domain.com box.example.com</programlisting>
 
       <para>In order for a client to share an exported file system it must
 	have permission to do so.  Make sure your client is listed in your
 	<filename>/etc/exports</filename> file.</para>
 
       <para>It's important to remember that you must restart mountd
         whenever you modify <filename>/etc/exports</filename> so that
         your changes take effect.  This can be accomplished by sending
         the hangup signal to the mountd process :</para>
 
       <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
 
       <para>Now that you have made all these changes you can just reboot
 	and let FreeBSD start everything for you at boot time or you can
 	run the following commands as root:</para>
 
       <para>On the NFS server:</para>
 
       <screen>&prompt.root; <userinput>portmap</userinput>
 &prompt.root; <userinput>nfsd -u -t -n 4</userinput>
 &prompt.root; <userinput>mountd -r</userinput></screen>
 
       <para>On the NFS client:</para>
 
       <screen>&prompt.root; <userinput>nfsiod -n 4</userinput></screen>
 
       <para>Now you should be ready to actually mount a remote file
 	system.  This can be done one of two ways.  In these examples the
 	server's name will be <literal>server</literal> and the client's
 	name will be <literal>client</literal>.  If you just want to
 	temporarily mount a remote file system or just want to test out
 	your config you can run a command like this as root on the
 	client:</para>
       <indexterm>
         <primary>NFS</primary>
         <secondary>mounting filesystems</secondary>
       </indexterm>
       <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>
 
       <para>This will mount <filename>/home</filename> on the server on
 	<filename>/mnt</filename> on the client.  If everything is setup
 	correctly you should be able to go into /mnt on the client and see
 	all the files that are on the server.</para>
 
       <para>If you want to permanently (each time you reboot) mount a
 	remote file system you need to add it to your
 	<filename>/etc/fstab</filename> file.  Here is an example
 	line:</para>
 
       <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>
 
       <para>Read the &man.fstab.5; man page for more options.</para>
     </sect2>
 
     <sect2>
       <title>Practical Uses</title>
 
       <para>There are many very cool uses for NFS.  Some of the more common
         ones are listed below.</para>
       <indexterm>
         <primary>NFS</primary>
         <secondary>uses</secondary>
       </indexterm>
       <itemizedlist>
         <listitem>
 	  <para>Have several machines on a network and share a CDROM or
 	    floppy drive among them.  This is cheaper and often more
 	    convenient.</para>
 	</listitem>
 
 	<listitem>
 	  <para>With so many machines on a network, it gets old having your
 	    personal files strewn all over the place.  You can have a
 	    central NFS server that houses all user home directories and
 	    shares them with the rest of the machines on the LAN, so no
 	    matter where you log in you will have the same home
 	    directory.</para>
 	</listitem>
 
 	<listitem>
 	  <para>When you get to reinstalling FreeBSD on one of your
 	    machines, NFS is the way to go!  Just pop your distribution
 	    CDROM into your file server and away you go!</para>
 	</listitem>
 
 	<listitem>
 	  <para>Have a common <filename>/usr/ports/distfiles</filename>
 	    directory that all your machines share.  That way, when you go
 	    to install a port that you've already installed on a different
 	    machine, you do not have to download the source all over
 	    again!</para>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Problems integrating with other systems</title>
 
       <para><emphasis>Contributed by &a.jlind;.</emphasis></para>
 
       <para>Certain Ethernet adapters for ISA PC systems have limitations
 	which can lead to serious network problems, particularly with NFS.
 	This difficulty is not specific to FreeBSD, but FreeBSD systems
 	are affected by it.</para>
 
       <para>The problem nearly always occurs when (FreeBSD) PC systems are
 	networked with high-performance workstations, such as those made
 	by Silicon Graphics, Inc., and Sun Microsystems, Inc.  The NFS
 	mount will work fine, and some operations may succeed, but
 	suddenly the server will seem to become unresponsive to the
 	client, even though requests to and from other systems continue to
 	be processed.  This happens to the client system, whether the
 	client is the FreeBSD system or the workstation.  On many systems,
 	there is no way to shut down the client gracefully once this
 	problem has manifested itself.  The only solution is often to
 	reset the client, because the NFS situation cannot be
 	resolved.</para>
 
       <para>Though the <quote>correct</quote> solution is to get a higher
 	performance and capacity Ethernet adapter for the FreeBSD system,
 	there is a simple workaround that will allow satisfactory
 	operation.  If the FreeBSD system is the
 	<emphasis>server</emphasis>, include the option
 	<option>-w=1024</option> on the mount from the client.  If the
 	FreeBSD system is the <emphasis>client</emphasis>, then mount the
 	NFS file system with the option <option>-r=1024</option>.  These
 	options may be specified using the fourth field of the
 	<filename>fstab</filename> entry on the client for automatic
 	mounts, or by using the <option>-o</option> parameter of the mount
 	command for manual mounts.</para>
 
       <para>It should be noted that there is a different problem,
 	sometimes mistaken for this one, when the NFS servers and clients
 	are on different networks.  If that is the case, make
 	<emphasis>certain</emphasis> that your routers are routing the
 	necessary UDP information, or you will not get anywhere, no matter
 	what else you are doing.</para>
 
       <para>In the following examples, <hostid>fastws</hostid> is the host
 	(interface) name of a high-performance workstation, and
 	<hostid>freebox</hostid> is the host (interface) name of a FreeBSD
 	system with a lower-performance Ethernet adapter.  Also,
 	<filename>/sharedfs</filename> will be the exported NFS
 	filesystem (see <command>man exports</command>), and
 	<filename>/project</filename> will be the mount point on the
 	client for the exported file system.  In all cases, note that
 	additional options, such as <option>hard</option> or
 	<option>soft</option> and <option>bg</option> may be desirable in
 	your application.</para>
 
       <para>Examples for the FreeBSD system (<hostid>freebox</hostid>) as
 	the client: in <filename>/etc/fstab</filename> on freebox:</para>
 
       <programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting>
 
       <para>As a manual mount command on <hostid>freebox</hostid>:</para>
 	  
       <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen>
 	  
       <para>Examples for the FreeBSD system as the server: in
 	<filename>/etc/fstab</filename> on <hostid>fastws</hostid>:</para>
 
       <programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
 
       <para>As a manual mount command on <hostid>fastws</hostid>:</para>
 
       <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen>
 	  
       <para>Nearly any 16-bit Ethernet adapter will allow operation
 	without the above restrictions on the read or write size.</para>
 
       <para>For anyone who cares, here is what happens when the failure
 	occurs, which also explains why it is unrecoverable.  NFS
 	typically works with a <quote>block</quote> size of 8k (though it
 	may do fragments of smaller sizes).  Since the maximum Ethernet
 	packet is around 1500 bytes, the NFS <quote>block</quote> gets
 	split into multiple Ethernet packets, even though it is still a
 	single unit to the upper-level code, and must be received,
 	assembled, and <emphasis>acknowledged</emphasis> as a unit.  The
 	high-performance workstations can pump out the packets which
 	comprise the NFS unit one right after the other, just as close
 	together as the standard allows.  On the smaller, lower capacity
 	cards, the later packets overrun the earlier packets of the same
 	unit before they can be transferred to the host and the unit as a
 	whole cannot be reconstructed or acknowledged.  As a result, the
 	workstation will time out and try again, but it will try again
 	with the entire 8K unit, and the process will be repeated, ad
 	infinitum.</para>
 
       <para>By keeping the unit size below the Ethernet packet size
 	limitation, we ensure that any complete Ethernet packet received
 	can be acknowledged individually, avoiding the deadlock
 	situation.</para>
 
       <para>Overruns may still occur when a high-performance workstations
 	is slamming data out to a PC system, but with the better cards,
 	such overruns are not guaranteed on NFS <quote>units</quote>.  When
 	an overrun occurs, the units affected will be retransmitted, and
 	there will be a fair chance that they will be received, assembled,
 	and acknowledged.</para>
     </sect2>
   </sect1>
   
   <sect1 id="diskless">
     <title>Diskless Operation</title>
     
     <para><emphasis>Contributed by &a.martin;.</emphasis></para>
     <indexterm><primary>diskless workstation</primary></indexterm>
     <para><filename>netboot.com</filename>/<filename>netboot.rom</filename>
       allow you to boot your FreeBSD machine over the network and run FreeBSD
       without having a disk on your client.  Under 2.0 it is now possible to
       have local swap.  Swapping over NFS is also still supported.</para>
 
     <para>Supported Ethernet cards include: Western Digital/SMC 8003, 8013,
       8216 and compatibles; NE1000/NE2000 and compatibles (requires
       recompile)</para>
     
     <sect2>
       <title>Setup Instructions</title>
       
       <procedure>
 	<step>
 	  <para>Find a machine that will be your server.  This machine will
 	    require enough disk space to hold the FreeBSD 2.0 binaries and
 	    have bootp, tftp and NFS services available. Tested
 	    machines:</para>
 	      
 	  <itemizedlist>
 	    <indexterm><primary>HP-UX</primary></indexterm>
 	    <listitem>
 	      <para>HP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't
 		work)</para>
 	    </listitem>
 	    <indexterm><primary>Solaris</primary></indexterm>	    
 	    <listitem>
 	      <para>Sun/Solaris 2.3.  (you may need to get bootp)</para>
 	    </listitem>
 	  </itemizedlist>
 	</step>
 
 	<step>
 	  <para>Set up a bootp server to provide the client with IP, gateway,
 	    netmask.</para>
 	  
 	  <programlisting>diskless:\
         :ht=ether:\
         :ha=0000c01f848a:\
         :sm=255.255.255.0:\
         :hn:\
         :ds=192.1.2.3:\
         :ip=192.1.2.4:\
         :gw=192.1.2.5:\
         :vm=rfc1048:</programlisting>
 	</step>
 
 	<step>
 	  <indexterm><primary>TFTP</primary></indexterm>
 	  <indexterm><primary>bootp</primary></indexterm>
 	  <para>Set up a TFTP server (on same machine as bootp server) to
 	    provide booting information to client.  The name of this file is
 	    <filename>cfg.<replaceable>X.X.X.X</replaceable></filename> (or
 	    <filename>/tftpboot/cfg.<replaceable>X.X.X.X</replaceable></filename>,
 	    it will try both) where <replaceable>X.X.X.X</replaceable> is the
 	    IP address of the client.  The contents of this file can be any
 	    valid netboot commands.  Under 2.0, netboot has the following
 	    commands:</para>
 
 	  <informaltable frame="none">
 	    <tgroup cols="2">
 	      <tbody>
 		<row>
 		  <entry>help</entry>
 		  <entry>print help list</entry>
 		</row>
 		
 		<row>
 		  <entry>ip
 		    <option><replaceable>X.X.X.X</replaceable></option></entry>
 		  <entry>print/set client's IP address</entry>
 		</row>
 		
 		<row>
 		  <entry>server
 		    <option><replaceable>X.X.X.X</replaceable></option></entry>
 		  <entry>print/set bootp/tftp server address</entry>
 		</row>
 		
 		<row>
 		  <entry>netmask
 		    <option><replaceable>X.X.X.X</replaceable></option></entry>
 		  <entry>print/set netmask</entry>
 		</row>
 
 		<row>
 		  <entry>hostname <replaceable>name</replaceable></entry>
 		  <entry>print/set hostname</entry>
 		    </row>
 		
 		<row>
 		  <entry>kernel
 		    <option><replaceable>name</replaceable></option></entry>
 		  <entry>print/set kernel name</entry>
 		</row>
 		
 		<row>
 		  <entry>rootfs
 		    <option><replaceable>ip:/fs</replaceable></option></entry>
 		  <entry>print/set root filesystem</entry>
 		</row>
 		
 		<row>
 		  <entry>swapfs
 		    <option><replaceable>ip:/fs</replaceable></option></entry>
 		  <entry>print/set swap filesystem</entry>
 		</row>
 		
 		<row>
 		  <entry>swapsize
 		    <option><replaceable>size</replaceable></option></entry>
 		  <entry>set diskless swapsize in KBytes</entry>
 		</row>
 		
 		<row>
 		  <entry>diskboot</entry>
 		  <entry>boot from disk</entry>
 		</row>
 		
 		<row>
 		  <entry>autoboot</entry>
 		  <entry>continue boot process</entry>
 		</row>
 		
 		<row>
 		  <entry>trans
 		    <option>on</option>|<option>off</option></entry>
 		  <entry>turn transceiver on|off</entry>
 		</row>
 		
 		<row>
 		  <entry>flags
 		    <option>b</option><option>c</option><option>d</option><option>h</option><option>s</option><option>v</option></entry>
 		  <entry>set boot flags</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 	  
 	  <para>A typical completely diskless cfg file might contain:</para>
 
 	  <programlisting>rootfs 192.1.2.3:/rootfs/myclient
 swapfs 192.1.2.3:/swapfs
 swapsize 20000
 hostname myclient.mydomain</programlisting>
 
 	  <para>A cfg file for a machine with local swap might contain:</para>
 
 	  <programlisting>rootfs 192.1.2.3:/rootfs/myclient
 hostname myclient.mydomain</programlisting>
 	</step>
 
 	<step>
 	  <para>Ensure that your NFS server has exported the root (and swap if
 	    applicable) filesystems to your client, and that the client has
 	    root access to these filesystems A typical
 	    <filename>/etc/exports</filename> file on FreeBSD might look
 	    like:</para>
 	  
 	  <programlisting>/rootfs/myclient -maproot=0:0 myclient.mydomain
 /swapfs -maproot=0:0 myclient.mydomain</programlisting>
 
 	  <para>And on HP-UX:</para>
 
 	  <programlisting>/rootfs/myclient -root=myclient.mydomain
 /swapfs -root=myclient.mydomain</programlisting>
 	</step>
 	      
 	<step>
 	  <indexterm>
 	    <primary>NFS</primary>
 	    <secondary>swapping over</secondary>
 	  </indexterm>
 	  <para>If you are swapping over NFS (completely diskless
 	    configuration) create a swap file for your client using
 	    <command>dd</command>.  If your <command>swapfs</command> command
 	    has the arguments <filename>/swapfs</filename> and the size 20000
 	    as in the example above, the swapfile for myclient will be called
 	    <filename>/swapfs/swap.<replaceable>X.X.X.X</replaceable></filename>
 	    where <replaceable>X.X.X.X</replaceable> is the client's IP addr,
 	    e.g.:</para>
 		  
 	  <screen>&prompt.root; <userinput>dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000</userinput></screen>
 		  
 	  <para>Also, the client's swap space might contain sensitive
 	    information once swapping starts, so make sure to restrict read
 	    and write access to this file to prevent unauthorized
 	    access:</para>
 		  
 	  <screen>&prompt.root; <userinput>chmod 0600 /swapfs/swap.192.1.2.4</userinput></screen>
 	</step>
 
 	<step>
 	  <para>Unpack the root filesystem in the directory the client will
 	    use for its root filesystem (<filename>/rootfs/myclient</filename>
 	    in the example above).</para>
 	  
 	  <itemizedlist>
 	    <listitem>
 	      <para>On HP-UX systems: The server should be running HP-UX 9.04
 		or later for HP9000/800 series machines. Prior versions do not
 		allow the creation of device files over NFS.</para>
 	    </listitem>
 	    
 	    <listitem>
 	      <para>When extracting <filename>/dev</filename> in
 		<filename>/rootfs/myclient</filename>, beware that some
 		systems (HPUX) will not create device files that FreeBSD is
 		happy with.  You may have to go to single user mode on the
 		first bootup (press control-c during the bootup phase), cd
 		<filename>/dev</filename> and do a <command>sh ./MAKEDEV
 		  all</command> from the client to fix this.</para>
 	    </listitem>
 	  </itemizedlist>
 	</step>
 
 	<step>
 	  <para>Run <command>netboot.com</command> on the client or make an
 	    EPROM from the <filename>netboot.rom</filename> file</para>
 	</step>
       </procedure>
     </sect2>
     
     <sect2>
       <title>Using Shared <filename>/</filename> and <filename>/usr</filename>
 	filesystems</title>
 
       <para>Although this is not an officially sanctioned or supported way
         of doing this, some people report that it works quite well.  If
         anyone has any suggestions on how to do this cleanly, please tell
         &a.doc;.</para>
     </sect2>
     
     <sect2>
       <title>Compiling netboot for specific setups</title>
       
       <para>Netboot can be compiled to support NE1000/2000 cards by changing
 	the configuration in
 	<filename>/sys/i386/boot/netboot/Makefile</filename>.  See the
 	comments at the top of this file.</para>
     </sect2>
   </sect1>
   
   <sect1 id="isdn">
     <title>ISDN</title>
     
     <para>A good resource for information on ISDN technology and hardware is
       <ulink url="http://alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN
 	Page</ulink>.</para>
 
     <para>A quick simple road map to ISDN follows:</para>
     
     <itemizedlist>
       <listitem>
         <para>If you live in Europe you might want to investigate the ISDN card
           section.</para>
       </listitem>
       
       <listitem>
 	<para>If you are planning to use ISDN primarily to connect to the
 	  Internet with an Internet Provider on a dial-up non-dedicated basis,
 	  you might look into Terminal Adapters.  This will give you the
 	  most flexibility, with the fewest problems, if you change
 	  providers.</para>
       </listitem>
       
       <listitem>
 	<para>If you are connecting two LANs together, or connecting to the
 	  Internet with a dedicated ISDN connection, you might consider
 	  the stand alone router/bridge option.</para>
       </listitem>
     </itemizedlist>
     
     <para>Cost is a significant factor in determining what solution you will
       choose.  The following options are listed from least expensive to most
       expensive.</para>
     
     <sect2>
       <title>ISDN Cards</title>
       
       <para><emphasis>Contributed by &a.hm;.</emphasis></para>
 
       <indexterm>
         <primary>ISDN</primary>
         <secondary>cards</secondary>
       </indexterm>
       <para>This section is really only relevant to ISDN users in countries
 	where the DSS1/Q.931 ISDN standard is supported.</para>
   
       <para>Some growing number of PC ISDN cards are supported under FreeBSD
 	2.2.X and up by the isdn4bsd driver package.  It is still under
 	development but the reports show that it is successfully used all over
 	Europe.</para>
 
       <indexterm><primary>isdn4bsd</primary></indexterm>
       <para>The latest isdn4bsd version is available from  <ulink
 	  url="ftp://isdn4bsd@ftp.consol.de/pub/">ftp://isdn4bsd@ftp.consol.de/pub/</ulink>,
 	the main isdn4bsd ftp site (you have to log in as user
 	<username>isdn4bsd</username> , give your mail address as the password
 	and change to the <filename>pub</filename> directory.  Anonymous ftp
 	as user <username>ftp</username> or <username>anonymous</username>
 	will <emphasis>not</emphasis> give the desired result).</para>
 
       <para>Isdn4bsd allows you to connect to other ISDN routers using either
 	IP over raw HDLC or by using synchronous PPP.  A telephone answering
 	machine application is also available.</para>
 
       <para>Many ISDN PC cards are supported, mostly the ones with a Siemens
 	ISDN chipset (ISAC/HSCX), support for other chipsets (from Motorola,
 	Cologne Chip Designs) is currently under development.  For an
 	up-to-date list of supported cards, please have a look at the <ulink
 	  url="ftp://isdn4bsd@ftp.consol.de/pub/README">README</ulink>
 	file.</para>
 
       <para>In case you are interested in adding support for a different ISDN
 	protocol, a currently unsupported ISDN PC card or otherwise enhancing
 	isdn4bsd, please get in touch with <email>hm@kts.org</email>.</para>
 
       <para>A majordomo maintained mailing list is available.  To join the
 	list, send mail to &a.majordomo; and
 	specify:</para>
       
       <programlisting>subscribe freebsd-isdn</programlisting>
 
       <para>in the body of your message.</para>
     </sect2>
     
     <sect2>
       <title>ISDN Terminal Adapters</title>
 
       <para>Terminal adapters(TA), are to ISDN what modems are to regular
 	phone lines.</para>
       <indexterm><primary>modem</primary></indexterm>
       <para>Most TA's use the standard hayes modem AT command set, and can be
 	used as a drop in replacement for a modem.</para>
 	  
       <para>A TA will operate basically the same as a modem except connection
 	and throughput speeds will be much faster than your old modem.  You
 	will need to configure <link linkend="ppp">PPP</link> exactly the same
 	as for a modem setup.  Make sure you set your serial speed as high as
 	possible.</para>
       <indexterm><primary>PPP</primary></indexterm>	  
       <para>The main advantage of using a TA to connect to an Internet
 	Provider is that you can do Dynamic PPP.  As IP address space becomes
 	more and more scarce, most providers are not willing to provide you
 	with a static IP anymore.  Most stand-alone routers are not able to
 	accommodate dynamic IP allocation.</para>
       
       <para>TA's completely rely on the PPP daemon that you are running for
 	their features and stability of connection.  This allows you to
 	upgrade easily from using a modem to ISDN on a FreeBSD machine, if you
 	already have PPP setup.  However, at the same time any problems you
 	experienced with the PPP program and are going to persist.</para>
 	  
       <para>If you want maximum stability, use the kernel <link
 	  linkend="ppp">PPP</link> option, not the user-land <link
 	  linkend="userppp">iijPPP</link>.</para>
 	  
       <para>The following TA's are know to work with FreeBSD.</para>
 	  
       <itemizedlist>
 	<listitem>
 	  <para>Motorola BitSurfer and Bitsurfer Pro</para>
 	</listitem>
 
 	<listitem>
 	  <para>Adtran</para>
 	</listitem>
       </itemizedlist>
       
       <para>Most other TA's will probably work as well, TA vendors try to make
 	sure their product can accept most of the standard modem AT command
 	set.</para>
 	  
       <para>The real problem with external TA's is like modems you need a good
 	serial card in your computer.</para>
 	  
       <para>You should read the <ulink
 	url="http://www.freebsd.org/tutorials">FreeBSD Serial
 	Hardware</ulink> tutorial for a detailed understanding of
 	serial devices, and the differences between asynchronous and
 	synchronous serial ports.</para>
       
       <para>A TA running off a standard PC serial port (asynchronous) limits
 	you to 115.2Kbs, even though you have a 128Kbs connection. To fully
 	utilize the 128Kbs that ISDN is capable of, you must move the TA to a
 	synchronous serial card.</para>
 	  
       <para>Do not be fooled into buying an internal TA and thinking you have
 	avoided the synchronous/asynchronous issue.  Internal TA's simply have
 	a standard PC serial port chip built into them.  All this will do, is
 	save you having to buy another serial cable, and find another empty
 	electrical socket.</para>
 	  
       <para>A synchronous card with a TA is at least as fast as a stand-alone
 	router, and with a simple 386 FreeBSD box driving it, probably more
 	flexible.</para>
 	  
       <para>The choice of sync/TA v.s. stand-alone router is largely a
 	religious issue.  There has been some discussion of this in
 	the mailing lists.  I suggest you search the <ulink
 	url="http://www.FreeBSD.org/search.html">archives</ulink> for
 	the complete discussion.</para>
     </sect2>
     
     <sect2>
       <title>Stand-alone ISDN Bridges/Routers</title>
       <indexterm>
         <primary>ISDN</primary>
 	<secondary>stand-alone bridges/routers</secondary>
       </indexterm>	        
       <para>ISDN bridges or routers are not at all specific to FreeBSD
 	or any other operating system.  For a more complete
 	description of routing and bridging technology, please refer
 	to a Networking reference book.</para>
 	  
       <para>In the context of this page, the terms router and bridge will
 	be used interchangeably.</para>
 	  
       <para>As the cost of low end ISDN routers/bridges comes down, it
 	will likely become a more and more popular choice.  An ISDN
 	router is a small box that plugs directly into your local
 	Ethernet network(or card), and manages its own connection to
 	the other bridge/router.  It has all the software to do PPP
 	and other protocols built in.</para>
 	  
       <para>A router will allow you much faster throughput that a
 	standard TA, since it will be using a full synchronous ISDN
 	connection.</para>
 	  
       <para>The main problem with ISDN routers and bridges is that
 	interoperability between manufacturers can still be a problem.
 	If you are planning to connect to an Internet provider, you
 	should discuss your needs with them.</para>
 	  
       <para>If you are planning to connect two LAN segments together,
 	ie: home LAN to the office LAN, this is the simplest lowest
 	maintenance solution.  Since you are buying the equipment for
 	both sides of the connection you can be assured that the link
 	will work.</para>
 	  
       <para>For example to connect a home computer or branch office
 	network to a head office network the following setup could be
 	used.</para>
 	  
       <example>
 	<title>Branch office or Home network</title>
 
 	<indexterm><primary>10 base 2</primary></indexterm>	        
 	<para>Network uses a bus based topology with 10 base 2
 	  Ethernet ("thinnet").  Connect router to network cable with
 	  AUI/10BT transceiver, if necessary.</para>
 
         <mediaobject>
           <imageobject>
             <imagedata fileref="advanced-networking/isdn-bus">
           </imageobject>
 
 	  <textobject>
 	    <literallayout class="monospaced">---Sun workstation     
 |
 ---FreeBSD box
 |
 ---Windows 95 (Do not admit to owning it)
 |
 Stand-alone router
    |
 ISDN BRI line</literallayout>
           </textobject>
 
 	  <textobject>
 	    <phrase>10 Base 2 Ethernet</phrase>
 	  </textobject>
 	</mediaobject>
 
 	<para>If your home/branch office is only one computer you can use a
 	  twisted pair crossover cable to connect to the stand-alone router
 	  directly.</para>
       </example>
       
       <example>
 	<title>Head office or other LAN</title>
 
 	<indexterm><primary>10 base T</primary></indexterm>
 	<para>Network uses a star topology with 10 base T Ethernet
   	  ("Twisted Pair").</para>
 
         <mediaobject>
           <imageobject>
             <imagedata fileref="advanced-networking/isdn-twisted-pair">
           </imageobject>
 
 	  <textobject>
 	    <literallayout class="monospaced">    -------Novell Server
     | H |
     |   ---Sun      
     |   |
     | U ---FreeBSD
     |   |
     |   ---Windows 95
     | B |
     |___---Stand-alone router
                 |
         ISDN BRI line</literallayout>
 	  </textobject>
 
 	  <textobject>
 	    <phrase>ISDN Network Diagram</phrase>
 	  </textobject>
 	</mediaobject>
       </example>
       
       <para>One large advantage of most routers/bridges is that they allow you
 	to have 2 <emphasis>separate independent</emphasis> PPP connections to
 	2 separate sites at the <emphasis>same</emphasis> time.  This is not
 	supported on most TA's, except for specific(expensive) models that
 	have two serial ports. Do not confuse this with channel bonding, MPP
 	etc.</para>
 	  
       <para>This can be very useful feature, for example if you have an
 	dedicated ISDN connection at your office and would like to
 	tap into it, but don't want to get another ISDN line at work. A router
 	at the office location can manage a dedicated B channel connection
 	(64Kbs) to the Internet, as well as a use the other B channel for a
 	separate data connection.  The second B channel can be used for
 	dial-in, dial-out or dynamically bond(MPP etc.) with the first B channel
 	for more bandwidth.</para>
 
       <indexterm><primary>IPX/SPX</primary></indexterm>	  
       <para>An Ethernet bridge will also allow you to transmit more than just
 	IP traffic, you can also send IPX/SPX or whatever other protocols you
 	use.</para>
     </sect2>
   </sect1>
 
   <sect1 id="nis">
     <title>NIS/YP</title>
 
     <para><emphasis>Written by &a.unfurl;, 21 January 2000, enhanced
       with parts and comments from Eric Ogren
       <email>eogren@earthlink.net</email> and Udo Erdelhoff
       <email>ue@nathan.ruhr.de</email> in June 2000.</emphasis></para>
 
     <sect2>
       <title>What is it?</title>
       <indexterm><primary>NIS</primary></indexterm>	    
       <indexterm><primary>Solaris</primary></indexterm>	    
       <indexterm><primary>HP-UX</primary></indexterm>	    
       <indexterm><primary>AIX</primary></indexterm>	    
       <indexterm><primary>Linux</primary></indexterm>	    
       <indexterm><primary>NetBSD</primary></indexterm>	    
       <indexterm><primary>OpenBSD</primary></indexterm>	    
       <para>NIS, which stands for Network Information Services, was
         developed by Sun Microsystems to centralize administration of Unix
         (originally SunOS) systems.  It has now essentially become an
         industry standard; all major Unices (Solaris, HP-UX, AIX, Linux,
         NetBSD, OpenBSD, FreeBSD, etc) support NIS.</para>
 
       <indexterm><primary>yellow pages (see NIS)</primary></indexterm>
       <para>NIS was formerly known as Yellow Pages (or yp), but due to
         copyright violations, Sun was forced to change the name.</para>
 
       <indexterm>
         <primary>NIS</primary>
         <secondary>domains</secondary>
       </indexterm>
       <para>It is a RPC-based client/server system that allows a group
 	of machines within an NIS domain to share a common set of
 	configuration files.  This permits a system administrator to set
 	up NIS client systems with only minimal configuration data and
 	add, remove or modify configuration data from a single
 	location.</para>
 
       <indexterm><primary>Windows NT</primary></indexterm>
       <para>It is similar to Windows NT's domain system; although the
         internal implementation of the two aren't at all similar,
         the basic functionality can be compared.</para>
     </sect2>
   
     <sect2>
       <title>Terms/processes you should know</title>
 
       <para>There are several terms and several important user processes
         that you will come across when
         attempting to implement NIS on FreeBSD, whether you are trying to
         create an NIS server or act an NIS client:</para>
 
       <itemizedlist>
         <listitem>
           <para><emphasis>The NIS domainname</emphasis>. An NIS master
             server and all of its clients (including its slave servers) have
             a NIS domainname. Similar to an NT domain name, the NIS
             domainname does not have anything to do with DNS.</para>
         </listitem>
 	<indexterm><primary>portmap</primary></indexterm>
         <listitem>
           <para><emphasis>portmap</emphasis>. <command>portmap</command>
             must be running in order to enable RPC (Remote Procedure Call, a
             network protocol used by NIS). If <command>portmap</command> is
             not running, it will be impossible to run an NIS server, or to
             act as an NIS client.</para>
         </listitem>
         <listitem>
           <para><emphasis>ypbind</emphasis>. <command>ypbind</command>
             &ldquo;binds&rdquo; an NIS client to its NIS server.
             It will take the NIS domainname from the system, and
             using RPC, connect to the server. <command>ypbind</command> is
             the core of client-server communication in an NIS environment; if
             <command>ypbind</command> dies on a client machine, it will not
             be able to access the NIS server.</para>
         </listitem>
         <listitem>
           <para><emphasis>ypserv</emphasis>. <command>ypserv</command>,
             which should only be running on NIS servers, is the NIS server
             process itself. If ypserv dies, then the server will no longer be
             able to respond to NIS requests (hopefully, there is a slave
             server to take over for it).</para>
 
           <note><para>There are some implementations of NIS (but not the
             FreeBSD one), that don't try to reconnect to another server
             if the server it used before dies.  Often, the only thing
             that helps in this case is to restart the server process (or
             even the whole server) or the <command>ypbind</command> process
             on the client.</para></note>
         </listitem>
         <listitem>
           <para><emphasis>rpc.yppasswdd</emphasis>.
             <command>rpc.yppasswdd</command>, another process that should
             only be running on NIS master servers, is a daemon that will
             allow NIS clients to change their NIS passwords.
             If this daemon is not running, users will have to login to the
             NIS master server and change their passwords there.</para>
         </listitem>
 
         <!-- XXX Missing: rpc.ypxfrd (not important, though) May only run
              on the master -->
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>How does it work?</title>
         
       <para>There are three types of hosts in an NIS environment; master
 	servers, slave servers, and clients.  Servers act as a central
 	repository for host configuration information.  Master servers
 	hold the authoritative copy of this information, while slave
 	servers mirror this information for redundancy.  Clients rely on
 	the servers to provide this information to them.</para>
 
       <para>Information in many files can be shared in this manner.  The
 	<filename>master.passwd</filename>, <filename>group</filename>,
 	and <filename>hosts</filename> files are commonly shared via NIS.
 	Whenever a process on a client needs information that would
 	normally be found in these files locally, it makes a query to the
 	server it is bound to, to get this information.</para>
 
       <sect3>
         <title>Machine types</title>
 
         <itemizedlist>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>master server</secondary>
 	  </indexterm>
           <listitem>
             <para>A <emphasis>NIS master server</emphasis>.
               This server, analogous to a Windows
               NT primary domain controller, maintains the files used by all
               of the NIS clients.  The <filename>passwd</filename>,
               <filename>group</filename>, and other various files used by the
               NIS clients live on the master server.</para>
        
             <note><para>It is possible for one machine to be an NIS
               master server for more than one NIS domain.  However, this will
               not be covered in this introduction, which assumes a relatively
               small-scale NIS environment.</para></note>
           </listitem>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>slave server</secondary>
 	  </indexterm>
           <listitem>
             <para><emphasis>NIS slave servers</emphasis>.
               Similar to NT's backup domain
               controllers, NIS slave servers maintain copies of the NIS
               master's data files.  NIS slave servers provide the redundancy,
               which is needed in important environments. They also help
               to balance the load of the master server:  NIS Clients always
               attach to the NIS server whose response they get first, and
               this includes slave-server-replies.</para>
           </listitem>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>client</secondary>
 	  </indexterm>
           <listitem>
             <para><emphasis>NIS clients</emphasis>. NIS clients, like most
               NT workstations, authenticate against the NIS server (or the NT
               domain controller in the NT Workstation case) to log on.</para>
           </listitem>
         </itemizedlist>
       </sect3>
     </sect2>
     
     <sect2>
       <title>Using NIS/YP</title>
 
       <para>This section will deal with setting up a sample NIS
         environment.</para>
 
       <note><para>This section assumes that you are running FreeBSD 3.3
         or later.  The instructions given here will
         <emphasis>probably</emphasis> work for any version of FreeBSD greater
         than 3.0, but there are no guarantees that this is
         true.</para></note>
 
   
       <sect3>
         <title>Planning</title>
   
         <para>Let's assume that you are the administrator of a small
           university lab.  This lab, which consists of 15 FreeBSD machines,
           currently has no centralized point of administration;  each machine
           has its own <filename>/etc/passwd</filename> and
           <filename>/etc/master.passwd</filename>.  These files are kept in
           sync with each other only through manual intervention;
           currently, when you add a user to the lab, you must run
           <command>adduser</command> on all 15 machines.
           Clearly, this has to change, so you have decided to convert the
           lab to use NIS, using two of the machines as servers.</para>
 
         <para>Therefore, the configuration of the lab now looks something
           like:</para>
 
         <informaltable>
           <tgroup cols="3">
             <thead>
               <row>
                 <entry>Machine name</entry>
                 <entry>IP address</entry>
                 <entry>Machine role</entry>
               </row>
             </thead>
             <tbody>
               <row>
                 <entry><hostid>ellington</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.2</hostid></entry>
                 <entry>NIS master</entry>
               </row>
               <row>
                 <entry><hostid>coltrane</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.3</hostid></entry>
                 <entry>NIS slave</entry>
               </row>
               <row>
                 <entry><hostid>basie</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.4</hostid></entry>
                 <entry>Faculty workstation</entry>
               </row>
               <row>
                 <entry><hostid>bird</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.5</hostid></entry>
                 <entry>Client machine</entry>
               </row>
               <row>
                 <entry><hostid>cli[1-11]</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.[6-17]</hostid></entry>
                 <entry>Other client machines</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
         <para>If you are setting up a NIS scheme for the first time, it
 	  is a good idea to think through how you want to go about it.  No
 	  matter what the size of your network, there are a few decisions
 	  that need to be made.</para>
   
         <sect4>
           <title>Choosing a NIS Domain Name</title>
 
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>domainname</secondary>
 	  </indexterm>  
           <para>This might not be the <quote>domainname</quote> that you
 	    are used to.  It is more accurately called the
 	    <quote>NIS domainname</quote>.  When a client broadcasts its
 	    requests for info, it includes the name of the NIS domain
 	    that it is part of.  This is how multiple servers on one
 	    network can tell which server should answer which request.
 	    Think of the NIS domainname as the name for a group of hosts
 	    that are related in some way.</para>
   
 	  <para>Some organizations choose to use their Internet domainname
 	    for their NIS domainname. This is not recommended as it can
 	    cause confusion when trying to debug network problems.  The
 	    NIS domainname should be unique within your network and it is
 	    helpful if it describes the group of machines it represents.
 	    For example, the Art department at Acme Inc. might be in the
 	    "acme-art" NIS domain.  For this example, assume you have
             chosen the name <emphasis>test-domain</emphasis>.</para>
 
 	  <indexterm><primary>SunOS</primary></indexterm>
           <para>However, some operating systems (notably SunOS) use their
             NIS domain name as their Internet domain name.
             If one or more machines on your network have this restriction,
             you <emphasis>must</emphasis> use the Internet domain name as
             your NIS domain name.</para>
         </sect4>
   
         <sect4>
           <title>Physical Server Requirements</title>
             
 	  <para>There are several things to keep in mind when choosing a
 	    machine to use as a NIS server.  One of the unfortunate things
 	    about NIS is the level of dependency the clients have on the
 	    server.  If a client cannot contact the server for its NIS
 	    domain, very often the machine becomes unusable.  The lack of
 	    user and group information causes most systems to temporarily
 	    freeze up.  With this in mind you should make sure to choose a
 	    machine that won't be prone to being rebooted regularly, or
 	    one that might be used for development.  The NIS server should
 	    ideally be a stand alone machine whose sole purpose in life is
 	    to be an NIS server.  If you have a network that is not very
 	    heavily used, it is acceptable to put the NIS server on a
 	    machine running other services, just keep in mind that if the
 	    NIS server becomes unavailable, it will affect
 	    <emphasis>all</emphasis> of your NIS clients adversely.</para>
         </sect4>
       </sect3>
 
       <sect3>
         <title>NIS Servers</title>
 
 	<para> The canonical copies of all NIS information are stored on
 	  a single machine called the NIS master server.  The databases
 	  used to store the information are called NIS maps.  In FreeBSD,
 	  these maps are stored in
 	  <filename>/var/yp/[domainname]</filename> where
 	  <filename>[domainname]</filename> is the name of the NIS domain
 	  being served.  A single NIS server can support several domains
 	  at once, therefore it is possible to have several such
 	  directories, one for each supported domain.  Each domain will
 	  have its own independent set of maps.</para>
 
 	<para>NIS master and slave servers handle all NIS requests with
 	  the <command>ypserv</command> daemon.  <command>Ypserv</command>
 	  is responsible for receiving incoming requests from NIS clients,
 	  translating the requested domain and map name to a path to the
 	  corresponding database file and transmitting data from the
 	  database back to the client.</para>
 
         <sect4>
 	  <title>Setting up a NIS master server</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>server configuration</secondary>
 	  </indexterm>
 	  <para>Setting up a master NIS server can be relatively straight
 	    forward, depending on your needs.  FreeBSD comes with support
             for NIS out-of-the-box.  All you need is to add the following
             lines to <filename>/etc/rc.conf</filename>, and FreeBSD will
             do the rest for you.</para>
 
           <itemizedlist>
             <listitem>
               <para><programlisting>nisdomainname="test-domain"</programlisting>
                 This line will set the NIS domainname to
                 <emphasis>test-domain</emphasis>
                 upon network setup (e.g. after reboot).</para>
             </listitem>
             <listitem>
               <para><programlisting>nis_server_enable="YES"</programlisting>
                 This will tell FreeBSD to start up the NIS server processes
                 when the networking is next brought up.</para>
             </listitem>
             <listitem>
               <para><programlisting>nis_yppasswdd_enable="YES"</programlisting>
                 This will enable the <command>rpc.yppasswdd</command>
                 daemon, which, as mentioned above, will allow users to
                 change their NIS password from a client machine.</para>
             </listitem>
           </itemizedlist>
 
           <para>Now, all you have to do is to run the command
             <command>/etc/netstart</command> as superuser.  It will
             setup everything for you, using the values you defined in
             <filename>/etc/rc.conf</filename>.</para>
         </sect4>
 
         <sect4>
           <title>Initializing the NIS maps</title>
 	  <indexterm><primary>NIS maps</primary></indexterm>
           <para>The <emphasis>NIS maps</emphasis> are database files,
             that are kept in the <filename>/var/yp</filename> directory.
             They are generated from configuration files in the
             <filename>/etc</filename> directory of the NIS master, with one
             exception: the <filename>/etc/master.passwd</filename> file.
             This is for a good reason; you don't want to propagate
             passwords to your root and other administrative accounts to
             all the servers in the NIS domain.  Therefore, before we
             initialize the NIS maps, you should:</para>
 
           <screen>&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput>
 &prompt.root; <userinput>cd /var/yp</userinput>
 &prompt.root; <userinput>vi master.passwd</userinput></screen>
 
           <para>You should remove all entries regarding system accounts
             (bin, tty, kmem, games, etc), as well as any accounts that you
             don't want to be propagated to the NIS clients (for example
             root and any other UID 0 (superuser) accounts).</para>
 
           <note><para>Make sure the
             <filename>/var/yp/master.passwd</filename> is neither group
             nor world readable (mode 600)!  Use the
             <command>chmod</command> command, if appropriate.</para></note>
 
 	  <indexterm><primary>Tru64 Unix</primary></indexterm>
           <para>When you have finished, it's time to initialize the NIS
             maps!  FreeBSD includes a script named
             <command>ypinit</command> to do this for you
             (see its man page for more information).  Note that this
             script is available on most Unix OSs, but not on all.
             On Digital Unix/Compaq Tru64 Unix it is called
             <command>ypsetup</command>.
             Because we are generating maps for an NIS master, we are
             going to pass the <option>-m</option> option to
             <command>ypinit</command>.
             To generate the NIS maps, assuming you already performed
             the steps above, run:</para>
 
           <screen>ellington&prompt.root; <userinput>ypinit -m test-domain</userinput>
 Server Type: MASTER Domain: test-domain
 Creating an YP server will require that you answer a few questions.
 Questions will all be asked at the beginning of the procedure.
 Do you want this procedure to quit on non-fatal errors? [y/n: n] <userinput>n</userinput>
 Ok, please remember to go back and redo manually whatever fails.
 If you don't, something might not work.
 At this point, we have to construct a list of this domains YP servers.
 rod.darktech.org is already known as master server.
 Please continue to add any slave servers, one per line. When you are
 done with the list, type a &lt;control D&gt;.
 master server   :  ellington
 next host to add:  <userinput>coltrane</userinput>
 next host to add:  <userinput>^D</userinput>
 The current list of NIS servers looks like this:
 ellington
 coltrane
 Is this correct?  [y/n: y] <userinput>y</userinput>
 
 [..output from map generation..]
 
 NIS Map update completed.
 ellington has been setup as an YP master server without any errors.</screen>
 
           <para><command>ypinit</command> should have created
             <filename>/var/yp/Makefile</filename> from
             <filename>/var/yp/Makefile.dist</filename>.
             When created, this file assumes that you are operating
             in a single server NIS environment with only FreeBSD
             machines.  Since <emphasis>test-domain</emphasis> has
             a slave server as well, you must edit
             <filename>/var/yp/Makefile</filename>:</para>
 
           <screen>ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput></screen>
 
           <para>You should comment out the line that says `NOPUSH =
             "True"' (if it is not commented out already).</para>
         </sect4>
 
         <sect4>
 	  <title>Setting up a NIS slave server</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>configuring a slave server</secondary>
 	  </indexterm>
 	  <para>Setting up an NIS slave server is even more simple than
 	    setting up the master.  Log on to the slave server and edit the
             file <filename>/etc/rc.conf</filename> as you did before.
             The only difference is that we now must use the
             <option>-s</option> option when running <command>ypinit</command>.
             The <option>-s</option> option requires the name of the NIS
             master be passed to it as well, so our command line looks
             like:</para>
 
   <screen>coltrane&prompt.root; <userinput>ypinit -s ellington test-domain</userinput>
 
 Server Type: SLAVE Domain: test-domain Master: ellington
 
 Creating an YP server will require that you answer a few questions.
 Questions will all be asked at the beginning of the procedure.
 
 Do you want this procedure to quit on non-fatal errors? [y/n: n]  <userinput>n</userinput>
 
 Ok, please remember to go back and redo manually whatever fails.
 If you don't, something might not work. 
 There will be no further questions. The remainder of the procedure
 should take a few minutes, to copy the databases from ellington.
 Transferring netgroup...
 ypxfr: Exiting: Map successfully transferred
 Transferring netgroup.byuser...
 ypxfr: Exiting: Map successfully transferred
 Transferring netgroup.byhost...
 ypxfr: Exiting: Map successfully transferred
 Transferring master.passwd.byuid...
 ypxfr: Exiting: Map successfully transferred
 Transferring passwd.byuid...
 ypxfr: Exiting: Map successfully transferred
 Transferring passwd.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring group.bygid...
 ypxfr: Exiting: Map successfully transferred
 Transferring group.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring services.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring rpc.bynumber...
 ypxfr: Exiting: Map successfully transferred
 Transferring rpc.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring protocols.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring master.passwd.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring networks.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring networks.byaddr...
 ypxfr: Exiting: Map successfully transferred
 Transferring netid.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring hosts.byaddr...
 ypxfr: Exiting: Map successfully transferred
 Transferring protocols.bynumber...
 ypxfr: Exiting: Map successfully transferred
 Transferring ypservers...
 ypxfr: Exiting: Map successfully transferred
 Transferring hosts.byname...
 ypxfr: Exiting: Map successfully transferred
 
 coltrane has been setup as an YP slave server without any errors. 
 Don't forget to update map ypservers on ellington.</screen>
         
 	  <para>You should now have a directory called 
 	    <filename>/var/yp/test-domain</filename>.  Copies of the NIS
 	    master server's maps should be in this directory.  You will
 	    need to make sure that these stay updated.  The following
 	    <filename>/etc/crontab</filename> entries on your slave 
 	    servers should do the job:</para>
 
 	  <programlisting>20      *       *       *       *       root   /usr/libexec/ypxfr passwd.byname
 21      *       *       *       *       root   /usr/libexec/ypxfr passwd.byuid</programlisting>
 
 	  <para>These two lines force the slave to sync its maps with
 	    the maps on the master server.  Although this is
 	    not mandatory, because the master server
 	    tries to make sure any changes to its NIS maps are
 	    communicated to its slaves, the password
 	    information is so vital to systems that depend on the server,
 	    that it is a good idea to force the updates.  This is more
 	    important on busy networks where map updates might not always
 	    complete.</para>
 
           <para>Now, run the command <command>/etc/netstart</command> on the
             slave server as well, which again starts the NIS server.</para>
 	</sect4>
       </sect3>
 
       <sect3>
         <title>NIS Clients</title>
 	
 	<para> An NIS client establishes what is called a binding to a
 	  particular NIS server using the
 	  <command>ypbind</command> daemon.
 	  <command>ypbind</command> checks the system's default
 	  domain (as set by the <command>domainname</command> command),
 	  and begins broadcasting RPC requests on the local network.
 	  These requests specify the name of the domain for which
 	  <command>ypbind</command> is attempting to establish a binding.
 	  If a server that has been configured to serve the requested
 	  domain receives one of the broadcasts, it will respond to
 	  <command>ypbind</command>,  which will record the server's
 	  address.  If there are several servers available (a master and
 	  several slaves, for example), <command>ypbind</command> will
 	  use the address of the first one to respond.  From that point
 	  on, the client system will direct all of its NIS requests to
 	  that server.  <command>Ypbind</command> will
 	  occasionally <quote>ping</quote> the server to make sure it is
 	  still up and running.  If it fails to receive a reply to one of
 	  its pings within a reasonable amount of time,
 	  <command>ypbind</command> will mark the domain as unbound and
 	  begin broadcasting again in the hopes of locating another
 	  server.</para>
 
 	<sect4>
 	  <title>Setting up an NIS client</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>client configuration</secondary>
 	  </indexterm>
 	  <para>Setting up a FreeBSD machine to be a NIS client is fairly
 	    straightforward.</para>
 	
 	  <itemizedlist>
 	    <listitem>
 	      <para>Edit the file <filename>/etc/rc.conf</filename> and
                 add the following lines in order to set the NIS domainname
                 and start <command>ypbind</command> upon network
                 startup:</para>
 
 	      <programlisting>nisdomainname="test-domain"
 nis_client_enable="YES"</programlisting>
 	    </listitem>
 
 	    <listitem>
 	      <para>To import all possible password entries from the NIS
 		server, add this line to your
 		<filename>/etc/master.passwd</filename> file, using
 		<command>vipw</command>:</para>
 
 	      <programlisting>+:::::::::</programlisting>
 
 	      <note>
 		<para>This line will afford anyone with a valid account in
 		  the NIS server's password maps an account.  There are
 		  many ways to configure your NIS client by changing this
 		  line.  See the <link linkend="netgroups">netgroups
 		  part</link> below for more information.
                   For more detailed reading see O'Reilly's book on
 		  <literal>Managing NFS and NIS</literal>.</para>
 	      </note>
 	    </listitem>
 
 	    <listitem>
 	      <para>To import all possible group entries from the NIS
 		server, add this line to your
 		<filename>/etc/group</filename> file:</para>
 
 	      <programlisting>+:*::</programlisting>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>After completing these steps, you should be able to run
 	    <command>ypcat passwd</command> and see the NIS server's
 	    passwd map.</para>
 	</sect4>
       </sect3>
     </sect2>
 
     <sect2>
       <title>NIS Security</title>
 
       <para>In general, any remote user can issue an RPC to ypserv and
 	retrieve the contents of your NIS maps, provided the remote user
 	knows your domainname.  To prevent such unauthorized transactions,
 	ypserv supports a feature called securenets which can be used to
 	restrict access to a given set of hosts.  At startup, ypserv will
 	attempt to load the securenets information from a file called
 	<filename>/var/yp/securenets</filename>.</para>
 	
       <note>
 	<para>This path varies depending on the path specified with the
 	  <option>-p</option> option.  This file contains entries that
 	  consist of a network specification and a network mask separated
 	  by white space.  Lines starting with <quote>#</quote> are
 	  considered to be comments.  A sample securenets file might look
 	  like this:</para>
       </note>
 
       <programlisting># allow connections from local host -- mandatory
 127.0.0.1     255.255.255.255
 # allow connections from any host
 # on the 192.168.128.0 network
 192.168.128.0 255.255.255.0
 # allow connections from any host
 # between 10.0.0.0 to 10.0.15.255
 # this includes the machines in the testlab
 10.0.0.0      255.255.240.0</programlisting>
 
       <para>If ypserv receives a request from an address that matches one
 	of these rules, it will process the request normally.  If the
 	address fails to match a rule, the request will be ignored and a
 	warning message will be logged.  If the
 	<filename>/var/yp/securenets</filename> file does not exist,
 	ypserv will allow connections from any host.</para>
 
       <para>The ypserv program also has support for Wietse Venema's
 	<application>tcpwrapper</application> package.  This allows the
 	administrator to use the tcpwrapper configuration files for access
 	control instead of <filename>/var/yp/securenets</filename>.</para>
 
       <note>
         <para>While both of these access control mechanisms provide some
           security, they, like the privileged port test, are
           vulnerable to <quote>IP spoofing</quote> attacks.  All
           NIS-related traffic should be blocked at your firewall.</para>
 
         <para>Servers using <filename>/var/yp/securenets</filename>
           may fail to serve legitimate NIS clients with archaic TCP/IP
           implementations.  Some of these implementations set all
           host bits to zero when doing broadcasts and/or fail to
           observe the subnet mask when calculating the broadcast
           address.  While some of these problems can be fixed by
           changing the client configuration, other problems may force
           the retirement of the client systems in question or the
           abandonment of <filename>/var/yp/securenets</filename>.</para>
 
         <para>Using <filename>/var/yp/securenets</filename> on a
           server with such an archaic implementation of TCP/IP is a
           really bad idea and will lead to loss of NIS functionality
           for large parts of your network.</para>
 
 	<indexterm><primary>tcpwrapper</primary></indexterm>
         <para>The use of the <application>tcpwrapper</application>
           package increases the latency of your NIS server.  The
           additional delay may be long enough to cause timeouts in
           client programs, especially in busy networks or with slow
           NIS servers.  If one or more of your client systems
           suffers from these symptoms, you should convert the client
           systems in question into NIS slave servers and force them
           to bind to themselves.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Barring some users from logging on</title>
 
       <para>In our lab, there is a machine <hostid>basie</hostid> that is
         supposed to be a faculty only workstation. We don't want to take this
          machine out of the NIS domain, yet the <filename>passwd</filename>
        file on the master NIS server contains accounts for both faculty and
         students. What can we do?</para>
 
       <para>There is a way to bar specific users from logging on to a
         machine, even if they are present in the NIS database. To do this,
         all you must do is add
         <emphasis>-<replaceable>username</replaceable></emphasis> to the end of
         the <filename>/etc/master.passwd</filename> file on the client
         machine, where <replaceable>username</replaceable> is the username of
         the user you wish to bar from logging in. This should preferably be
         done using <command>vipw</command>, since <command>vipw</command>
         will sanity check your changes to
         <filename>/etc/master.passwd</filename>, as well as
         automatically rebuild the password database when you
         finish editing. For example, if we wanted to bar user
         <emphasis>bill</emphasis> from logging on to <hostid>basie</hostid>
         we would:</para>
 
         <screen>basie&prompt.root; <userinput>vipw</userinput>
 <userinput>[add -bill to the end, exit]</userinput>
 vipw: rebuilding the database...
 vipw: done
 
 basie&prompt.root; <userinput>cat /etc/master.passwd</userinput>
 
 root:[password]:0:0::0:0:The super-user:/root:/bin/csh
 toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
 daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
 operator:*:2:5::0:0:System &:/:/sbin/nologin
 bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
 tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
 kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
 games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
 news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
 man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
 bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
 uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
 xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
 pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
 nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
 +:::::::::
 -bill
 
 basie&prompt.root;</screen>
     </sect2>
 
     <sect2 id="netgroups">
       <title>Using netgroups</title>
       <indexterm><primary>netgroups</primary></indexterm>
 
       <para><emphasis>The netgroups part was contributed by
 	Udo Erdelhoff <email>ue@nathan.ruhr.de</email> in July
 	2000.</emphasis></para>
 
       <para>The method shown in the previous chapter works reasonably
         well if you need special rules for a very small number of
         users and/or machines.  On larger networks, you
         <emphasis>will</emphasis> forget to bar some users from logging
         onto sensitive machines, or you may even have to modify each
         machine separately, thus losing the main benefit of NIS,
         <emphasis>centralized</emphasis> administration.</para>
 
       <para>The NIS developers' solution for this problem is called
         <emphasis>netgroups</emphasis>.  Their purpose and semantics
         can be compared to the normal groups used by Unix file
         systems.  The main differences are the lack of a numeric id
         and the ability to define a netgroup by including both user
         accounts and other netgroups.</para>
 
       <para>Netgroups were developed to handle large, complex networks
         with hundreds of users and machines.  On one hand, this is
         a Good Thing if you are forced to deal with such a situation.
         On the other hand, this complexity makes it almost impossible to
         explain netgroups with really simple examples.  The example
         used in the remainder of this chapter demonstrates this
         problem.</para>
 
       <para>Let us assume that your successful introduction of NIS in
         your laboratory caught your superiors' interest.  Your next
         job is to extend your NIS domain to cover some of the other
         machines on campus.  The two tables contain the names of the
         new users and new machines as well as brief descriptions of
         them.</para>
 
       <informaltable>
         <tgroup cols="2">
           <thead>
             <row>
               <entry>User Name(s)</entry>
               <entry>Description</entry>
             </row>
           </thead>
    
           <tbody>
             <row>
               <entry>alpha, beta</entry>
               <entry>Normal employees of the IT department</entry>
             </row>
             
             <row>
               <entry>charlie, delta</entry>
               <entry>The new apprentices of the IT department</entry>
             </row>
             
             <row>
               <entry>echo, foxtrott, golf, ...</entry>
               <entry>Ordinary employees</entry>
             </row>
             
             <row>
               <entry>able, baker, ...</entry>
               <entry>The current interns</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <informaltable>
         <tgroup cols="2">
           <thead>
             <row>
               <entry>Machine Name(s)</entry>
               <entry>Description</entry>
             </row>
           </thead>
    
           <tbody>
             <row>
               <!--  Names taken from "Good Omens" by Neil Gaiman and Terry
                     Pratchett.  Many thanks for a brilliant book.  --> 
               <entry>war, death, famine, pollution</entry>
               <entry>Your most important servers.  Only the IT
                 employees are allowed to log onto these
                 machines.</entry>
             </row>
             <row>
               <!-- gluttony was omitted because it was too fat ;-) -->
               <entry>pride, greed, envy, wrath, lust, sloth</entry>
               <entry>Less important servers.  All members of the IT
                 department are allowed to login onto these machines.</entry>
             </row>
             
             <row>
               <entry>one, two, three, four, ...</entry>
               <entry>Ordinary workstations.  Only the
                 <emphasis>real</emphasis> employees are allowed to use
                 these machines.</entry>
             </row>
             
             <row>
               <entry>trashcan</entry>
               <entry>A very old machine without any critical data.
                 Even the intern is allowed to use this box.</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>If you tried to implement these restrictions by separately
         blocking each user, you would have to add one
         -<replaceable>user</replaceable> line to each system's passwd
         for each user who is not allowed to login onto that system.
         If you forget just one entry, you could be in trouble.  It may
         be feasible to do this correctly during the initial setup,
         however you <emphasis>will</emphasis> eventually forget to add
         the lines for new users during day-to-day operations.  After
         all, Murphy was an optimist.</para>
 
       <para>Handling this situation with netgroups offers several
         advantages.  Each user need not be handled separately;
         you assign a user to one or more netgroups and allow or forbid
         logins for all members of the netgroup.  If you add a new
         machine, you will only have to define login restrictions for
         netgroups.  If a new user is added, you will only have to add
         the user to one or more netgroups.  Those changes are
         independent of each other; no more <quote>for each combination
         of user and machine do...</quote> If your NIS setup is planned
         carefully, you will only have to modify exactly one central
         configuration file to grant or deny access to machines.</para>
         
       <para>The first step is the initialization of the NIS map
         netgroup.  FreeBSD's ypinit does not create this map by
         default, but its NIS implementation will support it once it has
         been created.  To create an empty map, simply type</para>
 
       <screen>ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput></screen>
 
       <para>and start adding content.  For our example, we need at
          least four netgroups: IT employees, IT apprentices, normal
          employees and interns.</para>
 
       <programlisting>IT_EMP  (,alpha,test-domain)    (,beta,test-domain)
 IT_APP  (,charlie,test-domain)  (,delta,test-domain)
 USERS   (,echo,test-domain)     (,foxtrott,test-domain) \
         (,golf,test-domain)
 INTERNS (,able,test-domain)     (,baker,test-domain)</programlisting>
 
       <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc.
         are the names of the netgroups.  Each bracketed group adds
         one or more user accounts to it.  The three fields inside a
         group are:</para>
         
       <orderedlist> 
         <listitem>
           <para>The name of the host(s) where the following items are
             valid.  If you do not specify a hostname, the entry is
             valid on all hosts.  If you do specify a hostname, you
             will enter a realm of darkness, horror and utter confusion.</para>
         </listitem>
 
         <listitem>
           <para>The name of the account that belongs to this
             netgroup.</para>
         </listitem>
 
         <listitem>
           <para>The NIS domain for the account.  You can import
             accounts from other NIS domains into your netgroup if you
             are one of unlucky fellows with more than one NIS
             domain.</para>
         </listitem>
       </orderedlist>
 
       <para>Each of these fields can contain wildcards.  See
         &man.netgroup.5; for details.</para>
         
       <note>
         <indexterm><primary>netgroups</primary></indexterm>
         <para>Netgroup names longer than 8 characters should not be
           used, especially if you have machines running other
           operating systems within your NIS domain.  The names are
           case sensitive; using capital letters for your netgroup
           names is an easy way to distinguish between user, machine
           and netgroup names.</para>
 
         <para>Some NIS clients (other than FreeBSD) cannot handle
           netgroups with a large number of entries.  For example, some
           older versions of SunOS start to cause trouble if a netgroup
           contains more than 15 <emphasis>entries</emphasis>.  You can
           circumvent this limit by creating several sub-netgroups with
           15 users or less and a real netgroup that consists of the
           sub-netgroups:</para>
 
         <programlisting>BIGGRP1  (,joe1,domain)  (,joe2,domain)  (,joe3,domain) [...]
 BIGGRP2  (,joe16,domain)  (,joe17,domain) [...]
 BIGGRP3  (,joe31,domain)  (,joe32,domain)
 BIGGROUP  BIGGRP1 BIGGRP2 BIGGRP3</programlisting>
 
         <para>You can repeat this process if you need more than 225
           users within a single netgroup.</para>
       </note>
 
       <para>Activating and distributing your new NIS map is
         easy:</para>
 
       <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput>
 ellington&prompt.root; <userinput>make</userinput></screen>
 
       <para>This will generate the three NIS maps
         <filename>netgroup</filename>,
         <filename>netgroup.byhost</filename> and
         <filename>netgroup.byuser</filename>.  Use &man.ypcat.1; to
         check if your new NIS maps are available:</para>
 
       <screen>ellington&prompt.user; <userinput>ypcat -k netgroup</userinput>
 ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput>
 ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen>
 
       <para>The output of the first command should resemble the
         contents of <filename>/var/yp/netgroup</filename>.  The second
         command will not produce output if you have not specified
         host-specific netgroups.  The third command can be used to
         get the list of netgroups for a user.</para>
 
       <para>The client setup is quite simple.  To configure the server
         <replaceable>war</replaceable>, you only have to start
         &man.vipw.8; and replace the line</para>
         
       <programlisting>+:::::::::</programlisting>
       
       <para>with</para>
 
       <programlisting>+@IT_EMP:::::::::</programlisting>
 
       <para>Now, only the data for the users defined in the netgroup
         <replaceable>IT_EMP</replaceable> is imported into
         <replaceable>war</replaceable>'s password database and only
         these users are allowed to login.</para>
 
       <para>Unfortunately, this limitation also applies to the ~
         function of the shell and all routines converting between user
         names and numerical user ids.  In other words, cd
         ~<replaceable>user</replaceable> will not work, <command>ls
         -l</command> will show the numerical id instead of the
         username and <command>find . -user joe -print</command> will
         fail with <quote>No such user</quote>.  To fix this, you will
         have to import all user entries <emphasis>without
         allowing them to login onto your servers</emphasis>.</para>
 
       <para>This can be achieved by adding another line to 
         <filename>/etc/master.passwd</filename>.  This line should
         contain <literal>+:::::::::/sbin/nologin</literal>, meaning
         <quote>Import all entries but replace the shell with
         <filename>/sbin/nologin</filename> in the imported
         entries</quote>.  You can replace any field
         in the passwd entry by placing a default value in your
         <filename>/etc/master.passwd</filename>.</para>
 
       <!-- Been there, done that, got the scars to prove it - ue -->
       <warning>
         <para>Make sure that the line
         <literal>+:::::::::/sbin/nologin</literal> is placed after 
         <literal>+@IT_EMP:::::::::</literal>.  Otherwise, all user
         accounts imported from NIS will have /sbin/nologin as their
         login shell.</para>
       </warning>
 
       <para>After this change, you will only have to change one NIS
         map if a new employee joins the IT department.  You could use
         a similar approach for the less important servers by replacing
         the old <literal>+:::::::::</literal> in their local version
         of <filename>/etc/master.passwd</filename> with something like
         this:</para>
 
       <programlisting>+@IT_EMP:::::::::
 +@IT_APP:::::::::
 +:::::::::/sbin/nologin</programlisting>
 
       <para>The corresponding lines for the normal workstations
         could be:</para>
 
       <programlisting>+@IT_EMP:::::::::
 +@USERS:::::::::
 +:::::::::/sbin/nologin</programlisting>
 
       <para>And everything would be fine until there is a policy
         change a few weeks later:  The IT department starts hiring
         interns.  The IT interns are allowed to use the normal
         workstations and the less important servers; and the IT
         apprentices are allowed to login onto the main servers.  You
         add a new netgroup IT_INTERN, add the new IT interns to this
         netgroup and start to change the config on each and every
         machine...  As the old saying goes:  <quote>Errors in
         centralized planning lead to global mess</quote>.</para>
 
       <para>NIS' ability to create netgroups from other netgroups can
         be used to prevent situations like these.  One possibility
         is the creation of role-based netgroups.  For example, you
         could create a netgroup called
         <replaceable>BIGSRV</replaceable> to define the login
         restrictions for the important servers, another netgroup
         called <replaceable>SMALLSRV</replaceable> for the less
         important servers and a third netgroup called
         <replaceable>USERBOX</replaceable> for the normal
         workstations.  Each of these netgroups contains the netgroups
         that are allowed to login onto these machines.  The new
         entries for your NIS map netgroup should look like this:</para>
 
       <programlisting>BIGSRV    IT_EMP  IT_APP
 SMALLSRV  IT_EMP  IT_APP  ITINTERN
 USERBOX   IT_EMP  ITINTERN USERS</programlisting>
 
       <para>This method of defining login restrictions works
         reasonably well if you can define groups of machines with
         identical restrictions.  Unfortunately, this is the exception
         and not the rule.  Most of the time, you will need the ability
         to define login restrictions on a per-machine basis.</para>
 
       <para>Machine-specific netgroup definitions are the other
         possibility to deal with the policy change outlined above.  In
         this scenario, the <filename>/etc/master.passwd</filename> of
         each box contains two lines starting with ``+''.  The first of
         them adds a netgroup with the accounts allowed to login onto
         this machine, the second one adds all other accounts with
         <filename>/sbin/nologin</filename> as shell.  It is a good
         idea to use the ALL-CAPS version of the machine name as the
         name of the netgroup.  In other words, the lines should look
         like this:</para>
 
       <programlisting>+@<replaceable>BOXNAME</replaceable>:::::::::
 +:::::::::/sbin/nologin</programlisting>
 
       <para>Once you have completed this task for all your machines,
         you will not have to modify the local versions of
         <filename>/etc/master.passwd</filename> ever again.  All
         further changes can be handled by modifying the NIS map.  Here
         is an example of a possible netgroup map for this
         scenario with some additional goodies.</para>
 
       <programlisting># Define groups of users first
 IT_EMP    (,alpha,test-domain)    (,beta,test-domain)
 IT_APP    (,charlie,test-domain)  (,delta,test-domain)
 DEPT1     (,echo,test-domain)     (,foxtrott,test-domain)
 DEPT2     (,golf,test-domain)     (,hotel,test-domain)
 DEPT3     (,india,test-domain)    (,juliet,test-domain)
 ITINTERN  (,kilo,test-domain)     (,lima,test-domain)
 D_INTERNS (,able,test-domain)     (,baker,test-domain)
 #
 # Now, define some groups based on roles
 USERS     DEPT1   DEPT2     DEPT3
 BIGSRV    IT_EMP  IT_APP
 SMALLSRV  IT_EMP  IT_APP    ITINTERN
 USERBOX   IT_EMP  ITINTERN  USERS
 #
 # And a groups for a special tasks
 # Allow echo and golf to access our anti-virus-machine
 SECURITY  IT_EMP  (,echo,test-domain)  (,golf,test-domain)
 #
 # machine-based netgroups
 # Our main servers
 WAR       BIGSRV
 FAMINE    BIGSRV
 # User india needs access to this server
 POLLUTION  BIGSRV  (,india,test-domain)
 #
 # This one is really important and needs more access restrictions
 DEATH     IT_EMP
 #
 # The anti-virus-machine mentioned above
 ONE       SECURITY
 #
 # Restrict a machine to a single user
 TWO       (,hotel,test-domain)
 # [...more groups to follow]</programlisting>
 
       <para>If you are using some kind of database to manage your user
         accounts, you should be able to create the first part of the
         map with your database's report tools.  This way, new users
         will automatically have access to the boxes.</para>
 
       <para>One last word of caution: It may not always be advisable
         to use machine-based netgroups.  If you are deploying a couple
         dozen or even hundreds of identical machines for student labs,
         you should use role-based netgroups instead of machine-based
         netgroups to keep the size of the NIS map within reasonable
         limits.</para>
     </sect2>
 
     <sect2>
       <title>Important things to remember</title>
 
       <para>There are still a couple of things that you will need to do
         differently now that you are in an NIS environment.</para>
 
       <itemizedlist>
         <listitem>
           <para>Every time you wish to add a user to the lab, you
             must add it to the master NIS server <emphasis>only</emphasis>,
             and <emphasis>you must remember to rebuild the NIS
             maps</emphasis>.  If you forget to do this, the new user will
             not be able to login anywhere except on the NIS master.
             For example, if we needed to add a new user
             &ldquo;jsmith&rdquo; to the lab, we would:</para>
 
           <screen>&prompt.root; <userinput>pw useradd jsmith</userinput>
 &prompt.root; <userinput>cd /var/yp</userinput>
 &prompt.root; <userinput>make test-domain</userinput></screen>
 
           <para>You could also run <command>adduser jsmith</command> instead
             of <command>pw useradd jsmith</command>.</para>
         </listitem>
         <listitem>
           <para><emphasis>Keep the administration accounts out of the NIS
             maps</emphasis>. You don't want to be propagating administrative
             accounts and passwords to machines that will have users that
             shouldn't have access to those accounts.</para>
         </listitem>
         <listitem>
           <para><emphasis>Keep the NIS master and slave
             secure, and minimize their downtime</emphasis>.
             If somebody either hacks or simply turns off
             these machines, they have effectively rendered many people without
             the ability to login to the lab.</para>
 
           <para>This is the chief weakness of any centralized administration
             system, and it is probably the most important weakness. If you do
             not protect your NIS servers, you will have a lot of angry
             users!</para>
         </listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>NIS v1 compatibility</title>
 
       <para> FreeBSD's <application>ypserv</application> has some support
 	for serving NIS v1 clients.  FreeBSD's NIS implementation only
 	uses the NIS v2 protocol, however other implementations include
 	support for the v1 protocol for backwards compatibility with older
 	systems.  The <application>ypbind</application> daemons supplied
 	with these systems will try to establish a binding to an NIS v1
 	server even though they may never actually need it (and they may
 	persist in broadcasting in search of one even after they receive a
 	response from a v2 server).  Note that while support for normal
 	client calls is provided, this version of ypserv does not handle
 	v1 map transfer requests; consequently, it cannot be used as a
 	master or slave in conjunction with older NIS servers that only
 	support the v1 protocol.  Fortunately, there probably are not any
 	such servers still in use today.</para>
     </sect2>
 
     <sect2>
       <title>NIS servers that are also NIS clients</title>
 
       <para> Care must be taken when running ypserv in a multi-server
 	domain where the server machines are also NIS clients.  It is
 	generally a good idea to force the servers to bind to themselves
 	rather than allowing them to broadcast bind requests and possibly
 	become bound to each other.  Strange failure modes can result if
 	one server goes down and others are dependent upon on it.
 	Eventually all the clients will time out and attempt to bind to
 	other servers, but the delay involved can be considerable and the
 	failure mode is still present since the servers might bind to each
 	other all over again.</para>
 
       <para>You can force a host to bind to a particular server by running
 	<command>ypbind</command> with the <option>-S</option>
 	flag.</para>
     </sect2>
 
     <sect2>
       <title>libscrypt v.s. libdescrypt</title>
       <indexterm>
         <primary>NIS</primary>
 	<secondary>crypto library</secondary>
       </indexterm>
       <para>One of the most common issues that people run into when trying
 	to implement NIS is crypt library compatibility.  If your NIS
 	server is using the DES crypt libraries, it will only support
 	clients that are using DES as well. To check which one your server
 	and clients are using look at the symlinks in
 	<filename>/usr/lib</filename>.  If the machine is configured to
 	use the DES libraries, it will look something like this:</para>
 
       <screen>&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
 lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libdescrypt.a
 lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libdescrypt.so
 lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libdescrypt.so.2
 lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libdescrypt_p.a
 -r--r--r--  1 root  wheel  13018 Nov  8 14:27 /usr/lib/libdescrypt.a
 lrwxr-xr-x  1 root  wheel     16 Nov  8 14:27 /usr/lib/libdescrypt.so@ -> libdescrypt.so.2
 -r--r--r--  1 root  wheel  12965 Nov  8 14:27 /usr/lib/libdescrypt.so.2
 -r--r--r--  1 root  wheel  14750 Nov  8 14:27 /usr/lib/libdescrypt_p.a</screen>
 
       <para>If the machine is configured to use the standard FreeBSD MD5
 	crypt libraries they will look something like this:</para>
 
       <screen>&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
 lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libscrypt.a
 lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libscrypt.so
 lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libscrypt.so.2
 lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libscrypt_p.a
 -r--r--r--  1 root  wheel   6194 Nov  8 14:27 /usr/lib/libscrypt.a
 lrwxr-xr-x  1 root  wheel     14 Nov  8 14:27 /usr/lib/libscrypt.so@ -> libscrypt.so.2
 -r--r--r--  1 root  wheel   7579 Nov  8 14:27 /usr/lib/libscrypt.so.2
 -r--r--r--  1 root  wheel   6684 Nov  8 14:27 /usr/lib/libscrypt_p.a</screen>
 
       <para>If you have trouble authenticating on an NIS client, this
         is a pretty good place to start looking for possible problems.
         If you want to deploy an NIS server for a heterogenous
         network, you will probably have to use DES on all systems
         because it is the lowest common standard.</para>
     </sect2>
   </sect1>
 
   <sect1 id="dhcp">
     <title>DHCP</title>
 
     <para><emphasis>Written by &a.gsutter;, March 2000.</emphasis></para>
 
     <sect2>
       <title>What is DHCP?</title>
       <indexterm>
         <primary>Dynamic Host Configuration Protocol (DHCP)</primary>
       </indexterm>
       <indexterm>
         <primary>Internet Software Consortium (ISC)</primary>
       </indexterm>
 
       <para>DHCP, the Dynamic Host Configuration Protocol, describes
         the means by which a system can connect to a network and obtain the
         necessary information for communication upon that network. FreeBSD
         uses the ISC (Internet Software Consortium) DHCP implementation, so
         all implementation-specific information here is for use with the ISC
         distribution.</para>
     </sect2>
 
     <sect2>
       <title>What This Section Covers</title>
 
       <para>This handbook section attempts to describe only the parts
         of the DHCP system that are integrated with FreeBSD; 
         consequently, the server portions are not described.  The DHCP
         manual pages, in addition to the references below, are useful
         resources.</para>
     </sect2>
 
     <sect2>
       <title>How it Works</title>
       <indexterm><primary>UDP</primary></indexterm>
       <para>When dhclient, the DHCP client, is executed on the client
         machine, it begins broadcasting requests for configuration
         information. By default, these requests are on UDP port 68. The
         server replies on UDP 67, giving the client an IP address and
         other relevant network information such as netmask, router, and
         DNS servers. All of this information comes in the form of a DHCP
         "lease" and is only valid for a certain time (configured by the
         DHCP server maintainer). In this manner, stale IP addresses for
         clients no longer connected to the network can be automatically
         reclaimed.</para>
 
       <para>DHCP clients can obtain a great deal of information from 
         the server.  An exhaustive list may be found in
         &man.dhcp-options.5;.</para>
     </sect2>
 
     <sect2>
       <title>FreeBSD Integration</title>
 
       <para>FreeBSD fully integrates the ISC DHCP client,
         <command>dhclient</command>.  DHCP client support is provided 
         within both the installer and the base system, obviating the need
         for detailed knowledge of network configurations on any network 
         that runs a DHCP server.  <command>dhclient</command> has been
         included in all FreeBSD distributions since 3.2.</para>
         <indexterm><primary>sysinstall</primary></indexterm>
         <para>DHCP is supported by <application>sysinstall</application>.
           When configuring a network interface within sysinstall, 
           the first question asked is, "Do you want to try dhcp
           configuration of this interface?"  Answering affirmatively will
           execute dhclient, and if successful, will fill in the network
           configuration information automatically.</para>
 
         <para>There are two things you must do to have your system use
 	  DHCP upon startup:</para>
         <indexterm>
 	  <primary>DHCP</primary>
 	  <secondary>requirements</secondary>
 	</indexterm>
 	<itemizedlist>
 	  <listitem>
             <para>Make sure that the <devicename>bpf</devicename>
 	      device is compiled into your kernel.  To do this, add
 	      <literal>pseudo-device bpf</literal> to your kernel
 	      configuration file, and rebuild the kernel.  For more
 	      information about building kernels, see <xref
 	      linkend="kernelconfig">.</para>
 	    <para>The <devicename>bpf</devicename> device is already
 	      part of the <filename>GENERIC</filename> kernel that is
 	      supplied with FreeBSD, so if you don't have a custom
 	      kernel, you shouldn't need to create one in order to get
 	      DHCP working.</para>
 	    <note>
 	      <para>For those who are particularly security conscious,
 	        you should be warned that <devicename>bpf</devicename>
 		is also the device that allows packet sniffers to work
 		correctly (although they still have to be run as
 		root).  <devicename>bpf</devicename>
 		<emphasis>is</emphasis> required to use DHCP, but if
 		you are very sensitive about security, you probably
 		shouldn't add <devicename>bpf</devicename> to your
 		kernel in the expectation that at some point in the
 		future you will be using DHCP.</para>
 	    </note>
 	  </listitem>
           <listitem>
             <para>Edit your <filename>/etc/rc.conf</filename> to
 	      include the following:</para>
 
             <programlisting>ifconfig_fxp0="DHCP"</programlisting>
 
             <note>
               <para>Be sure to replace <literal>fxp0</literal> with the
                 designation for the interface that you wish to dynamically 
                  configure.</para>
             </note>
 
             <para>If you are using a different location for
               <command>dhclient</command>, or if you wish to pass additional
               flags to <command>dhclient</command>, also include the
               following (editing as necessary):</para>
 
             <programlisting>dhcp_program="/sbin/dhclient"
 dhcp_flags=""</programlisting>
           </listitem>
         </itemizedlist>
 
         <indexterm>
 	  <primary>DHCP</primary>
 	  <secondary>server</secondary>
 	</indexterm>
         <para>The DHCP server, <command>dhcpd</command>, is included
           as part of the <literal>isc-dhcp2</literal> port in the ports
           collection.  This port contains the full ISC DHCP distribution,
           consisting of client, server, relay agent and documentation.
           </para>
     </sect2>
 
     <sect2>
       <title>Files</title>
       <indexterm>
         <primary>DHCP</primary>
 	<secondary>configuration files</secondary>
       </indexterm>	  
       <itemizedlist>
         <listitem><para><filename>/etc/dhclient.conf</filename></para>
           <para><command>dhclient</command> requires a configuration file,
             <filename>/etc/dhclient.conf</filename>. Typically the file
             contains only comments, the defaults being reasonably sane. This
             configuration file is described by the &man.dhclient.conf.5;
             man page.</para>
         </listitem>
 
         <listitem><para><filename>/sbin/dhclient</filename></para>
           <para><command>dhclient</command> is statically linked and
             resides in <filename>/sbin</filename>.  The &man.dhclient.8;
             manual page gives more information about
             <command>dhclient</command>.</para>
         </listitem>
 
         <listitem><para><filename>/sbin/dhclient-script</filename></para>
           <para><command>dhclient-script</command> is the FreeBSD-specific
             DHCP client configuration script.  It is described in
             &man.dhclient-script.8;, but should not need any user
             modification to function properly.</para>
         </listitem>
 
         <listitem><para><filename>/var/db/dhclient.leases</filename></para>
           <para>The DHCP client keeps a database of valid leases in this
             file, which is written as a log.  &man.dhclient.leases.5;
             gives a slightly longer description.</para>
         </listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
 
       <para>The DHCP protocol is fully described in
         <ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>.
         An informational resource has also been set up at
         <ulink url="http://www.dhcp.org/">dhcp.org</ulink>.</para>
     </sect2>
   </sect1>
 
 
   <sect1 id="dns">
     <title>DNS</title>
     <para><emphasis>Contributed by &a.chern;, April 12, 2001.
           </emphasis>
     </para>
 
     <sect2>
       <title>Overview</title>
       <indexterm><primary>BIND</primary></indexterm>
 
       <para>FreeBSD utilizes, by default, a version of BIND (Berkeley 
         Internet Name Domain), which is the most common implementation of the 
         DNS protocol.  DNS is the protocol through which names are mapped to 
         IPs, and vice versa.  For example, a query for www.freebsd.org 
         will send back a reply for the IP address of The FreeBSD Project's 
         webpage, whereas, a query for ftp.freebsd.org will return the IP 
         of the corresponding ftp machine.  Likewise, the opposite can 
         happen.  A query for an IP address can resolve its hostname.
       </para>
 
       <indexterm><primary>DNS</primary></indexterm>
       <para>DNS is coordinated across the Internet through a somewhat 
         complex system of authoritative root name servers, and other 
         smaller-scale nameservers who host and relay individual domain 
         information.
       </para>
 
       <para>
         This document refers to BIND 8.x, as it is the most current, 
         stable version used in FreeBSD.
       </para>
 
       <para>
         RFC1034 and RFC1035 dictates the DNS protocol.
       </para>
 
       <para>
         Currently, BIND is maintained by the <ulink 
         url="http://www.isc.org">
         Internet Software Consortium (www.isc.org)</ulink>
       </para>
     </sect2>
 
     <sect2>
       <title>Terminology</title>
 
       <indexterm><primary>zones</primary></indexterm>
       <para><emphasis>zone</emphasis> - Each individual domain, subdomain, 
         or 'area' dictated by DNS is considered a zone.
       </para>
 
       <para>Examples of zones:
       </para>
       <itemizedlist>
         <listitem>
           <para>. is the root zone</para>
         </listitem>
         <listitem>
           <para>org. is a zone under the root zone</para>
         </listitem>
         <listitem>
           <para>foobardomain.org is a zone under the org. zone</para>
         </listitem>
         <listitem>
           <para>foo.foobardomain.org. is a subdomain, a zone under the 
              foobardomain.org. zone
           </para>
         </listitem>
         <listitem>
           <para>
             1.2.3.in-addr.arpa is a zone referencing all ips which fall 
             under the 3.2.1.* ip space.
           </para>
         </listitem>
       </itemizedlist>
 
       <para><emphasis>named, bind, name server</emphasis> - these are all 
         common names for the BIND name server package within FreeBSD.
       </para>
 
       <indexterm><primary>resolver</primary></indexterm>
       <para><emphasis>resolver</emphasis> - a network process by which a 
         system queries a nameserver for answers
       </para>
 
       <indexterm><primary>root zone</primary></indexterm>
       <para><emphasis>root zone</emphasis> - literally, a '.', refers to 
         the root, or beginning zone.  All zones fall under this, as do all 
         files in fall under the root directory.  It is the beginning of the 
         Internet zone hierarchy
       </para>
 
       <para><emphasis>origin</emphasis> - refers to the point of start for 
         the particular zone
       </para>
 
       <para><emphasis>forward dns</emphasis> - mapping of hostnames to ip 
         addresses
       </para>
 
       <indexterm><primary>reverse DNS</primary></indexterm>
       <para><emphasis>reverse dns</emphasis> - the opposite, mapping of ip
         addresses to hostnames
       </para>
     </sect2>
 
     <sect2>
       <title>Reasons to run a name server</title>
         <itemizedlist>
           <listitem>
             <para>
               You need your machine to host DNS information to the world
             </para> 
             <itemizedlist>
               <listitem>
                 <para>An authoritative nameserver replies exclusively 
                   to requests.
                 </para>
               </listitem>
               <listitem>
                 <para>For example, you register foobardomain.org and wish 
                   to assign hostnames to the proper IP addresses.
                 </para>
               </listitem>
               <listitem>
                 <para>A slave nameserver, which replies to queries for a 
                   domain when the primary is down or inaccessible.
                 </para>
               </listitem>
               <listitem>
                 <para>The above two can also be done with in-addr.arpa, IP 
                   to hostname entries
                 </para>
               </listitem>
             </itemizedlist>
           </listitem>
           <listitem>
             <para>
               You wish your machine to act as a local relay of DNS 
               information
             </para>
             <itemizedlist>
               <listitem>
                 <para>DNS traffic has been measured to be about 5% or more 
                   of the total Internet traffic.
                 </para>
               </listitem>
               <listitem>
                  <para>A local DNS server may have some added benefit by 
                    providing a local cache of DNS information.
                  </para>
                </listitem>
                <listitem>
                  <para>
                    For example, when one queries for www.freebsd.org, 
                    their resolver goes out to (usually) your ISP's name 
                    server, and retrieves the query.
                  </para>
                </listitem>
                <listitem>
                  <para>
                    With a local, caching DNS server, the query only has to 
                    be made once to the outside world.  Every additional 
                    query will not have to go outside of the local network, 
                    since the information is cached.
                 </para>
               </listitem>
             </itemizedlist>
          </listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>How it works</title>
       <para>
         A DNS server in FreeBSD relies on the BIND daemon.  This daemon is
         called 'named' for obvious reasons.
       </para>
 
       <para><command>named</command> - the bind daemon</para>
       <para><command>ndc</command> - name daemon control program</para>
 
       <para>
         <filename>/etc/namedb</filename> - directory where all the bind 
         information resides
       </para>
       <para>
         <filename>/etc/namedb/named.conf</filename> - daemon configuration 
         file
       </para>
 
       <para>
         zone files are usually contained within the 
         <filename>/etc/namedb</filename>
         directory, and contain the information (query answers from 
         your site) served by your name server.
       </para>
     </sect2>
 
     <sect2>
       <title>Starting BIND</title>
       <indexterm>
         <primary>BIND</primary>
 	<secondary>starting</secondary>
       </indexterm>
       <para>
         Since bind is installed by default, configuring it all is 
         relatively simple.
       </para>
       <para>
         To ensure the named daemon is started at boot, put the following
          modifications in your <filename>/etc/rc.conf</filename>
       </para>
       <programlisting>named_enable="YES"</programlisting>
       <para>To start the daemon manually (after configuring it)</para>
       <screen>&prompt.root; <userinput>ndc start</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Configuration files</title>
       <indexterm>
         <primary>BIND</primary>
 	<secondary>configuration files</secondary>
       </indexterm>
       <sect3>
         <title>make-localhost</title>
         <para>Be sure to
         </para>
         <screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
 &prompt.root; <userinput>sh make-localhost</userinput></screen> 
         <para>to properly create your local reverse dns zone file in
           <filename>/etc/namedb/localhost.rev</filename>.
         </para>
       </sect3>
 
       <sect3>
         <title><filename>/etc/namedb/named.conf</filename></title>
 
-        <programlisting>// $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.56 2001/07/14 23:40:27 murray Exp $
+        <programlisting>// $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.57 2001/07/17 00:11:17 chern Exp $
 //
 // Refer to the named(8) man page for details.  If you are ever going
 // to setup a primary server, make sure you've understood the hairy
 // details of how DNS is working.  Even with simple mistakes, you can
 // break connectivity for affected parties, or cause huge amount of
 // useless Internet traffic.
 
 options {
         directory "/etc/namedb";
 
 // In addition to the "forwarders" clause, you can force your name
 // server to never initiate queries of its own, but always ask its
 // forwarders only, by enabling the following line:
 //
 //      forward only;
 
 // If you've got a DNS server around at your upstream provider, enter
 // its IP address here, and enable the line below.  This will make you
 // benefit from its cache, thus reduce overall DNS traffic in the
 Internet.
 /*
         forwarders {
                 127.0.0.1;
         };
 */</programlisting>
 
         <para>
           Just as the comment says, if you want to benefit from your 
           uplink's cache, you can enable this section of the config file.
 
           Normally, your nameserver will recursively query different 
           nameservers until it finds the answer it is looking for.  Having 
           this enabled will have it automatically see if your 
           uplink's (or whatever provided) ns has the requested query.
       
           If your uplink has a heavily trafficked, fast nameserver, 
           enabling this properly could work to your advantage.
 
           127.0.0.1 will *NOT* work here; change this to the IP of a 
           nameserver at your uplink.
         </para>
 
         <programlisting>        /*
          * If there is a firewall between you and nameservers you want
          * to talk to, you might need to uncomment the query-source
          * directive below.  Previous versions of BIND always asked
          * questions using port 53, but BIND 8.1 uses an unprivileged
          * port by default.
          */
         // query-source address * port 53;
 
         /*
          * If running in a sandbox, you may have to specify a different
          * location for the dumpfile.
          */
         // dump-file "s/named_dump.db";
 };
 
 // Note: the following will be supported in a future release.
 /*
 host { any; } {
         topology {
                 127.0.0.0/8;
         };
 };
 */
 
 // Setting up secondaries is way easier and the rough picture for this
 // is explained below.
 //
 // If you enable a local name server, don't forget to enter 127.0.0.1
 // into your /etc/resolv.conf so this server will be queried first.
 // Also, make sure to enable it in /etc/rc.conf.
 
 zone "." {
         type hint;
         file "named.root";
 };
 
 zone "0.0.127.IN-ADDR.ARPA" {
         type master;
         file "localhost.rev";
 };
 
 zone
 "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.INT" {
         type master;
         file "localhost.rev";
 };
 
 // NB: Do not use the IP addresses below, they are faked, and only
 // serve demonstration/documentation purposes!
 //
 // Example secondary config entries.  It can be convenient to become
 // a secondary at least for the zone where your own domain is in.  Ask
 // your network administrator for the IP address of the responsible
 // primary.
 //
 // Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
 // (This is the first bytes of the respective IP address, in reverse
 // order, with ".IN-ADDR.ARPA" appended.)
 //
 // Before starting to setup a primary zone, better make sure you fully
 // understand how DNS and BIND works, however.  There are sometimes
 // unobvious pitfalls.  Setting up a secondary is comparably simpler.
 //
 // NB: Don't blindly enable the examples below. :-)  Use actual names
 // and addresses instead.
 //
 // NOTE!!! FreeBSD runs bind in a sandbox (see named_flags in rc.conf).
 // The directory containing the secondary zones must be write accessible
 // to bind.  The following sequence is suggested:
 //
 //      mkdir /etc/namedb/s
 //      chown bind:bind /etc/namedb/s
 //      chmod 750 /etc/namedb/s
 
 /*
 zone "domain.com" {
         type slave;
         file "s/domain.com.bak";
         masters {
                 192.168.1.1;
         };
 };
 
 zone "0.168.192.in-addr.arpa" {
         type slave;
         file "s/0.168.192.in-addr.arpa.bak";
         masters {
                 192.168.1.1;
         };
 };
 */</programlisting>
         <para>
           These are example slave entries, read below to see more.
         </para>
         <para>
           For each new domain added to your nameserver, you must add one 
           of these entries to your <filename>named.conf</filename>
         </para>
         <para>
           The simplest zone entry, can look like
         </para>
         <programlisting>zone "foobardomain.org" {
 	type master;
 	file "foorbardomain.org";
 };</programlisting>
 
         <para>For a master entry with the zone information within 
           foobardomain.org, or
         </para>
 
         <programlisting>zone "foobardomain.org" {
 	type slave;
 	file "foobardomain.org";
 };</programlisting>
 
         <para>
           for a slave.  Note that slave zones automatically query the 
           listed master (authoritative) name servers for the zone file.
         </para>
       </sect3>
 
       <sect3>
         <title>Zone files</title>  
         <para>
           An example master 'foobardomain.org' (existing within 
           /etc/namedb/foobardomain.org) is as follows:
         </para>
 
         <programlisting>$TTL 3600
 
 foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
                         5               ; Serial
                         10800           ; Refresh
                         3600            ; Retry
                         604800          ; Expire
                         86400 )         ; Minimum TTL
 
 ; DNS Servers
 @       IN NS           ns1.foobardomain.org.
 @       IN NS           ns2.foobardomain.org.
 
 ; Machine Names
 localhost       IN A    127.0.0.1
 ns1             IN A    3.2.1.2
 ns2             IN A    3.2.1.3
 mail            IN A    3.2.1.10
 @               IN A    3.2.1.30
 
 ; Aliases
 www             IN CNAME        @
 
 ; MX Record
 @               IN MX   10      mail.foobardomain.org.</programlisting>
 
         <para>
           Note that every hostname ending in a '.' is an exact
           hostname, whereas everything without a trailing '.' is
           referenced to the origin.  For example, www is translated
           into www + origin.  In our fictitious zone file, our origin
           is foobardomain.org, so www would be www.foobardomain.org.
         </para>
 
         <para>
           The format of this file follows:
         </para>
         <programlisting>recordname      IN recordtype   value</programlisting>
 
 	<indexterm>
 	  <primary>DNS</primary>
 	  <secondary>records</secondary>
 	</indexterm>
         <para>
           The most commonly used DNS records:
         </para>
         <para><emphasis>SOA</emphasis> - start of zone authority</para>
         <para><emphasis>NS</emphasis> - an authoritative nameserver</para>
         <para><emphasis>A</emphasis> - A host address</para>
         <para><emphasis>CNAME</emphasis> - the canonical name for an 
           alias</para>
         <para><emphasis>MX</emphasis> - mail exchange</para>
         <para><emphasis>PTR</emphasis> - a domain name pointer (used in 
           reverse dns)</para>
         <programlisting>
 foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
                         5               ; Serial
                         10800           ; Refresh after 3 hours
                         3600            ; Retry after 1 hour
                         604800          ; Expire after 1 week
                         86400 )         ; Minimum TTL of 1 day
         </programlisting>
         <para>
           <emphasis>foobardomain.org.</emphasis> - the domain name, also 
           the origin for this zone file.
         </para>
         <para><emphasis>ns1.foobardomain.org.</emphasis> - the 
           primary/authoritative nameserver for this zone
         </para>
         <para><emphasis>admin.foobardomain.org.</emphasis> - the 
           responsible person for this zone, e-mail address with @ 
           replaced. (admin@foobardomain.org becomes admin.foobardomain.org)
         </para>
         <para>
           <emphasis>5</emphasis> - the serial number of the file.  this 
           must 
           be incremented each time the zone file is modified.  Nowadays, 
           many admins prefer a yyyymmddrr format for the serial number.  
           2001041002 would mean last modified 04/10/2001, the latter 02 being 
           the second time the zone file has been modified this day.  The 
           serial number is important as it alerts slave nameservers for a zone 
           when it is updated.
         </para>
 
         <programlisting>
 @       IN NS           ns1.foobardomain.org.
         </programlisting>
         <para>
           This is an NS entry.  Every nameserver that is going to reply
           authoritatively for the zone must have one of these entries.  
           The @ as seen here could have been 'foobardomain.org.' The @ 
           translates to the origin.
         </para>
 
         <programlisting>
 localhost       IN A    127.0.0.1
 ns1             IN A    3.2.1.2
 ns2             IN A    3.2.1.3
 mail            IN A    3.2.1.10
 @               IN A    3.2.1.30
         </programlisting>
         <para>
           The A record indicates machine names.  As seen above, 
           ns1.foobardomain.org would resolve to 3.2.1.2.  Again, the 
           origin symbol, @, is used here, thus meaning foobardomain.org would 
           resolve to 3.2.1.30.
         </para>
 
         <programlisting>
 www             IN CNAME        @
         </programlisting>
         <para>
           The canonical name record is usually used for giving aliases
           to a machine.  In the example, www is aliased to the machine
           addressed to the origin, or foobardomain.org (3.2.1.30).
           CNAMEs can be used to provide alias hostnames, or round
           robin one hostname among multiple machines.
         </para>
 
         <programlisting>
 @               IN MX   10      mail.foobardomain.org.
         </programlisting>
 
         <para>
           The MX record indicates which mail servers are responsible
           for handling incoming mail for the zone.
           mail.foobardomain.org is the hostname of the mail server,
           and 10 being the priority of that mailserver.
         </para>
 
         <para>
           One can have several mailservers, with priorities of 3, 2,
           1.  A mail server attempting to deliver to foobardomain.org
           would first try the highest priority MX, then the second
           highest, etc, until the mail can be properly delivered.
         </para>
 
         <para>
           For in-addr.arpa zone files (reverse dns), the same format is 
           used, except with PTR entries instead of A or CNAME.
         </para>
 
         <programlisting>$TTL 3600
 
 1.2.3.in-addr.arpa. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
                         5               ; Serial
                         10800           ; Refresh
                         3600            ; Retry
                         604800          ; Expire
                         3600 )          ; Minimum
 
 @       IN NS   ns1.foobardomain.org.
 @       IN NS   ns2.foobardomain.org.
 
 2       IN PTR  ns1.foobardomain.org.
 3       IN PTR  ns2.foobardomain.org.
 10      IN PTR  mail.foobardomain.org.
 30      IN PTR  foobardomain.org.</programlisting>
         <para>
          This file gives the proper IP to hostname mappings of our above
          fictitious domain.
         </para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Caching Name Server</title>
       <indexterm>
         <primary>BIND</primary>
 	<secondary>caching name server</secondary>
       </indexterm>
       <para>
         A caching nameserver is simply a nameserver that is not 
         authoritative for any zones.  It simply asks queries of its own, 
         and remembers them for later use.  To set one up, just configure 
         the name server as usual, omitting any inclusions of zones.
       </para>
     </sect2>
 
     <sect2 id="named-sandbox">
       <title>Running named in a Sandbox</title>
       <indexterm>
         <primary>BIND</primary>
 	<secondary>running in a sandbox</secondary>
       </indexterm>
       <para><emphasis>Contributed by Mike Makonnen 
         <email>mike_makonnen@yahoo.com</email>, May 1, 2001</emphasis>
       </para>
 
       <indexterm><primary>chroot</primary></indexterm>
       <para>For added security you may want to run &man.named.8; in a 
         sandbox. This will reduce the potential damage should it be 
         compromised. If you include a sandbox directory in its command 
         line, named will &man.chroot.8;
         into that directory immediately upon finishing processing its
         command line. It is also a good idea to have named run as a
         non-privileged user in the sandbox. The default FreeBSD install
         contains a user bind with group bind. If we wanted the sandbox in
         the <filename>/etc/namedb/sandbox</filename> directory the command 
         line for named would look like this:
       </para>
       <screen> &prompt.root; <userinput>/usr/sbin/named -u bind -g bind -t /etc/namedb/sandbox &lt;path_to_named.conf> </userinput></screen>
 
       <para>The following steps should be taken in order to 
         successfully run named in a sandbox. Throughout the following 
         discussion we will assume the path to your sandbox is 
         <filename>/etc/namedb/sandbox</filename>
       </para>
 
       <itemizedlist>
         <listitem>
           <para>Create the sandbox directory: 
             <filename>/etc/namedb/sandbox</filename></para>
         </listitem>
         <listitem>
         <para>Create other necessary directories off of the sandbox
           directory: <filename>etc</filename> and 
           <filename>var/run</filename></para>
         </listitem>
         <listitem>
          <para>copy <filename>/etc/localtime</filename> to 
            <filename>sandbox/etc</filename>
          </para>
         </listitem>
         <listitem>
           <para>make bind:bind the owner of all files and directories in 
             the sandbox:
             <screen>&prompt.root; <userinput>chown -R bind:bind /etc/namedb/sandbox</userinput> </screen>
             <screen>&prompt.root; <userinput>chmod -R 750 /etc/namedb/sandbox</userinput> </screen>
           </para>
         </listitem>
       </itemizedlist>
 
       <para>There are some issues you need to be aware of when running
          named in a sandbox.</para>
 
       <itemizedlist>
         <listitem>
         <para>Your &man.named.conf.5; file and all your zone files must 
            be in the sandbox
           </para>
         </listitem>
         <listitem>
           <para><filename>sandbox/etc/localtime</filename> is needed
             in order to have the correct time for your time zone in
             log messages.</para>
         </listitem>
         <listitem>
          <para> &man.named.8; will write its process id to a file in
          <filename>sandbox/var/run</filename></para>
         </listitem>
         <listitem>
           <para>The Unix socket used for communication by the &man.ndc.8;
             utility will be created in 
             <filename>sandbox/var/run</filename></para>
         </listitem>
         <listitem>
           <para>When using the ndc utility you need to specify the
             location of the Unix socket created in the sandbox, by
             &man.named.8;, by using the -c switch:
             <command>&prompt.root; ndc -c /etc/namedb/sandbox/var/run/ndc</command>
 	  </para>
         </listitem>
         <listitem>
           <para>If you enable logging to file, the log files must be
           in the sandbox</para>
         </listitem>
       </itemizedlist>
 
       <para>&man.named.8; can be started in a sandbox properly, if the
         following is in <filename>/etc/rc.conf</filename>
       </para>
       <programlisting>named_flags="-u bind -g bind -t /etc/namedb/sandbox"</programlisting>
     </sect2>
 
     <sect2>
       <title>How to use the nameserver</title>
 
       <para>If setup properly, the nameserver should be accessible through 
         the network and locally.  <filename>/etc/resolv.conf</filename> must 
         contain a nameserver entry with the local ip so it will query the 
         local name server first.
       </para>
 
       <para>
         To access it over the network, the machine must have the
         nameserver's IP address set properly in its own nameserver
         configuration options.
       </para>
     </sect2>
 
     <sect2>
       <title>Security</title>
 
       <para>Although BIND is the most common implementation of DNS,
         there is always the issue of security.  Possible and
         exploitable security holes are sometimes found.
       </para>
 
       <para>
         It is a good idea to subscribe to <ulink 
         url="http://www.cert.org">CERT</ulink> and
         <ulink url="http://www.freebsd.org/handbook/eresources.html#ERESOURCES-MAIL">freebsd-announce</ulink>
         to stay up to date with the current Internet and FreeBSD security 
         issues.
       </para>
 
       <para>
         If a problem arises, keeping your sources up to date and having a 
         fresh build of named can't hurt.
       </para>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
       <para>
         &man.ndc.8; &man.named.8; &man.named.conf.5;
       </para>
 
       <para>
         Official ISC BIND Page
         <ulink url="http://www.isc.org/products/BIND/">http://www.isc.org/products/BIND/</ulink>
       </para>
 
       <para>
         BIND FAQ
         <ulink url="http://www.nominum.com/resources/faqs/bind-faqs.html">
         http://www.nominum.com/resources/faqs/bind-faqs.html</ulink>
       </para>
 
        <para>
          <ulink url="http://www.oreilly.com/catalog/dns4/">O'Reilly DNS and BIND 4th Edition</ulink>
       </para>
 
       <para>
         <ulink url="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1034.txt">RFC1034 - Domain Names - 
         Concepts and Facilities</ulink>
       </para>
 
       <para>
        <ulink url="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1035.txt">RFC1035 - Domain Names - 
        Implementation and Specification</ulink>
       </para>
     </sect2>
   </sect1>
 
   <sect1 id="natd">
     <title>Network Address Translation daemon (natd)</title>
     <para><emphasis>Contributed by &a.chern;, June 2001.
           </emphasis>
     </para>
 
     <sect2 id="overview">
       <title>Overview</title>
       <indexterm><primary>natd</primary></indexterm>
       <para>FreeBSD's Network Address Translation daemon, commonly known as
         &man.natd.8; is a daemon that accepts incoming raw IP packets,
         changes the source to the local machine and re-injects these packets
         back into the outgoing IP packet stream. natd does this by changing 
         the source ip and port such that when data is received back, it is 
         able to determine the original location of the data and forward it 
         back to its original requestor.</para>
       <indexterm><primary>Internet connection sharing</primary></indexterm>
       <indexterm><primary>IP masquerading</primary></indexterm>
       <para>The most common use of NAT is to perform what is commonly known as
         Internet Connection Sharing.</para>
     </sect2>
 
     <sect2 id="setup">
       <title>Setup</title>
       <para>Due to the diminishing ip space in ipv4, and the increased number
         of users on high-speed consumer lines such as cable or DSL, people are
         in more and more need of an Internet Connection Sharing solution.  The
         ability to connect several computers online through one connection and
         ip makes &man.natd.8; a reasonable choice.</para>
 
       <para>Most commonly, a user has a machine connected to a cable or DSL
         line with one ip and wishes to use this one connected computer to
         provide Internet access to several more over a LAN.</para>
 
       <para>To do this, the FreeBSD machine on the Internet must act as a 
         gateway.  This gateway machine must have two NICs--one for connecting
         to the Internet router, the other connecting to a LAN.  All the
         machines on the LAN are connected through a hub or switch.</para>
 
       <mediaobject>
         <imageobject>
           <imagedata fileref="advanced-networking/natd">
         </imageobject>
 
 	<textobject>
 	  <literallayout class="monospaced">  _______       __________       ________
  |       |     |          |     |        |
  |  Hub  |-----| Client B |-----| Router |----- Internet
  |_______|     |__________|     |________|
      |
  ____|_____
 |          |
 | Client A |
 |__________|</literallayout>
         </textobject>
 
 	<textobject>
 	  <phrase>Network Layout</phrase>
 	</textobject>
       </mediaobject>
 
       <para>With this setup, the machine without Internet access can use
         the machine with access as a gateway to access the outside 
         world.</para>
     </sect2>
 
     <sect2 id="configuration">
       <indexterm>
         <primary>kernel</primary>
 	<secondary>configuration</secondary>
       </indexterm>
       <title>Configuration</title>
       <para>The following options must be in the kernel configuration
         file:</para>
       <programlisting>options IPFIREWALL
 options IPDIVERT</programlisting>
 
       <para>Additionally, at choice, the following may also be suitable:</para>
       <programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT
 options IPFIREWALL_VERBOSE</programlisting>
 
       <para>The following must be in <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>gateway_enable="YES"
 firewall_enable="YES"
 firewall_type="OPEN"
 natd_enable="YES"
 natd_interface="<replaceable>fxp0</replaceable>"
 natd_flags=""</programlisting>
 
       <informaltable frame="none">
         <tgroup cols="2">
           <tbody>
             <row>
               <entry>gateway_enable="YES"</entry>
               <entry>Sets up the machine to act as a gateway.  Running
                 <command>sysctl -w net.inet.ip.forwarding=1</command>
                 would have the same effect.</entry>
             </row>
             <row><entry>firewall_enable="YES"</entry>
              <entry>Enables the firewall rules in 
                <filename>/etc/rc.firewall</filename> at boot.</entry>
             </row>
             <row><entry>firewall_type="OPEN"</entry>
               <entry>This specifies a predefined firewall ruleset that
                 allows anything in.  See
                 <filename>/etc/rc.firewall</filename> for additional
                 types.</entry>
             </row>
             <row>
               <entry>natd_interface="fxp0"</entry>
               <entry>Indicates which interface to forward packets through. 
                 (the interface connected to the Internet)</entry>
             </row>
             <row>
               <entry>natd_flags=""</entry>
               <entry>Any additional configuration options passed to 
                 &man.natd.8; on boot.</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>Having the previous options defined in 
         <filename>/etc/rc.conf</filename> would run 
         <command>natd -interface fxp0</command> at boot.  This can also 
         be run manually.</para>
 
       <para>Each machine and interface behind the LAN should be assigned ip 
         numbers in the private network space as defined by
         <ulink url="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1918.txt">RFC 1918</ulink>
         and have a default gateway of the natd machine's internal ip.</para>
 
       <para>For example, client a and b behind the LAN have ips of 192.168.0.2
         and 192.168.0.3, while the natd machine's LAN interface has an ip of
         192.168.0.1.  Client a and b's default gateway must be set to that of
         the natd machine, 192.168.0.1.  The natd machine's external, or 
         Internet interface does not require any special modification for natd
         to work.</para>
     </sect2>
 
     <sect2 id="port-redirection">
       <title>Port Redirection</title>
 
       <para>The drawback with natd is that the LAN clients are not accessible
         from the Internet. Clients on the LAN can make outgoing connections to
         the world but cannot receive incoming ones.  This presents a problem 
         if trying to run Internet services on one of the LAN client machines.
         A simple way around this is to redirect selected Internet ports on the
         natd machine to a LAN client.
       </para>
 
       <para>For example, an IRC server runs on Client A, and a web server runs
         on Client B.  For this to work properly, connections received on ports
         6667 (irc) and 80 (web) must be redirected to the respective machines.
       </para>
 
       <para>The <command>-redirect_port</command> must be passed to 
         &man.natd.8; with the proper options.  The syntax is as follows:</para>
       <para><programlisting>     -redirect_port proto targetIP:targetPORT[-targetPORT]
                  [aliasIP:]aliasPORT[-aliasPORT]
                  [remoteIP[:remotePORT[-remotePORT]]]</programlisting></para>
 
       <para>In the above example, the argument should be:
         <programlisting>    -redirect_port tcp 192.168.0.2:6667 6667
     -redirect_port tcp 192.168.0.3:80 80</programlisting>
         This will redirect the proper <emphasis>tcp</emphasis> ports to the 
         LAN client machines.
       </para>
 
       <para>The -redirect_port argument can be used to indicate port
         ranges over individual ports.  For example, <replaceable>tcp
         192.168.0.2:2000-3000 2000-3000</replaceable> would redirect
         all connections received on ports 2000 to 3000 to ports 2000
         to 3000 on Client A.</para>
 
       <para>These options can be used when directly running 
         &man.natd.8; or placed within the
         <programlisting>natd_flags=""</programlisting> option in 
         <filename>/etc/rc.conf</filename>.</para>
 
       <para>For further configuration options, consult &man.natd.8;</para>
     </sect2>
 
     <sect2 id="address-redirection">
       <title>Address Redirection</title>
       <indexterm><primary>address redirection</primary></indexterm>
       <para>Address redirection is useful if several ips are available, yet
         they must be on one machine.  With this, &man.natd.8; can assign each
         LAN client its own external ip.  &man.natd.8; then rewrites outgoing
         packets from the LAN clients with the proper external ip and redirects
         all traffic incoming on that particular ip back to the specific LAN 
         client.  This is also known as static NAT. For example, the ips 
         128.1.1.1, 128.1.1.2, and 128.1.1.3 belong to the natd gateway 
         machine.  128.1.1.1 can be used as the natd gateway machine's external
         ip address, while 128.1.1.2 and 128.1.1.3 are forwarded back to LAN 
         clients A and B.</para>
 
       <para>The -redirect_address syntax is as follows:</para>
       <para><programlisting> -redirect_address localIP publicIP</programlisting>
       </para>
 
       <informaltable frame="none">
         <tgroup cols="2">
           <tbody>
             <row>
               <entry>localIP</entry>
               <entry>The internal ip of the LAN client.</entry>
             </row>
             <row>
               <entry>publicIP</entry>
               <entry>The external ip corresponding to the LAN client.</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>In the example, this argument would read:</para>
       <programlisting>    -redirect_address 192.168.0.2 128.1.1.2
     -redirect_address 192.168.0.3 128.1.1.3</programlisting>
 
       <para>Like -redirect_port, these arguments are also placed within 
         natd_flags of <filename>/etc/rc.conf</filename>.  With address 
         redirection, there is no need for port redirection since all data 
         received on a particular ip address is redirected.</para>
 
       <para>The external ips on the natd machine must be active and aliased 
         to the external interface.  Look at &man.rc.conf.5; to do so.</para>
 
     </sect2>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 <!--  LocalWords:  config mnt www -->
diff --git a/en_US.ISO8859-1/books/handbook/boot/chapter.sgml b/en_US.ISO8859-1/books/handbook/boot/chapter.sgml
index 3d728b73c4..2ca621e59f 100644
--- a/en_US.ISO8859-1/books/handbook/boot/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/boot/chapter.sgml
@@ -1,575 +1,575 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/boot/chapter.sgml,v 1.12 2001/06/29 18:31:16 murray Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/boot/chapter.sgml,v 1.13 2001/07/06 13:03:00 dd Exp $
 -->
 
 <chapter id="boot">
   <title>The FreeBSD Booting Process</title>
 
   <sect1 id="boot-synopsis">
     <title>Synopsis</title>
     <indexterm><primary>booting</primary></indexterm>
     <indexterm><primary>bootstrap</primary></indexterm>
 
     <para>FreeBSD uses a three-stage bootstrap by default, which
       basically entails three programs which call each
       other in order (two <link linkend="boot-blocks">boot
 	blocks</link>, and the <link
 	linkend="boot-loader">loader</link>).  Each of these three build on the
       previous program's understanding and provide increasing amounts
       of sophistication.</para>
 
     <indexterm><primary>kernel</primary></indexterm>
     <indexterm><primary><command>init</command></primary></indexterm>
 
     <para>The kernel is then started, which will then probe for devices
       and initialize them for use.  Once the kernel boot
       process is finished, the kernel passes control to the user process
       &man.init.8;, which then makes sure the disks are in a usable state.
       &man.init.8; then starts the user-level resource configuration which
       then mounts filesystems, sets up network cards to act on the
       network, and generally starts all the processes that usually
       are run on a FreeBSD system at startup.</para>
   </sect1>
 
   <sect1 id="boot-blocks">
     <title>The Boot Blocks: Bootstrap Stages 1 and 2</title>
 
     <para><firstterm>Bootstrapping</firstterm> is the process
       whereby a computer probes and initializes its devices, and
       works out what programs it is supposed to run.</para>
 
     <para>This involves the use of special Read Only Memory chips,
       which determine what further operations to do, and these
       usually pass control to other chips that do consistency and
       memory tests, configure devices, and provide a mechanism for
       programs to determine what configuration details were
       determined.</para>
 
     <indexterm><primary>BIOS</primary></indexterm>
     <indexterm><primary>CMOS</primary></indexterm>
     <para>In standard personal computers, this involves the BIOS
       (which oversees the bootstrap), and CMOS (which stores
       configuration).  BIOS and CMOS understand disks, and also
       understand where on the disk to find a program that will know
       how to load up an operating system.</para>
 
     <para>This chapter will not deal with this first part of the
       bootstrap process.  Instead it will focus on what happens after control
       is passed to the program on the disk.</para>
 
     <para>The boot blocks are responsible for finding (usually) the
       loader, and running it, and thus need to understand how to
       find that program on the filesystem, how to run the program,
       and also allow minor configuration of how they work.</para>
 
     <sect2 id="boot-boot0">
       <title>boot0</title>
       <indexterm><primary>Master Boot Record (MBR)</primary></indexterm>
 
       <para>There is actually a preceding bootblock, named boot0,
 	which lives on the <firstterm>Master Boot
 	  Record</firstterm>, the special part of the disk that the
 	system bootstrap looks for and runs, and it simply shows a
 	list of possible slices to boot from.</para>
 
       <para>boot0 is very simple, since the program in the
 	<abbrev>MBR</abbrev> can only be 512 bytes in size.</para>
 
       <para>It displays something like this:</para>
 
       <example id="boot-boot0-example">
 	<title>boot0 screenshot</title>
 
 	<screen>F1 DOS
 F2 FreeBSD
 F3 Linux
 F4 ??
 F5 Drive 1
 
 Default: F2</screen>
       </example>
     </sect2>
   
     <sect2 id="boot-boot1">
       <title>boot1</title>
       
       <para>boot1 is found on the boot sector of the boot slice,
 	which is where <link linkend="boot-boot0">boot0</link>, or
 	any other program on the <abbrev>MBR</abbrev> expects to
 	find the program to run to continue the boot process.</para>
 
       <para>boot1 is very simple, since it too can only be 512 bytes
 	in size, and knows just enough about the FreeBSD
 	<firstterm>disklabel</firstterm>, which stores information
 	about the slice, to find and execute <link
 	  linkend="boot-boot2">boot2</link>.</para>
     </sect2>
   
     <sect2 id="boot-boot2">
       <title>boot2</title>
       
       <para>boot2 is slightly more sophisticated, and understands
 	the FreeBSD filesystem enough to find files on it, and can
 	provide a simple interface to choose the kernel or loader to
 	run.</para>
 
       <para>Since the <link linkend="boot-loader">loader</link> is
 	much more sophisticated, and provides a nice easy-to-use
 	boot configuration, boot2 usually runs it, but previously it
 	was tasked to run the kernel directly.</para>
 
       <example id="boot-boot2-example">
 	<title>boot2 screenshot</title>
 
 	<screen>&gt;&gt; FreeBSD/i386 BOOT
 Default: 0:wd(0,a)/kernel
 boot:</screen>
       </example>
     </sect2>
   </sect1>
 
   <sect1 id="boot-loader">
     <title>Loader: Bootstrap Stage Three</title>
 
     <indexterm><primary>boot-loader</primary></indexterm>
     <para>The loader is the final stage of the three-stage
       bootstrap, and is located on the filesystem, usually as
       <filename>/boot/loader</filename>.</para>
       
     <note>
       <para>While <filename>/boot/boot0</filename>,
 	<filename>/boot/boot1</filename>, and
 	<filename>/boot/boot2</filename> are files there, they are
 	not the actual copies in the <abbrev>MBR</abbrev>, the boot
 	sector, or the disklabel respectively.</para>
     </note>
     
     <para>The loader is intended as a user-friendly method for
       configuration, using an easy-to-use built-in command set,
       backed up by a more powerful interpreter, with a more complex
       command set.</para> 
 
     <sect2 id="boot-loader-flow">
       <title>Loader Program Flow</title>
       
       <para>During initialization, the loader will probe for a
 	console and for disks, and figure out what disk it is
 	booting from.  It will set variables accordingly, and then
 	the interpreter is started, and the easy-to-use commands are
 	explained to it.</para>
       <indexterm><primary>loader</primary></indexterm>
       <indexterm><primary>loader configuration</primary</indexterm>
 
       <para>loader will then read
 	<filename>/boot/loader.rc</filename>, which by default reads
 	in <filename>/boot/defaults/loader.conf</filename> which
 	sets reasonable defaults for variables and reads
 	<filename>/boot/loader.conf</filename> for local changes to
 	those variables.  <filename>loader.rc</filename> then acts
 	on these variables, loading whichever modules and kernel are
 	selected.</para>
 
       <para>Finally, by default, the loader issues a 10 second wait
 	for key presses, and boots the kernel if it is not interrupted.
 	If interrupted, the user is presented with a prompt which
 	understands the easy-to-use command set, where the user may
 	adjust variables, unload all modules, load modules, and then
 	finally boot or reboot.</para>
 
       <para>A more technical discussion of the process is available
 	in &man.loader.8;</para>
     </sect2>
     
     <sect2 id="boot-loader-commands">
       <title>Loader Built-In Commands</title>
       
       <para>The easy-to-use command set comprises of:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term>autoboot <replaceable>seconds</replaceable></term>
 
 	  <listitem>
 	    <para>Proceeds to boot the kernel if not interrupted
 	      within the time span given, in seconds.  It displays a
 	      countdown, and the default timespan is 10
 	      seconds.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>boot
 	    <optional><replaceable>-options</replaceable></optional>
 	    <optional><replaceable>kernelname</replaceable></optional></term>
 
 	  <listitem>
 	    <para>Immediately proceeds to boot the kernel, with the
 	      given options, if any, and with the kernel name given,
 	      if it is.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>boot-conf</term>
 
 	  <listitem>
 	    <para>Goes through the same automatic configuration of
 	      modules based on variables as what happens at boot.
 	      This only makes sense if you use
 	      <command>unload</command> first, and change some
 	      variables, most commonly <envar>kernel</envar>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>help
 	    <optional><replaceable>topic</replaceable></optional></term>
 
 	  <listitem>
 	    <para>Shows help messages read from
 	      <filename>/boot/loader.help</filename>.  If the topic
 	      given is <literal>index</literal>, then the list of
 	      available topics is given.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>include <replaceable>filename</replaceable>
 	    &hellip;</term>
 
 	  <listitem>
 	    <para>Processes the file with the given filename.  The
 	      file is read in, and interpreted line by line.  An
 	      error immediately stops the include command.</para>
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
 	  <term>load <optional><option>-t</option>
 	    <replaceable>type</replaceable></optional>
 	    <replaceable>filename</replaceable></term>
 
 	  <listitem>
 	    <para>Loads the kernel, kernel module, or file of the
 	      type given, with the filename given.  Any arguments
 	      after filename are passed to the file.</para>
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
 	  <term>ls <optional><option>-l</option></optional>
 	    <optional><replaceable>path</replaceable></optional></term>
 
 	  <listitem>
 	    <para>Displays a listing of files in the given path, or
 	      the root directory, if the path is not specified.  If
 	      <option>-l</option> is specified, file sizes will be
 	      shown too.</para>
 	  </listitem>
 	</varlistentry>
 	<varlistentry>
 	  <term>lsdev <optional><option>-v</option></optional></term>
 
 	  <listitem>
 	    <para>Lists all of the devices from which it may be
 	      possible to load modules. If <option>-v</option> is
 	      specified, more details are printed.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>lsmod <optional><option>-v</option></optional></term>
 
 	  <listitem>
 	    <para>Displays loaded modules. If <option>-v</option> is
 	      specified, more details are shown.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>more <replaceable>filename</replaceable></term>
 
 	  <listitem>
 	    <para>Display the files specified, with a pause at each
 	      <varname>LINES</varname> displayed.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>reboot</term>
 
 	  <listitem>
 	    <para>Immediately reboots the system.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>set <replaceable>variable</replaceable></term>
 	  <term>set
 	    <replaceable>variable</replaceable>=<replaceable>value</replaceable></term>
 
 	  <listitem>
 	    <para>Set loader's environment variables.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>unload</term>
 
 	  <listitem>
 	    <para>Removes all loaded modules.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2 id="boot-loader-examples">
       <title>Loader Examples</title>
 
       <para>Here are some practical examples of loader usage.</para>
 
       <itemizedlist>
 	<listitem>
     <indexterm><primary>single-user mode</primary></indexterm>
 	  <para>To simply boot your usual kernel, but in single-user
 	    mode:</para>
 
 	  <screen><userinput>boot -s</userinput></screen>
 	</listitem>
 
 	<listitem>
 	  <para>To unload your usual kernel and modules, and then
 	    load just your old (or another) kernel:</para>
     <indexterm><primary>kernel.old</primary></indexterm>
 
 	  <screen><userinput>unload</userinput>
   <userinput>load <replaceable>kernel.old</replaceable></userinput></screen>
 
 	  <para>You can use <filename>kernel.GENERIC</filename> to
 	    refer to the generic kernel that comes on the install
 	    disk, or <filename>kernel.old</filename> to refer to
 	    your previously installed kernel (when you've upgraded
 	    or configured your own kernel, for example).</para>
 
 	  <note>
 	    <para>Use the following to load your usual modules with
 	      another kernel:</para>
 
 	    <screen><userinput>unload</userinput>
 <userinput>set kernel="<replaceable>kernel.old</replaceable>"</userinput>
 <userinput>boot-conf</userinput></screen>
 	  </note>
 	</listitem>
 
 	<listitem>
 	  <para>To load a kernel configuration script (an automated
 	    script which does the things you'd normally do in the
 	    kernel boot-time configurator):</para>
 
 	  <screen><userinput>load -t userconfig_script
 	    <replaceable>/boot/kernel.conf</replaceable></userinput></screen>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="boot-kernel">
     <title>Kernel Interaction During Boot</title>
     <indexterm>
       <primary>kernel</primary>
       <secondary>boot interaction</secondary>
     </indexterm>
     
     <para>Once the kernel is loaded by either <link
 	linkend="boot-loader">loader</link> (as usual) or <link
 	linkend="boot-boot2">boot2</link> (bypassing the loader), it
       examines its boot flags, if any, and adjusts its behavior as
       necessary.</para>
 
     <sect2 id="boot-kernel-bootflags">
       <indexterm>
         <primary>kernel</primary>
         <secondary>bootflags</secondary>
       </indexterm>
       <title>Kernel Boot Flags</title>
 
       <para>Here are the more common boot flags:</para>
 
       <variablelist id="boot-kernel-bootflags-list">
 	<varlistentry>
 	  <term><option>-a</option></term>
 
 	  <listitem>
 	    <para>during kernel initialization, ask for the device
 	      to mount as the root file system.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-C</option></term>
 
 	  <listitem>
 	    <para>boot from CDROM.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-c</option></term>
 
 	  <listitem>
 	    <para>run UserConfig, the boot-time kernel
 	      configurator</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-s</option></term>
 
 	  <listitem>
 	    <para>boot into single-user mode</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-v</option></term>
 
 	  <listitem>
 	    <para>be more verbose during kernel startup</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
       <note>
 	<para>There are other boot flags, read &man.boot.8; for more
 	  information on them.</para>
       </note>
     </sect2>
 
 <!--    <sect2 id="boot-kernel-userconfig">
       <title>UserConfig: The boot-time kernel configurator</title>
       
       <para> </para>
     </sect2> -->
   </sect1>
 
   <sect1 id="boot-init">
     <indexterm><primary>init</primary></indexterm>
     <title>Init: Process Control Initialization</title>
 	
     <para>Once the kernel has finished booting, it passes control to
       the user process <command>init</command>, which is located at
       <filename>/sbin/init</filename>, or the program path specified
       in the <envar>init_path</envar> variable in
       <command>loader</command>.</para>
 
     <sect2 id="boot-autoreboot">
       <title>Automatic Reboot Sequence</title>
       
       <para>The automatic reboot sequence makes sure that the
 	filesystems available on the system are consistent.  If they
-	are not, and <command>fsck</command> can not fix the
+	are not, and <command>fsck</command> cannot fix the
 	inconsistencies, <command>init</command> drops the system
 	into <link linkend="boot-singleuser">single-user mode</link>
 	for the system administrator to take care of the problems
 	directly.</para>
     </sect2>
 
     <sect2 id="boot-singleuser">
       <title>Single-User Mode</title>
       <indexterm><primary>single-user mode</primary></indexterm>
       <indexterm><primary>console</primary></indexterm>
       
       <para>This mode can be reached through the <link
 	  linkend="boot-autoreboot">automatic reboot
 	  sequence</link>, or by the user booting with the
 	<option>-s</option> or setting the
 	<envar>boot_single</envar> variable in
 	<command>loader</command>.</para>
 
       <para>It can also be reached by calling
 	<command>shutdown</command> without the reboot
 	(<option>-r</option>) or halt (<option>-h</option>) options,
 	from <link linkend="boot-multiuser">multi-user
 	  mode</link>.</para>
 
       <para>If the system console <literal>console</literal> is set
 	to <literal>insecure</literal> in
 	<filename>/etc/ttys</filename>, then the system prompts for
 	the root password before initiating single-user mode.</para>
 
       <example id="boot-insecure-console">
 	<title>An insecure console in /etc/ttys</title>
 
 	<programlisting># name  getty                           type    status          comments
 #
 # This entry needed for asking password when init goes to single-user mode
 # If you want to be asked for password, change "secure" to "insecure" here
 console none                            unknown off insecure</programlisting>
       </example>
 
       <note>
 	<para>An <literal>insecure</literal> console means that you
 	  consider your physical security to the console to be
 	  insecure, and want to make sure only someone who knows the
 	  root password may use single-user mode, and it does not
 	  mean that you want to run your console insecurely.  Thus,
 	  if you want security, choose <literal>insecure</literal>,
 	  not <literal>secure</literal>.</para>
       </note>
     </sect2>
     
     <sect2 id="boot-multiuser">
       <title>Multi-User Mode</title>
       <indexterm><primary>multi-user mode</primary></indexterm>
       
       <para>If <command>init</command> finds your filesystems to be
 	in order, or once the user has finished in <link
 	  linkend="boot-singleuser">single-user mode</link>, the
 	system enters multi-user mode, in which it starts the
 	resource configuration of the system.</para>
 
       <sect3 id="boot-rc">
       <indexterm><primary>rc files</primary></indexterm>
 	<title>Resource Configuration (rc)</title>
 
 	<para>The resource configuration system reads in
 	  configuration defaults from
 	  <filename>/etc/defaults/rc.conf</filename>, and
 	  system-specific details from
 	  <filename>/etc/rc.conf</filename>, and then proceeds to
 	  mount the system filesystems mentioned in
 	  <filename>/etc/fstab</filename>, start up networking
 	  services, starts up miscellaneous system daemons, and
 	  finally runs the startup scripts of locally installed
 	  packages.</para>
 
 	<para>&man.rc.8; is a good reference to the resource
 	  configuration system, as is examining the scripts
 	  themselves.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="boot-shutdown">
     <title>Shutdown Sequence</title>
     <indexterm><primary>shutdown</primary></indexterm>
 
     <para>Upon controlled shutdown, via <command>shutdown</command>,
       <command>init</command> will attempt to run the script
       <filename>/etc/rc.shutdown</filename>, and then proceed to send
       all processes the terminate signal, and subsequently the kill
       signal to any that don't terminate timely.</para>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
index 8d5b25fd1a..5040b09af4 100644
--- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
@@ -1,2295 +1,2295 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml,v 1.30 2001/07/17 00:11:24 chern Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml,v 1.31 2001/07/17 01:22:35 chern Exp $
 -->
 
 <chapter id="x11">
   <title>The X Window System</title>
 
   <para><emphasis>This chapter has been graciously donated by &a.grog;
     from his book, <ulink
     url="http://www.wccdrom.com/titles/freebsd/bsdcomp_bkx.phtml">The
     Complete FreeBSD</ulink>, and remains copyright of him.
     Modifications for the handbook made by &a.jim;.  The section on
     fonts in XFree86 was contributed by &a.murray; and the section on
     XDM was contributed by &a.sethk;.</emphasis></para>
 
   <sect1>
     <title>Synopsis</title>
     <para>The following chapter will cover installing and configuring X11
       on your system.  For more information on X11 and to see whether your
       video card is supported, check the <ulink
       url="http://www.xfree86.org/">XFree86</ulink> web site.</para>
   </sect1>
 
   <sect1 id="x-overview">
     <title>Overview</title>
 
     <para>FreeBSD comes with XFree86, a port of X11R6 that supports
       several versions of Intel-based Unix.  This chapter describes how
       to set up your XFree86 server.  It is based on material supplied
       with the FreeBSD release, specifically the files README.FreeBSD
       and  README.Config in the directory
       <filename>/usr/X11R6/lib/X11/doc</filename>.  If you find any
       discrepancy, the material in those files will be more up-to-date
       than this description.  In addition, the file
       <filename>/usr/X11R6/lib/X11/doc/RELNOTES</filename> contains
       OS-independent information about the current release.</para>
 
     <para>X uses a lot of memory.  In order to run X, your system should
       have an absolute minimum of 8 MB of memory, but performance will be
       painful with so little memory.  A more practical minimum is 16 MB,
       and you can improve performance  by adding more memory.  If you use
       X intensively, you will continue seeing performance improvement by
       increasing to as much as 128 MB of RAM.</para>
 
     <para>There is lots of useful information in the rest of this chapter,
       but maybe you are not interested in information right now.  You just
       want to get your X server up and running.  However, be warned:</para>
 
       <warning>
 	<para>An incorrect installation can burn out your monitor or your
 	  video  board.</para>
       </warning>
 
       <para>However, if you know you are in spec, and you have a standard
 	Super VGA board and a good multi-frequency monitor, then you can
 	probably get things up and running without reading this
 	chapter.</para>
   </sect1>
 
   <sect1 id="x-install">
     <title>Installing XFree86</title>
 
     <para>The easiest way to install XFree86 is with the sysinstall
       program, either when you are installing the system, or later by
       starting the program <command>/stand/sysinstall</command>.  In the
       rest of this chapter, we will look at what makes up the
       distribution, and we will also take a look at manually installing
       X11.</para>
 
     <sect2>
       <title>The XFree86 Distribution</title>
 
       <para>XFree86 is distributed as a bewildering number of archives.
 	In the following section, we will take a look at what you should
 	install.  Do not worry too much, though; if you cannot decide
 	what to pick and you have 200MB of disk space free, it's safe to
 	unpack everything.</para>
 
       <para>At a minimum you need to unpack the archives in the
 	following table and at least one server that matches your VGA
 	board.  You will need 10Mb for the minimum required run-time
 	binaries only, and between 1.7 and 3 MB for the server.</para>
 
       <para>Below is a table of the required components.</para>
 
       <informaltable>
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Archive</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><filename>Xbin.tgz</filename></entry>
 	      <entry>All the executable X client applications and shared
 		libraries.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xfnts.tgz</filename></entry>
 	      <entry>The misc and 75 dpi fonts.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xlib.tgz</filename></entry>
 	      <entry>Data files and libraries needed at runtime.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
 
     <sect2>
       <title>The X Server</title>
 
       <para>In addition to the archives above, you need at least one
 	server, which will take up about 3 MB of disk.  The choice
 	depends primarily on what kind of display board you have.  The
 	default server name is <filename>/usr/X11R6/bin/X</filename>, and
 	it is a link to a specific server binary
 	<filename>/usr/X11R6/bin/XF86_xxxx</filename>.  You will find the
 	server archives for the standard PC architecture in
 	<filename>/cdrom/XF86336/Servers</filename>, and the servers for
 	the Japanese PC98 architecture in
 	<filename>/cdrom/XF86336/PC98-Servers</filename> if you have the
 	CD set.  Alternatively, they are available on our FTP site at
 	<ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/XF86336/Servers/">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/XF86336/Servers/</ulink> or <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/XF86336/PC98-Servers/">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/XF86336/PC98-Servers/</ulink></para>
 
       <para>Available X servers for the standard PC architecture:</para>
 
       <informaltable>
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Archive</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><filename>X8514.tgz</filename></entry>
 	      <entry>8-bit color for IBM 8514 and true
 		compatibles.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XAGX.tgz</filename></entry>
 	      <entry>8 and 16-bit color for AGX and XGA boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XI128.tgz</filename></entry>
 	      <entry>8 and 16-bit color for I128 boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XMa32.tgz</filename></entry>
 	      <entry>8 and 16-bit color for ATI Mach32 boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XMa64.tgz</filename></entry>
 	      <entry>8, 16, and 32-bit color fot ATI Mach64
 		boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XMa8.tgz</filename></entry>
 	      <entry>8-bit color for ATI Mach8 boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XMono.tgz</filename></entry>
 	      <entry>1-bit monochrome for VGA, Super-VGA, Hercules, and
 		others.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XP9K.tgz</filename></entry>
 	      <entry>8, 16, and 32-bit color for Weitek P9000 boards
 		(Diamond Viper).</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XS3.tgz</filename></entry>
 	      <entry>8, 16, and 32-bit color for S3 boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XS3V.tgz</filename></entry>
 	      <entry>8 and 16-bit color for S3 ViRGE boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XSVGA.tgz</filename></entry>
 	      <entry>&gt;=8-bit color for Super-VGA cards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XVG16.tgz</filename></entry>
 	      <entry>4-bit color for VGA and Super-VGA cards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>XW32.tgz</filename></entry>
 	      <entry>8-bit color for ET4000/W32, /W32i, /W32p, and
 		ET6000 cards.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>Available X servers for the Japanese PC98 architecture:</para>
 
       <informaltable>
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Archive</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><filename>X9GAN.tgz</filename></entry>
 	      <entry>8-bit color for PC98 GA-98NB/WAP boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9GA9.tgz</filename></entry>
 	      <entry>8, 16, and 32-bit color for PC98 S3 GA-968
 		boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9480.tgz</filename></entry>
 	      <entry>8-bit color for PC98 PEGC</entry>
 	    </row>
 
 	    <row>
   	      <entry><filename>X9NKV.tgz</filename></entry>
 	      <entry>8-bit color for PC98 NEC-CIRRUS/EPSON NKV/NKV2
 		boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9WBS.tgz</filename></entry>
 	      <entry>8-bit color for PC98 WAB-S boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9WEP.tgz</filename></entry>
 	      <entry>8-bit color for PC98 WAB-EP boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9WSN.tgz</filename></entry>
 	      <entry>8-bit color for PC98 WSN-A2F boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9EGC.tgz</filename></entry>
 	      <entry>4-bit color for PC98 EGC.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9TGU.tgz</filename></entry>
 	      <entry>8 and 16-bit color for PC98 Trident Cyber9320/9680
 		boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9NS3.tgz</filename></entry>
 	      <entry>8 and 16-bit color for PC98 NEC S3 boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9SPW.tgz</filename></entry>
 	      <entry>8 and 16-bit color for PC98 S3 PW/PCSKB
 		boards.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>X9LPW.tgz</filename></entry>
 	      <entry>8 and 16-bit color for PC98 S3 PW/LB boards.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>Each of these servers includes a manual page which contains
 	details of supported chipsets and server-specific configuration
 	options.</para>
 
       <para>There are also a number of archives are provided for X
 	programmers:</para>
 
       <informaltable>
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Archive</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><filename>Xprog.tgz</filename></entry>
 	      <entry>Config, <filename>lib*.a</filename>, and
 		<filename>*.h</filename> files needed for compiling
 		clients.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xctrb.tgz</filename></entry>
 	      <entry>Contributed sources.</entry>
 	    </row>
 
 	    <row>
   	      <entry><filename>Xlk98.tgz</filename></entry>
 	      <entry>The <quote>link kit</quote> for building servers,
 		Japanese PC98 version.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xlkit.tgz</filename></entry>
 	      <entry>The <quote>link kit</quote> for building servers,
 		normal PC architecture.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xsrc-1.tgz</filename></entry>
 	      <entry>Part 1 of the complete sources.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xsrc-2.tgz</filename></entry>
 	      <entry>Part 2 of the complete sources.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xsrc-3.tgz</filename></entry>
 	      <entry>Part 3 of the complete sources.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <note>
 	<para>You will need <filename>Xprog.tgz</filename> if you intend
 	  to install ports of X software.</para>
       </note>
 
       <para>XFree86 also includes a number of optional parts, such as
         documentation, and setup programs.</para>
 
       <informaltable>
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Archive</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><filename>Xdoc.tgz</filename></entry>
 	      <entry>READMEs</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xjdoc.tgz</filename></entry>
 	      <entry>READMEs in Japanese.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xps.tgz</filename></entry>
 	      <entry>READMEs in PostScript.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xhtml.tgz</filename></entry>
 	      <entry>READMEs in HTML.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xman.tgz</filename></entry>
 	      <entry>Manual pages.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xcfg.tgz</filename></entry>
 	      <entry>Customizable <command>xinit</command> and
 		<command>xdm</command> runtime configuration
 		files.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xset.tgz</filename></entry>
 	      <entry>The <filename>X86Setup</filename> utility; a
 		graphical version of the <filename>xf86config</filename>
 		utility.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xjset.tgz</filename></entry>
 	      <entry>The <filename>XF86Setup</filename> utility,
 		Japanese version, for the normal PC architecture.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para><filename>XF86Setup</filename> is a graphical mode setup
 	program for XFree86, and you may prefer it to the standard setup
 	program <filename>xf86config</filename>.  You do not need any
 	special archives for <filename>xf86config</filename>; it is
 	included in <filename>Xbin.tgz</filename>.</para>
 
       <para>The first time you install, you will need
         <filename>Xcfg.tgz</filename> to create your initial configuration
 	files.  Do not use it when upgrading; it overwrites your
 	configuration files.</para>
 
       <para>There are also additional fonts that are available with
         XFree86:</para>
 
       <informaltable>
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Archive</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><filename>Xf100.tgz</filename></entry>
 	      <entry>100 dpi fonts.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xfscl.tgz</filename></entry>
 	      <entry>Speedo and Type1 fonts.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xfnon.tgz</filename></entry>
 	      <entry>Japanese, Chinese, and other non-english
 		fonts.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xfcyr.tgz</filename></entry>
 	      <entry>Cyrillic fonts.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>Unlike the X servers described above, the archives for the
         following servers are all in the main directory.</para>
 
       <informaltable>
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Archive</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><filename>Xfsrv.tgz</filename></entry>
 	      <entry>The font server.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xnest.tgz</filename></entry>
 	      <entry>A nested server running as a client window on
 		another display.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xprt.tgz</filename></entry>
 	      <entry>The print server.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>Xvfb.tgz</filename></entry>
 	      <entry>The Virtual Framebuffer X server, which renders
 		into memory or an mmapped file.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
 
     <sect2>
       <title>Installing XFree86 Manually</title>
 
       <para>If you do not use sysinstall to install X, you need to perform
         a number of steps:</para>
 
       <procedure>
 	<step>
 	  <para>Create the directories and unpack the required
 	    archives.</para>
 	</step>
 
 	<step>
 	  <para>Choose and install an X server.</para>
 	</step>
 
 	<step>
 	  <para>Set up the environment to be able to access X.</para>
 	</step>
 
 	<step>
 	  <para>Find a virtual terminal in which to run X.</para>
 	</step>
 
 	<step>
 	  <para>Configure X for your hardware.</para>
 	</step>
       </procedure>
 
       <para>This sounds like a lot of work, but if you approach it
 	methodically, it is not too bad.  In the rest of this section,
 	we will look at each step in turn.</para>
 
       <sect3>
 	<title>Unpacking the Archives</title>
 
 	<para>You must unpack the archives as root, since a number of
 	  the executables are set-user-id (they run as root even when
 	  started by other users).  If you unpack the server as an
 	  ordinary user, it may abort when you try to run it.  You must
 	  also use a umask value of 022 (permissions rwxr-xr-x), because
 	  the X server requires special permissions.</para>
 
 	<screen>&prompt.user; <userinput>su</userinput>
 Password:
 &prompt.root; <userinput>umask 022</userinput></screen>
 
 	<para>If you do not have enough space in the
 	  <filename>/usr</filename> file system, create a directory on
 	  another partition and symlink it to /usr.  For example, if you
 	  have a file system <filename>/home</filename>  with adequate
 	  space, you could do:</para>
 
 	<screen>&prompt.root; <userinput>cd /home</userinput>
 &prompt.root; <userinput>mkdir X11R6</userinput>
 &prompt.root; <userinput>ln -s /home/X11R6 /usr/X11R6</userinput></screen>
 
 	<para>Next, decide which archives you want to install.  For a
 	  minimal installation, choose <filename>Xbin.tgz</filename>,
 	  <filename>Xfnts.tgz</filename>, <filename>Xlib.tgz</filename>,
 	  and <filename>Xcfg.tgz</filename>.  If you have already
 	  configured X for your hardware, you can omit
 	  <filename>Xcfg.tgz</filename>.</para>
 
 	<para>If you are using sh, unpack like this:</para>
 
 	<screen>&prompt.root; <userinput>mkdir -p /usr/X11R6</userinput>
 &prompt.root; <userinput>cd /usr/X11R6</userinput>
 &prompt.root; <userinput>for i in bin fnts lib cfg; do</userinput>
 &prompt.root; <userinput>  tar xzf X$i.tgz</userinput>
 &prompt.root; <userinput>done</userinput></screen>
 
 	<para>If you are using csh, enter:</para>
 
 	<screen>&prompt.root; <userinput>mkdir -p /usr/X11R6</userinput>
 &prompt.root; <userinput>cd /usr/X11R6</userinput>
 &prompt.root; <userinput>foreach i (bin fnts lib cfg)</userinput>
 <prompt>?</prompt> <userinput>  tar xzf X$i.tgz</userinput>
 <prompt>?</prompt> <userinput>end</userinput></screen>
       </sect3>
 
       <sect3>
 	<title>Installing the Server</title>
 
 	<para>Choose a server archive corresponding to your VGA board.
 	  If the table in the section above does not give you enough
 	  information, check  the  server  man  pages,
 	  <filename>/usr/X11R6/man/man1/XF86_*</filename>, which list
 	  the VGA chipsets supported by each server.  For example, if
 	  you have an ET4000 based board you will use the
 	  <filename>XF86_SVGA</filename> server.  In this case you
 	  would enter:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/X11R6</userinput>
 &prompt.root; <userinput>tar xzf XSVGA.tgz [substitute your server name here]</userinput></screen>
       </sect3>
 
       <sect3>
 	<title>Setting up the environment</title>
 
 	<para>Next, you may wish to create a symbolic link
 	  <filename>/usr/X11/bin/X</filename> that points to the server
 	  that matches your video board.  In this example, it is the
 	  <filename>XF86_SVGA</filename> server:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/X11R6/bin</userinput>
 &prompt.root; <userinput>rm X</userinput>
 &prompt.root; <userinput>ln -s XF86_SVGA X</userinput></screen>
 
 	<para>X needs this symbolic link in order to be able to work
 	  correctly, but you have the option of setting it when you run
 	  <filename>xf86config</filename> &ndash; see below.</para>
 
 	<para>Next, check that the directory
 	  <filename>/usr/X11R6/bin</filename> is in the default path for
 	  sh in <filename>/etc/profile</filename> and for csh in
 	  <filename>/etc/csh.login</filename>, and add it if it is not.
 	  It is best to do this with an editor, but if you want to take
 	  a shortcut, you can enter:</para>
 
 	<screen>&prompt.root; <userinput>echo 'PATH=$PATH:/usr/X11R6/bin' &gt;&gt;/etc/profile</userinput></screen>
 
 	<para>or:</para>
 	  
 	<screen>&prompt.root; <userinput>echo 'set path = ($path /usr/X11R6/bin)' &gt;&gt;/etc/csh.login</userinput></screen>
 
 	<para>Alternatively, make sure everybody who uses X puts
 	  <filename>/usr/X11R6/bin</filename> in their shell's
 	  <envar>PATH</envar> variable.</para>
 
 	<para>Next, invoke ldconfig to put the shared libraries in
 	  <filename>ld.so</filename>'s cache:</para>
 
 	<screen>&prompt.root; <userinput>ldconfig -m /usr/X11R6/lib</userinput></screen>
 
 	<para>You can omit invoking <command>ldconfig</command> if you
 	  plan to reboot before using X.</para>
 
 	<para>You do not need to uncompress the font files, but if you
 	  do, you must  run <command>mkfontdir</command> in the
 	  corresponding font directory, otherwise your server will abort
 	  with the message <quote>could not open default font
 	  `fixed'</quote>.</para>
       </sect3>
 
       <sect3>
 	<title>Assigning a virtual terminal to X</title>
 
 	<para>Next, make sure you have a spare virtual console which is
 	  running a getty.  First check how many virtual consoles you
 	  have:</para>
 
 	<screen>&prompt.root; <userinput>dmesg | grep virtual</userinput>
 sc0: VGA color &lt;16 virtual consoles, flags=0x0&gt;</screen>
 
 	<para>Then check <filename>/etc/ttys</filename> to make sure
 	  there is at least one virtual terminal (ttyvxx device) which
 	  does not have a getty enabled.  Look for the keyword
 	  <literal>off</literal>:</para>
 
 	<screen>&prompt.root; <userinput>grep ttyv /etc/ttys</userinput>
 ttyv0  "/usr/libexec/getty Pc" cons25  on secure
 ttyv1  "/usr/libexec/getty Pc" cons25  on secure
 ttyv2  "/usr/libexec/getty Pc" cons25  on secure
 ttyv3  "/usr/libexec/getty Pc" cons25  off secure</screen>
 
 	<para>In this case, <filename>/dev/ttyv3</filename> is
 	  available, if your kernel has least 4 VTs.  If not, either
 	  disable a getty in <filename>/etc/ttys</filename> by
 	  changing on to off, or build another kernel with more virtual
 	  terminals.</para>
       </sect3>
 
       <sect3>
 	<title>Configuring X for Your Hardware</title>
 
 	<para>After installing the X software, you will need to
 	  customize the file <filename>XF86Config</filename>, which
 	  tells the X server about your hardware and how you want to
 	  run it.</para>
 
 	<para>In order to set up <filename>XF86Config</filename>, you
 	  will need the following hardware information:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>Your mouse type, the bit rate if it is a serial mouse,
 	      and the name of the device to which it is connected.  This
 	      will typically be <filename>/dev/ttyd0</filename> or
 	      <filename>/dev/ttyd1</filename> for a serial mouse,
 	      <filename>/dev/psm0</filename> for a PS/2 mouse, or
 	      <filename>/dev/mse0</filename> for a bus mouse.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The type of the video board and the amount of display
 	      memory.  If it is a no-name board, establish what VGA chip
 	      set it uses.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The parameters of your monitor; vertical and
 	      horizontal frequency.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Identifying the hardware</title>
 
 	<para>How do you decide what your hardware is?  The manufacturer
 	  should tell you, but very often the information you get about
 	  your display board and monitor is pitiful; <quote>Super VGA
 	  board with 76 Hz refresh rate and 16,777,216 colors</quote>.
 	  This tells you the maximum pixel depth (24 bits &ndash; - the
 	  number of colors is 2(pixel depth)), but it doesn't tell you
 	  anything else about the display board.</para>
 
 	<para>As we will see later, the real parameters you need to know
 	  are the maximum horizontal frequency, the dot clock range, the
 	  chipset and the amount of display memory.</para>
 
 	<para>You could be unlucky trying to get some of this
 	  information, but you can get some with the
 	  <command>SuperProbe</command> program.  It should always be
 	  able to tell you the chipset and the amount of memory on
 	  board.</para>
 
 	<para>Occasionally <command>SuperProbe</command> can crash your
 	  system.  Make sure you are not doing anything important when
 	  you run it.  Running SuperProbe looks like this:</para>
 
 	<screen>&prompt.root; <userinput>SuperProbe</userinput>
 (warnings and acknowledgments omitted)
 First video: Super-VGA
         Chipset: Tseng ET4000 (Port Probed)
         Memory:  1024 Kbytes
         RAMDAC:  Generic 8-bit pseudo-color DAC
                  (with 6-bit wide lookup tables (or in 6-bit mode))</screen>
 
 	<para><command>SuperProbe</command> is very finicky about
 	  running at all, and you will often get messages like:</para>
 
 	<screen>SuperProbe: Cannot be run while an X server is running
 SuperProbe: If an X server is not running, unset $DISPLAY and try again
 SuperProbe: Cannot open video</screen>
 
 	<para>In other words, even if no X server is running,
 	  <command>SuperProbe</command> will not work if you have the
 	  environment variable <envar>DISPLAY</envar> set.  How do you
 	  unset it?  With Bourne-style shells, you enter:</para>
 
 	<screen>&prompt.root; <userinput>unset DISPLAY</userinput></screen>
 
 	<para>In the C shell, you enter:</para>
 
 	<screen>&prompt.root; <userinput>unsetenv DISPLAY</userinput></screen>
       </sect3>
 
       <sect3>
 	<title>Running <command>xf86config</command></title>
 
 	<para>The easy way to create your configuration file is with one
 	  of the utilities <command>xf86config</command> (note the lower
 	  case name) or <command>XF86Setup</command>.  Both lead you
 	  through the configuration step by step.
 	  <command>xf86config</command> runs in character mode, while
 	  <command>XF86Setup</command> runs in a graphical mode.
 	  <command>XF86Setup</command> can have problems with unusual
 	  hardware, so I personally prefer
 	  <command>xf86config</command>.</para>
 
 	<para>You can also use sysinstall, but this does not change
 	  much; <application>sysinstall</application> just starts
 	  <command>xf86config</command> for you, and it is easier to
 	  start it directly.  In this section, we will use an example to
 	  illustrate configuration via <command>xf86config</command>.
 	  We are installing X for an ancient Diamond SpeedStar with 1 MB
 	  of display memory, a Logitech MouseMan mouse, and an  ADI
 	  MicroScan 5AP monitor.  The mouse is connected to the system
 	  via the first serial port,
 	  <filename>/dev/ttyd0</filename>.</para>
 
 	<para>To run <command>xf86config</command>, type in the name.  If
 	  <filename>/usr/X11R6/bin</filename> is included in your
 	  <envar>PATH</envar> environment variable, you just need to type
 	  <command>xf86config</command>.  If it is not, you need to type
 	  out the full path to <command>xf86config</command>, like
 	  so:</para>
 
 	<screen>&prompt.root; <userinput>/usr/X11R6/bin/xf86config</userinput></screen>
 
 	<para>This program will create a basic
 	  <filename>XF86Config</filename>file, based on menu selections
 	  you make.</para>
 
 	<para>The <filename>XF86Config</filename> file usually resides
 	  in <filename>/usr/X11R6/lib/X11</filename> or
 	  <filename>/etc</filename>.  A sample
 	  <filename>XF86Config</filename> file is supplied with XFree86;
 	  it is configured for a standard VGA card and monitor with
 	  640x480 resolution. This program will ask for a pathname when
 	  it is ready to write the file.</para>
 
 	<para>You can either take the sample
 	  <filename>XF86Config</filename> as a base and edit it for your
 	  configuration, or let this program produce a base
 	  <filename>XF86Config</filename> file for your configuration
 	  and fine-tune it.  Refer to
 	  <filename>/usr/X11R6/lib/X11/doc/README.Config</filename> for
 	  a detailed overview of the configuration process.</para>
 
 	<para>For accelerated servers (including accelerated drivers in
 	  the SVGA server), there are many chipset and card-specific
 	  options and settings.  This program does not know about these.
 	  On some configurations some of these settings must be
 	  specified.  Refer to the server man pages and chipset-specific
 	  READMEs.</para>
 
 	<para>Before continuing with this program, make sure you know
 	  the chipset and amount of video memory on your video card.
 	  <command>SuperProbe</command> can help with this. It is also
 	  helpful if you know what server you want to run.</para>
 
 	<screen>Press enter to continue, or ctrl-c to abort. ENTER
 
 First specify a mouse protocol type. Choose one from the following list:
 
  1.  Microsoft compatible (2-button protocol)
  2.  Mouse Systems (3-button protocol)
  3.  Bus Mouse
  4.  PS/2 Mouse
  5.  Logitech Mouse (serial, old type, Logitech protocol)
  6.  Logitech MouseMan (Microsoft compatible)
  7.  MM Series
  8.  MM HitTablet
  9.  Microsoft IntelliMouse</screen>
 
 	<para>If you have a two-button mouse, it is most likely of type
 	  1, and if you have a three-button mouse, it can probably
 	  support both protocol 1 and 2.  There are two main varieties
 	  of the latter type; mice with a switch to select the protocol,
 	  and mice that default to 1 and require a button to be held at
 	  boot-time to select protocol 2.  Some mice can be convinced to
 	  do 2 by sending a special sequence to the serial port (see the
 	  ClearDTR/ClearRTS options).</para>
 
 	<screen>Enter a protocol number: 6              Logitech MouseMan
 
 You have selected a Logitech MouseMan type mouse. You might want to enable
 ChordMiddle which could cause the third button to work.
 
 Please answer the following question with either 'y' or 'n'.
 Do you want to enable ChordMiddle? n</screen>
 
 	<para>You definitely want to enable the third button on your
 	  mouse, since many X clients use it.  With a genuine Logitech
 	  mouse, however, you don't need to enable
 	  <literal>ChordMiddle</literal> in order to use the button.  If
 	  you find that the third button does not work when you start X,
 	  you can enable <literal>ChordMiddle</literal> by editing the
 	  configuration file &ndash; it is much easier and less
 	  error-prone than re-running <command>XF86Setup</command>.</para>
 
 	<para>Continuing through the setup:</para>
 
 	<screen>If your mouse has only two buttons, it is recommended that you enable Emulate3Buttons.
 
 Please answer the following question with either 'y' or 'n'.
 Do you want to enable Emulate3Buttons? n
 
 Now give the full device name that the mouse is connected to, for example
 /dev/tty00. Just pressing enter will use the default, /dev/mouse.
 
 Mouse device: /dev/ttyd1</screen>
 
 	<para>Be very careful about this entry.  You must specify the
 	  correct name for the device to which the mouse is connected.
 	  <command>xf86config</command> is not specific to FreeBSD, and
 	  the suggested example is just plain wrong for FreeBSD.  Use
 	  the names <filename>/dev/ttyd0</filename> through
 	  <filename>/dev/ttyd3</filename> for serial  mice,
 	  <filename>/dev/psm0</filename> for PS/2  mice or
 	  <filename>/dev/mse0</filename> for a bus mouse.</para>
 
 	<para>Continuing, we see:</para>
 
 	<screen>Beginning with XFree86 3.1.2D, you can use the new X11R6.1
 XKEYBOARD extension to manage the keyboard layout. If you answer 'n' to the
 following question, the server will use the old method, and you have to
 adjust your keyboard layout with xmodmap.
 
 Please answer the following question with either 'y' or 'n'.
 Do you want to use XKB? y
 
 The following dialogue will allow you to select from a list of already
 preconfigured keymaps. If you don't find a suitable keymap in the list,
 the program will try to combine a keymap from additional information you
 are asked then. Such a keymap is by default untested and may require
 manual tuning. Please report success or required changes for such a
 keymap to XFREE86@XFREE86.ORG for addition to the list of preconfigured
 keymaps in the future.
 
 Press enter to continue, or ctrl-c to abort.
 
 List of preconfigured keymaps:
 
   1  Standard 101-key, US encoding
   2  Microsoft Natural, US encoding
   3  KeyTronic FlexPro, US encoding
   4  Standard 101-key, US encoding with ISO9995-3 extensions
   5  Standard 101-key, German encoding
   6  Standard 101-key, French encoding
   7  Standard 101-key, Thai encoding
   8  Standard 101-key, Swiss/German encoding
   9  Standard 101-key, Swiss/French encoding
  10  None of the above
 
 Enter a number to choose the keymap.
 
 1                                       Choose the standard US keyboard</screen>
 
 	<para>Now we want to set the specifications of the monitor.  The
 	  two critical parameters are the vertical refresh rate, which
 	  is the rate at which the whole screen is refreshed, and
 	  most importantly the horizontal sync rate, which is the rate
 	  at which scanlines are displayed.</para>
 
 	<para>The valid range for horizontal sync and vertical sync
 	  should be documented in the manual of your monitor.  If in
 	  doubt, check the monitor database
 	  <filename>/usr/X11R6/lib/X11/doc/Monitors</filename> to see if
 	  your monitor is there.</para>
 
 	<screen>Press enter to continue, or ctrl-c to abort. ENTER
 
 You must indicate the horizontal sync range of your monitor. You can either
 select one of the predefined ranges below that correspond to industry-
 standard monitor types, or give a specific range.
 
 It is VERY IMPORTANT that you do not specify a monitor type with a horizontal
 sync range that is beyond the capabilities of your monitor. If in doubt,
 choose a conservative setting.
 
     hsync in kHz; monitor type with characteristic modes
  1  31.5; Standard VGA, 640x480 @@ 60 Hz
  2  31.5 - 35.1; Super VGA, 800x600 @@ 56 Hz
  3  31.5, 35.5; 8514 Compatible, 1024x768 @@ 87 Hz interlaced (no 800x600)
  4  31.5, 35.15, 35.5; Super VGA, 1024x768 @@ 87 Hz interlaced, 800x600 @@ 56 Hz
  5  31.5 - 37.9; Extended Super VGA, 800x600 @@ 60 Hz, 640x480 @@ 72 Hz
  6  31.5 - 48.5; Non-Interlaced SVGA, 1024x768 @@ 60 Hz, 800x600 @@ 72 Hz
  7  31.5 - 57.0; High Frequency SVGA, 1024x768 @@ 70 Hz
  8  31.5 - 64.3; Monitor that can do 1280x1024 @@ 60 Hz
  9  31.5 - 79.0; Monitor that can do 1280x1024 @@ 74 Hz
 10  31.5 - 82.0; Monitor that can do 1280x1024 @@ 76 Hz
 11  Enter your own horizontal sync range
 
 Enter your choice (1-11):</screen>
 
 	<para>Unfortunately, our monitor is not mentioned in the file
 	  <filename>/usr/X11R6/lib/X11/doc/Monitors</filename>,  but by
 	  chance the manual does specify the frequency range in the
 	  Technical Data section.  The horizontal frequency range is
 	  from 30 to 64 kHz, and the vertical frequency range is from
 	  50 to 100 Hz.  The horizontal frequency range is almost
 	  exactly covered by choice 8, but  that setting threatens to go
 	  0.3 kHz higher in frequency than the technical data state.  Do
 	  you want to risk it?  Doing so will most likely not be a
 	  problem, since it is unlikely that the monitor will die at
 	  such a small deviation from the specs, and it is also unlikely
 	  that your <filename>XF86Config</filename> will actually
 	  generate a horizontal frequency between 64.0 and 64.3 kHz.
 	  However, there is no need to take even this slight risk.  Just
 	  specify the real values:</para>
 
 	<screen>Enter your choice (1-11): 11
 
 Please enter the horizontal sync range of your monitor, in the format used
 in the table of monitor types above. You can either specify one or more
 continuous ranges (e.g. 15-25, 30-50), or one or more fixed sync
 frequencies.
 
 Horizontal sync range: 30-64</screen>
 
 	<para>Next, we select the vertical frequency range:</para>
 
 	<screen>You must indicate the vertical sync range of your monitor.
 You can either select one of the predefined ranges below that correspond
 to industry-standard monitor types, or give a specific range.  For
 interlaced modes, the number that counts is the high one (e.g., 87 Hz
 rather than 43 Hz).
 
  1  50-70
  2  50-90
  3  50-100
  4  40-150
  5  Enter your own vertical sync range
 
 Enter your choice: 3                         exactly the range of the monitor</screen>
 
 	<para>The next step is to specify identification strings.  You
 	  can think out names if you want, but unless you are juggling a
 	  lot of different hardware, you can let
 	  <command>xf86config</command> do it for you:</para>
 
 	<screen>You must now enter a few identification/description strings,
 namely an identifier, a vendor name, and a model name. Just pressing enter
 will fill in default names.
 
 The strings are free-form, spaces are allowed.
 Enter an identifier for your monitor definition: ENTER
 Enter the vendor name of your monitor:  ENTER
 Enter the model name of your monitor:  ENTER</screen>
 
 	<para>Next comes the choice of the video board.  We have an
 	  elderly Diamond SpeedStar Plus with an ET4000 chip, and
 	  unknown Ramdac and Clock Chip.  Let's see how we fare:</para>
 
 	<screen>Now we must configure video card specific settings.  At
 this point you can choose to make a selection out of a database of video
 card definitions.  Because there can be variation in Ramdacs and clock
 generators even between cards of the same model, it is not sensible to
 blindly copy the settings (e.g., a Device section).  For this reason,
 after you make a selection, you will still be asked about the components
 of the card, with the settings from the chosen database entry presented as
 a strong hint.
 
 The database entries include information about the chipset, what server to
 run, the Ramdac and ClockChip, and comments that will be included in the
 Device section. However, a lot of definitions only hint about what server
 to run (based on the chipset the card uses) and are untested.
 
 If you can't find your card in the database, there's nothing to worry about.
 You should only choose a database entry that is exactly the same model as
 your card; choosing one that looks similar is just a bad idea (e.g. a
 GemStone Snail 64 may be as different from a GemStone Snail 64+ in terms of
 hardware as can be).
 
 Do you want to look at the card database? y
   0  2 the Max MAXColor S3 Trio64V+                    S3 Trio64V+
   1  928Movie                                          S3 928
   2  AGX (generic)                                     AGX-014/15/16
   3  ALG-5434(E)                                       CL-GD5434
   4  ASUS 3Dexplorer                                   RIVA128
   5  ASUS PCI-AV264CT                                  ATI-Mach64
   6  ASUS PCI-V264CT                                   ATI-Mach64
   7  ASUS Video Magic PCI V864                         S3 864
   8  ASUS Video Magic PCI VT64                         S3 Trio64
   9  AT25                                              Alliance AT3D
  10  AT3D                                              Alliance AT3D
  11  ATI 3D Pro Turbo                                  ATI-Mach64
  12  ATI 3D Xpression                                  ATI-Mach64
  13  ATI 3D Xpression+ PC2TV                           ATI-Mach64
  14  ATI 8514 Ultra (no VGA)                           ATI-Mach8
  15  ATI All-in-Wonder                                 ATI-Mach64
  16  ATI Graphics Pro Turbo                            ATI-Mach64
  17  ATI Graphics Pro Turbo 1600                       ATI-Mach64
 
 Enter a number to choose the corresponding card definition.
 Press enter for the next page, q to continue configuration.
 ENTER</screen>
 
 	<para>Dozens of board definitions come in alphabetic order.
 	  Finally we see:</para>
 
 	<screen>108  DSV3325                                           S3 ViRGE
 109  DSV3326                                           S3 Trio64V+
 110  DataExpert DSV3325                                S3 ViRGE
 111  DataExpert DSV3365                                S3 Trio64V+
 112  Dell S3 805                                       S3 801/805
 113  Dell onboard ET4000                               ET4000
 114  Diamond Edge 3D                                   nv1
 115  Diamond Multimedia Stealth 3D 2000                S3 ViRGE
 116  Diamond Multimedia Stealth 3D 2000 PRO            S3 ViRGE/DX
 117  Diamond SpeedStar (Plus)                          ET4000
 118  Diamond SpeedStar 24                              ET4000
 119  Diamond SpeedStar 24X (not fully supported)       WD90C31
 120  Diamond SpeedStar 64                              CL-GD5434
 121  Diamond SpeedStar HiColor                         ET4000
 122  Diamond SpeedStar Pro (not SE)                    CL-GD5426/28
 123  Diamond SpeedStar Pro 1100                        CL-GD5420/2/4/6/8/9
 124  Diamond SpeedStar Pro SE (CL-GD5430/5434)         CL-GD5430/5434
 125  Diamond SpeedStar64 Graphics 2000/2200            CL-GD5434
 
 Enter a number to choose the corresponding card definition.
 Press enter for the next page, q to continue configuration.
 
 117
 
 Your selected card definition:
 
 Identifier: Diamond SpeedStar (Plus)
 Chipset:    ET4000
 Server:     XF86_SVGA
 
 Press enter to continue, or ctrl-c to abort.ENTER
 
 Now you must determine which server to run.  Refer to the man pages and
 other documentation.  The following servers are available (they may not
 all be installed on your system):
 
  1  The XF86_Mono server. This a monochrome server that should work on any
     VGA-compatible card, in 640x480 (more on some SVGA chipsets).
  2  The XF86_VGA16 server. This is a 16-color VGA server that should work on
     any VGA-compatible card.
  3  The XF86_SVGA server. This is a 256 color SVGA server that supports
     a number of SVGA chipsets. On some chipsets it is accelerated or
     supports higher color depths.
  4  The accelerated servers. These include XF86_S3, XF86_Mach32, XF86_Mach8,
     XF86_8514, XF86_P9000, XF86_AGX, XF86_W32, XF86_Mach64, XF86_I128 and
     XF86_S3V.
 
 These four server types correspond to the four different "Screen" sections in
 XF86Config (vga2, vga16, svga, accel).
 
  5  Choose the server from the card definition, XF86_SVGA.
 
 Which one of these screen types do you intend to run by default (1-5)?</screen>
 
 	<para>The system already chose XF86_SVGA for us.  Do we want to
 	  change?  We would need a good reason.  In this case, we do not
 	  have a reason, so we will keep the server from the card
 	  definition:</para>
 
 	<screen>Which one of these screen types do you intend to run by default (1-5)? 5
 
 The server to run is selected by changing the symbolic link 'X'. For example,
 the SVGA server.
 
 Please answer the following question with either 'y' or 'n'.
 Do you want me to set the symbolic link? y</screen>
 
 	<para>All the programs that start X (xinit, startx, and xdm)
 	  start a program <filename>/usr/X11R6/bin/X</filename>.  This
 	  symbolic link makes <filename>/usr/X11R6/bin/X</filename>
 	  point to your X server.  If you don't have a link, you will
 	  not be able to start X.</para>
 
 	<screen>Now you must give information about your video card.  This
 will be used for the "Device" section of your video card in XF86Config.
 
 You must indicate how much video memory you have. It is probably a good
 idea to use the same approximate amount as that detected by the server you
 intend to use. If you encounter problems that are due to the used server
 not supporting the amount memory you have (e.g. ATI Mach64 is limited to
 1024K with the SVGA server), specify the maximum amount supported by the
 server.
 
 How much video memory do you have on your video card:
 
  1  256K
  2  512K
  3  1024K
  4  2048K
  5  4096K
  6  Other
 
 Enter your choice: 3
 
 You must now enter a few identification/description strings, namely an
 identifier, a vendor name, and a model name. Just pressing enter will fill
 in default names (possibly from a card definition).
 
 Your card definition is Diamond SpeedStar (Plus).
 
 The strings are free-form, spaces are allowed.
 Enter an identifier for your video card definition: ENTER
 You can simply press enter here if you have a generic card, or want to
 describe your card with one string.
 Enter the vendor name of your video card:  ENTER
 Enter the model (board) name of your video card:  ENTER
 
 Especially for accelerated servers, Ramdac, Dacspeed and ClockChip settings
 or special options may be required in the Device section.
 
 The RAMDAC setting only applies to the S3, AGX, W32 servers, and some
 drivers in the SVGA servers. Some RAMDAC's are auto-detected by the server.
 The detection of a RAMDAC is forced by using a Ramdac "identifier" line in
 the Device section. The identifiers are shown at the right of the following
 table of RAMDAC types:
 
   1  AT&amp;T 20C490 (S3 and AGX servers, ARK driver)                att20c490
   2  AT&amp;T 20C498/21C498/22C498 (S3, autodetected)                att20c498
   3  AT&amp;T 20C409/20C499 (S3, autodetected)                       att20c409
   4  AT&amp;T 20C505 (S3)                                            att20c505
   5  BrookTree BT481 (AGX)                                       bt481
   6  BrookTree BT482 (AGX)                                       bt482
   7  BrookTree BT485/9485 (S3)                                   bt485
   8  Sierra SC15025 (S3, AGX)                                    sc15025
   9  S3 GenDAC (86C708) (autodetected)                           s3gendac
  10  S3 SDAC (86C716) (autodetected)                             s3_sdac
  11  STG-1700 (S3, autodetected)                                 stg1700
  12  STG-1703 (S3, autodetected)                                 stg1703
 
 
 Enter a number to choose the corresponding RAMDAC.
 Press enter for the next page, q to quit without selection of a RAMDAC.
 
 
 q                                  We don't need this
 
 
 A Clockchip line in the Device section forces the detection of a
 programmable clock device. With a clockchip enabled, any required
 clock can be programmed without requiring probing of clocks or a
 Clocks line. Most cards don't have a programmable clock chip.
 Choose from the following list:
 
  1  Chrontel 8391                                               ch8391
  2  ICD2061A and compatibles (ICS9161A, DCS2824)                icd2061a
  3  ICS2595                                                     ics2595
  4  ICS5342 (similar to SDAC, but not completely compatible)    ics5342
  5  ICS5341                                                     ics5341
  6  S3 GenDAC (86C708) and ICS5300 (autodetected)               s3gendac
  7  S3 SDAC (86C716)                                            s3_sdac
  8  STG 1703 (autodetected)                                     stg1703
  9  Sierra SC11412                                              sc11412
 10  TI 3025 (autodetected)                                      ti3025
 11  TI 3026 (autodetected)                                      ti3026
 12  IBM RGB 51x/52x (autodetected)                              ibm_rgb5xx
 
 Just press enter if you don't want a Clockchip setting.
 What Clockchip setting do you want (1-12)? ENTER
 
 For most configurations, a Clocks line is useful since it prevents the slow
 and nasty sounding clock probing at server start-up. Probed clocks are
 displayed at server startup, along with other server and hardware
 configuration info. You can save this information in a file by running
 imprecise; some clocks may be slightly too high (varies per run).
 
 At this point I can run X -probeonly, and try to extract the clock information
 from the output. It is recommended that you do this yourself and add a clocks
 line (note that the list of clocks may be split over multiple Clocks lines) to
 your Device section afterwards. Be aware that a clocks line is not
 appropriate for drivers that have a fixed set of clocks and don't probe by
 default (e.g. Cirrus). Also, for the P9000 server you must simply specify
 clocks line that matches the modes you want to use.  For the S3 server with
 a programmable clock chip you need a 'ClockChip' line and no Clocks line.
 
 You must be root to be able to run X -probeonly now.
 
 Do you want me to run 'X -probeonly' now?</screen>
 
 	<para>This last question is worth thinking about.  You should
 	  run  X  -probeonly at some point, but it requires some extra
 	  work.  We'll take the recommendation and try it later.</para>
 
 	<screen>Do you want me to run 'X -probeonly' now? n
 
 For each depth, a list of modes (resolutions) is defined. The default
 resolution that the server will start-up with will be the first listed
 mode that can be supported by the monitor and card.
 Currently it is set to:
 
 "640x480" "800x600" "1024x768" for 8bpp
 "640x480" "800x600" for 16bpp
 "640x480" for 24bpp
 "640x400" for 32bpp
 
 Note that 16, 24 and 32bpp are only supported on a few configurations.
 Modes that cannot be supported due to monitor or clock constraints will
 be automatically skipped by the server.
 
  1  Change the modes for 8pp (256 colors)
  2  Change the modes for 16bpp (32K/64K colors)
  3  Change the modes for 24bpp (24-bit color, packed pixel)
  4  Change the modes for 32bpp (24-bit color)
  5  The modes are OK, continue.
 
 Enter your choice: 5     accept the defaults
 
 You can have a virtual screen (desktop), which is screen area that is larger
 than the physical screen and which is panned by moving the mouse to the edge
 of the screen. If you don't want virtual desktop at a certain resolution,
 you cannot have modes listed that are larger. Each color depth can have a
 differently-sized virtual screen
 
 Please answer the following question with either 'y' or 'n'.
 Do you want a virtual screen that is larger than the physical screen? n</screen>
 
 	<para>It is difficult to decide whether you want a virtual
 	  screen larger than the physical screen.  I find it extremely
 	  disturbing, so I suggest you answer n.  You might find it
 	  useful, especially if your highest resolution is small.</para>
 
 	<para>Now the configuration is complete, and
 	  <application>sysinstall</application> just need to write the
 	  configuration file:</para>
 
 	<screen>I am going to write the XF86Config file now.  Make sure
 you don't accidently overwrite a previously configured one.
 
 Shall I write it to /etc/XF86Config? y
 
 File has been written. Take a look at it before running 'startx'. Note that
 the XF86Config file must be in one of the directories searched by the server
 (e.g. /usr/X11R6/lib/X11) in order to be used. Within the server press
 ctrl, alt and '+' simultaneously to cycle video resolutions. Pressing ctrl,
 alt and backspace simultaneously immediately exits the server (use if
 the monitor doesn't sync for a particular mode).
 
 For further configuration, refer to /usr/X11R6/lib/X11/doc/README.Config.</screen>
 
 	<para>Once you have completed this configuration, you are ready to
 	  start X.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="x11-4">
     <title>XFree86 4.X Configuration</title>
       
     <para><emphasis>Contributed by &a.cshumway;, July 2001.</emphasis>
     </para>
 
     <sect2>
       <title>Introduction</title>
       
       <para>This chapter will introduce the steps necessary to install
 	and configure the XFree86 X Windows System under FreeBSD.
 	Once the server is installed and configured properly. The user 
 	can read <xref linkend="x11-wm"> to setup their desktop
 	environment.</para>
 
       <indexterm><primary>XFree86 4.X</primary></indexterm>
       <indexterm><primary>XFree86</primary></indexterm>
 
     </sect2>
 
     <sect2>
       <title>Before You Start</title>
 
       <para>Before the user is to start configuration of XFree86-4,
 	the the following information will need to be known about the
 	target system:</para>
 
       <itemizedlist>
 	<listitem><para>Monitor specifications</para></listitem>
 	<listitem><para>Video Adapter chipset</para></listitem>
 	<listitem><para>Video Adapter memory</para></listitem>
       </itemizedlist>
 
       <indexterm><primary>horizontal scan rate</primary></indexterm>
       <indexterm><primary>vertical scan rate</primary></indexterm>
 
       <para>The specifications for the target system's monitor are
 	used by XFree86 to determine the resolution and refresh rate
 	to run at.  These specifications can usually be obtained from
 	the documentation that came with the target system's monitor 
 	or from the manufacturer's website.  There are two ranges of
 	numbers that are needed, the horizontal scan rate and the 
 	vertical synchronization rate.</para>
 
       <para>The video adapter's chipset defines what driver module
 	XFree86 uses to talk to the graphics hardware.  With most
 	chipsets, this can be automatically determined, but it is still
 	useful to know in case the automatic detection doesn't work
 	correctly.</para>
 
       <para>Video memory on the graphic adapter determines the
 	resolution and color depth the target system can run at.  This
 	is important to know so the user knows the limitations of the
 	target system.</para>
 
     </sect2>
 
     <sect2>
       <title>Installing XFree86 4.X software</title>
 
       <para>XFree86 4 can be installed using the FreeBSD ports system
 	or using &man.pkg.add.1;.  If the user is building XFree86-4
 	from source and has USA_RESIDENT set in
 	<filename>/etc/make.conf</filename>, the user may first have to
 	fetch <filename>Wraphelp.c</filename> if XDM-AUTHORIZATION-1
 	support is desired.  This file is to be placed in the port's
         <filename>files/</filename> sub-directory before the port is
 	built.</para>
 
     </sect2>
 
     <sect2>
       <title>Configuring XFree86 4.X</title>
 
       <para>Configuration of XFree86 4.1 is a several step process.
 	The first step is to build an initial configuration file with
 	the configure option to XFree86.  As the super user, simply run:</para>
 
       <screen>&prompt.root; XFree86 -configure</screen>
 
       <para>This will generate a skeleton XFree86 configuration file
 	in the current working directory called
 	<filename>XF86Config.new</filename>.  The XFree86 program will
 	attempt to probe the graphics hardware on the system and will
 	write a configuration file to load the proper drivers for the
 	detected hardware on the target system.</para>
 
       <para>The next step is to test the currently existing
 	configuration to verify that XFree86 can work with the graphics
 	hardware on the target system.  To preform this task, the user
 	needs to run:</para>
 
       <screen>&prompt.root; XFree86 -xf86config XF86Config.new</screen>
 
       <para>If the user is presented with a black and grey grid and an
 	X mouse cursor, then the configuration was successful.  To exit
 	the test, just press ctrl, alt and backspace simultaneously.</para>
 
       <indexterm><primary>XFree86 4 Tuning</primary></indexterm>
 
       <para>Next, the user needs to tune the
 	<filename>XF86Config.new</filename> configuration file to their
 	personal taste.  Open up the file in a text editor such as
 	&man.emacs.1; or &man.ee.1;.  The first thing the user will want to
 	do is add the frequencies for the target system's monitor.
 	These are usually expressed as a horizontal and vertical
 	synchronization rate.  These values are added to the
 	<filename>XF86Config.new</filename> file under the "Monitor"
 	section as such:</para>
 
       <programlisting>Section "Monitor"
         Identifier   "Monitor0"
         VendorName   "Monitor Vendor"
         ModelName    "Monitor Model"
         Horizsync    30-107
         VertRefresh  48-120
 EndSection</programlisting>
 
       <para>The <varname>Horizsync</varname> and
 	<varname>VertRefresh</varname> keywords may not exist in the
 	user's configuration file.  If they do not, they need to be
 	added, with the correct horizontal synchronization rate placed
 	after the <varname>Horizsync</varname> keyword and the vertical
 	synchronization rate after the <varname>VertRefresh</varname>
 	keyword.  In the example above the target monitor's rates where
 	entered.</para>
 
       <indexterm><primary>XF86Config</primary></indexterm>
       
       <para>While the <filename>XF86Config.new</filename>
 	configuration file is still open in an editor, next the user
 	needs to select what the default resolution and color depth is
 	desired.  This is defined in the <literal>Screen</literal>
 	section.</para>
       
       <programlisting>Section "Screen"
         Identifier "Screen0"
         Device     "Card0"
         Monitor    "Monitor0"
         DefaultColorDepth 24
         SubSection "Display"
                 Depth     24
                 Modes     "1024x768"
         EndSubSection
 EndSection</programlisting>
 
       <para>The <varname>DefaultColorDepth</varname> keyword describes
 	the color depth the user wishes to run at by default.  This can
 	be overridden with the <command>-bpp</command> command line
 	switch to <citerefentry><refentrytitle>XFree86</refentrytitle>
         <manvolnum>1</manvolnum></citerefentry>.  The Modes keyword describes the
 	resolution the user wishes to run at for the given color depth.
 	In the example above, the default color depth is twenty four
 	bits per pixel.  At this color depth, the accepted resolution is
 	one thousand twenty four pixels by seven hundred and sixty eight
 	pixels.</para>
 
       <para>If a user wants to run at a resolution of one thousand
 	twenty four pixels by seven hundred sixty eight pixels at twenty
 	four bits per pixel, then the user needs to add the
 	<varname>DefaultColorDepth</varname> keyword with the value of
 	twenty four, and add to the <varname>"Display"</varname>
 	subsection with the desired Depth the Modes keyword with the
 	resolution the user wishes to run at.  Note that only VESA
 	standard modes are supported as defined by the target system's
 	graphics hardware.</para>
 
       <para>Finally, the user can write out the configuration file and
 	test it using the test mode given above.  If all is well, then
 	the configuration file needs to be installed in a common
 	location where <citerefentry><refentrytitle>XFree86</refentrytitle>
         <manvolnum>1</manvolnum></citerefentry> can source it in the future.
 	This is typically <filename>/etc/X11/XF86Config</filename> or
 	<filename>/usr/X11R6/etc/X11/XF86Config</filename>.</para>
 
       <screen>&prompt.root; cp XF86Config.new /etc/X11/XF86Config</screen>
 
       <para>Once the configuration file has been placed in a common
 	location, XFree86 can then be used through &man.xdm.1;.  In
 	order to use <citerefentry><refentrytitle>startx</refentrytitle>
         <manvolnum>1</manvolnum></citerefentry> the user will have to install 
         the <filename>X11/wrapper</filename> port.</para>
 
     </sect2>
 
     <sect2>
       <title>Advanced Configuration Topics</title>
       
       <sect3>
 	<title>Configuration with Intel i810 graphics chipsets</title>
 
         <indexterm><primary>Intel i810 graphic chipset</primary></indexterm>
 
 	<para>Configuration with Intel i810 integrated chipsets
 	  requires the agpgart AGP programming interface for XFree86 to
 	  be able to drive the card.  To enable the agpgart programming
 	  interface, the <filename>agp.ko</filename> kernel loadable
 	  module needs to be loaded into the kernel with
 	  &man.kldload.8;.  This can be done automatically with the
 	  &man.loader.8;.  Simply add this line to
 	  <filename>/boot/loader.conf</filename> to have the loader load
 	  agp.ko at boot time:</para>
 
 	<programlisting>agp_load="YES"</programlisting>
 
 	<para>Next, a device node needs to be created for the
 	  programming interface.  To create the agp device node, run
 	  &man.MAKEDEV.8; in the <filename>/dev</filename> directory as
 	  such:</para>
 
 	<screen>&prompt.root; cd /dev
 &prompt.root; sh MAKEDEV agpgart</screen>
 
 	<para>This will allow the user to configure the graphics
 	  hardware as any other graphics board.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="x-fonts">
     <title>Using Fonts in XFree86</title>
 
     <sect2 id="type1">
     <title>Type1 Fonts</title>
     <para>The default fonts that ship with
     <application>XFree86</application> are less than ideal for typical
     desktop publishing applications.  Large presentation fonts show up
     jagged and unprofessional looking and small fonts in Netscape are
     almost completely unintelligible.  However, there are several
     free, high quality Type1 (PostScript) fonts available which 
     can be readily used
     with <application>XFree86</application>, either version 3.X or 
     version 4.X.  For instance, the URW font collection 
     (<filename>/usr/ports/x11-fonts/urwfonts</filename>) includes
     high quality versions of standard type1 fonts (Times Roman, 
     Helvetica, Palatino and others).  The Freefont collection
     (<filename>/usr/ports/x11-fonts/freefont</filename>) includes
     many more fonts, but most of them are intended for use in 
     graphics software such as the Gimp, and are not complete 
     enough to serve as screen fonts.  In addition,
     <application>XFree86</application> can be configured to use
     TrueType fonts with a minimum of effort: see the
     <link linkend="truetype">section on TrueType fonts</link> later.</para>
 
     <para>To install the above Type1 font collections from the ports
 	collection you can run the following commands.</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
       
     <para>And likewise with the freefont or other collections.  To tell the X server
     that these fonts exist, you can add an appropriate line
     to your <filename>XF86Config</filename> file (in
     <filename>/etc/</filename> for <application>XFree86</application>
     version 3, or in <filename>/etc/X11/</filename> for version 4), 
     which reads:</para>
       
 <programlisting>FontPath "/usr/X11R6/lib/X11/fonts/URW/"</programlisting>
 
       <para>Alternatively, at the command line in your X session you can
 	write:</para>
       
 <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/URW</userinput>
 &prompt.user; <userinput>xset fp rehash</userinput></screen>
       
       <para>This will work but will be lost when you log out from this
     session, unless you add it to your startup file
     (<filename>~/.xinitrc</filename> for a normal startx session,
     or <filename>~/.xsession</filename> when logging in through a
     graphical login manager like <application>XDM</application>).  
     A third way is to use the new 
     XftConfig file: see the
     section on <link linkend="antialias">anti-aliasing</link>, later.
     </para>
     </sect2>
 
     <sect2 id="truetype">
     <title>TrueType Fonts</title>
 
     <para><application>XFree86</application> 4.0 has built in support
     for rendering TrueType fonts.  There are two different modules
     that can enable this functionality.  The "freetype" module is used
     in this example because it is more consistent with the other font
     rendering backends. To enable the freetype module just add the
     following line to the module section of your
     <filename>/etc/X11/XF86Config</filename> file.</para>
 
     <programlisting>Load  "freetype"</programlisting>
 
     <para>For <application>XFree86</application> 3.3.X you will need
       to run a separate TrueType font
       server. <application>Xfstt</application> is commonly used for
       this purpose. To install <application>Xfstt</application> on
       your FreeBSD system simply install the port from
       <filename>/usr/ports/x11-servers/Xfstt</filename></para>
 
     <para>You should now make a directory for your TrueType fonts
       (e.g. <filename>/usr/X11R6/lib/X11/fonts/TrueType</filename>)
       and copy all of your TrueType fonts into this directory. Keep in
-      mind that you can not take TrueType fonts directly from a
+      mind that you cannot take TrueType fonts directly from a
       Macintosh; they must be in Unix/DOS/Windows format for use by
       <application>XFree86</application>. Once you have copied the
       files into this directory you need to use
       <application>ttmkfdir</application> to create a
       <filename>fonts.dir</filename> file so that the X font renderer
       knows that you've installed these new files. There is a FreeBSD
       port for <application>ttmkfdir</application> in
       <filename>/usr/ports/x11-fonts/ttmkfdir</filename>.</para>
 <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/TrueType</userinput>
 &prompt.root; <userinput>ttmkfdir > fonts.dir</userinput></screen>
 
     <para>Now you need to add your TrueType directory to your fonts
       path. This is just the same as described above for <link
       linkend="type1">Type1</link> fonts, that is, use
 <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/TrueType</userinput>
 &prompt.user; <userinput>xset fp rehash</userinput></screen>
       or add a FontPath line to the <filename>XF86Config</filename> file.</para>
 
     <para>That's it. Now Netscape, Gimp, StarOffice, and all of your
       other X applications should now recognize your installed
       TrueType fonts. Extremely small fonts (as with text in a high
       resolution display on a web page) and extremely large fonts
       (within StarOffice) will look much better now.</para>
     </sect2>
 
     <sect2 id="antialias">
     <title>Anti-Aliasing your fonts</title>
 
     <para>Starting with version 4.0.2, XFree86 supports anti-aliased
       fonts.  Currently, most software has not been updated to take
       advantage of this new functionality.  However, Qt (the toolkit
       for the KDE desktop) does; so if you are running XFree86 4.0.2
       (or higher), Qt 2.3 (or higher) and KDE, all your KDE/Qt
       applications can be made to use anti-aliased fonts.</para>
 
     <para>To configure anti-aliasing, you need to create (or edit, if
       it already exists) the file
       <filename>/usr/X11R6/lib/X11/XftConfig</filename>.  Several
       advanced things can be done with this file; this section
       describes only the simplest possibilities.</para>
 
      <para>First, you need to tell the X server about the fonts which you
       want anti-aliased. To do that, for each font directory you have
       a line, which looks like this:</para>
       
       <programlisting>dir "/usr/X11R6/lib/X11/Type1"</programlisting>
       
       <para>And likewise for the other font directories (URW, truetype, etc) 
       containing fonts you'd like anti-aliased.  Anti-aliasing makes
       sense only for scalable fonts (basically, Type1 and TrueType) so
       don't include bitmap font directories here.  The
       directories which you included here can now be commented out 
       of your <filename>XF86Config</filename> file.</para>
 
      <para>Next, you may not want to anti-alias normal-sized text.
       (Antialiasing makes borders slightly fuzzy, which makes very
       small text more readable and removes "staircases" from large text,
       but can cause eyestrain if applied to normal text.)  To exclude
       point sizes between 9 and 13 from anti-aliasing, include these
       lines:</para>
       
       <programlisting>match
   any size > 8
   any size < 14
 edit
   antialias = false;</programlisting>
       
       <para>You may also find that the spacing for some monospaced fonts
        gets messed up when you turn on anti-aliasing.  This seems to
        be an issue with KDE, in particular.  One possible fix for this
        is to force the spacing for such fonts to be 100: add the
        following lines:</para>
       
       <programlisting>match any family == "fixed"      edit family =+ "mono";
 match any family == "console"    edit family =+ "mono";</programlisting>
       
       <para>(this aliases the other common names for fixed fonts as "mono"),
        and then add:</para>
       
       <programlisting>match any family == "mono" edit spacing = 100;</programlisting>
       
       <para>Supposing you want to use the Lucidux fonts whenever monospaced 
        fonts are required (these look nice, and don't seem to suffer
        from the spacing problem), you could replace that last line
        with these:</para>
 
       <programlisting>match any family == "mono"       edit family += "LuciduxMono";
 match any family == "Lucidux Mono"      edit family += "LuciduxMono";
 match any family == "LuciduxMono"       edit family =+ "Lucidux Mono";</programlisting> 
 
        <para>(the last lines alias different equivalent family names).</para>
 
        <para>Finally, you want to allow users to add commands to this
         file, via their personal <filename>.xftconfig</filename>
         files.  To do this, add a last line:</para>
 
        <programlisting>includeif  "~/.xftconfig"</programlisting>
  
        <para>That's all; anti-aliasing should be enabled the next
         time you start the X server.  However, note that your programs must
         know how to take advantage of it.  At the present time, the toolkit
         Qt does, so the entire KDE environment can use anti-aliased fonts
         (see <xref linkend="x11-wm-kde2-antialias"> on KDE for
         details); there are patches for gtk+ to do the same,
         so if compiled against such a patched gtk+, the GNOME environment
         and Mozilla can also use anti-aliased fonts.</para>
 
        <para>Anti-aliasing is still new to FreeBSD and XFree86;
         configuring it should get easier with time, and it will soon be
         supported by many more applications.</para>
     </sect2>
   </sect1>
 
   <sect1 id="x-xdm">
     <title>The X Display Manager</title>
     <sect2>
       <title>Overview</title>
       <para>The X Display Manager (XDM) is an optional part of the X
 	Window System that is used for login session management. This is
 	useful for several types of situations, including minimal
 	<quote>X Terminals</quote> (see 
 	<xref linkend="term-x">), desktops, and large network display
 	servers. Since the X Window System is network and protocol
 	independent, there are a wide variety of possible configurations
 	for running X clients and servers on different machines
 	connected by a network. XDM provides a graphical interface for
 	choosing which display server to connect to, and entering
 	authorization information such as a login and password
 	combination.</para>
 
       <para>You may think of XDM as providing the same functionality to
 	the user as the &man.getty.8; utility (see <xref
 	linkend="term-getty"> for details). That is, it performs system
 	logins to the display being connected to and then runs a session
 	manager on behalf of the user (usually an X window manager). XDM
 	then waits for this program to exit, signaling that the user is
 	done and should be logged out of the display. At this point, XDM
 	can display the login and display chooser screens for the next
 	user to login.</para>
     </sect2>
 
     <sect2>
       <title>Using XDM</title>
       <para>The XDM daemon program is located in
 	<filename>/usr/X11R6/bin/xdm</filename>. You can run this
 	program at any time as root and it will start managing the X
 	display on the local machine. If you want XDM to run in the
 	background every time the machine boots up, a convenient way to
 	do this is by adding an entry to <filename>/etc/ttys</filename>.
 	For more information about the format and usage of this file,
 	see <xref linkend="term-etcttys">. There is a line in the
 	default <filename>/etc/ttys</filename> file for running the xdm
 	daemon on a virtual terminal:
 
 <screen>ttyv8	"/usr/X11R6/bin/xdm -nodaemon"	xterm	off secure</screen>
 
 	By default this entry is disabled, and in order to enable it you
 	will need to change field 5 from <literal>off</literal> to
 	<literal>on</literal> and then restart &man.init.8; using the
 	directions in <xref linkend="term-hup">. The first field, the
 	name of the terminal this program will manage, is
 	<literal>ttyv8</literal>. This means that XDM will start running
 	on the 9th virtual terminal.</para>
     </sect2>
 
     <sect2>
       <title>Configuring XDM</title>
       <para>The XDM configuration directory is located in
 	<filename>/usr/X11R6/lib/X11/xdm</filename>. In this directory
 	you will see several files used to change the behavior and
 	appearance of XDM. Typically you will find these files:</para> 
 
 	<informaltable>
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>File</entry>
 		<entry>Description</entry>
 	      </row>
 	    </thead>
 
 	    <tbody>
 	      <row>
 		<entry><filename>Xaccess</filename></entry>
 		<entry>Client authorization ruleset.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>Xresources</filename></entry>
 		<entry>Default X resource values.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>Xservers</filename></entry>
 		<entry>List of remote and local displays to manage.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>Xsession</filename></entry>
 		<entry>Default session script for logins.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>Xsetup_</filename>*</entry>
 		<entry></entry>
 	      </row>
 
 	      <row>
 		<entry><filename>xdm-config</filename></entry>
 		<entry>Global configuration for all displays running on
 		  this machine.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>xdm-errors</filename></entry>
 		<entry>Errors generated by the server program.</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>xdm-pid</filename></entry>
 		<entry>The process ID of the currently running XDM.</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
       <para>Also in this directory are a few scripts and programs used
 	to setup the desktop when XDM is running. In the next few
 	sections I will briefly describe the purpose of each of these
 	files. The exact syntax and usage of all of these files is
 	described in &man.xdm.1;</para>
 
       <para>The default configuration is a simple rectangular login
 	window with the hostname of the machine displayed at the top in
 	a large font and <quote>Login:</quote> and
 	<quote>Password:</quote> prompts below. This is a good starting
 	point if you are planning to design your own look and feel for
 	the XDM screens.</para>
 
       <sect3>
 	<title>Xaccess</title>
 	<para>The protocol for connecting to XDM controlled displays is
 	  called the X Display Manager Connection Protocol (XDMCP). This
 	  file is basically just a ruleset for controlling XDMCP
 	  connections from remote machines. By default, it allows any
 	  client to connect, but you will see this will not matter
 	  because the default xdm-config file does not listen for remote
 	  connections.</para>
       </sect3>
 
       <sect3>
 	<title>Xresources</title>
 	<para>This is an application-defaults file for the display
 	  chooser and the login screens. This is where you can customize
 	  the appearance of the login program. The format is identical
 	  to the app-defaults file described in the XFree86
 	  documentation.</para>
       </sect3>
 
       <sect3>
 	<title>Xservers</title>
 	<para>This is a list of the remote displays the chooser should
 	  provide as choices.</para>
       </sect3>
 
       <sect3>
 	<title>Xsession</title>
 	<para>This is the default session script for XDM to run after a
 	  user has logged in. Normally each user will have a customized
 	  session script in <filename>~/.xsessionrc</filename> that
 	  overrides this script.</para>
       </sect3>
 
       <sect3>
 	<title>Xsetup_*</title>
 	<para>These files contain scripts that will be run automatically
 	  before displaying the chooser or login interfaces. There is a
 	  script for each display being used, named
 	  <filename>Xsetup_</filename>followed by the local display
 	  number (for instance <filename>Xsetup_0</filename>). Typically
 	  these scripts will run one or two programs in the background
 	  such as <filename>xconsole</filename>.</para>
       </sect3>
 
       <sect3>
 	<title>xdm-config</title>
 	<para>This file contains settings in the form of app-defaults
 	  that are applicable to every display that this installation
 	  manages.</para>
       </sect3>
 
       <sect3>
 	<title>xdm-errors</title>
 	<para>This file contains the output of the X servers that XDM is
 	  trying to run. If a display that XDM is trying to start hangs
 	  for some reason, this is a good place to look for error
 	  messages. These messages are also written to the user's
 	  ~/.xsession-errors file on a per-session basis</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Running A Network Display Server</title>
       <para>In order for other clients to connect to your display
 	server, you will need to edit the access control rules, and
 	enable the connection listener. By default these are set to
 	conservative values, which is a good decision security-wise. To
 	get XDM to listen for connections first comment out a line in
 	the <filename>xdm-config</filename> file:
 
 <screen>! SECURITY: do not listen for XDMCP or Chooser requests
 ! Comment out this line if you want to manage X terminals with xdm
 DisplayManager.requestPort:     0</screen>
 
 	and then restart XDM. Remember that comments in app-defaults
 	files begin with a <quote>!</quote> character, not a
 	<quote>#</quote>. After this, you may need to put more strict
 	access controls in place. Look at the example entries in
 	<filename>Xaccess</filename> file, and refer to the &man.xdm.1;
 	manual page.</para>
     </sect2>
 
      <sect2>
         <title>Replacements for XDM</title>
         <para>Several replacements for the default XDM program exist. 
         One of them, KDM (bundled with KDE) is described in a later
         <link linkend="x11-wm-kde2-kdm">section</link>.  Apart from
         various visual improvements and cosmetic frills, it can be
         easily configured to let users choose their window manager of
         choice at the time they log in.</para>
      </sect2>
 
 
   </sect1>
 
   <sect1 id="x11-wm">
     <title>Desktop Environments</title>
     <para><emphasis>Written by &a.logo;, June 2001</emphasis></para>
 
     <para>This section describes the different desktop environments
       available for X-Windows on FreeBSD.  For our purposes a "desktop
       environment" will mean anything ranging from a simple window
       manager, to a complete suite of desktop applications such as KDE
       or GNOME.</para>
 
     <sect2 id="x11-wm-gnome">
       <title>GNOME</title>
 
       <sect3 id="x11-wm-gnome-about">
         <title>About GNOME</title>
 
         <para>GNOME is a user-friendly desktop environment that
           enables users to easily use and configure their computers.
           GNOME includes a panel (for starting applications and displaying
           status), a desktop (where data and applications can be placed),
           a set of standard desktop tools and applications, and a set of
           conventions that make it easy for applications to cooperate and
           be consistent with each other. Users of other operating systems
           or environments should feel right at home using the powerful
           graphics-driven environment that GNOME provides.</para> 
 
       </sect3>
       <sect3 id="x11-wm-gnome-install">
         <title>Installing GNOME</title>
         <para>To install GNOME from the network, simply type:</para>
         <screen>&prompt.root; <userinput>pkg_add -r gnome</userinput></screen>
 
         <para>If you would rather build GNOME from source, then use
           the ports tree:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
         <para>Once GNOME is installed, we must have the X server start
           GNOME instead of a default window mananger.  If you have
           already customized your <filename>.xinitrc</filename> file
           then you should simply replace the line that starts your
           current window manager with one that starts
           <filename>/usr/X11R6/bin/gnome-wm</filename> instead.  If
           you haven't added anything special to your configuration
           file, then it is enough to simply type:</para>
 
         <screen>&prompt.root; <userinput>echo "/usr/X11R6/bin/gnome-wm" > ~/.xinitrc</userinput></screen>
 
         <para>That's it. Type 'startx' and you will be in the
           GNOME desktop environment.</para>
         <para> Note: if you're running a display manager like xdm,
           this will not work.  Instead, you should create an
           executable <filename>.xsession</filename> file with the same
           command in it.  To do this, edit your file (if you already
           have one) and replace the existing wm command with
           <filename>/usr/X11R6/bin/gnome-wm</filename>; or
           else,</para>
 
         <screen>&prompt.root; <userinput>echo "#!/bin/sh" > ~/.xsession</userinput>
 &prompt.root; <userinput>echo "/usr/X11R6/bin/gnome-wm" >> ~/.xsession</userinput>
 &prompt.root; <userinput>chmod +x ~/.xsession</userinput></screen>
 
         <para>Another option is to configure your display manager to
           allow choosing the window manager at login time; the section on
           <link linkend="x11-wm-kde2-details">KDE2 details</link>
           explains how to do this for <filename>kdm</filename>, the
           display manager of KDE.</para>
       </sect3>
     </sect2>
 
     <sect2 id="x11-wm-kde2">
       <title>KDE2</title>
 
       <sect3 id="x11-wm-kde2-about">
         <title>About KDE2</title>
         <para>KDE is an easy to use contemporary desktop environment.
           Some of the things that KDE brings to the user are:</para>
 
         <itemizedlist>
           <listitem><para>A beautiful contemporary desktop</para></listitem>
           <listitem><para>A desktop exhibiting complete network transparency</para></listitem>
           <listitem><para>An integrated help system allowing for convenient,
             consistent access to help on the use of the KDE desktop and its
             applications</para></listitem>
           <listitem><para>Consistent look and feel of all KDE applications</para></listitem>
           <listitem><para>Standardized menu and toolbars, keybindings, color-schemes, etc.</para></listitem>
           <listitem><para>Internationalization: KDE is available in more than 40 languages</para></listitem>
           <listitem><para>Centralized consisted dialog driven desktop configuration</para></listitem>
           <listitem><para>A great number of useful KDE applications</para></listitem>
         </itemizedlist>
 
         <para>KDE has an office application suite based on KDE's
           KParts technology consisting of a spread-sheet, a
           presentation application, an organizer, a news client and
           more. KDE is also comes with a web browser called Konqeuror,
           which represents already a solid competitor to other
           existing web browsers on Unix systems. More information on
           KDE can be found on the <ulink url="http://www.kde.org">KDE
           website</ulink></para>
       </sect3>
       <sect3 id="x11-wm-kde2-install">
         <title>Installing KDE2</title>
    
         <para>At the time of writing, a package for kde2 doesn't
           exist yet. No problem!  The ports tree hides all the
           complexity of building a package from source.  To install
           KDE2, do this :</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde2</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
         <para>This command will fetch all the necessary files from the
           Internet, configure and compile KDE2, install the
           applications, and then clean up after itself.</para>
 
         <para>Now you're going to have to tell the X server to launch
           KDE2 instead of a default window manager. Do this by typing
           this:</para>
 
         <screen>&prompt.root; <userinput>echo "/usr/X11R6/bin/startkde" > ~/.xinitrc</userinput></screen>
 
         <para>Now, whenever you go into X-Windows, KDE2 will be your
           desktop.  (Note: this will not work if you're logging in via
           a display manager like <filename>xdm</filename>.  In that
           case you have two options: create an
           <filename>.xsession</filename> file as described in the
           section on <link linkend="x11-wm-gnome">GNOME</link>, but
           with the <filename>/usr/X11R6/bin/startkde</filename>
           command instead of the <filename>gnome-wm</filename>
           command; or, configure your display manager to allow
           choosing a desktop at login time.  Below it is explained how
           to do this for <filename>kdm</filename>, KDE's display
           manager.)</para>
       </sect3>
     </sect2>
     <sect2 id="x11-wm-kde2-details">
         <title>More details on KDE2</title>
 
         <para>Now that KDE2 is installed on your system, you'll find
           that you can learn a lot from its help pages, or just by
           pointing and clicking at various menus.  Windows or Mac
           users will feel quite at home.</para>
 
         <para>The best reference for KDE is the on-line documentation.
           KDE comes with its own web browser, Konqueror, dozens of
           useful applications, and extensive documentation.  This
           section only discusses somewhat technical things which are
           difficult to learn just by random exploration.</para>
 
       <sect3 id="x11-wm-kde2-kdm">
         <title>The KDE display manager</title>
 
         <para>If you're an administrator on a multi-user system, you
           may like to have a graphical login screen to welcome users.
           You can use <link
           linkend="x-xdm"><filename>xdm</filename></link>, as
           described earlier.  However, KDE includes an alternative,
           kdm, which is designed to look more attractive and include
           more login-time options.  In particular, users can easily
           choose (via a menu) which desktop environment (KDE2, GNOME,
           or something else) to run after logging on.  If you're slightly
           adventurous and you want this added flexibility and visual
           appeal, read on.</para>
 
 	<para>To begin with, run the KDE2 control panel,
 	  <filename>kcontrol</filename>, as root.  Note: it is
 	  generally considered unsafe to run your entire X environment
 	  as root.  Instead, run your window manager as a normal user,
 	  open a terminal window (such as <filename>xterm</filename>
 	  or KDE's <filename>konsole</filename>, become root with
 	  <userinput>su</userinput> (you need to be in the "wheel"
 	  group in <filename>/etc/group</filename> for this), and then
 	  type <userinput>kcontrol</userinput>.</para>
 
 	<para> Click on the icon on the left marked "System", then on
 	  "Login manager".  On the right you'll see various
 	  configurable options, which the KDE manual will explain in
 	  greater detail.  Click on "sessions" on the right.
 	  Depending on what window managers or desktop environments
 	  you have currently installed, you can type their names in
 	  "New type" and add them.  (These are just labels so far, not
 	  commands, so you can write "KDE" and "GNOME" rather than
 	  "startkde" or "gnome-wm".)  Include a label
 	  "failsafe".</para>
 
 	<para> Play with the other menus as you like (those are mainly
           cosmetic and self-explanatory).  When you're done, click on
           "Apply" at the bottom, and quit the control center.</para>
 
         <para> To make sure kdm understands what your above labels
           (KDE, GNOME etc) mean, you need to edit some more files: the
           same ones used by <link linkend="x-xdm">xdm</link>.  In your
           terminal window, as root, edit the file
           <filename>/usr/X11R6/lib/X11/xdm/Xsession</filename>.  You
           will come across a section in the middle looking like this
           (by default):</para>
 <screen>case $# in
 1)
         case $1 in
         failsafe)
                 exec xterm -geometry 80x24-0-0
                 ;;
         esac
 esac</screen>
         <para>You will need to add a few lines to this section.
 	  Assuming the labels you gave earlier were KDE2 and GNOME,
 	  the following will do:</para>
 <screen>case $# in
 1)
         case $1 in
         KDE2)
                 exec /usr/X11R6/bin/startkde
                 ;;
         GNOME)
                 exec /usr/X11R6/bin/gnome-wm
                 ;;
         failsafe)
                 exec xterm -geometry 80x24-0-0
                 ;;
         esac
 esac</screen>
 
         <para>To make sure your KDE choice of a login-time desktop
           background is also honored, you will need to add the
           following line to
           <filename>/usr/X11R6/lib/X11/xdm/Xsetup_0</filename>:</para>
         <screen>/usr/X11R6/bin/kdmdesktop</screen>
 
         <para>Now, you need only to make sure kdm is started at the
           next bootup.  To learn how to do this, read the section on
           <link linkend="x-xdm">xdm</link>, and do the same thing
           replacing references to the <filename>xdm</filename> program
           by <filename>kdm</filename>.</para>
 
         <para>That's it. Your next login screen should have a pretty
           face and lots of menus.</para>
 
       </sect3>
       <sect3 id="x11-wm-kde2-antialias">
         <title>Anti-aliased fonts</title>
 
         <para>Tired of blocky staircase edges to your fonts under X11?
           Tired of unreadable text in web browsers?  Well, no
           more.</para>
 
         <para>Starting with version 4.0.2, XFree86 supports
           anti-aliasing via its "RENDER" extension, and starting with
           version 2.3, Qt (the toolkit used by KDE) supports this
           extension.  Configuring this is described in <xref
           linkend="antialias"> on  antialiasing X11 fonts.
           So if you're running up-to-date software,
           anti-aliasing is possible on your KDE2 desktop.  Just go to
           your KDE2 menu, go to Preferences -> Look and Feel -> Style,
           and click on the checkbox "Use Anti-Aliasing for Fonts and
           Icons".  That's all.  If you're running a Qt application
           which is not part of KDE, you may need to set the
           environment variable QT_XFT to true before starting your
           program.</para>
 
        </sect3>
      </sect2>
 
      <sect2 id="x11-wm-xfce">
          <title>XFCE</title>
        <sect3 id="x11-wm-xfce-about">
          <title>About XFCE</title>
          <para>XFCE is based on the gtk+ toolkit used by GNOME, but is
            much more lightweight and meant for those who want a simple,
            efficient desktop which is nevertheless easy to use and
            configure.  Visually, it looks very much like CDE, found on
            commercial Unix systems.
            Some of XFCE's features are:</para>
 
          <itemizedlist>
            <listitem><para>A simple, easy-to-handle desktop</para></listitem>
            <listitem><para>Fully configurable via mouse, with drag and
                drop, etc </para></listitem>
            <listitem><para>Main panel similar to CDE, with menus, applets and
  app launchers</para></listitem>
            <listitem><para>Integrated window manager, file manager,
  sound manager, GNOME compliance module, and other things</para></listitem>
            <listitem><para> Themable (since it uses gtk+) </para></listitem>
            <listitem><para> Fast, light and efficient: ideal for
  older/slower machines or machiens with memory limitations</para></listitem>
          </itemizedlist>
 
          <para> More information on
            XFCE can be found on the <ulink url="http://www.xfce.org">XFCE
            website</ulink>.</para>
        </sect3>
        <sect3 id="x11-wm-xfce-install">
          <title>Installing XFCE</title>
    
          <para>A binary package for xfce exists (at the time of
            writing). To install, simply do this:</para>
 
          <screen>&prompt.root; <userinput>pkg_add -r xfce</userinput></screen>
 
          <para> Alternatively, you may prefer to build from source.
            The ports tree comes to the rescue again: </para>
 
          <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce</userinput>
  &prompt.root; <userinput>make install clean</userinput></screen>
 
          <para> All necessary source packages (including dependencies)
            will be automagically fetched, built and installed, and
            the build areas cleaned up afterwards.</para>
 
          <para>Now you want to tell the X server to launch
            XFCE the next time you start X. Simply type
            this:</para>
 
          <screen>&prompt.root; <userinput>echo "/usr/X11R6/bin/startxfce" > ~/.xinitrc</userinput></screen>
 
          <para>The next time you start X, XFCE will be your
            desktop.  (Note, as before:
            if you're logging in via a display manager like
            <filename>xdm</filename>,  you should either create an
            <filename>.xsession</filename>, as described in the
            section on <link linkend="x11-wm-gnome">GNOME</link>, but
            with the <filename>/usr/X11R6/bin/startxfce</filename>
            command; or, configure your display manager to allow
            choosing a desktop at login time, as explained in
            the section on <link linkend="x11-wm-kde2-kdm">kdm</link>.)</para>
 
       </sect3>
     </sect2>
   </sect1>
 
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index 2aedfa164d..622059a188 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -1,4510 +1,4510 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v 1.156 2001/07/13 07:33:25 dd Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v 1.157 2001/07/14 20:56:36 tobez Exp $
 -->
 
 <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 
 <!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN">
 %bookinfo;
 
 <!ENTITY % authors SYSTEM "../handbook/authors.ent"> %authors;
 <!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
 %mailing-lists;
 
 ]>
 
 <book>
   <bookinfo>
     <title>FreeBSD Porter's Handbook</title>
 
     <authorgroup>
       <corpauthor>The FreeBSD Documentation Project</corpauthor>
     </authorgroup>
 
     <pubdate>April 2000</pubdate>
 
     <copyright>
       <year>2000</year>
       <holder role="mailto:doc@FreeBSD.org">The FreeBSD Documentation
 	Project</holder>
     </copyright>
 
     &bookinfo.legalnotice;
   </bookinfo>
 
 
     <chapter>
       <title>Making a port yourself</title>
 
       <para>So, now you are interested in making your own port or
         upgrading an existing one?  Great!</para>
 
       <para>What follows are some guidelines for creating a new port for
         FreeBSD.  If you want to upgrade an existing port, you should
 	read this and then read <xref linkend="port-upgrading">.</para>
 
       <para>When this document is not sufficiently detailed, you should
         refer to <filename>/usr/ports/Mk/bsd.port.mk</filename>, which
 	all port Makefiles include.  Even if you do not hack Makefiles
 	daily, it is well commented, and you will still gain much
 	knowledge from it.  Additionally, you may send specific questions
 	to the &a.ports;.</para>
 
       <note>
         <para>Only a fraction of the variables
           (<makevar><replaceable>VAR</replaceable></makevar>) that can be
           overridden are mentioned in this document.  Most (if not all)
 	  are documented at the start of <filename>bsd.port.mk</filename>.
 	  This file uses a non-standard tab setting.
 	  <application>Emacs</application> and
 	  <application>Vim</application> should recognize the setting on
 	  loading the file.  Both <command>vi</command> and
 	  <command>ex</command> can be set to use the correct value by
 	  typing <command>:set tabstop=4</command> once the file has been
 	  loaded.</para>
       </note>
     </chapter>
 
     <chapter id="quick-porting">
       <title>Quick Porting</title>
 
       <para>This section tells you how to do a quick port.  In many cases, it
         is not enough, but we will see.</para>
 
       <para>First, get the original tarball and put it into
         <makevar>DISTDIR</makevar>, which defaults to
         <filename>/usr/ports/distfiles</filename>.</para>
 
       <note>
         <para>The following assumes that the software compiled out-of-the-box,
           i.e., there was absolutely no change required for the port to work
           on your FreeBSD box.  If you needed to change something, you will
           have to refer to the next section too.</para>
       </note>
 
       <sect1>
         <title>Writing the <filename>Makefile</filename></title>
 
         <para>The minimal <filename>Makefile</filename> would look something
           like this:</para>
 
         <programlisting># New ports collection makefile for:   oneko
 # Date created:        5 December 1994
 # Whom:                asami
 #
 # &dollar;FreeBSD&dollar;
 #
 
 PORTNAME=      oneko
 PORTVERSION=   1.1b
 CATEGORIES=    games
 MASTER_SITES=  ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
 
 MAINTAINER=    asami@FreeBSD.org
 
 MAN1=          oneko.1
 MANCOMPRESSED= yes
 USE_IMAKE=     yes
 
 .include &lt;bsd.port.mk&gt;</programlisting>
 
         <para>See if you can figure it out.  Do not worry about the contents
           of the <literal>&dollar;FreeBSD&dollar;</literal> line, it will be
           filled in automatically by CVS when the port is imported to our main
           ports tree.  You can find a more detailed example in the <link
             linkend="porting-samplem">sample Makefile</link> section.</para>
       </sect1>
 
       <sect1>
         <title>Writing the description files</title>
 
         <para>There are three description files that are required for
           any port, whether they actually package or not. They are
           <filename>pkg-comment</filename>,
           <filename>pkg-descr</filename>, and
           <filename>pkg-plist</filename>, and their
           <filename>pkg-</filename> prefix distinguishes them from
           other files.</para>
 
         <sect2>
           <title><filename>pkg-comment</filename></title>
 
           <para>This is the one-line description of the port.
             <emphasis>Please</emphasis> do not include the package name (or
             version number of the software) in the comment.  The comment
             should begin with a capital, and end without a period.  Here
             is an example:</para>
 
           <programlisting>A cat chasing a mouse all over the screen</programlisting>
         </sect2>
 
         <sect2>
           <title><filename>pkg-descr</filename></title>
 
           <para>This is a longer description of the port.  One to a few
             paragraphs concisely explaining what the port does is
             sufficient.</para>
 
           <note>
             <para>This is <emphasis>not</emphasis> a manual or an in-depth
               description on how to use or compile the port! <emphasis>Please
               be careful if you are copying from the
               <filename>README</filename> or manpage</emphasis>; too often
               they are not a concise description of the port or are in an
               awkward format (e.g., manpages have justified spacing).  If the
               ported software has an official WWW homepage, you should list it
               here.  Prefix <emphasis>one</emphasis> of the websites with
               <literal>WWW:</literal> so that automated tools will work
               correctly.</para>
           </note>
 
           <para>It is recommended that you sign your name at the end of this
             file, as in:</para>
 
           <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
 the screen.
  :
 (etc.)
 
 WWW: http://www.oneko.org/
 
 - Satoshi
 asami@cs.berkeley.edu</programlisting>
         </sect2>
 
         <sect2>
           <title><filename>pkg-plist</filename></title>
 
           <para>This file lists all the files installed by the port.  It is
             also called the &ldquo;packing list&rdquo; because the package is
             generated by packing the files listed here.  The pathnames are
             relative to the installation prefix (usually
             <filename>/usr/local</filename> or
             <filename>/usr/X11R6</filename>).  If you are using the
             <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
             you should be), do not list any manpages here.</para>
 
           <para>Here is a small example:</para>
 
           <programlisting>bin/oneko
 lib/X11/app-defaults/Oneko
 lib/X11/oneko/cat1.xpm
 lib/X11/oneko/cat2.xpm
 lib/X11/oneko/mouse.xpm
 @dirrm lib/X11/oneko</programlisting>
 
           <para>Refer to the &man.pkg.create.1; man page for details on the
             packing list.</para>
 
           <note>
             <para>You should list all the files, but not the name directories,
               in the list.  Also, if the port creates directories for itself
               during installation, make sure to add <literal>@dirrm</literal>
               lines as necessary to remove them when the port is
               deleted.</para>
 
             <para>It is recommended that you keep all the filenames in this
               file sorted alphabetically.  It will make verifying the changes
               when you upgrade the port much easier.</para>
 
             <para>Creating a packing list manually can be a very tedious
               task.  If the port installs a large numbers of files, <link
                 linkend="porting-autoplist">creating the packing list
                 automatically</link> might save time.</para>
           </note>
         </sect2>
       </sect1>
 
       <sect1>
         <title>Creating the checksum file</title>
 
         <para>Just type <command>make makesum</command>. The ports make rules
           will automatically generate the file
           <filename>distinfo</filename>.</para>
       </sect1>
 
       <sect1 id="porting-testing">
         <title>Testing the port</title>
 
         <para>You should make sure that the port rules do exactly what you
           want them to do, including packaging up the port.  These are the
           important points you need to verify.</para>
 
         <itemizedlist>
           <listitem>
             <para><filename>pkg-plist</filename> does not contain anything not
               installed by your port</para>
           </listitem>
 
           <listitem>
             <para><filename>pkg-plist</filename> contains everything that is
               installed by your port</para>
           </listitem>
 
           <listitem>
             <para>Your port can be installed multiple times using the
               <maketarget>reinstall</maketarget> target</para>
           </listitem>
 
           <listitem>
             <para>Your port <link linkend="porting-cleaning">cleans up</link>
               after itself upon deinstall</para>
           </listitem>
         </itemizedlist>
 
         <procedure>
           <title>Recommended test ordering</title>
 
           <step>
             <para><command>make install</command></para>
           </step>
 
           <step>
             <para><command>make package</command></para>
           </step>
 
           <step>
             <para><command>make deinstall</command></para>
           </step>
 
           <step>
             <para><command>pkg_add <replaceable>package-name</replaceable>
               </command></para>
           </step>
 
           <step>
             <para><command>make deinstall</command></para>
           </step>
 
           <step>
             <para><command>make reinstall</command></para>
           </step>
 
           <step>
             <para><command>make package</command></para>
           </step>
         </procedure>
 
         <para>Make sure that there are not any warnings issued in any of the
           <maketarget>package</maketarget> and
           <maketarget>deinstall</maketarget> stages.  After step 3, check to
           see if all the new directories are correctly deleted.  Also, try
           using the software after step 4, to ensure that it works correctly
           when installed from a package.</para>
       </sect1>
 
       <sect1 id="porting-portlint">
         <title>Checking your port with <command>portlint</command></title>
 
         <para>Please use <command>portlint</command> to see if your port
           conforms to our guidelines.  The <command>portlint</command> program
           is part of the ports collection.  In particular, you may want to
           check if the <link linkend="porting-samplem">Makefile</link> is in
           the right shape and the <link
             linkend="porting-pkgname">package</link> is named
           appropriately.</para>
       </sect1>
 
       <sect1 id="porting-submitting">
         <title>Submitting the port</title>
 
         <para>First, make sure you have read the <link
             linkend="porting-dads">DOs and DON'Ts</link> section.</para>
 
         <para>Now that you are happy with your port, the only thing remaining
           is to put it in the main FreeBSD ports tree and make everybody else
           happy about it too.  We do not need your <filename>work</filename>
           directory or the <filename>pkgname.tgz</filename> package, so delete
           them now.  Next, simply include the output of <command>shar `find
             port_dir`</command> in a bug report and send it with the
             &man.send-pr.1; program (see <ulink url="../handbook/contrib-how.html#CONTRIB-GENERAL">Bug
             Reports and General Commentary</ulink> for more information about
             &man.send-pr.1;.  If the uncompressed port is larger than 20KB,
           you should compress it into a tarfile and use &man.uuencode.1;
           before including it in the bug report (uuencoded tarfiles are
           acceptable even if the bug report is smaller than 20KB but are not
           preferred).  Be sure to classify the bug report as category
           <literal>ports</literal> and class
           <literal>change-request</literal>  (Do not mark the report
           <literal>confidential</literal>!).
           Also add a short description of the program you ported
           to the <quote>Description</quote> field of the PR and
           the shar or uuencoded tarfile to the
           <quote>Fix</quote> field.  The latter one helps the committers
           a lot, who use scripts for the ports-work.</para>
 
         <para>One more time, <emphasis>do not include the original source
             distfile, the <filename>work</filename> directory, or the package
             you built with <command>make package</command></emphasis>.</para>
 
         <note>
           <para>In the past, we asked you to upload new port submissions in
             our ftp site (<hostid role="fqdn">ftp.FreeBSD.org</hostid>). This
             is no longer recommended as read access is turned off on the
             <filename>incoming/</filename> directory of that site due to the
             large amount of pirated software showing up there.</para>
         </note>
 
         <para>We will look at your port, get back to you if necessary, and put
           it in the tree.  Your name will also appear in the list of
           &ldquo;Additional FreeBSD contributors&rdquo; in the FreeBSD
           Handbook and other files. Isn't that great?!? <!-- smiley
           -->:-)</para>
 
         <note>
           <para>You can make our work a lot easier, if you use a good
             description in the synopsis of the problem report.
             We prefer something like
             &ldquo;New port: &lt;short description of the port&gt;&rdquo; for
             new ports and
             &ldquo;Update port: &lt;category&gt;/&lt;port&gt; &lt;short description
             of the update&gt;&rdquo; for port updates.
             If you stick to this scheme, the chance that one takes a look at
             your PR soon is much bigger.</para>
         </note>
       </sect1>
     </chapter>
 
     <chapter>
       <title>Slow Porting</title>
 
       <para>Ok, so it was not that simple, and the port required some
         modifications to get it to work.  In this section, we will explain,
         step by step, how to modify it to get it to work with the ports
         paradigm.</para>
 
       <sect1>
         <title>How things work</title>
 
         <para>First, this is the sequence of events which occurs when the user
           first types <command>make</command> in your port's directory.
           You may find that having <filename>bsd.port.mk</filename> in another
           window while you read this really helps to understand it.</para>
 
         <para>But do not worry if you do not really understand what
           <filename>bsd.port.mk</filename> is doing, not many people do...
           <!-- smiley --><emphasis>:-&gt;</emphasis></para>
 
         <procedure>
 
           <step>
             <para>The <maketarget>fetch</maketarget> target is run.  The
               <maketarget>fetch</maketarget> target is responsible for making
               sure that the tarball exists locally in
               <makevar>DISTDIR</makevar>. If <maketarget>fetch</maketarget>
               cannot find the required files in <makevar>DISTDIR</makevar> it
               will look up the URL <makevar>MASTER_SITES</makevar>, which is
               set in the Makefile, as well as our main ftp site at <ulink
                 url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</ulink>,
               where we put sanctioned distfiles as backup.  It will then
               attempt to fetch the named distribution file with
               <makevar>FETCH</makevar>, assuming that the requesting site has
               direct access to the Internet.  If that succeeds, it will save
               the file in <makevar>DISTDIR</makevar> for future use and
               proceed.</para>
           </step>
 
           <step>
             <para>The <maketarget>extract</maketarget> target is run.  It
               looks for your port's distribution file (typically a gzip'd
               tarball) in <makevar>DISTDIR</makevar> and unpacks it into a
               temporary subdirectory specified by <makevar>WRKDIR</makevar>
               (defaults to <filename>work</filename>).</para>
           </step>
 
           <step>
             <para>The <maketarget>patch</maketarget> target is run.  First,
               any patches defined in <makevar>PATCHFILES</makevar> are
               applied.  Second, if any patch files named
               <filename>patch-<replaceable>*</replaceable></filename> are found in
               <makevar>PATCHDIR</makevar> (defaults to the
               <filename>files</filename> subdirectory), they are applied at
               this time in alphabetical order.</para>
           </step>
 
           <step>
             <para>The <maketarget>configure</maketarget> target is run.  This
               can do any one of many different things.</para>
 
             <orderedlist>
               <listitem>
                 <para>If it exists, <filename>scripts/configure</filename> is
                   run.</para>
               </listitem>
 
               <listitem>
                 <para>If <makevar>HAS_CONFIGURE</makevar> or
                   <makevar>GNU_CONFIGURE</makevar> is set,
                   <filename><makevar>WRKSRC</makevar>/configure</filename> is
                   run.</para>
               </listitem>
 
               <listitem>
                 <para>If <makevar>USE_IMAKE</makevar> is set,
                   <makevar>XMKMF</makevar> (default: <command>xmkmf
                     -a</command>) is run.</para>
               </listitem>
             </orderedlist>
           </step>
 
           <step>
             <para>The <maketarget>build</maketarget> target is run.  This is
               responsible for descending into the port's private working
               directory (<makevar>WRKSRC</makevar>) and building it.  If
               <makevar>USE_GMAKE</makevar> is set, GNU <command>make</command>
               will be used, otherwise the system <command>make</command> will
               be used.</para>
           </step>
         </procedure>
 
         <para>The above are the default actions.  In addition, you can define
           targets
           <maketarget>pre-<replaceable>something</replaceable></maketarget> or
           <maketarget>post-<replaceable>something</replaceable></maketarget>,
           or put scripts with those names, in the <filename>scripts</filename>
           subdirectory, and they will be run before or after the default
           actions are done.</para>
 
         <para>For example, if you have a <maketarget>post-extract</maketarget>
           target defined in your Makefile, and a file
           <filename>pre-build</filename> in the <filename>scripts</filename>
           subdirectory, the <maketarget>post-extract</maketarget> target will
           be called after the regular extraction actions, and the
           <filename>pre-build</filename> script will be executed before the
           default build rules are done.  It is recommended that you use
           <filename>Makefile</filename> targets if the actions are simple
           enough, because it will be easier for someone to figure out what
           kind of non-default action the port requires.</para>
 
         <para>The default actions are done by the
           <filename>bsd.port.mk</filename> targets
           <maketarget>do-<replaceable>something</replaceable></maketarget>.
           For example, the commands to extract a port are in the target
           <maketarget>do-extract</maketarget>.  If you are not happy with the
           default target, you can fix it by redefining the
           <maketarget>do-<replaceable>something</replaceable></maketarget>
           target in your <filename>Makefile</filename>.</para>
 
         <note>
           <para>The &ldquo;main&rdquo; targets (e.g.,
             <maketarget>extract</maketarget>,
             <maketarget>configure</maketarget>, etc.) do nothing more than
             make sure all  the stages up to that one are completed and call
             the real targets or scripts, and they are not intended to be
             changed.  If you want to fix the extraction, fix
             <maketarget>do-extract</maketarget>, but never ever touch
             <maketarget>extract</maketarget>!</para>
         </note>
 
         <para>Now that you understand what goes on when the user types
           <command>make</command>, let us go through the recommended steps to
           create the perfect port.</para>
       </sect1>
 
       <sect1>
         <title>Getting the original sources</title>
 
         <para>Get the original sources (normally) as a compressed tarball
           (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
           <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy
           it into <makevar>DISTDIR</makevar>.  Always use
           <emphasis>mainstream</emphasis> sources when and where you
           can.</para>
 
         <para>If you cannot find a ftp/http site that is well-connected to the
           net, or can only find sites that have irritatingly non-standard
           formats, you might want to put a copy on a reliable ftp or http
           server that you control (e.g., your home page).  Make sure you set
           <makevar>MASTER_SITES</makevar> to reflect your choice.</para>
 
         <para>If you cannot find somewhere convenient and reliable to put the
           distfile
           we can &ldquo;house&rdquo; it ourselves
           on <hostid>ftp.FreeBSD.org</hostid>.
           The distfile must be placed into
           <filename>~/public_distfiles/</filename> of someone's
           <hostid>freefall</hostid> account.
           Ask the person who commits your port to do this.
           This person will also set <makevar>MASTER_SITES</makevar> to
           <makevar>MASTER_SITE_LOCAL</makevar> and
           <makevar>MASTER_SITE_SUBDIR</makevar> to their
           <hostid>freefall</hostid> username.</para>
 
         <para>If your port's distfile changes all the time for no good reason,
           consider putting the distfile in your home page and listing it as
           the first <makevar>MASTER_SITES</makevar>.  This will prevent users
           from getting <errorname>checksum mismatch</errorname> errors, and
           also reduce the workload of maintainers of our ftp site.  Also, if
           there is only one master site for the port, it is recommended that
           you house a backup at your site and list it as the second
           <makevar>MASTER_SITES</makevar>.</para>
 
         <para>If your port requires some additional `patches' that are
           available on the Internet, fetch them too and put them in
           <makevar>DISTDIR</makevar>.  Do not worry if they come from a site
           other than where you got the main source tarball, we have a way to
           handle these situations (see the description of <link
             linkend="porting-patchfiles">PATCHFILES</link> below).</para>
       </sect1>
 
       <sect1>
         <title>Modifying the port</title>
 
         <para>Unpack a copy of the tarball in a private directory and make
           whatever changes are necessary to get the port to compile properly
           under the current version of FreeBSD.  Keep <emphasis>careful
             track</emphasis> of everything you do, as you will be automating
           the process shortly.  Everything, including the deletion, addition,
           or modification of files should be doable using an automated script
           or patch file when your port is finished.</para>
 
         <para>If your port requires significant user interaction/customization
           to compile or install, you should take a look at one of Larry Wall's
           classic <application>Configure</application> scripts and perhaps do
           something similar yourself.  The goal of the new ports collection is
           to make each port as &ldquo;plug-and-play&rdquo; as possible for the
           end-user while using a minimum of disk space.</para>
 
         <note>
           <para>Unless explicitly stated, patch files, scripts, and other
             files you have created and contributed to the FreeBSD ports
             collection are assumed to be covered by the standard BSD copyright
             conditions.</para>
         </note>
       </sect1>
 
       <sect1>
         <title>Patching</title>
 
         <para>In the preparation of the port, files that have been added or
           changed can be picked up with a recursive diff for later feeding to
           patch.  Each set of patches you wish to apply should be collected
           into a file named
           <filename>patch-<replaceable>*</replaceable></filename> where
           <replaceable>*</replaceable> denotes the sequence in which the
           patches will be applied &mdash; these are done in
           <emphasis>alphabetical order</emphasis>, thus <literal>aa</literal>
           first, <literal>ab</literal> second and so on.  If you wish,
           you can use names that indicate the pathnames of the files that
           are patched, such as <filename>patch-Imakefile</filename> or
           <filename>patch-src-config.h</filename>.  These files should
           be stored in <makevar>PATCHDIR</makevar>, from where they will be
           automatically applied.  All patches should be relative to
           <makevar>WRKSRC</makevar> (generally the directory your port's
           tarball unpacks itself into, that being where the build is done).
           To make fixes and upgrades easier, you should avoid having more than
           one patch fix the same file (e.g., <filename>patch-aa</filename> and
           <filename>patch-ab</filename> both changing
           <filename><makevar>WRKSRC</makevar>/foobar.c</filename>).</para>
       </sect1>
 
       <sect1>
         <title>Configuring</title>
 
         <para>Include any additional customization commands in your
           <filename>configure</filename> script and save it in the
           <filename>scripts</filename> subdirectory.  As mentioned above, you
           can also do this with <filename>Makefile</filename> targets and/or
           scripts with the name <filename>pre-configure</filename> or
           <filename>post-configure</filename>.</para>
       </sect1>
 
       <sect1>
         <title>Handling user input</title>
 
         <para>If your port requires user input to build, configure, or install,
           then set <makevar>IS_INTERACTIVE</makevar> in your Makefile.  This
           will allow &ldquo;overnight builds&rdquo; to skip your port if the
           user sets the variable <envar>BATCH</envar> in his environment (and
           if the user sets the variable <envar>INTERACTIVE</envar>, then
           <emphasis>only</emphasis> those ports requiring interaction are
           built).</para>
 
         <para>It is also recommended that if there are reasonable default
           answers to the questions, you check the
           <makevar>PACKAGE_BUILDING</makevar> variable and turn off the
           interactive script when it is set.  This will allow us to build the
-          packages for CD-ROMs and ftp.</para>
+          packages for CDROMs and ftp.</para>
       </sect1>
     </chapter>
 
     <chapter>
       <title>Configuring the Makefile</title>
 
       <para>Configuring the Makefile is pretty simple, and again we suggest
         that you look at existing examples before starting. Also, there is a
         <link linkend="porting-samplem">sample Makefile</link> in this
         handbook, so take a look and please follow the ordering of variables
         and sections in that template to make your port easier for others to
         read.</para>
 
       <para>Now, consider the following problems in sequence as you design
         your new Makefile:</para>
 
       <sect1>
         <title>The original source</title>
 
         <para>Does it live in <makevar>DISTDIR</makevar> as a standard
 	  gzip'd tarball named something like
 	  <filename>foozolix-1.2.tar.gz</filename>? If so, you can go on
 	  to the next step.  If not, you should look at overriding any of
 	  the <makevar>DISTNAME</makevar>, <makevar>EXTRACT_CMD</makevar>,
 	  <makevar>EXTRACT_BEFORE_ARGS</makevar>,
 	  <makevar>EXTRACT_AFTER_ARGS</makevar>,
 	  <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar>
 	  variables, depending on how alien a format your port's
 	  distribution file is.  (The most common case is
 	  <literal>EXTRACT_SUFX=.tar.Z</literal>, when the tarball is
 	  condensed by regular <command>compress</command>, not
 	  <command>gzip</command>.)</para>
 
         <para>In the worst case, you can simply create your own
 	  <maketarget>do-extract</maketarget> target to override the
 	  default, though this should be rarely, if ever,
 	  necessary.</para>
       </sect1>
 
       <sect1>
         <title><makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar></title>
 
         <para>You should set <makevar>PORTNAME</makevar> to the
           base name of your port, and <makevar>PORTVERSION</makevar>
           to the version number of the port.</para>
       </sect1>
 
       <sect1>
 	<title><makevar>PORTREVISION</makevar> and
 	  <makevar>PORTEPOCH</makevar></title>
 
 	<sect2>
 	  <title><makevar>PORTREVISION</makevar></title>
 
 	  <para>The <makevar>PORTREVISION</makevar> variable is a
 	    monotonically increasing value which is reset to 0 with
 	    every increase of <makevar>PORTVERSION</makevar> (i.e.
 	    every time a new official vendor release is made), and
 	    appended to the package name if non-zero.
 	    <makevar>PORTREVISION</makevar> is increased each time a
 	    change is made to the FreeBSD port which significantly
 	    affects the content or stucture of the derived
 	    package.</para>
 
 	  <para>Examples of when PORTREVISION should be bumped:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>Addition of patches to correct security
 		vulnerabilities, bugs, or to add new functionality to
 		the FreeBSD port.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Changes to the port makefile to enable or disable
 		compile-time options in the package.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Changes in the packing list or the install-time
 		behaviour of the package (e.g. change to a script
 		which generates initial data for the package, like ssh
 		host keys).</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Version bump of a port's shared library dependency
 		(in this case, someone trying to install the old
 		package after installing a newer version of the
 		dependency will fail since it will look for the old
 		libfoo.x instead of libfoo.(x+1)).</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Silent changes to the port distfile which have
 		significant functional differences, i.e. changes to
 		the distfile requiring a correction to
 		<filename>distinfo</filename> with no corresponding change to
 		<makevar>PORTVERSION</makevar>, where a <command>diff
 		-ru</command> of the old and new versions shows
 		non-trivial changes to the code.</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>Examples of changes which do not require a
 	    <makevar>PORTREVISION</makevar> bump:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>Style changes to the port skeleton with no
 		functional change to what appears in the resulting
 		package.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Changes to <makevar>MASTER_SITES</makevar> or
 		other functional changes to the port which do not
 		effect the resulting package.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Trivial patches to the distfile such as correction
 		of typos, which are not important enough that users of
 		the package should go to the trouble of
 		upgrading.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Build fixes which cause a package to become
 		compilable where it was previously failing (as long as
 		the changes do not introduce any functional change on
 		any other platforms on which the port did previously
 		build). Since <makevar>PORTREVISION</makevar> reflects
 		the content of the package, if no package was
 		previously buildable then there is no need to increase
 		<makevar>PORTREVISION</makevar> to mark a
 		change.</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>A rule of thumb is to ask yourself whether a change
 	    committed to a port is something which someone, somewhere,
 	    would benefit from having (either because of an
 	    enhancement, fix, or by virtue that the new package will
 	    actually work for them). If yes, the
 	    <makevar>PORTREVISION</makevar> should be bumped so that
 	    automated tools (e.g.  <command>pkg_version</command>)
 	    will highlight the fact that a new package is
 	    available.</para>
 	</sect2>
 
 	<sect2>
 	  <title><makevar>PORTEPOCH</makevar></title>
 
 	  <para>From time to time a software vendor or FreeBSD porter
 	    will do something silly and release a version of their
 	    software which is actually numerically less than the
 	    previous version. An example of this is a port which goes
 	    from foo-20000801 to foo-1.0 (the former will be
 	    incorrectly treated as a newer version since 20000801 is a
 	    numerically greater value than 1).</para>
 
 	  <para>In situations such as this, the
 	    <makevar>PORTEPOCH</makevar> version should be increased.
 	    If <makevar>PORTEPOCH</makevar> is nonzero it is appended
 	    to the package name as described in section 0 above.
 	    <makevar>PORTEPOCH</makevar> is never decreased or reset
 	    to zero, because that would cause comparison to a package
 	    from an earlier epoch to fail (i.e. the package would not
 	    be detected as out of date): the new version number (e.g.
 	    <literal>1.0,1</literal> in the above example) is still
 	    numerically less than the previous version (2000801), but
 	    the <literal>,1</literal> suffix is treated specially by
 	    automated tools and found to be greater than the implied
 	    suffix ",0" on the earlier package)</para>
 
 	  <para>It is expected that <makevar>PORTEPOCH</makevar> will
 	    not be used for the majority of ports, and that sensible
 	    use of <makevar>PORTVERSION</makevar> can often pre-empt
 	    it becoming necessary if a future release of the software
 	    should change the version structure. However, care is
 	    needed by FreeBSD porters when a vendor release is made
 	    without an official version number - such as a code
 	    "snapshot" release.  The temptation is to label the
 	    release with the release date, which will cause problems
 	    as in the example above when a new "official" release is
 	    made.</para>
 
 	  <para>For example, if a snapshot release is made on the date
 	    20000917, and the previous version of the software was
 	    version 1.2, the snapshot release should be given a
 	    <makevar>PORTVERSION</makevar> of 1.2.20000917 or similar,
 	    not 20000917, so that the succeeding release, say 1.3, is
 	    still a numerically greater value.</para>
 	</sect2>
 
 	<sect2>
 	  <title>Example of <makevar>PORTREVISION</makevar> and
 	    <makevar>PORTEPOCH</makevar> usage</title>
 
 	  <para>The gtkmumble port, version 0.10, is committed to the
 	    ports collection.</para>
 
 	  <programlisting>PORTNAME=	gtkmumble
 PORTVERSION=	0.10</programlisting>
 
 	  <para><makevar>PKGNAME</makevar> becomes
 	    <literal>gtkmumble-0.10</literal>.</para>
 
 	  <para>A security hole is discovered which requires a local
 	    FreeBSD patch. <makevar>PORTREVISION</makevar> is bumped
 	    accordingly.</para>
 
 	  <programlisting>PORTNAME=	gtkmumble
 PORTVERSIOn=	0.10
 PORTREVISION=	1</programlisting>
 
 	  <para><makevar>PKGNAME</makevar> becomes
 	    <literal>gtkmumble-0.10_1</literal></para>
 
 	  <para>A new version is released by the vendor, numbered 0.2
 	    (it turns out the author actually intended
 	    <literal>0.10</literal> to actually mean
 	    <literal>0.1.0</literal>, not <quote>what comes after
 	      0.9</quote> - oops, too late now). Since the new minor
 	    version <literal>2</literal> is numerically less than the
 	    previous version <literal>10</literal> the
 	    <makevar>PORTEPOCH</makevar> must be bumped to manually
 	    force the new package to be detected as "newer". Since it
 	    is a new vendor release of the code,
 	    <makevar>PORTREVISION</makevar> is reset to 0 (or removed
 	    from the makefile).</para>
 
 	  <programlisting>PORTNAME=	gtkmumble
 PORTVERSION=	0.2
 PORTEPOCH=	1</programlisting>
 
 	  <para><makevar>PKGNAME</makevar> becomes
 	    <literal>gtkmumble-0.2,1</literal></para>
 
 	  <para>The next release is 0.3. Since
 	    <makevar>PORTEPOCH</makevar> never decreases, the version
 	    variables are now:</para>
 	    
 	  <programlisting>PORTNAME=	gtkmumble
 PORTVERSION=	0.3
 PORTEPOCH=	1</programlisting>
 
 	  <para><makevar>PKGNAME</makevar> becomes
 	    <literal>gtkmumble-0.3,1</literal></para>
 
           <note>
             <para>If <makevar>PORTEPOCH</makevar> were reset
               to <literal>0</literal> with this upgrade, someone who had
               installed the gtkmumble-0.10_1 package would not detect
               the gtkmumble-0.3 package as newer, since
               <literal>3</literal> is still numerically less than
               <literal>10</literal>.</para>
 	  </note>
         </sect2>
       </sect1>
 
       <sect1>
         <title><makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar></title>
 
 	<para>Two optional variables, <makevar>PKGNAMEPREFIX</makevar> and
 	  <makevar>PKGNAMESUFFIX</makevar>, are combined with
 	  <makevar>PORTNAME</makevar> and
 	  <makevar>PORTVERSION</makevar> to 
           form <makevar>PKGNAME</makevar> as
           <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
           Make sure this conforms to our <link
           linkend="porting-pkgname">guidelines for a good package
           name</link>.  In particular, you are not allowed to use a
           hyphen (<literal>-</literal>) in
           <makevar>PORTVERSION</makevar>.  Also, if the package name
           has the <replaceable>language-</replaceable> or the
           <replaceable>compiled.specifics</replaceable> part, use
           <makevar>PKGNAMEPREFIX</makevar> and
           <makevar>PKGNAMESUFFIX</makevar>, respectively.  Do not make
           them part of <makevar>PORTNAME</makevar>.</para>
       </sect1>
 
       <sect1>
         <title><makevar>DISTNAME</makevar></title>
 
         <para><makevar>DISTNAME</makevar> is the name of the port as
           called by the authors of the software.
           <makevar>DISTNAME</makevar> defaults to
           <literal>${PORTNAME}-${PORTVERSION}</literal>, so override it if necessary.
           <makevar>DISTNAME</makevar> is only used in two places.
           First, the distribution file list
           (<makevar>DISTFILES</makevar>) defaults to
           <makevar>${DISTNAME}</makevar><makevar>${EXTRACT_SUFX}</makevar>.
           Second, the distribution file is expected to extract into a
           subdirectory named <makevar>WRKSRC</makevar>, which defaults
           to <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para>
 
 	<note>
           <para><makevar>PKGNAMEPREFIX</makevar> and
             <makevar>PKGNAMESUFFIX</makevar> do not affect
             <makevar>DISTNAME</makevar>.  Also note that when
             <makevar>WRKSRC</makevar> is equal to
             <filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>
             while the original source archive is named something other than
             <makevar>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</makevar>,
             you should probably leave <makevar>DISTNAME</makevar>
             alone&mdash; you are better off defining
             <makevar>DISTFILES</makevar> than having to set both
             <makevar>DISTNAME</makevar> and <makevar>WRKSRC</makevar>
             (and possibly <makevar>EXTRACT_SUFX</makevar>).</para>
 	</note>
       </sect1>
 
       <sect1>
         <title><makevar>CATEGORIES</makevar></title>
 
         <para>When a package is created, it is put under
           <filename>/usr/ports/packages/All</filename> and links are made from
           one or more subdirectories of
           <filename>/usr/ports/packages</filename>.  The names of these
           subdirectories are specified by the variable
           <makevar>CATEGORIES</makevar>.  It is intended to make life easier
           for the user when he is wading through the pile of packages on the
-          ftp site or the CD-ROM.  Please take a look at the existing <link
+          ftp site or the CDROM.  Please take a look at the existing <link
             linkend="porting-categories">categories</link> and pick the ones
           that are suitable for your port.</para>
 
         <para>This list also determines where in the ports tree the port is
           imported.  If you put more than one category here, it is assumed
           that the port files will be put in the subdirectory with the name in
           the first category.  See the <link
             linkend="porting-categories">categories</link> section for more
           discussion about how to pick the right categories.</para>
 
         <para>If your port truly belongs to something that is different from
           all the existing ones, you can even create a new category name.  In
           that case, please send mail to the &a.ports; to propose a new
           category.</para>
       </sect1>
 
       <sect1>
         <title><makevar>MASTER_SITES</makevar></title>
 
         <para>Record the directory part of the ftp/http-URL pointing at the
           original tarball in <makevar>MASTER_SITES</makevar>.  Do not forget
           the trailing slash (<filename>/</filename>)!</para>
 
         <para>The <command>make</command> macros will try to use this
           specification for grabbing the distribution file with
           <makevar>FETCH</makevar> if they cannot find it already on the
           system.</para>
 
         <para>It is recommended that you put multiple sites on this list,
           preferably from different continents.  This will safeguard against
           wide-area network problems, and we are even planning to add support
           for automatically determining the closest master site and fetching
           from there!</para>
 
         <para>If the original tarball is part of one of the popular
           archives such as X-contrib, GNU, or Perl CPAN, you may be able
           refer to those sites in an easy compact form using
           <makevar>MASTER_SITE_<replaceable>*</replaceable></makevar>
           (e.g., <makevar>MASTER_SITE_XCONTRIB</makevar> and
           <makevar>MASTER_SITE_PERL_GNU</makevar>).  Simply set
           <makevar>MASTER_SITES</makevar> to one of these variables and 
           <makevar>MASTER_SITE_SUBDIR</makevar> to the path within the
           archive.  Here is an example:</para>
 
         <programlisting>MASTER_SITES=         ${MASTER_SITE_XCONTRIB}
 MASTER_SITE_SUBDIR=   applications</programlisting>
 
         <para>These variables are defined in
           <filename>/usr/ports/Mk/bsd.sites.mk</filename>.  There are
           new archives added all the time, so make sure to check the
           latest version of this file before submitting a port.</para>
 
         <para>The user can also set the <makevar>MASTER_SITE_*</makevar>
           variables in <filename>/etc/make.conf</filename> to override our
           choices, and use their favorite mirrors of these popular archives
           instead.</para>
       </sect1>
 
       <sect1 id="porting-patchfiles">
         <title><makevar>PATCHFILES</makevar></title>
 
         <para>If your port requires some additional patches that are available
           by ftp or http, set <makevar>PATCHFILES</makevar> to the names of
           the files and <makevar>PATCH_SITES</makevar> to the URL of the
           directory that contains them (the format is the same as
           <makevar>MASTER_SITES</makevar>).</para>
 
         <para>If the patch is not relative to the top of the source tree
           (i.e., <makevar>WRKSRC</makevar>) because it contains some extra
           pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly. For
           instance, if all the pathnames in the patch have an extra
           <literal>foozolix-1.0/</literal> in front of the filenames, then set
           <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
 
         <para>Do not worry if the patches are compressed; they will be
           decompressed automatically if the filenames end with
           <filename>.gz</filename> or <filename>.Z</filename>.</para>
 
         <para>If the patch is distributed with some other files, such as
           documentation, in a gzip'd tarball, you cannot just use
           <makevar>PATCHFILES</makevar>.  If that is the case, add the name
           and the location of the patch tarball to
           <makevar>DISTFILES</makevar> and <makevar>MASTER_SITES</makevar>.
           Then, use the <makevar>EXTRA_PATCHES</makevar> variable to
           point to those files and <filename>bsd.port.mk</filename>
           will automatically apply them for you.  In particular, do
           <emphasis>not</emphasis> copy patch files into the
           <makevar>PATCHDIR</makevar> directory&mdash;that directory may
           not be writable.</para>
 
         <note>
           <para>Note that the tarball will have been extracted alongside the
             regular source by then, so there is no need to explicitly extract
             it if it is a regular gzip'd or compress'd tarball. If you do the
             latter, take extra care not to overwrite something that already
             exists in that directory.  Also, do not forget to add a command to
             remove the copied patch in the <maketarget>pre-clean</maketarget>
             target.</para>
         </note>
       </sect1>
 
       <sect1>
         <title><makevar>MAINTAINER</makevar></title>
 
         <para>Set your mail-address here.  Please.  <!-- smiley
           --><emphasis>:-)</emphasis></para>
 
         <para>For a detailed description of the responsibilities of maintainers,
           refer to the <ulink url="../handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
             Makefiles</ulink> section.</para>
       </sect1>
 
       <sect1>
         <title>Dependencies</title>
 
         <para>Many ports depend on other ports.  There are five variables that
           you can use to ensure that all the required bits will be on the
           user's machine.  There are also some pre-supported dependency
           variables for common cases, plus a few more to control the behaviour
           of dependencies.</para>
 
         <sect2>
           <title><makevar>LIB_DEPENDS</makevar></title>
 
           <para>This variable specifies the shared libraries this port depends
             on.  It is a list of
             <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
             tuples where <replaceable>lib</replaceable> is the name of the
             shared library, <replaceable>dir</replaceable> is the
             directory in which to find it in case it is not available, and
             <replaceable>target</replaceable> is the target to call in that
             directory.  For example, <programlisting> LIB_DEPENDS=
               jpeg.9:${PORTSDIR}/graphics/jpeg:install</programlisting>
             will check for a shared jpeg library with major version 9, and
             descend into the <filename>graphics/jpeg</filename> subdirectory
             of your ports tree to build and install it if it is not found.
             The <replaceable>target</replaceable> part can be omitted if it is
             equal to <makevar>DEPENDS_TARGET</makevar> (which defaults to
             <literal>install</literal>).</para>
 
           <note>
             <para>The <replaceable>lib</replaceable> part is an argument given
               to <command>ldconfig -r | grep -wF</command>.  There shall be no
               regular expressions in this variable.</para>
           </note>
 
           <para>The dependency is checked twice, once from within the
             <maketarget>extract</maketarget> target and then from within the
             <maketarget>install</maketarget> target.  Also, the name of the
             dependency is put into the package so that
             <command>pkg_add</command> will automatically install it if it is
             not on the user's system.</para>
         </sect2>
 
         <sect2>
           <title><makevar>RUN_DEPENDS</makevar></title>
 
           <para>This variable specifies executables or files this port depends
             on during run-time.  It is a list of
             <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
             tuples where <replaceable>path</replaceable> is the name of the
             executable or file, <replaceable>dir</replaceable> is the
             directory in which to find it in case it is not available, and
             <replaceable>target</replaceable> is the target to call in that
             directory.  If <replaceable>path</replaceable> starts with a slash
             (<literal>/</literal>), it is treated as a file and its existence
             is  tested with <command>test -e</command>; otherwise, it is
             assumed to be an executable, and <command>which -s</command> is
             used to determine if the program exists in the user's search
             path.</para>
 
           <para>For example,</para>
 
             <programlisting>RUN_DEPENDS=   ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
                wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting>
 
           <para>will check if the file or directory
             <filename>/usr/local/etc/innd</filename> exists, and build and
             install it from the <filename>news/inn</filename> subdirectory of
             the ports tree if it is not found.  It will also see if an
             executable called <command>wish8.0</command> is in your search
             path, and descend into the <filename>x11-toolkits/tk80</filename>
             subdirectory of your ports tree to build and install it if it is
             not found.</para>
 
           <note>
             <para>In this case, <command>innd</command> is actually an
               executable; if an executable is in a place that is not expected
               to be in a normal user's search path, you should use the full
               pathname.</para>
           </note>
 
           <para>The dependency is checked from within the
             <maketarget>install</maketarget> target.  Also, the name of the
             dependency is put in to the  package so that
             <command>pkg_add</command> will automatically install it if it is
             not on the user's system.  The <replaceable>target</replaceable>
             part can be omitted if it is the same as
             <makevar>DEPENDS_TARGET</makevar>.</para>
         </sect2>
 
         <sect2>
           <title><makevar>BUILD_DEPENDS</makevar></title>
 
           <para>This variable specifies executables or files this port
             requires to build.  Like <makevar>RUN_DEPENDS</makevar>, it is a
             list of
             <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
             tuples. For example, <programlisting> BUILD_DEPENDS=
               unzip:${PORTSDIR}/archivers/unzip</programlisting> will check
             for an executable called <command>unzip</command>, and descend
             into the <filename>archivers/unzip</filename> subdirectory of your
             ports tree to build and install it if it is not found.</para>
 
           <note>
             <para>&ldquo;build&rdquo; here means everything from extraction to
               compilation.  The dependency is checked from within the
               <maketarget>extract</maketarget> target.  The
               <replaceable>target</replaceable> part can be omitted if it is
               the same as <makevar>DEPENDS_TARGET</makevar></para>
           </note>
         </sect2>
 
         <sect2>
           <title><makevar>FETCH_DEPENDS</makevar></title>
 
           <para>This variable specifies executables or files this port
             requires to fetch.  Like the previous two, it is a list of
             <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>
             tuples.  For example, <programlisting> FETCH_DEPENDS=
               ncftp2:${PORTSDIR}/net/ncftp2</programlisting> will check for an
             executable called <command>ncftp2</command>, and descend into the
             <filename>net/ncftp2</filename> subdirectory of your ports tree to
             build and install it if it is not found.</para>
 
           <para>The dependency is checked from within the
             <maketarget>fetch</maketarget> target.  The
             <replaceable>target</replaceable> part can be omitted if it is the
             same as <makevar>DEPENDS_TARGET</makevar>.</para>
         </sect2>
 
         <sect2>
           <title><makevar>DEPENDS</makevar></title>
 
           <para>If there is a dependency that does not fall into either of the
             above four categories, or your port requires having the source of
             the other port extracted in addition to having it installed,
             then use this variable.  This is a list of
             <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>,
             as there is nothing to check, unlike the previous four.  The
             <replaceable>target</replaceable> part can be omitted if it is the
             same as <makevar>DEPENDS_TARGET</makevar>.</para>
         </sect2>
 
         <sect2>
           <title>Common dependency variables</title>
 
           <para>Define <literal>USE_XLIB=yes</literal> if your port requires
             the X Window System to be installed (it is implied by
             <makevar>USE_IMAKE</makevar>).  Define
             <literal>USE_GMAKE=yes</literal> if your port requires GNU
             <command>make</command> instead of BSD <command>make</command>.
             Define <literal>USE_AUTOCONF=yes</literal> if your port requires
             GNU autoconf to be run.  Define <literal>USE_QT=yes</literal> if
             your port uses the latest qt toolkit.  Use
             <literal>USE_PERL5=yes</literal> if your port requires version 5
             of the perl language.  (The last is especially important since
             some versions of FreeBSD have perl5 as part of the base system
             while others do not.)</para>
         </sect2>
 
         <sect2>
           <title>Notes on dependencies</title>
 
           <para>As mentioned above, the default target to call when a
             dependency is required is <maketarget>DEPENDS_TARGET</maketarget>.
             It defaults to <literal>install</literal>.  This is a user
             variable; it is never defined in a port's
             <filename>Makefile</filename>.  If your port needs a special way
             to handle a dependency, use the <literal>:target</literal> part of
             the <makevar>*_DEPENDS</makevar> variables instead of redefining
             <makevar>DEPENDS_TARGET</makevar>.</para>
 
           <para>When you type <command>make clean</command>, its dependencies
             are automatically cleaned too.  If you do not wish this to happen,
             define the variable <makevar>NOCLEANDEPENDS</makevar> in your
             environment.</para>
 
           <para>To depend on another port unconditionally, use the
             variable <makevar>${NONEXISTENT}</makevar> as the first field 
             of <makevar>BUILD_DEPENDS</makevar> or
             <makevar>RUN_DEPENDS</makevar>.  Use this only when you need to
             the to get to the source of the other port.  You can often save
             compilation time by specifying the target too.  For
             instance
 
             <programlisting>BUILD_DEPENDS=   ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>
 
             will always descend to the JPEG port and extract it.</para>
 
           <para>Do not use <makevar>DEPENDS</makevar> unless there is no other
             way the behaviour you want can be accomplished.  It will cause the
             other port to always be built (and installed, by default), and the
             dependency will go into the packages as well.  If this is really
             what you need, you should probably write it as
             <literal>BUILD_DEPENDS</literal> and
             <literal>RUN_DEPENDS</literal> instead&mdash;at least the
             intention will be clear.</para>
         </sect2>
       </sect1>
 
      <sect1>
       <title>Optional dependencies</title>
       
       <para>Some large applications can be built in a number of
 	configurations, adding functionality if one of a number of
 	libraries or applications is available. Since not all users
 	want those libraries or applications, the ports system
 	provides hooks that the port author can use to decide which
 	configuration should be built. Supporting these properly will
 	make uses happy, and effectively provide 2 or more ports for the
 	price of one.</para>
 	
       <para>The easiest of these to use is
 	<makevar>WITHOUT_X11</makevar>. If the port can be built both
 	with and without X support, then it should normally be built
 	with X support. If <makevar>WITHOUT_X11</makevar> is defined,
 	then the version that does not have X support should be
 	built.</para>
 	
       <para>Various parts of GNOME have such knobs, though they are
 	slightly more difficult to use. The variables to use in the
 	<filename>Makefile</filename> are <makevar>WANT_*</makevar>
 	and <makevar>HAVE_*</makevar>. If the application can be
 	built both with or without one of the dependencies listed
 	below, then the <filename>Makefile</filename> should set
 	<makevar>WANT_PKG</makevar>, and should build the version that
 	uses <makevar>PKG</makevar> if <makevar>HAVE_PKG</makevar>
 	is defined.</para>
 	
       <para>The <makevar>WANT_*</makevar> variables currently
 	supported this way are <makevar>WANT_GLIB</makevar>,
 	<makevar>WANT_GTK</makevar>, <makevar>WANT_ESOUND</makevar>,
 	<makevar>WANT_IMLIB</makevar>, and
 	<makevar>WANT_GNOME</makevar>.</para>
       </sect1>
 
       <sect1>
         <title>Building mechanisms</title>
 
         <para>If your package uses GNU <command>make</command>, set
           <literal>USE_GMAKE=yes</literal>.  If your package uses
           <command>configure</command>, set
           <literal>HAS_CONFIGURE=yes</literal>.  If your package uses GNU
           <command>configure</command>, set
           <literal>GNU_CONFIGURE=yes</literal> (this implies
           <literal>HAS_CONFIGURE</literal>).  If you want to give some extra
           arguments to <command>configure</command> (the default argument list
           <literal>--prefix=&dollar;{PREFIX}</literal> for GNU
           <command>configure</command> and empty for non-GNU
           <command>configure</command>), set those extra arguments in
           <makevar>CONFIGURE_ARGS</makevar>.  If your package uses GNU
           <command>autoconf</command>, set
           <literal>USE_AUTOCONF=yes</literal>.  This implies
           <makevar>GNU_CONFIGURE</makevar>, and will cause
           <command>autoconf</command> to be run before
           <command>configure</command>.</para>
 
         <para>If your package is an X application that creates
           <filename>Makefile</filename>s from <filename>Imakefile</filename>s
           using <command>imake</command>, then set
           <literal>USE_IMAKE=yes</literal>.  This will cause the configure
           stage to automatically do an <command>xmkmf -a</command>.  If the
           <option>-a</option> flag is a problem for your port, set
           <literal>XMKMF=xmkmf</literal>. If the port uses
           <command>imake</command> but does not understand the
           <maketarget>install.man</maketarget> target,
           <literal>NO_INSTALL_MANPAGES=yes</literal> should be set. In
           addition, the author of the original port should be shot. <!--
           smiley --><emphasis>:-&gt;</emphasis></para>
 
         <para>If your port's source <filename>Makefile</filename> has
           something else than <maketarget>all</maketarget> as the main build
           target, set <makevar>ALL_TARGET</makevar> accordingly.  Same goes
           for <maketarget>install</maketarget> and
           <makevar>INSTALL_TARGET</makevar>.</para>
       </sect1>
     </chapter>
 
     <chapter>
       <title>Special considerations</title>
 
       <para>There are some more things you have to take into account when you
         create a port.  This section explains the most common of those.</para>
 
       <sect1 id="porting-shlibs">
         <title>Shared Libraries</title>
 
         <para>If your port installs one or more shared libraries, define a
           <makevar>INSTALLS_SHLIB</makevar> make variable, which will instruct
           a <filename>bsd.port.mk</filename> to run
           <literal>&dollar;{LDCONFIG} -m</literal> on the directory where the
           new library is installed (usually
           <filename><makevar>PREFIX</makevar>/lib</filename>) during
           <maketarget>post-install</maketarget> target to register it into the
           shared library cache.  This variable, when defined, will also
           facilitate addition of an appropriate
           <literal>@exec /sbin/ldconfig -m</literal> and
           <literal>@unexec /sbin/ldconfig -R</literal> pair into your
           <filename>pkg-plist</filename> file, so that a user who installed
           the package can start using the shared library immediately and
           deinstallation will not cause the system to still believe the
           library is there.</para>
 
         <para>If you need, you can override default location where the new
           library is installed by defining <makevar>LDCONFIG_DIRS</makevar>
           make variable, which should contain a list of directories into which
           shared libraries are to be installed.  For example if your port
           installs shared libraries into
           <filename><makevar>PREFIX</makevar>/lib/foo</filename> and
           <filename><makevar>PREFIX</makevar>/lib/bar</filename> directories
           you could use the following in your
           <filename>Makefile</filename>:</para>
 
         <programlisting>INSTALLS_SHLIB= yes
 LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 
         <para>Note that content of <makevar>LDCONFIG_DIRS</makevar> is passed
           through &man.sed.1; just like the rest of <filename>pkg-plist</filename>,
           so <makevar>PLIST_SUB</makevar> substitutions also apply here.  It is
           recommended that you use <literal>%%PREFIX%%</literal> for
           <makevar>PREFIX</makevar>, <literal>%%LOCALBASE%%</literal> for
           <makevar>LOCALBASE</makevar> and <literal>%%X11BASE%%</literal> for
           <makevar>X11BASE</makevar>.</para>
       </sect1>
     </chapter>
 
 <!--
 
     <chapter>
       <title>ELF support</title>
 
       <para>Since FreeBSD changed to an ELF binary format shortly after
         3.0-RELEASE, we need to convert many ports that build shared
         libraries to support ELF.  Complicating this task is that a 3.0
         system can run as both ELF and a.out, and we wish to unofficially
         support the 2.2 branch as long as possible.  Below are the guidelines on
         how to convert a.out only ports to support both a.out and ELF
         compilation.</para>
 
       <para>Some part of this list is only applicable during the conversion,
         but will be left here for a while for reference in case you have come
         across some old port you wish to upgrade.</para>
 
       <sect1>
         <title>Moving a.out libraries out of the way</title>
 
         <para>Any a.out libraries should be moved out of
           <filename>/usr/local/lib</filename> and similar to an
           <filename>aout</filename> subdirectory.  (If you do not move them out
           of the way, ELF ports will happily overwrite a.out libraries.) The
           <maketarget>move-aout-libs</maketarget> target in the 3.0-CURRENT
           <filename>src/Makefile</filename> (called from
           <maketarget>aout-to-elf</maketarget>) will do this for you.  It will
           only move a.out libs so it is safe to call it on a system with both
           ELF and a.out libs in the standard directories.</para>
       </sect1>
 
       <sect1>
         <title>Format</title>
 
         <para>The ports tree will build packages in the format the machine is
           in.  This means a.out for 2.2 and a.out or ELF for 3.0 depending on
           what <command>`objformat`</command> returns.  Also, once users move
           a.out libraries to a subdirectory, building a.out libraries will be
           unsupported.  (I.e., it may still work if you know what you are
           doing, but you are on your own.)</para>
 
         <note>
           <para>If a port only works for a.out, set
             <makevar>BROKEN_ELF</makevar> to a string describing the reason
             why.  Such ports will be skipped during a build on an ELF
             system.</para>
         </note>
       </sect1>
 
       <sect1>
         <title><makevar>PORTOBJFORMAT</makevar></title>
 
         <para><filename>bsd.port.mk</filename> will set
           <makevar>PORTOBJFORMAT</makevar> to <literal>aout</literal> or
           <literal>elf</literal> and export it in the environments
           <envar>CONFIGURE_ENV</envar>, <envar>SCRIPTS_ENV</envar> and
           <envar>MAKE_ENV</envar>.  (It's always going to be
           <literal>aout</literal> in 2.2-STABLE).  It is also passed to
           <maketarget>PLIST_SUB</maketarget> as
           <literal>PORTOBJFORMAT=${PORTOBJFORMAT}</literal>.  (See comment on
           <literal>ldconfig</literal> lines below.)</para>
 
         <para>The variable is set using this line in
           <filename>bsd.port.mk</filename>:</para>
 
         <programlisting>PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</programlisting>
 
         <para>Ports' make processes should use this variable to decide what to
           do.  However, if the port's <filename>configure</filename> script
           already automatically detects an ELF system, it is not necessary to
           refer to <makevar>PORTOBJFORMAT</makevar>.</para>
       </sect1>
 
       <sect1>
         <title>Building shared libraries</title>
 
         <para>The following are differences in handling shared libraries for
           a.out and ELF.</para>
 
         <itemizedlist>
           <listitem>
             <para>Shared library versions</para>
 
             <para>An ELF shared library should be called
               <filename>libfoo.so.<replaceable>M</replaceable></filename>
               where <replaceable>M</replaceable> is the single version number,
               and an a.out library should be called
               <filename>libfoo.so.<replaceable>M</replaceable>.<replaceable>N</replaceable></filename>
               where <replaceable>M</replaceable> is the major version and
               <replaceable>N</replaceable> is the minor version number.
               Do not mix those; <emphasis>never</emphasis> install an ELF
               shared library called
               <filename>libfoo.so.<replaceable>N</replaceable>.<replaceable>M</replaceable></filename>
               or an a.out shared library (or symlink) called
               <filename>libfoo.so.<replaceable>N</replaceable></filename>.</para>
           </listitem>
 
           <listitem>
             <para>Linker command lines</para>
 
             <para>Assuming <command>cc -shared</command> is used rather than
               <command>ld</command> directly, the only difference is that you
               need to add
               <option>-Wl,-<replaceable>soname,libfoo.so.M</replaceable></option>
               on the command line for ELF.</para>
             </listitem>
         </itemizedlist>
 
         <para>You need to install a symlink from
           <filename>libfoo.so</filename> to
           <filename>libfoo.so.<replaceable>N</replaceable></filename> to make
           ELF linkers happy.  Since it should be listed in
           <filename>pkg-plist</filename> too, and it won't hurt in the a.out case
           (some ports even require the link for dynamic loading), you should
           just make this link regardless of the setting of
           <makevar>PORTOBJFORMAT</makevar>.</para>
       </sect1>
 
       <sect1>
         <title><makevar>LIB_DEPENDS</makevar></title>
 
         <para>All port Makefiles are edited to remove minor numbers from
           <makevar>LIB_DEPENDS</makevar>, and also to have the regexp support
           removed.  (E.g., <literal>foo\\.1\\.\\(33|40\\)</literal> becomes
           <literal>foo.2</literal>.)  They will be matched using <command>grep
             -wF</command>.</para>
       </sect1>
 
       <sect1>
         <title><filename>pkg-plist</filename></title>
 
         <para><filename>pkg-plist</filename> should contain the short (ELF) shlib
           names if the a.out minor number is zero, and the long (a.out) names
           otherwise.  <filename>bsd.port.mk</filename> will automatically add
           <literal>.0</literal> to the end of short shlib lines if
           <makevar>PORTOBJFORMAT</makevar> equals <literal>aout</literal>, and
           will delete the minor number from long shlib names if
           <makevar>PORTOBJFORMAT</makevar> equals
           <literal>elf</literal>.</para>
 
         <para>In cases where you really need to install shlibs with two
           versions on an ELF system or those with one version on an a.out
           system (for instance, ports that install compatibility libraries for
           other operating systems), define the variable
           <makevar>NO_FILTER_SHLIBS</makevar>.  This will turn off the editing
           of <filename>pkg-plist</filename> mentioned in the previous
           paragraph.</para>
       </sect1>
 
       <sect1>
         <title><literal>ldconfig</literal></title>
 
         <para>The <literal>ldconfig</literal> line in Makefiles should
           read:</para>
 
         <programlisting>${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
 
         <para>In <filename>pkg-plist</filename> it should read;</para>
 
         <programlisting>@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ...
 @unexec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -R</programlisting>
 
         <para>This is to ensure that the correct <command>ldconfig</command>
           will be called depending on the format of the package, not the
           default format of the system.</para>
       </sect1>
     </chapter>
 
 -->
 
     <chapter id="porting-masterdir">
       <title><makevar>MASTERDIR</makevar></title>
 
       <para>If your port needs to build slightly different versions of
         packages by having a variable (for instance, resolution, or paper
         size) take different values, create one subdirectory per package to
         make it easier for users to see what to do, but try to share as many
         files as possible between ports.  Typically you only need a very short
         <filename>Makefile</filename> in all but one of the directories if you
         use variables cleverly.  In the sole <filename>Makefiles</filename>,
         you can use <makevar>MASTERDIR</makevar> to specify the directory
         where the rest of the files are.  Also, use a variable as part of
         <link linkend="porting-pkgname"><makevar>PKGNAMESUFFIX</makevar></link> so
         the packages will have different names.</para>
 
       <para>This will be best demonstrated by an example.  This is part of
         <filename>japanese/xdvi300/Makefile</filename>;</para>
 
       <programlisting>PORTNAME=       xdvi
 PORTVERSION=    17
 PKGNAMEPREFIX=  ja-
 PKGNAMESUFFIX=  ${RESOLUTION}
  :
 # default
 RESOLUTION?=   300
 .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \
        ${RESOLUTION} != 300 && ${RESOLUTION} != 400
        @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
        @${ECHO} "Possible values are: 118, 240, 300 (default) and 400."
        @${FALSE}
 .endif</programlisting>
 
       <para><filename>japanese/xdvi300</filename> also has all the regular
         patches, package files, etc.  If you type <command>make</command>
         there, it will take the default value for the resolution (300) and
         build the port normally.</para>
 
       <para>As for other resolutions, this is the <emphasis>entire</emphasis>
         <filename>xdvi118/Makefile</filename>:</para>
 
       <programlisting>RESOLUTION=     118
 MASTERDIR=      ${.CURDIR}/../xdvi300
 
 .include ${MASTERDIR}/Makefile</programlisting>
 
       <para>(<filename>xdvi240/Makefile</filename> and
         <filename>xdvi400/Makefile</filename> are similar).  The
         <makevar>MASTERDIR</makevar> definition tells
         <filename>bsd.port.mk</filename> that the regular set of
         subdirectories like <makevar>FILESDIR</makevar> and
         <makevar>SCRIPTDIR</makevar> are to be found under
         <filename>xdvi300</filename>.  The <literal>RESOLUTION=118</literal>
         line will override the <literal>RESOLUTION=300</literal> line in
         <filename>xdvi300/Makefile</filename> and the port will be built with
         resolution set to 118.</para>
     </chapter>
 
     <chapter>
       <title>Shared library versions</title>
 
       <para>Please read our <ulink url="../handbook/policies-shlib.html">policy on
         shared library versioning</ulink> to understand what to do with
         shared library versions in general.  Do not blindly assume software
         authors know what they are doing; many of them do not.  It is very
         important that these details are carefully considered, as we have
         quite a unique situation where we are trying to have dozens of
         potentially incompatible software pairs co-exist. Careless port
         imports have caused great trouble regarding shared libraries in the
         past (ever wondered why the port <filename>jpeg-6b</filename> has a
         shared library version of 9?). If in doubt, send a message to the
         &a.ports;.  Most of the time, your job ends by determining the right
         shared library version and making appropriate patches to implement
         it.</para>
 
 <!--
       <para>However, if there is a port which is a different version of the
         same software already in the tree, the situation is much more complex.
         In short, the FreeBSD implementation does not allow the user to
         specify to the linker which version of shared library to link against
         (the linker will always pick the highest numbered version).  This
         means, if there is a <filename>libfoo.so.3.2</filename> and
         <filename>libfoo.so.4.0</filename> in the system, there is no way to
         tell the linker to link a particular application to
         <filename>libfoo.so.3.2</filename>.  It is essentially completely
         overshadowed in terms of compilation-time linkage.  In this case, the
         only solution  is to rename the <emphasis>base</emphasis> part of the
         shared library.  For instance, change
         <filename>libfoo.so.4.0</filename> to
         <filename>libfoo4.so.1.0</filename> so both version 3.2 and 4.0 can be
         linked from other ports.</para>
 -->
     </chapter>
 
     <chapter id="porting-manpages">
       <title>Manpages</title>
 
       <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically add
         any manpages to <filename>pkg-plist</filename> (this means you must
         <emphasis>not</emphasis> list manpages in the
         <filename>pkg-plist</filename>&mdash;see <link
           linkend="porting-plist">generating PLIST</link> for more).  It also
         makes the install stage automatically compress or uncompress manpages
         depending on the setting of <makevar>NOMANCOMPRESS</makevar> in
         <filename>/etc/make.conf</filename>.</para>
 
       <para>If your port tries to install multiple names for manpages using
         symlinks or hardlinks, you must use the <makevar>MLINKS</makevar>
         variable to identify these.  The link installed by your port will
         be destroyed and recreated by <filename>bsd.port.mk</filename>
         to make sure it points to the correct file.  Any manpages
         listed in MLINKS must not be listed in the
         <filename>pkg-plist</filename>.</para>
 
       <para>To specify whether the manpages are compressed upon installation,
         use the <makevar>MANCOMPRESSED</makevar> variable. This variable can
         take three values, <literal>yes</literal>, <literal>no</literal> and
         <literal>maybe</literal>. <literal>yes</literal> means manpages are
         already installed compressed, <literal>no</literal> means they are
         not, and <literal>maybe</literal> means the software already respects
         the value of <makevar>NOMANCOMPRESS</makevar> so
         <filename>bsd.port.mk</filename> does not have to do anything
         special.</para>
 
       <para><makevar>MANCOMPRESSED</makevar> is automatically set to
         <literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set and
         <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to
         <literal>no</literal> otherwise.  You do not have to explicitly define
         it unless the default is not suitable for your port.</para>
 
       <para>If your port anchors its man tree somewhere other than
         <makevar>PREFIX</makevar>, you can use the
         <makevar>MANPREFIX</makevar> to set it.  Also, if only manpages in
         certain sections go in a non-standard place, such as some Perl modules
         ports, you can set individual man paths using
         <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
         <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
         <literal>L</literal> or <literal>N</literal>).</para>
 
       <para>If your manpages go to language-specific subdirectories, set the
         name of the languages to <makevar>MANLANG</makevar>.  The value of
         this variable defaults to <literal>""</literal> (i.e., English
         only).</para>
 
       <para>Here is an example that puts it all together.</para>
 
       <programlisting>MAN1=          foo.1
 MAN3=          bar.3
 MAN4=          baz.4
 MLINKS=        foo.1 alt-name.8
 MANLANG=       "" ja
 MAN3PREFIX=    ${PREFIX}/share/foobar
 MANCOMPRESSED= yes</programlisting>
 
       <para>This states that six files are installed by this port;</para>
 
           <programlisting>${PREFIX}/man/man1/foo.1.gz
 ${PREFIX}/man/ja/man1/foo.1.gz
 ${PREFIX}/share/foobar/man/man3/bar.3.gz
 ${PREFIX}/share/foobar/man/ja/man3/bar.3.gz
 ${PREFIX}/man/man4/baz.4.gz
 ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 
       <para>Additionally <filename>${PREFIX}/man/man8/alt-name.8.gz</filename>
         may or may not be installed by your port.  Regardless, a
         symlink will be made to join the foo(1) manpage and
         alt-name(8) manpage.</para>
 
     </chapter>
 
     <chapter id="porting-motif">
       <title>Ports that require Motif</title>
 
       <para>There are many programs that require a Motif library (available
         from several commercial vendors, while there is a free clone reported
         to be able to run many applications in
         <filename>x11-toolkits/lesstif</filename>) to compile.  Since it is a
         popular toolkit and their licenses usually permit redistribution of
         statically linked binaries, we have made special provisions for
         handling ports that require Motif in a way that we can easily compile
         binaries linked either dynamically (for people who are compiling from
         the port) or statically (for people who distribute packages).</para>
 
       <sect1>
         <title><makevar>REQUIRES_MOTIF</makevar></title>
 
         <para>If your port requires Motif, define this variable in the
           Makefile.  This will prevent people who do not own a copy of Motif
           from even attempting to build it.</para>
       </sect1>
 
       <sect1>
         <title><makevar>MOTIFLIB</makevar></title>
 
         <para>This variable will be set by <filename>bsd.port.mk</filename> to
           be the appropriate reference to the Motif library.  Please patch the
           source to use this wherever the Motif library is referenced in the
           <filename>Makefile</filename> or
           <filename>Imakefile</filename>.</para>
 
         <para>There are two common cases:</para>
 
         <itemizedlist>
           <listitem>
             <para>If the port refers to the Motif library as
               <literal>-lXm</literal> in its <filename>Makefile</filename> or
               <filename>Imakefile</filename>, simply substitute
               <literal>&dollar;{MOTIFLIB}</literal> for it.</para>
           </listitem>
 
           <listitem>
             <para>If the port uses <literal>XmClientLibs</literal> in its
               <filename>Imakefile</filename>, change it to
               <literal>&dollar;{MOTIFLIB} &dollar;{XTOOLLIB}
                 &dollar;{XLIB}</literal>.</para>
           </listitem>
 
         </itemizedlist>
 
         <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands to
           <literal>-L/usr/X11R6/lib -lXm</literal> or
           <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need to
           add <literal>-L</literal> or <literal>-l</literal> in front.</para>
       </sect1>
     </chapter>
 
     <chapter>
       <title>X11 fonts</title>
 
       <para>If your port installs fonts for the X Window system, put them in
         <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>.
         This directory is new to XFree86 release 3.3.3.  If it does not exist,
         please create it, and print out a message urging the user to update
         their XFree86 to 3.3.3 or newer, or at least add this directory to the
         font path in <filename>/etc/XF86Config</filename>.</para>
     </chapter>
 
     <chapter id="porting-info">
       <title>Info files</title>
 
       <para>The new version of texinfo (included in 2.2.2-RELEASE and onwards)
         contains a utility called <command>install-info</command> to add and
         delete entries to the <filename>dir</filename> file.  If your port
         installs any info documents, please follow these instructions so your
         port/package will correctly update the user's
         <filename><makevar>PREFIX</makevar>/info/dir</filename> file.  (Sorry
         for the length of this section, but is it imperative to weave all the
         info files together.  If done correctly, it will produce a
         <emphasis>beautiful</emphasis> listing, so please bear with me!</para>
 
       <para>First, this is what you (as a porter) need to know</para>
 
       <screen>&prompt.user; <userinput>install-info --help</userinput>
 install-info [OPTION]... [INFO-FILE [DIR-FILE]]
   Install INFO-FILE in the Info directory file DIR-FILE.
 
 Options:
 --delete          Delete existing entries in INFO-FILE;
                     don't insert any new entries.
  :
 --entry=TEXT      Insert TEXT as an Info directory entry.
  :
 --section=SEC     Put this file's entries in section SEC of the directory. :</screen>
 
       <note>
         <para>This program will not actually <emphasis>install</emphasis> info
           files; it merely inserts or deletes entries in the
           <filename>dir</filename> file.</para>
       </note>
 
       <para>Here's a seven-step procedure to convert ports to use
         <command>install-info</command>.
         <filename>editors/emacs</filename> will be used as an
         example.</para>
 
       <procedure>
         <step>
           <para>Look at the texinfo sources and make a patch to insert
             <literal>@dircategory</literal> and <literal>@direntry</literal>
             statements to files that do not have them.  This is part of my
             patch:</para>
 
           <programlisting>--- ./man/vip.texi.org  Fri Jun 16 15:31:11 1995
 +++ ./man/vip.texi      Tue May 20 01:28:33 1997
 @@ -2,6 +2,10 @@
 
  @setfilename ../info/vip
  @settitle VIP
 +@dircategory The Emacs editor and associated tools
 +@direntry
 +* VIP: (vip).          A VI-emulation for Emacs.
 +@end direntry
 
  @iftex
  @finalout
  :</programlisting>
 
           <para>The format should be self-explanatory.  Many authors leave a
             <filename>dir</filename> file in the source tree that contains all
             the entries you need, so look around before you try to write your
             own.  Also, make sure you look into related ports and make the
             section names and entry indentations consistent (we recommend that
             all entry text start at the 4th tab stop).</para>
 
           <note>
             <para>Note that you can put only one info entry per file because
               of a bug in <command>install-info --delete</command> that
               deletes only the first entry if you specify multiple entries in
               the <email>@direntry</email> section.</para>
           </note>
 
           <para>You can give the <literal>dir</literal> entries to
             <command>install-info</command> as arguments
             (<option>--section</option> and <option>--entry</option>) instead
             of patching the texinfo sources.  This probably is not a good
             idea for ports because you need to duplicate the same information
             in <emphasis>three</emphasis> places
             (<filename>Makefile</filename> and
             <literal>@exec</literal>/<literal>@unexec</literal> of
             <filename>pkg-plist</filename>; see below).  However, if you have
             Japanese (or other multibyte encoding) info files, you will have
             to use the extra arguments to <command>install-info</command>
             because <command>makeinfo</command> cannot handle those texinfo
             sources.  (See <filename>Makefile</filename> and
             <filename>pkg-plist</filename> of <filename>japanese/skk</filename>
             for examples on how to do this).</para>
         </step>
 
         <step>
           <para>Go back to the port directory and do a <command>make clean;
               make</command> and verify that the info files are regenerated
             from the texinfo sources. Since the texinfo sources are newer than
             the info files, they should be rebuilt when you type
             <command>make</command>; but many <filename>Makefile</filename>s
             do not include correct dependencies for info files.  In
             <command>emacs</command>' case, it was necessary to patch the main
             <filename>Makefile.in</filename> so it would descend into the
             <filename>man</filename> subdirectory to rebuild the info
             pages.</para>
 
           <programlisting>--- ./Makefile.in.org   Mon Aug 19 21:12:19 1996
 +++ ./Makefile.in       Tue Apr 15 00:15:28 1997
 @@ -184,7 +184,7 @@
  # Subdirectories to make recursively.  `lisp' is not included
  # because the compiled lisp files are part of the distribution
  # and you cannot remake them without installing Emacs first.
 -SUBDIR = lib-src src
 +SUBDIR = lib-src src man
 
  # The makefiles of the directories in $SUBDIR.
  SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile
  lwlib/Makefile
 --- ./man/Makefile.in.org       Thu Jun 27 15:27:19 1996
 +++ ./man/Makefile.in   Tue Apr 15 00:29:52 1997
 @@ -66,6 +66,7 @@
  ${srcdir}/gnu1.texi \
  ${srcdir}/glossary.texi
 
 +all: info
  info: $(INFO_TARGETS)
 
  dvi: $(DVI_TARGETS)</programlisting>
 
           <para>The second hunk was necessary because the default target in
             the <filename>man</filename> subdir is called
             <maketarget>info</maketarget>, while the main
             <filename>Makefile</filename> wants to call
             <maketarget>all</maketarget>.  The installation of the
             <filename>info</filename> info file was also removed because we
             already have one with the same name in
             <filename>/usr/share/info</filename> (that patch is not shown
             here).</para>
         </step>
 
         <step>
           <para>If there is a place in the <filename>Makefile</filename> that
             is installing the <filename>dir</filename> file, delete it.  Your
             port may not be doing it.  Also, remove any commands that are
             otherwise mucking around with the <filename>dir</filename>
             file.</para>
 
           <programlisting>--- ./Makefile.in.org   Mon Aug 19 21:12:19 1996
 +++ ./Makefile.in       Mon Apr 14 23:38:07 1997
 @@ -368,14 +368,8 @@
         if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
         then \
           (cd ${infodir};  \
 -          if [ -f dir ]; then \
 -            if [ ! -f dir.old ]; then mv -f dir dir.old; \
 -            else mv -f dir dir.bak; fi; \
 -          fi; \
            cd ${srcdir}/info ; \
 -          (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir);
 \
 -          (cd $${thisdir}; chmod a+r ${infodir}/dir); \
            for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
              (cd $${thisdir}; \
               ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
               chmod a+r ${infodir}/$$f); \</programlisting>
         </step>
 
         <step>
           <para>(This step is only necessary if you are modifying an existing
             port.) Take a look at <filename>pkg-plist</filename> and delete
             anything that is trying to patch up <filename>info/dir</filename>.
             They may be in <filename>pkg-install</filename> or some other
             file, so search extensively.</para>
 
           <programlisting>Index: pkg-plist
 ===================================================================
 RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
 retrieving revision 1.15
 diff -u -r1.15 pkg-plist
 --- pkg-plist       1997/03/04 08:04:00     1.15
 +++ pkg-plist       1997/04/15 06:32:12
 @@ -15,9 +15,6 @@
  man/man1/emacs.1.gz
  man/man1/etags.1.gz
  man/man1/ctags.1.gz
 -@unexec cp %D/info/dir %D/info/dir.bak
 -info/dir
 -@unexec cp %D/info/dir.bak %D/info/dir
  info/cl
  info/cl-1
  info/cl-2</programlisting>
         </step>
 
         <step>
           <para>Add a <maketarget>post-install</maketarget> target to the
             <filename>Makefile</filename> to call
             <maketarget>install-info</maketarget> with the installed
             info files.  (It is no longer necessary to create the
             <filename>dir</filename> file yourself;
             <command>install-info</command> automatically creates this
             file if it does not exist.)</para>
 
           <programlisting>Index: Makefile
 ===================================================================
 RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
 retrieving revision 1.26
 diff -u -r1.26 Makefile
 --- Makefile    1996/11/19 13:14:40     1.26
 +++ Makefile    1997/05/20 10:25:09     1.28
 @@ -20,5 +20,8 @@
  post-install:
  .for file in emacs-19.34 emacsclient etags ctags b2m
         strip ${PREFIX}/bin/${file}
  .endfor
 +.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
 +       install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
 +.endfor
 
  .include &lt;bsd.port.mk&gt;</programlisting>
         </step>
 
         <step>
           <para>Edit <filename>pkg-plist</filename> and add equivalent
             <literal>@exec</literal> statements and also
             <literal>@unexec</literal> for
             <command>pkg_delete</command>.</para>
 
           <programlisting>Index: pkg-plist
 ===================================================================
 RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v
 retrieving revision 1.15
 diff -u -r1.15 pkg-plist
 --- pkg-plist       1997/03/04 08:04:00     1.15
 +++ pkg-plist       1997/05/20 10:25:12     1.17
 @@ -16,7 +14,14 @@
  man/man1/etags.1.gz
  man/man1/ctags.1.gz
 +@unexec install-info --delete %D/info/emacs %D/info/dir
  :
 +@unexec install-info --delete %D/info/ccmode %D/info/dir
  info/cl
  info/cl-1
 @@ -87,6 +94,18 @@
  info/viper-3
  info/viper-4
 +@exec install-info %D/info/emacs %D/info/dir
  :
 +@exec install-info %D/info/ccmode %D/info/dir
  libexec/emacs/19.34/i386--freebsd/cvtmail
  libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
 
           <note>
             <para>The <literal>@unexec install-info --delete</literal>
               commands have to be listed before the info files themselves so
               they can read the files. Also, the <literal>@exec
                 install-info</literal> commands have to be after the info
               files and the <literal>@exec</literal> command that creates the
               the <filename>dir</filename> file.</para>
           </note>
         </step>
 
         <step>
           <para><link linkend="porting-testing">Test</link> and admire your
             work.  <!-- smiley --><emphasis>:-)</emphasis>.  Check the
             <filename>dir</filename> file before and after each step.</para>
         </step>
       </procedure>
     </chapter>
 
     <chapter>
       <title>The <filename>pkg-<replaceable>*</replaceable></filename> files</title>
 
       <para>There are some tricks we have not mentioned yet about the
         <filename>pkg-<replaceable>*</replaceable></filename> files
         that come in handy sometimes.</para>
 
       <sect1 id="porting-message">
         <title><filename>pkg-message</filename></title>
 
         <para>If you need to display a message to the installer, you may place
           the message in <filename>pkg-message</filename>.  This capability is
           often useful to display additional installation steps to be taken
           after a <command>pkg_add</command> or to display licensing
           information.</para>
 
         <note>
           <para>The <filename>pkg-message</filename> file does not need to be
             added to <filename>pkg-plist</filename>.  Also, it will not get
             automatically printed if the user is using the port, not the
             package, so you should probably display it from the
             <maketarget>post-install</maketarget> target yourself.</para>
         </note>
       </sect1>
 
       <sect1>
         <title><filename>pkg-install</filename></title>
 
         <para>If your port needs to execute commands when the binary package
           is installed with <command>pkg_add</command> you can do this via the
           <filename>pkg-install</filename> script.  This script will
           automatically be added to the package, and will be run twice by
           <command>pkg_add</command>.  The first time as
           <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
           PRE-INSTALL</literal> and the second time as
           <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME} POST-INSTALL</literal>. 
           <literal>&dollar;2</literal> can be tested to determine which mode
           the script is being run in.  The <envar>PKG_PREFIX</envar>
           environmental variable will be set to the package installation
           directory.  See &man.pkg.add.1; for
           additional information.</para>
 
         <note>
           <para>This script is not run automatically if you install the port
             with <command>make install</command>.  If you are depending on it
             being run, you will have to explicitly call it from your port's
             <filename>Makefile</filename>.</para>
         </note>
       </sect1>
 
       <sect1>
         <title><filename>pkg-req</filename></title>
 
         <para>If your port needs to determine if it should install or not, you
           can create a <filename>pkg-req</filename> &ldquo;requirements&rdquo;
           script.  It will be invoked automatically at
           installation/deinstallation time to determine whether or not
           installation/deinstallation should proceed.</para>
 
         <para>The script will be run at installation time by
           <command>pkg_add</command> as
           <literal>pkg-req &dollar;{PKGNAME} INSTALL</literal>.
           At deinstallation time it will be run by
           <command>pkg_delete</command> as
           <literal>pkg-req &dollar;{PKGNAME} DEINSTALL</literal>.</para>
       </sect1>
 
       <sect1 id="porting-plist">
         <title>Changing <filename>pkg-plist</filename> based on make
           variables</title>
 
         <para>Some ports, particularly the p5- ports, need to change their
           <filename>pkg-plist</filename> depending on what options they are
           configured with (or version of perl, in the case of p5- ports).  To
           make this easy, any instances in the <filename>pkg-plist</filename> of
           <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and
           <literal>%%PERL_VERSION%%</literal> will be substituted for
           appropriately.  The value of <literal>%%OSREL%%</literal> is the
           numeric revision of the operating system (e.g.,
           <literal>2.2.7</literal>).  <literal>%%PERL_VERSION%%</literal> is
           the full version number of perl (e.g., <literal>5.00502</literal>)
           and <literal>%%PERL_VER%%</literal> is the perl version number minus
           the patchlevel (e.g., <literal>5.005</literal>).</para>
 
         <para>If you need to make other substitutions, you can set the
           <makevar>PLIST_SUB</makevar> variable with a list of
           <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal>
           pairs and instances of
           <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
           substituted with <replaceable>VALUE</replaceable> in the
           <filename>pkg-plist</filename>.</para>
 
         <para>For instance, if you have a port that installs many files in a
           version-specific subdirectory, you can put something like
 
           <programlisting>OCTAVE_VERSION= 2.0.13
 PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
 
           in the <filename>Makefile</filename> and use
           <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows up
           in <filename>pkg-plist</filename>.  That way, when you upgrade the port,
           you will not have to change dozens (or in some cases, hundreds) of
           lines in the <filename>pkg-plist</filename>.</para>
 
         <para>This substitution (as well as addition of any <link
           linkend="porting-manpages">man pages</link>) will be done between
           the <maketarget>do-install</maketarget> and
           <maketarget>post-install</maketarget> targets, by reading from
           <makevar>PLIST</makevar> and writing to <makevar>TMPPLIST</makevar>
           (default:
           <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>).  So if
           your port builds <makevar>PLIST</makevar> on the fly, do so in or
           before <maketarget>do-install</maketarget>.  Also, if your port
           needs to edit the resulting file, do so in
           <maketarget>post-install</maketarget> to a file named
           <makevar>TMPPLIST</makevar>.</para>
       </sect1>
 
       <sect1>
         <title id="porting-pkgfiles">Changing the names of
           <filename>pkg-<replaceable>*</replaceable></filename> files</title>
 
         <para>All the names of <filename>pkg-<replaceable>*</replaceable></filename> files
           are defined using variables so you can change them in your
           <filename>Makefile</filename> if need be.  This is especially useful
           when you are sharing the same <filename>pkg-<replaceable>*</replaceable></filename> files
           among  several ports or have to write to one of the above files (see
           <link linkend="porting-wrkdir">writing to places other than
           <makevar>WRKDIR</makevar></link> for why it is a bad idea to write
           directly in to the <filename>pkg-<replaceable>*</replaceable></filename> subdirectory).</para>
 
         <para>Here is a list of variable names and their default
           values.  (<makevar>PKGDIR</makevar> defaults to
           <makevar>${MASTERDIR}</makevar>.)</para>
 
         <informaltable frame="none">
           <tgroup cols="2">
             <thead>
               <row>
                 <entry>Variable</entry>
                 <entry>Default value</entry>
               </row>
             </thead>
 
             <tbody>
               <row>
                 <entry><makevar>COMMENT</makevar></entry>
                 <entry><literal>${PKGDIR}/pkg-comment</literal></entry>
               </row>
 
               <row>
                 <entry><makevar>DESCR</makevar></entry>
                 <entry><literal>${PKGDIR}/pkg-descr</literal></entry>
               </row>
 
               <row>
                 <entry><makevar>PLIST</makevar></entry>
                 <entry><literal>${PKGDIR}/pkg-plist</literal></entry>
               </row>
 
               <row>
                 <entry><makevar>PKGINSTALL</makevar></entry>
                 <entry><literal>${PKGDIR}/pkg-install</literal></entry>
               </row>
 
               <row>
                 <entry><makevar>PKGDEINSTALL</makevar></entry>
                 <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
               </row>
 
               <row>
                 <entry><makevar>PKGREQ</makevar></entry>
                 <entry><literal>${PKGDIR}/pkg-req</literal></entry>
               </row>
 
               <row>
                 <entry><makevar>PKGMESSAGE</makevar></entry>
                 <entry><literal>${PKGDIR}/pkg-message</literal></entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
         <para>Please change these variables rather than overriding
           <makevar>PKG_ARGS</makevar>.  If you change
           <makevar>PKG_ARGS</makevar>, those files will not correctly be
           installed in <filename>/var/db/pkg</filename> upon install from a
           port.</para>
       </sect1>
     </chapter>
 
     <chapter>
       <title>Licensing Problems</title>
 
       <para>Some software packages have restrictive licenses or can be in
         violation of the law in some countries (such as violating a patent).
         What we can do with
         them varies a lot, depending on the exact wordings of the respective
         licenses.</para>
 
       <note>
         <para>It is your responsibility as a porter to read the licensing
           terms of the software and make sure that the FreeBSD project will
           not be held accountable for violating them by redistributing the
-          source or compiled binaries either via ftp or CD-ROM.  If in doubt,
+          source or compiled binaries either via ftp or CDROM.  If in doubt,
           please contact the &a.ports;.</para>
       </note>
 
       <para>There are two variables you can set in the Makefile to handle the
         situations that arise frequently:</para>
 
       <orderedlist>
         <listitem>
           <para>If the port has a &ldquo;do not sell for profit&rdquo; type of
             license, set the variable <makevar>NO_CDROM</makevar> to a string
             describing the reason why.  We will make sure such ports will not go
-            into the CD-ROM come release time.  The distfile and package will
+            into the CDROM come release time.  The distfile and package will
             still be available via ftp.</para>
         </listitem>
 
         <listitem>
           <para>If the resulting package needs to be built uniquely for each
             site, or the resulting binary package cannot be distributed due to
             licensing; set the variable <makevar>NO_PACKAGE</makevar> to a
             string describing the reason why.  We will make sure such packages
-            will not go on the ftp site, nor  into the CD-ROM come release time.
+            will not go on the ftp site, nor  into the CDROM come release time.
             The distfile will still be included on both however.</para>
         </listitem>
 
         <listitem>
           <para>If the port has legal restrictions on who can use it (e.g.,
             patented stuff) or has a &ldquo;no commercial use&rdquo; license,
             set the variable <makevar>RESTRICTED</makevar> to be the string
             describing the reason why.  For such ports, the distfiles/packages
             will not be available even from our ftp sites.</para>
         </listitem>
       </orderedlist>
 
       <note>
         <para>The GNU General Public License (GPL), both version 1 and 2,
           should not be a problem for ports.</para>
       </note>
 
       <note>
         <para>If you are a committer, make sure you update the
           <filename>ports/LEGAL</filename> file too.</para>
       </note>
     </chapter>
 
     <chapter id="port-upgrading">
       <title>Upgrading</title>
 
       <para>When you notice that a port is out of date compared to the latest
         version from the original authors, first make sure you have the latest
         port.  You can find them in the
         <filename>ports/ports-current</filename> directory of the ftp mirror
         sites.  You may also use CVSup to keep your whole ports collection
         up-to-date, as described in <ulink url="../handbook/synching.html#CVSUP-CONFIG">the Handbook</ulink>.</para>
 
       <para>The next step is to send a mail to the maintainer, if one is
         listed in the port's <filename>Makefile</filename>.  That person may
         already be working on an upgrade, or have a reason to not upgrade the
         port right now (because of, for example, stability problems of the new
         version).</para>
 
       <para>If the maintainer asks you to do the upgrade or there is not any
         such person to begin with, please make the upgrade and send the
         recursive diff (either unified or context diff is fine, but port
         committers appear to prefer unified diff more) of the new and old
         ports directories to us (e.g., if your modified port directory is
         called <filename>superedit</filename> and the original as in our tree
         is <filename>superedit.bak</filename>, then send us the result of
         <command>diff -ruN superedit.bak superedit</command>).  Please examine
         the output to make sure all the changes make sense.  The best way to
         send us the diff is by including it via &man.send-pr.1; (category
         <literal>ports</literal>).  Please mention any added or deleted files
         in the message, as they have to be explicitly specified to CVS when
         doing a commit.  If the diff is more than about 20KB, please compress
         and uuencode it; otherwise, just include it in the PR as is.</para>
 
       <note>
         <para>Once again, please use &man.diff.1; and not &man.shar.1; to send
           updates to existing ports!</para>
       </note>
     </chapter>
 
     <chapter>
       <title><anchor id="porting-dads">Dos and Don'ts</title>
 
       <para>Here is a list of common dos and don'ts that you encounter during
         the porting process.You should check your own port against this list,
         but you can also check ports in the PR database that others have
         submitted.  Submit any comments on ports you check as described in
         <ulink url="../handbook/contrib-how.html#CONTRIB-GENERAL">Bug Reports and General
           Commentary</ulink>.  Checking ports in the PR database will both make
         it faster for us to commit them, and prove that you know what you are
         doing.</para>
 
       <sect1>
         <title>Strip Binaries</title>
 
         <para>Do strip binaries.  If the original source already strips the
           binaries, fine; otherwise you should add a
           <literal>post-install</literal> rule to it yourself.  Here is an
           example:</para>
 
         <programlisting>post-install:
         strip ${PREFIX}/bin/xdl</programlisting>
 
         <para>Use the &man.file.1; command on the installed executable to
           check whether the binary is stripped or not.  If it does not say
           <literal>not stripped</literal>, it is stripped.</para>
       </sect1>
 
       <sect1>
         <title>INSTALL_* macros</title>
 
         <para>Do use the macros provided in <filename>bsd.port.mk</filename>
           to ensure correct modes and ownership of files in your own
           <maketarget>*-install</maketarget> targets.</para>
 
         <itemizedlist>
           <listitem>
             <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
               binary executables.</para>
           </listitem>
 
           <listitem>
             <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
               executable scripts.</para>
           </listitem>
 
           <listitem>
             <para><makevar>INSTALL_DATA</makevar> is a command to install
               sharable data.</para>
           </listitem>
 
           <listitem>
             <para><makevar>INSTALL_MAN</makevar> is a command to install
               manpages and other documentation (it does not compress
               anything).</para>
           </listitem>
         </itemizedlist>
 
         <para>These are basically the <command>install</command> command with
           all the appropriate flags.  See below for an example on how to use
           them.</para>
       </sect1>
 
       <sect1 id="porting-wrkdir">
         <title><makevar>WRKDIR</makevar></title>
 
         <para>Do not write anything to files outside
           <makevar>WRKDIR</makevar>.  <makevar>WRKDIR</makevar> is the only
           place that is guaranteed to be writable during the port build (see
           <ulink url="../handbook/ports-using.html#PORTS-CD">compiling ports from CDROM</ulink> for an
           example of building ports from a read-only tree).  If you need to
           modify one of the <filename>pkg-<replaceable>*</replaceable></filename>
           files, do so by <link
           linkend="porting-pkgfiles">redefining a variable</link>, not by
           writing over it.</para>
       </sect1>
 
       <sect1 id="porting-wrkdirprefix">
         <title><makevar>WRKDIRPREFIX</makevar></title>
 
         <para>Make sure your port honors <makevar>WRKDIRPREFIX</makevar>.
           Most ports do not have to worry about this.  In particular, if you
           are referring to a <makevar>WRKDIR</makevar> of another port, note
           that the correct location is
           <filename><makevar>WRKDIRPREFIX</makevar><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> not <filename><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> or <filename><makevar>.CURDIR</makevar>/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> or some such.</para>
 
         <para>Also, if you are defining <makevar>WRKDIR</makevar> yourself,
           make sure you prepend
           <literal>&dollar;{WRKDIRPREFIX}&dollar;{.CURDIR}</literal> in the
           front.</para>
       </sect1>
 
       <sect1 id="porting-versions">
         <title>Differentiating operating systems and OS versions</title>
 
         <para>You may come across code that needs modifications or conditional
-          compilation based upon what version of UNIX it is running under.  If
+          compilation based upon what version of Unix it is running under.  If
           you need to make such changes to the code for conditional
           compilation, make sure you make the changes as general as possible
           so that we can back-port code to FreeBSD 1.x systems and cross-port
           to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD,
           NetBSD, and OpenBSD.</para>
 
         <para>The preferred way to tell 4.3BSD/Reno (1990) and newer versions
           of the BSD code apart is by using the <literal>BSD</literal> macro
           defined in <filename>&lt;sys/param.h&gt;</filename>.  Hopefully that
           file is already included; if not, add the code:</para>
 
         <programlisting>#if (defined(__unix__) || defined(unix)) &amp;&amp; !defined(USG)
 #include &lt;sys/param.h&gt;
 #endif</programlisting>
 
         <para>to the proper place in the <filename>.c</filename> file.  We
           believe that every system that defines these two symbols has
           <filename>sys/param.h</filename>.  If you find a system that
           does not, we would like to know.  Please send mail to the
           &a.ports;.</para>
 
         <para>Another way is to use the GNU Autoconf style of doing
           this:</para>
 
         <programlisting>#ifdef HAVE_SYS_PARAM_H
 #include &lt;sys/param.h&gt;
 #endif</programlisting>
 
         <para>Do not forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to the
           <makevar>CFLAGS</makevar> in the <filename>Makefile</filename> for
           this method.</para>
 
         <para>Once you have <filename>sys/param.h</filename> included, you may
           use:</para>
 
         <programlisting>#if (defined(BSD) &amp;&amp; (BSD &gt;= 199103))</programlisting>
 
         <para>to detect if the code is being compiled on a 4.3 Net2 code base
           or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386
           1.1 and below).</para>
 
         <para>Use:</para>
 
         <programlisting>#if (defined(BSD) &amp;&amp; (BSD &gt;= 199306))</programlisting>
 
         <para>to detect if the code is being compiled on a 4.4 code base or
           newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
           above).</para>
 
         <para>The value of the <literal>BSD</literal> macro is
           <literal>199506</literal> for the 4.4BSD-Lite2 code base.  This is
           stated for informational purposes only.  It should not be used to
           distinguish between versions of FreeBSD based only on 4.4-Lite vs.
           versions that have merged in changes from 4.4-Lite2.  The
           <literal>__FreeBSD__</literal> macro should be used instead.</para>
 
         <para>Use sparingly:</para>
 
         <itemizedlist>
           <listitem>
             <para><literal>__FreeBSD__</literal> is defined in all versions of
               FreeBSD.  Use it if the change you are making
               <emphasis>only</emphasis> affects FreeBSD.  Porting gotchas like
               the use of <literal>sys_errlist[]</literal> vs
               <function>strerror()</function> are Berkeleyisms, not FreeBSD
               changes.</para>
           </listitem>
 
           <listitem>
             <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is defined to
               be <literal>2</literal>.  In earlier versions, it is
               <literal>1</literal>.  Later versions will bump it to match
               their major version number.</para>
           </listitem>
 
           <listitem>
             <para>If you need to tell the difference between a FreeBSD 1.x
               system and a FreeBSD 2.x or 3.x system, usually the right answer
               is to use the <literal>BSD</literal> macros described above.  If
               there actually is a FreeBSD specific change (such as special
               shared library options when using <command>ld</command>) then it
               is OK to use <literal>__FreeBSD__</literal> and <literal>#if
                 __FreeBSD__ &gt; 1</literal> to detect a FreeBSD 2.x and later
               system.  If you need more granularity in detecting FreeBSD
               systems since 2.0-RELEASE you can use the following:</para>
 
             <programlisting>#if __FreeBSD__ &gt;= 2
 #include &lt;osreldate.h&gt;
 #    if __FreeBSD_version &gt;= 199504
          /* 2.0.5+ release specific code here */
 #    endif
 #endif</programlisting>
 
 		<informaltable frame="none">
 		<tgroup cols="2">
 		<thead>
 		  <row>
 		    <entry>Release</entry>
 		    <entry><literal>__FreeBSD_version</literal></entry>
 		  </row>
 		</thead>
 
 		<tbody>
 		  <row>
 		    <entry>2.0-RELEASE</entry>
 		    <entry>119411</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.1-CURRENT</entry>
 		  <entry>199501, 199503</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.0.5-RELEASE</entry>
 		  <entry>199504</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-CURRENT before 2.1</entry>
 		  <entry>199508</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.1.0-RELEASE</entry>
 		  <entry>199511</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-CURRENT before 2.1.5</entry>
 		  <entry>199512</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.1.5-RELEASE</entry>
 		  <entry>199607</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-CURRENT before 2.1.6</entry>
 		  <entry>199608</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.1.6-RELEASE</entry>
 		  <entry>199612</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.1.7-RELEASE</entry>
 		  <entry>199612</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-RELEASE</entry>
 		  <entry>220000</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2.1-RELEASE</entry>
 		  <entry>220000 (no change)</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
 		  <entry>220000 (no change)</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-STABLE after texinfo-3.9</entry>
 		  <entry>221001</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-STABLE after top</entry>
 		  <entry>221002</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2.2-RELEASE</entry>
 		  <entry>222000</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
 		  <entry>222001</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2.5-RELEASE</entry>
 		  <entry>225000</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
 		  <entry>225001</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-STABLE after ldconfig -R merge</entry>
 		  <entry>225002</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2.6-RELEASE</entry>
 		  <entry>226000</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2.7-RELEASE</entry>
 		  <entry>227000</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-STABLE after 2.2.7-RELEASE</entry>
 		  <entry>227001</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-STABLE after &man.semctl.2; change</entry>
 		  <entry>227002</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2.8-RELEASE</entry>
 		  <entry>228000</entry>
 		  </row>
 
 		  <row>
 		  <entry>2.2-STABLE after 2.2.8-RELEASE</entry>
 		  <entry>228001</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.0-CURRENT before &man.mount.2; change</entry>
 		  <entry>300000</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.0-CURRENT after &man.mount.2; change</entry>
 		  <entry>300001</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.0-CURRENT after &man.semctl.2; change</entry>
 		  <entry>300002</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.0-CURRENT after ioctl arg changes</entry>
 		  <entry>300003</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.0-CURRENT after ELF conversion</entry>
 		  <entry>300004</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.0-RELEASE</entry>
 		  <entry>300005</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.0-CURRENT after 3.0-RELEASE</entry>
 		  <entry>300006</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.0-STABLE after 3/4 branch</entry>
 		  <entry>300007</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.1-RELEASE</entry>
 		  <entry>310000</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.1-STABLE after 3.1-RELEASE</entry>
 		  <entry>310001</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.1-STABLE after C++ constructor/destructor order
 		  change</entry>
 		  <entry>310002</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.2-RELEASE</entry>
 		  <entry>320000</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.2-STABLE</entry>
 		  <entry>320001</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.2-STABLE after binary-incompatible IPFW and
 		  socket changes</entry>
 		  <entry>320002</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.3-RELEASE</entry>
 		  <entry>330000</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.3-STABLE</entry>
 		  <entry>330001</entry>
 		  </row>
 
 		  <row>
 		  <entry>3.3-STABLE after adding &man.mkstemp.3;
 		    to libc</entry>
 		  <entry>330002</entry>
 		  </row>
 
 		  <row>
 		    <entry>3.4-RELEASE</entry>
 		    <entry>340000</entry>
 		  </row>
 
 		  <row>
 		    <entry>3.4-STABLE</entry>
 		    <entry>340001</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after 3.4 branch</entry>
 		  <entry>400000</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after change in dynamic linker
 		  handling</entry>
 		  <entry>400001</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after C++ constructor/destructor
 		  order change</entry>
 		  <entry>400002</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after functioning &man.dladdr.3;</entry>
 		  <entry>400003</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.0-CURRENT after __deregister_frame_info dynamic
 		    linker bug fix (also 4.0-CURRENT after EGCS 1.1.2
 		    integration)
 		    </entry>
 		    <entry>400004</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after &man.suser.9; API change
 		  (also 4.0-CURRENT after newbus)</entry>
 		  <entry>400005</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after cdevsw registration change</entry>
 		  <entry>400006</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after the addition of so_cred for
 		  socket level credentials</entry>
 		  <entry>400007</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after the addition of a poll syscall
 		  wrapper to libc_r</entry>
 		  <entry>400008</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after the change of the kernel's
 		  <literal>dev_t</literal> type to <literal>struct
 		  specinfo</literal> pointer</entry>
 		  <entry>400009</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after fixing a hole
 		    in &man.jail.2;</entry>
 		  <entry>400010</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after the <literal>sigset_t</literal>
 		  datatype change</entry>
 		  <entry>400011</entry>
 		  </row>
 
 		  <row>
 		  <entry>4.0-CURRENT after the cutover to the GCC 2.95.2
 		  compiler</entry>
 		  <entry>400012</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.0-CURRENT after adding pluggable linux-mode
 		    ioctl handlers</entry>
 		    <entry>400013</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.0-CURRENT after importing OpenSSL</entry>
 		    <entry>400014</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.0-CURRENT after the C++ ABI change in GCC 2.95.2
 		    from -fvtable-thunks to -fno-vtable-thunks by
 		    default</entry>
 		    <entry>400015</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.0-CURRENT after importing OpenSSH</entry>
 		    <entry>400016</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.0-RELEASE</entry>
 		    <entry>400017</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.0-STABLE after 4.0-RELEASE</entry>
 		    <entry>400018</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.0-STABLE after merging libxpg4 code into
 		    libc.</entry>
 		    <entry>400020</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.0-STABLE after upgrading Binutils to 2.10.0, ELF
 		    branding changes, and tcsh in the base system.</entry>
 		    <entry>400021</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.1-RELEASE</entry>
 		    <entry>410000</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.1-STABLE after 4.1-RELEASE</entry>
 		    <entry>410001</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.1-STABLE after &man.setproctitle.3; moved from
 		    libutil to libc.</entry>
 		    <entry>410002</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.1.1-RELEASE</entry>
 		    <entry>411000</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.1.1-STABLE after 4.1.1-RELEASE</entry>
 		    <entry>411001</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.2-RELEASE</entry>
 		    <entry>420000</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.2-STABLE after combining libgcc.a and
 		    libgcc_r.a, and associated GCC linkage changes.</entry>
 		    <entry>420001</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT</entry>
 		    <entry>500000</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after adding addition ELF header fields,
 		    and changing our ELF binary branding method.</entry>
 		    <entry>500001</entry>
 		  </row>
 
                   <row>
                     <entry>5.0-CURRENT after kld metadata changes.</entry>
                     <entry>500002</entry>
                   </row>
 
                   <row>
                     <entry>5.0-CURRENT after buf/bio changes.</entry>
                     <entry>500003</entry>
                   </row>
 
                   <row>
                     <entry>5.0-CURRENT after binutils upgrade.</entry>
                     <entry>500004</entry>
                   </row>
 
                   <row>
                     <entry>5.0-CURRENT after merging libxpg4 code into
                     libc and after TASKQ interface introduction.</entry>
                     <entry>500005</entry>
                   </row>
 
                   <row>
                     <entry>5.0-CURRENT after the addition of AGP
                     interfaces.</entry>
                     <entry>500006</entry>
                   </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after Perl upgrade to 5.6.0</entry>
 		    <entry>500007</entry>
 		  </row>
 
                   <row>
                     <entry>5.0-CURRENT after the update of KAME code to
                     2000/07 sources.</entry>
                     <entry>500008</entry>
                   </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after ether_ifattach() and
 		    ether_ifdetach() changes.</entry>
 		    <entry>500009</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after changing mtree defaults	
 		    back to original variant, adding -L to follow 
 		    symlinks.</entry>
 		    <entry>500010</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after kqueue API changed.</entry>
 		    <entry>500011</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after &man.setproctitle.3; moved from
 		    libutil to libc.</entry>
 		    <entry>500012</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the first SMPng commit.</entry>
 		    <entry>500013</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after &lt;sys/select.h&gt; moved to
 		    &lt;sys/selinfo.h&gt;.</entry>
 		    <entry>500014</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after combining libgcc.a and
 		    libgcc_r.a, and associated GCC linkage changes.</entry>
 		    <entry>500015</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after change allowing libc and libc_r
 		    to be linked together, deprecating -pthread option.</entry>
 		    <entry>500016</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after switch from struct ucred to
                     struct xucred to stabilize kernel-exported API for
                     mountd et al.</entry>
 		    <entry>500017</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after addition of CPUTYPE make variable
                     for controlling CPU-specific optimizations.</entry>
 		    <entry>500018</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after moving machine/ioctl_fd.h to
                     sys/fdcio.h</entry>
 		    <entry>500019</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after locale names renaming.</entry>
 		    <entry>500020</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after Bzip2 import.</entry>
 		    <entry>500021</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after SSE support.</entry>
 		    <entry>500022</entry>
 		  </row>
                 </tbody>
               </tgroup>
             </informaltable>
           </listitem>
         </itemizedlist>
 
         <note>
           <para>Note that 2.2-STABLE sometimes identifies itself as
             &ldquo;2.2.5-STABLE&rdquo; after the 2.2.5-RELEASE.  The pattern
             used to be year followed by the month, but we decided to change it
             to a more straightforward major/minor system starting from 2.2.
             This is because the parallel development on several branches made
             it infeasible to classify the releases simply by their real
             release dates.  If you are making a port now, you do not have to
             worry about old -CURRENTs; they are listed here just for your
             reference.</para>
         </note>
 
         <para>In the hundreds of ports that have been done, there have only
           been one or two cases where <literal>__FreeBSD__</literal> should
           have been used.  Just because an earlier port screwed up and used it
           in the wrong place does not mean you should do so too.</para>
       </sect1>
 
       <sect1>
         <title>Writing something after
           <filename>bsd.port.mk</filename></title>
 
         <para>Do not write anything after the <literal>.include
             &lt;bsd.port.mk&gt;</literal> line.  It usually can be avoided by
           including <filename>bsd.port.pre.mk</filename> somewhere in the
           middle of your <filename>Makefile</filename> and
           <filename>bsd.port.post.mk</filename> at the end.</para>
 
         <note>
           <para>You need to include either the
             <filename>pre.mk</filename>/<filename>post.mk</filename> pair or
             <filename>bsd.port.mk</filename> only; do not mix these two.</para>
         </note>
 
         <para><filename>bsd.port.pre.mk</filename> only defines a few
           variables, which can be used in tests in the
           <filename>Makefile</filename>, <filename>bsd.port.post.mk</filename>
           defines the rest.</para>
 
         <para>Here are some important variables defined in
           <filename>bsd.port.pre.mk</filename> (this is not the complete list,
           please read <filename>bsd.port.mk</filename> for the complete
           list).</para>
 
         <informaltable frame="none">
           <tgroup cols="2">
             <thead>
               <row>
                 <entry>Variable</entry>
                 <entry>Description</entry>
               </row>
             </thead>
 
             <tbody>
               <row>
                 <entry><makevar>ARCH</makevar></entry>
                 <entry>The architecture as returned by <command>uname
                     -m</command> (e.g., <literal>i386</literal>)</entry>
               </row>
 
               <row>
                 <entry><makevar>OPSYS</makevar></entry>
                 <entry>The operating system type, as returned by
                   <command>uname -s</command> (e.g.,
                   <literal>FreeBSD</literal>)</entry>
               </row>
 
               <row>
                 <entry><makevar>OSREL</makevar></entry>
                 <entry>The release version of the operating system (e.g.,
                   <literal>2.1.5</literal> or
                   <literal>2.2.7</literal>)</entry>
               </row>
 
               <row>
                 <entry><makevar>OSVERSION</makevar></entry>
                 <entry>The numeric version of the operating system, same as
                   <link
                     linkend="porting-versions"><literal>__FreeBSD_version</literal></link>.</entry>
               </row>
 
               <row>
                 <entry><makevar>PORTOBJFORMAT</makevar></entry>
                 <entry>The object format of the system
                   (<literal>aout</literal> or <literal>elf</literal>)</entry>
               </row>
 
               <row>
                 <entry><makevar>LOCALBASE</makevar></entry>
                 <entry>The base of the &ldquo;local&rdquo; tree (e.g.,
                   <literal>/usr/local/</literal>)</entry>
               </row>
 
               <row>
                 <entry><makevar>X11BASE</makevar></entry>
                 <entry>The base of the &ldquo;X11&rdquo; tree (e.g.,
                   <literal>/usr/X11R6</literal>)</entry>
               </row>
 
               <row>
                 <entry><makevar>PREFIX</makevar></entry>
                 <entry>Where the port installs itself (see <link
                     linkend="porting-prefix">more on
                     <makevar>PREFIX</makevar></link>).</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
         <note>
           <para>If you have to define the variables
             <makevar>USE_IMAKE</makevar>, <makevar>USE_X_PREFIX</makevar>, or
             <makevar>MASTERDIR</makevar>, do so before including
             <filename>bsd.port.pre.mk</filename>.</para>
         </note>
 
         <para>Here are some examples of things you can write after
           <filename>bsd.port.pre.mk</filename>:</para>
 
         <programlisting># no need to compile lang/perl5 if perl5 is already in system
 .if ${OSVERSION} > 300003
 BROKEN= perl is in system
 .endif
 
 # only one shlib version number for ELF
 .if ${PORTOBJFORMAT} == "elf"
 TCL_LIB_FILE=  ${TCL_LIB}.${SHLIB_MAJOR}
 .else
 TCL_LIB_FILE=  ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
 .endif
 
 # software already makes link for ELF, but not for a.out
 post-install:
 .if ${PORTOBJFORMAT} == "aout"
        ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
 .endif</programlisting>
       </sect1>
 
       <sect1>
         <title>Install additional documentation</title>
 
         <para>If your software has some documentation other than the standard
           man and info pages that you think is useful for the user, install it
           under <filename><makevar>PREFIX</makevar>/share/doc</filename>.
           This can be done, like the previous item, in the
           <maketarget>post-install</maketarget> target.</para>
 
         <para>Create a new directory for your port.  The directory name should
           reflect what the port is.  This usually means
           <makevar>PORTNAME</makevar>. However, if you
           think the user might want different versions of the port to be
           installed at the same time, you can use the whole
           <makevar>PKGNAME</makevar>.</para>
 
         <para>Make the installation dependent to the variable
           <makevar>NOPORTDOCS</makevar> so that users can disable it in
           <filename>/etc/make.conf</filename>, like this:</para>
 
         <programlisting>post-install:
 .if !defined(NOPORTDOCS)
         ${MKDIR} ${PREFIX}/share/doc/xv
         ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
 .endif</programlisting>
 
         <para>Do not forget to add them to <filename>pkg-plist</filename> too.
           (Do not worry about <makevar>NOPORTDOCS</makevar> here; there is
           currently no way for the packages to read variables from
           <filename>/etc/make.conf</filename>.)</para>
 
         <para>You can also use the <filename>pkg-message</filename> file to
           display messages upon installation.  See the <link
           linkend="porting-message">using
           <filename>pkg-message</filename></link> section for
           details.</para>
 
         <note>
           <para><filename>pkg-message</filename> does not need to be added to
             <filename>pkg-plist</filename>.</para>
         </note>
       </sect1>
 
       <sect1>
         <title><makevar>DIST_SUBDIR</makevar></title>
 
         <para>Do not let your port clutter
           <filename>/usr/ports/distfiles</filename>.  If your port requires a
           lot of files to be fetched, or contains a file that has a name that
           might conflict with other ports (e.g.,
           <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar>
           to the name of the port (<literal>${PORTNAME}</literal> or
           <literal>${PKGNAMEPREFIX}${PORTNAME}</literal>
           should work fine).  This will change
           <makevar>DISTDIR</makevar> from the default
           <filename>/usr/ports/distfiles</filename> to
           <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
           and in effect puts everything that is required for your port into
           that subdirectory.</para>
 
         <para>It will also look at the subdirectory with the same name on the
           backup master site at <filename>ftp.FreeBSD.org</filename>.
           (Setting <makevar>DISTDIR</makevar> explicitly in your
           <makevar>Makefile</makevar> will not accomplish this, so please use
           <makevar>DIST_SUBDIR</makevar>.)</para>
 
         <note>
           <para>This does not affect the <makevar>MASTER_SITES</makevar> you
             define in your Makefile.</para>
         </note>
       </sect1>
 
       <sect1>
         <title>Package information</title>
 
         <para>Do include package information, i.e.
           <filename>pkg-comment</filename>, <filename>pkg-descr</filename>, and
           <filename>pkg-plist</filename>.</para>
 
         <note>
           <para>Note that these files are not used only for packaging anymore,
             and are <emphasis>mandatory</emphasis> now, even if
             <makevar>NO_PACKAGE</makevar> is set.</para>
         </note>
       </sect1>
 
       <sect1>
         <title>RCS strings</title>
 
         <para>Do not put RCS strings in patches.  CVS will mangle them when we
           put the files into the ports tree, and when we check them out again,
           they will come out different and the patch will fail.  RCS strings
           are surrounded by dollar (<literal>&dollar;</literal>) signs, and
           typically start with <literal>&dollar;Id</literal> or
           <literal>&dollar;RCS</literal>.</para>
       </sect1>
 
       <sect1>
         <title>Recursive diff</title>
 
         <para>Using the recurse (<option>-r</option>) option to
           <command>diff</command> to generate patches is fine, but please take
           a look at the resulting patches to make sure you do not have any
           unnecessary junk in there.  In particular, diffs between two backup
           files, <filename>Makefiles</filename> when the port uses
           <command>Imake</command> or GNU <command>configure</command>, etc.,
           are unnecessary and should be deleted.  If you had to edit
           <filename>configure.in</filename> and run
           <command>autoconf</command> to regenerate
           <command>configure</command>, do not take the diffs of
           <command>configure</command> (it often grows to a few thousand
           lines!); define <literal>USE_AUTOCONF=yes</literal> and take the
           diffs of <filename>configure.in</filename>.</para>
 
         <para>Also, if you had to delete a file, then you can do it in the
           <maketarget>post-extract</maketarget> target rather than as part of
           the patch.  Once you are happy with the resulting diff, please split
           it up into one source file per patch file.</para>
       </sect1>
 
       <sect1 id="porting-prefix">
         <title><makevar>PREFIX</makevar></title>
 
         <para>Do try to make your port install relative to
           <makevar>PREFIX</makevar>.  (The value of this variable will be set
           to <makevar>LOCALBASE</makevar> (default
           <filename>/usr/local</filename>), unless
           <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is
           set, in which case it will be <makevar>X11BASE</makevar> (default
           <filename>/usr/X11R6</filename>).)</para>
 
         <para>Not hard-coding <filename>/usr/local</filename> or
           <filename>/usr/X11R6</filename> anywhere in the source will make the
           port much more flexible and able to cater to the needs of other
           sites.  For X ports that use <command>imake</command>, this is
           automatic; otherwise, this can often be done by simply replacing the
           occurrences of <filename>/usr/local</filename> (or
           <filename>/usr/X11R6</filename> for X ports that do not use imake)
           in the various scripts/Makefiles in the port to read
           <makevar>PREFIX</makevar>, as this variable is automatically passed
           down to every stage of the build and install processes.</para>
 
 	<para>Make sure your application isn't installing things in 
 	<filename>/usr/local</filename> instead of <makevar>PREFIX</makevar>.
 	A quick test for this is to do this is:</para>
 
 	<screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen>
 	
 	<para>If anything is installed outside of <makevar>PREFIX</makevar>, 
 	making the package creation process will complain that it
 	can't find the files.</para>
 
 	<!-- XXX This paragraph is confusing and poorly indented. -->
 	<para>This does not test for the existence of internal references,
 	or correct use of <makevar>LOCALBASE</makevar> for references to
 	files from other ports.  Testing the installation in
 	<filename>/var/tmp/<replaceable>port-name</replaceable></filename>
 	to do that that while you have it installed would do that.</para>
 
         <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
           truly requires it (i.e., it links against X libs or it needs to
           reference files in <makevar>X11BASE</makevar>).</para>
 
         <para>The variable <makevar>PREFIX</makevar> can be reassigned in your
           <filename>Makefile</filename> or in the user's environment.
           However, it is strongly discouraged for individual ports to set this
           variable explicitly in the <filename>Makefiles</filename>.</para>
 
         <para>Also, refer to programs/files from other ports with the
           variables mentioned above, not explicit pathnames.  For instance, if
           your port requires a macro <literal>PAGER</literal> to be the full
           pathname of <command>less</command>, use the compiler flag:
 
           <programlisting>-DPAGER=\"&dollar;{PREFIX}/bin/less\"</programlisting>
 
           or
 
           <programlisting>-DPAGER=\"&dollar;{LOCALBASE}/bin/less\"</programlisting>
 
           if this is an X port, instead of
           <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will
           have a better chance of working if the system administrator has
           moved the whole `/usr/local' tree somewhere else.</para>
       </sect1>
 
       <sect1>
         <title>Subdirectories</title>
 
         <para>Try to let the port put things in the right subdirectories of
           <makevar>PREFIX</makevar>.  Some ports lump everything and put it in
           the subdirectory with the port's name, which is incorrect.  Also,
           many ports put everything except binaries, header files and manual
           pages in the a subdirectory of <filename>lib</filename>, which does
           not bode well with the BSD paradigm.  Many of the files should be
           moved to one of the following: <filename>etc</filename>
           (setup/configuration files), <filename>libexec</filename>
           (executables started internally), <filename>sbin</filename>
           (executables for superusers/managers), <filename>info</filename>
           (documentation for info browser) or  <filename>share</filename>
           (architecture independent files).  See man &man.hier.7; for details,
           the rules governing
           <filename>/usr</filename> pretty much apply to
           <filename>/usr/local</filename> too.  The exception are ports
           dealing with USENET &ldquo;news&rdquo;.  They may use
           <filename><makevar>PREFIX</makevar>/news</filename> as a destination
           for their files.</para>
       </sect1>
 
       <sect1 id="porting-cleaning">
         <title>Cleaning up empty directories</title>
 
         <para>Do make your ports clean up after themselves when they are
           deinstalled.  This is usually accomplished by adding
           <literal>@dirrm</literal> lines for all directories that are
           specifically created by the port.  You need to delete subdirectories
           before you can delete parent directories.</para>
 
         <programlisting> :
 lib/X11/oneko/pixmaps/cat.xpm
 lib/X11/oneko/sounds/cat.au
  :
 @dirrm lib/X11/oneko/pixmaps
 @dirrm lib/X11/oneko/sounds
 @dirrm lib/X11/oneko</programlisting>
 
         <para>However, sometimes <literal>@dirrm</literal> will give you
           errors because other ports also share the same subdirectory.  You
           can call <command>rmdir</command> from <literal>@unexec</literal> to
           remove only empty directories without warning.</para>
 
         <programlisting>@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting>
 
         <para>This will neither print any error messages nor cause
           <command>pkg_delete</command> to exit abnormally even if
           <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is not
           empty due to other ports installing some files in there.</para>
       </sect1>
 
       <sect1>
         <title>UIDs</title>
 
         <para>If your port requires a certain user to be on the installed
           system, let the <filename>pkg-install</filename> script call
           <command>pw</command> to create it automatically.  Look at
           <filename>net/cvsup-mirror</filename> for an example.</para>
 
         <para>If your port must use the same user/group ID number when it is
           installed as a binary package as when it was compiled, then you must
           choose a free UID from 50 to 99 and register it below.  Look at
           <filename>japanese/Wnn</filename> for an example.</para>
 
         <para>Make sure you do not use a UID already used by the system or
           other ports.  This is the current list of UIDs between 50 and
           99.</para>
 
         <programlisting>majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
 cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
 gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
 uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
 xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent
 pop:*:68:6:Post Office Owner (popper):/nonexistent:/nonexistent
 wnn:*:69:7:Wnn:/nonexistent:/nonexistent
 ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
 pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
 ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
 alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
 qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
 qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
 qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
 qmails:*:87:82:QMail user:/var/qmail:/nonexistent
 qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
 qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
 msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh
 mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin
 vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent</programlisting>
 
         <para>Please include a notice when you submit a port (or an upgrade)
           that reserves a new UID or GID in this range.  This allows us to
           keep the list of reserved IDs up to date.</para>
       </sect1>
 
       <sect1>
         <title>Do things rationally</title>
 
         <para>The <filename>Makefile</filename> should do things simply and
           reasonably.  If you can make it a couple of lines shorter or more
           readable, then do so.  Examples include using a make
           <literal>.if</literal> construct instead of a shell
           <literal>if</literal> construct, not redefining
           <maketarget>do-extract</maketarget> if you can redefine
           <makevar>EXTRACT*</makevar> instead, and using
           <makevar>GNU_CONFIGURE</makevar> instead of <literal>CONFIGURE_ARGS
             += --prefix=&dollar;{PREFIX}</literal>.</para>
       </sect1>
 
       <sect1>
         <title>Respect <makevar>CFLAGS</makevar></title>
 
         <para>The port should respect the <makevar>CFLAGS</makevar> variable.
           If it does not, please add <literal>NO_PACKAGE=ignores
             cflags</literal> to the <filename>Makefile</filename>.</para>
 
 	<para>An example of a <filename>Makefile</filename> respecting
 	  the <makevar>CFLAGS</makevar> variable follows.  Note the
 	  <makevar>+=</makevar>:</para>
 
 	<programlisting>CFLAGS += -Wall -Werror</programlisting>
 
 	<para>Here is an example which does not respect the
 	  <makevar>CFLAGS</makevar> variable:</para>
 
 	<programlisting>CFLAGS = -Wall -Werror</programlisting>
 
 	<para>The <makevar>CFLAGS</makevar> variable is defined on
 	  FreeBSD systems in <filename>/etc/make.conf</filename>.  The
 	  first example appends additional flags to the
 	  <makevar>CFLAGS</makevar> variable, preserving any system-wide
 	  definitions.  The second example clobbers anything previously
 	  defined.</para>
       </sect1>
 
       <sect1>
         <title>Configuration files</title>
 
         <para>If your port requires some configuration files in
           <filename><makevar>PREFIX</makevar>/etc</filename>, do
           <emphasis>not</emphasis> just install them and list them in
           <filename>pkg-plist</filename>.  That will cause
           <command>pkg_delete</command> to delete files carefully edited by
           the user and a new installation to wipe them out.</para>
 
         <para>Instead, install sample files with a suffix
           (<filename><replaceable>filename</replaceable>.sample</filename>
           will work well) and print out a <link
             linkend="porting-message">message</link> pointing out that the
           user has to copy and edit the file before the software can be made
           to work.</para>
       </sect1>
 
       <sect1>
         <title>Portlint</title>
 
         <para>Do check your work with <link
             linkend="porting-portlint"><command>portlint</command></link>
           before you submit or commit it.</para>
       </sect1>
 
       <sect1>
         <title>Feedback</title>
 
         <para>Do send applicable changes/patches to the original
           author/maintainer for inclusion in next release of the code.  This
           will only make your job that much easier for the next
           release.</para>
       </sect1>
 
       <sect1>
         <title><filename>README.html</filename></title>
 
         <para>Do not include the <filename>README.html</filename> file.  This
           file is not part of the cvs collection but is generated using the
           <command>make readme</command> command.
         </para>
       </sect1>
 
       <sect1>
         <title>Miscellanea</title>
 
         <para>The files <filename>pkg-comment</filename>,
           <filename>pkg-descr</filename>, and <filename>pkg-plist</filename>
           should each be double-checked.  If you are reviewing a port and feel
           they can be worded better, do so.</para>
 
         <para>Do not copy more copies of the GNU General Public License into
           our system, please.</para>
 
         <para>Please be careful to note any legal issues! Do not let us
           illegally distribute software!</para>
       </sect1>
 
       <sect1>
         <title>If you are stuck&hellip;</title>
 
         <para>Do look at existing examples and the
           <filename>bsd.port.mk</filename> file before asking us questions!
           <!-- smiley --><emphasis>;-)</emphasis></para>
 
         <para>Do ask us questions if you have any trouble! Do not just beat
           your head against a wall! <!-- smiley
           --><emphasis>:-)</emphasis></para>
       </sect1>
     </chapter>
 
     <chapter id="porting-samplem">
       <title>A Sample <filename>Makefile</filename></title>
 
       <para>Here is a sample <filename>Makefile</filename> that you can use to
         create a new port.  Make sure you remove all the extra comments (ones
         between brackets)!</para>
 
       <para>It is recommended that you follow this format (ordering of
         variables, empty lines between sections, etc.).  This format is
         designed so that the most important information is easy to locate.  We
         recommend that you use <link
           linkend="porting-portlint">portlint</link> to check the
         <filename>Makefile</filename>.</para>
 
       <programlisting>[the header...just to make it easier for us to identify the ports.]
 # New ports collection makefile for:   xdvi
 [the "version required" line is only needed when the PORTVERSION
  variable is not specific enough to describe the port.]
 # Date created:                26 May 1995
 [this is the person who did the original port to FreeBSD, in particular, the
 person who wrote the first version of this Makefile.  Remember, this should
 not be changed when upgrading the port later.]
 # Whom:                        Satoshi Asami &lt;asami@FreeBSD.org&gt;
 #
 # &dollar;FreeBSD&dollar;
 [ ^^^^^^^^^ This will be automatically replaced with RCS ID string by CVS
 when it is committed to our repository.  If upgrading a port, do not alter
 this line back to "&dollar;FreeBSD&dollar;".  CVS deals with it automatically.]
 #
 
 [section to describe the port itself and the master site - PORTNAME
  and PORTVERSION are always first, followed by CATEGORIES,
  and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
  PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that.
  Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then
  EXTRACT_ONLY, as necessary.]
 PORTNAME=      xdvi
 PORTVERSION=   18.2
 CATEGORIES=    print
 [do not forget the trailing slash ("/")!
  if you are not using MASTER_SITE_* macros]
 MASTER_SITES=  ${MASTER_SITE_XCONTRIB}
 MASTER_SITE_SUBDIR= applications
 PKGNAMEPREFIX= ja-
 DISTNAME=      xdvi-pl18
 [set this if the source is not in the standard ".tar.gz" form]
 EXTRACT_SUFX=  .tar.Z
 
 [section for distributed patches -- can be empty]
 PATCH_SITES=   ftp://ftp.sra.co.jp/pub/X11/japanese/
 PATCHFILES=    xdvi-18.patch1.gz xdvi-18.patch2.gz
 
 [maintainer; *mandatory*!  This is the person (preferably with commit
  privileges) whom a user can contact for questions and bug reports - this
  person should be the porter or someone who can forward questions to the
  original porter reasonably promptly.  If you really do not want to have
  your address here, set it to "ports@FreeBSD.org".]
 MAINTAINER=    asami@FreeBSD.org
 
 [dependencies -- can be empty]
 RUN_DEPENDS=   gs:${PORTSDIR}/print/ghostscript
 LIB_DEPENDS=   Xpm.5:${PORTSDIR}/graphics/xpm
 
 [this section is for other standard bsd.port.mk variables that do not
  belong to any of the above]
 [If it asks questions during configure, build, install...]
 IS_INTERACTIVE=        yes
 [If it extracts to a directory other than ${DISTNAME}...]
 WRKSRC=                ${WRKDIR}/xdvi-new
 [If the distributed patches were not made relative to ${WRKSRC}, you
  may need to tweak this]
 PATCH_DIST_STRIP=      -p1
 [If it requires a "configure" script generated by GNU autoconf to be run]
 GNU_CONFIGURE= yes
 [If it requires GNU make, not /usr/bin/make, to build...]
 USE_GMAKE=     yes
 [If it is an X application and requires "xmkmf -a" to be run...]
 USE_IMAKE=     yes
 [et cetera.]
 
 [non-standard variables to be used in the rules below]
 MY_FAVORITE_RESPONSE=  "yeah, right"
 
 [then the special rules, in the order they are called]
 pre-fetch:
         i go fetch something, yeah
 
 post-patch:
         i need to do something after patch, great
 
 pre-install:
         and then some more stuff before installing, wow
 
 [and then the epilogue]
 .include &lt;bsd.port.mk&gt;</programlisting>
     </chapter>
 
     <chapter id="porting-autoplist">
       <title>Automated package list creation</title>
 
       <para>First, make sure your port is almost complete, with only
         <filename>pkg-plist</filename> missing.  Create an empty
         <filename>pkg-plist</filename>.</para>
 
       <screen>&prompt.root; <userinput>touch pkg-plist</userinput></screen>
 
       <para>Next, create a new set of directories which your port can be
         installed, and install any dependencies.</para>
 
       <screen>&prompt.root; <userinput>mtree -U -f /etc/mtree/BSD.local.dist -d -e -p /var/tmp/<replaceable>port-name</replaceable></userinput>
 &prompt.root; <userinput>make depends PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen>
 
       <para>Store the directory structure in a new file.</para>
 
       <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * -type d) &gt; OLD-DIRS</userinput></screen>
 
       <para>If your port honors <makevar>PREFIX</makevar> (which it should)
         you can then install the port and create the package list.</para>
 
       <screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput>
 &prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find * \! -type d) &gt; pkg-plist</userinput></screen>
 
       <para>You must also add any newly created directories to the packing
         list.</para>
 
       <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' &gt;&gt; pkg-plist</replaceable></userinput></screen>
 
       <para>Finally, you need to tidy up the packing list by hand; it isn't
         <emphasis>all</emphasis> automated.  Manual pages should be listed in
         the port's <filename>Makefile</filename> under
         <makevar>MAN<replaceable>n</replaceable></makevar>, and not in the
         package list.  User configuration files should be removed, or
         installed as
         <filename><replaceable>filename</replaceable>.sample</filename>.
         The <filename>info/dir</filename> file should not be listed
         and appropriate <filename>install-info</filename> lines should
         be added as noted in the <link linkend="porting-info">info
         files</link> section.  Any
         libraries installed by the port should be listed as specified in the
         <link linkend="porting-shlibs">shared libraries</link> section.</para>
     </chapter>
 
     <chapter id="porting-pkgname">
       <title>Package Names</title>
 
       <para>The following are the conventions you should follow in naming your
         packages.  This is to have our package directory easy to scan, as
         there are already lots and lots of packages and users are going to
         turn away if they hurt their eyes!</para>
 
       <para>The package name should look like
         <filename><replaceable><optional>language<optional>_region</optional></optional>-name<optional><optional>-</optional>compiled.specifics</optional>-version.numbers</replaceable></filename>.</para>
 
       <para>The package name is defined as
         <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
         Make sure to set the variables to conform to that format.</para>
 
       <orderedlist>
         <listitem>
           <para>FreeBSD strives to support the native language of its users.
             The <replaceable>language-</replaceable> part should be a two
             letter abbreviation of the natural language defined by ISO-639 if
             the port is specific to a certain language.  Examples are
             <literal>ja</literal> for Japanese, <literal>ru</literal> for
             Russian, <literal>vi</literal> for Vietnamese,
             <literal>zh</literal> for Chinese, <literal>ko</literal> for
             Korean and <literal>de</literal> for German.</para>
 
 	  <para>If the port is specific to a certain region within the
             language area, add the two letter country code as well.
             Examples are <literal>en_US</literal> for US English and
             <literal>fr_CH</literal> for Swiss French.</para>
 
           <para>The <replaceable>language-</replaceable> part should
             be set in the <makevar>PKGNAMEPREFIX</makevar> variable.</para>
         </listitem>
 
         <listitem>
           <para>The first letter of <filename>name</filename> part
             should be lowercase.  (The rest of the name can contain
             capital letters, so use your own discretion when you are
             converting a software name that has some capital letters in it.)
             There is a tradition of naming Perl 5 modules by
             prepending <literal>p5-</literal> and converting the double-colon
             separator to a hyphen; for example, the
             <literal>Data::Dumper</literal> module becomes
             <literal>p5-Data-Dumper</literal>.  If the software in question
             has numbers, hyphens, or underscores in its name, you may include
             them as well (like <literal>kinput2</literal>).</para>
         </listitem>
 
         <listitem>
           <para>If the port can be built with different <link
               linkend="porting-masterdir">hardcoded defaults</link> (usually
             part of the directory name in a family of ports), the
             <replaceable>-compiled.specifics</replaceable> part should state
             the compiled-in defaults (the hyphen is optional).  Examples are
             papersize and font units.</para>
 
           <para>The <replaceable>compiled.specifics</replaceable> part
             should be set in the <makevar>PKGNAMESUFFIX</makevar>
             variable.</para>
         </listitem>
 
         <listitem>
           <para>The version string should follow a dash
             (<literal>-</literal>) and be a period-separated list of
             integers and single lowercase alphabetics.  In particular,
             it is not permissible to have another dash inside the
             version string.  The only exception is the string
             <literal>pl</literal> (meaning `patchlevel'), which can be
             used <emphasis>only</emphasis> when there are no major and
             minor version numbers in the software.  If the software
             version has strings like "alpha", "beta", "rc", or "pre", take
             the first letter and put it immediately after a period.
             If the version string continues after those names, the
             numbers should follow the single alphabet without an extra
             period between them.</para>
 
           <para>The idea is to make it easier to sort ports by looking
             at the version string.  In particular, make sure version
             number components are always delimited by a period, and
             if the date is part of the string, use the
             <literal><replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
             format, not
             <literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal>
             or the non-Y2K compliant
             <literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
             format.</para>
         </listitem>
       </orderedlist>
 
       <para>Here are some (real) examples on how to convert the name
         as called by the software authors to a suitable package
         name:</para>
 
       <informaltable frame="none">
         <tgroup cols="6">
           <thead>
             <row>
               <entry>Distribution Name</entry>
               <entry><makevar>PKGNAMEPREFIX</makevar></entry>
               <entry><makevar>PORTNAME</makevar></entry>
               <entry><makevar>PKGNAMESUFFIX</makevar></entry>
               <entry><makevar>PORTVERSION</makevar></entry>
               <entry>Reason</entry>
             </row>
           </thead>
 
           <tbody>
             <row>
               <entry>mule-2.2.2</entry>
               <entry>(empty)</entry>
               <entry>mule</entry>
               <entry>(empty)</entry>
               <entry>2.2.2</entry>
               <entry>No changes required</entry>
             </row>
 
             <row>
               <entry>XFree86-3.3.6</entry>
               <entry>(empty)</entry>
               <entry>XFree86</entry>
               <entry>(empty)</entry>
               <entry>3.3.6</entry>
               <entry>No changes required</entry>
             </row>
 
             <row>
               <entry>EmiClock-1.0.2</entry>
               <entry>(empty)</entry>
               <entry>emiclock</entry>
               <entry>(empty)</entry>
               <entry>1.0.2</entry>
               <entry>No uppercase names for single programs</entry>
             </row>
 
             <row>
               <entry>rdist-1.3alpha</entry>
               <entry>(empty)</entry>
               <entry>rdist</entry>
               <entry>(empty)</entry>
               <entry>1.3.a</entry>
               <entry>No strings like <literal>alpha</literal>
                 allowed</entry>
             </row>
 
             <row>
               <entry>es-0.9-beta1</entry>
               <entry>(empty)</entry>
               <entry>es</entry>
               <entry>(empty)</entry>
               <entry>0.9.b1</entry>
               <entry>No strings like <literal>beta</literal>
                 allowed</entry>
             </row>
 
             <row>
               <entry>mailman-2.0rc3</entry>
               <entry>(empty)</entry>
               <entry>mailman</entry>
               <entry>(empty)</entry>
               <entry>2.0.r3</entry>
               <entry>No strings like <literal>rc</literal>
                 allowed</entry>
             </row>
 
             <row>
               <entry>v3.3beta021.src</entry>
               <entry>(empty)</entry>
               <entry>tiff</entry>
               <entry>(empty)</entry>
               <entry>3.3</entry>
               <entry>What the heck was that anyway?</entry>
             </row>
 
             <row>
               <entry>tvtwm</entry>
               <entry>(empty)</entry>
               <entry>tvtwm</entry>
               <entry>(empty)</entry>
               <entry>pl11</entry>
               <entry>Version string always required</entry>
             </row>
 
             <row>
               <entry>piewm</entry>
               <entry>(empty)</entry>
               <entry>piewm</entry>
               <entry>(empty)</entry>
               <entry>1.0</entry>
               <entry>Version string always required</entry>
             </row>
 
             <row>
               <entry>xvgr-2.10pl1</entry>
               <entry>(empty)</entry>
               <entry>xvgr</entry>
               <entry>(empty)</entry>
               <entry>2.10.1</entry>
               <entry><literal>pl</literal> allowed only when no
                 major/minor version numbers</entry>
             </row>
 
             <row>
               <entry>gawk-2.15.6</entry>
               <entry>ja-</entry>
               <entry>gawk</entry>
               <entry>(empty)</entry>
               <entry>2.15.6</entry>
               <entry>Japanese language version</entry>
             </row>
 
             <row>
               <entry>psutils-1.13</entry>
               <entry>(empty)</entry>
               <entry>psutils</entry>
               <entry>-letter</entry>
               <entry>1.13</entry>
               <entry>Papersize hardcoded at package build time</entry>
             </row>
 
             <row>
               <entry>pkfonts</entry>
               <entry>(empty)</entry>
               <entry>pkfonts</entry>
               <entry>300</entry>
               <entry>1.0</entry>
               <entry>Package for 300dpi fonts</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>If there is absolutely no trace of version information in the
         original source and it is unlikely that the original author will ever
         release another version, just set the version string to
         <literal>1.0</literal> (like the piewm example above).  Otherwise, ask
         the original author or use the date string
         (<literal><replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>)
 	as the version.</para>
     </chapter>
 
     <chapter id="porting-categories">
         <title>Categories</title>
 
       <para>As you already know, ports are classified in several categories.
         But for this to work, it is important that porters and users understand
         what each category is for and how we decide what to put in each
         category.</para>
 
       <sect1>
         <title>Current list of categories</title>
 
         <para>First, this is the current list of port categories.  Those
           marked with an asterisk (<literal>*</literal>) are
           <emphasis>virtual</emphasis> categories&mdash;those that do not have
           a corresponding subdirectory in the ports tree.</para>
 
         <note>
           <para>For non-virtual categories, you will find a one-line
             description in the <filename>pkg/COMMENT</filename> file in that
             subdirectory (e.g.,
             <filename>archivers/pkg/COMMENT</filename>).</para>
         </note>
 
         <informaltable frame="none">
           <tgroup cols="2">
             <thead>
               <row>
                 <entry>Category</entry>
                 <entry>Description</entry>
               </row>
             </thead>
 
             <tbody>
               <row>
                 <entry><filename>afterstep*</filename></entry>
                 <entry>Ports to support the AfterStep window manager.</entry>
               </row>
 
               <row>
                 <entry><filename>archivers</filename></entry>
                 <entry>Archiving tools.</entry>
               </row>
 
               <row>
                 <entry><filename>astro</filename></entry>
                 <entry>Astronomical ports.</entry>
               </row>
 
               <row>
                 <entry><filename>audio</filename></entry>
                 <entry>Sound support.</entry>
               </row>
 
               <row>
                 <entry><filename>benchmarks</filename></entry>
                 <entry>Benchmarking utilities.</entry>
               </row>
 
               <row>
                 <entry><filename>biology</filename></entry>
                 <entry>Biology-related software.</entry>
               </row>
 
               <row>
                 <entry><filename>cad</filename></entry>
                 <entry>Computer aided design tools.</entry>
               </row>
 
               <row>
                 <entry><filename>chinese</filename></entry>
                 <entry>Chinese language support.</entry>
               </row>
 
               <row>
                 <entry><filename>comms</filename></entry>
                 <entry>Communication software.  Mostly software to talk to
                   your serial port.</entry>
               </row>
 
               <row>
                 <entry><filename>converters</filename></entry>
                 <entry>Character code converters.</entry>
               </row>
 
               <row>
                 <entry><filename>databases</filename></entry>
                 <entry>Databases.</entry>
               </row>
 
               <row>
                 <entry><filename>deskutils</filename></entry>
                 <entry>Things that used to be on the desktop before
                   computers were invented.</entry>
               </row>
 
               <row>
                 <entry><filename>devel</filename></entry>
                 <entry>Development utilities.  Do not put libraries here just
                   because they are libraries&mdash;unless they truly do not
                   belong anywhere else, they should not be in this
                   category.</entry>
               </row>
 
               <row>
                 <entry><filename>editors</filename></entry>
                 <entry>General editors.  Specialized editors go in the section
                   for those tools (e.g., a mathematical-formula editor will go
                   in <filename>math</filename>).</entry>
               </row>
 
               <row>
                 <entry><filename>elisp*</filename></entry>
                 <entry>Emacs-lisp ports.</entry>
               </row>
 
               <row>
                 <entry><filename>emulators</filename></entry>
                 <entry>Emulators for other operating systems.  Terminal
                   emulators do <emphasis>not</emphasis> belong
                   here&mdash;X-based ones should go to
                   <filename>x11</filename> and text-based ones to either
                   <filename>comms</filename> or <filename>misc</filename>,
                   depending on the exact functionality.</entry>
               </row>
 
               <row>
                 <entry><filename>french</filename></entry>
                 <entry>French language support.</entry>
               </row>
 
               <row>
                 <entry><filename>ftp</filename></entry>
                 <entry>FTP client and server utilities.  If your
                   port speaks both FTP and HTTP, put it in
                   <filename>ftp</filename> with a secondary
                   category of <filename>www</filename>.</entry>
               </row>
 
               <row>
                 <entry><filename>games</filename></entry>
                 <entry>Games.</entry>
               </row>
 
               <row>
                 <entry><filename>german</filename></entry>
                 <entry>German language support.</entry>
               </row>
 
               <row>
                 <entry><filename>gnome*</filename></entry>
                 <entry>Ports from the GNU Object Model Environment (GNOME)
                   Project.</entry>
               </row>
 
               <row>
                 <entry><filename>graphics</filename></entry>
                 <entry>Graphics utilities.</entry>
               </row>
 
               <row>
                 <entry><filename>hebrew</filename></entry>
                 <entry>Hebrew language support.</entry>
               </row>
 
               <row>
                 <entry><filename>irc</filename></entry>
                 <entry>Internet Relay Chat utilities.</entry>
               </row>
 
               <row>
                 <entry><filename>ipv6*</filename></entry>
                 <entry>IPv6 related software.</entry>
               </row>
 
               <row>
                 <entry><filename>japanese</filename></entry>
                 <entry>Japanese language support.</entry>
               </row>
 
               <row>
                 <entry><filename>java</filename></entry>
                 <entry>Java language support.</entry>
               </row>
 
               <row>
                 <entry><filename>kde*</filename></entry>
                 <entry>Ports from the K Desktop Environment (KDE)
                   Project.</entry>
               </row>
 
               <row>
                 <entry><filename>korean</filename></entry>
                 <entry>Korean language support.</entry>
               </row>
 
               <row>
                 <entry><filename>lang</filename></entry>
                 <entry>Programming languages.</entry>
               </row>
 
               <row>
                 <entry><filename>linux*</filename></entry>
                 <entry>Linux applications and support utilities.</entry>
               </row>
 
               <row>
                 <entry><filename>mail</filename></entry>
                 <entry>Mail software.</entry>
               </row>
 
               <row>
                 <entry><filename>math</filename></entry>
                 <entry>Numerical computation software and other utilities
                   for mathematics.</entry>
               </row>
 
               <row>
                 <entry><filename>mbone</filename></entry>
                 <entry>MBone applications.</entry>
               </row>
 
               <row>
                 <entry><filename>misc</filename></entry>
                 <entry>Miscellaneous utilities&mdash;basically things that
                   do not belong anywhere else.  This is the only category
                   that should not appear with any other non-virtual category.
                   If you have <literal>misc</literal> with something else in
                   your <makevar>CATEGORIES</makevar> line, that means you can
                   safely delete <literal>misc</literal> and just put the port
                   in that other subdirectory!</entry>
               </row>
 
               <row>
                 <entry><filename>net</filename></entry>
                 <entry>Miscellaneous networking software.</entry>
               </row>
 
               <row>
                 <entry><filename>news</filename></entry>
                 <entry>USENET news software.</entry>
               </row>
 
               <row>
                 <entry><filename>offix*</filename></entry>
                 <entry>Ports from the OffiX suite.</entry>
               </row>
 
               <row>
                 <entry><filename>palm</filename></entry>
                 <entry>Software support for the 3Com Palm(tm) series.</entry>
               </row>
 
               <row>
                 <entry><filename>perl5*</filename></entry>
                 <entry>Ports that require perl version 5 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>picobsd</filename></entry>
                 <entry>Ports to support PicoBSD.</entry>
               </row>
 
               <row>
                 <entry><filename>plan9*</filename></entry>
                 <entry>Various programs from Plan9.</entry>
               </row>
 
               <row>
                 <entry><filename>print</filename></entry>
                 <entry>Printing software.  Desktop publishing tools
                   (previewers, etc.) belong here too.</entry>
               </row>
 
               <row>
                 <entry><filename>python*</filename></entry>
                 <entry>Software written in python.</entry>
               </row>
 
               <row>
                 <entry><filename>ruby*</filename></entry>
                 <entry>Software written in ruby.</entry>
               </row>
 
               <row>
                 <entry><filename>russian</filename></entry>
                 <entry>Russian language support.</entry>
               </row>
 
               <row>
                 <entry><filename>science</filename></entry>
                 <entry>Scientific ports that don't fit into other
                   categories such as <filename>astro</filename>,
                   <filename>biology</filename> and
                   <filename>math</filename>.</entry>
               </row>
 
               <row>
                 <entry><filename>security</filename></entry>
                 <entry>Security utilities.</entry>
               </row>
 
               <row>
                 <entry><filename>shells</filename></entry>
                 <entry>Command line shells.</entry>
               </row>
 
               <row>
                 <entry><filename>sysutils</filename></entry>
                 <entry>System utilities.</entry>
               </row>
 
               <row>
                 <entry><filename>tcl76*</filename></entry>
                 <entry>Ports that use Tcl version 7.6 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>tcl80*</filename></entry>
                 <entry>Ports that use Tcl version 8.0 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>tcl81*</filename></entry>
                 <entry>Ports that use Tcl version 8.1 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>tcl82*</filename></entry>
                 <entry>Ports that use Tcl version 8.2 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>textproc</filename></entry>
                 <entry>Text processing utilities.  It does not include
                   desktop publishing tools, which go to print/.</entry>
               </row>
 
               <row>
                 <entry><filename>tk42*</filename></entry>
                 <entry>Ports that use Tk version 4.2 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>tk80*</filename></entry>
                 <entry>Ports that use Tk version 8.0 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>tk81*</filename></entry>
                 <entry>Ports that use Tk version 8.1 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>tk82*</filename></entry>
                 <entry>Ports that use Tk version 8.2 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>tkstep80*</filename></entry>
                 <entry>Ports that use TkSTEP version 8.0 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>ukrainian</filename></entry>
                 <entry>Ukrainian language support.</entry>
               </row>
 
               <row>
                 <entry><filename>vietnamese</filename></entry>
                 <entry>Vietnamese language support.</entry>
               </row>
 
               <row>
                 <entry><filename>windowmaker*</filename></entry>
                 <entry>Ports to support the WindowMaker window
                   manager</entry>
               </row>
 
               <row>
                 <entry><filename>www</filename></entry>
                 <entry>Software related to the World Wide Web.  HTML language
                   support belongs here too.</entry>
               </row>
 
               <row>
                 <entry>x11</entry>
                 <entry>The X window system and friends.  This category is only
                   for software that directly supports the window system.  Do not
                   put regular X applications here.  If your port is an X
                   application, define <makevar>USE_XLIB</makevar> (implied by
                   <makevar>USE_IMAKE</makevar>) and put it in the appropriate
                   categories.  Also, many of them go into other
                   <filename>x11-*</filename> categories (see below).</entry>
               </row>
 
               <row>
                 <entry><filename>x11-clocks</filename></entry>
                 <entry>X11 clocks.</entry>
               </row>
 
               <row>
                 <entry><filename>x11-fm</filename></entry>
                 <entry>X11 file managers.</entry>
               </row>
 
               <row>
                 <entry><filename>x11-fonts</filename></entry>
                 <entry>X11 fonts and font utilities.</entry>
               </row>
 
               <row>
                 <entry><filename>x11-servers</filename></entry>
                 <entry>X11 servers.</entry>
               </row>
 
               <row>
                 <entry><filename>x11-toolkits</filename></entry>
                 <entry>X11 toolkits.</entry>
               </row>
 
               <row>
                 <entry><filename>x11-wm</filename></entry>
                 <entry>X11 window managers.</entry>
               </row>
 
               <row>
                 <entry><filename>zope*</filename></entry>
                 <entry>Zope support.</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
       </sect1>
 
       <sect1>
         <title>Choosing the right category</title>
 
         <para>As many of the categories overlap, you often have to choose
           which of the categories should be the primary category of your port.
           There are several rules that govern this issue.  Here is the list of
           priorities, in decreasing order of precedence.</para>
 
         <itemizedlist>
           <listitem>
             <para>Language specific categories always come first.  For
               example, if your port installs Japanese X11 fonts, then your
               <makevar>CATEGORIES</makevar> line would read <literal>japanese
                 x11-fonts</literal>.</para>
           </listitem>
 
           <listitem>
             <para>Specific categories win over less-specific ones.  For
               instance, an HTML editor should be listed as <literal>www
                 editors</literal>, not the other way around.  Also, you do not
               need to list <literal>net</literal> when the port belongs to
               any of <literal>irc</literal>, <literal>mail</literal>,
               <literal>mbone</literal>, <literal>news</literal>,
               <literal>security</literal>, or <literal>www</literal>.</para>
           </listitem>
 
           <listitem>
             <para><literal>x11</literal> is used as a secondary category only
               when the primary category is a natural language.  In particular,
               you should not put <literal>x11</literal> in the category line
               for X applications.</para>
           </listitem>
 
           <listitem>
             <para><application>Emacs</application> modes should be
 	      placed in the same ports category as the application
 	      supported by the mode, not in
 	      <filename>editors</filename>.  For example, an
 	      <application>Emacs</application> mode to edit source
 	      files of some programming language should go into
 	      <filename>lang</filename>.
               </para>
           </listitem>
 
           <listitem>
             <para>If your port truly does not belong anywhere else, put it in
               <literal>misc</literal>.</para>
           </listitem>
         </itemizedlist>
 
         <para>If you are not sure about the category, please put a comment to
           that effect in your <command>send-pr</command> submission so we can
           discuss it before we import it.  If you are a committer, send a note
           to the &a.ports; so we can discuss it first&mdash;too often new ports are
           imported to the wrong category only to be moved right away.</para>
       </sect1>
     </chapter>
 
     <chapter>
       <title>Changes to this document and the ports system</title>
 
       <para>If you maintain a lot of ports, you should consider following the
         &a.ports;.  Important changes to the way ports work will be announced
         there.  You can always find more detailed information on the latest
         changes by looking at <ulink
           url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/Mk/bsd.port.mk"> the
           bsd.port.mk CVS log</ulink>.</para>
     </chapter>
 
     <chapter>
       <title>That is It, Folks!</title>
 
       <para>Boy, this sure was a long tutorial, wasn't it?  Thanks for
         following us to here, really.  Now that you know how to do a port,
         have at it and convert everything in the world into ports! That
         is the easiest way to start contributing to the FreeBSD Project!
         <!-- smiley --><emphasis>:-)</emphasis></para>
     </chapter>
 </book>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      End:
 -->
diff --git a/en_US.ISO8859-1/books/ppp-primer/book.sgml b/en_US.ISO8859-1/books/ppp-primer/book.sgml
index 59cf194479..0a9c82bf87 100644
--- a/en_US.ISO8859-1/books/ppp-primer/book.sgml
+++ b/en_US.ISO8859-1/books/ppp-primer/book.sgml
@@ -1,2372 +1,2372 @@
 <!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 ]>
 
 <book>
 
 <bookinfo>
 <title>PPP - Pedantic PPP Primer</title>
 
 <authorgroup>
 <author>
 <firstname>Steve</firstname>			
 <surname>Sims</surname>
 <affiliation>
 <address><email>SimsS@IBM.net</email></address>
 </affiliation>
 </author>
 </authorgroup>
 
-<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/books/ppp-primer/book.sgml,v 1.9 2001/04/17 01:39:30 dd Exp $</pubdate>
+<pubdate>$FreeBSD: doc/en_US.ISO8859-1/books/ppp-primer/book.sgml,v 1.10 2001/04/17 15:58:38 nik Exp $</pubdate>
 
 <abstract><para>This is a step-by-step guide for configuring FreeBSD systems to act as
 a dial-up router/gateway in a Local Area Environment.  All entries may
 be assumed to be relevant to FreeBSD 2.2+, unless otherwise noted.</para></abstract>
 
 </bookinfo>
 
 <preface>
 <title>Overview:</title>
 
 <para>The User-Mode PPP dialer in FreeBSD Version 2.2 (also known as:
 <emphasis remap=it>"IIJ-PPP"</emphasis> ) now supports Packet Aliasing for dial up
 connections to the Internet.  This feature, also known as
 "<emphasis remap=it>Masquerading</emphasis>", "<emphasis remap=it>IP Aliasing</emphasis>", or "<emphasis remap=it>Network Address
 Translation</emphasis>", allows a FreeBSD system to act as a dial- on-demand
 router between an Ethernet-based Local Area Network and an Internet
 Service Provider.  Systems on the LAN can use the FreeBSD system to
 forward information between the Internet by means of a single
 dial-connection.</para>
   
 <para>This guide explains how to:
 <itemizedlist>
 
 <listitem>
 <para>Configure the FreeBSD system to support dial-out connections,</para>
 </listitem>
 
 <listitem>
 <para>Share a dial-out connection with other systems in a network,</para>
 </listitem>
 
 <listitem>
 <para>Configure Windows platforms to use the FreeBSD system as a gateway to the Internet.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>While the focus of this guide is to assist in configuring IP Aliasing,
 it also includes specific examples of the configuration steps necessary
 to configure and install each individual component; each section stands
 alone and may be used to assist in the configuration of various aspects
 of FreeBSD internetworking.</para>
   
 </preface>
 
 <chapter>
 <title>Building the Local Area Network</title>
 
 <para> While the ppp program can, and usually is, be configured to provide
 services to <emphasis>only</emphasis> the local FreeBSD box it can also be used to serve as a
 "Gateway" (or "router") between other LAN-connected resources and the Internet or
 other Dial-Up service.</para>
   
 
 <sect1>
 <title>Typical Network Topology</title>
 
 <para>This guide assumes a typical Local Area Network lashed together as
 follows:
 <programlisting> 
 +---------+       ----&gt; Dial-Up Internet Connection
 | FreeBSD |       \       (i.e.: NetCom, AOL, AT&amp;T, EarthLink,
 etc)
 |         |--------
 | "Curly" |
 |         |
 +----+----+
      |
 |----+-------------+-------------+----|  &lt;-- Ethernet Network
      |             |             |
      |             |             |
 +----+----+   +----+----+   +----+----+
 |         |   |         |   |         |
 |  Win95  |   |   WFW   |   |  WinNT  |
 | "Larry" |   |  "Moe"  |   | "Shemp" |
 |         |   |         |   |         |
 +---------+   +---------+   +---------+</programlisting>
 </para>
   
 </sect1>
 
 <sect1>
 <title>Assumptions about the Local Area Network</title>
 
 <para>Some specific assumptions about this sample network are:</para>
   
 <para>Three workstations and a Server are connected with Ethernet
 cabling:
 <itemizedlist>
 
 <listitem>
 <para>a FreeBSD Server ("Curly") with an NE-2000 adapter configured as
 'ed0'</para>
 </listitem>
 
 <listitem>
 <para>a Windows-95 workstation ("Larry") with Microsoft's "native"
 32-bit TCP/IP drivers</para>
 </listitem>
 
 <listitem>
 <para>a Windows for Workgroups workstation ("Moe") with Microsoft's
 16-bit TCP/IP extensions</para>
 </listitem>
 
 <listitem>
 <para>a Windows NT workstation ("Shemp") with Microsoft's "native"
 32-bit TCP/IP drivers</para>
 </listitem>
 
 </itemizedlist>
  </para>
 
 <para>The IP addresses on the Ethernet side of this sample LAN have been
 taken from a pool addresses proposed reserved by RFC 1918 for use on
 private LANs, so you are free to use these actual IP addresses on your
 own LAN if you want.  IP addresses are assigned as follows:</para>
 
 <informaltable>
   <tgroup cols=3>
     <thead>
       <row>
         <entry>Name</entry>
 	<entry>IP Address</entry>
 	<entry>Comment</entry>
       </row>
     </thead>
 
     <tbody>
       <row>
         <entry><hostid>Curly</hostid></entry>
         <entry><hostid role="ipaddr">192.168.1.1</hostid></entry>
         <entry>The FreeBSD box</entry>
       </row>
 
       <row>
         <entry><hostid>Larry</hostid></entry>
         <entry><hostid role="ipaddr">192.168.1.2</hostid></entry>
         <entry>The Win'95 box</entry>
       </row>
 
       <row>
         <entry><hostid>Moe</hostid></entry>
         <entry><hostid role="ipaddr">192.168.1.3</hostid></entry>
         <entry>The WfW box</entry>
       </row>
 
       <row>
         <entry><hostid>Shemp</hostid></entry>
         <entry><hostid role="ipaddr">192.168.1.4</hostid></entry>
         <entry>The Windows NT box</entry>
       </row>
     </tbody>
   </tgroup>
 </informaltable>
 
 <para>This guide assumes that the modem on the FreeBSD box is connected 
 to the first serial port ('<filename>/dev/cuaa0</filename>' or '<emphasis remap=tt>COM1:</emphasis>' in
 DOS-terms).</para>
   
 <para>Finally, we'll also assume that your Internet Service Provider (ISP)
 automatically provides the IP addresses of both your PPP/FreeBSD side
 as well as the ISP's side.  (i.e.: Dynamic IP Addresses on both ends 
 of the link.)  Specific details for configuring the Dial-Out side of 
 PPP will be addressed in Section 2, "Configuring the FreeBSD System".</para>
   
 </sect1>
 </chapter>
 
 <chapter id="system-config">
 <title>FreeBSD System Configuration</title>
 
 <para>There are three basic pieces of information that must be known to
 the FreeBSD box before you can proceed with integrating the sample
 Local Area Network:</para>
   
 <para>
 <itemizedlist>
 
 <listitem>
 <para>The Host Name of the FreeBSD system; in our example it's "Curly",</para>
 </listitem>
 
 <listitem>
 <para>The Network configuration,</para>
 </listitem>
 
 <listitem>
 <para>The <filename>/etc/hosts</filename> file (which lists the names and IP addresses of
 the other systems in your network)</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>If you performed the installation of FreeBSD over a network
 connection some of this information may already be configured into
 your FreeBSD system.</para>
   
 <para>Even if you believe that the FreeBSD system was properly configured
 when it was installed you should at least verify each of these bits of
 information to prevent trouble in subsequent steps.</para>
   
 
 <sect1>
 <title>Verifying the FreeBSD Host Name</title>
 
 <para>It's possible that the FreeBSD host name was specified and saved
 when the system was initially installed.  To verify that it was, enter
 the following command at a prompt:</para>
   
 <para>
 <informalexample>
 <screen># hostname</screen>
 </informalexample>
 </para>
   
 <para>The name of the host FreeBSD system will be displayed on a single
 line.  If the name looks correct (this is very subjective :-) skip
 ahead to <xref linkend="verify-ether-if-config">.</para>
         
 <para>For example, in our sample network, we would see 'curly.my.domain'
 as a result of the `hostname` command if the name had been set
 correctly during, or after, installation.  (At this point, don't worry
 too much about the ".my.domain" part, we'll sort this out later.  The
 important part is the name up to the first dot.)</para>
   
 <para>If a host name wasn't specified when FreeBSD was installed you'll
 probably see 'myname.my.domain` as a response.  You'll need to edit
 <filename>/etc/rc.conf</filename> to set the name of the machine.</para>
   
 
 <sect2>
 <title>Configuring the FreeBSD Host Name</title>
 
 <para><emphasis><emphasis remap=bf>Reminder: You must be logged in as 'root' to edit the
 system configuration files!</emphasis></emphasis></para>
   
 <para><emphasis><emphasis remap=bf>CAUTION: If you mangle the system configuration files,
 chances are your system WILL NOT BOOT correctly!  Be careful!</emphasis></emphasis></para>
   
 <para>The configuration file that specifies the FreeBSD system's host
 name when the system boots is in <filename>/etc/rc.conf</filename>.  Use the
 default text editor ('<emphasis remap=tt>ee</emphasis>') to edit this file.</para>
   
 <para>Logged in as user 'root' load <filename>/etc/rc.conf</filename> into the
 editor with the following command:
 <informalexample>
 <screen># ee /etc/rc.conf</screen>
 </informalexample>
 </para>
   
 <para>Using the arrow keys, scroll down until you find the line that 
 specifies the host name of the FreeBSD system.  By default, this 
 section says:
 <informalexample>
 <screen>---
 ### Basic network options: ###
 hostname="myname.my.domain"	# Set this!
 ---</screen>
 </informalexample>
 
 Change this section to say (in our example):
 <informalexample>
 <screen>---
 ### Basic network options: ###
 hostname="curly.my.domain"	# Set this!
 ---</screen>
 </informalexample>
 </para>
   
 <para>Once the change to the host name has been made, press the 'Esc' key to
 access the command menu.  Select "leave editor" and make sure to
 specify "save changes" when prompted.</para>
   
 </sect2>
 </sect1>
 
 <sect1 id="verify-ether-if-config">
 <title>Verifying the Ethernet Interface Configuration</title>
 
 <para>To reiterate our basic assumption, this guide assumes that the
 Ethernet Interface in the FreeBSD system is named '<emphasis remap=tt>ed0</emphasis>'.  This is
 the default for NE-1000, NE-2000, WD/SMC models 8003, 8013 and Elite
 Ultra (8216) network adapters.</para>
   
 <para>Other models of network adapters may have different device names in
 FreeBSD.  Check the FAQ for specifics about your network adapter.  If
 you're not sure of the device name of your adapter, check the FreeBSD
 FAQ to determine the device name for the card you have and substitute
 that name (i.e.: '<emphasis remap=tt>de0</emphasis>', '<emphasis remap=tt>zp0</emphasis>', or similar) in the following
 steps.</para>
   
 <para>As was the case with the host name, the configuration for the
 FreeBSD system's Ethernet Interface may have been specified when the
 system was installed.</para>
   
 <para>To display the configuration for the interfaces in your 
 FreeBSD system (Ethernet and others), enter the following command:
 <informalexample>
 <screen># ifconfig -a</screen>
 </informalexample>
 
 (In layman's terms:  "Show me the <emphasis remap=bf>I</emphasis>nter<emphasis remap=bf>F</emphasis>ace <acronym>CONFIG</acronym>uration
 for my network devices.") </para>
   
 <para>An example:
 <informalexample>
 <screen># ifconfig -a
  ed0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu
 1500
       inet 192.168.1.1 netmask 0xffffff00 broadcast 192.168.1.255
       ether 01:02:03:04:05:06
  lp0: flags=8810&lt;POINTOPOINT,SIMPLEX,MULTICAST&gt; mtu 1500
  tun0: flags=8050&lt;POINTOPOINT,RUNNING, MULTICAST&gt; mtu 1500
  sl0: flags=c010&lt;POINTOPOINT,LINK2,MULTICAST&gt; mtu 552
  ppp0: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1500
  lo0: flags=8049&lt;UP,LOOPBACK,RUNNING,MULTICAST&gt; mtu 16384
       inet 127.0.0.1 netmask 0xff000000
 # _</screen>
 </informalexample>
 </para>
   
 <para>In this example, the following devices were displayed:</para>
   
 <para><emphasis remap=tt>ed0:</emphasis>  The Ethernet Interface</para>
   
 <para><emphasis remap=tt>lp0:</emphasis>  The Parallel Port Interface (ignored in this guide)</para>
   
 <para><emphasis remap=tt>tun0:</emphasis> The "tunnel" device; <emphasis>This is the one user-mode ppp uses!</emphasis></para>
   
 <para><emphasis remap=tt>sl0:</emphasis>  The SL/IP device (ignored in this guide)</para>
   
 <para><emphasis remap=tt>ppp0:</emphasis> Another PPP device (for kernel ppp; ignored in this guide)</para>
   
 <para><emphasis remap=tt>lo0:</emphasis>  The "Loopback" device (ignored in this guide)</para>
   
 <para>In this example, the 'ed0' device is up and running.  The key 
 indicators are:
 <orderedlist>
 
 <listitem>
 <para>Its status is "<acronym>UP</acronym>",</para>
 </listitem>
 
 <listitem>
 <para>It has an Internet ("<emphasis remap=tt>inet</emphasis>") address, (in this case, 192.168.1.1)</para>
 </listitem>
 
 <listitem>
 <para>It has a valid Subnet Mask ("netmask"; 0xffffff00 is the same as
 255.255.255.0), and</para>
 </listitem>
 
 <listitem>
 <para>It has a valid broadcast address (in this case, 192.168.1.255).</para>
 </listitem>
 
 </orderedlist>
 </para>
   
 <para>If the line for the Ethernet card had shown something similar to:
 <informalexample>
 <screen>ed0: flags=8802&lt;BROADCAST,SIMPLEX,MULTICAST&gt; mtu 1500
         ether 01:02:03:04:05:06</screen>
 </informalexample>
 
 then the Ethernet card hasn't been configured yet.</para>
   
 <para>If the configuration for the Ethernet interface is correct you can
 skip forward to <xref linkend="list-lan-hosts">.</para>
       
 <sect2 >
 <title>Configuring your Ethernet Interface</title>
 
 <para><emphasis><emphasis remap=bf>Reminder:  You must be logged in as 'root' to edit the
 system configuration files!</emphasis></emphasis></para>
   
 <para><emphasis><emphasis remap=bf>CAUTION:  If you mangle the system configuration files, 
 chances are your system WILL NOT BOOT correctly!  Be careful!</emphasis></emphasis></para>
   
 <para>The configuration file that specifies settings for the network
 interfaces when the system boots is in <filename>/etc/rc.conf</filename>.  Use
 the default text editor ('ee') to edit this file.</para>
   
 <para>Logged in as user 'root' load <filename>/etc/rc.conf</filename> into the
 editor with the following command:</para>
   
 <para><command>  # ee /etc/rc.conf</command></para>
   
 <para>About 20 lines from the top of <filename>/etc/rc.conf</filename> is the section
 that describes which network interfaces should be activated when the
 system boots.  In the default configuration file the specific line
 that controls this is:</para>
   
 <para>
 <informalexample>
 <screen>network_interfaces="lo0"       # List of network interfaces (lo0 is loopback).</screen>
 </informalexample>
 </para>
   
 <para>You'll need to amend this line to tell FreeBSD that you want to add
 another device, namely the '<emphasis remap=tt>ed0</emphasis>' device.  Change this line to
 read:</para>
   
 <para>
 <informalexample>
 <screen>network_interfaces="lo0 ed0"   # List of network interfaces (lo0 is loopback).</screen>
 </informalexample>
 </para>
   
 <para>(Note the space between the definition for the loopback device
 ("<emphasis remap=tt>lo0</emphasis>") 
 and the Ethernet device ("<emphasis remap=tt>ed0</emphasis>")! </para>
   
 <para><emphasis><emphasis remap=bf> Reminder: If your Ethernet card isn't named '<emphasis remap=tt>ed0</emphasis>', specify
 the correct device name here instead.</emphasis></emphasis></para>
   
 <para>If you performed the installation of FreeBSD over a network
 connection then the '<literal>network_interfaces=</literal>' line may already
 include a reference to your Ethernet adapter.  If it is, verify that
 it is the correct device name.</para>
   
 <para>Specify the Interface Settings for the Ethernet device
 ('<emphasis remap=tt>ed0</emphasis>'):</para>
   
 <para>Beneath the line that specifies which interfaces should be
 activated are the lines that specify the actual settings for each
 interface.  In the default <filename>/etc/rc.conf</filename> file is a single
 line that says:</para>
   
 <para>
 <informalexample>
 <screen>ifconfig_lo0="inet 127.0.0.1"   # default loopback device configuration.</screen>
 </informalexample>
 </para>
   
 <para>You'll need to add another line after that to specify the settings
 for your '<emphasis remap=tt>ed0</emphasis>' device.</para>
   
 <para>If you performed the installation of FreeBSD over a network
 connection then there may already be an '<literal>ifconfig_ed0=</literal>' line
 after the loopback definition. If so, verify that it has the correct
 values.</para>
   
 <para>For our sample configuration we'll insert a line immediately after
 the loopback device definition that says:</para>
   
 <para>
 <informalexample>
 <screen>ifconfig_ed0="inet 192.168.1.1 netmask 255.255.255.0"</screen>
 </informalexample>
 </para>
   
 <para>When you've finished editing <filename>/etc/rc.conf</filename> to specify and
 configure the network interfaces the section should look really close
 to:</para>
   
 <para>
 <informalexample>
 <screen>---
 network_interfaces="ed1 lo0"    # List of network interfaces (lo0 is loopback).
 ifconfig_lo0="inet 127.0.0.1"   # default loopback device configuration.
 ifconfig_ed1="inet 192.168.1.1  netmask 255.255.255.0"
 ---</screen>
 </informalexample>
 </para>
   
 <para>Once all of the necessary changes to <filename>/etc/rc.conf</filename> have
 been made, press the 'Esc' key to invoke the control menu.  Select
 "leave editor" and be sure to select "save changes" when prompted.</para>
   
 </sect2>
 </sect1>
 
 <sect1>
 <title>Enabling Packet Forwarding</title>
 
 <para>By default the FreeBSD system will not forward IP packets between
 various network interfaces.  In other words, routing functions (also
 known as gateway functions) are disabled.</para>
   
 <para>If your intent is to use a FreeBSD system as stand-alone Internet 
 workstation and not as a gateway between LAN nodes and your ISP you 
 should skip forward to <xref linkend="list-lan-hosts">.</para>
   
 <para>If you intend for the PPP program to service the local FreeBSD box
 as well as LAN workstations (as a router) you'll need to enable IP 
 forwarding.</para>
   
 <para>To enable IP Packet forwarding you'll need to edit the
 <filename>/etc/rc.conf</filename> file.</para>
 
       <para>This file contains overrides of the defaults in
 	<filename>/etc/defaults/rc.conf</filename>.  The default gateway
 	setting is controlled by the line</para>
 
       <programlisting>gateway_enable="NO"</programlisting>
 
       <para>in that file.  To override it, add a line like</para>
 
       <programlisting>gateway_enable="YES"</programlisting>
 
       <para><filename>/etc/rc.conf</filename>.</para>
   
 <para><emphasis><emphasis remap=bf>NOTE: This line may already be set to
 '<literal>gateway_enable="YES"</literal>' if IP forwarding was enabled when the
 FreeBSD system was installed.</emphasis></emphasis></para>
   
 </sect1>
 
 <sect1 id="list-lan-hosts">
 <title>Creating the List of other LAN Hosts(<filename>/etc/hosts</filename>)</title>
 
 <para>The final step in configuring the LAN side of the FreeBSD system is
 to create a list of the names and TCP/IP addresses of the various
 systems that are connected to the Local Area Network.  This list is
 stored in the '<filename>/etc/hosts</filename>' file.</para>
   
 <para>The default version of this file has only a single host name
 listing in it: the name and address of the loopback device ('lo0').
 By networking convention, this device is always named "localhost" and
 always has an IP address of 127.0.0.1. <xref
 	  linkend="verify-ether-if-config">.</para>
       
 	  
 <para>To edit the <filename>/etc/hosts</filename> file enter the following command:
 <informalexample>
 <screen> # ee /etc/hosts </screen>
 </informalexample>
 </para>
   
 <para>Scroll all the way to the bottom of the file (paying attention to
 the comments along the way; there's some good information there!)  and
 enter (assuming our sample network) the following IP addresses and
 host names:
 <informalexample>
 <screen>192.168.1.1    curly  curly.my.domain  # FreeBSD System
 192.168.1.2    larry  larry.my.domain  # Windows '95 System
 192.168.1.3    moe    moe.my.domain    # Windows for Workgroups
 System
 192.168.1.4    shemp  shemp.my.domain  # Windows NT System</screen>
 </informalexample>
 </para>
   
 <para>(No changes are needed to the line for the '<emphasis remap=tt>127.0.0.1
 localhost</emphasis>' entry.)</para>
   
 <para>Once you've entered these lines, press the 'Esc' key to invoke the
 control menu.  Select "leave editor" and be sure to select "save
 changes" when prompted.</para>
   
 </sect1>
 
 <sect1>
 <title>Testing the FreeBSD system</title>
 
 <para>Congratulations!  Once you've made it to this point, the FreeBSD
-system is configured as a network-connected UNIX system!  If you made
+system is configured as a network-connected Unix system!  If you made
 any changes to the <filename>/etc/rc.conf</filename> file you should probably
 re-boot your FreeBSD system.  This will accomplish two important
 objectives:
 <itemizedlist>
 
 <listitem>
 <para>Allow the changes to the interface configurations to be applied, and</para>
 </listitem>
 
 <listitem>
 <para>Verify that the system restarts without any glaring configuration errors.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>Once the system has been rebooted you should test the network
 interfaces.</para>
   
 
 <sect2>
 <title>Verifying the operation of the loopback device</title>
 
 <para>To verify that the loopback device is configured correctly, log in as
 'root' and enter:
 <informalexample>
 <screen># ping localhost</screen>
 </informalexample>
 </para>
   
 <para>You should see:
 <informalexample>
 <screen># ping localhost
 PING localhost.my.domain. (127.0.0.1): 56 data bytes
 64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=0.219 ms
 64 bytes from 127.0.0.1: icmp_seq=1 ttl=255 time=0.287 ms
 64 bytes from 127.0.0.1: icmp_seq=2 ttl=255 time=0.214 m
 [...]</screen>
 </informalexample>
 
 messages scroll by until you hit Ctrl-C to stop the madness.</para>
   
 </sect2>
 
 <sect2>
 <title>Verifying the operation of the Ethernet Device</title>
 
 <para>To verify that the Ethernet device is configured correctly, enter:</para>
   
 <para>
 <informalexample>
 <screen># ping curly</screen>
 </informalexample>
 </para>
   
 <para>You should see:
 <informalexample>
 <screen># ping curly
 PING curly.my.domain. (192.168.1.1): 56 data bytes
 64 bytes from 192.168.1.1: icmp_seq=0 ttl=255 time=0.219 ms
 64 bytes from 192.168.1.1: icmp_seq=1 ttl=255 time=0.200 ms
 64 bytes from 192.168.1.1: icmp_seq=2 ttl=255 time=0.187 ms
 [...]</screen>
 </informalexample>
 
 messages.</para>
   
 <para>One important thing to look at in these two examples is that the
 names (loopback and curly) correctly correlate to their IP addresses
 (127.0.0.1 and 192.168.1.1).  This verifies that the
 <filename>/etc/hosts</filename> files is correct.</para>
   
 <para>If the IP address for "curly" isn't 192.168.1.1 or the address for
 "localhost" isn't 127.0.0.1, return to <xref linkend="list-lan-hosts"> and review your
 entries in '<filename>/etc/hosts</filename>'.</para>
   
 <para>If the names and addresses are indicated correctly in the result of
 the ping command but there are errors displayed then something is
 amiss with the interface configuration(s).  Return to <xref linkend="system-config"> and
 verify everything again.</para>
   
 <para>If everything here checks out, proceed with the next section.</para>
   
 </sect2>
 </sect1>
 </chapter>
 
 <chapter>
 <title>Configuring the PPP Dial-Out Connection</title>
 
 <para>There are two basic modes of operation of the ppp driver:
 "Interactive" and "Automatic".</para>
   
 <para>In Interactive mode you:</para>
   
 <para>
 <itemizedlist>
 
 <listitem>
 <para>Manually establish a connection to your ISP,</para>
 </listitem>
 
 <listitem>
 <para>Browse, surf, transfer files and mail, etc...,</para>
 </listitem>
 
 <listitem>
 <para>Manually disconnect from your ISP.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>In Automatic mode, the PPP program silently watches what goes on
 inside the FreeBSD system and automagically connects and disconnects
 with your ISP as required to make the Internet a seamless element of
 your network.</para>
   
 <para>In this section we'll address the configuration(s) for both modes
 with emphasis on configuring your `ppp` environment to operate in
 "Automatic" mode.</para>
   
 
 <sect1>
 <title>Backing up the original PPP configuration files</title>
 
       <note>
 	<para>More recent versions of FreeBSD have the examples files in
 	  <filename>/usr/share/examples/ppp</filename>, so this step may not
 	  be necessary.</para>
       </note>
       
 <para>Before making any changes to the files which are used by PPP you
 should make a copy of the default files that were created when the
 FreeBSD system was installed.</para>
   
 <para>Log in as the 'root' user and perform the following steps:</para>
   
 <para>Change to the '<filename>/etc</filename> directory:</para>
   
 <para><emphasis remap=tt># cd /etc</emphasis></para>
   
 <para>Make a backup copy the original files in the 'ppp' directory:</para>
   
 <para><emphasis remap=tt># cp -R ppp ppp.ORIGINAL</emphasis></para>
   
 <para>You should now be able to see both a '<emphasis remap=tt>ppp</emphasis>' and a
 '<filename>ppp.ORIGINAL</filename>' subdirectory
 in the '<filename>/etc</filename>' directory.</para>
   
 </sect1>
 
 <sect1>
 <title>Create your own PPP configuration files</title>
 
 <para>By default, the FreeBSD installation process creates a number of
 sample configuration files in the <filename>/etc/ppp</filename>
 and <filename>/usr/share/examples/ppp</filename> directories.  Please take
 some time to review these files; they were derived from working
 systems and represent the features and capabilities of the PPP
 program.</para>
 
 <para>You are <emphasis>strongly</emphasis> encouraged to learn from
 these sample files and apply them to your own configuration as
 necessary.</para>
   
 <para>For detailed information about the `ppp` program, read the ppp
 manpage:
 <informalexample>
 <screen># man ppp</screen>
 </informalexample>
 </para>
   
 <para>For detailed information about the `chat` scripting language used by
 the PPP dialer, read the chat manpage:
 <informalexample>
 <screen># man chat</screen>
 </informalexample>
 </para>
   
 <para>The remainder of this section describes the recommended contents of
 the PPP configuration files.</para>
   
 
 <sect2>
 <title>The '<filename>/etc/ppp/ppp.conf</filename>' file</title>
 
 <para>The '<filename>/etc/ppp/ppp.conf</filename>' file contains the information and
 settings required to set up a dial-out PPP connection.  More than one
 configuration may be contained in this file.  The FreeBSD handbook
 (XXX URL? XXX) describes the contents and syntax of this file in
 detail.</para>
   
 <para>This section will describe only the minimal configuration to get a
 dial-out connection working.</para>
   
 <para>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a
 dial-out Internet gateway for our example LAN:
 
 <note>
   <para>The full syntax for <filename>ppp.conf</filename> is described in
     &man.ppp.8;.  Particuarly, note that any line that isn't a label that
     ends with a colon (e.g., <literal>default:</literal>,
     <literal>interactive:</literal>), a command that begins with
     <quote>!</quote> (e.g., <literal>!include</literal>), or a comment
     <emphasis>must</emphasis> be indented!</para>
 </note>
 
 <programlisting>################################################################
 # PPP Configuration File ('/etc/ppp/ppp.conf')
 #
 # Default settings; These are always executed always when PPP
 # is invoked and apply to all system configurations.
 ################################################################
 default:
   set device /dev/cuaa0
   set speed 57600
   disable pred1
   deny pred1
   disable lqr
   deny lqr
   set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT"
   set redial 3 10
 #
 #
 ################################################################
 #
 # For interactive mode use this configuration:
 #
 # Invoke with `ppp -alias interactive`
 #
 ################################################################
 interactive:
   set authname Your_User_ID_On_Remote_System
   set authkey Your_Password_On_Remote_System
   set phone 1-800-123-4567
   set timeout 300
   set openmode active
   accept chap
 #
 ################################################################
 #
 # For demand-dial (automatic) mode we'll use this configuration:
 #
 # Invoke with: 'ppp -auto -alias demand'
 #
 ################################################################
 demand:
   set authname Your_User_ID_On_Remote_System
   set authkey Your_Password_On_Remote_System
   set phone 1-800-123-4567
   set timeout 300
   set openmode active
   accept chap
   set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0
   add 0 0 127.2.2.2
 ################################################################
 # End of /etc/ppp/ppp.conf</programlisting>
 
 This file, taken verbatim from a working system, has three relevant 
 configuration sections:</para>
   
 
 <sect3>
 <title>The "<emphasis remap=tt>default</emphasis>" Section</title>
 
 <para>The '<emphasis remap=tt>default:</emphasis>' section contains the values and settings
 used by every other section in the file.  Essentially, this section is
 implicitly added to the configuration lines to each other section.</para>
   
 <para>This is a good place to put "global defaults" applicable to all
 dial-up sessions; especially modem settings and dialing prefixes which
 typically don't change based on which destination system you're
 connecting to.</para>
   
 <para>Following are the descriptions of each line in the "default" section
 of the sample '<filename>/etc/ppp/ppp.conf</filename>' file:
 <informalexample>
 <screen>set device /dev/cuaa0</screen>
 </informalexample>
 
 This statement informs the PPP program that it should use the first
 serial port.
 Under FreeBSD the '<filename>/dev/cuaa0</filename>' device is the same port that's
 known as "<emphasis remap=tt>COM1:</emphasis>" under DOS, Windows, Windows 95, etc....</para>
   
 <para>If your modem is on <emphasis remap=tt>COM2:</emphasis> you should specify
 '<filename>/dev/cuaa1</filename>; <emphasis remap=tt>COM3:</emphasis> would be '<filename>/dev/cuaa2</filename>'.</para>
   
 <para>
 <informalexample>
 <screen>set speed 57600 </screen>
 </informalexample>
 </para>
   
 <para>This line sets the transmit and receive speed for the connection
 between the serial port and the modem. While the modem used for this
 configuration is only a 28.8 device, setting this value to 57600 lets
 the serial link run at a higher rate to accommodate higher throughput
 as a result of the data compression built into late-model modems.</para>
   
 <para>If you have trouble communicating with your modem, try setting this
 value to 38400 or even as low as 19200.</para>
   
 <para>
 <informalexample>
 <screen>disable pred1
 deny pred1</screen>
 </informalexample>
 </para>
   
 <para>These two lines disable the "CCP/Predictor type 1" compression
 features of the PPP program.  The current version of `ppp` supports
 data compression in accordance with draft Internet standards.
 Unfortunately many ISPs use equipment that does not support this
 capability.  Since most modems try to perform on-the-fly compression
 anyway you're probably not losing much performance by disabling this
 feature on the FreeBSD side and denying the remote side from forcing
 it on you.</para>
   
 <para>
 <informalexample>
 <screen>disable lqr
 deny lqr</screen>
 </informalexample>
 </para>
   
 <para>These two lines control the "Line Quality Reporting" functions which
 are part of the complete Point-to-Point (PPP) protocol specification.
 (See RFC-1989 for details.)</para>
   
 <para>The first line, "disable lqr", instructs the PPP program to not
 attempt to report line quality status to the device on the remote end.</para>
   
 <para>The second line, "deny lqr", instructs the PPP program to deny any
 attempts by the remote end to reports line quality.</para>
   
 <para>As most modern dial-up modems have automatic error correction and
 detection and LQR reporting is not fully implemented in many vendor's
 products it's generally a safe bet to include these two lines in the
 default configuration.</para>
   
 <para>
 <informalexample>
 <screen>set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0
 OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT"</screen>
 </informalexample>
 </para>
   
 <para><emphasis>NOTE: (This statement should appear on a single line; ignore any
 line wrapping that may appear in this document.)</emphasis></para>
   
 <para>This line instructs the PPP program how to dial the modem and
 specifies some rudimentary guidelines for doing so:
 <itemizedlist>
 
 <listitem>
 <para>Attempts to dial should fail if the modem returns a "BUSY" result code,</para>
 </listitem>
 
 <listitem>
 <para>Attempts to dial should also fail if the modem returns a "NO CARRIER" result code,</para>
 </listitem>
 
 <listitem>
 <para>The PPP program should expect each of the following events to complete within a
 5-second timeout period:
 <itemizedlist>
 
 <listitem>
 <para>The PPP program will initially expect nothing (specified above
 by the \"\" portion of the statement) from the modem </para>
 </listitem>
 
 <listitem>
 <para>The program
 will send the modem initialization string "ATE1Q0M0" to the modem and
 await a response of "OK".  If a response is not received, the program
 should send an attention command to the modem ("AT") and look again
 for a response of "OK", </para>
 </listitem>
 
 <listitem>
 <para>The program should delay for one second
 (specified by the "\\d" part of the statement, and send the dialing
 string to the modem.  The "ATDT" portion of the statement is the
 standard modem prefix to dial using tone-dialing; if you do not have
 touch-tone service on your local phone line, replace the "ATDT" with
 "ATDP".  The "\\T" string is a placeholder for the actual phone number
 (which will be automatically inserted as specified by the "set dial
 123-4567").</para>
 </listitem>
 
 </itemizedlist>
 </para>
 </listitem>
 
 <listitem>
 <para>Finally, before a (maximum) timeout of 40 seconds, the PPP
 program should expect to see a "CONNECT" result code returned from the
 modem.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>A failure at any point in this dialog will be interpreted as a dialing
 failure and the PPP program will fail to connect.</para>
   
 <para>(For a detailed description of the mini-scripting language used by the
 PPP dialer, refer to the "chat" manpage.)</para>
   
 <para>
 <informalexample>
 <screen>set redial 3 10</screen>
 </informalexample>
 
 This line specifies that if a dial connection cannot immediately be made
 the PPP program should retry (up to 3 times if necessary) with a delay of 10 seconds
 between redialing attempts.</para>
   
 </sect3>
 
 <sect3>
 <title>The "<emphasis remap=tt>interactive</emphasis>" Section</title>
 
 <para>The '<emphasis remap=tt>interactive:</emphasis>' section contains the values and
 settings used to set up an "interactive" PPP session with a specific
 remote system.  Settings in this section will have the lines included
 in the "default" section included automatically.</para>
   
 <para>The example cited in this section of the guide presumes that you'll
 be connecting to a remote system that understands how to authenticate
 a user without any fancy scripting language.  That is, this sample
 uses the CHAP protocol to set up the connection.</para>
   
 <para>A good rule of thumb is that if the Windows '95 dialer can set up a
 connection by just clicking the "Connect" button this sample
 configuration should work OK.</para>
   
 <para>If, on the other hand, when you connect to your ISP using Microsoft
 Windows '95 Dial-Up Networking you need to resort to using the "Dial
 Up Scripting Tool" from the Microsoft Plus! pack or you have to select
 "Bring up a terminal windows after dialing" in the Windows '95
 connection options then you'll need to look at the sample PPP
 configuration files and the ppp manpage for examples of "expect /
 response" scripting to make your ISP connection.  The "set login"
 command is used for this purpose.</para>
   
 <para>Or even better, find an ISP who knows how to provide PAP or CHAP
 authentication!</para>
   
 <para>The configuration examples shown here have been successfully used to
 connect to:
 <itemizedlist>
 
 <listitem>
 <para>Various Shiva LanRovers</para>
 </listitem>
 
 <listitem>
 <para>The IBM Network (<ulink URL="http://www.ibm.net">http://www.ibm.net</ulink>)</para>
 </listitem>
 
 <listitem>
 <para>AT&amp;T WorldNet (<ulink URL="http://att.com/worldnet">http://att.com/worldnet</ulink>)</para>
 </listitem>
 
 <listitem>
 <para>Erol's (<ulink URL="http://www.erols.com">http://www.erols.com</ulink>)</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>Following are descriptions for each line in the "interactive" section
 of the sample '<filename>/etc/ppp/ppp.conf</filename>' file:</para>
   
 <para>
 <informalexample>
 <screen>set authname Your_User_ID_On_Remote_System</screen>
 </informalexample>
 
 This line specifies the name you would use to log in to the remote
 system.  </para>
   
 <para>
 <informalexample>
 <screen>set authkey Your_Password_On_Remote_System</screen>
 </informalexample>
 
 This is the password you'd use to log in to the remote system.</para>
   
 <para>
 <informalexample>
 <screen>set phone 1-800-123-4567</screen>
 </informalexample>
 
 This is the phone number of the remote system.  If you're inside a PBX
 you can 
 prepend '<emphasis remap=tt>9, </emphasis>' to the number here.</para>
   
 <para>
 <informalexample>
 <screen>set timeout 300</screen>
 </informalexample>
 
 This tells the PPP program that it should automatically hang up the
 phone if no data has 
 be exchanged for 300 seconds (5 minutes).  You may wish to tailor this
 number to your 
 specific requirements.</para>
   
 <para>
 <informalexample>
 <screen>set openmode active</screen>
 </informalexample>
 
 This tells the PPP program that once the modems are connected it
 should immediately attempt to negotiate the connection.  Some remote
 sites do this automatically, some don't.  This instructs your side of
 the link to take the initiative and try to set up the connection.</para>
   
 
 
 <screen>accept chap</screen>
 
 
 <para>This tells the PPP program to use the "Challenge-Handshake
 Authentication Protocol" to authenticate you.  The values exchanged
 between the local and remote side for UserID and password are taken
 from the 'authname' and 'authkey' entries above.</para>
   
 </sect3>
 
 <sect3>
 <title>The "<emphasis remap=tt>demand</emphasis>" Section</title>
 
 <para>The "<emphasis remap=tt>demand</emphasis>" section contains the values and settings used
 to set up a "Dial-on-demand" PPP session with a specific remote
 system.  Settings in this section will also have the lines included in
 the "default" section included automatically.</para>
   
 <para>Except for the last two lines in this section it is identical to
 the configuration section which defines the "interactive"
 configuration.</para>
   
 <para>As noted earlier, the examples cited in this section of
 the guide presume that you'll be connecting to a remote system that
 understands how to use the CHAP protocol to set up the connection.</para>
   
 <para>Following are descriptions for each line in the "demand" section of
 the sample '<filename>/etc/ppp/ppp.conf</filename>' file:</para>
   
 <para>
 <informalexample>
 <screen>set authname Your_User_ID_On_Remote_System</screen>
 </informalexample>
 
 This line specifies the name you would use to log in to the remote
 system.  </para>
   
 <para>
 <informalexample>
 <screen>set authkey Your_Password_On_Remote_System</screen>
 </informalexample>
 
 This is the password you'd use to log in to the remote system.</para>
   
 <para>
 <informalexample>
 <screen>set phone 1-800-123-4567</screen>
 </informalexample>
 
 This is the phone number of the remote system.</para>
   
 <para>
 <informalexample>
 <screen>set timeout 300</screen>
 </informalexample>
 </para>
   
 <para>This tells the PPP program that it should automatically hang up the
 phone if no data has be exchanged for 300 seconds (5 minutes).  You
 may wish to tailor this number to your specific requirements.</para>
   
 <para>
 <informalexample>
 <screen>set openmode active</screen>
 </informalexample>
 </para>
   
 <para>This tells the PPP program that once the modems are connected it
 should immediately attempt to negotiate the connection.  Some remote
 sites do this automatically, some don't.  This instructs your side of
 the link to take the initiative and try to set up the connection.</para>
   
 <para>
 <informalexample>
 <screen>accept chap</screen>
 </informalexample>
 </para>
   
 <para>This tells the PPP program to use the "Challenge-Handshake
 Authentication Protocol" to authenticate you.  The values exchanged
 between the local and remote side for UserID and password are taken
 from the 'authname' and 'authkey' entries above.</para>
   
 <para>
 <informalexample>
 <screen>set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0</screen>
 </informalexample>
 </para>
   
 <para>This command sets up a pair of "fake" IP addresses for the local and
 remote sides of the PPP link.  It instructs the PPP program to create
 an IP address of 127.1.1.1 for the local side of the '<emphasis remap=tt>tun0</emphasis>'
 (tunnel) device 
 and 127.2.2.2 for the remote side.  Appending '<filename>/0</filename>' to
 each address tells the PPP program that zero of the bits that make up
 these addresses are significant and can (in fact, must!) be negotiated
 between the local and remote systems when the link is established.
 The 255.255.255.0 string tells the PPP program what Subnet mask to
 apply to these pseudo-interfaces.</para>
   
 <para>Remember, we've assumed that your ISP provides the IP addresses for
 both ends of the link!  If your ISP assigned you a specific IP address
 that you should use on your side when configuring your system, enter
 that IP address here <emphasis>instead</emphasis> of <emphasis remap=tt>127.1.1.1</emphasis>.</para>
   
 <para>Conversly, if your ISP gave you a specific IP address that he uses on
 his end you should enter that IP address here <emphasis>instead</emphasis> of
 <emphasis remap=tt>127.2.2.2</emphasis>.</para>
   
 <para>In both cases, it's probably a good idea to leave the '<filename>/0</filename>' on
 the end of each address.  This gives the PPP program the opportunity
 to change the address(es) of the link if it <emphasis>has</emphasis> to.</para>
   
 <para>
 <informalexample>
 <screen>add 0 0 127.2.2.2</screen>
 </informalexample>
 </para>
   
 <para>This last line tells the PPP program that it should add a default
 route for IP traffic that points to the (fake) IP address of the ISP's
 system.</para>
   
 <para><emphasis><emphasis remap=bf>Note: If you used an ISP-specified address instead of
 <emphasis remap=tt>127.2.2.2</emphasis> on the preceeding line, use the same number here
 instead of <emphasis remap=tt>127.2.2.2</emphasis></emphasis></emphasis>.</para>
   
 <para>By adding this "fake" route for IP traffic, the PPP program can,
 while idle:
 <itemizedlist>
 
 <listitem>
 <para>Accept packets that FreeBSD doesn't already know how to forward,</para>
 </listitem>
 
 <listitem>
 <para>Establish a connection to the ISP "<emphasis>on-the-fly</emphasis>",</para>
 </listitem>
 
 <listitem>
 <para>Reconfigure the IP addresses of the local and remote side of the link,</para>
 </listitem>
 
 <listitem>
 <para>Forward packets between your workstation and the ISP.</para>
 </listitem>
 
 </itemizedlist>
 
 automatically!</para>
   
 <para>Once the number of seconds specified by the timeout value in the
 "default" section have elapsed without any TCP/IP traffic the PPP
 program will automatically close the dial-up connection and the
 process will begin again.</para>
   
 </sect3>
 </sect2>
 
 <sect2>
 <title>The '<filename>/etc/ppp/ppp.linkup</filename>' file</title>
 
 <para>The other file needed to complete the PPP configuration is found in
 '<filename>/etc/ppp/ppp.linkup</filename>'.  This file contains instructions for
 the PPP program on what actions to take after a dial-up link is
 established.</para>
   
 <para>In the case of dial-on-demand configurations the PPP program will need
 to delete the default route that was created to the fake IP address of
 the remote side (127.2.2.2 in our example in the previous section) and
 install a new default route that points the actual IP address of the
 remote end (discovered during the dial-up connection setup).</para>
   
 <para>A representative '<filename>/etc/ppp/ppp.linkup</filename>' file:
 <informalexample>
 <screen>#########################################################################=
 
 # PPP Link Up File ('/etc/ppp/ppp.linkup')
 #
 #  This file is checked after PPP establishes a network connection.
 # 
 #  This file is searched in the following order.
 #
 #  1) First, the IP address assigned to us is searched and
 #     the associated command(s) are executed.
 #
 #  2) If the IP Address is not found, then the label name specified at
 
 #     PPP startup time is searched and the associated command(s) 
 #     are executed.
 #
 #  3) If neither of the above are found then commands under the label
 #     'MYADDR:' are executed.
 #
 #########################################################################=
 
 #
 # This section is used for the "demand" configuration in
 #   /etc/ppp/ppp.conf:
 demand:
  delete ALL
  add 0 0 HISADDR
 #
 # All other configurations in /etc/ppp/ppp.conf use this:
 #
 MYADDR:
  add 0 0 HISADDR
 ########################################################################
 # End of /etc/ppp/ppp.linkup</screen>
 </informalexample>
 
 Notice that there is a section in this file named "demand:", identical
 to the configuration name used in the '<filename>/etc/ppp/ppp.conf</filename>'
 file.  This section instructs the PPP program that once a link is
 established using this configuration, it must:
 <orderedlist>
 
 <listitem>
 <para>Remove any IP routing information that the PPP program has created</para>
 </listitem>
 
 <listitem>
 <para>Add a default route the remote end's actual address.</para>
 </listitem>
 
 </orderedlist>
 </para>
   
 <para>It's critical that those configurations in
 '<filename>/etc/ppp/ppp.conf</filename>' which include the '<emphasis remap=tt>set ifaddr</emphasis>' and
 '<emphasis remap=tt>add 0 0</emphasis>' statements (i.e.: those configurations used for
 Dial-on-Demand configurations) execute the "delete ALL" and "add 0 0
 HISADDR" commands in <filename>/etc/ppp/ppp.linkup</filename>.</para>
   
 <para><emphasis><emphasis remap=bf>This is the mechanism that controls the actual on-demand
 configuration of the link.</emphasis></emphasis></para>
   
 <para>All configurations not explicitly named in
 <filename>/etc/ppp/ppp.linkup</filename> will use whatever commands are in the
 "MYADDR:" section of the file.  This is where non-Demand-Dial
 configurations (such as our "interactive:" sample) will fall through
 to.  This section simply adds a default route to the ISP's IP address
 (at the remote end).</para>
   
 </sect2>
 </sect1>
 
 <sect1>
 <title>IP Aliasing</title>
 
 <para>All of the configuration steps described thus far are relevant to
 any FreeBSD system which will be used to connect to an ISP via dial-up
 connection.</para>
   
 <para>If your sole objective in reading this guide is to connect your
 FreeBSD box to the Internet using dial-out ppp you can proceed to
 <xref linkend="testing-the-network">.</para>
   
 <para>One very attractive feature of the PPP program in on-demand mode is
 its ability to route IP traffic between other systems on the Local
 Area Network automatically.  This feature is known by various names,
 "<emphasis>IP Aliasing</emphasis>", "<emphasis>Network Address Translation</emphasis>", "<emphasis>Address
 Masquerading</emphasis>" or "<emphasis>Transparent Proxying</emphasis>".</para>
   
 <para>Regardless of the terminology used, this mode is not, however,
 automatic.  If the PPP program is started normally then the program
 will not forward packets between LAN interface(s) and the dial-out
 connection. In effect, only the FreeBSD system is connected to the
 ISP; other workstations cannot "share" the same connection.</para>
   
 <para>For example, if the program is started with either of the following
 command lines:</para>
   
 <para><emphasis remap=tt># ppp interactive   (Interactive mode)</emphasis></para>
   
 <para> or</para>
   
 <para><emphasis remap=tt># ppp -auto demand  (Dial-on-Demand mode)</emphasis></para>
   
 <para>then the system will function as an Internet-connected workstation
 <emphasis>only</emphasis> for the 
 FreeBSD box.</para>
   
 <para>To start the PPP program as a gateway between LAN resources and the
 Internet, one of the following command lines would be used instead:</para>
   
 <para><emphasis remap=tt># ppp -alias interactive   (Interactive mode)</emphasis></para>
   
 <para> or</para>
   
 <para><emphasis remap=tt># ppp -auto -alias demand  (Dial-on-Demand mode)</emphasis></para>
   
 <para>You can alternatively use the command <emphasis remap=tt>``alias enable yes''</emphasis>
 in your ppp configuration file (refer to the man page for details).</para>
   
 <para>Keep this in mind if you intend to proceed with <xref
 	  linkend="config-window-system">.</para>      
   
 </sect1>
 </chapter>
 
 <chapter id="config-window-system">
 <title>Configuring Windows Systems</title>
 
 <para>As indicated in Section 1, our example network consists of a
 FreeBSD system ("Curly") which acts as a gateway (or router) between a
 Local Area Network consisting of two different flavors of Windows
 Workstations.  In order for the LAN nodes to use Curly as a router
 they need to be properly configured.  Note that this section does not
 explain how to configure the Windows workstations for Dial-Up
 networking.  If you need a good explanation of that procedure, I
 recommend <ulink URL="http://www.aladdin.co.uk/techweb">http://www.aladdin.co.uk/techweb</ulink>.</para>
   
 
 <sect1>
 <title> Configuring Windows 95</title>
 
 <para>Configuring Windows 95 to act as an attached resource on your LAN
 is relatively simple.  The Windows 95 network configuration must be
 slightly modified to use the FreeBSD system as the default gateway to
 the ISP.  Perform the following steps:</para>
   
 <para><emphasis remap=bf>Create the Windows 95 "hosts" file:</emphasis></para>
   
 <para>In order to connect to the other TCP/IP systems on the LAN you'll
 need to create an identical copy of the "hosts" file that you
 installed on the FreeBSD system in <xref linkend="list-lan-hosts">.
 <itemizedlist>
 
 <listitem>
 <para>Click the "Start" button; select "Run..."; enter "notepad
 \WINDOWS\HOSTS" (without the quotes) and click "OK"</para>
 </listitem>
 
 <listitem>
 <para>In the editor, enter the addresses and system names from the hosts
 file shown in <xref linkend="list-lan-hosts">.</para>
 </listitem>
 
 <listitem>
 <para>When finished editing, close the notepad application (making sure
 that you save the file!).</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configure the Windows 95 TCP/IP Network Configuation
 settings</emphasis>:
 <itemizedlist>
 
 <listitem>
 <para>Click the "Start" button on the taskbar; select "Settings" and
 "Control Panel". </para>
 </listitem>
 
 <listitem>
 <para>Double-click the "Network" icon to open it.</para>
 
 <para> 
 The settings for all Network Elements are displayed.</para>
 </listitem>
 
 <listitem>
 <para>With the "Configuration" tab selected, scroll down the list of
 installed components and highlight the "TCP/IP-&gt;<emphasis>YourInterfaceType</emphasis>" line
 (where "<emphasis>YourInterfaceType</emphasis>" is the name or type of Ethernet adapter in your system).
 </para>
 
 <para>If TCP/IP is not listed in the list of installed network
 components, click the "Add" button and install it before proceeding.</para>
 
 <para>(Hint:  "Add | Protocol | Microsoft | TCP/IP | OK")</para>
 </listitem>
 
 <listitem>
 <para>Click on the "Properties" button to display a list of the
 settings associated with the TCP component.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configure the IP Address Information:</emphasis>
 <itemizedlist>
 
 <listitem>
 <para>Click the "IP Address" tab</para>
 </listitem>
 
 <listitem>
 <para>Click the "Specify an IP address" radio button. 
 </para>
 
 <para>(In our example LAN the Windows 95 system is the one we've called "Larry".)</para>
 </listitem>
 
 <listitem>
 <para>In the "IP Address" field enter "192.168.1.2".</para>
 </listitem>
 
 <listitem>
 <para>Enter 255.255.255.0 in the "Subnet Mask" field.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configure the Gateway information:</emphasis>
 <itemizedlist>
 
 <listitem>
 <para>Click on the "Gateway" tab
 </para>
 
 <para>For our example network the FreeBSD box will be acting as our
 gateway to the Internet (routing packets between the Ethernet LAN and
 the PPP dial-up connection.  Enter the IP address of the FreeBSD
 Ethernet interface, 192.168.1.1, in the "New gateway" field and click
 the "Add" button.  If any other gateways are defined in the "Installed
 gateways" list you may wish to consider removing them.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configure the DNS Information:</emphasis></para>
   
 <para>This guide assumes that your Internet Service Provider has given
 you a list of Domain Name Servers (or "DNS Servers") that you should
 use.  If you wish to run a DNS server on your local FreeBSD system,
 refer to Section 6, "Exercise for the Interested Student" for tips on
 setting up DNS on your FreeBSD system.</para>
   
 <para>
 <itemizedlist>
 
 <listitem>
 <para>Click the "DNS Configuration" tab</para>
 </listitem>
 
 <listitem>
 <para>Make sure that the "Enable DNS" radio button is selected.
 </para>
 
 <para>(If this button is not selected only the entries that 
 we put in the host file(s) will be available and your Net-Surfing 
 will not work as you expect!)</para>
 </listitem>
 
 <listitem>
 <para>In the "Host" field enter the name of the Windows 95 box, in this
 case: "Larry".</para>
 </listitem>
 
 <listitem>
 <para>In the "Domain" field enter the name of our local network, in this
 case: "my.domain"</para>
 </listitem>
 
 <listitem>
 <para>In the "DNS Server Search Order" section, enter the IP address
 of the DNS server(s) that your ISP provided, clicking the "Add" button
 after every address is entered.  Repeat this step as many times as
 necessary to add all of the addresses that your ISP provided.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Other Windows 95 TCP/IP options:</emphasis></para>
   
 <para>For our purposes the settings under the "Advanced", "WINS
 Configuration" and "Bindings" tabs are not necessary.</para>
   
 <para>If you wish to use the Windows Internet Naming Service ("WINS")
 your attention is invited to <ulink URL="http://www.localnet.org">http://www.localnet.org</ulink> for
 more information about WINS settings, specifically regarding sharing
 files transparently across the Internet.</para>
   
 <para><emphasis remap=bf>Mopping up:</emphasis>
 <itemizedlist>
 
 <listitem>
 <para>Click on the "OK" button to close the TCP/IP Properties window.</para>
 </listitem>
 
 <listitem>
 <para>Click on the "OK" button to close the Network Control Panel. </para>
 </listitem>
 
 <listitem>
 <para>Reboot your computer if prompted to do so. </para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para> That's it!</para>
   
 </sect1>
 
 <sect1>
 <title>Configuring Windows NT</title>
 
 <para>Configuring Windows NT to act as a LAN resource is also relatively
 straightforward.  The procedures for configuring Windows NT are
 similar to Windows 95 with minor exceptions in the user interface.</para>
   
 <para>The steps shown here are appropriate for a Windows NT 4.0
 Workstation, but the principles are the same for NT 3.5x.  You may
 wish to refer to the "Configuring Windows for Workgroups" section if
 you're configuring Windows NT 3.5<emphasis remap=it>x</emphasis>, since the user interface is
 the same for NT 3.5 and WfW.</para>
   
 <para>Perform the following steps: </para>
   
 <para><emphasis remap=bf>Create the Windows NT "hosts" file:</emphasis></para>
   
 <para>In order to connect to the other TCP/IP systems on the LAN you'll
 need to create an identical copy of the "hosts" file that you
 installed on the FreeBSD system in Section 3.4
 <itemizedlist>
 
 <listitem>
 <para>Click the "Start" button; select "Run..."; enter "notepad
 \WINNT\SYSTEM32\DRIVERS\ETC\HOSTS" (without the quotes) and click
 "OK"</para>
 </listitem>
 
 <listitem>
 <para>In the editor, enter the addresses and system names from Section
 3.4.</para>
 </listitem>
 
 <listitem>
 <para>When finished editing, close the notepad application (making sure
 that you save the file!).</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configure the Windows NT TCP/IP Network Configuation
 settings</emphasis>:
 <itemizedlist>
 
 <listitem>
 <para>Click the "Start" button on the taskbar; select "Settings" and
 "Control Panel". </para>
 </listitem>
 
 <listitem>
 <para>Double-click the "Network" icon to open it. </para>
 </listitem>
 
 <listitem>
 <para>With the "Identification" tab selected, verify the "Computer Name"
 and "Workgroup" fields.  In this example we'll use "Shemp" for the name
 and "Stooges" for the workgroup.  Click the "Change" button and amend
 these entries as necessary.</para>
 </listitem>
 
 <listitem>
 <para>Select the "Protocols" tab. 
 
 </para>
 
 <para>The installed Network Protocols will be displayed.  There may be a
 number of protocols listed but the one of interest to this guide is
 the "TCP/IP Protocol".  If "TCP/IP Protocol" is not listed, click the
 "Add" button to load it.</para>
 
 <para>(Hint: "Add | TCP/IP Protocol | OK") </para>
 </listitem>
 
 <listitem>
 <para>Highlight "TCP/IP
 Protocol" and click the "Properties" button.
 </para>
 
 <para>Tabs for specifying various settings for TCP/IP will be displayed.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configuring the IP Address:</emphasis></para>
   
 <para>Make sure that the Ethernet Interface is shown in the "Adapter"
 box; if not, scroll through the list of adapters until the correct
 interface is shown.
 <itemizedlist>
 
 <listitem>
 <para>Click the "Specify an IP address" radio button to enable the three
 text boxes.
 </para>
 
 <para>In our example LAN the Windows NT system is the one we've called
 "Shemp"</para>
 </listitem>
 
 <listitem>
 <para>In the "IP Address" field enter "192.168.1.4".</para>
 </listitem>
 
 <listitem>
 <para>Enter 255.255.255.0 in the "Subnet Mask" field.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configure the Gateway information:</emphasis></para>
   
 <para>For our example network the FreeBSD box will be acting as our gateway
 to the Internet (routing packets between the Ethernet LAN and the PPP dial-up
 connection.
 <itemizedlist>
 
 <listitem>
 <para>Enter the IP address of the FreeBSD Ethernet interface,
 192.168.1.1, in the "New gateway" field and click the "Add" button.  
 </para>
 
 <para>If any other gateways are defined in the "Installed gateways" list
 you may wish to consider removing them.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configuring DNS:</emphasis></para>
   
 <para>Again, this guide assumes that your Internet Service Provider has
 given you a list of Domain Name Servers (or "DNS Servers") that you
 should use.</para>
   
 <para>If you wish to run a DNS server on your local FreeBSD system, refer to
 Section 6, "Exercise for the Interested Student" for tips on setting
 up DNS on your FreeBSD system.
 <itemizedlist>
 
 <listitem>
 <para>Click the "DNS" tab</para>
 </listitem>
 
 <listitem>
 <para>In the "Host Name" field enter the name of the Windows NT box, in
 this case: "Shemp".</para>
 </listitem>
 
 <listitem>
 <para>In the "Domain" field enter the name of our local network, in this
 case: "my.domain"</para>
 </listitem>
 
 <listitem>
 <para>In the "DNS Server Search Order" section, enter the IP address of
 the DNS server that your ISP provided, clicking the "Add" button after
 every address is entered.  Repeat this step as many times as necessary
 to add all of the addresses that your ISP provided.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Other Windows NT TCP/IP options:</emphasis></para>
   
 <para>For our purposes the settings under the "WINS Address" and
 "Routing" tabs are not used.</para>
   
 <para>If you wish to use the Windows Internet Naming Service ("WINS")
 your attention is invited to <ulink URL="http://www.localnet.org">http://www.localnet.org</ulink> for
 more information about WINS settings, specifically regarding sharing
 files transparently across the Internet.</para>
   
 <para><emphasis remap=bf>Mopping up:</emphasis>
 <itemizedlist>
 
 <listitem>
 <para>Click on the "OK" button to close the TCP/IP Properties section.
 </para>
 </listitem>
 
 <listitem>
 <para>Click on the "Close" button to close the Network Control Panel.
 </para>
 </listitem>
 
 <listitem>
 <para>Restart your computer if prompted to do so.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>That's it!</para>
   
 </sect1>
 
 <sect1>
 <title>Configuring Windows for Workgroups</title>
 
 <para>Configuring Windows for Workgroups to act as a network client
 requires that the Microsoft TCP/IP-32 driver diskette has been
 installed on the workstation.  The TCP/IP drivers are not included
 with the WfW CD or diskettes; if you need a copy they're available at
 <ulink URL="ftp://ftp.microsoft.com:/peropsys/windows/public/tcpip">ftp://ftp.microsoft.com:/peropsys/windows/public/tcpip</ulink>.</para>
   
 <para>Once the TCP/IP drivers have been loaded, perform the following
 steps:</para>
   
 <para><emphasis remap=bf>Create the Windows for Workgroups "hosts" file:</emphasis></para>
   
 <para>In order to connect to the other TCP/IP systems on the LAN you'll
 need to create an identical copy of the "hosts" file that you
 installed on the FreeBSD system in Section 3.4.
 <itemizedlist>
 
 <listitem>
 <para>In Program Manager, click the "File" button; select "Run"; and
 enter: "notepad \WINDOWS\HOSTS" (without the quotes) and click "OK"</para>
 </listitem>
 
 <listitem>
 <para>In the editor, enter the addresses and system names from the hosts
 file shown in Section 3.4.</para>
 </listitem>
 
 <listitem>
 <para>When finished editing, close the notepad application (making sure
 that you save the file!).</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configure the Windows 95 TCP/IP Network Configuation
 settings</emphasis>
 <itemizedlist>
 
 <listitem>
 <para>In the main window of Program Manager, open the "Network" group by
 double-clicking the icon. </para>
 </listitem>
 
 <listitem>
 <para>Double click on the "Network Setup" icon. </para>
 </listitem>
 
 <listitem>
 <para>In the "Network Drivers Box" double-click the "Microsoft
 TCP/IP-32" entry. </para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configure the Windows for Workgroups IP Address:</emphasis> </para>
   
 <para>Ensure
 the correct Ethernet Interface is selected in the "Adapter" list.  If
 not, scroll down until it is displayed and select it by clicking on
 it.
 <itemizedlist>
 
 <listitem>
 <para>Ensure that the "Enable Automatic DHCP Configuration" check box is
 blank.  If it is checked, click it to remove the "X".</para>
 </listitem>
 
 <listitem>
 <para>In our example LAN the Windows for Workgroups system is the one
 we've called "Moe"; in the "IP Address" field enter "192.168.1.3".</para>
 </listitem>
 
 <listitem>
 <para>Enter 255.255.255.0 in the "Subnet Mask" field.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configure the Gateway information:</emphasis></para>
   
 <para>For our example network the FreeBSD box will be acting as our
 gateway to the Internet (routing packets between the Ethernet LAN and
 the PPP dial-up connection).
 <itemizedlist>
 
 <listitem>
 <para>Enter the IP address of the FreeBSD system, 192.168.1.1, in the
 "Default Gateway" field.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Configuring DNS:</emphasis></para>
   
 <para>Again, this guide assumes that your Internet Service Provider has
 given you a list of Domain Name Servers (or "DNS Servers") that you
 should use.  If you wish to run a DNS server on your local FreeBSD
 system, refer to Section 6, "Exercise for the Interested Student" for
 tips on setting up DNS on your FreeBSD system.
 <itemizedlist>
 
 <listitem>
 <para>Click the "DNS" button.</para>
 </listitem>
 
 <listitem>
 <para>In the "Host Name" field enter the name of the Windows for
 Workgroups box, in this case: "Moe".</para>
 </listitem>
 
 <listitem>
 <para>In the "Domain" field enter the name of our local network, in this
 case: "my.domain"</para>
 </listitem>
 
 <listitem>
 <para>In the "Domain Name Service (DNS) Search Order" section, enter the
 IP address of the DNS server that your ISP provided, clicking the "Add"
 button after each address is entered.  Repeat this step as many times as
 necessary to add all of the addresses that your ISP provided.</para>
 </listitem>
 
 <listitem>
 <para>Click on the "OK" button to close the DNS Configuration window.
 </para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para><emphasis remap=bf>Mopping up:</emphasis>
 <itemizedlist>
 
 <listitem>
 <para>Click on the "OK" button to close the TCP/IP Configuration window.
 </para>
 </listitem>
 
 <listitem>
 <para>Click on the "OK" button to close the Network Setup window.</para>
 </listitem>
 
 <listitem>
 <para>Reboot your computer if prompted. </para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>That's it!</para>
   
 </sect1>
 </chapter>
 
 <chapter id="testing-the-network">
 <title>Testing the Network</title>
 
 <para> Once you've completed that appropriate tasks above you should have
 a functioning PPP gateway to the Internet.</para>
   
 
 <sect1>
 <title>Testing the Dial-Up link:</title>
 
 <para> The first thing to test is that the connection is being made
 between your modem and the ISP.</para>
   
 </sect1>
 
 <sect1>
 <title>Testing the Ethernet LAN</title>
 
 <para> *** TBD ***</para>
   
 </sect1>
 </chapter>
 
 <chapter>
 <title>Exercises for the Interested Student</title>
 
 
 <sect1>
 <title>Creating a mini-DNS system</title>
 
 <para>While managing a Domain Name Service (DNS) hierarchy can be a black
 art, it is possible to set up a Mini-DNS server on the FreeBSD system
 that also acts as your gateway to your ISP.</para>
   
 <para>Building on the files in <filename>/etc/namedb</filename> when the FreeBSD
 system was installed it's possible to create a name server that is
 both authoritative for the example network shown here as well as a
 front-door to the Internet DNS architecture.</para>
   
 <para>In this minimal DNS configuration, only three files are necessary:
 <informalexample>
 <screen>/etc/namedb/named.boot
 /etc/namedb/named.root
 /etc/namedb/mydomain.db</screen>
 </informalexample>
 </para>
   
 <para>The <filename>/etc/namedb/named.root</filename> file is automatically installed
 as part of the FreeBSD base installation; the other two files must be
 created manually.</para>
   
 
 <sect2>
 <title>The <filename>/etc/namedb/named.boot</filename> file</title>
 
 <para>The <filename>/etc/namedb/named.boot</filename> file controls the startup
 settings of the DNS server.
 Esentially, it tells the Name Server:
 <orderedlist>
 
 <listitem>
 <para>Where to find configuration files,</para>
 </listitem>
 
 <listitem>
 <para>What "domain names" it's responsible for, and</para>
 </listitem>
 
 <listitem>
 <para>Where to find other DNS servers.</para>
 </listitem>
 
 </orderedlist>
 </para>
   
 <para>Using the '<emphasis remap=tt>ee</emphasis>' editor, create a
 <filename>/etc/namedb/named.boot</filename> with the following contents:
 <informalexample>
 <screen>; boot file for mini-name server
 
 directory	/etc/namedb
 
 ; type    domain		source host/file		backup file
 
 cache     .			named.root
 primary   my.domain.		mydomain.db</screen>
 </informalexample>
 </para>
   
 <para>Lines that begin with a semi-colon are comments.  The significant
 lines in this file are:
 <itemizedlist>
 
 <listitem>
 <para><command>directory /etc/namedb</command>
 </para>
 
 <para>Tells the Name Server where to find the configuration files
 referenced in the remaining sections of the
 '<filename>/etc/namedb/named.boot</filename>' file.</para>
 </listitem>
 
 <listitem>
 <para><emphasis remap=tt>cache . named.root</emphasis>
 </para>
 
 <para>Tells the Name Server that the list of "Top-Level" DNS servers for
 the Internet can be found in a file called '<filename>named.root</filename>'.
 (This file is included in the base installation and its 
 contents are not described in this document.)</para>
 </listitem>
 
 <listitem>
 <para><emphasis remap=tt>primary my.domain. mydomain.db</emphasis>
 </para>
 
 <para>Tells the Name Server that it will be "authoritative" for a DNS
 domain called "my.domain" and that a list of names and IP addresses
 for the systems in "my.domain" (the local network)
 can be found in a file named '<filename>mydomain.db</filename>'.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>Once the <filename>/etc/namedb/named.boot</filename> file has been created and
 saved, proceed to the next section to create the
 <filename>/etc/namedb/mydomain.db</filename> file.</para>
   
 </sect2>
 
 <sect2>
 <title>The <filename>/etc/namedb/mydomain.db</filename> file</title>
 
 <para>The <filename>/etc/namedb/mydomain.db</filename> file lists the names and IP
 addresses of <emphasis>every</emphasis> system in the Local Area Network.</para>
   
 <para><emphasis>For a detailed description of the statements used in this file,
 refer to the <emphasis remap=tt>named</emphasis> manpage.</emphasis></para>
   
 <para>The <filename>/etc/namedb/mydomain.db</filename> file for our minimal DNS
 server has the following contents:
 <informalexample>
 <screen>@	IN SOA	my.domain. root.my.domain.  (
 				961230	; Serial
 				3600	; Refresh
 				300	; Retry
 				3600000	; Expire
 				3600 )	; Minimum
 	IN NS	curly.my.domain.
 
 curly.my.domain.	IN A	192.168.1.1	# The FreeBSD box
 larry.my.domain.	IN A	192.168.1.2	# The Win'95 box
 moe.my.domain.		IN A	192.168.1.3	# The WfW box
 shemp.my.domain.	IN A	192.168.1.4	# The Windows NT box
 
 $ORIGIN 1.168.192.IN-ADDR.ARPA
 		IN NS	curly.my.domain.
 1		IN PTR	curly.my.domain.
 2		IN PTR	larry.my.domain.
 3		IN PTR	moe.my.domain.
 4		IN PTR	shemp.my.domain.
 
 $ORIGIN 0.0.127.IN-ADDR.ARPA
 		IN NS	curly.my.domain.
 1		IN PTR	localhost.my.domain.</screen>
 </informalexample>
 </para>
   
 <para>In simple terms, this file declares that the local DNS server is:
 <itemizedlist>
 
 <listitem>
 <para>The Start of Authority for ("SOA") for a domain called
 'my.domain',</para>
 </listitem>
 
 <listitem>
 <para>The Name Server ("NS") for 'my.domain',</para>
 </listitem>
 
 <listitem>
 <para>Responsible for the reverse-mapping for all IP addresses that
 start with '192.168.1.' and 
 '127.0.0.' ("$ORIGIN ...")</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>To add workstation entries to this file you'll need to add two
 lines for each system; one in the top section where the name(s) are
 mapped into Internet Addresses ("IN A"), and another line that maps
 the addresses back into names in the <filename>$ORIGIN
 1.168.192.IN-ADDR.ARPA</filename> section.</para>
   
 </sect2>
 
 <sect2>
 <title>Starting the DNS Server</title>
 
 <para>By default the DNS server ('<filename>/usr/sbin/named</filename>') is not
 started when the system boots.  You can modify this behavior by
 changing a single line in '<filename>/etc/rc.conf</filename>' as follows:</para>
   
 <para> Using the '<emphasis remap=tt>ee</emphasis>' editor, load <filename>/etc/rc.conf</filename>.  Scroll
 down approximately 40 lines until you come to the section that says:
 <informalexample>
 <screen>---
 named_enable="NO"                       # Run named, the DNS server (or NO).
 named_flags="-b /etc/namedb/named.boot" # Flags to named (if enabled).
 ---</screen>
 </informalexample>
 
 Change this section to read:
 <informalexample>
 <screen>---
 named_enable="YES"                      # Run named, the DNS server (or NO).
 named_flags="-b /etc/namedb/named.boot" # Flags to named (if enabled).
 ---</screen>
 </informalexample>
 
 Save the file and reboot.</para>
   
 <para>Alternatively, start the Name Server daemon by entering the following
 command:
 <informalexample>
 <screen># named -b /etc/namedb/named.boot</screen>
 </informalexample>
 </para>
   
 <para>Whenever you modify any of the files in <filename>/etc/namedb</filename> you'll
 need to kick-start the Name Server process to make it pick up the
 modifications.  This is performed with the following system command:
 <informalexample>
 <screen># kill -HUP `cat /var/run/named.pid`</screen>
 </informalexample>
 </para>
   
 </sect2>
 </sect1>
 
 <sect1>
 <title>Playing with PPP filters</title>
 
 <para>The PPP program has the ability to apply selected filtering rules
 to the traffic it routes.  While this is not nearly as secure as a
 formal firewall it does provide some access control as to how the link
 is used.</para>
   
 <para>('<emphasis remap=tt>man ipfw</emphasis>' for information on setting up a more secure
 FreeBSD system.)</para>
   
 <para>The complete documentation for the various filters and rules under
 PPP are availabe in the PPP manpage.</para>
   
 <para>There are four distinct classes of rules which may be applied to
 the PPP program:
 <itemizedlist>
 
 <listitem>
 <para><emphasis>alive</emphasis> filter - Access Counter (or "Keep Alive") filters
 </para>
 
 <para>These control which events are ignored by the <literal>set timeout=</literal>
 statement in the configuration file.</para>
 </listitem>
 
 <listitem>
 <para><emphasis>dial</emphasis> filter - Dialing filters
 </para>
 
 <para>These filtering rules control which events are ignored by the
 demand-dial mode of PPP.</para>
 </listitem>
 
 <listitem>
 <para><emphasis>in</emphasis> filter - Input filters
 </para>
 
 <para>Control whether incoming packets should be discarded or passed into
 the system.</para>
 </listitem>
 
 <listitem>
 <para><emphasis>out</emphasis> filter - Output filters
 </para>
 
 <para>Control whether outgoing packets should be discarded or passed into
 the system.</para>
 </listitem>
 
 </itemizedlist>
 </para>
   
 <para>What follows is a snippet from an operating system which provides a
 good foundation for "normal" Internet operations while preventing PPP
 from pumping <emphasis>all</emphasis> data over the dial-up connection.  Comments
 briefly describe the logic of each rule set:
 <informalexample>
 <screen>#
 # KeepAlive filters
 # Don't keep Alive with ICMP,DNS and RIP packet
 #
  set filter alive 0 deny icmp
  set filter alive 1 deny udp src eq 53
  set filter alive 2 deny udp dst eq 53
  set filter alive 3 deny udp src eq 520
  set filter alive 4 deny udp dst eq 520
  set filter alive 5 permit 0/0 0/0
 #
 # Dial Filters:
 #  Note:  ICMP will trigger a dial-out in this configuration!
 #
  set filter dial 0 permit 0/0 0/0
 #
 # Allow ident packet pass through
 #
  set filter in 0 permit tcp dst eq 113
  set filter out 0 permit tcp src eq 113
 #
 # Allow telnet connection to the Internet
 #
  set filter in 1 permit tcp src eq 23 estab
  set filter out 1 permit tcp dst eq 23
 #
 # Allow ftp access to the Internet
 #
  set filter in 2 permit tcp src eq 21 estab
  set filter out 2 permit tcp dst eq 21
  set filter in 3 permit tcp src eq 20 dst gt 1023
  set filter out 3 permit tcp dst eq 20
 #
 # Allow access to DNS lookups
 #
  set filter in 4 permit udp src eq 53
  set filter out 4 permit udp dst eq 53
 #
 # Allow DNS Zone Transfers
 #
  set filter in 5 permit tcp src eq 53
  set filter out 5 permit tcp dst eq 53
 #
 # Allow access from/to local network
 #
  set filter in 6 permit 0/0 192.168.1.0/24
  set filter out 6 permit 192.168.1.0/24 0/0
 #
 # Allow ping and traceroute response
 #
  set filter in 7 permit icmp
  set filter out 7 permit icmp
  set filter in 8 permit udp dst gt 33433
  set filter out 9 permit udp dst gt 33433
 #
 # Allow cvsup
 #
  set filter in 9 permit tcp src eq 5998
  set filter out 9 permit tcp dst eq 5998
  set filter in 10 permit tcp src eq 5999
  set filter out 10 permit tcp dst eq 5999
 #
 # Allow NTP for Time Synchronization
 #
  set filter in 11 permit tcp src eq 123 dst eq 123
  set filter out 11 permit tcp src eq 123 dst eq 123
  set filter in 12 permit udp src eq 123 dst eq 123
  set filter out 12 permit udp src eq 123 dst eq 123
 #
 # SMTP'd be a good idea!
 #
  set filter in 13 permit tcp src eq 25
  set filter out 13 permit tcp dst eq 25
 #
 #
 # We use a lot of `whois`, let's pass that
 #
  set filter in 14 permit tcp src eq 43
  set filter out 14 permit tcp dst eq 43
  set filter in 15 permit udp src eq 43
  set filter out 15 permit udp dst eq 43
 #
 # If none of above rules matches, then packet is blocked.
 #-------</screen>
 </informalexample>
 </para>
   
 <para>Up to 20 distinct filtering rules can be applied to each class of
 filter.  Rules in each class are number sequentially from 0 to 20
 <emphasis>but none of the rules for a particular filter class take affect
 until ruleset '0' is defined!</emphasis></para>
   
 <para>If you choose <emphasis>not</emphasis> to use Filtering Rules in the PPP
 configuration then <acronym>ALL</acronym> traffic will be permitted both into and
 out of your system while it's connected to your ISP.</para>
   
 <para>If you decide that you want to implement filtering rules, add the
 above lines to your <filename>/etc/ppp/ppp.conf</filename> file in either the
 "default:", "demand:", or "interactive:" section (or all of them - the
 choice is yours).</para>
   
 </sect1>
 </chapter>
 </book>