diff --git a/en_US.ISO8859-1/books/arch-handbook/boot/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/boot/chapter.sgml
index 4fbb435473..66e0b8e8aa 100644
--- a/en_US.ISO8859-1/books/arch-handbook/boot/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/boot/chapter.sgml
@@ -1,1023 +1,1023 @@
 <!--
 The FreeBSD Documentation Project
 
 Copyright (c) 2002 Sergey Lyubka <devnull@uptsoft.com>
 All rights reserved
 $FreeBSD$
 -->
 
 <chapter id="boot">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Sergey</firstname>
 	<surname>Lyubka</surname>
 	<contrib>Contributed by </contrib>
       </author> <!-- devnull@uptsoft.com  12 Jun 2002 -->
     </authorgroup>
   </chapterinfo>
   <title>Bootstrapping and kernel initialization</title>
 
-  <sect1>
+  <sect1 id="boot-synopsis">
     <title>Synopsis</title>
 
     <para>This chapter is an overview of the boot and system
       initialization process, starting from the BIOS (firmware) POST,
       to the first user process creation.  Since the initial steps of
       system startup are very architecture dependent, the IA-32
       architecture is used as an example.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-overview">
     <title>Overview</title>
 
     <para>A computer running FreeBSD can boot by several methods,
       although the most common method, booting from a harddisk where
       the OS is installed, will be discussed here.  The boot process
       is divided into several steps:</para>
 
     <itemizedlist>
       <listitem><para>BIOS POST</para></listitem>
       <listitem><para><literal>boot0</literal> stage</para></listitem>
       <listitem><para><literal>boot2</literal> stage</para></listitem>
       <listitem><para>loader stage</para></listitem>
       <listitem><para>kernel initialization</para></listitem>
     </itemizedlist>
 
     <para>The <literal>boot0</literal> and <literal>boot2</literal>
       stages are also referred to as <emphasis>bootstrap stages 1 and
       2</emphasis> in &man.boot.8; as the first steps in FreeBSD's
       3-stage bootstrapping procedure.  Various information is printed
       on the screen at each stage, so you may visually recognize them
       using the table that follows.  Please note that the actual data
       may differ from machine to machine:</para>
 
     <informaltable>
       <tgroup cols="2">
         <tbody>
           <row>
             <entry><para>may vary</para></entry>
 
 	    <entry><para>BIOS (firmware) messages</para></entry>
           </row>
 
           <row>
             <entry><para>
 <screen>F1    FreeBSD
 F2    BSD
 F5    Disk 2</screen>
             </para></entry>
 
 	    <entry><para><literal>boot0</literal></para></entry>
           </row>
 
           <row>
             <entry><para>
 <screen>>>FreeBSD/i386 BOOT
 Default: 1:ad(1,a)/boot/loader
 boot:</screen>
             </para></entry>
 
 	    <entry><para><literal>boot2</literal><footnote><para>This
 	      prompt will appear if the user presses a key just after
 	      selecting an OS to boot at the <literal>boot0</literal>
               stage.</para></footnote></para></entry>
           </row>
 
           <row>
             <entry><para>
 <screen>BTX loader 1.0 BTX version is 1.01
 BIOS drive A: is disk0
 BIOS drive C: is disk1
 BIOS 639kB/64512kB available memory
 FreeBSD/i386 bootstrap loader, Revision 0.8
 Console internal video/keyboard
 (jkh@bento.freebsd.org, Mon Nov 20 11:41:23 GMT 2000)
 /kernel text=0x1234 data=0x2345 syms=[0x4+0x3456]
 Hit [Enter] to boot immediately, or any other key for command prompt
 Booting [kernel] in 9 seconds..._</screen>
             </para></entry>
 
             <entry><para>loader</para></entry>
           </row>
 
           <row>
             <entry><para>
 	      <screen>Copyright (c) 1992-2002 The FreeBSD Project.
 Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
         The Regents of the University of California. All rights reserved.
 FreeBSD 4.6-RC #0: Sat May  4 22:49:02 GMT 2002
     devnull@kukas:/usr/obj/usr/src/sys/DEVNULL
 Timecounter "i8254"  frequency 1193182 Hz</screen></para></entry>
 
             <entry><para>kernel</para></entry>
           </row>
         </tbody>
       </tgroup>
     </informaltable>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-bios">
     <title>BIOS POST</title>
 
     <para>When the PC powers on, the processor's registers are set
       to some predefined values.  One of the registers is the
       <emphasis>instruction pointer</emphasis> register, and its value
       after a power on is well defined: it is a 32-bit value of
       0xffffff00.  The instruction pointer register points to code to
       be executed by the processor.  One of the registers is the
       <literal>cr1</literal> 32-bit control register, and its value
       just after the reboot is 0.  One of the cr1's bits, the bit PE
       (Protected Enabled) indicates whether the processor is running
       in protected or real mode.  Since at boot time this bit is
       cleared, the processor boots in real mode.  Real mode means,
       among other things, that linear and physical addresses are
       identical.</para>
 
     <para>The value of 0xffffff00 is slightly less then 4Gb, so unless
       the machine has 4Gb physical memory, it cannot point to a valid
       memory address.  The computer's hardware translates this address
       so that it points to a BIOS memory block.</para>
 
     <para>BIOS stands for <emphasis>Basic Input Output
       System</emphasis>, and it is a chip on the motherboard that has
       a relatively small amount of read-only memory (ROM).  This
       memory contains various low-level routines that are specific to
       the hardware supplied with the motherboard.  So, the processor
       will first jump to the address 0xffffff00, which really resides
       in the BIOS's memory.  Usually this address contains a jump
       instruction to the BIOS's POST routines.</para>
 
     <para>POST stands for <emphasis>Power On Self Test</emphasis>.
       This is a set of routines including the memory check, system bus
       check and other low-level stuff so that the CPU can initialize
       the computer properly.  The important step on this stage is
       determining the boot device.  All modern BIOS's allow the boot
       device to be set manually, so you can boot from a floppy,
       CD-ROM, harddisk etc.</para>
 
     <para>The very last thing in the POST is the <literal>INT
       0x19</literal> instruction.  That instruction reads 512 bytes
       from the first sector of boot device into the memory at address
       0x7c00.  The term <emphasis>first sector</emphasis> originates
       from harddrive architecture, where the magnetic plate is divided
       to a number of cylindrical tracks.  Tracks are numbered, and
       every track is divided by a number (usually 64) sectors.  Track
       number 0 is the outermost on the magnetic plate, and sector 1,
       the first sector (tracks, or, cylinders, are numbered starting
       from 0, but sectors - starting from 1), has a special meaning.
       It is also called Master Boot Record, or MBR.  The remaining
       sectors on the first track are never used <footnote><para>Some
       utilities such as &man.disklabel.8; may store the information in
       this area, mostly in the second
       sector.</para></footnote>.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-boot0">
     <title><literal>boot0</literal> stage</title>
 
     <para>Take a look at the file <filename>/boot/boot0</filename>.
       This is a small 512-byte file, and it is exactly what FreeBSD's
       installation procedure wrote to your harddisk's MBR if you chose
       the <quote>bootmanager</quote> option at installation time.</para>
 
     <para>As mentioned previously, the <literal>INT 0x19</literal>
       instruction loads an MBR, i.e. the <filename>boot0</filename>
       content, into the memory at address 0x7c00.  Taking a look at
       the file <filename>sys/boot/i386/boot0/boot0.s</filename> can
       give a guess at what is happening there - this is the boot
       manager, which is an awesome piece of code written by Robert
       Nordier.</para>
 
     <para>The MBR, or, <filename>boot0</filename>, has a special
       structure starting from offset 0x1be, called the
       <emphasis>partition table</emphasis>.  It has 4 records of 16
       bytes each, called <emphasis>partition records</emphasis>, which
       represent how the harddisk(s) are partitioned, or, in FreeBSD's
       terminology, sliced.  One byte of those 16 says whether a
       partition (slice) is bootable or not.  Exactly one record must
       have that flag set, otherwise <filename>boot0</filename>'s code
       will refuse to proceed.</para>
 
     <para>A partition record has the following fields:</para>
 
     <itemizedlist>
       <listitem>
         <para>the 1-byte filesystem type</para>
       </listitem>
 
       <listitem>
         <para>the 1-byte bootable flag</para>
       </listitem>
 
       <listitem>
         <para>the 6 byte descriptor in CHS format</para>
       </listitem>
 
       <listitem>
         <para>the 8 byte descriptor in LBA format</para>
       </listitem>
     </itemizedlist>
 
     <para>A partition record descriptor has the information about
       where exactly the partition resides on the drive.  Both
       descriptors, LBA and CHS, describe the same information, but in
       different ways: LBA (Logical Block Addressing) has the starting
       sector for the partition and the partition's length, while CHS
       (Cylinder Head Sector) has coordinates for the first and last
       sectors of the partition.</para>
 
     <para>The boot manager scans the partition table and prints the
       menu on the screen so the user can select what disk and what
       slice to boot.  By pressing an appropriate key,
       <filename>boot0</filename> performs the following
       actions:</para>
 
     <itemizedlist>
       <listitem>
 	<para>modifies the bootable flag for the selected partition to
 	  make it bootable, and clears the previous</para>
       </listitem>
 
       <listitem>
 	<para>saves itself to disk to remember what partition (slice)
 	  has been selected so to use it as the default on the next
 	  boot</para>
       </listitem>
 
       <listitem>
 	<para>loads the first sector of the selected partition (slice)
 	  into memory and jumps there</para>
       </listitem>
     </itemizedlist>
 
     <para>What kind of data should reside on the very first sector of
       a bootable partition (slice), in our case, a FreeBSD slice?  As
       you may have already guessed, it is
       <filename>boot2</filename>.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-boot2">
     <title><literal>boot2</literal> stage</title>
 
     <para>You might wonder, why <literal>boot2</literal> comes after
       <literal>boot0</literal>, and not boot1.  Actually, there is a
       512-byte file called <filename>boot1</filename> in the directory
       <filename>/boot</filename> as well.  It is used for booting from
       a floppy.  When booting from a floppy,
       <filename>boot1</filename> plays the same role as
       <filename>boot0</filename> for a harddisk: it locates
       <filename>boot2</filename> and runs it.</para>
 
     <para>You may have realized that a file
       <filename>/boot/mbr</filename> exists as well.  It is a
       simplified version of <filename>boot0</filename>.  The code in
       <filename>mbr</filename> does not provide a menu for the user,
       it just blindly boots the partition marked active.</para>
 
     <para>The code implementing <filename>boot2</filename> resides in
       <filename>sys/boot/i386/boot2/</filename>, and the executable
       itself is in <filename>/boot</filename>.  The files
       <filename>boot0</filename> and <filename>boot2</filename> that
       are in <filename>/boot</filename> are not used by the bootstrap,
       but by utilities such as <application>boot0cfg</application>.
       The actual position for <filename>boot0</filename> is in the
       MBR.  For <filename>boot2</filename> it is the beginning of a
       bootable FreeBSD slice.  These locations are not under the
       filesystem's control, so they are invisible to commands like
       <application>ls</application>.</para>
 
     <para>The main task for <literal>boot2</literal> is to load the
       file <filename>/boot/loader</filename>, which is the third stage
       in the bootstrapping procedure.  The code in
       <literal>boot2</literal> cannot use any services like
       <function>open()</function> and <function>read()</function>,
       since the kernel is not yet loaded.  It must scan the harddisk,
       knowing about the filesystem structure, find the file
       <filename>/boot/loader</filename>, read it into memory using a
       BIOS service, and then pass the execution to the loader's entry
       point.</para>
 
     <para>Besides that, <literal>boot2</literal> prompts for user
       input so the loader can be booted from different disk, unit,
       slice and partition.</para>
 
     <para>The <literal>boot2</literal> binary is created in special
       way:</para>
 
     <programlisting><filename>sys/boot/i386/boot2/Makefile</filename>
 boot2: boot2.ldr boot2.bin ${BTX}/btx/btx
 	btxld -v -E ${ORG2} -f bin -b ${BTX}/btx/btx -l boot2.ldr \
 		-o boot2.ld -P 1 boot2.bin</programlisting>
 
     <para>This Makefile snippet shows that &man.btxld.8; is used to
       link the binary.  BTX, which stands for BooT eXtender, is a
       piece of code that provides a protected mode environment for the
       program, called the client, that it is linked with.  So
       <literal>boot2</literal> is a BTX client, i.e. it uses the
       service provided by BTX.</para>
 
     <para>The <application>btxld</application> utility is the linker.
       It links two binaries together.  The difference between
       &man.btxld.8; and &man.ld.1; is that
       <application>ld</application> usually links object files into a
       shared object or executable, while
       <application>btxld</application> links an object file with the
       BTX, producing the binary file suitable to be put on the
       beginning of the partition for the system boot.</para>
 
     <para><literal>boot0</literal> passes the execution to BTX's entry
       point.  BTX then switches the processor to protected mode, and
       prepares a simple environment before calling the client.  This
       includes:</para>
 
     <itemizedlist>
       <listitem><para>virtual v86 mode.  That means, the BTX is a v86
         monitor.  Real mode instructions like posh, popf, cli, sti, if
         called by the client, will work.</para></listitem>
 
       <listitem><para>Interrupt Descriptor Table (IDT) is set up so
         all hardware interrupts are routed to the default BIOS's
         handlers, and interrupt 0x30 is set up to be the syscall
         gate.</para></listitem>
 
       <listitem><para>Two system calls: <function>exec</function> and
         <function>exit</function>, are defined:</para>
 
     <programlisting><filename>sys/boot/i386/btx/lib/btxsys.s:</filename>
 		.set INT_SYS,0x30		# Interrupt number
 #
 # System call: exit
 #
 __exit: 	xorl %eax,%eax			# BTX system
 		int $INT_SYS			#  call 0x0
 #
 # System call: exec
 #
 __exec: 	movl $0x1,%eax			# BTX system
 		int $INT_SYS			#  call 0x1</programlisting></listitem>
     </itemizedlist>
 
     <para>BTX creates a Global Descriptor Table (GDT):</para>
 
     <programlisting><filename>sys/boot/i386/btx/btx/btx.s:</filename>
 gdt:		.word 0x0,0x0,0x0,0x0		# Null entry
 		.word 0xffff,0x0,0x9a00,0xcf	# SEL_SCODE
 		.word 0xffff,0x0,0x9200,0xcf	# SEL_SDATA
 		.word 0xffff,0x0,0x9a00,0x0	# SEL_RCODE
 		.word 0xffff,0x0,0x9200,0x0	# SEL_RDATA
 		.word 0xffff,MEM_USR,0xfa00,0xcf# SEL_UCODE
 		.word 0xffff,MEM_USR,0xf200,0xcf# SEL_UDATA
 		.word _TSSLM,MEM_TSS,0x8900,0x0 # SEL_TSS</programlisting>
 
     <para>The client's code and data start from address MEM_USR
       (0xa000), and a selector (SEL_UCODE) points to the client's code
       segment.  The SEL_UCODE descriptor has Descriptor Privilege
       Level (DPL) 3, which is the lowest privilege level.  But the
       <literal>INT 0x30</literal> instruction handler resides in a
       segment pointed to by the SEL_SCODE (supervisor code) selector,
       as shown from the code that creates an IDT:</para>
 
   <programlisting>		mov $SEL_SCODE,%dh		# Segment selector
 init.2: 	shr %bx				# Handle this int?
 		jnc init.3			# No
 		mov %ax,(%di)			# Set handler offset
 		mov %dh,0x2(%di)		#  and selector
 		mov %dl,0x5(%di)		# Set P:DPL:type
 		add $0x4,%ax			# Next handler</programlisting>
 
     <para>So, when the client calls <function>__exec()</function>, the
       code will be executed with the highest privileges.  This allows
       the kernel to change the protected mode data structures, such as
       page tables, GDT, IDT, etc later, if needed.</para>
 
     <para><literal>boot2</literal> defines an important structure,
       <literal>struct bootinfo</literal>.  This structure is
       initialized by <literal>boot2</literal> and passed to the
       loader, and then further to the kernel.  Some nodes of this
       structures are set by <literal>boot2</literal>, the rest by the
       loader.  This structure, among other information, contains the
       kernel filename, BIOS harddisk geometry, BIOS drive number for
       boot device, physical memory available, <literal>envp</literal>
       pointer etc.  The definition for it is:</para>
 
     <programlisting><filename>/usr/include/machine/bootinfo.h</filename>
 struct bootinfo {
 	u_int32_t	bi_version;
 	u_int32_t	bi_kernelname;		/* represents a char * */
 	u_int32_t	bi_nfs_diskless;	/* struct nfs_diskless * */
 				/* End of fields that are always present. */
 #define	bi_endcommon	bi_n_bios_used
 	u_int32_t	bi_n_bios_used;
 	u_int32_t	bi_bios_geom[N_BIOS_GEOM];
 	u_int32_t	bi_size;
 	u_int8_t	bi_memsizes_valid;
 	u_int8_t	bi_bios_dev;		/* bootdev BIOS unit number */
 	u_int8_t	bi_pad[2];
 	u_int32_t	bi_basemem;
 	u_int32_t	bi_extmem;
 	u_int32_t	bi_symtab;		/* struct symtab * */
 	u_int32_t	bi_esymtab;		/* struct symtab * */
 				/* Items below only from advanced bootloader */
 	u_int32_t	bi_kernend;		/* end of kernel space */
 	u_int32_t	bi_envp;		/* environment */
 	u_int32_t	bi_modulep;		/* preloaded modules */
 };</programlisting>
 
   <para><literal>boot2</literal> enters into an infinite loop waiting
     for user input, then calls <function>load()</function>.  If the
     user does not press anything, the loop brakes by a timeout, so
     <function>load()</function> will load the default file
     (<filename>/boot/loader</filename>).  Functions <function>ino_t
     lookup(char *filename)</function> and <function>int xfsread(ino_t
     inode, void *buf, size_t nbyte)</function> are used to read the
     content of a file into memory.  <filename>/boot/loader</filename>
     is an ELF binary, but where the ELF header is prepended with
     a.out's <literal>struct exec</literal> structure.
     <function>load()</function> scans the loader's ELF header, loading
     the content of <filename>/boot/loader</filename> into memory, and
     passing the execution to the loader's entry:</para>
 
   <programlisting><filename>sys/boot/i386/boot2/boot2.c:</filename>
     __exec((caddr_t)addr, RB_BOOTINFO | (opts & RBX_MASK),
 	   MAKEBOOTDEV(dev_maj[dsk.type], 0, dsk.slice, dsk.unit, dsk.part),
 	   0, 0, 0, VTOP(&amp;bootinfo));</programlisting>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-loader">
     <title><application>loader</application> stage</title>
 
     <para><application>loader</application> is a BTX client as well.
       I will not describe it here in detail, there is a comprehensive
       manpage written by Mike Smith, &man.loader.8;.  The underlying
       mechanisms and BTX were discussed above.</para>
 
     <para>The main task for the loader is to boot the kernel.  When
       the kernel is loaded into memory, it is being called by the
       loader:</para>
 
   <programlisting><filename>sys/boot/common/boot.c:</filename>
     /* Call the exec handler from the loader matching the kernel */
     module_formats[km->m_loader]->l_exec(km);</programlisting>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-kernel">
     <title>Kernel initialization</title>
 
     <para>To where exactly is the execution passed by the loader,
       i.e. what is the kernel's actual entry point.  Let us take a
       look at the command that links the kernel:</para>
 
     <programlisting><filename>sys/conf/Makefile.i386:</filename>
 ld -elf -Bdynamic -T /usr/src/sys/conf/ldscript.i386  -export-dynamic \
 -dynamic-linker /red/herring -o kernel -X locore.o \
 &lt;lots of kernel .o files&gt;</programlisting>
 
     <para>A few interesting things can be seen in this line.  First,
       the kernel is an ELF dynamically linked binary, but the dynamic
       linker for kernel is <filename>/red/herring</filename>, which is
       definitely a bogus file.  Second, taking a look at the file
       <filename>sys/conf/ldscript.i386</filename> gives an idea about
       what <application>ld</application> options are used when
       compiling a kernel.  Reading through the first few lines, the
       string</para>
 
   <programlisting><filename>sys/conf/ldscript.i386:</filename>
 ENTRY(btext)</programlisting>
 
     <para>says that a kernel's entry point is the symbol `btext'.
       This symbol is defined in <filename>locore.s</filename>:</para>
 
   <programlisting><filename>sys/i386/i386/locore.s:</filename>
 	.text
 /**********************************************************************
  *
  * This is where the bootblocks start us, set the ball rolling...
  *
  */
 NON_GPROF_ENTRY(btext)</programlisting>
 
     <para>First what is done is the register EFLAGS is set to a
       predefined value of 0x00000002, and then all the segment
       registers are initialized:</para>
 
     <programlisting><filename>sys/i386/i386/locore.s</filename>
 /* Don't trust what the BIOS gives for eflags. */
 	pushl	$PSL_KERNEL
 	popfl
 
 /*
  * Don't trust what the BIOS gives for %fs and %gs.  Trust the bootstrap
  * to set %cs, %ds, %es and %ss.
  */
 	mov	%ds, %ax
 	mov	%ax, %fs
 	mov	%ax, %gs</programlisting>
 
     <para>btext calls the routines
       <function>recover_bootinfo()</function>,
       <function>identify_cpu()</function>,
       <function>create_pagetables()</function>, which are also defined
       in <filename>locore.s</filename>.  Here is a description of what
       they do:</para>
 
     <informaltable>
       <tgroup cols=2 align=left>
       <tbody>
         <row>
           <entry><function>recover_bootinfo</function></entry>
 
           <entry>This routine parses the parameters to the kernel
             passed from the bootstrap.  The kernel may have been
             booted in 3 ways: by the loader, described above, by the
             old disk boot blocks, and by the old diskless boot
             procedure.  This function determines the booting method,
             and stores the <literal>struct bootinfo</literal>
             structure into the kernel memory.</entry>
         </row>
 
         <row>
           <entry><function>identify_cpu</function></entry>
 
 	  <entry>This functions tries to find out what CPU it is
 	    running on, storing the value found in a variable
 	    <varname>_cpu</varname>.</entry>
         </row>
 
         <row>
           <entry><function>create_pagetables</function></entry>
 
 	  <entry>This function allocates and fills out a Page Table
 	    Directory at the top of the kernel memory area.</entry>
         </row>
       </tgroup>
     </informaltable>
 
     <para>The next steps are enabling VME, if the CPU supports
       it:</para>
 
     <programlisting>	testl	$CPUID_VME, R(_cpu_feature)
 	jz	1f
 	movl	%cr4, %eax
 	orl	$CR4_VME, %eax
 	movl	%eax, %cr4</programlisting>
 
     <para>Then, enabling paging:</para>
     <programlisting>/* Now enable paging */
 	movl	R(_IdlePTD), %eax
 	movl	%eax,%cr3			/* load ptd addr into mmu */
 	movl	%cr0,%eax			/* get control word */
 	orl	$CR0_PE|CR0_PG,%eax		/* enable paging */
 	movl	%eax,%cr0			/* and let's page NOW! */</programlisting>
 
     <para>The next three lines of code are because the paging was set,
       so the jump is needed to continue the execution in virtualized
       address space:</para>
 
     <programlisting>	pushl	$begin				/* jump to high virtualized address */
 	ret
 
 /* now running relocated at KERNBASE where the system is linked to run */
 begin:</programlisting>
 
     <para>The function <function>init386()</function> is called, with
       a pointer to the first free physical page, after that
       <function>mi_startup()</function>.  <function>init386</function>
       is an architecture dependent initialization function, and
       <function>mi_startup()</function> is an architecture independent
       one (the 'mi_' prefix stands for Machine Independent).  The
       kernel never returns from <function>mi_startup()</function>, and
       by calling it, the kernel finishes booting:</para>
 
     <programlisting><filename>sys/i386/i386/locore.s:</filename>
 	movl	physfree, %esi
 	pushl	%esi				/* value of first for init386(first) */
 	call	_init386			/* wire 386 chip for unix operation */
 	call	_mi_startup			/* autoconfiguration, mountroot etc */
 	hlt		/* never returns to here */</programlisting>
 
     <sect2>
       <title><function>init386()</function></title>
 
       <para><function>init386()</function> is defined in
         <filename>sys/i386/i386/machdep.c</filename> and performs
         low-level initialization, specific to the i386 chip.  The
         switch to protected mode was performed by the loader.  The
         loader has created the very first task, in which the kernel
         continues to operate.  Before running straight away to the
         code, I will enumerate the tasks the processor must complete
         to initialize protected mode execution:</para>
 
       <itemizedlist>
         <listitem>
 	  <para>Initialize the kernel tunable parameters, passed from
 	    the bootstrapping program.</para>
 	  </listitem>
 
         <listitem>
 	  <para>Prepare the GDT.</para>
 	</listitem>
 
         <listitem>
 	  <para>Prepare the IDT.</para>
 	</listitem>
 
         <listitem>
 	  <para>Initialize the system console.</para>
 	</listitem>
 
         <listitem>
 	  <para>Initialize the DDB, if it is compiled into
 	    kernel.</para>
 	</listitem>
 
         <listitem>
 	  <para>Initialize the TSS.</para>
 	</listitem>
 
         <listitem>
 	  <para>Prepare the LDT.</para>
 	</listitem>
 
         <listitem>
 	  <para>Setup proc0's pcb.</para>
 	</listitem>
       </itemizedlist>
 
       <para>What <function>init386()</function> first does is
         initialize the tunable parameters passed from bootstrap.  This
         is done by setting the environment pointer (envp) and calling
         <function>init_param1()</function>.  The envp pointer has been
         passed from loader in the <literal>bootinfo</literal>
         structure:</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
 		kern_envp = (caddr_t)bootinfo.bi_envp + KERNBASE;
 
 	/* Init basic tunables, hz etc */
 	init_param1();</programlisting>
 
       <para><function>init_param1()</function> is defined in
         <filename>sys/kern/subr_param.c</filename>.  That file has a
         number of sysctls, and two functions,
         <function>init_param1()</function> and
         <function>init_param2()</function>, that are called from
         <function>init386()</function>:</para>
 
       <programlisting><filename>sys/kern/subr_param.c</filename>
 	hz = HZ;
 	TUNABLE_INT_FETCH("kern.hz", &amp;hz);</programlisting>
 
       <para>TUNABLE_&lt;typename&gt;_FETCH is used to fetch the value
         from the environment:</para>
 
     <programlisting><filename>/usr/src/sys/sys/kernel.h</filename>
 #define	TUNABLE_INT_FETCH(path, var)	getenv_int((path), (var))
 </programlisting>
 
       <para>Sysctl <literal>kern.hz</literal> is the system clock tick.  Along with
         this, the following sysctls are set by
         <function>init_param1()</function>: <literal>kern.maxswzone,
         kern.maxbcache, kern.maxtsiz, kern.dfldsiz, kern.dflssiz,
         kern.maxssiz, kern.sgrowsiz</literal>.</para>
 
       <para>Then <function>init386()</function> prepares the Global
         Descriptors Table (GDT).  Every task on an x86 is running in
         its own virtual address space, and this space is addressed by
         a segment:offset pair.  Say, for instance, the current
         instruction to be executed by the processor lies at CS:EIP,
         then the linear virtual address for that instruction would be
         <quote>the virtual address of code segment CS</quote> + EIP.  For
         convenience, segments begin at virtual address 0 and end at a
         4Gb boundary.  Therefore, the instruction's linear virtual
         address for this example would just be the value of EIP.
         Segment registers such as CS, DS etc are the selectors,
         i.e. indexes, into GDT (to be more precise, an index is not a
         selector itself, but the INDEX field of a selector).
         FreeBSD's GDT holds descriptors for 15 selectors per
         CPU:</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
 union descriptor gdt[NGDT * MAXCPU];	/* global descriptor table */
 
 <filename>sys/i386/include/segments.h:</filename>
 /*
  * Entries in the Global Descriptor Table (GDT)
  */
 #define	GNULL_SEL	0	/* Null Descriptor */
 #define	GCODE_SEL	1	/* Kernel Code Descriptor */
 #define	GDATA_SEL	2	/* Kernel Data Descriptor */
 #define	GPRIV_SEL	3	/* SMP Per-Processor Private Data */
 #define	GPROC0_SEL	4	/* Task state process slot zero and up */
 #define	GLDT_SEL	5	/* LDT - eventually one per process */
 #define	GUSERLDT_SEL	6	/* User LDT */
 #define	GTGATE_SEL	7	/* Process task switch gate */
 #define	GBIOSLOWMEM_SEL	8	/* BIOS low memory access (must be entry 8) */
 #define	GPANIC_SEL	9	/* Task state to consider panic from */
 #define GBIOSCODE32_SEL	10	/* BIOS interface (32bit Code) */
 #define GBIOSCODE16_SEL	11	/* BIOS interface (16bit Code) */
 #define GBIOSDATA_SEL	12	/* BIOS interface (Data) */
 #define GBIOSUTIL_SEL	13	/* BIOS interface (Utility) */
 #define GBIOSARGS_SEL	14	/* BIOS interface (Arguments) */</programlisting>
 
       <para>Note that those #defines are not selectors themselves, but
         just a field INDEX of a selector, so they are exactly the
         indices of the GDT.  for example, an actual selector for the
         kernel code (GCODE_SEL) has the value 0x08.</para>
 
       <para>The next step is to initialize the Interrupt Descriptor
         Table (IDT).  This table is to be referenced by the processor
         when a software or hardware interrupt occurs.  For example, to
         make a system call, user application issues the <literal>INT
         0x80</literal> instruction.  This is a software interrupt, so
         the processor's hardware looks up a record with index 0x80 in
         the IDT.  This record points to the routine that handles this
         interrupt, in this particular case, this will be the kernel's
         syscall gate.  The IDT may have a maximum of 256 (0x100)
         records.  The kernel allocates NIDT records for the IDT, where
         NIDT is the maximum (256):</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
 static struct gate_descriptor idt0[NIDT];
 struct gate_descriptor *idt = &amp;idt0[0];	/* interrupt descriptor table */
 </programlisting>
 
       <para>For each interrupt, an appropriate handler is set.  The
         syscall gate for <literal>INT 0x80</literal> is set as
         well:</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
  	setidt(0x80, &amp;IDTVEC(int0x80_syscall),
 			SDT_SYS386TGT, SEL_UPL, GSEL(GCODE_SEL, SEL_KPL));</programlisting>
 
       <para>So when a userland application issues the <literal>INT
         0x80</literal> instruction, control will transfer to the
         function <function>_Xint0x80_syscall</function>, which is in
         the kernel code segment and will be executed with supervisor
         privileges.</para>
 
       <para>Console and DDB are then initialized:</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
 	cninit();
 /* skipped */
 #ifdef DDB
 	kdb_init();
 	if (boothowto & RB_KDB)
 		Debugger("Boot flags requested debugger");
 #endif</programlisting>
 
       <para>The Task State Segment is another x86 protected mode
         structure, the TSS is used by the hardware to store task
         information when a task switch occurs.</para>
 
       <para>The Local Descriptors Table is used to reference userland
         code and data.  Several selectors are defined to point to the
         LDT, they are the system call gates and the user code and data
         selectors:</para>
 
       <programlisting><filename>/usr/include/machine/segments.h</filename>
 #define	LSYS5CALLS_SEL	0	/* forced by intel BCS */
 #define	LSYS5SIGR_SEL	1
 #define	L43BSDCALLS_SEL	2	/* notyet */
 #define	LUCODE_SEL	3
 #define LSOL26CALLS_SEL	4	/* Solaris >= 2.6 system call gate */
 #define	LUDATA_SEL	5
 /* separate stack, es,fs,gs sels ? */
 /* #define	LPOSIXCALLS_SEL	5*/	/* notyet */
 #define LBSDICALLS_SEL	16	/* BSDI system call gate */
 #define NLDT		(LBSDICALLS_SEL + 1)
 </programlisting>
 
     <para>Next, proc0's Process Control Block (<literal>struct
       pcb</literal>) structure is initialized.  proc0 is a
       <literal>struct proc</literal> structure that describes a kernel
       process.  It is always present while the kernel is running,
       therefore it is declared as global:</para>
 
     <programlisting><filename>sys/kern/kern_init.c:</filename>
     struct	proc proc0;</programlisting>
 
     <para>The structure <literal>struct pcb</literal> is a part of a
       proc structure.  It is defined in
       <filename>/usr/include/machine/pcb.h</filename> and has a
       process's information specific to the i386 architecture, such as
       registers values.</para>
     </sect2>
 
     <sect2>
       <title><function>mi_startup()</function></title>
 
       <para>This function performs a bubble sort of all the system
         initialization objects and then calls the entry of each object
         one by one:</para>
 
       <programlisting><filename>sys/kern/init_main.c:</filename>
 	for (sipp = sysinit; *sipp; sipp++) {
 
 		/* ... skipped ... */
 
 		/* Call function */
 		(*((*sipp)->func))((*sipp)->udata);
 		/* ... skipped ... */
 	}</programlisting>
 
     <para>Although the sysinit framework is described in the
       Developers' Handbook, I will discuss the internals of it.</para>
 
     <para>Every system initialization object (sysinit object) is
       created by calling a SYSINIT() macro.  Let us take as example an
       <literal>announce</literal> sysinit object.  This object prints
       the copyright message:</para>
 
     <programlisting><filename>sys/kern/init_main.c:</filename>
 static void
 print_caddr_t(void *data __unused)
 {
 	printf("%s", (char *)data);
 }
 SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t, copyright)</programlisting>
 
     <para>The subsystem ID for this object is SI_SUB_COPYRIGHT
       (0x0800001), which comes right after the SI_SUB_CONSOLE
       (0x0800000).  So, the copyright message will be printed out
       first, just after the console initialization.</para>
 
     <para>Let us take a look at what exactly the macro
       <literal>SYSINIT()</literal> does.  It expands to a
       <literal>C_SYSINIT()</literal> macro.  The
       <literal>C_SYSINIT()</literal> macro then expands to a static
       <literal>struct sysinit</literal> structure declaration with
       another <literal>DATA_SET</literal> macro call:</para>
       <programlisting><filename>/usr/include/sys/kernel.h:</filename>
       #define C_SYSINIT(uniquifier, subsystem, order, func, ident) \
       static struct sysinit uniquifier ## _sys_init = { \ subsystem, \
       order, \ func, \ ident \ }; \ DATA_SET(sysinit_set,uniquifier ##
       _sys_init);
 
 #define	SYSINIT(uniquifier, subsystem, order, func, ident)	\
 	C_SYSINIT(uniquifier, subsystem, order,			\
 	(sysinit_cfunc_t)(sysinit_nfunc_t)func, (void *)ident)</programlisting>
 
     <para>The <literal>DATA_SET()</literal> macro expands to a
       <literal>MAKE_SET()</literal>, and that macro is the point where
       the all sysinit magic is hidden:</para>
 
     <programlisting><filename>/usr/include/linker_set.h</filename>
 #define MAKE_SET(set, sym)						\
 	static void const * const __set_##set##_sym_##sym = &amp;sym;	\
 	__asm(".section .set." #set ",\"aw\"");				\
 	__asm(".long " #sym);						\
 	__asm(".previous")
 #endif
 #define TEXT_SET(set, sym) MAKE_SET(set, sym)
 #define DATA_SET(set, sym) MAKE_SET(set, sym)</programlisting>
 
     <para>In our case, the following declaration will occur:</para>
 
     <programlisting>static struct sysinit announce_sys_init = {
 	SI_SUB_COPYRIGHT,
 	SI_ORDER_FIRST,
 	(sysinit_cfunc_t)(sysinit_nfunc_t)  print_caddr_t,
 	(void *) copyright
 };
 
 static void const *const __set_sysinit_set_sym_announce_sys_init =
     &amp;announce_sys_init;
 __asm(".section .set.sysinit_set" ",\"aw\"");
 __asm(".long " "announce_sys_init");
 __asm(".previous");</programlisting>
 
     <para>The first <literal>__asm</literal> instruction will create
       an ELF section within the kernel's executable.  This will happen
       at kernel link time.  The section will have the name
       <literal>.set.sysinit_set</literal>.  The content of this section is one 32-bit
       value, the address of announce_sys_init structure, and that is
       what the second <literal>__asm</literal> is.  The third
       <literal>__asm</literal> instruction marks the end of a section.
       If a directive with the same section name occured before, the
       content, i.e. the 32-bit value, will be appended to the existing
       section, so forming an array of 32-bit pointers.</para>
 
     <para>Running <application>objdump</application> on a kernel
       binary, you may notice the presence of such small
       sections:</para>
 
     <screen>&prompt.user; <userinput>objdump -h /kernel</userinput>
   7 .set.cons_set 00000014  c03164c0  c03164c0  002154c0  2**2
                   CONTENTS, ALLOC, LOAD, DATA
   8 .set.kbddriver_set 00000010  c03164d4  c03164d4  002154d4  2**2
                   CONTENTS, ALLOC, LOAD, DATA
   9 .set.scrndr_set 00000024  c03164e4  c03164e4  002154e4  2**2
                   CONTENTS, ALLOC, LOAD, DATA
  10 .set.scterm_set 0000000c  c0316508  c0316508  00215508  2**2
                   CONTENTS, ALLOC, LOAD, DATA
  11 .set.sysctl_set 0000097c  c0316514  c0316514  00215514  2**2
                   CONTENTS, ALLOC, LOAD, DATA
  12 .set.sysinit_set 00000664  c0316e90  c0316e90  00215e90  2**2
                   CONTENTS, ALLOC, LOAD, DATA</screen>
 
     <para>This screen dump shows that the size of .set.sysinit_set
       section is 0x664 bytes, so <literal>0x664/sizeof(void
       *)</literal> sysinit objects are compiled into the kernel.  The
       other sections such as <literal>.set.sysctl_set</literal>
       represent other linker sets.</para>
 
     <para>By defining a variable of type <literal>struct
       linker_set</literal> the content of
       <literal>.set.sysinit_set</literal> section will be <quote>collected</quote>
       into that variable:</para>
       <programlisting><filename>sys/kern/init_main.c:</filename>
       extern struct linker_set sysinit_set; /* XXX */</programlisting>
 
     <para>The <literal>struct linker_set</literal> is defined as
       follows:</para>
 
     <programlisting><filename>/usr/include/linker_set.h:</filename>
   struct linker_set {
 	int	ls_length;
 	void	*ls_items[1];		/* really ls_length of them, trailing NULL */
 };</programlisting>
 
     <para>The first node will be equal to the number of a sysinit
       objects, and the second node will be a NULL-terminated array of
       pointers to them.</para>
 
     <para>Returning to the <function>mi_startup()</function>
       discussion, it is must be clear now, how the sysinit objects are
       being organized.  The <function>mi_startup()</function> function
       sorts them and calls each.  The very last object is the system
       scheduler:</para>
 
     <programlisting><filename>/usr/include/sys/kernel.h:</filename>
 enum sysinit_sub_id {
 	SI_SUB_DUMMY		= 0x0000000,	/* not executed; for linker*/
 	SI_SUB_DONE		= 0x0000001,	/* processed*/
 	SI_SUB_CONSOLE		= 0x0800000,	/* console*/
 	SI_SUB_COPYRIGHT	= 0x0800001,	/* first use of console*/
 ...
 	SI_SUB_RUN_SCHEDULER	= 0xfffffff	/* scheduler: no return*/
 };</programlisting>
 
     <para>The system scheduler sysinit object is defined in the file
       <filename>sys/vm/vm_glue.c</filename>, and the entry point for
       that object is <function>scheduler()</function>.  That function
       is actually an infinite loop, and it represents a process with
       PID 0, the swapper process.  The proc0 structure, mentioned
       before, is used to describe it.</para>
 
     <para>The first user process, called <emphasis>init</emphasis>, is
       created by the sysinit object <literal>init</literal>:</para>
 
     <programlisting><filename>sys/kern/init_main.c:</filename>
 static void
 create_init(const void *udata __unused)
 {
 	int error;
 	int s;
 
 	s = splhigh();
 	error = fork1(&amp;proc0, RFFDG | RFPROC, &amp;initproc);
 	if (error)
 		panic("cannot fork init: %d\n", error);
 	initproc->p_flag |= P_INMEM | P_SYSTEM;
 	cpu_set_fork_handler(initproc, start_init, NULL);
 	remrunqueue(initproc);
 	splx(s);
 }
 SYSINIT(init,SI_SUB_CREATE_INIT, SI_ORDER_FIRST, create_init, NULL)</programlisting>
 
   <para>The <function>create_init()</function> allocates a new process
     by calling <function>fork1()</function>, but does not mark it
     runnable.  When this new process is scheduled for execution by the
     scheduler, the <function>start_init()</function> will be called.
     That function is defined in <filename>init_main.c</filename>.  It
     tries to load and exec the <filename>init</filename> binary,
     probing <filename>/sbin/init</filename> first, then
     <filename>/sbin/oinit</filename>,
     <filename>/sbin/init.bak</filename>, and finally
     <filename>/stand/sysinstall</filename>:</para>
 
   <programlisting><filename>sys/kern/init_main.c:</filename>
 static char init_path[MAXPATHLEN] =
 #ifdef	INIT_PATH
     __XSTRING(INIT_PATH);
 #else
     "/sbin/init:/sbin/oinit:/sbin/init.bak:/stand/sysinstall";
 #endif</programlisting>
 
   </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/arch-handbook/driverbasics/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.sgml
index e47a3772fd..61a425b8bd 100644
--- a/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.sgml
@@ -1,392 +1,392 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="driverbasics">
   <title>Writing FreeBSD Device Drivers</title>
 
   <para>This chapter was written by &a.murray; with selections from a
     variety of sources including the intro(4) manual page by
     &a.joerg;.</para>
 
-  <sect1>
+  <sect1 id="driverbasics-intro">
     <title>Introduction</title>
     <para>This chapter provides a brief introduction to writing device
       drivers for FreeBSD.  A device in this context is a term used
       mostly for hardware-related stuff that belongs to the system,
       like disks, printers, or a graphics display with its keyboard.
       A device driver is the software component of the operating
       system that controls a specific device.  There are also
       so-called pseudo-devices where a device driver emulates the
       behavior of a device in software without any particular
       underlying hardware.  Device drivers can be compiled into the
       system statically or loaded on demand through the dynamic kernel
       linker facility `kld'.</para>
 
     <para>Most devices in a Unix-like operating system are accessed
       through device-nodes, sometimes also called special files.
       These files are usually located under the directory
       <filename>/dev</filename> in the filesystem hierarchy.
       In releases of FreeBSD older than 5.0-RELEASE, where
       &man.devfs.5; support is not integrated into FreeBSD,
       each device node must be
       created statically and independent of the existence of the
       associated device driver.  Most device nodes on the system are
       created by running <command>MAKEDEV</command>.</para>
 
     <para>Device drivers can roughly be broken down into two 
       categories; character and network device drivers.</para>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="driverbasics-kld">
     <title>Dynamic Kernel Linker Facility - KLD</title> 
 
     <para>The kld interface allows system administrators to
       dynamically add and remove functionality from a running system.
       This allows device driver writers to load their new changes into
       a running kernel without constantly rebooting to test
       changes.</para>
 
     <para>The kld interface is used through the following
       privileged commands:
 
     <itemizedlist>
       <listitem><simpara><command>kldload</command> - loads a new kernel
 	module</simpara></listitem>
       <listitem><simpara><command>kldunload</command> - unloads a kernel
 	module</simpara></listitem>
       <listitem><simpara><command>kldstat</command> - lists the currently loaded
 	modules</simpara></listitem>
     </itemizedlist>
     </para>
 
     <para>Skeleton Layout of a kernel module</para>
 
 <programlisting>/*
  * KLD Skeleton
  * Inspired by Andrew Reiter's Daemonnews article
  */
 
 #include &lt;sys/types.h&gt;
 #include &lt;sys/module.h&gt;
 #include &lt;sys/systm.h&gt;  /* uprintf */ 
 #include &lt;sys/errno.h&gt;
 #include &lt;sys/param.h&gt;  /* defines used in kernel.h */
 #include &lt;sys/kernel.h&gt; /* types used in module initialization */
 
 /* 
  * Load handler that deals with the loading and unloading of a KLD.
  */
 
 static int
 skel_loader(struct module *m, int what, void *arg)
 {
   int err = 0;
   
   switch (what) {
   case MOD_LOAD:                /* kldload */
     uprintf("Skeleton KLD loaded.\n");
     break;
   case MOD_UNLOAD:
     uprintf("Skeleton KLD unloaded.\n");
     break;
   default:
     err = EINVAL;
     break;
   }
   return(err);
 }
 
 /* Declare this module to the rest of the kernel */
 
 static moduledata_t skel_mod = {
   "skel",
   skel_loader,
   NULL
 };  
 
 DECLARE_MODULE(skeleton, skel_mod, SI_SUB_KLD, SI_ORDER_ANY);</programlisting>
 
 
     <sect2>
       <title>Makefile</title>
 
       <para>FreeBSD provides a makefile include that you can use to
 	quickly compile your kernel addition.</para>
 
       <programlisting>SRCS=skeleton.c
 KMOD=skeleton
 
 .include &lt;bsd.kmod.mk&gt;</programlisting>
 
       <para>Simply running <command>make</command> with this makefile
         will create a file <filename>skeleton.ko</filename> that can
         be loaded into your system by typing:
 <screen>&prompt.root; <userinput>kldload -v ./skeleton.ko</userinput></screen>
       </para>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="driverbasics-access">
     <title>Accessing a device driver</title>
 
     <para>Unix provides a common set of system calls for user
       applications to use.  The upper layers of the kernel dispatch
       these calls to the corresponding device driver when a user
       accesses a device node.  The <command>/dev/MAKEDEV</command>
       script makes most of the device nodes for your system but if you
       are doing your own driver development it may be necessary to
       create your own device nodes with <command>mknod</command>.
     </para>
 
     <sect2>
       <title>Creating static device nodes</title>
 
       <para>The <command>mknod</command> command requires four
 	arguments to create a device node.  You must specify the name
 	of the device node, the type of device, the major number of
 	the device, and the minor number of the device.</para>
     </sect2>
 
     <sect2>
       <title>Dynamic device nodes</title>
 
       <para>The device filesystem, or devfs, provides access to the
 	kernel's device namespace in the global filesystem namespace.
 	This eliminates the problems of potentially having a device
 	driver without a static device node, or a device node without
 	an installed device driver.  Devfs is still a work in
 	progress, but it is already working quite nicely.</para>
     </sect2>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="driverbasics-char">
     <title>Character Devices</title>
 
     <para>A character device driver is one that transfers data
       directly to and from a user process.  This is the most common
       type of device driver and there are plenty of simple examples in
       the source tree.</para>
 
     <para>This simple example pseudo-device remembers whatever values
       you write to it and can then supply them back to you when you
       read from it.</para>
 
     <programlisting>/*
  * Simple `echo' pseudo-device KLD
  *
  * Murray Stokely
  */
 
 #define MIN(a,b) (((a) < (b)) ? (a) : (b))
 
 #include &lt;sys/types.h&gt;
 #include &lt;sys/module.h&gt;
 #include &lt;sys/systm.h&gt; /* uprintf */ 
 #include &lt;sys/errno.h&gt;
 #include &lt;sys/param.h&gt;  /* defines used in kernel.h */
 #include &lt;sys/kernel.h&gt; /* types used in module initialization */
 #include &lt;sys/conf.h&gt;   /* cdevsw struct */
 #include &lt;sys/uio.h&gt;    /* uio struct */
 #include &lt;sys/malloc.h&gt;
 
 #define BUFFERSIZE 256
 
 /* Function prototypes */
 d_open_t      echo_open;
 d_close_t     echo_close;
 d_read_t      echo_read;
 d_write_t     echo_write;
 
 /* Character device entry points */
 static struct cdevsw echo_cdevsw = {
   echo_open,
   echo_close,
   echo_read,
   echo_write,
   noioctl,
   nopoll,
   nommap,
   nostrategy,
   "echo",
   33,                   /* reserved for lkms - /usr/src/sys/conf/majors */
   nodump,
   nopsize,
   D_TTY,
   -1
 };
 
 typedef struct s_echo {
   char msg[BUFFERSIZE];
   int len;
 } t_echo;
 
 /* vars */
 static dev_t sdev;
 static int len;
 static int count;
 static t_echo *echomsg;
 
 MALLOC_DECLARE(M_ECHOBUF);
 MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module");
 
 /*
  * This function acts is called by the kld[un]load(2) system calls to
  * determine what actions to take when a module is loaded or unloaded.
  */
       
 static int
 echo_loader(struct module *m, int what, void *arg)
 {
   int err = 0;
   
   switch (what) {
   case MOD_LOAD:                /* kldload */
     sdev = make_dev(<literal>&</literal>echo_cdevsw,
 		    0,
 		    UID_ROOT,
 		    GID_WHEEL,
 		    0600,
 		    "echo");
     /* kmalloc memory for use by this driver */
     /*    malloc(256,M_ECHOBUF,M_WAITOK); */
     MALLOC(echomsg, t_echo *, sizeof(t_echo), M_ECHOBUF, M_WAITOK);
     printf("Echo device loaded.\n");
     break;
   case MOD_UNLOAD:
     destroy_dev(sdev);
     FREE(echomsg,M_ECHOBUF);
     printf("Echo device unloaded.\n");
     break;
   default:
     err = EINVAL;
     break;
   }
   return(err);
 }
 
 int 
 echo_open(dev_t dev, int oflags, int devtype, struct proc *p)
 {
   int err = 0;
   
   uprintf("Opened device \"echo\" successfully.\n");
   return(err);
 }
 
 int 
 echo_close(dev_t dev, int fflag, int devtype, struct proc *p)
 {
   uprintf("Closing device \"echo.\"\n"); 
   return(0);
 } 
 
 /* 
  * The read function just takes the buf that was saved via
  * echo_write() and returns it to userland for accessing.
  * uio(9) 
  */
 
 int
 echo_read(dev_t dev, struct uio *uio, int ioflag)
 {
   int err = 0;
   int amt;
 
   /* How big is this read operation?  Either as big as the user wants,
      or as big as the remaining data */
   amt = MIN(uio->uio_resid, (echomsg->len - uio->uio_offset > 0) ? echomsg->len - uio->uio_offset : 0);
   if ((err = uiomove(echomsg->msg + uio->uio_offset,amt,uio)) != 0) {
     uprintf("uiomove failed!\n");
   }
 
   return err;
 }
 
 /*
  * echo_write takes in a character string and saves it
  * to buf for later accessing.
  */
 
 int
 echo_write(dev_t dev, struct uio *uio, int ioflag)
 {
   int err = 0;
 
   /* Copy the string in from user memory to kernel memory */
   err = copyin(uio->uio_iov->iov_base, echomsg->msg, MIN(uio->uio_iov->iov_len,BUFFERSIZE));
 
   /* Now we need to null terminate */
   *(echomsg->msg + MIN(uio->uio_iov->iov_len,BUFFERSIZE)) = 0;
   /* Record the length */
   echomsg->len = MIN(uio->uio_iov->iov_len,BUFFERSIZE);
 
   if (err != 0) {
     uprintf("Write failed: bad address!\n");
   }
 
   count++;
   return(err);
 }
 
 DEV_MODULE(echo,echo_loader,NULL);</programlisting>
 
     <para>To install this driver you will first need to make a node on
       your filesystem with a command such as:</para>
 
     <screen>&prompt.root; <userinput>mknod /dev/echo c 33 0</userinput></screen>
 
     <para>With this driver loaded you should now be able to type
       something like:</para>
 
     <screen>&prompt.root; <userinput>echo -n "Test Data" &gt; /dev/echo</userinput>
 &prompt.root; <userinput>cat /dev/echo</userinput>
 Test Data</screen>
 
     <para>Real hardware devices in the next chapter..</para>
 
     <para>Additional Resources
     <itemizedlist>
       <listitem><simpara><ulink
 	url="http://www.daemonnews.org/200010/blueprints.html">Dynamic
 	Kernel Linker (KLD) Facility Programming Tutorial</ulink> -
 	<ulink url="http://www.daemonnews.org/">Daemonnews</ulink> October 2000</simpara></listitem>
       <listitem><simpara><ulink
 	url="http://www.daemonnews.org/200007/newbus-intro.html">How
 	to Write Kernel Drivers with NEWBUS</ulink> - <ulink
 	url="http://www.daemonnews.org/">Daemonnews</ulink> July
 	2000</simpara></listitem>
     </itemizedlist>
     </para>
   </sect1>
 
-  <sect1>
+  <sect1 id="driverbasics-net">
     <title>Network Drivers</title>
 
     <para>Drivers for network devices do not use device nodes in order
       to be accessed.  Their selection is based on other decisions
       made inside the kernel and instead of calling open(), use of a
       network device is generally introduced by using the system call
       socket(2).</para> 
 
     <para>man ifnet(), loopback device, Bill Paul's drivers,
       etc..</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/arch-handbook/isa/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml
index 1f51a1a70c..3c4b99338b 100644
--- a/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.sgml
@@ -1,2483 +1,2483 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <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>
+  <sect1 id="isa-driver-synopsis">
     <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
       <literal>ep</literal> and <literal>aha</literal> are good sources of information.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="isa-driver-basics">
     <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 <quote>xxx</quote>
       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>
+    <sect1 id="isa-driver-device-t">
       <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 <literal>"xxx"</literal> 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 <quote>xxx0</quote>, <quote>xxx1</quote> 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
         <filename>kern/bus_subr.c</filename>.</para>
 
     </sect1>
 
-    <sect1>
+    <sect1 id="isa-driver-config">
       <title>Configuration file and the order of identifying and probing
 	during auto-configuration</title>
 
       <para>The ISA devices are described in the kernel configuration 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's needs and abilities for
 	auto-configuration. For example, some devices do not 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 <literal>isa0</literal> or <literal>isa1</literal>, otherwise the device would be
 	searched for on all the ISA buses.</para>
 
       <para><literal>sensitive</literal> 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 is 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
         <literal>sensitive</literal> 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; in this case, 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 is the responsibility of the driver to make sure
         that the same device will not 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 <filename>kern/subr_bus.c</filename>. The old IDE disk driver
         <filename>i386/isa/wd.c</filename> 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>
+    <sect1 id="isa-driver-resources">
       <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. However, generally this is neither needed nor recommended,
         so this issue is not discussed further here.</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 it 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 <literal>unsigned long</literal> and must be
         cast as necessary. The resource numbers do not 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
         normally be 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 by 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, this function will
             return an error only if one of <literal>type</literal>,
             <literal>rid</literal>, <literal>start</literal> or
             <literal>count</literal> has a value that falls out of the
             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 to 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 is 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 is 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 SEPARATE 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 <function>void
             driver_intr_t(void *)</function></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 are 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>
+    <sect1 id="isa-driver-busmem">
       <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 the computer</para>
 
       <para>In 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 is
         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
         configuration of a memory hole of 1MB starting at 14MB or
         15MB. FreeBSD can handle the memory holes properly if the BIOS
         reports them properly (this feature may be broken on old BIOSes).</para>
 
       <para>In 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, and 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 is
         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 is
         left at its original location. If it is not then a fresh
         conformant <quote>bounce page</quote> 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 a 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 <quote>no specific
               alignment</quote>. Applies only to the future
               <function>bus_dmamem_alloc()</function> but not
               <function>bus_dmamap_create()</function> calls.</para>
 	  </listitem>
 
 	  <listitem>
               <para><emphasis>boundary</emphasis> - physical address
               boundary that must not be crossed when allocating the
               memory. Use value 0 for <quote>no boundary</quote>. 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 slightly 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 is 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 (the hardware
 	      can not normally support that many
               scatter-gather buffers anyway).</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 being 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 until the memory
                       becomes 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>. At present, 
               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 at present
                   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 is 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 is
           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 is 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 is 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 its processing and
           check this synchronization flag. If it is 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>
+     <sect1 id="isa-driver-dma">
         <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 is
           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 (in addition 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 not 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 is 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 something
             probably 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>
+     <sect1 id="isa-driver-probe">
      <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 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 not 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 and a
           well-behaved driver should do so. But in cases where 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 do not
           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 do not 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
           <literal>sensitive</literal> flag: the sensitive devices get probed first and
           the rest of the 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 <quote>use those we set by
           <function>bus_set_resource()</function></quote>):
         </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 do not 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 is 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 is 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 function <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 are 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 is 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>
+     <sect1 id="isa-driver-attach">
      <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 the 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>
+     <sect1 id="isa-driver-detach">
        <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 a reboot will be
           needed anyway, so the efforts spent on writing the detach
           routine may not be worth it. Another argument 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 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>
+     <sect1 id="isa-driver-shutdown">
        <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 do not consider it here
           in any detail.
         </para>
      </sect1>
 
-     <sect1>
+     <sect1 id="isa-driver-intr">
           <title>xxx_intr</title>
 
         <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 in 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. This 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/jail/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/jail/chapter.sgml
index 7de06d5182..53af59a441 100644
--- a/en_US.ISO8859-1/books/arch-handbook/jail/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/jail/chapter.sgml
@@ -1,611 +1,611 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="jail">
   <chapterinfo>
     <author><firstname>Evan Sarmiento</firstname>
     <affiliation><address><email>evms@cs.bu.edu</email></address>
     </affiliation>
     </author>
     <copyright>
       <year>2001</year>
       <holder role="mailto:evms@cs.bu.edu">Evan Sarmiento</holder>
     </copyright>
   </chapterinfo>
   <title>The Jail Subsystem</title>
 
   <para>On most UNIX systems, root has omnipotent power. This promotes
     insecurity. If an attacker were to gain root on a system, he would
     have every function at his fingertips. In FreeBSD there are
     sysctls which dilute the power of root, in order to minimize the
     damage caused by an attacker. Specifically, one of these functions
     is called secure levels. Similarly, another function which is
     present from FreeBSD 4.0 and onward, is a utility called
     &man.jail.8;. <application>Jail</application> chroots an
     environment and sets certain restrictions on processes which are
     forked from within. For example, a jailed process cannot affect
     processes outside of the jail, utilize certain system calls, or
     inflict any damage on the main computer.</para>
 
   <para><application>Jail</application> is becoming the new security
     model. People are running potentially vulnerable servers such as
     Apache, BIND, and sendmail within jails, so that if an attacker
     gains root within the <application>Jail</application>, it is only
     an annoyance, and not a devastation. This article focuses on the
     internals (source code) of <application>Jail</application> and
     <application>Jail</application> NG. It will also suggest
     improvements upon the jail code base which are already being
     worked on. If you are looking for a how-to on setting up a
     <application>Jail</application>, I suggest you look at my other
     article in Sys Admin Magazine, May 2001, entitled "Securing
     FreeBSD using <application>Jail</application>."</para>
 
-  <sect1>
+  <sect1 id="jail-arch">
     <title>Architecture</title>
 
     <para>
       <application>Jail</application> consists of two realms: the
       user-space program, jail, and the code implemented within the
       kernel: the <literal>jail()</literal> system call and associated
       restrictions. I will be discussing the user-space program and
       then how jail is implemented within the kernel.</para>
 
     <sect2>
       <title>Userland code</title>
 
       <para>The source for the user-land jail is located in
         <filename>/usr/src/usr.sbin/jail</filename>, consisting of
         one file, <filename>jail.c</filename>. The program takes these
         arguments: the path of the jail, hostname, ip address, and the
         command to be executed.</para>
 
       <sect3>
         <title>Data Structures</title>
 
         <para>In <filename>jail.c</filename>, the first thing I would
           note is the declaration of an important structure
           <literal>struct jail j</literal>; which was included from
           <filename>/usr/include/sys/jail.h</filename>.
 
         <para>The definition of the jail structure is:</para>
 
 <programlisting><filename>/usr/include/sys/jail.h</filename>: 
 
 struct jail {
         u_int32_t       version;
         char            *path;
         char            *hostname;
         u_int32_t       ip_number;
 };</programlisting>
 
         <para>As you can see, there is an entry for each of the
           arguments passed to the jail program, and indeed, they are
           set during it's execution.</para>
 
         <programlisting><filename>/usr/src/usr.sbin/jail.c</filename>
 j.version = 0; 
 j.path = argv[1];
 j.hostname = argv[2];</programlisting>
 
       </sect3>
 
       <sect3>
         <title>Networking</title>
 
         <para>One of the arguments passed to the Jail program is an IP
           address with which the jail can be accessed over the
           network. Jail translates the ip address given into network
           byte order and then stores it in j (the jail structure).</para>
 
         <programlisting><filename>/usr/src/usr.sbin/jail/jail.c</filename>:
 struct in.addr in; 
 ... 
 i = inet.aton(argv[3], <![CDATA[&in]]>); 
 ... 
 j.ip_number = ntohl(in.s.addr);</programlisting>
 
         <para>The
           <citerefentry><refentrytitle>inet_aton</refentrytitle><manvolnum>3</manvolnum></citerefentry>
           function "interprets the specified character string as an
           Internet address, placing the address into the structure
           provided." The ip number node in the jail structure is set
           only when the ip address placed onto the in structure by
           inet aton is translated into network byte order by
           <function>ntohl()</function>.</para>
 
       </sect3>
 
       <sect3>
         <title>Jailing The Process</title>
 
         <para>Finally, the userland program jails the process, and
           executes the command specified. Jail now becomes an
           imprisoned process itself and forks a child process which
           then executes the command given using &man.execv.3;
 
         <programlisting><filename>/usr/src/sys/usr.sbin/jail/jail.c</filename>
 i = jail(<![CDATA[&j]]>); 
 ... 
 i = execv(argv[4], argv + 4);</programlisting>
 
         <para>As you can see, the jail function is being called, and
           its argument is the jail structure which has been filled
           with the arguments given to the program. Finally, the
           program you specify is executed. I will now discuss how Jail
           is implemented within the kernel.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Kernel Space</title>
 
       <para>We will now be looking at the file
         <filename>/usr/src/sys/kern/kern_jail.c</filename>.  This is
         the file where the jail system call, appropriate sysctls, and
         networking functions are defined.</para>
 
       <sect3>
         <title>sysctls</title>
 
         <para>In <filename>kern_jail.c</filename>, the following
           sysctls are defined:</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c:</filename>
 
 int     jail_set_hostname_allowed = 1;
 SYSCTL_INT(_jail, OID_AUTO, set_hostname_allowed, CTLFLAG_RW,
     <![CDATA[&jail]]>_set_hostname_allowed, 0,
     "Processes in jail can set their hostnames");
 
 int     jail_socket_unixiproute_only = 1;
 SYSCTL_INT(_jail, OID_AUTO, socket_unixiproute_only, CTLFLAG_RW,
     <![CDATA[&jail]]>_socket_unixiproute_only, 0,
     "Processes in jail are limited to creating UNIX/IPv4/route sockets only
 ");
 
 int     jail_sysvipc_allowed = 0;
 SYSCTL_INT(_jail, OID_AUTO, sysvipc_allowed, CTLFLAG_RW,
     <![CDATA[&jail]]>_sysvipc_allowed, 0,
     "Processes in jail can use System V IPC primitives");</programlisting>
 
         <para>Each of these sysctls can be accessed by the user
           through the sysctl program. Throughout the kernel, these
           specific sysctls are recognized by their name. For example,
           the name of the first sysctl is
           <literal>jail.set.hostname.allowed</literal>.</para>
       </sect3>
 
       <sect3>
         <title>&man.jail.2; system call</title>
 
         <para>Like all system calls, the &man.jail.2; system call takes
           two arguments, <literal>struct proc *p</literal> and
           <literal>struct jail_args
           *uap</literal>. <literal>p</literal> is a pointer to a proc
           structure which describes the calling process. In this
           context, uap is a pointer to a structure which specifies the
           arguments given to &man.jail.2; from the userland program
           <filename>jail.c</filename>. When I described the userland
           program before, you saw that the &man.jail.2; system call was
           given a jail structure as its own argument.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c:</filename>
 int
 jail(p, uap)
         struct proc *p;
         struct jail_args /* {
                 syscallarg(struct jail *) jail;
         } */ *uap;</programlisting>
 
         <para>Therefore, <literal>uap->jail</literal> would access the
           jail structure which was passed to the system call. Next,
           the system call copies the jail structure into kernel space
           using the <literal>copyin()</literal>
           function. <literal>copyin()</literal> takes three arguments:
           the data which is to be copied into kernel space,
           <literal>uap->jail</literal>, where to store it,
           <literal>j</literal> and the size of the storage. The jail
           structure <literal>uap->jail</literal> is copied into kernel
           space and stored in another jail structure,
           <literal>j</literal>.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c: </filename>
 error = copyin(uap->jail, <![CDATA[&j]]>, sizeof j);</programlisting>
 
         <para>There is another important structure defined in
           jail.h. It is the prison structure
           (<literal>pr</literal>). The prison structure is used
           exclusively within kernel space. The &man.jail.2; system call
           copies everything from the jail structure onto the prison
           structure. Here is the definition of the prison structure.</para>
 
         <programlisting><filename>/usr/include/sys/jail.h</filename>:
 struct prison {
         int             pr_ref;
         char            pr_host[MAXHOSTNAMELEN];
         u_int32_t       pr_ip;
         void            *pr_linux;
 };</programlisting>
 
         <para>The jail() system call then allocates memory for a
         pointer to a prison structure and copies data between the two
         structures.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c</filename>:
  MALLOC(pr, struct prison *, sizeof *pr , M_PRISON, M_WAITOK);
  bzero((caddr_t)pr, sizeof *pr);
  error = copyinstr(j.hostname, <![CDATA[&pr->pr_host]]>, sizeof pr->pr_host, 0);
  if (error) 
          goto bail;</programlisting>
 
         <para>Finally, the jail system call chroots the path
           specified. The chroot function is given two arguments. The
           first is p, which represents the calling process, the second
           is a pointer to the structure chroot args. The structure
           chroot args contains the path which is to be chrooted. As
           you can see, the path specified in the jail structure is
           copied to the chroot args structure and used.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c</filename>:
 ca.path = j.path; 
 error = chroot(p, <![CDATA[&ca]]>);</programlisting>
 
         <para>These next three lines in the source are very important,
           as they specify how the kernel recognizes a process as
           jailed. Each process on a Unix system is described by its
           own proc structure. You can see the whole proc structure in
           <filename>/usr/include/sys/proc.h</filename>. For example,
           the p argument in any system call is actually a pointer to
           that process' proc structure, as stated before. The proc
           structure contains nodes which can describe the owner's
           identity (<literal>p_cred</literal>), the process resource
           limits (<literal>p_limit</literal>), and so on. In the
           definition of the process structure, there is a pointer to a
           prison structure. (<literal>p_prison</literal>).</para>
 
         <programlisting><filename>/usr/include/sys/proc.h: </filename>
 struct proc { 
 ...
 struct prison *p_prison; 
 ...
 };</programlisting>
 
         <para>In <filename>kern_jail.c</filename>, the function then
           copies the pr structure, which is filled with all the
           information from the original jail structure, over to the
           <literal>p->p_prison</literal> structure. It then does a
           bitwise OR of <literal>p->p_flag</literal> with the constant
           <literal>P_JAILED</literal>, meaning that the calling
           process is now recognized as jailed. The parent process of
           each process, forked within the jail, is the program jail
           itself, as it calls the &man.jail.2; system call. When the
           program is executed through execve, it inherits the
           properties of its parents proc structure, therefore it has
           the <literal>p->p_flag</literal> set, and the
           <literal>p->p_prison</literal> structure is filled.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c</filename>
 p->p.prison = pr; 
 p->p.flag |= P.JAILED;</programlisting>
 
         <para>When a process is forked from a parent process, the
           &man.fork.2; system call deals differently with imprisoned
           processes. In the fork system call, there are two pointers
           to a <literal>proc</literal> structure <literal>p1</literal>
           and <literal>p2</literal>. <literal>p1</literal> points to
           the parent's <literal>proc</literal> structure and p2 points
           to the child's unfilled <literal>proc</literal>
           structure. After copying all relevant data between the
           structures, &man.fork.2; checks if the structure
           <literal>p->p_prison</literal> is filled on
           <literal>p2</literal>. If it is, it increments the
           <literal>pr.ref</literal> by one, and sets the
           <literal>p_flag</literal> to one on the child process.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_fork.c</filename>:
 if (p2->p_prison) {
         p2->p_prison->pr_ref++;
 	p2->p_flag |= P_JAILED;
 }</programlisting>
 
       </sect3>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="jail-restrictions">
     <title>Restrictions</title>
 
     <para>Throughout the kernel there are access restrictions relating
       to jailed processes. Usually, these restrictions only check if
       the process is jailed, and if so, returns an error. For
       example:</para>
 
     <programlisting>if (p->p_prison) 
         return EPERM;</programlisting>
 
     <sect2>
       <title>SysV IPC</title>
 
       <para>System V IPC is based on messages. Processes can send each
         other these messages which tell them how to act. The functions
         which deal with messages are: <literal>msgsys</literal>,
         <literal>msgctl</literal>, <literal>msgget</literal>,
         <literal>msgsend</literal> and <literal>msgrcv</literal>.
         Earlier, I mentioned that there were certain sysctls you could
         turn on or off in order to affect the behavior of Jail. One of
         these sysctls was <literal>jail_sysvipc_allowed</literal>. On
         most systems, this sysctl is set to 0. If it were set to 1, it
         would defeat the whole purpose of having a jail; privleged
         users from within the jail would be able to affect processes
         outside of the environment. The difference between a message
         and a signal is that the message only consists of the signal
         number.</para>
 
       <para><filename>/usr/src/sys/kern/sysv_msg.c</filename>:</para>
 
       <itemizedlist>
         <listitem> <para>&man.msgget.3;: msgget returns (and possibly
         creates) a message descriptor that designates a message queue
         for use in other system calls.</para></listitem>
 
         <listitem> <para>&man.msgctl.3;: Using this function, a process
         can query the status of a message
         descriptor.</para></listitem>
 
         <listitem> <para>&man.msgsnd.3;: msgsnd sends a message to a
         process.</para></listitem>
 
         <listitem> <para>&man.msgrcv.3;: a process receives messages using
         this function</para></listitem>
 
       </itemizedlist>
 
       <para>In each of these system calls, there is this
         conditional:</para>
 
       <programlisting><filename>/usr/src/sys/kern/sysv msg.c</filename>:
 if (!jail.sysvipc.allowed && p->p_prison != NULL)
         return (ENOSYS);</programlisting>
 
       <para>Semaphore system calls allow processes to synchronize
         execution by doing a set of operations atomically on a set of
         semaphores. Basically semaphores provide another way for
         processes lock resources. However, process waiting on a
         semaphore, that is being used, will sleep until the resources
         are relinquished. The following semaphore system calls are
         blocked inside a jail: <literal>semsys</literal>,
         <literal>semget</literal>, <literal>semctl</literal> and
         <literal>semop</literal>.</para>
 
       <para><filename>/usr/src/sys/kern/sysv_sem.c</filename>:</para>
 
       <itemizedlist>
         <listitem>
           <para>&man.semctl.2;<literal>(id, num, cmd, arg)</literal>:
             Semctl does the specified cmd on the semaphore queue
             indicated by id.</para></listitem>
 
         <listitem>
            <para>&man.semget.2;<literal>(key, nsems, flag)</literal>:
            Semget creates an array of semaphores, corresponding to
            key.</para>
 
           <para><literal>Key and flag take on the same meaning as they
           do in msgget.</literal></para></listitem>
 
         <listitem><para>&man.semop.2;<literal>(id, ops, num)</literal>:
           Semop does the set of semaphore operations in the array of
           structures ops, to the set of semaphores identified by
           id.</para></listitem>
       </itemizedlist>
 
       <para>System V IPC allows for processes to share
         memory. Processes can communicate directly with each other by
         sharing parts of their virtual address space and then reading
         and writing data stored in the shared memory. These system
         calls are blocked within a jailed environment: <literal>shmdt,
         shmat, oshmctl, shmctl, shmget</literal>, and
         <literal>shmsys</literal>.</para>
 
       <para><filename>/usr/src/sys/kern/sysv shm.c</filename>:</para>
 
       <itemizedlist>
         <listitem><para>&man.shmctl.2;<literal>(id, cmd, buf)</literal>:
         shmctl does various control operations on the shared memory
         region identified by id.</para></listitem>
 
         <listitem><para>&man.shmget.2;<literal>(key, size,
         flag)</literal>: shmget accesses or creates a shared memory
         region of size bytes.</para></listitem>
 
         <listitem><para>&man.shmat.2;<literal>(id, addr, flag)</literal>:
         shmat attaches a shared memory region identified by id to the
         address space of a process.</para></listitem>
 
         <listitem><para>&man.shmdt.2;<literal>(addr)</literal>: shmdt
         detaches the shared memory region previously attached at
         addr.</para></listitem>
 
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Sockets</title>
 
       <para>Jail treats the &man.socket.2; system call and related
         lower-level socket functions in a special manner. In order to
         determine whether a certain socket is allowed to be created,
         it first checks to see if the sysctl
         <literal>jail.socket.unixiproute.only</literal> is set. If
         set, sockets are only allowed to be created if the family
         specified is either <literal>PF_LOCAL</literal>,
         <literal>PF_INET</literal> or
         <literal>PF_ROUTE</literal>. Otherwise, it returns an
         error.</para>
 
       <programlisting><filename>/usr/src/sys/kern/uipc_socket.c</filename>:
 int socreate(dom, aso, type, proto, p) 
 ... 
 register struct protosw *prp; 
 ... 
 {
         if (p->p_prison && jail_socket_unixiproute_only &&
             prp->pr_domain->dom_family != PR_LOCAL && prp->pr_domain->dom_family != PF_INET 
             && prp->pr_domain->dom_family != PF_ROUTE)
                 return (EPROTONOSUPPORT); 
 ...
 }</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Berkeley Packet Filter</title>
 
       <para>The Berkeley Packet Filter provides a raw interface to
         data link layers in a protocol independent fashion. The
         function <literal>bpfopen()</literal> opens an Ethernet
         device. There is a conditional which disallows any jailed
         processes from accessing this function.</para>
 
       <programlisting><filename>/usr/src/sys/net/bpf.c</filename>: 
 static int bpfopen(dev, flags, fmt, p) 
 ... 
 {
         if (p->p_prison) 
                 return (EPERM);
 ...
 }</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Protocols</title>
 
       <para>There are certain protocols which are very common, such as
         TCP, UDP, IP and ICMP. IP and ICMP are on the same level: the
         network layer 2. There are certain precautions which are
         taken in order to prevent a jailed process from binding a
         protocol to a certain port only if the <literal>nam</literal>
         parameter is set. nam is a pointer to a sockaddr structure,
         which describes the address on which to bind the service. A
         more exact definition is that sockaddr "may be used as a
         template for reffering to the identifying tag and length of
         each address"[2]. In the function in
         <literal>pcbbind</literal>, <literal>sin</literal> is a
         pointer to a sockaddr.in structure, which contains the port,
         address, length and domain family of the socket which is to be
         bound. Basically, this disallows any processes from jail to be
         able to specify the domain family.</para>
 
       <programlisting><filename>/usr/src/sys/kern/netinet/in_pcb.c</filename>: 
 int in.pcbbind(int, nam, p) 
 ...
         struct sockaddr *nam; 
         struct proc *p; 
 {
         ... 
         struct sockaddr.in *sin; 
         ... 
         if (nam) {
                 sin = (struct sockaddr.in *)nam; 
                 ... 
                 if (sin->sin_addr.s_addr != INADDR_ANY) 
                        if (prison.ip(p, 0, <![CDATA[&sin]]>->sin.addr.s_addr)) 
                               return (EINVAL); 
                 ....
         }
 ...
 }</programlisting>
 
       <para>You might be wondering what function
         <literal>prison_ip()</literal> does. prison.ip is given three
         arguments, the current process (represented by
         <literal>p</literal>), any flags, and an ip address. It
         returns 1 if the ip address belongs to a jail or 0 if it does
         not. As you can see from the code, if it is indeed an ip
         address belonging to a jail, the protcol is not allowed to
         bind to a certain port.</para>
 
       <programlisting><filename>/usr/src/sys/kern/kern_jail.c:</filename>
 int prison_ip(struct proc *p, int flag, u_int32_t *ip) {
         u_int32_t tmp;
 
        if (!p->p_prison) 
               return (0); 
        if (flag) 
               tmp = *ip; 
        else tmp = ntohl (*ip); 
 
        if (tmp == INADDR_ANY) {
               if (flag) 
                      *ip = p->p_prison->pr_ip; 
               else *ip = htonl(p->p_prison->pr_ip); 
               return (0); 
        }
 
        if (p->p_prison->pr_ip != tmp) 
               return (1); 
        return (0); 
 }</programlisting>
 
       <para>Jailed users are not allowed to bind services to an ip
         which does not belong to the jail. The restriction is also
         written within the function <literal>in_pcbbind</literal>:</para>
 
       <programlisting><filename>/usr/src/sys/net inet/in_pcb.c</filename>
         if (nam) {
                ... 
                lport = sin->sin.port; 
                ... if (lport) { 
                           ... 
                          if (p && p->p_prison)
                                 prison = 1; 
                          if (prison &&
                              prison_ip(p, 0, <![CDATA[&sin]]>->sin_addr.s_addr))
 			            return (EADDRNOTAVAIL);</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Filesystem</title>
 
       <para>Even root users within the jail are not allowed to set any
         file flags, such as immutable, append, and no unlink flags, if
         the securelevel is greater than 0.</para>
 
       <programlisting>/usr/src/sys/ufs/ufs/ufs_vnops.c:
 int ufs.setattr(ap) 
         ... 
 {
         if ((cred->cr.uid == 0) && (p->prison == NULL)) {
 	        if ((ip->i_flags 
                      & (SF_NOUNLINK | SF_IMMUTABLE | SF_APPEND)) && 
                      securelevel > 0)
 		       return (EPERM);
 }</programlisting>
 
     </sect2>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="jail-jailng">
     <title>Jail NG</title>
 
     <para>Jail NG is a "from-scratch re-implementation of Jail" by
       Robert Watson, a FreeBSD committer. Some of the new features
       include the ability to add processes to a jail, an improved
       management tool, and per-jail sysctls. For example, you could
       have <literal>sysvipc_permitted</literal> set on one jail while
       another jail may be allowed to use System V IPC. You can
       download the kernel patches and utilities for Jail NG from his
       website at:
       <ulink
       url="http://www.watson.org/~robert/jailng/"></ulink>.</para>
 
   </sect1>
 
 </chapter>
 
diff --git a/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.sgml
index f8fd4d9851..b2ef1f689b 100644
--- a/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.sgml
@@ -1,298 +1,298 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="kernel-objects">
   <title>Kernel Objects</title>
 
   <para>Kernel Objects, or <firstterm>Kobj</firstterm> provides an
     object-oriented C programming system for the kernel. As such the
     data being operated on carries the description of how to operate
     on it. This allows operations to be added and removed from an
     interface at run time and without breaking binary
     compatibility.</para>
 
-  <sect1>
+  <sect1 id="kernel-objects-term">
     <title>Terminology</title>
 
     <variablelist>
       <varlistentry>
 	<term>Object</term>
 	<listitem><para>A set of data - data structure - data
 	allocation.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Method</term>
 	<listitem>
 	  <para>An operation - function.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Class</term>
 	<listitem>
 	  <para>One or more methods.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Interface</term>
 	<listitem>
 	  <para>A standard set of one or more methods.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
-  <sect1>
+  <sect1 id="kernel-objects-operation">
     <title>Kobj Operation</title>
 
     <para>Kobj works by generating descriptions of methods. Each
       description holds a unique id as well as a default function. The
       description's address is used to uniquely identify the method
       within a class' method table.</para>
 
     <para>A class is built by creating a method table associating one
       or more functions with method descriptions. Before use the class
       is compiled. The compilation allocates a cache and associates it
       with the class. A unique id is assigned to each method
       description within the method table of the class if not already
       done so by another referencing class compilation. For every
       method to be used a function is generated by script to qualify
       arguments and automatically reference the method description for
       a lookup. The generated function looks up the method by using
       the unique id associated with the method description as a hash
       into the cache associated with the object's class. If the method
       is not cached the generated function proceeds to use the class'
       table to find the method. If the method is found then the
       associated function within the class is used; otherwise, the
       default function associated with the method description is
       used.</para>
 
     <para>These indirections can be visualized as the
       following:</para>
 
     <programlisting>object->cache<->class</programlisting>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="kernel-objects-using">
     <title>Using Kobj</title>
 
     <sect2>
       <title>Structures</title>
 
       <programlisting>struct kobj_method</programlisting>
     </sect2>
 
     <sect2>
       <title>Functions</title>
 
       <programlisting>void kobj_class_compile(kobj_class_t cls);
 void kobj_class_compile_static(kobj_class_t cls, kobj_ops_t ops);
 void kobj_class_free(kobj_class_t cls);
 kobj_t kobj_create(kobj_class_t cls, struct malloc_type *mtype, int mflags);
 void kobj_init(kobj_t obj, kobj_class_t cls);
 void kobj_delete(kobj_t obj, struct malloc_type *mtype);</programlisting>
     </sect2>
 
     <sect2>
       <title>Macros</title>
 
       <programlisting>KOBJ_CLASS_FIELDS
 KOBJ_FIELDS
 DEFINE_CLASS(name, methods, size)
 KOBJMETHOD(NAME, FUNC)</programlisting>
     </sect2>
 
     <sect2>
       <title>Headers</title>
 
       <programlisting>&lt;sys/param.h>
 &lt;sys/kobj.h></programlisting>
     </sect2>
 
     <sect2>
       <title>Creating an interface template</title>
 
       <para>The first step in using Kobj is to create an
         Interface. Creating the interface involves creating a template
         that the script
         <filename>src/sys/kern/makeobjops.pl</filename> can use to
         generate the header and code for the method declarations and
         method lookup functions.</para>
 
       <para>Within this template the following keywords are used:
         <literal>#include</literal>, <literal>INTERFACE</literal>,
         <literal>CODE</literal>, <literal>METHOD</literal>,
         <literal>STATICMETHOD</literal>, and
         <literal>DEFAULT</literal>.</para>
 
       <para>The <literal>#include</literal> statement and what follows
         it is copied verbatim to the head of the generated code
         file.</para>
 
       <para>For example:</para>
 
       <programlisting>#include &lt;sys/foo.h></programlisting>
 
       <para>The <literal>INTERFACE</literal> keyword is used to define
         the interface name. This name is concatenated with each method
         name as [interface name]_[method name]. Its syntax is
         INTERFACE [interface name];.</para>
 
       <para>For example:</para>
 
       <programlisting>INTERFACE foo;</programlisting>
 
       <para>The <literal>CODE</literal> keyword copies its arguments
       verbatim into the code file. Its syntax is
       <literal>CODE { [whatever] };</literal></para>
 
       <para>For example:</para>
 
       <programlisting>CODE {
 	struct foo * foo_alloc_null(struct bar *)
 	{
 		return NULL;
 }
 };</programlisting>
 
       <para>The <literal>METHOD</literal> keyword describes a method. Its syntax is
       <literal>METHOD [return type] [method name] { [object [,
       arguments]] };</literal></para>
 
       <para>For example:</para>
 
       <programlisting>METHOD int bar {
 	struct object *;
 	struct foo *;
 	struct bar;
 };</programlisting>
 
       <para>The <literal>DEFAULT</literal> keyword may follow the
         <literal>METHOD</literal> keyword. It extends the
         <literal>METHOD</literal> key word to include the default
         function for method. The extended syntax is
         <literal>METHOD [return type] [method name] {
         [object; [other arguments]] }DEFAULT [default
         function];</literal></para>
 
       <para>For example:</para>
 
       <programlisting>METHOD int bar {
 	struct object *;
 	struct foo *;
 	int bar;
 } DEFAULT foo_hack;</programlisting>
 
       <para>The <literal>STATICMETHOD</literal> keyword is used like
       the <literal>METHOD</literal> keyword except the kobj data is not
       at the head of the object structure so casting to kobj_t would
       be incorrect. Instead <literal>STATICMETHOD</literal> relies on the Kobj data being
       referenced as 'ops'. This is also useful for calling
       methods directly out of a class's method table.</para>
 
       <para>Other complete examples:</para>
 
       <programlisting>src/sys/kern/bus_if.m
 src/sys/kern/device_if.m</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Creating a Class</title>
 
       <para>The second step in using Kobj is to create a class. A
         class consists of a name, a table of methods, and the size of
         objects if Kobj's object handling facilities are used. To
         create the class use the macro
         <function>DEFINE_CLASS()</function>. To create the method
         table create an array of kobj_method_t terminated by a NULL
         entry. Each non-NULL entry may be created using the macro
         <function>KOBJMETHOD()</function>.</para>
 
       <para>For example:</para>
 
       <programlisting>DEFINE_CLASS(fooclass, foomethods, sizeof(struct foodata));
 
 kobj_method_t foomethods[] = {
 	KOBJMETHOD(bar_doo, foo_doo),
 	KOBJMETHOD(bar_foo, foo_foo),
 	{ NULL, NULL}
 };</programlisting>
 
       <para>The class must be <quote>compiled</quote>.  Depending on
         the state of the system at the time that the class is to be
         initialized a statically allocated cache, <quote>ops
         table</quote> have to be used. This can be accomplished by
         declaring a <structname>struct kobj_ops</structname> and using
         <function>kobj_class_compile_static();</function> otherwise,
         <function>kobj_class_compile()</function> should be used.</para>
     </sect2>
 
     <sect2>
       <title>Creating an Object</title>
 
       <para>The third step in using Kobj involves how to define the
         object. Kobj object creation routines assume that Kobj data is
         at the head of an object. If this in not appropriate you will
         have to allocate the object yourself and then use
         <function>kobj_init()</function> on the Kobj portion of it;
         otherwise, you may use <function>kobj_create()</function> to
         allocate and initialize the Kobj portion of the object
         automatically. <function>kobj_init()</function> may also be
         used to change the class that an object uses.</para>
 
       <para>To integrate Kobj into the object you should use the macro
        KOBJ_FIELDS.</para>
 
       <para>For example</para>
 
       <programlisting>struct foo_data {
 	KOBJ_FIELDS;
 	foo_foo;
 	foo_bar;
 };</programlisting>
     </sect2>
 
     <sect2>
       <title>Calling Methods</title>
 
       <para>The last step in using Kobj is to simply use the generated
 	functions to use the desired method within the object's
 	class. This is as simple as using the interface name and the
 	method name with a few modifications. The interface name
 	should be concatenated with the method name using a '_'
 	between them, all in upper case.</para>
 
       <para>For example, if the interface name was foo and the method
       was bar then the call would be:</para>
 
       <programlisting>[return value = ] FOO_BAR(object [, other parameters]);</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Cleaning Up</title>
 
       <para>When an object allocated through
         <function>kobj_create()</function> is no longer needed
         <function>kobj_delete()</function> may be called on it, and
         when a class is no longer being used
         <function>kobj_class_free()</function> may be called on it.</para>
     </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/arch-handbook/locking/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/locking/chapter.sgml
index 00501a8d2f..e604ef443b 100644
--- a/en_US.ISO8859-1/books/arch-handbook/locking/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/locking/chapter.sgml
@@ -1,333 +1,333 @@
 <!--
      The FreeBSD Documentation Project
      The FreeBSD SMP Next Generation Project
 
      $FreeBSD$
 -->
 
 <chapter id="locking">
   <title>Locking Notes</title>
 
   <para><emphasis>This chapter is maintained by the FreeBSD SMP Next
     Generation Project.  Please direct any comments or suggestions
     to its &a.smp;.</emphasis></para>
 
 
   <para>This document outlines the locking used in the FreeBSD kernel
     to permit effective multi-processing within the kernel.  Locking
     can be achieved via several means.  Data structures can be
     protected by mutexes or &man.lockmgr.9; locks.  A few variables
     are protected simply by always using atomic operations to access
     them.</para>
 
-  <sect1>
+  <sect1 id="locking-mutexes">
     <title>Mutexes</title>
 
     <para>A mutex is simply a lock used to guarantee mutual exclusion.
       Specifically, a mutex may only be owned by one entity at a time.
       If another entity wishes to obtain a mutex that is already
       owned, it must wait until the mutex is released.  In the FreeBSD
       kernel, mutexes are owned by processes.</para>
 
     <para>Mutexes may be recursively acquired, but they are intended
       to be held for a short period of time.  Specifically, one may
       not sleep while holding a mutex.  If you need to hold a lock
       across a sleep, use a &man.lockmgr.9; lock.</para>
     
     <para>Each mutex has several properties of interest:</para>
 
     <variablelist>
 	<varlistentry>
 	<term>Variable Name</term>
 	<listitem>
 	  <para>The name of the <type>struct mtx</type> variable in
 	    the kernel source.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Logical Name</term>
 	<listitem>
 	  <para>The name of the mutex assigned to it by
 	    <function>mtx_init</function>.  This name is displayed in
 	    KTR trace messages and witness errors and warnings and is
 	    used to distinguish mutexes in the witness code.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Type</term>
 	<listitem>
 	  <para>The type of the mutex in terms of the
 	    <constant>MTX_*</constant> flags.  The meaning for each
 	    flag is related to its meaning as documented in
 	    &man.mutex.9;.</para>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term><constant>MTX_DEF</constant></term>
 	      <listitem>
 		<para>A sleep mutex</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><constant>MTX_SPIN</constant></term>
 	      <listitem>
 		<para>A spin mutex</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><constant>MTX_COLD</constant></term>
 	      <listitem>
 		<para>This mutex is initialized very early.  Thus, it
 		  must be declared via
 		  <function>MUTEX_DECLARE</function>, and the
 		  <constant>MTX_COLD</constant> flag must be passed to
 		  <function>mtx_init</function>.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><constant>MTX_TOPHALF</constant></term>
 	      <listitem>
 		<para>This spin mutex does not disable
 		  interrupts.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><constant>MTX_NORECURSE</constant></term>
 	      <listitem>
 		<para>This mutex is not allowed to recurse.</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Protectees</term>
 	<listitem>
 	  <para>A list of data structures or data structure members
 	    that this entry protects.  For data structure members, the
 	    name will be in the form of
 	    <structname/structure name/.<structfield/member name/.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Dependent Functions</term>
 	<listitem>
 	  <para>Functions that can only be called if this mutex is
 	    held.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <table frame="all" colsep="1" rowsep="1" pgwide="1">
       <title>Mutex List</title>
       
       <tgroup cols="5">
 	<thead>
 	  <row>
 	    <entry>Variable Name</entry>
 	    <entry>Logical Name</entry>
 	    <entry>Type</entry>
 	    <entry>Protectees</entry>
 	    <entry>Dependent Functions</entry>
 	  </row>
 	</thead>
 	
 	<!-- The scheduler lock -->
 	<tbody>
 	  <row>
 	    <entry>sched_lock</entry>
 	    <entry><quote>sched lock</quote></entry>
 	    <entry>
 	      <constant>MTX_SPIN</constant> |
 	      <constant>MTX_COLD</constant>
 	    </entry>
 	    <entry>
 	      <varname>_gmonparam</varname>,
 	      <varname>cnt.v_swtch</varname>,
 	      <varname>cp_time</varname>,
 	      <varname>curpriority</varname>,
 	      <structname/mtx/.<structfield/mtx_blocked/,
 	      <structname/mtx/.<structfield/mtx_contested/,
 	      <structname/proc/.<structfield/p_contested/,
 	      <structname/proc/.<structfield/p_blocked/,
 	      <structname/proc/.<structfield/p_flag/
 		(<constant>P_PROFIL</constant> XXX,
 		 <constant>P_INMEM</constant>,
 	         <constant>P_SINTR</constant>,
 	         <constant>P_TIMEOUT</constant>,
 	         <constant>P_SWAPINREQ</constant> XXX,
 	         <constant>P_INMEN</constant> XXX),
 	      <structname/proc/.<structfield/p_nice/,
 	      <structname/proc/.<structfield/p_procq/,
 	      <structname/proc/.<structfield/p_blocked/,
 	      <structname/proc/.<structfield/p_estcpu/,
 	      <structname/proc/.<structfield/p_nativepri/,
 	      <structname/proc/.<structfield/p_priority/,
 	      <structname/proc/.<structfield/p_usrpri/,
 	      <structname/proc/.<structfield/p_rtprio/,
 	      <structname/proc/.<structfield/p_rqindex/,
 	      <structname/proc/.<structfield/p_stats->p_prof/,
 	      <structname/proc/.<structfield/p_stats->p_ru/,
 	      <structname/proc/.<structfield/p_stat/,
 	      <structname/proc/.<structfield/p_cpticks/
 	      <structname/proc/.<structfield/p_iticks/,
 	      <structname/proc/.<structfield/p_uticks/,
 	      <structname/proc/.<structfield/p_sticks/,
 	      <structname/proc/.<structfield/p_swtime/,
 	      <structname/proc/.<structfield/p_slptime/,
 	      <structname/proc/.<structfield/p_runtime/,
 	      <structname/proc/.<structfield/p_pctcpu/,
 	      <structname/proc/.<structfield/p_oncpu/,
 	      <structname/proc/.<structfield/p_asleep/,
 	      <structname/proc/.<structfield/p_wchan/,
 	      <structname/proc/.<structfield/p_wmesg/,
 	      <structname/proc/.<structfield/p_slpq/,
 	      <structname/proc/.<structfield/p_vmspace/
 		(XXX - in <function>statclock</function>),
 	      <varname>pscnt</varname>,
 	      <varname>slpque</varname>,
 	      <varname>itqueuebits</varname>,
 	      <varname>itqueues</varname>,
 	      <varname>rtqueuebits</varname>,
 	      <varname>rtqueues</varname>,
 	      <varname>queuebits</varname>,
 	      <varname>queues</varname>,
 	      <varname>idqueuebits</varname>,
 	      <varname>idqueues</varname>,
 	      <varname>switchtime</varname>,
 	    </entry>
 	    <entry>
 	      <function>setrunqueue</function>,
 	      <function>remrunqueue</function>,
 	      <function>mi_switch</function>,
 	      <function>chooseproc</function>,
 	      <function>schedclock</function>,
 	      <function>resetpriority</function>,
 	      <function>updatepri</function>,
 	      <function>maybe_resched</function>,
 	      <function>cpu_switch</function>,
 	      <function>cpu_throw</function>
 	    </entry>
 	  </row>
 
 	  <!-- The vm86 pcb lock -->
 	  <row>
 	    <entry>vm86pcb_lock</entry>
 	    <entry><quote>vm86pcb lock</quote></entry>
 	    <entry>
 	      <constant>MTX_DEF</constant> |
 	      <constant>MTX_COLD</constant>
 	    </entry>
 	    <entry>
 	      <varname>vm86pcb</varname>
 	    </entry>
 	    <entry>
 	      <function>vm86_bioscall</function>
 	    </entry>
 	  </row>
 
 	  <!-- Giant -->
 	  <row>
 	    <entry>Giant</entry>
 	    <entry><quote>Giant</quote></entry>
 	    <entry>
 	      <constant>MTX_DEF</constant> |
 	      <constant>MTX_COLD</constant>
 	    </entry>
 	    <entry>nearly everything</entry>
 	    <entry>lots</entry>
 	  </row>
 
 	  <!-- The callout lock -->
 	  <row>
 	    <entry>callout_lock</entry>
 	    <entry><quote>callout lock</quote></entry>
 	    <entry>
 	      <constant>MTX_SPIN</constant>
 	    </entry>
 	    <entry>
 	      <varname>callfree</varname>,
 	      <varname>callwheel</varname>,
 	      <varname>nextsoftcheck</varname>,
 	      <structname/proc/.<structfield/p_itcallout/,
 	      <structname/proc/.<structfield/p_slpcallout/,
 	      <varname>softticks</varname>,
 	      <varname>ticks</varname>
 	    </entry>
 	    <entry>
 	    </entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
   </sect1>
 
-  <sect1>
+  <sect1 id="locking-lockmgr">
     <title>Lock Manager Locks</title>
 
     <para>Locks that are provided via the &man.lockmgr.9; interface
       are lock manager locks.  These locks are reader-writer locks and
       may be held by a sleeping process.</para>
 
     <table>
       <title>&man.lockmgr.9; Lock List</title>
 
       <tgroup cols="2">
 	<thead>
 	  <row>
 	    <entry>Variable Name</entry>
 	    <entry>Protectees</entry>
 	  </row>
 	</thead>
 	<tbody>
 	  <row>
 	    <entry><varname>allproc_lock</varname></entry>
 	    <entry>
 	      <varname>allproc</varname>
 	      <varname>zombproc</varname>
 	      <varname>pidhashtbl</varname>
 	      <structname/proc/.<structfield/p_list/
 	      <structname/proc/.<structfield/p_hash/
 	      <varname>nextpid</varname>
 	    </entry>
 	    <entry><varname>proctree_lock</varname></entry>
 	    <entry>
 	      <structname/proc/.<structfield/p_children/
 	      <structname/proc/.<structfield/p_sibling/
 	    </entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
   </sect1>
 
-  <sect1>
+  <sect1 id="locking-atomic">
     <title>Atomically Protected Variables</title>
 
     <para>An atomically protected variable is a special variable that
       is not protected by an explicit lock.  Instead, all data
       accesses to the variables use special atomic operations as
       described in &man.atomic.9;.  Very few variables are treated
       this way, although other synchronization primitives such as
       mutexes are implemented with atomically protected
       variables.</para>
 
     <itemizedlist>
       <listitem>
 	<para><varname>astpending</varname></para>
       </listitem>
 
       <listitem>
 	<para><structname/mtx/.<structfield/mtx_lock/</para>
       </listitem>
     </itemizedlist>
   </sect1>
 </chapter>
diff --git a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml
index 15146dc9e9..c422ec49d3 100644
--- a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.sgml
@@ -1,369 +1,369 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="pci">
   <title>PCI Devices</title>
 
   <para>This chapter will talk about the FreeBSD mechanisms for
     writing a device driver for a device on a PCI bus.</para>
 
-  <sect1>
+  <sect1 id="pci-probe">
     <title>Probe and Attach</title>
 
     <para>Information here about how the PCI bus code iterates through
       the unattached devices and see if a newly loaded kld will attach
       to any of them.</para>
 
 <programlisting>/*
  * Simple KLD to play with the PCI functions.
  *
  * Murray Stokely
  */
 
 #define MIN(a,b) (((a) < (b)) ? (a) : (b))
 
 #include &lt;sys/types.h&gt;
 #include &lt;sys/module.h&gt;
 #include &lt;sys/systm.h&gt;  /* uprintf */ 
 #include &lt;sys/errno.h&gt;
 #include &lt;sys/param.h&gt;  /* defines used in kernel.h */
 #include &lt;sys/kernel.h&gt; /* types used in module initialization */
 #include &lt;sys/conf.h&gt;   /* cdevsw struct */
 #include &lt;sys/uio.h&gt;    /* uio struct */
 #include &lt;sys/malloc.h&gt;
 #include &lt;sys/bus.h&gt;	/* structs, prototypes for pci bus stuff */
 
 #include &lt;pci/pcivar.h&gt; /* For get_pci macros! */
 
 /* Function prototypes */
 d_open_t      mypci_open;
 d_close_t     mypci_close;
 d_read_t      mypci_read;
 d_write_t     mypci_write;
 
 /* Character device entry points */
 
 static struct cdevsw mypci_cdevsw = {
   mypci_open,
   mypci_close,
   mypci_read,
   mypci_write,
   noioctl,
   nopoll,
   nommap,
   nostrategy,
   "mypci",
   36,                   /* reserved for lkms - /usr/src/sys/conf/majors */
   nodump,
   nopsize,
   D_TTY,
   -1
 };
 
 /* vars */
 static dev_t sdev;
 
 /* We're more interested in probe/attach than with
    open/close/read/write at this point */
 
 int 
 mypci_open(dev_t dev, int oflags, int devtype, struct proc *p)
 {
   int err = 0;
 
   uprintf("Opened device \"mypci\" successfully.\n");
   return(err);
 }
 
 int 
 mypci_close(dev_t dev, int fflag, int devtype, struct proc *p)
 {
   int err=0;
 
   uprintf("Closing device \"mypci.\"\n"); 
   return(err);
 } 
 
 int
 mypci_read(dev_t dev, struct uio *uio, int ioflag)
 {
   int err = 0;
 
   uprintf("mypci read!\n");
   return err;
 }
 
 int
 mypci_write(dev_t dev, struct uio *uio, int ioflag)
 {
   int err = 0;
 
   uprintf("mypci write!\n");
   return(err);
 }
 
 /* PCI Support Functions */
 
 /*
  * Return identification string if this is device is ours.
  */
 static int
 mypci_probe(device_t dev)
 {
   uprintf("MyPCI Probe\n"
 	  "Vendor ID : 0x%x\n"
 	  "Device ID : 0x%x\n",pci_get_vendor(dev),pci_get_device(dev));
 
   if (pci_get_vendor(dev) == 0x11c1) {
     uprintf("We've got the Winmodem, probe successful!\n");
     return 0;
   }
 
   return ENXIO;
 }
 
 /* Attach function is only called if the probe is successful */
 
 static int
 mypci_attach(device_t dev)
 {
   uprintf("MyPCI Attach for : deviceID : 0x%x\n",pci_get_vendor(dev));
   sdev = make_dev(<literal>&</literal>mypci_cdevsw,
 		  0,
 		  UID_ROOT,
 		  GID_WHEEL,
 		  0600,
 		  "mypci");
   uprintf("Mypci device loaded.\n");
   return ENXIO;
 }
 
 /* Detach device. */
 
 static int
 mypci_detach(device_t dev)
 {
   uprintf("Mypci detach!\n");
   return 0;
 }
 
 /* Called during system shutdown after sync. */
 
 static int
 mypci_shutdown(device_t dev)
 {
   uprintf("Mypci shutdown!\n");
   return 0;
 }
 
 /*
  * Device suspend routine.  
  */
 static int
 mypci_suspend(device_t dev)
 {
   uprintf("Mypci suspend!\n");
   return 0;
 }
 
 /*
  * Device resume routine.
  */
 
 static int
 mypci_resume(device_t dev)
 {
   uprintf("Mypci resume!\n");
   return 0;
 }
 
 static device_method_t mypci_methods[] = {
 	/* Device interface */
 	DEVMETHOD(device_probe,		mypci_probe),
 	DEVMETHOD(device_attach,	mypci_attach),
 	DEVMETHOD(device_detach,	mypci_detach),
 	DEVMETHOD(device_shutdown,	mypci_shutdown),
 	DEVMETHOD(device_suspend,	mypci_suspend),
 	DEVMETHOD(device_resume,	mypci_resume),
 
 	{ 0, 0 }
 };
 
 static driver_t mypci_driver = {
 	"mypci",
 	mypci_methods,
 	0,
 	/*	sizeof(struct mypci_softc), */
 };
 
 static devclass_t mypci_devclass;
 
 DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0);</programlisting>
       
     <para>Additional Resources
     <itemizedlist>
       <listitem><simpara><ulink url="http://www.pcisig.org/">PCI
 	Special Interest Group</ulink></simpara></listitem>
 
       <listitem><simpara>PCI System Architecture, Fourth Edition by
 	Tom Shanley, et al.</simpara></listitem>
 
     </itemizedlist>
     </para>
   </sect1>
 
-  <sect1>
+  <sect1 id="pci-bus">
     <title>Bus Resources</title>
 
     <para>FreeBSD provides an object-oriented mechanism for requesting
       resources from a parent bus.  Almost all devices will be a child
       member of some sort of bus (PCI, ISA, USB, SCSI, etc) and these
       devices need to acquire resources from their parent bus (such as
       memory segments, interrupt lines, or DMA channels).</para>
 
     <sect2>
       <title>Base Address Registers</title>
 
       <para>To do anything particularly useful with a PCI device you
       will need to obtain the <emphasis>Base Address
       Registers</emphasis> (BARs) from the PCI Configuration space.
       The PCI-specific details of obtaining the BAR is abstracted in
       the <function>bus_alloc_resource()</function> function.</para>
 
       <para>For example, a typical driver might have something similar
       to this in the <function>attach()</function> function:</para>
 
 <programlisting>    sc->bar0id = 0x10;
     sc->bar0res = bus_alloc_resource(dev, SYS_RES_MEMORY, &amp;(sc->bar0id),
 				  0, ~0, 1, RF_ACTIVE);
     if (sc->bar0res == NULL) {
         uprintf("Memory allocation of PCI base register 0 failed!\n");
         error = ENXIO;
         goto fail1;
     }
 
     sc->bar1id = 0x14;
     sc->bar1res = bus_alloc_resource(dev, SYS_RES_MEMORY, &amp;(sc->bar1id),
 				  0, ~0, 1, RF_ACTIVE);
     if (sc->bar1res == NULL) {
         uprintf("Memory allocation of PCI base register 1 failed!\n");
         error =  ENXIO;
         goto fail2;
     }
     sc->bar0_bt = rman_get_bustag(sc->bar0res);
     sc->bar0_bh = rman_get_bushandle(sc->bar0res);
     sc->bar1_bt = rman_get_bustag(sc->bar1res);
     sc->bar1_bh = rman_get_bushandle(sc->bar1res);
 
 </programlisting>
 
       <para>Handles for each base address register are kept in the
         <structname>softc</structname> structure so that they can be
         used to write to the device later.</para>
 
       <para>These handles can then be used to read or write from the
         device registers with the <function>bus_space_*</function>
         functions.  For example, a driver might contain a shorthand
         function to read from a board specific register like this:</para>
 
 <programlisting>uint16_t
 board_read(struct ni_softc *sc, uint16_t address) {
     return bus_space_read_2(sc->bar1_bt, sc->bar1_bh, address);
 }
 </programlisting>
 
       <para>Similarly, one could write to the registers with:</para>
 
 <programlisting>void
 board_write(struct ni_softc *sc, uint16_t address, uint16_t value) {
     bus_space_write_2(sc->bar1_bt, sc->bar1_bh, address, value);
 }
 </programlisting>
 
       <para>These functions exist in 8bit, 16bit, and 32bit versions
         and you should use
         <function>bus_space_{read|write}_{1|2|4}</function>
         accordingly.</para>
 
     </sect2>
     <sect2>
       <title>Interrupts</title>
 
       <para>Interrupts are allocated from the object-oriented bus code
         in a way similar to the memory resources.  First an IRQ
         resource must be allocated from the parent bus, and then the
         interrupt handler must be setup to deal with this IRQ.</para>
 
       <para>Again, a sample from a device
         <function>attach()</function> function says more than
         words.</para>
 
 <programlisting>/* Get the IRQ resource */
 
     sc->irqid = 0x0;
     sc->irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &amp;(sc->irqid),
 				  0, ~0, 1, RF_SHAREABLE | RF_ACTIVE);
     if (sc->irqres == NULL) {
 	uprintf("IRQ allocation failed!\n");
 	error = ENXIO;
 	goto fail3;
     }
 
     /* Now we should setup the interrupt handler */
 
     error = bus_setup_intr(dev, sc->irqres, INTR_TYPE_MISC,
 			   my_handler, sc, &amp;(sc->handler));
     if (error) {
 	printf("Couldn't set up irq\n");
 	goto fail4;
     }
 
     sc->irq_bt = rman_get_bustag(sc->irqres);
     sc->irq_bh = rman_get_bushandle(sc->irqres);
 </programlisting>
 
     </sect2>
 
     <sect2>
       <title>DMA</title>
       <para>On the PC, peripherals that want to do bus-mastering DMA
       must deal with physical addresses.  This is a problem since
       FreeBSD uses virtual memory and deals almost exclusively with
       virtual addresses.  Fortunately, there is a function,
       <function>vtophys()</function> to help.</para>
 
 <programlisting>#include &lt;vm/vm.h&gt;
 #include &lt;vm/pmap.h&gt;
 
 #define vtophys(virtual_address) (...)
 </programlisting>
 
       <para>The solution is a bit different on the alpha however, and
         what we really want is a function called
         <function>vtobus()</function>.</para>
 
 <programlisting>#if defined(__alpha__)
 #define vtobus(va)      alpha_XXX_dmamap((vm_offset_t)va)
 #else
 #define vtobus(va)      vtophys(va)
 #endif
 </programlisting>
 
     </sect2>
 
     <sect2>
       <title>Deallocating Resources</title>
 
       <para>It is very important to deallocate all of the resources
         that were allocated during <function>attach()</function>.
         Care must be taken to deallocate the correct stuff even on a
         failure condition so that the system will remain usable while
         your driver dies.</para>
 
     </sect2>
   </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 fa00f66106..bfbb5e6bfb 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$
 -->
 
 <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>
+  <sect1 id="scsi-synopsis">
     <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 <quote>recommended</quote>.</para>
 
    <para>The document is illustrated with examples in
      pseudo-code. Although sometimes the examples have many details
      and look like real code, it is 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>
+  <sect1 id="scsi-general">
     <title>General architecture</title>
 
     <para>CAM stands for Common Access Method. It is 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 do not describe
       here.</para>
 
     <para>This is achieved in multiple steps: first it is 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 is 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 <quote>ncr</quote> or <quote>wds</quote>.</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 <quote>wds0</quote> 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 <quote>path</quote>. 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 is 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 <quote>all devices</quote>)</para></listitem>
 
       <listitem><para>SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means
         <quote>all LUNs</quote>)</para></listitem>
     </itemizedlist>
 
     <para>If the driver can not allocate this path it will not 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 is 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 <quote>CAM Control Block</quote>. 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
       (<quote>normal</quote>) 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 is 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 <quote>bitwise or</quote> 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_release_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 <quote>struct ccb_scsiio csio</quote> 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 - do not 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 ca not 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 is OK to return the CCB with
         the status CAM_REQ_INVALID, the current drivers do that.  But
         it is 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 do not 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 is 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 is 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 is 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 <quote>BUS
     DEVICE RESET</quote> 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 <quote>struct
       ccb_abort cab</quote> 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 is 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 do not 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 is 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 <quote>struct ccb_trans_setting cts</quote> 
 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 is 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 <quote>new current
       settings</quote> 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 <quote>current</quote> 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 <quote>struct
       ccb_trans_setting cts</quote> 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 <quote>struct
       ccb_calc_geometry ccg</quote> 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 <quote>extended translation</quote> 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 <quote>struct
 ccb_pathinq cpi</quote> 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>
+  <sect1 id="scsi-polling">
     <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>
+  <sect1 id="scsi-async">
     <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>
+  <sect1 id="scsi-interrupts">
     <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
       <quote>typical</quote> 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 will not
       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>
+  <sect1 id="scsi-errors">
     <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 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> -
         <quote>impossible</quote> 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>
+  <sect1 id="scsi-timeout">
     <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 is 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/arch-handbook/sound/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.sgml
index 38f39f1e78..9ece7bbd03 100644
--- a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.sgml
@@ -1,687 +1,687 @@
 <!--
      The FreeBSD Documentation Project
 
     $FreeBSD$
 -->
 
 <chapter id="oss">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Jean-Francois</firstname>
 	<surname>Dockes</surname>
 	<contrib>Contributed by </contrib>
       </author>
     </authorgroup>
     <!-- 23 November 2001 -->
   </chapterinfo>
 
   <title>Sound subsystem</title>
   
-  <sect1>
+  <sect1 id="oss-intro">
     <title>Introduction</title>
     
     <para>The FreeBSD sound subsystem cleanly separates generic sound
       handling issues from device-specific ones.  This makes it easier
       to add support for new hardware.</para>
 
     <para>The &man.pcm.4; framework is the central piece of the sound
       subsystem.  It mainly implements the following elements:</para>
 
     <itemizedlist>
       <listitem>
         <para>A system call interface (read, write, ioctls) to
           digitized sound and mixer functions.  The ioctl command set
           is compatible with the legacy <emphasis>OSS</emphasis> or
           <emphasis>Voxware</emphasis> interface, allowing common
           multimedia applications to be ported without
           modification.</para>
       <listitem>
         <para>Common code for processing sound data (format
           conversions, virtual channels).</para>
       </listitem>
       <listitem>
         <para>A uniform software interface to hardware-specific audio
           interface modules.</para>
       </listitem>
       <listitem>
         <para>Additional support for some common hardware interfaces
           (ac97), or shared hardware-specific code (ex: ISA DMA
           routines).</para> 
       </listitem>
     </itemizedlist>
 
     <para>The support for specific sound cards is implemented by
       hardware-specific drivers, which provide channel and mixer interfaces
       to plug into the generic <devicename>pcm</devicename> code.</para>
 
     <para>In this chapter, the term <devicename>pcm</devicename> will
       refer to the central, common part of the sound driver, as
       opposed to the hardware-specific modules.</para>
 
     <para>The prospective driver writer will of course want to start
       from an existing module and use the code as the ultimate
       reference.  But, while the sound code is nice and clean, it is
       also mostly devoid of comments.  This document tries to give an
       overview of the framework interface and answer some questions
       that may arise while adapting the existing code.</para>
 
     <para>As an alternative, or in addition to starting from a working
       example, you can find a commented driver template at
       <ulink url="http://people.freebsd.org/~cg/template.c">
        http://people.freebsd.org/~cg/template.c</ulink></para>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="oss-files">
     <title>Files</title>
 
     <para>All the relevant code currently (FreeBSD 4.4) lives in
       <filename>/usr/src/sys/dev/sound/</filename>, except for the
       public ioctl interface definitions, found in
       <filename>/usr/src/sys/sys/soundcard.h</filename></para>
 
     <para>Under <filename>/usr/src/sys/dev/sound/</filename>, the
       <filename>pcm/</filename> directory holds the central code,
       while the <filename>isa/</filename> and
       <filename>pci/</filename> directories have the drivers for ISA
       and PCI boards.</para>
 
   </sect1>
 
   <sect1 id="pcm-probe-and-attach">
     <title>Probing, attaching, etc.</title>
 
     <para>Sound drivers probe and attach in almost the same way as any
       hardware driver module.  You might want to look at the <link
       linkend="isa-driver"> ISA</link> or <link
       linkend="pci">PCI</link> specific sections of the handbook for
       more information.</para>
       
     <para>However, sound drivers differ in some ways:</para>
 
     <itemizedlist>
 
       <listitem>
         <para>They declare themselves as <devicename>pcm</devicename>
           class devices, with a <structname>struct
           snddev_info</structname> device private structure:</para>
 
           <programlisting>          static driver_t xxx_driver = {
               "pcm",
               xxx_methods,
               sizeof(struct snddev_info)
           };
 
           DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0);
           MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER);</programlisting>
 
         <para>Most sound drivers need to store additional private
           information about their device.  A private data structure is
           usually allocated in the attach routine.  Its address is
           passed to <devicename>pcm</devicename> by the calls to
           <function>pcm_register()</function> and
           <function>mixer_init()</function>.
           <devicename>pcm</devicename> later passes back this address
           as a parameter in calls to the sound driver
           interfaces.</para>
       </listitem>
 
       <listitem>
         <para>The sound driver attach routine should declare its MIXER
           or AC97 interface to <devicename>pcm</devicename> by calling
           <function>mixer_init()</function>.  For a MIXER interface,
           this causes in turn a call to <link linkend="xxxmixer-init">
           <function>xxxmixer_init()</function></link>.</para>
       </listitem>
 
       <listitem>
         <para>The sound driver attach routine declares its general
           CHANNEL configuration to <devicename>pcm</devicename> by
           calling <function>pcm_register(dev, sc, nplay,
           nrec)</function>, where <varname>sc</varname> is the address
           for the device data structure, used in further calls from
           <devicename>pcm</devicename>, and <varname>nplay</varname>
           and <varname>nrec</varname> are the number of play and
           record channels.</para>
       </listitem>
 
       <listitem>
         <para>The sound driver attach routine declares each of its
           channel objects by calls to
           <function>pcm_addchan()</function>.  This sets up the
           channel glue in <devicename>pcm</devicename> and causes in
           turn a call to
             <link linkend="xxxchannel-init">
             <function>xxxchannel_init()</function></link>.</para>
       </listitem>
 
       <listitem>
         <para>The sound driver detach routine should call
         <function>pcm_unregister()</function> before releasing its
         resources.</para>
       </listitem>
     </itemizedlist>
       
     <para>There are two possible methods to handle non-PnP devices:</para>
     <itemizedlist>
       <listitem>
         <para>Use a <function>device_identify()</function> method
           (example: <filename>sound/isa/es1888.c</filename>).  The
           <function>device_identify()</function> method probes for the
           hardware at known addresses and, if it finds a supported
           device, creates a new pcm device which is then passed to
           probe/attach.</para>
       </listitem>
       <listitem>
         <para>Use a custom kernel configuration with appropriate hints
           for pcm devices (example:
           <filename>sound/isa/mss.c</filename>).</para>
       </listitem>
     </itemizedlist>
 
     <para><devicename>pcm</devicename> drivers should implement
     <function>device_suspend</function>,
     <function>device_resume</function> and
     <function>device_shutdown</function> routines, so that power
     management and module unloading function correctly.</para>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="oss-interfaces">
     <title>Interfaces</title>
 
     <para>The interface between the <devicename>pcm</devicename> core
       and the sound drivers is defined in terms of <link
       linkend="kernel-objects">kernel objects</link>.</para>
 
     <para>There are two main interfaces that a sound driver will
       usually provide: <emphasis>CHANNEL</emphasis> and either
       <emphasis>MIXER</emphasis> or <emphasis>AC97</emphasis>.</para>
       
     <para>The <emphasis>AC97</emphasis> interface is a very small
       hardware access (register read/write) interface, implemented by
       drivers for hardware with an AC97 codec.  In this case, the
       actual MIXER interface is provided by the shared AC97 code in
       <devicename>pcm</devicename>.</para>
 
     <sect2>
       <title>The CHANNEL interface</title>
 
       <sect3>
         <title>Common notes for function parameters</title>
 
         <para>Sound drivers usually have a private data structure to
           describe their device, and one structure for each play and
           record data channel that it supports.</para>
 
         <para>For all CHANNEL interface functions, the first parameter
           is an opaque pointer.</para>
 
         <para>The second parameter is a pointer to the private
           channel data structure, except for
           <function>channel_init()</function> which has a pointer to the
           private device structure (and returns the channel pointer
           for further use by <devicename>pcm</devicename>).</para>
 
       </sect3>
 
       <sect3>
         <title>Overview of data transfer operations</title>
 
         <para>For sound data transfers, the
           <devicename>pcm</devicename> core and the sound drivers
           communicate through a shared memory area, described by a
           <structname>struct snd_dbuf</structname>.</para>
 
         <para><structname>struct snd_dbuf</structname> is private to
           <devicename>pcm</devicename>, and sound drivers obtain
           values of interest by calls to accessor functions
           (<function>sndbuf_getxxx()</function>).</para>
 
         <para>The shared memory area has a size of
           <function>sndbuf_getsize()</function> and is divided into
           fixed size blocks of <function>sndbuf_getblksz()</function>
           bytes.</para>
           
         <para>When playing, the general transfer mechanism is as
           follows (reverse the idea for recording):</para>
 
         <itemizedlist>
           <listitem>
             <para><devicename>pcm</devicename> initially fills up the
               buffer, then calls the sound driver's <link
               linkend="channel-trigger">
               <function>xxxchannel_trigger()</function></link>
               function with a parameter of PCMTRIG_START.</para>
           </listitem>
 
           <listitem>
             <para>The sound driver then arranges to repeatedly
               transfer the whole memory area
               (<function>sndbuf_getbuf()</function>,
               <function>sndbuf_getsize()</function>) to the device, in
               blocks of <function>sndbuf_getblksz()</function> bytes.
               It calls back the <function>chn_intr()</function>
               <devicename>pcm</devicename> function for each
               transferred block (this will typically happen at
               interrupt time).</para>
           </listitem>
 
           <listitem>
             <para><function>chn_intr()</function> arranges to copy new
               data to the area that was transferred to the device (now
               free), and make appropriate updates to the
               <structname>snd_dbuf</structname> structure.</para>
           </listitem>
 
         </itemizedlist>
 
       <sect3 id="xxxchannel-init">
         <title>channel_init</title>
 
         <para><function>xxxchannel_init()</function> is called to
           initialize each of the play or record channels.  The calls
           are initiated from the sound driver attach routine.  (See
           the <link linkend="pcm-probe-and-attach">probe and attach
           section</link>).</para>
           
           <programlisting>          static void *
           xxxchannel_init(kobj_t obj, void *data, 
              struct snd_dbuf *b, struct pcm_channel *c, int dir)<co id="co-chinit-params">
           {
               struct xxx_info *sc = data;
               struct xxx_chinfo *ch;
                ...
               return ch;<co id="co-chinit-return">
            }</programlisting>
 
         <calloutlist>
 
           <callout arearefs="co-chinit-params">
             <para><varname>b</varname> is the address for the channel
               <structname>struct snd_dbuf</structname>.  It should be
               initialized in the function by calling
               <function>sndbuf_alloc()</function>.  The buffer size to
               use is normally a small multiple of the 'typical' unit
               transfer size for your device.</para>
 
             <para><varname>c</varname> is the
               <devicename>pcm</devicename> channel control structure
               pointer.  This is an opaque object.  The function should
               store it in the local channel structure, to be used in
               later calls to <devicename>pcm</devicename> (ie:
               <function>chn_intr(c)</function>).</para>
 
             <para><varname>dir</varname> indicates the channel
               direction (<literal>PCMDIR_PLAY</literal> or
               <literal>PCMDIR_REC</literal>).</para>
           </callout>
 
           <callout arearefs="co-chinit-return">
             <para>The function should return a pointer to the private
               area used to control this channel.  This will be passed
               as a parameter to other channel interface calls.</para>
           </callout>
 
         </calloutlist>
 
       </sect3>
 
       <sect3>
         <title>channel_setformat</title>
 
         <para><function>xxxchannel_setformat()</function> should set
           up the hardware for the specified channel for the specified
           sound format.</para>
           
           <programlisting>          static int
           xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format)<co id="co-chsetformat-params">
           {
               struct xxx_chinfo *ch = data;
                ...
               return 0;
            }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-chsetformat-params">
             <para><varname>format</varname> is specified as an
               <literal>AFMT_XXX value</literal>
               (<filename>soundcard.h</filename>).</para>
           </callout>
 
         </calloutlist>
       </sect3>
 
       <sect3>
         <title>channel_setspeed</title>
 
         <para><function>xxxchannel_setspeed()</function> sets up the
           channel hardware for the specified sampling speed, and
           returns the possibly adjusted speed.</para>
 
         <programlisting>          static int
           xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed)
           {
               struct xxx_chinfo *ch = data;
                ...
               return speed;
            }</programlisting>
 
       </sect3>
 
       <sect3>
         <title>channel_setblocksize</title>
 
         <para><function>xxxchannel_setblocksize()</function> sets the
           block size, which is the size of unit transactions between
           <devicename>pcm</devicename> and the sound driver, and
           between the sound driver and the device.  Typically, this
           would be the number of bytes transferred before an interrupt
           occurs.  During a transfer, the sound driver should call
           <devicename>pcm</devicename>'s
           <function>chn_intr()</function> every time this size has
           been transferred.</para>
 
         <para>Most sound drivers only take note of the block size
           here, to be used when an actual transfer will be
           started.</para>
           
         <programlisting>          static int
           xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize)
           {
               struct xxx_chinfo *ch = data;
                 ...
               return blocksize;<co id="co-chsetblocksize-return">
            }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-chsetblocksize-return">
             <para>The function returns the possibly adjusted block
               size.  In case the block size is indeed changed,
               <function>sndbuf_resize()</function> should be called to
               adjust the buffer.</para> 
 
           </callout>
         </calloutlist>
 
       </sect3>
 
       <sect3 id="channel-trigger">
         <title>channel_trigger</title>
 
         <para><function>xxxchannel_trigger()</function> is called by
           <devicename>pcm</devicename> to control data transfer
           operations in the driver.</para> 
           
         <programlisting>          static int
           xxxchannel_trigger(kobj_t obj, void *data, int go)<co id="co-chtrigger-params">
           {
               struct xxx_chinfo *ch = data;
                ...
               return 0;
            }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-chtrigger-params">
             <para><varname>go</varname> defines the action for the
               current call.  The possible values are:</para>
               <itemizedlist>
 
               <listitem>
                 <para><literal>PCMTRIG_START</literal>: the driver
                   should start a data transfer from or to the channel
                   buffer.  If needed, the buffer base and size can be
                   retrieved through
                   <function>sndbuf_getbuf()</function> and
                   <function>sndbuf_getsize()</function>.</para>
               </listitem>
 
               <listitem>
                 <para><literal>PCMTRIG_EMLDMAWR</literal> /
                   <literal>PCMTRIG_EMLDMARD</literal>: this tells the
                   driver that the input or output buffer may have been
                   updated.  Most drivers just ignore these
                   calls.</para>
               </listitem>
 
               <listitem>
                 <para><literal>PCMTRIG_STOP</literal> /
                   <literal>PCMTRIG_ABORT</literal>: the driver should
                   stop the current transfer.</para>
               </listitem>
             </itemizedlist>
 
           </callout> 
         </calloutlist>
 
         <note><para>If the driver uses ISA DMA,
           <function>sndbuf_isadma()</function> should be called before
           performing actions on the device, and will take care of the
           DMA chip side of things.</para>
           </note>
 
       </sect3>
 
       <sect3>
         <title>channel_getptr</title>
 
         <para><function>xxxchannel_getptr()</function> returns the
           current offset in the transfer buffer.  This will typically
           be called by <function>chn_intr()</function>, and this is how
           <devicename>pcm</devicename> knows where it can transfer
           new data.</para>
           
       </sect3>
 
       <sect3>
         <title>channel_free</title>
 
         <para><function>xxxchannel_free()</function> is called to free
           up channel resources, for example when the driver is
           unloaded, and should be implemented if the channel data
           structures are dynamically allocated or if
           <function>sndbuf_alloc()</function> was not used for buffer
           allocation.</para> 
 
       </sect3>
 
       <sect3>
         <title>channel_getcaps</title>
 
         <programlisting>          struct pcmchan_caps *
           xxxchannel_getcaps(kobj_t obj, void *data)
           {
               return &amp;xxx_caps;<co id="co-chgetcaps-return">
            }</programlisting>
 
         <calloutlist>
 
           <callout arearefs="co-chgetcaps-return">
             <para>The routine returns a pointer to a (usually
               statically-defined) <structname>pcmchan_caps</structname>
               structure (defined in
               <filename>sound/pcm/channel.h</filename>.  The structure holds
               the minimum and maximum sampling frequencies, and the
               accepted sound formats.  Look at any sound driver for an
               example.</para>
           </callout>
 
         </calloutlist>
 
       </sect3>
 
       <sect3>
         <title>More functions</title>
 
         <para><function>channel_reset()</function>,
           <function>channel_resetdone()</function>, and
           <function>channel_notify()</function> are for special purposes
           and should not be implemented in a driver without discussing
           it with the authorities (&a.cg;).</para>
 
         <para><function>channel_setdir()</function> is deprecated.</para>
       </sect3>
 
     </sect2>
 
     <sect2>
       <title>The MIXER interface</title>
         
       <sect3 id="xxxmixer-init">
         <title>mixer_init</title>
 
         <para><function>xxxmixer_init()</function> initializes the
           hardware and tells <devicename>pcm</devicename> what mixer
           devices are available for playing and recording</para>
 
         <programlisting>          static int
           xxxmixer_init(struct snd_mixer *m)
           {
               struct xxx_info   *sc = mix_getdevinfo(m);
               u_int32_t v;
 
               [Initialize hardware]
 
               [Set appropriate bits in v for play mixers]<co id="co-mxini-sd">
               mix_setdevs(m, v);
               [Set appropriate bits in v for record mixers]
               mix_setrecdevs(m, v)
 
               return 0;              
           }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-mxini-sd">
             <para>Set bits in an integer value and call
               <function>mix_setdevs()</function> and
               <function>mix_setrecdevs()</function> to tell
               <devicename>pcm</devicename> what devices exist.</para>
           </callout>
         </calloutlist>
 
         <para>Mixer bits definitions can be found in
           <filename>soundcard.h</filename>
           (<literal>SOUND_MASK_XXX</literal> values and
           <literal>SOUND_MIXER_XXX</literal> bit shifts).</para>
 
       </sect3>
 
       <sect3>
         <title>mixer_set</title>
 
         <para><function>xxxmixer_set()</function> sets the volume
           level for one mixer device.</para>
 
         <programlisting>          static int
           xxxmixer_set(struct snd_mixer *m, unsigned dev, 
                            unsigned left, unsigned right)<co id="co-mxset-params">
           {
               struct sc_info *sc = mix_getdevinfo(m);
               [set volume level]
               return left | (right << 8);<co id="co-mxset-return">
           }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-mxset-params">
             <para>The device is specified as a SOUND_MIXER_XXX
               value</para> <para>The volume values are specified in
               range [0-100].  A value of zero should mute the
               device.</para>
           </callout>
 
           <callout arearefs="co-mxset-return">
             <para>As the hardware levels probably won't match the
               input scale, and some rounding will occur, the routine
               returns the actual level values (in range 0-100) as
               shown.</para>
           </callout>
         </calloutlist>
 
       </sect3>
 
       <sect3>
         <title>mixer_setrecsrc</title>
 
         <para><function>xxxmixer_setrecsrc()</function> sets the
           recording source device.</para>
           
         <programlisting>          static int
           xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src)<co id="co-mxsr-params">
           {
               struct xxx_info *sc = mix_getdevinfo(m);
 
               [look for non zero bit(s) in src, set up hardware]
 
               [update src to reflect actual action]
               return src;<co id="co-mxsr-return">
            }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-mxsr-params">
             <para>The desired recording devices are specified as a
               bit field</para>
           </callout>
 
           <callout arearefs="co-mxsr-return">
             <para>The actual devices set for recording are returned.
               Some drivers can only set one device for recording.  The
               function should return -1 if an error occurs.</para>
           </callout>
         </calloutlist>
       </sect3>
 
       <sect3>
         <title>mixer_uninit, mixer_reinit</title>
 
         <para><function>xxxmixer_uninit()</function> should ensure
           that all sound is muted and if possible mixer hardware
           should be powered down </para>
 
         <para><function>xxxmixer_reinit()</function> should ensure
           that the mixer hardware is powered up and any settings not
           controlled by <function>mixer_set()</function> or
           <function>mixer_setrecsrc()</function> are restored.</para> 
 
       </sect3>
     </sect2>
 
     <sect2>
       <title>The AC97 interface</title>
 
       <para>The <emphasis>AC97</emphasis> interface is implemented
         by drivers with an AC97 codec.  It only has three methods:</para>
 
       <itemizedlist>
 
         <listitem><para><function>xxxac97_init()</function> returns
           the number of ac97 codecs found.</para>
         </listitem>
 
         <listitem><para><function>ac97_read()</function> and
           <function>ac97_write()</function> read or write a specified
           register.</para>
         </listitem>
 
       </itemizedlist>
 
       <para>The <emphasis>AC97</emphasis> interface is used by the
         AC97 code in <devicename>pcm</devicename> to perform higher
         level operations.  Look at
         <filename>sound/pci/maestro3.c</filename> or many others under
         <filename>sound/pci/</filename> for an example.</para>
 
     </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml
index 1b8a0b4cdb..083d21c8b4 100644
--- a/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.sgml
@@ -1,161 +1,161 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="sysinit">
   <title>The Sysinit Framework</title>
 
   <para>Sysinit is the framework for a generic call sort and dispatch
     mechanism. FreeBSD currently uses it for the dynamic
     initialization of the kernel. Sysinit allows FreeBSD's kernel
     subsystems to be reordered, and added, removed, and replaced at
     kernel link time when the kernel or one of its modules is loaded
     without having to edit a statically ordered initialization routing
     and recompile the kernel. This system also allows kernel modules,
     currently called <firstterm>KLD's</firstterm>, to be separately
     compiled, linked, and initialized at boot time and loaded even
     later while the system is already running. This is accomplished
     using the <quote>kernel linker</quote> and <quote>linker
     sets</quote>.</para>
 
-  <sect1>
+  <sect1 id="sysinit-term">
     <title>Terminology</title>
 
     <variablelist>
       <varlistentry>
         <term>Linker Set</term>
         <listitem>
           <para>A linker technique in which the linker gathers
             statically declared data throughout a program's source files
             into a single contiguously addressable unit of
             data.</para>
         </listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
-  <sect1>
+  <sect1 id="sysinit-operation">
     <title>Sysinit Operation</title>
 
     <para>Sysinit relies on the ability of the linker to take static
       data declared at multiple locations throughout a program's
       source and group it together as a single contiguous chunk of
       data. This linker technique is called a <quote>linker
       set</quote>. Sysinit uses two linker sets to maintain two data
       sets containing each consumer's call order, function, and a
       pointer to the data to pass to that function.</para>
 
     <para>Sysinit uses two priorities when ordering the functions for
       execution.  The first priority is a subsystem ID giving an
       overall order Sysinit's dispatch of functions. Current predeclared
       ID's are in <filename>&lt;sys/kernel.h></filename> in the enum
       list <literal>sysinit_sub_id</literal>. The second priority used
       is an element order within the subsystem. Current predeclared
       subsystem element orders are in
       <filename>&lt;sys/kernel.h></filename> in the enum list
       <literal>sysinit_elem_order</literal>.</para>
 
     <para>There are currently two uses for Sysinit. Function dispatch
       at system startup and kernel module loads, and function dispatch
       at system shutdown and kernel module unload.</para>
   </sect1>
 
 
-  <sect1>
+  <sect1 id="sysinit-using">
     <title>Using Sysinit</title>
 
     <sect2>
       <title>Interface</title>
 
       <sect3>
         <title>Headers</title>
 
           <programlisting>&lt;sys/kernel.h></programlisting>
       </sect3>
 
       <sect3>
         <title>Macros</title>
 
         <programlisting>SYSINIT(uniquifier, subsystem, order, func, ident)
         SYSUNINIT(uniquifier, subsystem, order, func, ident)</programlisting>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Startup</title>
 
       <para>The <literal>SYSINIT()</literal> macro creates the
         necessary sysinit data in Sysinit's startup data set for
         Sysinit to sort and dispatch a function at system startup and
         module load.  <literal>SYSINIT()</literal> takes a uniquifier
         that Sysinit uses identify the particular function dispatch
         data, the subsystem order, the subsystem element order, the
         function to call, and the data to pass the function. All
         functions must take a constant pointer argument.
         </para>
 
       <para>For example:</para>
 
       <programlisting>#include &lt;sys/kernel.h>
 
 void foo_null(void *unused)
 {
         foo_doo();
 }
 SYSINIT(foo_null, SI_SUB_FOO, SI_ORDER_FOO, NULL);
 
 struct foo foo_voodoo = {
         FOO_VOODOO;
 }
 
 void foo_arg(void *vdata)
 {
         struct foo *foo = (struct foo *)vdata;
         foo_data(foo);
 }
 SYSINIT(foo_arg, SI_SUB_FOO, SI_ORDER_FOO, foo_voodoo);
       </programlisting>
     </sect2>
 
     <sect2>
       <title>Shutdown</title>
 
       <para>The <literal>SYSUNINIT()</literal> macro behaves similarly
         to the <literal>SYSINIT()</literal> macro except that it adds
         the Sysinit data to Sysinit's shutdown data set.</para>
 
       <para>For example:</para>
 
       <programlisting>#include &lt;sys/kernel.h>
 
 void foo_cleanup(void *unused)
 {
         foo_kill();
 }
 SYSUNINIT(foo_cleanup, SI_SUB_FOO, SI_ORDER_FOO, NULL);
 
 struct foo_stack foo_stack = {
         FOO_STACK_VOODOO;
 }
 
 void foo_flush(void *vdata)
 {
 }
 SYSUNINIT(foo_flush, SI_SUB_FOO, SI_ORDER_FOO, foo_stack);
       </programlisting>
     </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/arch-handbook/usb/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/usb/chapter.sgml
index 3a483a1cf7..847666a67b 100644
--- a/en_US.ISO8859-1/books/arch-handbook/usb/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/usb/chapter.sgml
@@ -1,623 +1,623 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="usb">
   <title>USB Devices</title>
 
   <para><emphasis>This chapter was written by &a.nhibma;.  Modifications made for
     the handbook by &a.murray;.</emphasis></para>
 
-  <sect1>
+  <sect1 id="usb-intro">
     <title>Introduction</title>
 
     <para>The Universal Serial Bus (USB) is a new way of attaching
       devices to personal computers. The bus architecture features
       two-way communication and has been developed as a response to
       devices becoming smarter and requiring more interaction with the
       host.  USB support is included in all current PC chipsets and is
       therefore available in all recently built PCs.  Apple's
       introduction of the USB-only iMac has been a major incentive for
       hardware manufacturers to produce USB versions of their devices.
       The future PC specifications specify that all legacy connectors
       on PCs should be replaced by one or more USB connectors,
       providing generic plug and play capabilities.  Support for USB
       hardware was available at a very early stage in NetBSD and was
       developed by Lennart Augustsson for the NetBSD project.  The
       code has been ported to FreeBSD and we are currently maintaining
       a shared code base.  For the implementation of the USB subsystem
       a number of features of USB are important.</para>
 
     <para><emphasis>Lennart Augustsson has done most of the implementation of
       the USB support for the NetBSD project. Many thanks for this
       incredible amount of work. Many thanks also to Ardy and Dirk for
       their comments and proofreading of this paper.</emphasis></para>
 
     <itemizedlist>
 
       <listitem><para>Devices connect to ports on the computer
         directly or on devices called hubs, forming a treelike device
         structure.</para></listitem>
 
       <listitem><para>The devices can be connected and disconnected at
         run time.</para></listitem>
 
       <listitem><para>Devices can suspend themselves and trigger
         resumes of the host system</para></listitem>
 
       <listitem><para>As the devices can be powered from the bus, the
         host software has to keep track of power budgets for each
         hub.</para></listitem>
 
       <listitem><para>Different quality of service requirements by the
         different device types together with the maximum of 126
         devices that can be connected to the same bus, require proper
         scheduling of transfers on the shared bus to take full
         advantage of the 12Mbps bandwidth available. (over 400Mbps
         with USB 2.0)</para></listitem>
 
       <listitem><para>Devices are intelligent and contain easily
         accessible information about themselves</para></listitem>
 
     </itemizedlist>
 
     <para>The development of drivers for the USB subsystem and devices
       connected to it is supported by the specifications that have
       been developed and will be developed. These specifications are
       publicly available from the USB home pages.  Apple has been very
       strong in pushing for standards based drivers, by making drivers
       for the generic classes available in their operating system
       MacOS and discouraging the use of separate drivers for each new
       device.  This chapter tries to collate essential information for a
       basic understanding of the present implementation of the USB
       stack in FreeBSD/NetBSD.  It is recommended however to read it
       together with the relevant specifications mentioned in the
       references below.</para>
     
     <sect2>
       <title>Structure of the USB Stack</title>
 
       <para>The USB support in FreeBSD can be split into three
         layers. The lowest layer contains the host controller driver,
         providing a generic interface to the hardware and its scheduling
         facilities.  It supports initialisation of the hardware,
         scheduling of transfers and handling of completed and/or failed
         transfers.  Each host controller driver implements a virtual hub
         providing hardware independent access to the registers
         controlling the root ports on the back of the machine.</para>
 
       <para>The middle layer handles the device connection and
         disconnection, basic initialisation of the device, driver
         selection, the communication channels (pipes) and does
         resource management.  This services layer also controls the
         default pipes and the device requests transferred over
         them.</para>
   
       <para>The top layer contains the individual drivers supporting
         specific (classes of) devices. These drivers implement the
         protocol that is used over the pipes other than the default
         pipe. They also implement additional functionality to make the
         device available to other parts of the kernel or userland. They
         use the USB driver interface (USBDI) exposed by the services
         layer.</para>
     </sect2>
   </sect1>
 
   <sect1 id="usb-hc">
     <title>Host Controllers</title>
 
     <para>The host controller (HC) controls the transmission of
       packets on the bus. Frames of 1 millisecond are used. At the
       start of each frame the host controller generates a Start of
       Frame (SOF) packet.</para>
 
     <para>The SOF packet is used to synchronise to the start of the
       frame and to keep track of the frame number. Within each frame
       packets are transferred, either from host to device (out) or
       from device to host (in). Transfers are always initiated by the
       host (polled transfers). Therefore there can only be one host
       per USB bus. Each transfer of a packet has a status stage in
       which the recipient of the data can return either ACK
       (acknowledge reception), NAK (retry), STALL (error condition) or
       nothing (garbled data stage, device not available or
       disconnected). Section 8.5 of the <ulink
       url="http://www.usb.org/developers/docs.html">USB
       specification</ulink> explains the details of packets in more
       detail. Four different types of transfers can occur on a USB
       bus: control, bulk, interrupt and isochronous.  The types of
       transfers and their characteristics are described below (`Pipes'
       subsection).</para>
 
     <para>Large transfers between the device on the USB bus and the
       device driver are split up into multiple packets by the host
       controller or the HC driver.</para>
 
     <para>Device requests (control transfers) to the default endpoints
       are special. They consist of two or three phases: SETUP, DATA
       (optional) and STATUS. The set-up packet is sent to the
       device. If there is a data phase, the direction of the data
       packet(s) is given in the set-up packet. The direction in the
       status phase is the opposite of the direction during the data
       phase, or IN if there was no data phase. The host controller
       hardware also provides registers with the current status of the
       root ports and the changes that have occurred since the last
       reset of the status change register. Access to these registers
       is provided through a virtualised hub as suggested in the USB
       specification [ 2]. The virtual hub must comply with the hub
       device class given in chapter 11 of that specification. It must
       provide a default pipe through which device requests can be sent
       to it. It returns the standard andhub class specific set of
       descriptors. It should also provide an interrupt pipe that
       reports changes happening at its ports. There are currently two
       specifications for host controllers available: <ulink
       url="http://developer.intel.com/design/USB/UHCI11D.htm">Universal
       Host Controller Interface</ulink> (UHCI; Intel) and <ulink
       url="http://www.compaq.com/productinfo/development/openhci.html">Open
       Host Controller Interface</ulink> (OHCI; Compaq, Microsoft,
       National Semiconductor). The UHCI specification has been
       designed to reduce hardware complexity by requiring the host
       controller driver to supply a complete schedule of the transfers
       for each frame. OHCI type controllers are much more independent
       by providing a more abstract interface doing alot of work
       themselves. </para>
 
     <sect2>
       <title>UHCI</title>
 
       <para>The UHCI host controller maintains a framelist with 1024
         pointers to per frame data structures. It understands two
         different data types: transfer descriptors (TD) and queue
         heads (QH). Each TD represents a packet to be communicated to
         or from a device endpoint. QHs are a means to groupTDs (and
         QHs) together.</para>
 
       <para>Each transfer consists of one or more packets. The UHCI
         driver splits large transfers into multiple packets. For every
         transfer, apart from isochronous transfers, a QH is
         allocated. For every type of transfer these QHs are collected
         at a QH for that type. Isochronous transfers have to be
         executed first because of the fixed latency requirement and
         are directly referred to by the pointer in the framelist. The
         last isochronous TD refers to the QH for interrupt transfers
         for that frame. All QHs for interrupt transfers point at the
         QH for control transfers, which in turn points at the QH for
         bulk transfers. The following diagram gives a graphical
         overview of this:</para>
 
       <para>This results in the following schedule being run in each
         frame. After fetching the pointer for the current frame from
         the framelist the controller first executes the TDs for all
         the isochronous packets in that frame. The last of these TDs
         refers to the QH for the interrupt transfers for
         thatframe. The host controller will then descend from that QH
         to the QHs for the individual interrupt transfers. After
         finishing that queue, the QH for the interrupt transfers will
         refer the controller to the QH for all control transfers. It
         will execute all the subqueues scheduled there, followed by
         all the transfers queued at the bulk QH. To facilitate the
         handling of finished or failed transfers different types of
         interrupts are generated by the hardware at the end of each
         frame. In the last TD for a transfer the Interrupt-On
         Completion bit is set by the HC driver to flag an interrupt
         when the transfer has completed. An error interrupt is flagged
         if a TD reaches its maximum error count. If the short packet
         detect bit is set in a TD and less than the set packet length
         is transferred this interrupt is flagged to notify
         the controller driver of the completed transfer. It is the host
         controller driver's task to find out which transfer has
         completed or produced an error. When called the interrupt
         service routine will locate all the finished transfers and
         call their callbacks.</para>
 
       <para>See for a more elaborate description the <ulink
         url="http://developer.intel.com/design/USB/UHCI11D.htm">UHCI
         specification.</ulink></para>
 
     </sect2>
 
     <sect2>
       <title>OHCI</title>
       
       <para>Programming an OHCI host controller is much simpler. The
         controller assumes that a set of endpoints is available, and
         is aware of scheduling priorities and the ordering of the
         types of transfers in a frame. The main data structure used by
         the host controller is the endpoint descriptor (ED) to which
         aqueue of transfer descriptors (TDs) is attached. The ED
         contains the maximum packet size allowed for an endpoint and
         the controller hardware does the splitting into packets. The
         pointers to the data buffers are updated after each transfer
         and when the start and end pointer are equal, the TD is
         retired to the done-queue. The four types of endpoints have
         their own queues. Control and bulk endpoints are queued each at
         their own queue. Interrupt EDs are queued in a tree, with the
         level in the tree defining the frequency at which they
         run.</para>
 
       <para>framelist interruptisochronous control bulk</para>
 
       <para>The schedule being run by the host controller in each
         frame looks as follows. The controller will first run the
         non-periodic control and bulk queues, up to a time limit set
         by the HC driver. Then the interrupt transfers for that frame
         number are run, by using the lower five bits of the frame
         number as an index into level 0 of the tree of interrupts
         EDs. At the end of this tree the isochronous EDs are connected
         and these are traversed subsequently. The isochronous TDs
         contain the frame number of the first frame the transfer
         should be run in. After all the periodic transfers have been
         run, the control and bulk queues are traversed
         again. Periodically the interrupt service routine is called to
         process the done queue and call the callbacks for each
         transfer and reschedule interrupt and isochronous
         endpoints.</para>
 
       <para>See for a more elaborate description the <ulink
         url="http://www.compaq.com/productinfo/development/openhci.html">
         OHCI specification</ulink>. Services layer The middle layer
         provides access to the device in a controlled way and
         maintains resources in use by the different drivers and the
         services layer. The layer takes care of the following
         aspects:</para>
 
       <itemizedlist>
         <listitem><para>The device configuration
           information</para></listitem>
 	<listitem><para>The pipes to communicate with a
 	  device</para></listitem>
 	<listitem><para>Probing and attaching and detaching form a
   	  device.</para></listitem>
       </itemizedlist>
 
     </sect2>
   </sect1>
 
   <sect1 id="usb-dev">
     <title>USB Device Information</title>
 
     <sect2>
       <title>Device configuration information</title>
 
       <para>Each device provides different levels of configuration
         information. Each device has one or more configurations, of
         which one is selected during probe/attach. A configuration
         provides power and bandwidth requirements. Within each
         configuration there can be multiple interfaces. A device
         interface is a collection of endpoints. For example USB
         speakers can have an interface for the audio data (Audio
         Class) and an interface for the knobs, dials and buttons (HID
         Class). All interfaces in a configuration are active at the
         same time and can be attached to by different drivers. Each
         interface can have alternates, providing different quality of
         service parameters. In for example cameras this is used to
         provide different frame sizes and numbers of frames per
         second.</para>
 
       <para>Within each interface 0 or more endpoints can be
         specified. Endpoints are the unidirectional access points for
         communicating with a device. They provide buffers to
         temporarily store incoming or outgoing data from the
         device. Each endpoint has a unique address within
         a configuration, the endpoint's number plus its direction. The
         default endpoint, endpoint 0, is not part of any interface and
         available in all configurations. It is managed by the services
         layer and not directly available to device drivers.</para>
 
       <para>Level 0 Level 1 Level 2 Slot 0</para>
       <para>Slot 3 Slot 2 Slot 1</para>
       <para>(Only 4 out of 32 slots shown)</para>
 
       <para>This hierarchical configuration information is described
         in the device by a standard set of descriptors (see section 9.6
         of the USB specification [ 2]). They can be requested through
         the Get Descriptor Request. The services layer caches these
         descriptors to avoid unnecessary transfers on the USB
         bus. Access to the descriptors is provided through function
         calls.</para>
 
       <itemizedlist>
         <listitem><para>Device descriptors: General information about
           the device, like Vendor, Product and Revision Id, supported
           device class, subclass and protocol if applicable, maximum
           packet size for the default endpoint, etc.</para></listitem>
 
 	<listitem><para>Configuration descriptors: The number of
    	  interfaces in this configuration, suspend and resume
    	  functionality supported and power
    	  requirements.</para></listitem>
 
 	<listitem><para>Interface descriptors: interface class,
   	  subclass and protocol if applicable, number of alternate
   	  settings for the interface and the number of
   	  endpoints.</para></listitem>
 
 	<listitem><para>Endpoint descriptors: Endpoint address,
 	  direction and type, maximum packet size supported and
 	  polling frequency if type is interrupt endpoint. There is no
 	  descriptor for the default endpoint (endpoint 0) and it is
 	  never counted in an interface descriptor.</para></listitem>
 
 	<listitem><para>String descriptors: In the other descriptors
   	  string indices are supplied for some fields.These can be
   	  used to retrieve descriptive strings, possibly in multiple
   	  languages.</para></listitem>
 
       </itemizedlist>
 
       <para>Class specifications can add their own descriptor types
         that are available through the GetDescriptor Request.</para>
 
       <para>Pipes Communication to end points on a device flows
         through so-called pipes. Drivers submit transfers to endpoints
         to a pipe and provide a callback to be called on completion or
         failure of the transfer (asynchronous transfers) or wait for
         completion (synchronous transfer). Transfers to an endpoint
         are serialised in the pipe. A transfer can either complete,
         fail or time-out (if a time-out has been set). There are two
         types of time-outs for transfers. Time-outs can happen due to
         time-out on the USBbus (milliseconds). These time-outs are
         seen as failures and can be due to disconnection of the
         device. A second form of time-out is implemented in software
         and is triggered when a transfer does not complete within a
         specified amount of time (seconds). These are caused by a
         device acknowledging negatively (NAK) the transferred
         packets. The cause for this is the device not being ready to
         receive data, buffer under- or overrun or protocol
         errors.</para>
 
       <para>If a transfer over a pipe is larger than the maximum
         packet size specified in the associated endpoint descriptor,
         the host controller (OHCI) or the HC driver (UHCI) will split
         the transfer into packets of maximum packet size, with the
         last packet possibly smaller than the maximum
         packet size.</para>
 
       <para>Sometimes it is not a problem for a device to return less
         data than requested. For example abulk-in-transfer to a modem
         might request 200 bytes of data, but the modem has only 5
         bytes available at that time. The driver can set the short
         packet (SPD) flag. It allows the host controller to accept a
         packet even if the amount of data transferred is less than
         requested. This flag is only valid for in-transfers, as the
         amount of data to be sent to a device is always known
         beforehand. If an unrecoverable error occurs in a device
         during a transfer the pipe is stalled. Before any more data is
         accepted or sent the driver needs to resolve the cause of the
         stall and clear the endpoint stall condition through send the
         clear endpoint halt device request over the default
         pipe. The default endpoint should never stall.</para>
 
       <para>There are four different types of endpoints and
         corresponding pipes: - Control pipe / default pipe: There is
         one control pipe per device, connected to the default endpoint
         (endpoint 0). The pipe carries the device requests and
         associated data. The difference between transfers over the
         default pipe and other pipes is that the protocol for
         the transfers is described in the USB specification [ 2]. These
         requests are used to reset and configure the device. A basic
         set of commands that must be supported by each device is
         provided in chapter 9 of the USB specification [ 2]. The
         commands supported on this pipe can be extended by a device
         class specification to support additional
         functionality.</para>
 
       <itemizedlist>
         <listitem><para>Bulk pipe: This is the USB equivalent to a raw
           transmission medium.</para></listitem>
         <listitem><para>Interrupt pipe: The host sends a request for
           data to the device and if the device has nothing to send, it
           will NAK the data packet. Interrupt transfers are scheduled
           at a frequency specified when creating the
           pipe.</para></listitem>
 
 	<listitem><para>Isochronous pipe: These pipes are intended for
 	    isochronous data, for example video or audio streams, with
 	fixed latency, but no guaranteed delivery. Some support for
 	pipes of this type is available in the current
 	implementation. Packets in control, bulk and interrupt
 	transfers are retried if an error occurs during transmission
 	or the device acknowledges the packet negatively (NAK) due to
 	for example lack of buffer space to store the incoming
 	data. Isochronous packets are however not retried in case of
 	failed delivery or NAK of a packet as this might violate the
 	timing constraints.</para></listitem>
       </itemizedlist>
 
       <para>The availability of the necessary bandwidth is calculated
         during the creation of the pipe. Transfers are scheduled within
         frames of 1 millisecond. The bandwidth allocation within a
         frame is prescribed by the USB specification, section 5.6 [
         2]. Isochronous and interrupt transfers are allowed to consume
         up to 90% of the bandwidth within a frame. Packets for control
         and bulk transfers are scheduled after all isochronous and
         interrupt packets and will consume all the remaining
         bandwidth.</para>
 
       <para>More information on scheduling of transfers and bandwidth
         reclamation can be found in chapter 5of the USB specification
         [ 2], section 1.3 of the UHCI specification [ 3] and section
         3.4.2 of the OHCI specification [4].</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="usb-devprobe">
     <title>Device probe and attach</title>
 
     <para>After the notification by the hub that a new device has been
       connected, the service layer switches on the port, providing the
       device with 100 mA of current. At this point the device is in
       its default state and listening to device address 0. The
       services layer will proceed to retrieve the various descriptors
       through the default pipe. After that it will send a Set Address
       request to move the device away from the default device address
       (address 0). Multiple device drivers might be able to support
       the device. For example a modem driver might be able to support
       an ISDN TA through the AT compatibility interface. A driver for
       that specific model of the ISDN adapter might however be able to
       provide much better support for this device. To support this
       flexibility, the probes return priorities indicating their level
       of support. Support for a specific revision of a product ranks
       the highest and the generic driver the lowest priority. It might
       also be that multiple drivers could attach to one device if
       there are multiple interfaces within one configuration. Each
       driver only needs to support a subset of the interfaces.</para>
 
     <para>The probing for a driver for a newly attached device checks
       first for device specific drivers. If not found, the probe code
       iterates over all supported configurations until a driver
       attaches in a configuration. To support devices with multiple
       drivers on different interfaces, the probe iterates over all
       interfaces in a configuration that have not yet been claimed by
       a driver. Configurations that exceed the power budget for the
       hub are ignored. During attach the driver should initialise the
       device to its proper state, but not reset it, as this will make
       the device disconnect itself from the bus and restart the
       probing process for it. To avoid consuming unnecessary bandwidth
       should not claim the interrupt pipe at attach time, but
       should postpone allocating the pipe until the file is opened and
       the data is actually used. When the file is closed the pipe
       should be closed again, even though the device might still be
       attached.</para>
 
     <sect2>
       <title>Device disconnect and detach</title>
 
       <para>A device driver should expect to receive errors during any
         transaction with the device. The design of USB supports and
         encourages the disconnection of devices at any point in
         time. Drivers should make sure that they do the right thing
         when the device disappears.</para>
 
       <para>Furthermore a device that has been disconnected and
         reconnected will not be reattached at the same device
         instance. This might change in the future when more devices
         support serial numbers (see the device descriptor) or other
         means of defining an identity for a device have been
         developed.</para>
 
       <para>The disconnection of a device is signaled by a hub in the
         interrupt packet delivered to the hub driver. The status
         change information indicates which port has seen a connection
         change. The device detach method for all device drivers for
         the device connected on that port are called and the structures
         cleaned up. If the port status indicates that in the mean time
         a device has been connected to that port, the procedure for
         probing and attaching the device will be started. A device
         reset will produce a disconnect-connect sequence on the hub
         and will be handled as described above.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="usb-protocol">
     <title>USB Drivers Protocol Information</title>
 
     <para>The protocol used over pipes other than the default pipe is
       undefined by the USB specification.  Information on this can be
       found from various sources. The most accurate source is the
       developer's section on the USB home pages [ 1]. From these pages
       a growing number of deviceclass specifications are
       available. These specifications specify what a compliant device
       should look like from a driver perspective, basic functionality
       it needs to provide and the protocol that is to be used over the
       communication channels.  The USB specification [ 2] includes the
       description of the Hub Class. A class specification for Human
       Interface Devices (HID) has been created to cater for keyboards,
       tablets, bar-code readers, buttons, knobs, switches, etc. A
       third example is the class specification for mass storage
       devices. For a full list of device classes see the developers
       section on the USB home pages [ 1].</para>
 
     <para>For many devices the protocol information has not yet been
       published however. Information on the protocol being used might
       be available from the company making the device. Some companies
       will require you to sign a Non -Disclosure Agreement (NDA)
       before giving you the specifications. This in most cases
       precludes making the driver open source.</para>
 
     <para>Another good source of information is the Linux driver
       sources, as a number of companies have started to provide drivers
       for Linux for their devices. It is always a good idea to contact
       the authors of those drivers for their source of
       information.</para>
 
     <para>Example: Human Interface Devices The specification for the
       Human Interface Devices like keyboards, mice, tablets, buttons,
       dials,etc. is referred to in other device class specifications
       and is used in many devices.</para>
 
     <para>For example audio speakers provide endpoints to the digital
       to analogue converters and possibly an extra pipe for a
       microphone. They also provide a HID endpoint in a separate
       interface for the buttons and dials on the front of the
       device. The same is true for the monitor control class. It is
       straightforward to build support for these interfaces through
       the available kernel and userland libraries together with the
       HID class driver or the generic driver. Another device that
       serves as an example for interfaces within one configuration
       driven by different device drivers is a cheap keyboard with
       built-in legacy mouse port. To avoid having the cost of
       including the hardware for a USB hub in the device,
       manufacturers combined the mouse data received from the PS/2 port
       on the back of the keyboard and the key presses from the keyboard
       into two separate interfaces in the same configuration. The
       mouse and keyboard drivers each attach to the appropriate
       interface and allocate the pipes to the two independent
       endpoints.</para>
 
     <para>Example: Firmware download Many devices that have been
       developed are based on a general purpose processor with
       an additional USB core added to it. Because the development of
       drivers and firmware for USB devices is still very new, many
       devices require the downloading of the firmware after they
       have been connected.</para>
 
     <para>The procedure followed is straightforward. The device
       identifies itself through a vendor and product Id. The first
       driver probes and attaches to it and downloads the firmware into
       it. After that the device soft resets itself and the driver is
       detached. After a short pause the device announces its presence
       on the bus. The device will have changed its
       vendor/product/revision Id to reflect the fact that it has been
       supplied with firmware and as a consequence a second driver will
       probe it and attach to it.</para>
 
     <para>An example of these types of devices is the ActiveWire I/O
       board, based on the EZ-USB chip. For this chip a generic firmware
       downloader is available. The firmware downloaded into the
       ActiveWire board changes the revision Id. It will then perform a
       soft reset of the USB part of the EZ-USB chip to disconnect from
       the USB bus and again reconnect.</para>
 
     <para>Example: Mass Storage Devices Support for mass storage
       devices is mainly built around existing protocols. The Iomega
       USB Zipdrive is based on the SCSI version of their drive. The
       SCSI commands and status messages are wrapped in blocks and
       transferred over the bulk pipes to and from the device,
       emulating a SCSI controller over the USB wire. ATAPI and UFI
       commands are supported in a similar fashion.</para>
 
     <para>The Mass Storage Specification supports 2 different types of
       wrapping of the command block.The initial attempt was based on
       sending the command and status through the default pipe and
       using bulk transfers for the data to be moved between the host
       and the device. Based on experience a second approach was
       designed that was based on wrapping the command and status
       blocks and sending them over the bulk out and in endpoint. The
       specification specifies exactly what has to happen when and what
       has to be done in case an error condition is encountered. The
       biggest challenge when writing drivers for these devices is to
       fit USB based protocol into the existing support for mass storage
       devices. CAM provides hooks to do this in a fairly straight
       forward way. ATAPI is less simple as historically the IDE
       interface has never had many different appearances.</para>
 
     <para>The support for the USB floppy from Y-E Data is again less
       straightforward as a new command set has been designed.</para>
 
   </sect1>
 
 </chapter>
diff --git a/en_US.ISO8859-1/books/arch-handbook/vm/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/vm/chapter.sgml
index da0fc92672..2b78f50828 100644
--- a/en_US.ISO8859-1/books/arch-handbook/vm/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/vm/chapter.sgml
@@ -1,260 +1,260 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="vm">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Matthew</firstname>
 	<surname>Dillon</surname>
 	<contrib>Contributed by </contrib>
       </author>
     </authorgroup>
     <!-- 6 Feb 1999 -->
   </chapterinfo>
 
   <title>Virtual Memory System</title>
 
-    <sect1>
+    <sect1 id="vm-physmem">
       <title>Management of physical
 	memory&mdash;<literal>vm_page_t</literal></title>
       
       <para>Physical memory is managed on a page-by-page basis through the
 	<literal>vm_page_t</literal> structure.  Pages of physical memory are
 	categorized through the placement of their respective
 	<literal>vm_page_t</literal> structures on one of several paging
 	queues.</para>
 
       <para>A page can be in a wired, active, inactive, cache, or free state.
 	Except for the wired state, the page is typically placed in a doubly
 	link list queue representing the state that it is in.  Wired pages
 	are not placed on any queue.</para>
 
       <para>FreeBSD implements a more involved paging queue for cached and
 	free pages in order to implement page coloring.  Each of these states
 	involves multiple queues arranged according to the size of the
 	processor's L1 and L2 caches.  When a new page needs to be allocated,
 	FreeBSD attempts to obtain one that is reasonably well aligned from
 	the point of view of the L1 and L2 caches relative to the VM object
 	the page is being allocated for.</para>
 
       <para>Additionally, a page may be held with a reference count or locked
 	with a busy count.  The VM system also implements an <quote>ultimate
 	locked</quote> state for a page using the PG_BUSY bit in the page's
 	flags.</para>
 
       <para>In general terms, each of the paging queues operates in a LRU
 	fashion.  A page is typically placed in a wired or active state
 	initially.  When wired, the page is usually associated with a page
 	table somewhere.  The VM system ages the page by scanning pages in a
 	more active paging queue (LRU) in order to move them to a less-active
 	paging queue.  Pages that get moved into the cache are still
 	associated with a VM object but are candidates for immediate reuse.
 	Pages in the free queue are truly free.  FreeBSD attempts to minimize
 	the number of pages in the free queue, but a certain minimum number of
 	truly free pages must be maintained in order to accommodate page
 	allocation at interrupt time.</para>
 
       <para>If a process attempts to access a page that does not exist in its
 	page table but does exist in one of the paging queues (such as the
 	inactive or cache queues), a relatively inexpensive page reactivation
 	fault occurs which causes the page to be reactivated. If the page
 	does not exist in system memory at all, the process must block while
 	the page is brought in from disk.</para>
 
       <para>FreeBSD dynamically tunes its paging queues and attempts to
 	maintain reasonable ratios of pages in the various queues as well as
 	attempts to maintain a reasonable breakdown of clean vs. dirty pages.
 	The amount of rebalancing that occurs depends on the system's memory
 	load.  This rebalancing is implemented by the pageout daemon and
 	involves laundering dirty pages (syncing them with their backing
 	store), noticing when pages are activity referenced (resetting their
 	position in the LRU queues or moving them between queues), migrating
 	pages between queues when the queues are out of balance, and so forth.
 	FreeBSD's VM system is willing to take a reasonable number of
 	reactivation page faults to determine how active or how idle a page
 	actually is.  This leads to better decisions being made as to when to
 	launder or swap-out a page.</para>
     </sect1>
     
-    <sect1>
+    <sect1 id="vm-cache">
       <title>The unified buffer
 	cache&mdash;<literal>vm_object_t</literal></title>
 	  
       <para>FreeBSD implements the idea of a generic <quote>VM object</quote>.
 	VM objects can be associated with backing store of various
 	types&mdash;unbacked, swap-backed, physical device-backed, or
 	file-backed storage.  Since the filesystem uses the same VM objects to
 	manage in-core data relating to files, the result is a unified buffer
 	cache.</para>
 
       <para>VM objects can be <emphasis>shadowed</emphasis>.  That is, they
 	can be stacked on top of each other.  For example, you might have a
 	swap-backed VM object stacked on top of a file-backed VM object in
 	order to implement a MAP_PRIVATE mmap()ing.  This stacking is also
 	used to implement various sharing properties, including
 	copy-on-write, for forked address spaces.</para>
 
       <para>It should be noted that a <literal>vm_page_t</literal> can only be
 	associated with one VM object at a time.  The VM object shadowing
 	implements the  perceived sharing of the same page across multiple
 	instances.</para>
     </sect1>
     
-    <sect1>
+    <sect1 id="vm-fileio">
       <title>Filesystem I/O&mdash;<literal>struct buf</literal></title>
       
       <para>vnode-backed VM objects, such as file-backed objects, generally
 	need to maintain their own clean/dirty info independent from the VM
 	system's idea of clean/dirty.  For example, when the VM system decides
 	to  synchronize a physical page to its backing store, the VM system
 	needs to mark the page clean before the page is actually written to
 	its backing store.  Additionally, filesystems need to be able to map
 	portions of a file or file metadata into KVM in order to operate on
 	it.</para>
 
       <para>The entities used to manage this are known as filesystem buffers,
 	<literal>struct buf</literal>'s, or
 	<literal>bp</literal>'s.  When a filesystem needs to operate on a
 	portion of a VM object, it typically maps part of the object into a
 	struct buf and the maps the pages in the struct buf into KVM.  In the
 	same manner, disk I/O is typically issued by mapping portions of
 	objects into buffer structures and  then issuing the I/O on the buffer
 	structures.  The underlying  vm_page_t's are typically busied for the
 	duration of the I/O.  Filesystem buffers also have their own notion of
 	being busy, which is useful to filesystem driver code which would
 	rather operate on filesystem buffers instead of hard VM pages.</para>
 
       <para>FreeBSD reserves a limited amount of KVM to hold mappings from
 	struct bufs, but it should be made clear that this KVM is used solely
 	to hold mappings and does not limit the ability to cache data.
 	Physical data caching is strictly a function of
 	<literal>vm_page_t</literal>'s, not filesystem buffers.  However,
 	since filesystem buffers are used to placehold I/O, they do inherently
 	limit the amount of concurrent I/O possible.  However, as there are usually a
 	few thousand filesystem buffers available, this is not usually a
 	problem.</para>
     </sect1>
     
-    <sect1>
+    <sect1 id="vm-pagetables">
       <title>Mapping Page Tables&mdash;<literal>vm_map_t, vm_entry_t</literal></title>
       
       <para>FreeBSD separates the physical page table topology from the VM
 	system.  All hard per-process page tables can be reconstructed on  the
 	fly and are usually considered throwaway.  Special page tables such as
 	those managing KVM are typically permanently preallocated. These page
 	tables are not throwaway.</para>
 
       <para>FreeBSD associates portions of vm_objects with address ranges in
 	virtual memory through <literal>vm_map_t</literal> and
 	<literal>vm_entry_t</literal> structures.  Page tables are directly
 	synthesized from the
 	<literal>vm_map_t</literal>/<literal>vm_entry_t</literal>/
 	<literal>vm_object_t</literal> hierarchy.  Recall that I mentioned
 	that physical pages  are only directly associated with a
 	<literal>vm_object</literal>; that is not quite true.
 	<literal>vm_page_t</literal>'s are also linked into page tables that
 	they are actively associated with.  One <literal>vm_page_t</literal>
 	can be linked into  several <emphasis>pmaps</emphasis>, as page tables
 	are called.  However, the hierarchical association holds, so all
 	references to the same page in the same object reference the same
 	<literal>vm_page_t</literal> and thus give us buffer cache unification
 	across the board.</para>
     </sect1>
       
-    <sect1>
+    <sect1 id="vm-kvm">
       <title>KVM Memory Mapping</title>
       
       <para>FreeBSD uses KVM to hold various kernel structures.  The single
 	largest entity held in KVM is the filesystem buffer cache.  That is,
 	mappings relating to <literal>struct buf</literal> entities.</para>
 
       <para>Unlike Linux, FreeBSD does <emphasis>not</emphasis> map all of physical memory into
 	KVM.  This means that FreeBSD can handle memory configurations up to
 	4G on 32 bit platforms.  In fact, if the mmu were capable of it,
 	FreeBSD could theoretically handle memory configurations up to 8TB on
 	a 32 bit platform.  However, since most 32 bit platforms are only
 	capable of mapping 4GB of ram, this is a moot point.</para>
 
         <para>KVM is managed through several mechanisms.  The main mechanism
 	  used to manage KVM is the <emphasis>zone allocator</emphasis>.  The
 	  zone allocator takes a chunk of KVM and splits it up into
 	  constant-sized blocks of memory in order to allocate a specific type
 	  of structure.  You can use <command>vmstat -m</command> to get an
 	  overview of current KVM  utilization broken down by zone.</para>
     </sect1>
     
-    <sect1>
+    <sect1 id="vm-tuning">
       <title>Tuning the FreeBSD VM system</title>
       
       <para>A concerted effort has been made to make the FreeBSD kernel
 	dynamically tune itself.  Typically you do not need to mess with
 	anything beyond the <option>maxusers</option> and
 	<option>NMBCLUSTERS</option> kernel config options.  That is, kernel
 	compilation options specified in (typically)
 	<filename>/usr/src/sys/i386/conf/<replaceable>CONFIG_FILE</replaceable></filename>.
 	A description of all available kernel configuration options can be
 	found in <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
 
       <para>In a large system configuration you may wish to increase
 	<option>maxusers</option>.  Values typically range from 10 to 128.
 	Note that raising <option>maxusers</option> too high can cause the
 	system to overflow available KVM resulting in unpredictable operation.
 	It is better to leave <option>maxusers</option> at some reasonable number and add other
 	options, such as <option>NMBCLUSTERS</option>, to increase specific
 	resources.</para>
 
       <para>If your system is going to use the network heavily, you may want
 	to increase <option>NMBCLUSTERS</option>.  Typical values range from
 	1024 to 4096.</para>
 
       <para>The <literal>NBUF</literal> parameter is also traditionally used
 	to scale the system.  This parameter determines the amount of KVA the
 	system can use to map filesystem buffers for I/O.  Note that this
 	parameter has nothing whatsoever to do with the unified buffer cache!
 	This parameter is dynamically tuned in 3.0-CURRENT and later kernels
 	and should generally not be adjusted manually.  We recommend that you
 	<emphasis>not</emphasis> try to specify an <literal>NBUF</literal>
 	parameter.  Let the system pick it.  Too small a value can result in
 	extremely inefficient filesystem operation while too large a value can
 	starve the page queues by causing too many pages to become wired
 	down.</para>
 
       <para>By default, FreeBSD kernels are not optimized.  You can set
 	debugging and optimization flags with the
 	<literal>makeoptions</literal> directive in the kernel configuration.
 	Note that you should not use <option>-g</option> unless you can
 	accommodate the large (typically 7 MB+) kernels that result.</para>
 
       <programlisting>makeoptions      DEBUG="-g"
 makeoptions      COPTFLAGS="-O -pipe"</programlisting>
 
       <para>Sysctl provides a way to tune kernel parameters at run-time. You
 	typically do not need to mess with any of the sysctl variables,
 	especially the VM related ones.</para>
 
       <para>Run time VM and system tuning is relatively straightforward.
 	First, use Soft Updates on your UFS/FFS filesystems whenever possible.
 	<filename>/usr/src/sys/ufs/ffs/README.softupdates</filename> contains
 	instructions (and restrictions) on how to configure it.</para>
 
       <para>Second, configure  sufficient swap.  You should have a swap
 	partition configured on each physical disk, up to four, even on your
 	<quote>work</quote> disks.  You should have at least 2x the swap space
 	as you have main memory, and possibly even more if you do not have a
 	lot of memory.  You should also size your swap partition based on the
 	maximum memory configuration you ever intend to put on the machine so
 	you do not have to repartition your disks later on. If you want to be
 	able to accommodate a crash dump, your first swap partition must be at
 	least as large as main memory and <filename>/var/crash</filename> must
 	have sufficient free space to hold the dump.</para>
 
       <para>NFS-based swap is perfectly acceptable on 4.X or later systems,
 	but you must be aware that the NFS server will take the brunt of the
 	paging load.</para>
     </sect1>
 
 </chapter>
diff --git a/en_US.ISO8859-1/books/developers-handbook/boot/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/boot/chapter.sgml
index 4fbb435473..66e0b8e8aa 100644
--- a/en_US.ISO8859-1/books/developers-handbook/boot/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/boot/chapter.sgml
@@ -1,1023 +1,1023 @@
 <!--
 The FreeBSD Documentation Project
 
 Copyright (c) 2002 Sergey Lyubka <devnull@uptsoft.com>
 All rights reserved
 $FreeBSD$
 -->
 
 <chapter id="boot">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Sergey</firstname>
 	<surname>Lyubka</surname>
 	<contrib>Contributed by </contrib>
       </author> <!-- devnull@uptsoft.com  12 Jun 2002 -->
     </authorgroup>
   </chapterinfo>
   <title>Bootstrapping and kernel initialization</title>
 
-  <sect1>
+  <sect1 id="boot-synopsis">
     <title>Synopsis</title>
 
     <para>This chapter is an overview of the boot and system
       initialization process, starting from the BIOS (firmware) POST,
       to the first user process creation.  Since the initial steps of
       system startup are very architecture dependent, the IA-32
       architecture is used as an example.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-overview">
     <title>Overview</title>
 
     <para>A computer running FreeBSD can boot by several methods,
       although the most common method, booting from a harddisk where
       the OS is installed, will be discussed here.  The boot process
       is divided into several steps:</para>
 
     <itemizedlist>
       <listitem><para>BIOS POST</para></listitem>
       <listitem><para><literal>boot0</literal> stage</para></listitem>
       <listitem><para><literal>boot2</literal> stage</para></listitem>
       <listitem><para>loader stage</para></listitem>
       <listitem><para>kernel initialization</para></listitem>
     </itemizedlist>
 
     <para>The <literal>boot0</literal> and <literal>boot2</literal>
       stages are also referred to as <emphasis>bootstrap stages 1 and
       2</emphasis> in &man.boot.8; as the first steps in FreeBSD's
       3-stage bootstrapping procedure.  Various information is printed
       on the screen at each stage, so you may visually recognize them
       using the table that follows.  Please note that the actual data
       may differ from machine to machine:</para>
 
     <informaltable>
       <tgroup cols="2">
         <tbody>
           <row>
             <entry><para>may vary</para></entry>
 
 	    <entry><para>BIOS (firmware) messages</para></entry>
           </row>
 
           <row>
             <entry><para>
 <screen>F1    FreeBSD
 F2    BSD
 F5    Disk 2</screen>
             </para></entry>
 
 	    <entry><para><literal>boot0</literal></para></entry>
           </row>
 
           <row>
             <entry><para>
 <screen>>>FreeBSD/i386 BOOT
 Default: 1:ad(1,a)/boot/loader
 boot:</screen>
             </para></entry>
 
 	    <entry><para><literal>boot2</literal><footnote><para>This
 	      prompt will appear if the user presses a key just after
 	      selecting an OS to boot at the <literal>boot0</literal>
               stage.</para></footnote></para></entry>
           </row>
 
           <row>
             <entry><para>
 <screen>BTX loader 1.0 BTX version is 1.01
 BIOS drive A: is disk0
 BIOS drive C: is disk1
 BIOS 639kB/64512kB available memory
 FreeBSD/i386 bootstrap loader, Revision 0.8
 Console internal video/keyboard
 (jkh@bento.freebsd.org, Mon Nov 20 11:41:23 GMT 2000)
 /kernel text=0x1234 data=0x2345 syms=[0x4+0x3456]
 Hit [Enter] to boot immediately, or any other key for command prompt
 Booting [kernel] in 9 seconds..._</screen>
             </para></entry>
 
             <entry><para>loader</para></entry>
           </row>
 
           <row>
             <entry><para>
 	      <screen>Copyright (c) 1992-2002 The FreeBSD Project.
 Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
         The Regents of the University of California. All rights reserved.
 FreeBSD 4.6-RC #0: Sat May  4 22:49:02 GMT 2002
     devnull@kukas:/usr/obj/usr/src/sys/DEVNULL
 Timecounter "i8254"  frequency 1193182 Hz</screen></para></entry>
 
             <entry><para>kernel</para></entry>
           </row>
         </tbody>
       </tgroup>
     </informaltable>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-bios">
     <title>BIOS POST</title>
 
     <para>When the PC powers on, the processor's registers are set
       to some predefined values.  One of the registers is the
       <emphasis>instruction pointer</emphasis> register, and its value
       after a power on is well defined: it is a 32-bit value of
       0xffffff00.  The instruction pointer register points to code to
       be executed by the processor.  One of the registers is the
       <literal>cr1</literal> 32-bit control register, and its value
       just after the reboot is 0.  One of the cr1's bits, the bit PE
       (Protected Enabled) indicates whether the processor is running
       in protected or real mode.  Since at boot time this bit is
       cleared, the processor boots in real mode.  Real mode means,
       among other things, that linear and physical addresses are
       identical.</para>
 
     <para>The value of 0xffffff00 is slightly less then 4Gb, so unless
       the machine has 4Gb physical memory, it cannot point to a valid
       memory address.  The computer's hardware translates this address
       so that it points to a BIOS memory block.</para>
 
     <para>BIOS stands for <emphasis>Basic Input Output
       System</emphasis>, and it is a chip on the motherboard that has
       a relatively small amount of read-only memory (ROM).  This
       memory contains various low-level routines that are specific to
       the hardware supplied with the motherboard.  So, the processor
       will first jump to the address 0xffffff00, which really resides
       in the BIOS's memory.  Usually this address contains a jump
       instruction to the BIOS's POST routines.</para>
 
     <para>POST stands for <emphasis>Power On Self Test</emphasis>.
       This is a set of routines including the memory check, system bus
       check and other low-level stuff so that the CPU can initialize
       the computer properly.  The important step on this stage is
       determining the boot device.  All modern BIOS's allow the boot
       device to be set manually, so you can boot from a floppy,
       CD-ROM, harddisk etc.</para>
 
     <para>The very last thing in the POST is the <literal>INT
       0x19</literal> instruction.  That instruction reads 512 bytes
       from the first sector of boot device into the memory at address
       0x7c00.  The term <emphasis>first sector</emphasis> originates
       from harddrive architecture, where the magnetic plate is divided
       to a number of cylindrical tracks.  Tracks are numbered, and
       every track is divided by a number (usually 64) sectors.  Track
       number 0 is the outermost on the magnetic plate, and sector 1,
       the first sector (tracks, or, cylinders, are numbered starting
       from 0, but sectors - starting from 1), has a special meaning.
       It is also called Master Boot Record, or MBR.  The remaining
       sectors on the first track are never used <footnote><para>Some
       utilities such as &man.disklabel.8; may store the information in
       this area, mostly in the second
       sector.</para></footnote>.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-boot0">
     <title><literal>boot0</literal> stage</title>
 
     <para>Take a look at the file <filename>/boot/boot0</filename>.
       This is a small 512-byte file, and it is exactly what FreeBSD's
       installation procedure wrote to your harddisk's MBR if you chose
       the <quote>bootmanager</quote> option at installation time.</para>
 
     <para>As mentioned previously, the <literal>INT 0x19</literal>
       instruction loads an MBR, i.e. the <filename>boot0</filename>
       content, into the memory at address 0x7c00.  Taking a look at
       the file <filename>sys/boot/i386/boot0/boot0.s</filename> can
       give a guess at what is happening there - this is the boot
       manager, which is an awesome piece of code written by Robert
       Nordier.</para>
 
     <para>The MBR, or, <filename>boot0</filename>, has a special
       structure starting from offset 0x1be, called the
       <emphasis>partition table</emphasis>.  It has 4 records of 16
       bytes each, called <emphasis>partition records</emphasis>, which
       represent how the harddisk(s) are partitioned, or, in FreeBSD's
       terminology, sliced.  One byte of those 16 says whether a
       partition (slice) is bootable or not.  Exactly one record must
       have that flag set, otherwise <filename>boot0</filename>'s code
       will refuse to proceed.</para>
 
     <para>A partition record has the following fields:</para>
 
     <itemizedlist>
       <listitem>
         <para>the 1-byte filesystem type</para>
       </listitem>
 
       <listitem>
         <para>the 1-byte bootable flag</para>
       </listitem>
 
       <listitem>
         <para>the 6 byte descriptor in CHS format</para>
       </listitem>
 
       <listitem>
         <para>the 8 byte descriptor in LBA format</para>
       </listitem>
     </itemizedlist>
 
     <para>A partition record descriptor has the information about
       where exactly the partition resides on the drive.  Both
       descriptors, LBA and CHS, describe the same information, but in
       different ways: LBA (Logical Block Addressing) has the starting
       sector for the partition and the partition's length, while CHS
       (Cylinder Head Sector) has coordinates for the first and last
       sectors of the partition.</para>
 
     <para>The boot manager scans the partition table and prints the
       menu on the screen so the user can select what disk and what
       slice to boot.  By pressing an appropriate key,
       <filename>boot0</filename> performs the following
       actions:</para>
 
     <itemizedlist>
       <listitem>
 	<para>modifies the bootable flag for the selected partition to
 	  make it bootable, and clears the previous</para>
       </listitem>
 
       <listitem>
 	<para>saves itself to disk to remember what partition (slice)
 	  has been selected so to use it as the default on the next
 	  boot</para>
       </listitem>
 
       <listitem>
 	<para>loads the first sector of the selected partition (slice)
 	  into memory and jumps there</para>
       </listitem>
     </itemizedlist>
 
     <para>What kind of data should reside on the very first sector of
       a bootable partition (slice), in our case, a FreeBSD slice?  As
       you may have already guessed, it is
       <filename>boot2</filename>.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-boot2">
     <title><literal>boot2</literal> stage</title>
 
     <para>You might wonder, why <literal>boot2</literal> comes after
       <literal>boot0</literal>, and not boot1.  Actually, there is a
       512-byte file called <filename>boot1</filename> in the directory
       <filename>/boot</filename> as well.  It is used for booting from
       a floppy.  When booting from a floppy,
       <filename>boot1</filename> plays the same role as
       <filename>boot0</filename> for a harddisk: it locates
       <filename>boot2</filename> and runs it.</para>
 
     <para>You may have realized that a file
       <filename>/boot/mbr</filename> exists as well.  It is a
       simplified version of <filename>boot0</filename>.  The code in
       <filename>mbr</filename> does not provide a menu for the user,
       it just blindly boots the partition marked active.</para>
 
     <para>The code implementing <filename>boot2</filename> resides in
       <filename>sys/boot/i386/boot2/</filename>, and the executable
       itself is in <filename>/boot</filename>.  The files
       <filename>boot0</filename> and <filename>boot2</filename> that
       are in <filename>/boot</filename> are not used by the bootstrap,
       but by utilities such as <application>boot0cfg</application>.
       The actual position for <filename>boot0</filename> is in the
       MBR.  For <filename>boot2</filename> it is the beginning of a
       bootable FreeBSD slice.  These locations are not under the
       filesystem's control, so they are invisible to commands like
       <application>ls</application>.</para>
 
     <para>The main task for <literal>boot2</literal> is to load the
       file <filename>/boot/loader</filename>, which is the third stage
       in the bootstrapping procedure.  The code in
       <literal>boot2</literal> cannot use any services like
       <function>open()</function> and <function>read()</function>,
       since the kernel is not yet loaded.  It must scan the harddisk,
       knowing about the filesystem structure, find the file
       <filename>/boot/loader</filename>, read it into memory using a
       BIOS service, and then pass the execution to the loader's entry
       point.</para>
 
     <para>Besides that, <literal>boot2</literal> prompts for user
       input so the loader can be booted from different disk, unit,
       slice and partition.</para>
 
     <para>The <literal>boot2</literal> binary is created in special
       way:</para>
 
     <programlisting><filename>sys/boot/i386/boot2/Makefile</filename>
 boot2: boot2.ldr boot2.bin ${BTX}/btx/btx
 	btxld -v -E ${ORG2} -f bin -b ${BTX}/btx/btx -l boot2.ldr \
 		-o boot2.ld -P 1 boot2.bin</programlisting>
 
     <para>This Makefile snippet shows that &man.btxld.8; is used to
       link the binary.  BTX, which stands for BooT eXtender, is a
       piece of code that provides a protected mode environment for the
       program, called the client, that it is linked with.  So
       <literal>boot2</literal> is a BTX client, i.e. it uses the
       service provided by BTX.</para>
 
     <para>The <application>btxld</application> utility is the linker.
       It links two binaries together.  The difference between
       &man.btxld.8; and &man.ld.1; is that
       <application>ld</application> usually links object files into a
       shared object or executable, while
       <application>btxld</application> links an object file with the
       BTX, producing the binary file suitable to be put on the
       beginning of the partition for the system boot.</para>
 
     <para><literal>boot0</literal> passes the execution to BTX's entry
       point.  BTX then switches the processor to protected mode, and
       prepares a simple environment before calling the client.  This
       includes:</para>
 
     <itemizedlist>
       <listitem><para>virtual v86 mode.  That means, the BTX is a v86
         monitor.  Real mode instructions like posh, popf, cli, sti, if
         called by the client, will work.</para></listitem>
 
       <listitem><para>Interrupt Descriptor Table (IDT) is set up so
         all hardware interrupts are routed to the default BIOS's
         handlers, and interrupt 0x30 is set up to be the syscall
         gate.</para></listitem>
 
       <listitem><para>Two system calls: <function>exec</function> and
         <function>exit</function>, are defined:</para>
 
     <programlisting><filename>sys/boot/i386/btx/lib/btxsys.s:</filename>
 		.set INT_SYS,0x30		# Interrupt number
 #
 # System call: exit
 #
 __exit: 	xorl %eax,%eax			# BTX system
 		int $INT_SYS			#  call 0x0
 #
 # System call: exec
 #
 __exec: 	movl $0x1,%eax			# BTX system
 		int $INT_SYS			#  call 0x1</programlisting></listitem>
     </itemizedlist>
 
     <para>BTX creates a Global Descriptor Table (GDT):</para>
 
     <programlisting><filename>sys/boot/i386/btx/btx/btx.s:</filename>
 gdt:		.word 0x0,0x0,0x0,0x0		# Null entry
 		.word 0xffff,0x0,0x9a00,0xcf	# SEL_SCODE
 		.word 0xffff,0x0,0x9200,0xcf	# SEL_SDATA
 		.word 0xffff,0x0,0x9a00,0x0	# SEL_RCODE
 		.word 0xffff,0x0,0x9200,0x0	# SEL_RDATA
 		.word 0xffff,MEM_USR,0xfa00,0xcf# SEL_UCODE
 		.word 0xffff,MEM_USR,0xf200,0xcf# SEL_UDATA
 		.word _TSSLM,MEM_TSS,0x8900,0x0 # SEL_TSS</programlisting>
 
     <para>The client's code and data start from address MEM_USR
       (0xa000), and a selector (SEL_UCODE) points to the client's code
       segment.  The SEL_UCODE descriptor has Descriptor Privilege
       Level (DPL) 3, which is the lowest privilege level.  But the
       <literal>INT 0x30</literal> instruction handler resides in a
       segment pointed to by the SEL_SCODE (supervisor code) selector,
       as shown from the code that creates an IDT:</para>
 
   <programlisting>		mov $SEL_SCODE,%dh		# Segment selector
 init.2: 	shr %bx				# Handle this int?
 		jnc init.3			# No
 		mov %ax,(%di)			# Set handler offset
 		mov %dh,0x2(%di)		#  and selector
 		mov %dl,0x5(%di)		# Set P:DPL:type
 		add $0x4,%ax			# Next handler</programlisting>
 
     <para>So, when the client calls <function>__exec()</function>, the
       code will be executed with the highest privileges.  This allows
       the kernel to change the protected mode data structures, such as
       page tables, GDT, IDT, etc later, if needed.</para>
 
     <para><literal>boot2</literal> defines an important structure,
       <literal>struct bootinfo</literal>.  This structure is
       initialized by <literal>boot2</literal> and passed to the
       loader, and then further to the kernel.  Some nodes of this
       structures are set by <literal>boot2</literal>, the rest by the
       loader.  This structure, among other information, contains the
       kernel filename, BIOS harddisk geometry, BIOS drive number for
       boot device, physical memory available, <literal>envp</literal>
       pointer etc.  The definition for it is:</para>
 
     <programlisting><filename>/usr/include/machine/bootinfo.h</filename>
 struct bootinfo {
 	u_int32_t	bi_version;
 	u_int32_t	bi_kernelname;		/* represents a char * */
 	u_int32_t	bi_nfs_diskless;	/* struct nfs_diskless * */
 				/* End of fields that are always present. */
 #define	bi_endcommon	bi_n_bios_used
 	u_int32_t	bi_n_bios_used;
 	u_int32_t	bi_bios_geom[N_BIOS_GEOM];
 	u_int32_t	bi_size;
 	u_int8_t	bi_memsizes_valid;
 	u_int8_t	bi_bios_dev;		/* bootdev BIOS unit number */
 	u_int8_t	bi_pad[2];
 	u_int32_t	bi_basemem;
 	u_int32_t	bi_extmem;
 	u_int32_t	bi_symtab;		/* struct symtab * */
 	u_int32_t	bi_esymtab;		/* struct symtab * */
 				/* Items below only from advanced bootloader */
 	u_int32_t	bi_kernend;		/* end of kernel space */
 	u_int32_t	bi_envp;		/* environment */
 	u_int32_t	bi_modulep;		/* preloaded modules */
 };</programlisting>
 
   <para><literal>boot2</literal> enters into an infinite loop waiting
     for user input, then calls <function>load()</function>.  If the
     user does not press anything, the loop brakes by a timeout, so
     <function>load()</function> will load the default file
     (<filename>/boot/loader</filename>).  Functions <function>ino_t
     lookup(char *filename)</function> and <function>int xfsread(ino_t
     inode, void *buf, size_t nbyte)</function> are used to read the
     content of a file into memory.  <filename>/boot/loader</filename>
     is an ELF binary, but where the ELF header is prepended with
     a.out's <literal>struct exec</literal> structure.
     <function>load()</function> scans the loader's ELF header, loading
     the content of <filename>/boot/loader</filename> into memory, and
     passing the execution to the loader's entry:</para>
 
   <programlisting><filename>sys/boot/i386/boot2/boot2.c:</filename>
     __exec((caddr_t)addr, RB_BOOTINFO | (opts & RBX_MASK),
 	   MAKEBOOTDEV(dev_maj[dsk.type], 0, dsk.slice, dsk.unit, dsk.part),
 	   0, 0, 0, VTOP(&amp;bootinfo));</programlisting>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-loader">
     <title><application>loader</application> stage</title>
 
     <para><application>loader</application> is a BTX client as well.
       I will not describe it here in detail, there is a comprehensive
       manpage written by Mike Smith, &man.loader.8;.  The underlying
       mechanisms and BTX were discussed above.</para>
 
     <para>The main task for the loader is to boot the kernel.  When
       the kernel is loaded into memory, it is being called by the
       loader:</para>
 
   <programlisting><filename>sys/boot/common/boot.c:</filename>
     /* Call the exec handler from the loader matching the kernel */
     module_formats[km->m_loader]->l_exec(km);</programlisting>
   </sect1>
 
-  <sect1>
+  <sect1 id="boot-kernel">
     <title>Kernel initialization</title>
 
     <para>To where exactly is the execution passed by the loader,
       i.e. what is the kernel's actual entry point.  Let us take a
       look at the command that links the kernel:</para>
 
     <programlisting><filename>sys/conf/Makefile.i386:</filename>
 ld -elf -Bdynamic -T /usr/src/sys/conf/ldscript.i386  -export-dynamic \
 -dynamic-linker /red/herring -o kernel -X locore.o \
 &lt;lots of kernel .o files&gt;</programlisting>
 
     <para>A few interesting things can be seen in this line.  First,
       the kernel is an ELF dynamically linked binary, but the dynamic
       linker for kernel is <filename>/red/herring</filename>, which is
       definitely a bogus file.  Second, taking a look at the file
       <filename>sys/conf/ldscript.i386</filename> gives an idea about
       what <application>ld</application> options are used when
       compiling a kernel.  Reading through the first few lines, the
       string</para>
 
   <programlisting><filename>sys/conf/ldscript.i386:</filename>
 ENTRY(btext)</programlisting>
 
     <para>says that a kernel's entry point is the symbol `btext'.
       This symbol is defined in <filename>locore.s</filename>:</para>
 
   <programlisting><filename>sys/i386/i386/locore.s:</filename>
 	.text
 /**********************************************************************
  *
  * This is where the bootblocks start us, set the ball rolling...
  *
  */
 NON_GPROF_ENTRY(btext)</programlisting>
 
     <para>First what is done is the register EFLAGS is set to a
       predefined value of 0x00000002, and then all the segment
       registers are initialized:</para>
 
     <programlisting><filename>sys/i386/i386/locore.s</filename>
 /* Don't trust what the BIOS gives for eflags. */
 	pushl	$PSL_KERNEL
 	popfl
 
 /*
  * Don't trust what the BIOS gives for %fs and %gs.  Trust the bootstrap
  * to set %cs, %ds, %es and %ss.
  */
 	mov	%ds, %ax
 	mov	%ax, %fs
 	mov	%ax, %gs</programlisting>
 
     <para>btext calls the routines
       <function>recover_bootinfo()</function>,
       <function>identify_cpu()</function>,
       <function>create_pagetables()</function>, which are also defined
       in <filename>locore.s</filename>.  Here is a description of what
       they do:</para>
 
     <informaltable>
       <tgroup cols=2 align=left>
       <tbody>
         <row>
           <entry><function>recover_bootinfo</function></entry>
 
           <entry>This routine parses the parameters to the kernel
             passed from the bootstrap.  The kernel may have been
             booted in 3 ways: by the loader, described above, by the
             old disk boot blocks, and by the old diskless boot
             procedure.  This function determines the booting method,
             and stores the <literal>struct bootinfo</literal>
             structure into the kernel memory.</entry>
         </row>
 
         <row>
           <entry><function>identify_cpu</function></entry>
 
 	  <entry>This functions tries to find out what CPU it is
 	    running on, storing the value found in a variable
 	    <varname>_cpu</varname>.</entry>
         </row>
 
         <row>
           <entry><function>create_pagetables</function></entry>
 
 	  <entry>This function allocates and fills out a Page Table
 	    Directory at the top of the kernel memory area.</entry>
         </row>
       </tgroup>
     </informaltable>
 
     <para>The next steps are enabling VME, if the CPU supports
       it:</para>
 
     <programlisting>	testl	$CPUID_VME, R(_cpu_feature)
 	jz	1f
 	movl	%cr4, %eax
 	orl	$CR4_VME, %eax
 	movl	%eax, %cr4</programlisting>
 
     <para>Then, enabling paging:</para>
     <programlisting>/* Now enable paging */
 	movl	R(_IdlePTD), %eax
 	movl	%eax,%cr3			/* load ptd addr into mmu */
 	movl	%cr0,%eax			/* get control word */
 	orl	$CR0_PE|CR0_PG,%eax		/* enable paging */
 	movl	%eax,%cr0			/* and let's page NOW! */</programlisting>
 
     <para>The next three lines of code are because the paging was set,
       so the jump is needed to continue the execution in virtualized
       address space:</para>
 
     <programlisting>	pushl	$begin				/* jump to high virtualized address */
 	ret
 
 /* now running relocated at KERNBASE where the system is linked to run */
 begin:</programlisting>
 
     <para>The function <function>init386()</function> is called, with
       a pointer to the first free physical page, after that
       <function>mi_startup()</function>.  <function>init386</function>
       is an architecture dependent initialization function, and
       <function>mi_startup()</function> is an architecture independent
       one (the 'mi_' prefix stands for Machine Independent).  The
       kernel never returns from <function>mi_startup()</function>, and
       by calling it, the kernel finishes booting:</para>
 
     <programlisting><filename>sys/i386/i386/locore.s:</filename>
 	movl	physfree, %esi
 	pushl	%esi				/* value of first for init386(first) */
 	call	_init386			/* wire 386 chip for unix operation */
 	call	_mi_startup			/* autoconfiguration, mountroot etc */
 	hlt		/* never returns to here */</programlisting>
 
     <sect2>
       <title><function>init386()</function></title>
 
       <para><function>init386()</function> is defined in
         <filename>sys/i386/i386/machdep.c</filename> and performs
         low-level initialization, specific to the i386 chip.  The
         switch to protected mode was performed by the loader.  The
         loader has created the very first task, in which the kernel
         continues to operate.  Before running straight away to the
         code, I will enumerate the tasks the processor must complete
         to initialize protected mode execution:</para>
 
       <itemizedlist>
         <listitem>
 	  <para>Initialize the kernel tunable parameters, passed from
 	    the bootstrapping program.</para>
 	  </listitem>
 
         <listitem>
 	  <para>Prepare the GDT.</para>
 	</listitem>
 
         <listitem>
 	  <para>Prepare the IDT.</para>
 	</listitem>
 
         <listitem>
 	  <para>Initialize the system console.</para>
 	</listitem>
 
         <listitem>
 	  <para>Initialize the DDB, if it is compiled into
 	    kernel.</para>
 	</listitem>
 
         <listitem>
 	  <para>Initialize the TSS.</para>
 	</listitem>
 
         <listitem>
 	  <para>Prepare the LDT.</para>
 	</listitem>
 
         <listitem>
 	  <para>Setup proc0's pcb.</para>
 	</listitem>
       </itemizedlist>
 
       <para>What <function>init386()</function> first does is
         initialize the tunable parameters passed from bootstrap.  This
         is done by setting the environment pointer (envp) and calling
         <function>init_param1()</function>.  The envp pointer has been
         passed from loader in the <literal>bootinfo</literal>
         structure:</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
 		kern_envp = (caddr_t)bootinfo.bi_envp + KERNBASE;
 
 	/* Init basic tunables, hz etc */
 	init_param1();</programlisting>
 
       <para><function>init_param1()</function> is defined in
         <filename>sys/kern/subr_param.c</filename>.  That file has a
         number of sysctls, and two functions,
         <function>init_param1()</function> and
         <function>init_param2()</function>, that are called from
         <function>init386()</function>:</para>
 
       <programlisting><filename>sys/kern/subr_param.c</filename>
 	hz = HZ;
 	TUNABLE_INT_FETCH("kern.hz", &amp;hz);</programlisting>
 
       <para>TUNABLE_&lt;typename&gt;_FETCH is used to fetch the value
         from the environment:</para>
 
     <programlisting><filename>/usr/src/sys/sys/kernel.h</filename>
 #define	TUNABLE_INT_FETCH(path, var)	getenv_int((path), (var))
 </programlisting>
 
       <para>Sysctl <literal>kern.hz</literal> is the system clock tick.  Along with
         this, the following sysctls are set by
         <function>init_param1()</function>: <literal>kern.maxswzone,
         kern.maxbcache, kern.maxtsiz, kern.dfldsiz, kern.dflssiz,
         kern.maxssiz, kern.sgrowsiz</literal>.</para>
 
       <para>Then <function>init386()</function> prepares the Global
         Descriptors Table (GDT).  Every task on an x86 is running in
         its own virtual address space, and this space is addressed by
         a segment:offset pair.  Say, for instance, the current
         instruction to be executed by the processor lies at CS:EIP,
         then the linear virtual address for that instruction would be
         <quote>the virtual address of code segment CS</quote> + EIP.  For
         convenience, segments begin at virtual address 0 and end at a
         4Gb boundary.  Therefore, the instruction's linear virtual
         address for this example would just be the value of EIP.
         Segment registers such as CS, DS etc are the selectors,
         i.e. indexes, into GDT (to be more precise, an index is not a
         selector itself, but the INDEX field of a selector).
         FreeBSD's GDT holds descriptors for 15 selectors per
         CPU:</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
 union descriptor gdt[NGDT * MAXCPU];	/* global descriptor table */
 
 <filename>sys/i386/include/segments.h:</filename>
 /*
  * Entries in the Global Descriptor Table (GDT)
  */
 #define	GNULL_SEL	0	/* Null Descriptor */
 #define	GCODE_SEL	1	/* Kernel Code Descriptor */
 #define	GDATA_SEL	2	/* Kernel Data Descriptor */
 #define	GPRIV_SEL	3	/* SMP Per-Processor Private Data */
 #define	GPROC0_SEL	4	/* Task state process slot zero and up */
 #define	GLDT_SEL	5	/* LDT - eventually one per process */
 #define	GUSERLDT_SEL	6	/* User LDT */
 #define	GTGATE_SEL	7	/* Process task switch gate */
 #define	GBIOSLOWMEM_SEL	8	/* BIOS low memory access (must be entry 8) */
 #define	GPANIC_SEL	9	/* Task state to consider panic from */
 #define GBIOSCODE32_SEL	10	/* BIOS interface (32bit Code) */
 #define GBIOSCODE16_SEL	11	/* BIOS interface (16bit Code) */
 #define GBIOSDATA_SEL	12	/* BIOS interface (Data) */
 #define GBIOSUTIL_SEL	13	/* BIOS interface (Utility) */
 #define GBIOSARGS_SEL	14	/* BIOS interface (Arguments) */</programlisting>
 
       <para>Note that those #defines are not selectors themselves, but
         just a field INDEX of a selector, so they are exactly the
         indices of the GDT.  for example, an actual selector for the
         kernel code (GCODE_SEL) has the value 0x08.</para>
 
       <para>The next step is to initialize the Interrupt Descriptor
         Table (IDT).  This table is to be referenced by the processor
         when a software or hardware interrupt occurs.  For example, to
         make a system call, user application issues the <literal>INT
         0x80</literal> instruction.  This is a software interrupt, so
         the processor's hardware looks up a record with index 0x80 in
         the IDT.  This record points to the routine that handles this
         interrupt, in this particular case, this will be the kernel's
         syscall gate.  The IDT may have a maximum of 256 (0x100)
         records.  The kernel allocates NIDT records for the IDT, where
         NIDT is the maximum (256):</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
 static struct gate_descriptor idt0[NIDT];
 struct gate_descriptor *idt = &amp;idt0[0];	/* interrupt descriptor table */
 </programlisting>
 
       <para>For each interrupt, an appropriate handler is set.  The
         syscall gate for <literal>INT 0x80</literal> is set as
         well:</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
  	setidt(0x80, &amp;IDTVEC(int0x80_syscall),
 			SDT_SYS386TGT, SEL_UPL, GSEL(GCODE_SEL, SEL_KPL));</programlisting>
 
       <para>So when a userland application issues the <literal>INT
         0x80</literal> instruction, control will transfer to the
         function <function>_Xint0x80_syscall</function>, which is in
         the kernel code segment and will be executed with supervisor
         privileges.</para>
 
       <para>Console and DDB are then initialized:</para>
 
       <programlisting><filename>sys/i386/i386/machdep.c:</filename>
 	cninit();
 /* skipped */
 #ifdef DDB
 	kdb_init();
 	if (boothowto & RB_KDB)
 		Debugger("Boot flags requested debugger");
 #endif</programlisting>
 
       <para>The Task State Segment is another x86 protected mode
         structure, the TSS is used by the hardware to store task
         information when a task switch occurs.</para>
 
       <para>The Local Descriptors Table is used to reference userland
         code and data.  Several selectors are defined to point to the
         LDT, they are the system call gates and the user code and data
         selectors:</para>
 
       <programlisting><filename>/usr/include/machine/segments.h</filename>
 #define	LSYS5CALLS_SEL	0	/* forced by intel BCS */
 #define	LSYS5SIGR_SEL	1
 #define	L43BSDCALLS_SEL	2	/* notyet */
 #define	LUCODE_SEL	3
 #define LSOL26CALLS_SEL	4	/* Solaris >= 2.6 system call gate */
 #define	LUDATA_SEL	5
 /* separate stack, es,fs,gs sels ? */
 /* #define	LPOSIXCALLS_SEL	5*/	/* notyet */
 #define LBSDICALLS_SEL	16	/* BSDI system call gate */
 #define NLDT		(LBSDICALLS_SEL + 1)
 </programlisting>
 
     <para>Next, proc0's Process Control Block (<literal>struct
       pcb</literal>) structure is initialized.  proc0 is a
       <literal>struct proc</literal> structure that describes a kernel
       process.  It is always present while the kernel is running,
       therefore it is declared as global:</para>
 
     <programlisting><filename>sys/kern/kern_init.c:</filename>
     struct	proc proc0;</programlisting>
 
     <para>The structure <literal>struct pcb</literal> is a part of a
       proc structure.  It is defined in
       <filename>/usr/include/machine/pcb.h</filename> and has a
       process's information specific to the i386 architecture, such as
       registers values.</para>
     </sect2>
 
     <sect2>
       <title><function>mi_startup()</function></title>
 
       <para>This function performs a bubble sort of all the system
         initialization objects and then calls the entry of each object
         one by one:</para>
 
       <programlisting><filename>sys/kern/init_main.c:</filename>
 	for (sipp = sysinit; *sipp; sipp++) {
 
 		/* ... skipped ... */
 
 		/* Call function */
 		(*((*sipp)->func))((*sipp)->udata);
 		/* ... skipped ... */
 	}</programlisting>
 
     <para>Although the sysinit framework is described in the
       Developers' Handbook, I will discuss the internals of it.</para>
 
     <para>Every system initialization object (sysinit object) is
       created by calling a SYSINIT() macro.  Let us take as example an
       <literal>announce</literal> sysinit object.  This object prints
       the copyright message:</para>
 
     <programlisting><filename>sys/kern/init_main.c:</filename>
 static void
 print_caddr_t(void *data __unused)
 {
 	printf("%s", (char *)data);
 }
 SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t, copyright)</programlisting>
 
     <para>The subsystem ID for this object is SI_SUB_COPYRIGHT
       (0x0800001), which comes right after the SI_SUB_CONSOLE
       (0x0800000).  So, the copyright message will be printed out
       first, just after the console initialization.</para>
 
     <para>Let us take a look at what exactly the macro
       <literal>SYSINIT()</literal> does.  It expands to a
       <literal>C_SYSINIT()</literal> macro.  The
       <literal>C_SYSINIT()</literal> macro then expands to a static
       <literal>struct sysinit</literal> structure declaration with
       another <literal>DATA_SET</literal> macro call:</para>
       <programlisting><filename>/usr/include/sys/kernel.h:</filename>
       #define C_SYSINIT(uniquifier, subsystem, order, func, ident) \
       static struct sysinit uniquifier ## _sys_init = { \ subsystem, \
       order, \ func, \ ident \ }; \ DATA_SET(sysinit_set,uniquifier ##
       _sys_init);
 
 #define	SYSINIT(uniquifier, subsystem, order, func, ident)	\
 	C_SYSINIT(uniquifier, subsystem, order,			\
 	(sysinit_cfunc_t)(sysinit_nfunc_t)func, (void *)ident)</programlisting>
 
     <para>The <literal>DATA_SET()</literal> macro expands to a
       <literal>MAKE_SET()</literal>, and that macro is the point where
       the all sysinit magic is hidden:</para>
 
     <programlisting><filename>/usr/include/linker_set.h</filename>
 #define MAKE_SET(set, sym)						\
 	static void const * const __set_##set##_sym_##sym = &amp;sym;	\
 	__asm(".section .set." #set ",\"aw\"");				\
 	__asm(".long " #sym);						\
 	__asm(".previous")
 #endif
 #define TEXT_SET(set, sym) MAKE_SET(set, sym)
 #define DATA_SET(set, sym) MAKE_SET(set, sym)</programlisting>
 
     <para>In our case, the following declaration will occur:</para>
 
     <programlisting>static struct sysinit announce_sys_init = {
 	SI_SUB_COPYRIGHT,
 	SI_ORDER_FIRST,
 	(sysinit_cfunc_t)(sysinit_nfunc_t)  print_caddr_t,
 	(void *) copyright
 };
 
 static void const *const __set_sysinit_set_sym_announce_sys_init =
     &amp;announce_sys_init;
 __asm(".section .set.sysinit_set" ",\"aw\"");
 __asm(".long " "announce_sys_init");
 __asm(".previous");</programlisting>
 
     <para>The first <literal>__asm</literal> instruction will create
       an ELF section within the kernel's executable.  This will happen
       at kernel link time.  The section will have the name
       <literal>.set.sysinit_set</literal>.  The content of this section is one 32-bit
       value, the address of announce_sys_init structure, and that is
       what the second <literal>__asm</literal> is.  The third
       <literal>__asm</literal> instruction marks the end of a section.
       If a directive with the same section name occured before, the
       content, i.e. the 32-bit value, will be appended to the existing
       section, so forming an array of 32-bit pointers.</para>
 
     <para>Running <application>objdump</application> on a kernel
       binary, you may notice the presence of such small
       sections:</para>
 
     <screen>&prompt.user; <userinput>objdump -h /kernel</userinput>
   7 .set.cons_set 00000014  c03164c0  c03164c0  002154c0  2**2
                   CONTENTS, ALLOC, LOAD, DATA
   8 .set.kbddriver_set 00000010  c03164d4  c03164d4  002154d4  2**2
                   CONTENTS, ALLOC, LOAD, DATA
   9 .set.scrndr_set 00000024  c03164e4  c03164e4  002154e4  2**2
                   CONTENTS, ALLOC, LOAD, DATA
  10 .set.scterm_set 0000000c  c0316508  c0316508  00215508  2**2
                   CONTENTS, ALLOC, LOAD, DATA
  11 .set.sysctl_set 0000097c  c0316514  c0316514  00215514  2**2
                   CONTENTS, ALLOC, LOAD, DATA
  12 .set.sysinit_set 00000664  c0316e90  c0316e90  00215e90  2**2
                   CONTENTS, ALLOC, LOAD, DATA</screen>
 
     <para>This screen dump shows that the size of .set.sysinit_set
       section is 0x664 bytes, so <literal>0x664/sizeof(void
       *)</literal> sysinit objects are compiled into the kernel.  The
       other sections such as <literal>.set.sysctl_set</literal>
       represent other linker sets.</para>
 
     <para>By defining a variable of type <literal>struct
       linker_set</literal> the content of
       <literal>.set.sysinit_set</literal> section will be <quote>collected</quote>
       into that variable:</para>
       <programlisting><filename>sys/kern/init_main.c:</filename>
       extern struct linker_set sysinit_set; /* XXX */</programlisting>
 
     <para>The <literal>struct linker_set</literal> is defined as
       follows:</para>
 
     <programlisting><filename>/usr/include/linker_set.h:</filename>
   struct linker_set {
 	int	ls_length;
 	void	*ls_items[1];		/* really ls_length of them, trailing NULL */
 };</programlisting>
 
     <para>The first node will be equal to the number of a sysinit
       objects, and the second node will be a NULL-terminated array of
       pointers to them.</para>
 
     <para>Returning to the <function>mi_startup()</function>
       discussion, it is must be clear now, how the sysinit objects are
       being organized.  The <function>mi_startup()</function> function
       sorts them and calls each.  The very last object is the system
       scheduler:</para>
 
     <programlisting><filename>/usr/include/sys/kernel.h:</filename>
 enum sysinit_sub_id {
 	SI_SUB_DUMMY		= 0x0000000,	/* not executed; for linker*/
 	SI_SUB_DONE		= 0x0000001,	/* processed*/
 	SI_SUB_CONSOLE		= 0x0800000,	/* console*/
 	SI_SUB_COPYRIGHT	= 0x0800001,	/* first use of console*/
 ...
 	SI_SUB_RUN_SCHEDULER	= 0xfffffff	/* scheduler: no return*/
 };</programlisting>
 
     <para>The system scheduler sysinit object is defined in the file
       <filename>sys/vm/vm_glue.c</filename>, and the entry point for
       that object is <function>scheduler()</function>.  That function
       is actually an infinite loop, and it represents a process with
       PID 0, the swapper process.  The proc0 structure, mentioned
       before, is used to describe it.</para>
 
     <para>The first user process, called <emphasis>init</emphasis>, is
       created by the sysinit object <literal>init</literal>:</para>
 
     <programlisting><filename>sys/kern/init_main.c:</filename>
 static void
 create_init(const void *udata __unused)
 {
 	int error;
 	int s;
 
 	s = splhigh();
 	error = fork1(&amp;proc0, RFFDG | RFPROC, &amp;initproc);
 	if (error)
 		panic("cannot fork init: %d\n", error);
 	initproc->p_flag |= P_INMEM | P_SYSTEM;
 	cpu_set_fork_handler(initproc, start_init, NULL);
 	remrunqueue(initproc);
 	splx(s);
 }
 SYSINIT(init,SI_SUB_CREATE_INIT, SI_ORDER_FIRST, create_init, NULL)</programlisting>
 
   <para>The <function>create_init()</function> allocates a new process
     by calling <function>fork1()</function>, but does not mark it
     runnable.  When this new process is scheduled for execution by the
     scheduler, the <function>start_init()</function> will be called.
     That function is defined in <filename>init_main.c</filename>.  It
     tries to load and exec the <filename>init</filename> binary,
     probing <filename>/sbin/init</filename> first, then
     <filename>/sbin/oinit</filename>,
     <filename>/sbin/init.bak</filename>, and finally
     <filename>/stand/sysinstall</filename>:</para>
 
   <programlisting><filename>sys/kern/init_main.c:</filename>
 static char init_path[MAXPATHLEN] =
 #ifdef	INIT_PATH
     __XSTRING(INIT_PATH);
 #else
     "/sbin/init:/sbin/oinit:/sbin/init.bak:/stand/sysinstall";
 #endif</programlisting>
 
   </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/driverbasics/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/driverbasics/chapter.sgml
index e47a3772fd..61a425b8bd 100644
--- a/en_US.ISO8859-1/books/developers-handbook/driverbasics/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/driverbasics/chapter.sgml
@@ -1,392 +1,392 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="driverbasics">
   <title>Writing FreeBSD Device Drivers</title>
 
   <para>This chapter was written by &a.murray; with selections from a
     variety of sources including the intro(4) manual page by
     &a.joerg;.</para>
 
-  <sect1>
+  <sect1 id="driverbasics-intro">
     <title>Introduction</title>
     <para>This chapter provides a brief introduction to writing device
       drivers for FreeBSD.  A device in this context is a term used
       mostly for hardware-related stuff that belongs to the system,
       like disks, printers, or a graphics display with its keyboard.
       A device driver is the software component of the operating
       system that controls a specific device.  There are also
       so-called pseudo-devices where a device driver emulates the
       behavior of a device in software without any particular
       underlying hardware.  Device drivers can be compiled into the
       system statically or loaded on demand through the dynamic kernel
       linker facility `kld'.</para>
 
     <para>Most devices in a Unix-like operating system are accessed
       through device-nodes, sometimes also called special files.
       These files are usually located under the directory
       <filename>/dev</filename> in the filesystem hierarchy.
       In releases of FreeBSD older than 5.0-RELEASE, where
       &man.devfs.5; support is not integrated into FreeBSD,
       each device node must be
       created statically and independent of the existence of the
       associated device driver.  Most device nodes on the system are
       created by running <command>MAKEDEV</command>.</para>
 
     <para>Device drivers can roughly be broken down into two 
       categories; character and network device drivers.</para>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="driverbasics-kld">
     <title>Dynamic Kernel Linker Facility - KLD</title> 
 
     <para>The kld interface allows system administrators to
       dynamically add and remove functionality from a running system.
       This allows device driver writers to load their new changes into
       a running kernel without constantly rebooting to test
       changes.</para>
 
     <para>The kld interface is used through the following
       privileged commands:
 
     <itemizedlist>
       <listitem><simpara><command>kldload</command> - loads a new kernel
 	module</simpara></listitem>
       <listitem><simpara><command>kldunload</command> - unloads a kernel
 	module</simpara></listitem>
       <listitem><simpara><command>kldstat</command> - lists the currently loaded
 	modules</simpara></listitem>
     </itemizedlist>
     </para>
 
     <para>Skeleton Layout of a kernel module</para>
 
 <programlisting>/*
  * KLD Skeleton
  * Inspired by Andrew Reiter's Daemonnews article
  */
 
 #include &lt;sys/types.h&gt;
 #include &lt;sys/module.h&gt;
 #include &lt;sys/systm.h&gt;  /* uprintf */ 
 #include &lt;sys/errno.h&gt;
 #include &lt;sys/param.h&gt;  /* defines used in kernel.h */
 #include &lt;sys/kernel.h&gt; /* types used in module initialization */
 
 /* 
  * Load handler that deals with the loading and unloading of a KLD.
  */
 
 static int
 skel_loader(struct module *m, int what, void *arg)
 {
   int err = 0;
   
   switch (what) {
   case MOD_LOAD:                /* kldload */
     uprintf("Skeleton KLD loaded.\n");
     break;
   case MOD_UNLOAD:
     uprintf("Skeleton KLD unloaded.\n");
     break;
   default:
     err = EINVAL;
     break;
   }
   return(err);
 }
 
 /* Declare this module to the rest of the kernel */
 
 static moduledata_t skel_mod = {
   "skel",
   skel_loader,
   NULL
 };  
 
 DECLARE_MODULE(skeleton, skel_mod, SI_SUB_KLD, SI_ORDER_ANY);</programlisting>
 
 
     <sect2>
       <title>Makefile</title>
 
       <para>FreeBSD provides a makefile include that you can use to
 	quickly compile your kernel addition.</para>
 
       <programlisting>SRCS=skeleton.c
 KMOD=skeleton
 
 .include &lt;bsd.kmod.mk&gt;</programlisting>
 
       <para>Simply running <command>make</command> with this makefile
         will create a file <filename>skeleton.ko</filename> that can
         be loaded into your system by typing:
 <screen>&prompt.root; <userinput>kldload -v ./skeleton.ko</userinput></screen>
       </para>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="driverbasics-access">
     <title>Accessing a device driver</title>
 
     <para>Unix provides a common set of system calls for user
       applications to use.  The upper layers of the kernel dispatch
       these calls to the corresponding device driver when a user
       accesses a device node.  The <command>/dev/MAKEDEV</command>
       script makes most of the device nodes for your system but if you
       are doing your own driver development it may be necessary to
       create your own device nodes with <command>mknod</command>.
     </para>
 
     <sect2>
       <title>Creating static device nodes</title>
 
       <para>The <command>mknod</command> command requires four
 	arguments to create a device node.  You must specify the name
 	of the device node, the type of device, the major number of
 	the device, and the minor number of the device.</para>
     </sect2>
 
     <sect2>
       <title>Dynamic device nodes</title>
 
       <para>The device filesystem, or devfs, provides access to the
 	kernel's device namespace in the global filesystem namespace.
 	This eliminates the problems of potentially having a device
 	driver without a static device node, or a device node without
 	an installed device driver.  Devfs is still a work in
 	progress, but it is already working quite nicely.</para>
     </sect2>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="driverbasics-char">
     <title>Character Devices</title>
 
     <para>A character device driver is one that transfers data
       directly to and from a user process.  This is the most common
       type of device driver and there are plenty of simple examples in
       the source tree.</para>
 
     <para>This simple example pseudo-device remembers whatever values
       you write to it and can then supply them back to you when you
       read from it.</para>
 
     <programlisting>/*
  * Simple `echo' pseudo-device KLD
  *
  * Murray Stokely
  */
 
 #define MIN(a,b) (((a) < (b)) ? (a) : (b))
 
 #include &lt;sys/types.h&gt;
 #include &lt;sys/module.h&gt;
 #include &lt;sys/systm.h&gt; /* uprintf */ 
 #include &lt;sys/errno.h&gt;
 #include &lt;sys/param.h&gt;  /* defines used in kernel.h */
 #include &lt;sys/kernel.h&gt; /* types used in module initialization */
 #include &lt;sys/conf.h&gt;   /* cdevsw struct */
 #include &lt;sys/uio.h&gt;    /* uio struct */
 #include &lt;sys/malloc.h&gt;
 
 #define BUFFERSIZE 256
 
 /* Function prototypes */
 d_open_t      echo_open;
 d_close_t     echo_close;
 d_read_t      echo_read;
 d_write_t     echo_write;
 
 /* Character device entry points */
 static struct cdevsw echo_cdevsw = {
   echo_open,
   echo_close,
   echo_read,
   echo_write,
   noioctl,
   nopoll,
   nommap,
   nostrategy,
   "echo",
   33,                   /* reserved for lkms - /usr/src/sys/conf/majors */
   nodump,
   nopsize,
   D_TTY,
   -1
 };
 
 typedef struct s_echo {
   char msg[BUFFERSIZE];
   int len;
 } t_echo;
 
 /* vars */
 static dev_t sdev;
 static int len;
 static int count;
 static t_echo *echomsg;
 
 MALLOC_DECLARE(M_ECHOBUF);
 MALLOC_DEFINE(M_ECHOBUF, "echobuffer", "buffer for echo module");
 
 /*
  * This function acts is called by the kld[un]load(2) system calls to
  * determine what actions to take when a module is loaded or unloaded.
  */
       
 static int
 echo_loader(struct module *m, int what, void *arg)
 {
   int err = 0;
   
   switch (what) {
   case MOD_LOAD:                /* kldload */
     sdev = make_dev(<literal>&</literal>echo_cdevsw,
 		    0,
 		    UID_ROOT,
 		    GID_WHEEL,
 		    0600,
 		    "echo");
     /* kmalloc memory for use by this driver */
     /*    malloc(256,M_ECHOBUF,M_WAITOK); */
     MALLOC(echomsg, t_echo *, sizeof(t_echo), M_ECHOBUF, M_WAITOK);
     printf("Echo device loaded.\n");
     break;
   case MOD_UNLOAD:
     destroy_dev(sdev);
     FREE(echomsg,M_ECHOBUF);
     printf("Echo device unloaded.\n");
     break;
   default:
     err = EINVAL;
     break;
   }
   return(err);
 }
 
 int 
 echo_open(dev_t dev, int oflags, int devtype, struct proc *p)
 {
   int err = 0;
   
   uprintf("Opened device \"echo\" successfully.\n");
   return(err);
 }
 
 int 
 echo_close(dev_t dev, int fflag, int devtype, struct proc *p)
 {
   uprintf("Closing device \"echo.\"\n"); 
   return(0);
 } 
 
 /* 
  * The read function just takes the buf that was saved via
  * echo_write() and returns it to userland for accessing.
  * uio(9) 
  */
 
 int
 echo_read(dev_t dev, struct uio *uio, int ioflag)
 {
   int err = 0;
   int amt;
 
   /* How big is this read operation?  Either as big as the user wants,
      or as big as the remaining data */
   amt = MIN(uio->uio_resid, (echomsg->len - uio->uio_offset > 0) ? echomsg->len - uio->uio_offset : 0);
   if ((err = uiomove(echomsg->msg + uio->uio_offset,amt,uio)) != 0) {
     uprintf("uiomove failed!\n");
   }
 
   return err;
 }
 
 /*
  * echo_write takes in a character string and saves it
  * to buf for later accessing.
  */
 
 int
 echo_write(dev_t dev, struct uio *uio, int ioflag)
 {
   int err = 0;
 
   /* Copy the string in from user memory to kernel memory */
   err = copyin(uio->uio_iov->iov_base, echomsg->msg, MIN(uio->uio_iov->iov_len,BUFFERSIZE));
 
   /* Now we need to null terminate */
   *(echomsg->msg + MIN(uio->uio_iov->iov_len,BUFFERSIZE)) = 0;
   /* Record the length */
   echomsg->len = MIN(uio->uio_iov->iov_len,BUFFERSIZE);
 
   if (err != 0) {
     uprintf("Write failed: bad address!\n");
   }
 
   count++;
   return(err);
 }
 
 DEV_MODULE(echo,echo_loader,NULL);</programlisting>
 
     <para>To install this driver you will first need to make a node on
       your filesystem with a command such as:</para>
 
     <screen>&prompt.root; <userinput>mknod /dev/echo c 33 0</userinput></screen>
 
     <para>With this driver loaded you should now be able to type
       something like:</para>
 
     <screen>&prompt.root; <userinput>echo -n "Test Data" &gt; /dev/echo</userinput>
 &prompt.root; <userinput>cat /dev/echo</userinput>
 Test Data</screen>
 
     <para>Real hardware devices in the next chapter..</para>
 
     <para>Additional Resources
     <itemizedlist>
       <listitem><simpara><ulink
 	url="http://www.daemonnews.org/200010/blueprints.html">Dynamic
 	Kernel Linker (KLD) Facility Programming Tutorial</ulink> -
 	<ulink url="http://www.daemonnews.org/">Daemonnews</ulink> October 2000</simpara></listitem>
       <listitem><simpara><ulink
 	url="http://www.daemonnews.org/200007/newbus-intro.html">How
 	to Write Kernel Drivers with NEWBUS</ulink> - <ulink
 	url="http://www.daemonnews.org/">Daemonnews</ulink> July
 	2000</simpara></listitem>
     </itemizedlist>
     </para>
   </sect1>
 
-  <sect1>
+  <sect1 id="driverbasics-net">
     <title>Network Drivers</title>
 
     <para>Drivers for network devices do not use device nodes in order
       to be accessed.  Their selection is based on other decisions
       made inside the kernel and instead of calling open(), use of a
       network device is generally introduced by using the system call
       socket(2).</para> 
 
     <para>man ifnet(), loopback device, Bill Paul's drivers,
       etc..</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/developers-handbook/introduction/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.sgml
index 7bbb28eb9c..9e18e6eeb0 100644
--- a/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.sgml
@@ -1,226 +1,226 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="introduction">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Murray</firstname>
         <surname>Stokely</surname>
         <contrib>This chapter was written by </contrib>
       </author>
       <author>
         <firstname>Jeroen</firstname>
         <surname>Ruigrok van der Werven</surname>
       </author>
     </authorgroup>
   </chapterinfo>
   <title>Introduction</title>
 
-  <sect1>
+  <sect1 id="introduction-devel">
     <title>Developing on FreeBSD</title>
 
     <para>So here we are.  System all installed and you are ready to
       start programming.  But where to start?  What does FreeBSD
       provide?  What can it do for me, as a programmer?</para>
 
     <para>These are some questions which this chapter tries to answer.
       Of course, programming has different levels of proficiency like
       any other trade.  For some it is a hobby, for others it is their
       profession.  The information in this chapter might be more aimed
       towards the beginning programmer, but may also serve to be
       useful for the programmer taking her first steps on the FreeBSD
       platform.</para>      
 
   </sect1>
 
-  <sect1>
+  <sect1 id="introduction-bsdvision">
     <title>The BSD Vision</title>
 
     <para>To produce the best UNIX-like operating system package
       possible, with due respect to the original software tools
       ideology as well as usability, performance and
       stability.</para>
   </sect1>
  
-  <sect1>
+  <sect1 id="introduction-archguide">
     <title>Architectural Guidelines</title>
 
     <para>Our ideology can be described by the following
     guidelines</para>
 
     <itemizedlist>
 
       <listitem><para>Do not add new functionality unless an
         implementor cannot complete a real application without
         it.</para></listitem>
 
       <listitem><para>It is as important to decide what a system is
         not as to decide what it is. Do not serve all the world's
         needs; rather, make the system extensible so that additional
         needs can be met in an upwardly compatible
         fashion.</para></listitem>
 
       <listitem><para>The only thing worse than generalizing from one
         example is generalizing from no examples at
         all. </para></listitem>
 
       <listitem><para>If a problem is not completely understood, it is
         probably best to provide no solution at all.</para></listitem>
 
       <listitem><para>If you can get 90 percent of the desired effect
         for 10 percent of the work, use the simpler
         solution.</para></listitem>
 
       <listitem><para>Isolate complexity as much as
         possible.</para></listitem>
 
       <listitem><para>Provide mechanism, rather than policy. In
         particular, place user interface policy in the client's
         hands.</para></listitem>
 
      </itemizedlist>
 
      <para>From Scheifler & Gettys: "X Window System"</para>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="introduction-layout">
     <title>The Layout of 
       <filename class="directory">/usr/src</filename></title>
 
     <para>The complete source code to FreeBSD is available from our
       public CVS repository.  The source code is normally installed in
       <filename class=directory>/usr/src</filename> which contains the
       following subdirectories:</para>
 
     <para>
       <informaltable frame="none">
         <tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Directory</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	    <entry><filename class=directory>bin/</filename></entry>
             <entry>Source for files in
             <filename>/bin</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename class=directory>contrib/</filename></entry>
 	    <entry>Source for files from contributed software.</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>crypto/</filename></entry>
 	    <entry>Cryptographical sources</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>etc/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/etc</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>games/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/games</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>gnu/</filename></entry>
 	    <entry>Utilities covered by the GNU Public License</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>include/</filename></entry>
             <entry>Source for files in <filename
             class=directory>/usr/include</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>kerberosIV/</filename></entry>
             <entry>Source for Kerberos version IV</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>kerberos5/</filename></entry>
             <entry>Source for Kerberos version 5</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>lib/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/lib</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename class=directory>libexec/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/libexec</filename></entry>
 	    </row>
 	    
 	    <row>
 	    <entry><filename
  class=directory>release/</filename></entry>
             <entry>Files required to produce a FreeBSD release</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>sbin/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/sbin</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>secure/</filename></entry>
 	    <entry>FreeSec sources</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>share/</filename></entry>
 	    <entry>Source for files in <filename
 	    class=directory>/usr/share</filename></entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>sys/</filename></entry>
 	    <entry>Kernel source files</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename class=directory>tools/</filename></entry>
 	    <entry>Tools used for maintenance and testing of
 	    FreeBSD</entry>
 	    </row>
 
 	    <row>
 	    <entry><filename
  class=directory>usr.bin/</filename></entry>
             <entry>Source for files in <filename
  class=directory>/usr/bin</filename></entry>
             </row>
 
 	    <row>
 	    <entry><filename
  class=directory>usr.sbin/</filename></entry>
             <entry>Source for files in <filename
  class=directory>/usr/sbin</filename></entry>
             </row>
           </tbody>
 	</tgroup>
       </informaltable>
     </para>
   </sect1>
 </chapter>
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 1f51a1a70c..3c4b99338b 100644
--- a/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/isa/chapter.sgml
@@ -1,2483 +1,2483 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <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>
+  <sect1 id="isa-driver-synopsis">
     <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
       <literal>ep</literal> and <literal>aha</literal> are good sources of information.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="isa-driver-basics">
     <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 <quote>xxx</quote>
       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>
+    <sect1 id="isa-driver-device-t">
       <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 <literal>"xxx"</literal> 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 <quote>xxx0</quote>, <quote>xxx1</quote> 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
         <filename>kern/bus_subr.c</filename>.</para>
 
     </sect1>
 
-    <sect1>
+    <sect1 id="isa-driver-config">
       <title>Configuration file and the order of identifying and probing
 	during auto-configuration</title>
 
       <para>The ISA devices are described in the kernel configuration 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's needs and abilities for
 	auto-configuration. For example, some devices do not 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 <literal>isa0</literal> or <literal>isa1</literal>, otherwise the device would be
 	searched for on all the ISA buses.</para>
 
       <para><literal>sensitive</literal> 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 is 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
         <literal>sensitive</literal> 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; in this case, 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 is the responsibility of the driver to make sure
         that the same device will not 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 <filename>kern/subr_bus.c</filename>. The old IDE disk driver
         <filename>i386/isa/wd.c</filename> 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>
+    <sect1 id="isa-driver-resources">
       <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. However, generally this is neither needed nor recommended,
         so this issue is not discussed further here.</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 it 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 <literal>unsigned long</literal> and must be
         cast as necessary. The resource numbers do not 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
         normally be 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 by 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, this function will
             return an error only if one of <literal>type</literal>,
             <literal>rid</literal>, <literal>start</literal> or
             <literal>count</literal> has a value that falls out of the
             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 to 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 is 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 is 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 SEPARATE 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 <function>void
             driver_intr_t(void *)</function></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 are 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>
+    <sect1 id="isa-driver-busmem">
       <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 the computer</para>
 
       <para>In 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 is
         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
         configuration of a memory hole of 1MB starting at 14MB or
         15MB. FreeBSD can handle the memory holes properly if the BIOS
         reports them properly (this feature may be broken on old BIOSes).</para>
 
       <para>In 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, and 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 is
         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 is
         left at its original location. If it is not then a fresh
         conformant <quote>bounce page</quote> 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 a 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 <quote>no specific
               alignment</quote>. Applies only to the future
               <function>bus_dmamem_alloc()</function> but not
               <function>bus_dmamap_create()</function> calls.</para>
 	  </listitem>
 
 	  <listitem>
               <para><emphasis>boundary</emphasis> - physical address
               boundary that must not be crossed when allocating the
               memory. Use value 0 for <quote>no boundary</quote>. 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 slightly 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 is 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 (the hardware
 	      can not normally support that many
               scatter-gather buffers anyway).</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 being 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 until the memory
                       becomes 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>. At present, 
               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 at present
                   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 is 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 is
           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 is 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 is 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 its processing and
           check this synchronization flag. If it is 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>
+     <sect1 id="isa-driver-dma">
         <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 is
           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 (in addition 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 not 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 is 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 something
             probably 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>
+     <sect1 id="isa-driver-probe">
      <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 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 not 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 and a
           well-behaved driver should do so. But in cases where 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 do not
           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 do not 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
           <literal>sensitive</literal> flag: the sensitive devices get probed first and
           the rest of the 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 <quote>use those we set by
           <function>bus_set_resource()</function></quote>):
         </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 do not 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 is 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 is 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 function <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 are 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 is 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>
+     <sect1 id="isa-driver-attach">
      <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 the 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>
+     <sect1 id="isa-driver-detach">
        <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 a reboot will be
           needed anyway, so the efforts spent on writing the detach
           routine may not be worth it. Another argument 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 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>
+     <sect1 id="isa-driver-shutdown">
        <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 do not consider it here
           in any detail.
         </para>
      </sect1>
 
-     <sect1>
+     <sect1 id="isa-driver-intr">
           <title>xxx_intr</title>
 
         <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 in 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. This 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/jail/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/jail/chapter.sgml
index 7de06d5182..53af59a441 100644
--- a/en_US.ISO8859-1/books/developers-handbook/jail/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/jail/chapter.sgml
@@ -1,611 +1,611 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="jail">
   <chapterinfo>
     <author><firstname>Evan Sarmiento</firstname>
     <affiliation><address><email>evms@cs.bu.edu</email></address>
     </affiliation>
     </author>
     <copyright>
       <year>2001</year>
       <holder role="mailto:evms@cs.bu.edu">Evan Sarmiento</holder>
     </copyright>
   </chapterinfo>
   <title>The Jail Subsystem</title>
 
   <para>On most UNIX systems, root has omnipotent power. This promotes
     insecurity. If an attacker were to gain root on a system, he would
     have every function at his fingertips. In FreeBSD there are
     sysctls which dilute the power of root, in order to minimize the
     damage caused by an attacker. Specifically, one of these functions
     is called secure levels. Similarly, another function which is
     present from FreeBSD 4.0 and onward, is a utility called
     &man.jail.8;. <application>Jail</application> chroots an
     environment and sets certain restrictions on processes which are
     forked from within. For example, a jailed process cannot affect
     processes outside of the jail, utilize certain system calls, or
     inflict any damage on the main computer.</para>
 
   <para><application>Jail</application> is becoming the new security
     model. People are running potentially vulnerable servers such as
     Apache, BIND, and sendmail within jails, so that if an attacker
     gains root within the <application>Jail</application>, it is only
     an annoyance, and not a devastation. This article focuses on the
     internals (source code) of <application>Jail</application> and
     <application>Jail</application> NG. It will also suggest
     improvements upon the jail code base which are already being
     worked on. If you are looking for a how-to on setting up a
     <application>Jail</application>, I suggest you look at my other
     article in Sys Admin Magazine, May 2001, entitled "Securing
     FreeBSD using <application>Jail</application>."</para>
 
-  <sect1>
+  <sect1 id="jail-arch">
     <title>Architecture</title>
 
     <para>
       <application>Jail</application> consists of two realms: the
       user-space program, jail, and the code implemented within the
       kernel: the <literal>jail()</literal> system call and associated
       restrictions. I will be discussing the user-space program and
       then how jail is implemented within the kernel.</para>
 
     <sect2>
       <title>Userland code</title>
 
       <para>The source for the user-land jail is located in
         <filename>/usr/src/usr.sbin/jail</filename>, consisting of
         one file, <filename>jail.c</filename>. The program takes these
         arguments: the path of the jail, hostname, ip address, and the
         command to be executed.</para>
 
       <sect3>
         <title>Data Structures</title>
 
         <para>In <filename>jail.c</filename>, the first thing I would
           note is the declaration of an important structure
           <literal>struct jail j</literal>; which was included from
           <filename>/usr/include/sys/jail.h</filename>.
 
         <para>The definition of the jail structure is:</para>
 
 <programlisting><filename>/usr/include/sys/jail.h</filename>: 
 
 struct jail {
         u_int32_t       version;
         char            *path;
         char            *hostname;
         u_int32_t       ip_number;
 };</programlisting>
 
         <para>As you can see, there is an entry for each of the
           arguments passed to the jail program, and indeed, they are
           set during it's execution.</para>
 
         <programlisting><filename>/usr/src/usr.sbin/jail.c</filename>
 j.version = 0; 
 j.path = argv[1];
 j.hostname = argv[2];</programlisting>
 
       </sect3>
 
       <sect3>
         <title>Networking</title>
 
         <para>One of the arguments passed to the Jail program is an IP
           address with which the jail can be accessed over the
           network. Jail translates the ip address given into network
           byte order and then stores it in j (the jail structure).</para>
 
         <programlisting><filename>/usr/src/usr.sbin/jail/jail.c</filename>:
 struct in.addr in; 
 ... 
 i = inet.aton(argv[3], <![CDATA[&in]]>); 
 ... 
 j.ip_number = ntohl(in.s.addr);</programlisting>
 
         <para>The
           <citerefentry><refentrytitle>inet_aton</refentrytitle><manvolnum>3</manvolnum></citerefentry>
           function "interprets the specified character string as an
           Internet address, placing the address into the structure
           provided." The ip number node in the jail structure is set
           only when the ip address placed onto the in structure by
           inet aton is translated into network byte order by
           <function>ntohl()</function>.</para>
 
       </sect3>
 
       <sect3>
         <title>Jailing The Process</title>
 
         <para>Finally, the userland program jails the process, and
           executes the command specified. Jail now becomes an
           imprisoned process itself and forks a child process which
           then executes the command given using &man.execv.3;
 
         <programlisting><filename>/usr/src/sys/usr.sbin/jail/jail.c</filename>
 i = jail(<![CDATA[&j]]>); 
 ... 
 i = execv(argv[4], argv + 4);</programlisting>
 
         <para>As you can see, the jail function is being called, and
           its argument is the jail structure which has been filled
           with the arguments given to the program. Finally, the
           program you specify is executed. I will now discuss how Jail
           is implemented within the kernel.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Kernel Space</title>
 
       <para>We will now be looking at the file
         <filename>/usr/src/sys/kern/kern_jail.c</filename>.  This is
         the file where the jail system call, appropriate sysctls, and
         networking functions are defined.</para>
 
       <sect3>
         <title>sysctls</title>
 
         <para>In <filename>kern_jail.c</filename>, the following
           sysctls are defined:</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c:</filename>
 
 int     jail_set_hostname_allowed = 1;
 SYSCTL_INT(_jail, OID_AUTO, set_hostname_allowed, CTLFLAG_RW,
     <![CDATA[&jail]]>_set_hostname_allowed, 0,
     "Processes in jail can set their hostnames");
 
 int     jail_socket_unixiproute_only = 1;
 SYSCTL_INT(_jail, OID_AUTO, socket_unixiproute_only, CTLFLAG_RW,
     <![CDATA[&jail]]>_socket_unixiproute_only, 0,
     "Processes in jail are limited to creating UNIX/IPv4/route sockets only
 ");
 
 int     jail_sysvipc_allowed = 0;
 SYSCTL_INT(_jail, OID_AUTO, sysvipc_allowed, CTLFLAG_RW,
     <![CDATA[&jail]]>_sysvipc_allowed, 0,
     "Processes in jail can use System V IPC primitives");</programlisting>
 
         <para>Each of these sysctls can be accessed by the user
           through the sysctl program. Throughout the kernel, these
           specific sysctls are recognized by their name. For example,
           the name of the first sysctl is
           <literal>jail.set.hostname.allowed</literal>.</para>
       </sect3>
 
       <sect3>
         <title>&man.jail.2; system call</title>
 
         <para>Like all system calls, the &man.jail.2; system call takes
           two arguments, <literal>struct proc *p</literal> and
           <literal>struct jail_args
           *uap</literal>. <literal>p</literal> is a pointer to a proc
           structure which describes the calling process. In this
           context, uap is a pointer to a structure which specifies the
           arguments given to &man.jail.2; from the userland program
           <filename>jail.c</filename>. When I described the userland
           program before, you saw that the &man.jail.2; system call was
           given a jail structure as its own argument.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c:</filename>
 int
 jail(p, uap)
         struct proc *p;
         struct jail_args /* {
                 syscallarg(struct jail *) jail;
         } */ *uap;</programlisting>
 
         <para>Therefore, <literal>uap->jail</literal> would access the
           jail structure which was passed to the system call. Next,
           the system call copies the jail structure into kernel space
           using the <literal>copyin()</literal>
           function. <literal>copyin()</literal> takes three arguments:
           the data which is to be copied into kernel space,
           <literal>uap->jail</literal>, where to store it,
           <literal>j</literal> and the size of the storage. The jail
           structure <literal>uap->jail</literal> is copied into kernel
           space and stored in another jail structure,
           <literal>j</literal>.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c: </filename>
 error = copyin(uap->jail, <![CDATA[&j]]>, sizeof j);</programlisting>
 
         <para>There is another important structure defined in
           jail.h. It is the prison structure
           (<literal>pr</literal>). The prison structure is used
           exclusively within kernel space. The &man.jail.2; system call
           copies everything from the jail structure onto the prison
           structure. Here is the definition of the prison structure.</para>
 
         <programlisting><filename>/usr/include/sys/jail.h</filename>:
 struct prison {
         int             pr_ref;
         char            pr_host[MAXHOSTNAMELEN];
         u_int32_t       pr_ip;
         void            *pr_linux;
 };</programlisting>
 
         <para>The jail() system call then allocates memory for a
         pointer to a prison structure and copies data between the two
         structures.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c</filename>:
  MALLOC(pr, struct prison *, sizeof *pr , M_PRISON, M_WAITOK);
  bzero((caddr_t)pr, sizeof *pr);
  error = copyinstr(j.hostname, <![CDATA[&pr->pr_host]]>, sizeof pr->pr_host, 0);
  if (error) 
          goto bail;</programlisting>
 
         <para>Finally, the jail system call chroots the path
           specified. The chroot function is given two arguments. The
           first is p, which represents the calling process, the second
           is a pointer to the structure chroot args. The structure
           chroot args contains the path which is to be chrooted. As
           you can see, the path specified in the jail structure is
           copied to the chroot args structure and used.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c</filename>:
 ca.path = j.path; 
 error = chroot(p, <![CDATA[&ca]]>);</programlisting>
 
         <para>These next three lines in the source are very important,
           as they specify how the kernel recognizes a process as
           jailed. Each process on a Unix system is described by its
           own proc structure. You can see the whole proc structure in
           <filename>/usr/include/sys/proc.h</filename>. For example,
           the p argument in any system call is actually a pointer to
           that process' proc structure, as stated before. The proc
           structure contains nodes which can describe the owner's
           identity (<literal>p_cred</literal>), the process resource
           limits (<literal>p_limit</literal>), and so on. In the
           definition of the process structure, there is a pointer to a
           prison structure. (<literal>p_prison</literal>).</para>
 
         <programlisting><filename>/usr/include/sys/proc.h: </filename>
 struct proc { 
 ...
 struct prison *p_prison; 
 ...
 };</programlisting>
 
         <para>In <filename>kern_jail.c</filename>, the function then
           copies the pr structure, which is filled with all the
           information from the original jail structure, over to the
           <literal>p->p_prison</literal> structure. It then does a
           bitwise OR of <literal>p->p_flag</literal> with the constant
           <literal>P_JAILED</literal>, meaning that the calling
           process is now recognized as jailed. The parent process of
           each process, forked within the jail, is the program jail
           itself, as it calls the &man.jail.2; system call. When the
           program is executed through execve, it inherits the
           properties of its parents proc structure, therefore it has
           the <literal>p->p_flag</literal> set, and the
           <literal>p->p_prison</literal> structure is filled.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_jail.c</filename>
 p->p.prison = pr; 
 p->p.flag |= P.JAILED;</programlisting>
 
         <para>When a process is forked from a parent process, the
           &man.fork.2; system call deals differently with imprisoned
           processes. In the fork system call, there are two pointers
           to a <literal>proc</literal> structure <literal>p1</literal>
           and <literal>p2</literal>. <literal>p1</literal> points to
           the parent's <literal>proc</literal> structure and p2 points
           to the child's unfilled <literal>proc</literal>
           structure. After copying all relevant data between the
           structures, &man.fork.2; checks if the structure
           <literal>p->p_prison</literal> is filled on
           <literal>p2</literal>. If it is, it increments the
           <literal>pr.ref</literal> by one, and sets the
           <literal>p_flag</literal> to one on the child process.</para>
 
         <programlisting><filename>/usr/src/sys/kern/kern_fork.c</filename>:
 if (p2->p_prison) {
         p2->p_prison->pr_ref++;
 	p2->p_flag |= P_JAILED;
 }</programlisting>
 
       </sect3>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="jail-restrictions">
     <title>Restrictions</title>
 
     <para>Throughout the kernel there are access restrictions relating
       to jailed processes. Usually, these restrictions only check if
       the process is jailed, and if so, returns an error. For
       example:</para>
 
     <programlisting>if (p->p_prison) 
         return EPERM;</programlisting>
 
     <sect2>
       <title>SysV IPC</title>
 
       <para>System V IPC is based on messages. Processes can send each
         other these messages which tell them how to act. The functions
         which deal with messages are: <literal>msgsys</literal>,
         <literal>msgctl</literal>, <literal>msgget</literal>,
         <literal>msgsend</literal> and <literal>msgrcv</literal>.
         Earlier, I mentioned that there were certain sysctls you could
         turn on or off in order to affect the behavior of Jail. One of
         these sysctls was <literal>jail_sysvipc_allowed</literal>. On
         most systems, this sysctl is set to 0. If it were set to 1, it
         would defeat the whole purpose of having a jail; privleged
         users from within the jail would be able to affect processes
         outside of the environment. The difference between a message
         and a signal is that the message only consists of the signal
         number.</para>
 
       <para><filename>/usr/src/sys/kern/sysv_msg.c</filename>:</para>
 
       <itemizedlist>
         <listitem> <para>&man.msgget.3;: msgget returns (and possibly
         creates) a message descriptor that designates a message queue
         for use in other system calls.</para></listitem>
 
         <listitem> <para>&man.msgctl.3;: Using this function, a process
         can query the status of a message
         descriptor.</para></listitem>
 
         <listitem> <para>&man.msgsnd.3;: msgsnd sends a message to a
         process.</para></listitem>
 
         <listitem> <para>&man.msgrcv.3;: a process receives messages using
         this function</para></listitem>
 
       </itemizedlist>
 
       <para>In each of these system calls, there is this
         conditional:</para>
 
       <programlisting><filename>/usr/src/sys/kern/sysv msg.c</filename>:
 if (!jail.sysvipc.allowed && p->p_prison != NULL)
         return (ENOSYS);</programlisting>
 
       <para>Semaphore system calls allow processes to synchronize
         execution by doing a set of operations atomically on a set of
         semaphores. Basically semaphores provide another way for
         processes lock resources. However, process waiting on a
         semaphore, that is being used, will sleep until the resources
         are relinquished. The following semaphore system calls are
         blocked inside a jail: <literal>semsys</literal>,
         <literal>semget</literal>, <literal>semctl</literal> and
         <literal>semop</literal>.</para>
 
       <para><filename>/usr/src/sys/kern/sysv_sem.c</filename>:</para>
 
       <itemizedlist>
         <listitem>
           <para>&man.semctl.2;<literal>(id, num, cmd, arg)</literal>:
             Semctl does the specified cmd on the semaphore queue
             indicated by id.</para></listitem>
 
         <listitem>
            <para>&man.semget.2;<literal>(key, nsems, flag)</literal>:
            Semget creates an array of semaphores, corresponding to
            key.</para>
 
           <para><literal>Key and flag take on the same meaning as they
           do in msgget.</literal></para></listitem>
 
         <listitem><para>&man.semop.2;<literal>(id, ops, num)</literal>:
           Semop does the set of semaphore operations in the array of
           structures ops, to the set of semaphores identified by
           id.</para></listitem>
       </itemizedlist>
 
       <para>System V IPC allows for processes to share
         memory. Processes can communicate directly with each other by
         sharing parts of their virtual address space and then reading
         and writing data stored in the shared memory. These system
         calls are blocked within a jailed environment: <literal>shmdt,
         shmat, oshmctl, shmctl, shmget</literal>, and
         <literal>shmsys</literal>.</para>
 
       <para><filename>/usr/src/sys/kern/sysv shm.c</filename>:</para>
 
       <itemizedlist>
         <listitem><para>&man.shmctl.2;<literal>(id, cmd, buf)</literal>:
         shmctl does various control operations on the shared memory
         region identified by id.</para></listitem>
 
         <listitem><para>&man.shmget.2;<literal>(key, size,
         flag)</literal>: shmget accesses or creates a shared memory
         region of size bytes.</para></listitem>
 
         <listitem><para>&man.shmat.2;<literal>(id, addr, flag)</literal>:
         shmat attaches a shared memory region identified by id to the
         address space of a process.</para></listitem>
 
         <listitem><para>&man.shmdt.2;<literal>(addr)</literal>: shmdt
         detaches the shared memory region previously attached at
         addr.</para></listitem>
 
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Sockets</title>
 
       <para>Jail treats the &man.socket.2; system call and related
         lower-level socket functions in a special manner. In order to
         determine whether a certain socket is allowed to be created,
         it first checks to see if the sysctl
         <literal>jail.socket.unixiproute.only</literal> is set. If
         set, sockets are only allowed to be created if the family
         specified is either <literal>PF_LOCAL</literal>,
         <literal>PF_INET</literal> or
         <literal>PF_ROUTE</literal>. Otherwise, it returns an
         error.</para>
 
       <programlisting><filename>/usr/src/sys/kern/uipc_socket.c</filename>:
 int socreate(dom, aso, type, proto, p) 
 ... 
 register struct protosw *prp; 
 ... 
 {
         if (p->p_prison && jail_socket_unixiproute_only &&
             prp->pr_domain->dom_family != PR_LOCAL && prp->pr_domain->dom_family != PF_INET 
             && prp->pr_domain->dom_family != PF_ROUTE)
                 return (EPROTONOSUPPORT); 
 ...
 }</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Berkeley Packet Filter</title>
 
       <para>The Berkeley Packet Filter provides a raw interface to
         data link layers in a protocol independent fashion. The
         function <literal>bpfopen()</literal> opens an Ethernet
         device. There is a conditional which disallows any jailed
         processes from accessing this function.</para>
 
       <programlisting><filename>/usr/src/sys/net/bpf.c</filename>: 
 static int bpfopen(dev, flags, fmt, p) 
 ... 
 {
         if (p->p_prison) 
                 return (EPERM);
 ...
 }</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Protocols</title>
 
       <para>There are certain protocols which are very common, such as
         TCP, UDP, IP and ICMP. IP and ICMP are on the same level: the
         network layer 2. There are certain precautions which are
         taken in order to prevent a jailed process from binding a
         protocol to a certain port only if the <literal>nam</literal>
         parameter is set. nam is a pointer to a sockaddr structure,
         which describes the address on which to bind the service. A
         more exact definition is that sockaddr "may be used as a
         template for reffering to the identifying tag and length of
         each address"[2]. In the function in
         <literal>pcbbind</literal>, <literal>sin</literal> is a
         pointer to a sockaddr.in structure, which contains the port,
         address, length and domain family of the socket which is to be
         bound. Basically, this disallows any processes from jail to be
         able to specify the domain family.</para>
 
       <programlisting><filename>/usr/src/sys/kern/netinet/in_pcb.c</filename>: 
 int in.pcbbind(int, nam, p) 
 ...
         struct sockaddr *nam; 
         struct proc *p; 
 {
         ... 
         struct sockaddr.in *sin; 
         ... 
         if (nam) {
                 sin = (struct sockaddr.in *)nam; 
                 ... 
                 if (sin->sin_addr.s_addr != INADDR_ANY) 
                        if (prison.ip(p, 0, <![CDATA[&sin]]>->sin.addr.s_addr)) 
                               return (EINVAL); 
                 ....
         }
 ...
 }</programlisting>
 
       <para>You might be wondering what function
         <literal>prison_ip()</literal> does. prison.ip is given three
         arguments, the current process (represented by
         <literal>p</literal>), any flags, and an ip address. It
         returns 1 if the ip address belongs to a jail or 0 if it does
         not. As you can see from the code, if it is indeed an ip
         address belonging to a jail, the protcol is not allowed to
         bind to a certain port.</para>
 
       <programlisting><filename>/usr/src/sys/kern/kern_jail.c:</filename>
 int prison_ip(struct proc *p, int flag, u_int32_t *ip) {
         u_int32_t tmp;
 
        if (!p->p_prison) 
               return (0); 
        if (flag) 
               tmp = *ip; 
        else tmp = ntohl (*ip); 
 
        if (tmp == INADDR_ANY) {
               if (flag) 
                      *ip = p->p_prison->pr_ip; 
               else *ip = htonl(p->p_prison->pr_ip); 
               return (0); 
        }
 
        if (p->p_prison->pr_ip != tmp) 
               return (1); 
        return (0); 
 }</programlisting>
 
       <para>Jailed users are not allowed to bind services to an ip
         which does not belong to the jail. The restriction is also
         written within the function <literal>in_pcbbind</literal>:</para>
 
       <programlisting><filename>/usr/src/sys/net inet/in_pcb.c</filename>
         if (nam) {
                ... 
                lport = sin->sin.port; 
                ... if (lport) { 
                           ... 
                          if (p && p->p_prison)
                                 prison = 1; 
                          if (prison &&
                              prison_ip(p, 0, <![CDATA[&sin]]>->sin_addr.s_addr))
 			            return (EADDRNOTAVAIL);</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Filesystem</title>
 
       <para>Even root users within the jail are not allowed to set any
         file flags, such as immutable, append, and no unlink flags, if
         the securelevel is greater than 0.</para>
 
       <programlisting>/usr/src/sys/ufs/ufs/ufs_vnops.c:
 int ufs.setattr(ap) 
         ... 
 {
         if ((cred->cr.uid == 0) && (p->prison == NULL)) {
 	        if ((ip->i_flags 
                      & (SF_NOUNLINK | SF_IMMUTABLE | SF_APPEND)) && 
                      securelevel > 0)
 		       return (EPERM);
 }</programlisting>
 
     </sect2>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="jail-jailng">
     <title>Jail NG</title>
 
     <para>Jail NG is a "from-scratch re-implementation of Jail" by
       Robert Watson, a FreeBSD committer. Some of the new features
       include the ability to add processes to a jail, an improved
       management tool, and per-jail sysctls. For example, you could
       have <literal>sysvipc_permitted</literal> set on one jail while
       another jail may be allowed to use System V IPC. You can
       download the kernel patches and utilities for Jail NG from his
       website at:
       <ulink
       url="http://www.watson.org/~robert/jailng/"></ulink>.</para>
 
   </sect1>
 
 </chapter>
 
diff --git a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
index c91c3420e5..844176f629 100644
--- a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
@@ -1,649 +1,649 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="kerneldebug">
   <title>Kernel Debugging</title>
   
   <para><emphasis>Contributed by &a.paul; and &a.joerg;</emphasis></para>
   
-  <sect1>
+  <sect1 id="kerneldebug-gdb">
     <title>Debugging a Kernel Crash Dump with <command>gdb</command></title>
     
     <para>Here are some instructions for getting kernel debugging
       working on a crash dump.  They assume that you have enough swap
       space for a crash dump.  Typically you want to
       specify one of the swap devices specified in
       <filename>/etc/fstab</filename>. Dumps to non-swap devices,
       tapes for example, are currently not supported.</para>
 
     <note>
       <para>Use the &man.dumpon.8; command to tell the kernel where to dump to
 	(note that this will have to be done after configuring the partition in
 	question as swap space via &man.swapon.8;).  This is normally arranged
 	by setting the <varname>dumpdev</varname> variable in
 	<filename>/etc/rc.conf</filename>.</para>
 
       <para>Alternatively, you can hard-code the dump device via the
 	<literal>dump</literal> clause in the <literal>config</literal> line of
 	your kernel configuration file.  This approach is deprecated and should
 	be used only if you want a crash dump from a kernel that crashes during
 	booting.</para>
     </note>
     
     <note>
       <para>In the following, the term <command>gdb</command> refers to
         the debugger <command>gdb</command> run in <quote>kernel debug 
         mode</quote>.  This can be accomplished by starting the 
         <command>gdb</command> with the option <option>-k</option>.  In 
         kernel debug mode, <command>gdb</command> changes its prompt to 
         <prompt>(kgdb)</prompt>.</para>
     </note>
     
     <tip>
       <para>If you are using FreeBSD 3 or earlier, you should make a stripped
         copy of the debug kernel, rather than installing the large debug
         kernel itself:</para>
 
       <screen>&prompt.root; <userinput>cp kernel kernel.debug</userinput>
 &prompt.root; <userinput>strip -g kernel</userinput></screen>
 
       <para>This stage is not necessary, but it is recommended.  (In
         FreeBSD 4 and later releases this step is performed automatically
         at the end of the kernel <command>make</command> process.)
         When the kernel has been stripped, either automatically or by
         using the commands above, you may install it as usual by typing
         <command>make install</command>.</para>
 
       <para>Note that older releases of FreeBSD (up to but not including
         3.1) used a.out kernels by default, which must have their symbol
         tables permanently resident in physical memory.  With the larger
         symbol table in an unstripped debug kernel, this is wasteful.
         Recent FreeBSD releases use ELF kernels where this is no longer a
         problem.</para>
     </tip>
 
     <para>If you are testing a new kernel, for example by typing the new
       kernel's name at the boot prompt, but need to boot a different one in
       order to get your system up and running again, boot it only into single
       user state using the <option>-s</option> flag at the boot prompt, and
       then perform the following steps:</para>
 
     <screen>&prompt.root; <userinput>fsck -p</userinput>
 &prompt.root; <userinput>mount -a -t ufs</userinput>       # so your filesystem for /var/crash is writable
 &prompt.root; <userinput>savecore -N /kernel.panicked /var/crash</userinput>
 &prompt.root; <userinput>exit</userinput>                  # ...to multi-user</screen>
 	  
     <para>This instructs &man.savecore.8; to use another kernel for symbol
       name extraction.  It would otherwise default to the currently running
       kernel and most likely not do anything at all since the crash dump and
       the kernel symbols differ.</para>
     
     <para>Now, after a crash dump, go to
       <filename>/sys/compile/WHATEVER</filename> and run
       <command>gdb <option>-k</option></command>.  From <command>gdb</command> do:
 	  
       <screen><userinput>symbol-file kernel.debug</userinput>
 <userinput>exec-file /var/crash/kernel.0</userinput>
 <userinput>core-file /var/crash/vmcore.0</userinput></screen>
 	  
       and voila, you can debug the crash dump using the kernel sources just
       like you can for any other program.</para>
 
     <para>Here is a script log of a <command>gdb</command> session
       illustrating the procedure.  Long lines have been folded to improve
       readability, and the lines are numbered for reference. Despite this, it
       is a real-world error trace taken during the development of the pcvt
       console driver.</para>
     
 <screen> 1:Script started on Fri Dec 30 23:15:22 1994
  2:&prompt.root; <userinput>cd /sys/compile/URIAH</userinput>
  3:&prompt.root; <userinput>gdb -k kernel /var/crash/vmcore.1</userinput> 
  4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel
 ...done.
  5:IdlePTD 1f3000
  6:panic: because you said to!
  7:current pcb at 1e3f70
  8:Reading in symbols for ../../i386/i386/machdep.c...done.
  9:<prompt>(kgdb)</prompt> <userinput>where</userinput>
 10:#0  boot (arghowto=256) (../../i386/i386/machdep.c line 767)
 11:#1  0xf0115159 in panic ()
 12:#2  0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
 13:#3  0xf010185e in db_fncall ()
 14:#4  0xf0101586 in db_command (-266509132, -266509516, -267381073)
 15:#5  0xf0101711 in db_command_loop ()
 16:#6  0xf01040a0 in db_trap ()
 17:#7  0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
 18:#8  0xf019d2eb in trap_fatal (...)
 19:#9  0xf019ce60 in trap_pfault (...)
 20:#10 0xf019cb2f in trap (...)
 21:#11 0xf01932a1 in exception:calltrap ()
 22:#12 0xf0191503 in cnopen (...)
 23:#13 0xf0132c34 in spec_open ()
 24:#14 0xf012d014 in vn_open ()
 25:#15 0xf012a183 in open ()
 26:#16 0xf019d4eb in syscall (...)
 27:<prompt>(kgdb)</prompt> <userinput>up 10</userinput>
 28:Reading in symbols for ../../i386/i386/trap.c...done.
 29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
 30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
 31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
 32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
 33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
 34:ss = -266427884}) (../../i386/i386/trap.c line 283)
 35:283                             (void) trap_pfault(&amp;frame, FALSE);
 36:<prompt>(kgdb)</prompt> <userinput>frame frame-&gt;tf_ebp frame-&gt;tf_eip</userinput>
 37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
 38:#0  0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
 39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
 40:403             return ((*linesw[tp-&gt;t_line].l_open)(dev, tp));
 41:<prompt>(kgdb)</prompt> <userinput>list</userinput>
 42:398        
 43:399             tp-&gt;t_state |= TS_CARR_ON;
 44:400             tp-&gt;t_cflag |= CLOCAL;  /* cannot be a modem (:-) */
 45:401     
 46:402     #if PCVT_NETBSD || (PCVT_FREEBSD >= 200)
 47:403             return ((*linesw[tp-&gt;t_line].l_open)(dev, tp));
 48:404     #else
 49:405             return ((*linesw[tp-&gt;t_line].l_open)(dev, tp, flag));
 50:406     #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */
 51:407     }
 52:<prompt>(kgdb)</prompt> <userinput>print tp</userinput>
 53:Reading in symbols for ../../i386/i386/cons.c...done.
 54:$1 = (struct tty *) 0x1bae
 55:<prompt>(kgdb)</prompt> <userinput>print tp-&gt;t_line</userinput>
 56:$2 = 1767990816
 57:<prompt>(kgdb)</prompt> <userinput>up</userinput>
 58:#1  0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
 59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
 60:       return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
 61:<prompt>(kgdb)</prompt> <userinput>up</userinput>
 62:#2  0xf0132c34 in spec_open ()
 63:<prompt>(kgdb)</prompt> <userinput>up</userinput>
 64:#3  0xf012d014 in vn_open ()
 65:<prompt>(kgdb)</prompt> <userinput>up</userinput>
 66:#4  0xf012a183 in open ()
 67:<prompt>(kgdb)</prompt> <userinput>up</userinput>
 68:#5  0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
 69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
 70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
 71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
 72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
 73:673             error = (*callp-&gt;sy_call)(p, args, rval);
 74:<prompt>(kgdb)</prompt> <userinput>up</userinput>
 75:Initial frame selected; you cannot go up.
 76:<prompt>(kgdb)</prompt> <userinput>quit</userinput>
 77:&prompt.root; <userinput>exit</userinput>
 78:exit
 79:
 80:Script done on Fri Dec 30 23:18:04 1994</screen>
     <para>Comments to the above script:</para>
     
     <variablelist>
       <varlistentry>
 	<term>line 6:</term>
 
 	<listitem>
 	  <para>This is a dump taken from within DDB (see below), hence the
 	    panic comment <quote>because you said to!</quote>, and a rather
 	    long stack trace; the initial reason for going into DDB has been a
 	    page fault trap though.</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term>line 20:</term>
 
 	<listitem>
 	  <para>This is the location of function <function>trap()</function>
 	    in the stack trace.</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term>line 36:</term>
 
 	<listitem>
 	  <para>Force usage of a new stack frame; this is no longer necessary.
 	    The stack frames are supposed to point to the right
 	    locations now, even in case of a trap.
 	    From looking at the code in source line 403, there is a
 	    high probability that either the pointer access for
 	    <quote>tp</quote> was messed up, or the array access was out of
 	    bounds.</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term>line 52:</term>
 
 	<listitem>
 	  <para>The pointer looks suspicious, but happens to be a valid
 	    address.</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term>line 56:</term>
 
 	<listitem>
 	  <para>However, it obviously points to garbage, so we have found our
 	    error! (For those unfamiliar with that particular piece of code:
 	    <literal>tp-&gt;t_line</literal> refers to the line discipline  of
 	    the console device here, which must be a rather small integer
 	    number.)</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
   
-  <sect1>
+  <sect1 id="kerneldebug-ddd">
     <title>Debugging a Crash Dump with DDD</title>
     
     <para>Examining a kernel crash dump with a graphical debugger like
       <command>ddd</command> is also possible (you will need to install
       the <filename role="package">devel/ddd</filename> port in order to use the
       <command>ddd</command> debugger).  Add the <option>-k</option>
       option to the <command>ddd</command> command line you would use
       normally.  For example;</para>
 
     <screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen>
     
     <para>You should then be able to go about looking at the crash dump using
       <command>ddd</command>'s graphical interface.</para>
   </sect1>
   
-  <sect1>
+  <sect1 id="kerneldebug-post-mortem">
     <title>Post-Mortem Analysis of a Dump</title>
     
     <para>What do you do if a kernel dumped core but you did not expect it,
       and it is therefore not compiled using <command>config -g</command>? Not
       everything is lost here.  Do not panic!</para>
 
     <para>Of course, you still need to enable crash dumps.  See above for the
       options you have to specify in order to do this.</para>
       
     <para>Go to your kernel config directory
       (<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>)
       and edit your configuration file.  Uncomment (or add, if it does not
       exist) the following line:</para>
 
     <programlisting>makeoptions    DEBUG=-g                #Build kernel with gdb(1) debug symbols</programlisting>
 
     <para>Rebuild the kernel.  Due to the time stamp change on the Makefile,
       some other object files will be rebuilt, for example
       <filename>trap.o</filename>.  With a bit of luck, the added
       <option>-g</option> option will not change anything for the generated
       code, so you will finally get a new kernel with similar code to the
       faulting one but some debugging symbols.  You should at least verify the
       old and new sizes with the &man.size.1; command.  If there is a
       mismatch, you probably need to give up here.</para>
 
     <para>Go and examine the dump as described above.  The debugging symbols
       might be incomplete for some places, as can be seen in the stack trace
       in the example above where some functions are displayed without line
       numbers and argument lists.  If you need more debugging symbols, remove
       the appropriate object files, recompile the kernel again and repeat the
       <command>gdb <option>-k</option></command>
       session until you know enough.</para>
 
     <para>All this is not guaranteed to work, but it will do it fine in most
       cases.</para>
   </sect1>
   
-  <sect1>
+  <sect1 id="kerneldebug-online-ddb">
     <title>On-Line Kernel Debugging Using DDB</title>
     
     <para>While <command>gdb <option>-k</option></command> as an off-line debugger provides a very
       high level of user interface, there are some things it cannot do.  The
       most important ones being breakpointing and single-stepping kernel
       code.</para>
 
     <para>If you need to do low-level debugging on your kernel, there is an
       on-line debugger available called DDB.  It allows setting of
       breakpoints, single-stepping kernel functions, examining and changing
       kernel variables, etc.  However, it cannot access kernel source files,
       and only has access to the global and static symbols, not to the full
       debug information like <command>gdb</command> does.</para>
 
     <para>To configure your kernel to include DDB, add the option line
       
       <programlisting>options DDB</programlisting>
 
       to your config file, and rebuild.  (See <ulink
 	url="../handbook/index.html">The FreeBSD Handbook</ulink> for details on
       configuring the FreeBSD kernel).</para>
 
     <note>
       <para>If you have an older version of the boot blocks, your
 	debugger symbols might not be loaded at all.  Update the boot blocks;
 	the recent ones load the DDB symbols automagically.</para>
     </note>
     
     <para>Once your DDB kernel is running, there are several ways to enter
       DDB.  The first, and earliest way is to type the boot flag
       <option>-d</option> right at the boot prompt.  The kernel will start up
       in debug mode and enter DDB prior to any device probing.  Hence you can
       even debug the device probe/attach functions.</para>
 
     <para>The second scenario is to drop to the debugger once the
       system has booted.  There are two simple ways to accomplish
       this.  If you would like to break to the debugger from the
       command prompt, simply type the command:</para>
 
     <screen>&prompt.root; <userinput>sysctl debug.enter_debugger=ddb</userinput></screen>
 
     <para>Alternatively, if you are at the system console, you may use
       a hot-key on the keyboard.  The default break-to-debugger
       sequence is <keycombo action="simul"><keycap>Ctrl</keycap>
       <keycap>Alt</keycap><keycap>ESC</keycap></keycombo>.  For
       syscons, this sequence can be remapped and some of the
       distributed maps out there do this, so check to make sure you
       know the right sequence to use.  There is an option available
       for serial consoles that allows the use of a serial line BREAK on the
       console line to enter DDB (<literal>options BREAK_TO_DEBUGGER</literal>
       in the kernel config file).  It is not the default since there are a lot
       of serial adapters around that gratuitously generate a BREAK
       condition, for example when pulling the cable.</para>
 
     <para>The third way is that any panic condition will branch to DDB if the
       kernel is configured to use it.  For this reason, it is not wise to
       configure a kernel with DDB for a machine running unattended.</para>
 
     <para>The DDB commands roughly resemble some <command>gdb</command>
       commands.  The first thing you probably need to do is to set a
       breakpoint:</para>
     
     <screen><userinput>b function-name</userinput>
 <userinput>b address</userinput></screen>
 	  
     <para>Numbers are taken hexadecimal by default, but to make them distinct
       from symbol names; hexadecimal numbers starting with the letters
       <literal>a-f</literal> need to be preceded with <literal>0x</literal>
       (this is optional for other numbers).  Simple expressions are allowed,
       for example: <literal>function-name + 0x103</literal>.</para>
 
     <para>To continue the operation of an interrupted kernel, simply
       type:</para>
     
     <screen><userinput>c</userinput></screen>
     
     <para>To get a stack trace, use:</para>
     
     <screen><userinput>trace</userinput></screen>
     
     <note>
       <para>Note that when entering DDB via a hot-key, the kernel is currently
 	servicing an interrupt, so the stack trace might be not of much use
 	to you.</para>
     </note>
     
     <para>If you want to remove a breakpoint, use</para>
     
     
     <screen><userinput>del</userinput>
 <userinput>del address-expression</userinput></screen>
     
     <para>The first form will be accepted immediately after a breakpoint hit,
       and deletes the current breakpoint.  The second form can remove any
       breakpoint, but you need to specify the exact address; this can be
       obtained from:</para>
     
     <screen><userinput>show b</userinput></screen>
     
     <para>To single-step the kernel, try:</para>
     
     <screen><userinput>s</userinput></screen>
     
     <para>This will step into functions, but you can make DDB trace them until
       the matching return statement is reached by:</para>
     
     <screen><userinput>n</userinput></screen>
 
     <note>
       <para>This is different from <command>gdb</command>'s
 	<command>next</command> statement; it is like <command>gdb</command>'s
 	<command>finish</command>.</para>
     </note>
     
     <para>To examine data from memory, use (for example):
       	  
       <screen><userinput>x/wx 0xf0133fe0,40</userinput>
 <userinput>x/hd db_symtab_space</userinput>
 <userinput>x/bc termbuf,10</userinput>
 <userinput>x/s stringbuf</userinput></screen>
 	  
       for word/halfword/byte access, and hexadecimal/decimal/character/ string
       display.  The number after the comma is the object count.  To display
       the next 0x10 items, simply use:</para>
 	  
     <screen><userinput>x ,10</userinput></screen>
     
     <para>Similarly, use
 
       <screen><userinput>x/ia foofunc,10</userinput></screen>
 	  
       to disassemble the first 0x10 instructions of
       <function>foofunc</function>, and display them along with their offset
       from the beginning of <function>foofunc</function>.</para>
 
     <para>To modify memory, use the write command:</para>
     	  
     <screen><userinput>w/b termbuf 0xa 0xb 0</userinput>
 <userinput>w/w 0xf0010030 0 0</userinput></screen>
 	  
     <para>The command modifier
       (<literal>b</literal>/<literal>h</literal>/<literal>w</literal>)
       specifies the size of the data to be written, the first following
       expression is the address to write to and the remainder is interpreted
       as data to write to successive memory locations.</para>
 
     <para>If you need to know the current registers, use:</para>
 
     <screen><userinput>show reg</userinput></screen>
 
     <para>Alternatively, you can display a single register value by e.g.
 
       <screen><userinput>p $eax</userinput></screen>
 
       and modify it by:</para>
 
     <screen><userinput>set $eax new-value</userinput></screen>
 	  
     <para>Should you need to call some kernel functions from DDB, simply
       say:</para>
 
     <screen><userinput>call func(arg1, arg2, ...)</userinput></screen>
     
     <para>The return value will be printed.</para>
     
     <para>For a &man.ps.1; style summary of all running processes, use:</para>
     	  
     <screen><userinput>ps</userinput></screen>
     
     <para>Now you have examined why your kernel failed, and you wish to
       reboot.  Remember that, depending on the severity of previous
       malfunctioning, not all parts of the kernel might still be working as
       expected.  Perform one of the following actions to shut down and reboot
       your system:</para>
 
     <screen><userinput>panic</userinput></screen>
 	  
     <para>This will cause your kernel to dump core and reboot, so you can
       later analyze the core on a higher level with <command>gdb</command>.  This command
       usually must be followed by another <command>continue</command>
       statement.</para>
     
     <screen><userinput>call boot(0)</userinput></screen>
     
     <para>Which might be a good way to cleanly shut down the running system,
       <function>sync()</function> all disks, and finally reboot.  As long as
       the disk and filesystem interfaces of the kernel are not damaged, this
       might be a good way for an almost clean shutdown.</para>
     
     <screen><userinput>call cpu_reset()</userinput></screen>
     
     <para>This is the final way out of disaster and almost the same as hitting the
       Big Red Button.</para>
 
     <para>If you need a short command summary, simply type:</para>
     
     <screen><userinput>help</userinput></screen>
     
     <para>However, it is highly recommended to have a printed copy of the
 	&man.ddb.4; manual page ready for a debugging
       session.  Remember that it is hard to read the on-line manual while
       single-stepping the kernel.</para>
   </sect1>
   
-  <sect1>
+  <sect1 id="kerneldebug-online-gdb">
     <title>On-Line Kernel Debugging Using Remote GDB</title>
     
     <para>This feature has been supported since FreeBSD 2.2, and it is
       actually a very neat one.</para>
     
     <para>GDB has already supported <emphasis>remote debugging</emphasis> for
       a long time.  This is done using a very simple protocol along a serial
       line.  Unlike the other methods described above, you will need two
       machines for doing this.  One is the host providing the debugging
       environment, including all the sources, and a copy of the kernel binary
       with all the symbols in it, and the other one is the target machine that
       simply runs a similar copy of the very same kernel (but stripped of the
       debugging information).</para>
 
     <para>You should configure the kernel in question with <command>config
 	-g</command>, include <option>DDB</option> into the configuration, and
       compile it as usual.  This gives a large binary, due to the
       debugging information.  Copy this kernel to the target machine, strip
       the debugging symbols off with <command>strip -x</command>, and boot it
       using the <option>-d</option> boot option.  Connect the serial line
       of the target machine that has "flags 080" set on its sio device
       to any serial line of the debugging host.
       Now, on the debugging machine, go to the compile directory of the target
       kernel, and start <command>gdb</command>:</para>
 
     <screen>&prompt.user; <userinput>gdb -k kernel</userinput>
 GDB is free software and you are welcome to distribute copies of it
  under certain conditions; type "show copying" to see the conditions.
 There is absolutely no warranty for GDB; type "show warranty" for details.
 GDB 4.16 (i386-unknown-freebsd),
 Copyright 1996 Free Software Foundation, Inc...
 <prompt>(kgdb)</prompt> </screen>
 	  
     <para>Initialize the remote debugging session (assuming the first serial
       port is being used) by:</para>
 
     <screen><prompt>(kgdb)</prompt> <userinput>target remote /dev/cuaa0</userinput></screen>
 	  
     <para>Now, on the target host (the one that entered DDB right before even
       starting the device probe), type:</para>
     
     <screen>Debugger("Boot flags requested debugger")
 Stopped at Debugger+0x35: movb	$0, edata+0x51bc
 <prompt>db&gt;</prompt> <userinput>gdb</userinput></screen>
 	  
     <para>DDB will respond with:</para>
 		  
     <screen>Next trap will enter GDB remote protocol mode</screen>
     
     <para>Every time you type <command>gdb</command>, the mode will be toggled
       between remote GDB and local DDB.  In order to force a next trap
       immediately, simply type <command>s</command> (step).  Your hosting GDB
       will now gain control over the target kernel:</para>
 		  
     <screen>Remote debugging using /dev/cuaa0
 Debugger (msg=0xf01b0383 "Boot flags requested debugger")
     at ../../i386/i386/db_interface.c:257
 <prompt>(kgdb)</prompt></screen>
 		
     <para>You can use this session almost as any other GDB session, including
       full access to the source, running it in gud-mode inside an Emacs window
       (which gives you an automatic source code display in another Emacs
       window), etc.</para>
   </sect1>
   
-  <sect1>
+  <sect1 id="kerneldebug-kld">
     <title>Debugging Loadable Modules Using GDB</title>
     
     <para>When debugging a panic that occurred within a module, or
       using remote GDB against a machine that uses dynamic modules,
       you need to tell GDB how to obtain symbol information for those
       modules.</para>
 
     <para>First, you need to build the module(s) with debugging
       information:</para>
 
     <screen>&prompt.root; <userinput>cd /sys/modules/linux</userinput>
 &prompt.root; <userinput>make clean; make COPTS=-g</userinput></screen>
 	  
     <para>If you are using remote GDB, you can run
       <command>kldstat</command> on the target machine to find out
       where the module was loaded:</para>
 
     <screen>&prompt.root; <userinput>kldstat</userinput>
 Id Refs Address    Size     Name
  1    4 0xc0100000 1c1678   kernel
  2    1 0xc0a9e000 6000     linprocfs.ko
  3    1 0xc0ad7000 2000     warp_saver.ko
  4    1 0xc0adc000 11000    linux.ko</screen>
 
     <para>If you are debugging a crash dump, you will need to walk the
       <literal>linker_files</literal> list, starting at
       <literal>linker_files->tqh_first</literal> and following the
       <literal>link.tqe_next</literal> pointers until you find the
       entry with the <literal>filename</literal> you are looking for.
       The <literal>address</literal> member of that entry is the load
       address of the module.</para>
     
     <para>Next, you need to find out the offset of the text section
       within the module:</para>
 
     <screen>&prompt.root; <userinput>objdump --section-headers /sys/modules/linux/linux.ko | grep text</userinput>
   3 .rel.text     000016e0  000038e0  000038e0  000038e0  2**2
  10 .text         00007f34  000062d0  000062d0  000062d0  2**2</screen>
 
     <para>The one you want is the <literal>.text</literal> section,
       section 10 in the above example.  The fourth hexadecimal field
       (sixth field overall) is the offset of the text section within
       the file. Add this offset to the load address of the module to
       obtain the relocation address for the module's code. In our
       example, we get 0xc0adc000 + 0x62d0 = 0xc0ae22d0.  Use the
       <command>add-symbol-file</command> command in GDB to tell the
       debugger about the module:</para>
 
     <screen><prompt>(kgdb)</prompt> <userinput>add-symbol-file /sys/modules/linux/linux.ko 0xc0ae22d0</userinput>
 add symbol table from file "/sys/modules/linux/linux.ko" at text_addr = 0xc0ae22d0?
 (y or n) <userinput>y</userinput>
 Reading symbols from /sys/modules/linux/linux.ko...done.
 <prompt>(kgdb)</prompt></screen>
 	  
     <para>You should now have access to all the symbols in the
       module.</para>
   </sect1>
       
-  <sect1>
+  <sect1 id="kerneldebug-console">
     <title>Debugging a Console Driver</title>
 
     <para>Since you need a console driver to run DDB on, things are more
       complicated if the console driver itself is failing.  You might remember
       the use of a serial console (either with modified boot blocks, or by
       specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt),
       and hook up a standard terminal onto your first serial port.  DDB works
       on any configured console driver, including a serial
       console.</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/developers-handbook/kobj/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/kobj/chapter.sgml
index f8fd4d9851..b2ef1f689b 100644
--- a/en_US.ISO8859-1/books/developers-handbook/kobj/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/kobj/chapter.sgml
@@ -1,298 +1,298 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="kernel-objects">
   <title>Kernel Objects</title>
 
   <para>Kernel Objects, or <firstterm>Kobj</firstterm> provides an
     object-oriented C programming system for the kernel. As such the
     data being operated on carries the description of how to operate
     on it. This allows operations to be added and removed from an
     interface at run time and without breaking binary
     compatibility.</para>
 
-  <sect1>
+  <sect1 id="kernel-objects-term">
     <title>Terminology</title>
 
     <variablelist>
       <varlistentry>
 	<term>Object</term>
 	<listitem><para>A set of data - data structure - data
 	allocation.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Method</term>
 	<listitem>
 	  <para>An operation - function.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Class</term>
 	<listitem>
 	  <para>One or more methods.</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term>Interface</term>
 	<listitem>
 	  <para>A standard set of one or more methods.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
-  <sect1>
+  <sect1 id="kernel-objects-operation">
     <title>Kobj Operation</title>
 
     <para>Kobj works by generating descriptions of methods. Each
       description holds a unique id as well as a default function. The
       description's address is used to uniquely identify the method
       within a class' method table.</para>
 
     <para>A class is built by creating a method table associating one
       or more functions with method descriptions. Before use the class
       is compiled. The compilation allocates a cache and associates it
       with the class. A unique id is assigned to each method
       description within the method table of the class if not already
       done so by another referencing class compilation. For every
       method to be used a function is generated by script to qualify
       arguments and automatically reference the method description for
       a lookup. The generated function looks up the method by using
       the unique id associated with the method description as a hash
       into the cache associated with the object's class. If the method
       is not cached the generated function proceeds to use the class'
       table to find the method. If the method is found then the
       associated function within the class is used; otherwise, the
       default function associated with the method description is
       used.</para>
 
     <para>These indirections can be visualized as the
       following:</para>
 
     <programlisting>object->cache<->class</programlisting>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="kernel-objects-using">
     <title>Using Kobj</title>
 
     <sect2>
       <title>Structures</title>
 
       <programlisting>struct kobj_method</programlisting>
     </sect2>
 
     <sect2>
       <title>Functions</title>
 
       <programlisting>void kobj_class_compile(kobj_class_t cls);
 void kobj_class_compile_static(kobj_class_t cls, kobj_ops_t ops);
 void kobj_class_free(kobj_class_t cls);
 kobj_t kobj_create(kobj_class_t cls, struct malloc_type *mtype, int mflags);
 void kobj_init(kobj_t obj, kobj_class_t cls);
 void kobj_delete(kobj_t obj, struct malloc_type *mtype);</programlisting>
     </sect2>
 
     <sect2>
       <title>Macros</title>
 
       <programlisting>KOBJ_CLASS_FIELDS
 KOBJ_FIELDS
 DEFINE_CLASS(name, methods, size)
 KOBJMETHOD(NAME, FUNC)</programlisting>
     </sect2>
 
     <sect2>
       <title>Headers</title>
 
       <programlisting>&lt;sys/param.h>
 &lt;sys/kobj.h></programlisting>
     </sect2>
 
     <sect2>
       <title>Creating an interface template</title>
 
       <para>The first step in using Kobj is to create an
         Interface. Creating the interface involves creating a template
         that the script
         <filename>src/sys/kern/makeobjops.pl</filename> can use to
         generate the header and code for the method declarations and
         method lookup functions.</para>
 
       <para>Within this template the following keywords are used:
         <literal>#include</literal>, <literal>INTERFACE</literal>,
         <literal>CODE</literal>, <literal>METHOD</literal>,
         <literal>STATICMETHOD</literal>, and
         <literal>DEFAULT</literal>.</para>
 
       <para>The <literal>#include</literal> statement and what follows
         it is copied verbatim to the head of the generated code
         file.</para>
 
       <para>For example:</para>
 
       <programlisting>#include &lt;sys/foo.h></programlisting>
 
       <para>The <literal>INTERFACE</literal> keyword is used to define
         the interface name. This name is concatenated with each method
         name as [interface name]_[method name]. Its syntax is
         INTERFACE [interface name];.</para>
 
       <para>For example:</para>
 
       <programlisting>INTERFACE foo;</programlisting>
 
       <para>The <literal>CODE</literal> keyword copies its arguments
       verbatim into the code file. Its syntax is
       <literal>CODE { [whatever] };</literal></para>
 
       <para>For example:</para>
 
       <programlisting>CODE {
 	struct foo * foo_alloc_null(struct bar *)
 	{
 		return NULL;
 }
 };</programlisting>
 
       <para>The <literal>METHOD</literal> keyword describes a method. Its syntax is
       <literal>METHOD [return type] [method name] { [object [,
       arguments]] };</literal></para>
 
       <para>For example:</para>
 
       <programlisting>METHOD int bar {
 	struct object *;
 	struct foo *;
 	struct bar;
 };</programlisting>
 
       <para>The <literal>DEFAULT</literal> keyword may follow the
         <literal>METHOD</literal> keyword. It extends the
         <literal>METHOD</literal> key word to include the default
         function for method. The extended syntax is
         <literal>METHOD [return type] [method name] {
         [object; [other arguments]] }DEFAULT [default
         function];</literal></para>
 
       <para>For example:</para>
 
       <programlisting>METHOD int bar {
 	struct object *;
 	struct foo *;
 	int bar;
 } DEFAULT foo_hack;</programlisting>
 
       <para>The <literal>STATICMETHOD</literal> keyword is used like
       the <literal>METHOD</literal> keyword except the kobj data is not
       at the head of the object structure so casting to kobj_t would
       be incorrect. Instead <literal>STATICMETHOD</literal> relies on the Kobj data being
       referenced as 'ops'. This is also useful for calling
       methods directly out of a class's method table.</para>
 
       <para>Other complete examples:</para>
 
       <programlisting>src/sys/kern/bus_if.m
 src/sys/kern/device_if.m</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Creating a Class</title>
 
       <para>The second step in using Kobj is to create a class. A
         class consists of a name, a table of methods, and the size of
         objects if Kobj's object handling facilities are used. To
         create the class use the macro
         <function>DEFINE_CLASS()</function>. To create the method
         table create an array of kobj_method_t terminated by a NULL
         entry. Each non-NULL entry may be created using the macro
         <function>KOBJMETHOD()</function>.</para>
 
       <para>For example:</para>
 
       <programlisting>DEFINE_CLASS(fooclass, foomethods, sizeof(struct foodata));
 
 kobj_method_t foomethods[] = {
 	KOBJMETHOD(bar_doo, foo_doo),
 	KOBJMETHOD(bar_foo, foo_foo),
 	{ NULL, NULL}
 };</programlisting>
 
       <para>The class must be <quote>compiled</quote>.  Depending on
         the state of the system at the time that the class is to be
         initialized a statically allocated cache, <quote>ops
         table</quote> have to be used. This can be accomplished by
         declaring a <structname>struct kobj_ops</structname> and using
         <function>kobj_class_compile_static();</function> otherwise,
         <function>kobj_class_compile()</function> should be used.</para>
     </sect2>
 
     <sect2>
       <title>Creating an Object</title>
 
       <para>The third step in using Kobj involves how to define the
         object. Kobj object creation routines assume that Kobj data is
         at the head of an object. If this in not appropriate you will
         have to allocate the object yourself and then use
         <function>kobj_init()</function> on the Kobj portion of it;
         otherwise, you may use <function>kobj_create()</function> to
         allocate and initialize the Kobj portion of the object
         automatically. <function>kobj_init()</function> may also be
         used to change the class that an object uses.</para>
 
       <para>To integrate Kobj into the object you should use the macro
        KOBJ_FIELDS.</para>
 
       <para>For example</para>
 
       <programlisting>struct foo_data {
 	KOBJ_FIELDS;
 	foo_foo;
 	foo_bar;
 };</programlisting>
     </sect2>
 
     <sect2>
       <title>Calling Methods</title>
 
       <para>The last step in using Kobj is to simply use the generated
 	functions to use the desired method within the object's
 	class. This is as simple as using the interface name and the
 	method name with a few modifications. The interface name
 	should be concatenated with the method name using a '_'
 	between them, all in upper case.</para>
 
       <para>For example, if the interface name was foo and the method
       was bar then the call would be:</para>
 
       <programlisting>[return value = ] FOO_BAR(object [, other parameters]);</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Cleaning Up</title>
 
       <para>When an object allocated through
         <function>kobj_create()</function> is no longer needed
         <function>kobj_delete()</function> may be called on it, and
         when a class is no longer being used
         <function>kobj_class_free()</function> may be called on it.</para>
     </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.sgml
index bd31ac41c0..80e8686485 100644
--- a/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.sgml
@@ -1,82 +1,82 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
   <chapter id="l10n">
     <title>Localization and Internationalization - L10N and I18N</title>
 
-    <sect1>
+    <sect1 id="l10n-programming">
       <title>Programming I18N Compliant Applications</title>
       <indexterm><primary>Qt</primary></indexterm>
       <indexterm><primary>GTK</primary></indexterm>
       <para>To make your application more useful for speakers of other
 	languages, we hope that you will program I18N compliant.  The GNU
 	gcc compiler and GUI libraries like QT and GTK support I18N through
 	special handling of strings.  Making a program I18N compliant is
 	very easy.  It allows contributors to port your application to
 	other languages quickly.  Refer to the library specific I18N
 	documentation for more details.</para>
 
       <para>In contrast with common perception, I18N compliant code is
 	easy to write.  Usually, it only involves wrapping your strings
 	with library specific functions.  In addition, please be sure to
 	allow for wide or multibyte character support.</para>
 
       <sect2>
 	<title>A Call to Unify the I18N Effort</title>
 
 	<para>It has come to our attention that the individual I18N/L10N
 	  efforts for each country has been repeating each others'
 	  efforts.  Many of us have been reinventing the wheel repeatedly
 	  and inefficiently.  We hope that the various major groups in
 	  I18N could congregate into a group effort similar to the Core
 	  Team's responsibility.</para>
 
 	<para>Currently, we hope that, when you write or port I18N
 	  programs, you would send it out to each country's related
 	  FreeBSD mailing list for testing.  In the future, we hope to
 	  create applications that work in all the languages
 	  out-of-the-box without dirty hacks.</para>
 
 	<para>The &a.i18n; has been established.  If you are an I18N/L10N
 	  developer, please send your comments, ideas, questions, and
 	  anything you deem related to it.</para>
 	
 	<para> Michael C. Wu will be maintaining an I18N works in progress
 	  homepage at <ulink
 	  url="http://www.FreeBSD.org/~keichii/i18n/index.html">http://www.FreeBSD.org/~keichii/i18n/index.html</ulink>
 	  Please also read the BSDCon2000 I18N paper and presentations
 	  by Clive Lin, Chia-Liang Kao, and Michael C. Wu at <ulink
 	  url="http://www.FreeBSD.org/~keichii/papers/">http://www.FreeBSD.org/~keichii/papers/</ulink></para>
       </sect2>
 
       <sect2>
 	<title>Perl and Python</title>
         <indexterm>
          <primary>Perl</primary>
         </indexterm>
         <indexterm>
           <primary>Python</primary>
         </indexterm>
 
 	<para>Perl and Python have I18N and wide character handling
 	  libraries.  Please use them for I18N compliance.</para>
 
 	<para>In older FreeBSD versions,
 	  Perl may give warnings about not having a wide character locale
 	  installed on your system.  You can set the
 	  environment variable <envar>LD_PRELOAD</envar> to
 	  <filename>/usr/lib/libxpg4.so</filename> in your shell.</para>
 
 	<para>In <literal>sh</literal>-based shells:</para>
 
 	<programlisting><envar>LD_PRELOAD=/usr/lib/libxpg4.so</envar></programlisting>
 
 	<para>In <literal>C</literal>-based shells:</para>
 
 	<programlisting><envar>setenv LD_PRELOAD /usr/lib/libxpg4.so</envar></programlisting>
       </sect2>
     </sect1>
 </chapter>
diff --git a/en_US.ISO8859-1/books/developers-handbook/locking/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/locking/chapter.sgml
index 00501a8d2f..e604ef443b 100644
--- a/en_US.ISO8859-1/books/developers-handbook/locking/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/locking/chapter.sgml
@@ -1,333 +1,333 @@
 <!--
      The FreeBSD Documentation Project
      The FreeBSD SMP Next Generation Project
 
      $FreeBSD$
 -->
 
 <chapter id="locking">
   <title>Locking Notes</title>
 
   <para><emphasis>This chapter is maintained by the FreeBSD SMP Next
     Generation Project.  Please direct any comments or suggestions
     to its &a.smp;.</emphasis></para>
 
 
   <para>This document outlines the locking used in the FreeBSD kernel
     to permit effective multi-processing within the kernel.  Locking
     can be achieved via several means.  Data structures can be
     protected by mutexes or &man.lockmgr.9; locks.  A few variables
     are protected simply by always using atomic operations to access
     them.</para>
 
-  <sect1>
+  <sect1 id="locking-mutexes">
     <title>Mutexes</title>
 
     <para>A mutex is simply a lock used to guarantee mutual exclusion.
       Specifically, a mutex may only be owned by one entity at a time.
       If another entity wishes to obtain a mutex that is already
       owned, it must wait until the mutex is released.  In the FreeBSD
       kernel, mutexes are owned by processes.</para>
 
     <para>Mutexes may be recursively acquired, but they are intended
       to be held for a short period of time.  Specifically, one may
       not sleep while holding a mutex.  If you need to hold a lock
       across a sleep, use a &man.lockmgr.9; lock.</para>
     
     <para>Each mutex has several properties of interest:</para>
 
     <variablelist>
 	<varlistentry>
 	<term>Variable Name</term>
 	<listitem>
 	  <para>The name of the <type>struct mtx</type> variable in
 	    the kernel source.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Logical Name</term>
 	<listitem>
 	  <para>The name of the mutex assigned to it by
 	    <function>mtx_init</function>.  This name is displayed in
 	    KTR trace messages and witness errors and warnings and is
 	    used to distinguish mutexes in the witness code.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Type</term>
 	<listitem>
 	  <para>The type of the mutex in terms of the
 	    <constant>MTX_*</constant> flags.  The meaning for each
 	    flag is related to its meaning as documented in
 	    &man.mutex.9;.</para>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term><constant>MTX_DEF</constant></term>
 	      <listitem>
 		<para>A sleep mutex</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><constant>MTX_SPIN</constant></term>
 	      <listitem>
 		<para>A spin mutex</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><constant>MTX_COLD</constant></term>
 	      <listitem>
 		<para>This mutex is initialized very early.  Thus, it
 		  must be declared via
 		  <function>MUTEX_DECLARE</function>, and the
 		  <constant>MTX_COLD</constant> flag must be passed to
 		  <function>mtx_init</function>.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><constant>MTX_TOPHALF</constant></term>
 	      <listitem>
 		<para>This spin mutex does not disable
 		  interrupts.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><constant>MTX_NORECURSE</constant></term>
 	      <listitem>
 		<para>This mutex is not allowed to recurse.</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Protectees</term>
 	<listitem>
 	  <para>A list of data structures or data structure members
 	    that this entry protects.  For data structure members, the
 	    name will be in the form of
 	    <structname/structure name/.<structfield/member name/.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Dependent Functions</term>
 	<listitem>
 	  <para>Functions that can only be called if this mutex is
 	    held.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <table frame="all" colsep="1" rowsep="1" pgwide="1">
       <title>Mutex List</title>
       
       <tgroup cols="5">
 	<thead>
 	  <row>
 	    <entry>Variable Name</entry>
 	    <entry>Logical Name</entry>
 	    <entry>Type</entry>
 	    <entry>Protectees</entry>
 	    <entry>Dependent Functions</entry>
 	  </row>
 	</thead>
 	
 	<!-- The scheduler lock -->
 	<tbody>
 	  <row>
 	    <entry>sched_lock</entry>
 	    <entry><quote>sched lock</quote></entry>
 	    <entry>
 	      <constant>MTX_SPIN</constant> |
 	      <constant>MTX_COLD</constant>
 	    </entry>
 	    <entry>
 	      <varname>_gmonparam</varname>,
 	      <varname>cnt.v_swtch</varname>,
 	      <varname>cp_time</varname>,
 	      <varname>curpriority</varname>,
 	      <structname/mtx/.<structfield/mtx_blocked/,
 	      <structname/mtx/.<structfield/mtx_contested/,
 	      <structname/proc/.<structfield/p_contested/,
 	      <structname/proc/.<structfield/p_blocked/,
 	      <structname/proc/.<structfield/p_flag/
 		(<constant>P_PROFIL</constant> XXX,
 		 <constant>P_INMEM</constant>,
 	         <constant>P_SINTR</constant>,
 	         <constant>P_TIMEOUT</constant>,
 	         <constant>P_SWAPINREQ</constant> XXX,
 	         <constant>P_INMEN</constant> XXX),
 	      <structname/proc/.<structfield/p_nice/,
 	      <structname/proc/.<structfield/p_procq/,
 	      <structname/proc/.<structfield/p_blocked/,
 	      <structname/proc/.<structfield/p_estcpu/,
 	      <structname/proc/.<structfield/p_nativepri/,
 	      <structname/proc/.<structfield/p_priority/,
 	      <structname/proc/.<structfield/p_usrpri/,
 	      <structname/proc/.<structfield/p_rtprio/,
 	      <structname/proc/.<structfield/p_rqindex/,
 	      <structname/proc/.<structfield/p_stats->p_prof/,
 	      <structname/proc/.<structfield/p_stats->p_ru/,
 	      <structname/proc/.<structfield/p_stat/,
 	      <structname/proc/.<structfield/p_cpticks/
 	      <structname/proc/.<structfield/p_iticks/,
 	      <structname/proc/.<structfield/p_uticks/,
 	      <structname/proc/.<structfield/p_sticks/,
 	      <structname/proc/.<structfield/p_swtime/,
 	      <structname/proc/.<structfield/p_slptime/,
 	      <structname/proc/.<structfield/p_runtime/,
 	      <structname/proc/.<structfield/p_pctcpu/,
 	      <structname/proc/.<structfield/p_oncpu/,
 	      <structname/proc/.<structfield/p_asleep/,
 	      <structname/proc/.<structfield/p_wchan/,
 	      <structname/proc/.<structfield/p_wmesg/,
 	      <structname/proc/.<structfield/p_slpq/,
 	      <structname/proc/.<structfield/p_vmspace/
 		(XXX - in <function>statclock</function>),
 	      <varname>pscnt</varname>,
 	      <varname>slpque</varname>,
 	      <varname>itqueuebits</varname>,
 	      <varname>itqueues</varname>,
 	      <varname>rtqueuebits</varname>,
 	      <varname>rtqueues</varname>,
 	      <varname>queuebits</varname>,
 	      <varname>queues</varname>,
 	      <varname>idqueuebits</varname>,
 	      <varname>idqueues</varname>,
 	      <varname>switchtime</varname>,
 	    </entry>
 	    <entry>
 	      <function>setrunqueue</function>,
 	      <function>remrunqueue</function>,
 	      <function>mi_switch</function>,
 	      <function>chooseproc</function>,
 	      <function>schedclock</function>,
 	      <function>resetpriority</function>,
 	      <function>updatepri</function>,
 	      <function>maybe_resched</function>,
 	      <function>cpu_switch</function>,
 	      <function>cpu_throw</function>
 	    </entry>
 	  </row>
 
 	  <!-- The vm86 pcb lock -->
 	  <row>
 	    <entry>vm86pcb_lock</entry>
 	    <entry><quote>vm86pcb lock</quote></entry>
 	    <entry>
 	      <constant>MTX_DEF</constant> |
 	      <constant>MTX_COLD</constant>
 	    </entry>
 	    <entry>
 	      <varname>vm86pcb</varname>
 	    </entry>
 	    <entry>
 	      <function>vm86_bioscall</function>
 	    </entry>
 	  </row>
 
 	  <!-- Giant -->
 	  <row>
 	    <entry>Giant</entry>
 	    <entry><quote>Giant</quote></entry>
 	    <entry>
 	      <constant>MTX_DEF</constant> |
 	      <constant>MTX_COLD</constant>
 	    </entry>
 	    <entry>nearly everything</entry>
 	    <entry>lots</entry>
 	  </row>
 
 	  <!-- The callout lock -->
 	  <row>
 	    <entry>callout_lock</entry>
 	    <entry><quote>callout lock</quote></entry>
 	    <entry>
 	      <constant>MTX_SPIN</constant>
 	    </entry>
 	    <entry>
 	      <varname>callfree</varname>,
 	      <varname>callwheel</varname>,
 	      <varname>nextsoftcheck</varname>,
 	      <structname/proc/.<structfield/p_itcallout/,
 	      <structname/proc/.<structfield/p_slpcallout/,
 	      <varname>softticks</varname>,
 	      <varname>ticks</varname>
 	    </entry>
 	    <entry>
 	    </entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
   </sect1>
 
-  <sect1>
+  <sect1 id="locking-lockmgr">
     <title>Lock Manager Locks</title>
 
     <para>Locks that are provided via the &man.lockmgr.9; interface
       are lock manager locks.  These locks are reader-writer locks and
       may be held by a sleeping process.</para>
 
     <table>
       <title>&man.lockmgr.9; Lock List</title>
 
       <tgroup cols="2">
 	<thead>
 	  <row>
 	    <entry>Variable Name</entry>
 	    <entry>Protectees</entry>
 	  </row>
 	</thead>
 	<tbody>
 	  <row>
 	    <entry><varname>allproc_lock</varname></entry>
 	    <entry>
 	      <varname>allproc</varname>
 	      <varname>zombproc</varname>
 	      <varname>pidhashtbl</varname>
 	      <structname/proc/.<structfield/p_list/
 	      <structname/proc/.<structfield/p_hash/
 	      <varname>nextpid</varname>
 	    </entry>
 	    <entry><varname>proctree_lock</varname></entry>
 	    <entry>
 	      <structname/proc/.<structfield/p_children/
 	      <structname/proc/.<structfield/p_sibling/
 	    </entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
   </sect1>
 
-  <sect1>
+  <sect1 id="locking-atomic">
     <title>Atomically Protected Variables</title>
 
     <para>An atomically protected variable is a special variable that
       is not protected by an explicit lock.  Instead, all data
       accesses to the variables use special atomic operations as
       described in &man.atomic.9;.  Very few variables are treated
       this way, although other synchronization primitives such as
       mutexes are implemented with atomically protected
       variables.</para>
 
     <itemizedlist>
       <listitem>
 	<para><varname>astpending</varname></para>
       </listitem>
 
       <listitem>
 	<para><structname/mtx/.<structfield/mtx_lock/</para>
       </listitem>
     </itemizedlist>
   </sect1>
 </chapter>
diff --git a/en_US.ISO8859-1/books/developers-handbook/pci/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/pci/chapter.sgml
index 15146dc9e9..c422ec49d3 100644
--- a/en_US.ISO8859-1/books/developers-handbook/pci/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/pci/chapter.sgml
@@ -1,369 +1,369 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="pci">
   <title>PCI Devices</title>
 
   <para>This chapter will talk about the FreeBSD mechanisms for
     writing a device driver for a device on a PCI bus.</para>
 
-  <sect1>
+  <sect1 id="pci-probe">
     <title>Probe and Attach</title>
 
     <para>Information here about how the PCI bus code iterates through
       the unattached devices and see if a newly loaded kld will attach
       to any of them.</para>
 
 <programlisting>/*
  * Simple KLD to play with the PCI functions.
  *
  * Murray Stokely
  */
 
 #define MIN(a,b) (((a) < (b)) ? (a) : (b))
 
 #include &lt;sys/types.h&gt;
 #include &lt;sys/module.h&gt;
 #include &lt;sys/systm.h&gt;  /* uprintf */ 
 #include &lt;sys/errno.h&gt;
 #include &lt;sys/param.h&gt;  /* defines used in kernel.h */
 #include &lt;sys/kernel.h&gt; /* types used in module initialization */
 #include &lt;sys/conf.h&gt;   /* cdevsw struct */
 #include &lt;sys/uio.h&gt;    /* uio struct */
 #include &lt;sys/malloc.h&gt;
 #include &lt;sys/bus.h&gt;	/* structs, prototypes for pci bus stuff */
 
 #include &lt;pci/pcivar.h&gt; /* For get_pci macros! */
 
 /* Function prototypes */
 d_open_t      mypci_open;
 d_close_t     mypci_close;
 d_read_t      mypci_read;
 d_write_t     mypci_write;
 
 /* Character device entry points */
 
 static struct cdevsw mypci_cdevsw = {
   mypci_open,
   mypci_close,
   mypci_read,
   mypci_write,
   noioctl,
   nopoll,
   nommap,
   nostrategy,
   "mypci",
   36,                   /* reserved for lkms - /usr/src/sys/conf/majors */
   nodump,
   nopsize,
   D_TTY,
   -1
 };
 
 /* vars */
 static dev_t sdev;
 
 /* We're more interested in probe/attach than with
    open/close/read/write at this point */
 
 int 
 mypci_open(dev_t dev, int oflags, int devtype, struct proc *p)
 {
   int err = 0;
 
   uprintf("Opened device \"mypci\" successfully.\n");
   return(err);
 }
 
 int 
 mypci_close(dev_t dev, int fflag, int devtype, struct proc *p)
 {
   int err=0;
 
   uprintf("Closing device \"mypci.\"\n"); 
   return(err);
 } 
 
 int
 mypci_read(dev_t dev, struct uio *uio, int ioflag)
 {
   int err = 0;
 
   uprintf("mypci read!\n");
   return err;
 }
 
 int
 mypci_write(dev_t dev, struct uio *uio, int ioflag)
 {
   int err = 0;
 
   uprintf("mypci write!\n");
   return(err);
 }
 
 /* PCI Support Functions */
 
 /*
  * Return identification string if this is device is ours.
  */
 static int
 mypci_probe(device_t dev)
 {
   uprintf("MyPCI Probe\n"
 	  "Vendor ID : 0x%x\n"
 	  "Device ID : 0x%x\n",pci_get_vendor(dev),pci_get_device(dev));
 
   if (pci_get_vendor(dev) == 0x11c1) {
     uprintf("We've got the Winmodem, probe successful!\n");
     return 0;
   }
 
   return ENXIO;
 }
 
 /* Attach function is only called if the probe is successful */
 
 static int
 mypci_attach(device_t dev)
 {
   uprintf("MyPCI Attach for : deviceID : 0x%x\n",pci_get_vendor(dev));
   sdev = make_dev(<literal>&</literal>mypci_cdevsw,
 		  0,
 		  UID_ROOT,
 		  GID_WHEEL,
 		  0600,
 		  "mypci");
   uprintf("Mypci device loaded.\n");
   return ENXIO;
 }
 
 /* Detach device. */
 
 static int
 mypci_detach(device_t dev)
 {
   uprintf("Mypci detach!\n");
   return 0;
 }
 
 /* Called during system shutdown after sync. */
 
 static int
 mypci_shutdown(device_t dev)
 {
   uprintf("Mypci shutdown!\n");
   return 0;
 }
 
 /*
  * Device suspend routine.  
  */
 static int
 mypci_suspend(device_t dev)
 {
   uprintf("Mypci suspend!\n");
   return 0;
 }
 
 /*
  * Device resume routine.
  */
 
 static int
 mypci_resume(device_t dev)
 {
   uprintf("Mypci resume!\n");
   return 0;
 }
 
 static device_method_t mypci_methods[] = {
 	/* Device interface */
 	DEVMETHOD(device_probe,		mypci_probe),
 	DEVMETHOD(device_attach,	mypci_attach),
 	DEVMETHOD(device_detach,	mypci_detach),
 	DEVMETHOD(device_shutdown,	mypci_shutdown),
 	DEVMETHOD(device_suspend,	mypci_suspend),
 	DEVMETHOD(device_resume,	mypci_resume),
 
 	{ 0, 0 }
 };
 
 static driver_t mypci_driver = {
 	"mypci",
 	mypci_methods,
 	0,
 	/*	sizeof(struct mypci_softc), */
 };
 
 static devclass_t mypci_devclass;
 
 DRIVER_MODULE(mypci, pci, mypci_driver, mypci_devclass, 0, 0);</programlisting>
       
     <para>Additional Resources
     <itemizedlist>
       <listitem><simpara><ulink url="http://www.pcisig.org/">PCI
 	Special Interest Group</ulink></simpara></listitem>
 
       <listitem><simpara>PCI System Architecture, Fourth Edition by
 	Tom Shanley, et al.</simpara></listitem>
 
     </itemizedlist>
     </para>
   </sect1>
 
-  <sect1>
+  <sect1 id="pci-bus">
     <title>Bus Resources</title>
 
     <para>FreeBSD provides an object-oriented mechanism for requesting
       resources from a parent bus.  Almost all devices will be a child
       member of some sort of bus (PCI, ISA, USB, SCSI, etc) and these
       devices need to acquire resources from their parent bus (such as
       memory segments, interrupt lines, or DMA channels).</para>
 
     <sect2>
       <title>Base Address Registers</title>
 
       <para>To do anything particularly useful with a PCI device you
       will need to obtain the <emphasis>Base Address
       Registers</emphasis> (BARs) from the PCI Configuration space.
       The PCI-specific details of obtaining the BAR is abstracted in
       the <function>bus_alloc_resource()</function> function.</para>
 
       <para>For example, a typical driver might have something similar
       to this in the <function>attach()</function> function:</para>
 
 <programlisting>    sc->bar0id = 0x10;
     sc->bar0res = bus_alloc_resource(dev, SYS_RES_MEMORY, &amp;(sc->bar0id),
 				  0, ~0, 1, RF_ACTIVE);
     if (sc->bar0res == NULL) {
         uprintf("Memory allocation of PCI base register 0 failed!\n");
         error = ENXIO;
         goto fail1;
     }
 
     sc->bar1id = 0x14;
     sc->bar1res = bus_alloc_resource(dev, SYS_RES_MEMORY, &amp;(sc->bar1id),
 				  0, ~0, 1, RF_ACTIVE);
     if (sc->bar1res == NULL) {
         uprintf("Memory allocation of PCI base register 1 failed!\n");
         error =  ENXIO;
         goto fail2;
     }
     sc->bar0_bt = rman_get_bustag(sc->bar0res);
     sc->bar0_bh = rman_get_bushandle(sc->bar0res);
     sc->bar1_bt = rman_get_bustag(sc->bar1res);
     sc->bar1_bh = rman_get_bushandle(sc->bar1res);
 
 </programlisting>
 
       <para>Handles for each base address register are kept in the
         <structname>softc</structname> structure so that they can be
         used to write to the device later.</para>
 
       <para>These handles can then be used to read or write from the
         device registers with the <function>bus_space_*</function>
         functions.  For example, a driver might contain a shorthand
         function to read from a board specific register like this:</para>
 
 <programlisting>uint16_t
 board_read(struct ni_softc *sc, uint16_t address) {
     return bus_space_read_2(sc->bar1_bt, sc->bar1_bh, address);
 }
 </programlisting>
 
       <para>Similarly, one could write to the registers with:</para>
 
 <programlisting>void
 board_write(struct ni_softc *sc, uint16_t address, uint16_t value) {
     bus_space_write_2(sc->bar1_bt, sc->bar1_bh, address, value);
 }
 </programlisting>
 
       <para>These functions exist in 8bit, 16bit, and 32bit versions
         and you should use
         <function>bus_space_{read|write}_{1|2|4}</function>
         accordingly.</para>
 
     </sect2>
     <sect2>
       <title>Interrupts</title>
 
       <para>Interrupts are allocated from the object-oriented bus code
         in a way similar to the memory resources.  First an IRQ
         resource must be allocated from the parent bus, and then the
         interrupt handler must be setup to deal with this IRQ.</para>
 
       <para>Again, a sample from a device
         <function>attach()</function> function says more than
         words.</para>
 
 <programlisting>/* Get the IRQ resource */
 
     sc->irqid = 0x0;
     sc->irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &amp;(sc->irqid),
 				  0, ~0, 1, RF_SHAREABLE | RF_ACTIVE);
     if (sc->irqres == NULL) {
 	uprintf("IRQ allocation failed!\n");
 	error = ENXIO;
 	goto fail3;
     }
 
     /* Now we should setup the interrupt handler */
 
     error = bus_setup_intr(dev, sc->irqres, INTR_TYPE_MISC,
 			   my_handler, sc, &amp;(sc->handler));
     if (error) {
 	printf("Couldn't set up irq\n");
 	goto fail4;
     }
 
     sc->irq_bt = rman_get_bustag(sc->irqres);
     sc->irq_bh = rman_get_bushandle(sc->irqres);
 </programlisting>
 
     </sect2>
 
     <sect2>
       <title>DMA</title>
       <para>On the PC, peripherals that want to do bus-mastering DMA
       must deal with physical addresses.  This is a problem since
       FreeBSD uses virtual memory and deals almost exclusively with
       virtual addresses.  Fortunately, there is a function,
       <function>vtophys()</function> to help.</para>
 
 <programlisting>#include &lt;vm/vm.h&gt;
 #include &lt;vm/pmap.h&gt;
 
 #define vtophys(virtual_address) (...)
 </programlisting>
 
       <para>The solution is a bit different on the alpha however, and
         what we really want is a function called
         <function>vtobus()</function>.</para>
 
 <programlisting>#if defined(__alpha__)
 #define vtobus(va)      alpha_XXX_dmamap((vm_offset_t)va)
 #else
 #define vtobus(va)      vtophys(va)
 #endif
 </programlisting>
 
     </sect2>
 
     <sect2>
       <title>Deallocating Resources</title>
 
       <para>It is very important to deallocate all of the resources
         that were allocated during <function>attach()</function>.
         Care must be taken to deallocate the correct stuff even on a
         failure condition so that the system will remain usable while
         your driver dies.</para>
 
     </sect2>
   </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 fa00f66106..bfbb5e6bfb 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$
 -->
 
 <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>
+  <sect1 id="scsi-synopsis">
     <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 <quote>recommended</quote>.</para>
 
    <para>The document is illustrated with examples in
      pseudo-code. Although sometimes the examples have many details
      and look like real code, it is 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>
+  <sect1 id="scsi-general">
     <title>General architecture</title>
 
     <para>CAM stands for Common Access Method. It is 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 do not describe
       here.</para>
 
     <para>This is achieved in multiple steps: first it is 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 is 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 <quote>ncr</quote> or <quote>wds</quote>.</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 <quote>wds0</quote> 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 <quote>path</quote>. 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 is 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 <quote>all devices</quote>)</para></listitem>
 
       <listitem><para>SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means
         <quote>all LUNs</quote>)</para></listitem>
     </itemizedlist>
 
     <para>If the driver can not allocate this path it will not 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 is 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 <quote>CAM Control Block</quote>. 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
       (<quote>normal</quote>) 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 is 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 <quote>bitwise or</quote> 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_release_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 <quote>struct ccb_scsiio csio</quote> 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 - do not 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 ca not 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 is OK to return the CCB with
         the status CAM_REQ_INVALID, the current drivers do that.  But
         it is 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 do not 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 is 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 is 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 is 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 <quote>BUS
     DEVICE RESET</quote> 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 <quote>struct
       ccb_abort cab</quote> 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 is 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 do not 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 is 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 <quote>struct ccb_trans_setting cts</quote> 
 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 is 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 <quote>new current
       settings</quote> 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 <quote>current</quote> 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 <quote>struct
       ccb_trans_setting cts</quote> 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 <quote>struct
       ccb_calc_geometry ccg</quote> 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 <quote>extended translation</quote> 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 <quote>struct
 ccb_pathinq cpi</quote> 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>
+  <sect1 id="scsi-polling">
     <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>
+  <sect1 id="scsi-async">
     <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>
+  <sect1 id="scsi-interrupts">
     <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
       <quote>typical</quote> 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 will not
       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>
+  <sect1 id="scsi-errors">
     <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 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> -
         <quote>impossible</quote> 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>
+  <sect1 id="scsi-timeout">
     <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 is 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 351b0cc8d3..3fc3d9a00b 100644
--- a/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml
@@ -1,517 +1,517 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
     <chapter id="secure">
       <title>Secure Programming</title>
 
       <para>This chapter was written by &a.murray;.</para>
 
-      <sect1><title>Synopsis</title>
+      <sect1 id="secure-synopsis"><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> 
+      <sect1 id="secure-bufferov"><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 <ulink
           URL="http://immunix.org/stackguard.html">StackGuard
           website</ulink>:
 
         <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>
+      <sect1 id="secure-setuid"><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 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>
+      <sect1 id="secure-trust"><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 filesystem 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 from 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/developers-handbook/sound/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/sound/chapter.sgml
index 38f39f1e78..9ece7bbd03 100644
--- a/en_US.ISO8859-1/books/developers-handbook/sound/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/sound/chapter.sgml
@@ -1,687 +1,687 @@
 <!--
      The FreeBSD Documentation Project
 
     $FreeBSD$
 -->
 
 <chapter id="oss">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Jean-Francois</firstname>
 	<surname>Dockes</surname>
 	<contrib>Contributed by </contrib>
       </author>
     </authorgroup>
     <!-- 23 November 2001 -->
   </chapterinfo>
 
   <title>Sound subsystem</title>
   
-  <sect1>
+  <sect1 id="oss-intro">
     <title>Introduction</title>
     
     <para>The FreeBSD sound subsystem cleanly separates generic sound
       handling issues from device-specific ones.  This makes it easier
       to add support for new hardware.</para>
 
     <para>The &man.pcm.4; framework is the central piece of the sound
       subsystem.  It mainly implements the following elements:</para>
 
     <itemizedlist>
       <listitem>
         <para>A system call interface (read, write, ioctls) to
           digitized sound and mixer functions.  The ioctl command set
           is compatible with the legacy <emphasis>OSS</emphasis> or
           <emphasis>Voxware</emphasis> interface, allowing common
           multimedia applications to be ported without
           modification.</para>
       <listitem>
         <para>Common code for processing sound data (format
           conversions, virtual channels).</para>
       </listitem>
       <listitem>
         <para>A uniform software interface to hardware-specific audio
           interface modules.</para>
       </listitem>
       <listitem>
         <para>Additional support for some common hardware interfaces
           (ac97), or shared hardware-specific code (ex: ISA DMA
           routines).</para> 
       </listitem>
     </itemizedlist>
 
     <para>The support for specific sound cards is implemented by
       hardware-specific drivers, which provide channel and mixer interfaces
       to plug into the generic <devicename>pcm</devicename> code.</para>
 
     <para>In this chapter, the term <devicename>pcm</devicename> will
       refer to the central, common part of the sound driver, as
       opposed to the hardware-specific modules.</para>
 
     <para>The prospective driver writer will of course want to start
       from an existing module and use the code as the ultimate
       reference.  But, while the sound code is nice and clean, it is
       also mostly devoid of comments.  This document tries to give an
       overview of the framework interface and answer some questions
       that may arise while adapting the existing code.</para>
 
     <para>As an alternative, or in addition to starting from a working
       example, you can find a commented driver template at
       <ulink url="http://people.freebsd.org/~cg/template.c">
        http://people.freebsd.org/~cg/template.c</ulink></para>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="oss-files">
     <title>Files</title>
 
     <para>All the relevant code currently (FreeBSD 4.4) lives in
       <filename>/usr/src/sys/dev/sound/</filename>, except for the
       public ioctl interface definitions, found in
       <filename>/usr/src/sys/sys/soundcard.h</filename></para>
 
     <para>Under <filename>/usr/src/sys/dev/sound/</filename>, the
       <filename>pcm/</filename> directory holds the central code,
       while the <filename>isa/</filename> and
       <filename>pci/</filename> directories have the drivers for ISA
       and PCI boards.</para>
 
   </sect1>
 
   <sect1 id="pcm-probe-and-attach">
     <title>Probing, attaching, etc.</title>
 
     <para>Sound drivers probe and attach in almost the same way as any
       hardware driver module.  You might want to look at the <link
       linkend="isa-driver"> ISA</link> or <link
       linkend="pci">PCI</link> specific sections of the handbook for
       more information.</para>
       
     <para>However, sound drivers differ in some ways:</para>
 
     <itemizedlist>
 
       <listitem>
         <para>They declare themselves as <devicename>pcm</devicename>
           class devices, with a <structname>struct
           snddev_info</structname> device private structure:</para>
 
           <programlisting>          static driver_t xxx_driver = {
               "pcm",
               xxx_methods,
               sizeof(struct snddev_info)
           };
 
           DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0);
           MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER);</programlisting>
 
         <para>Most sound drivers need to store additional private
           information about their device.  A private data structure is
           usually allocated in the attach routine.  Its address is
           passed to <devicename>pcm</devicename> by the calls to
           <function>pcm_register()</function> and
           <function>mixer_init()</function>.
           <devicename>pcm</devicename> later passes back this address
           as a parameter in calls to the sound driver
           interfaces.</para>
       </listitem>
 
       <listitem>
         <para>The sound driver attach routine should declare its MIXER
           or AC97 interface to <devicename>pcm</devicename> by calling
           <function>mixer_init()</function>.  For a MIXER interface,
           this causes in turn a call to <link linkend="xxxmixer-init">
           <function>xxxmixer_init()</function></link>.</para>
       </listitem>
 
       <listitem>
         <para>The sound driver attach routine declares its general
           CHANNEL configuration to <devicename>pcm</devicename> by
           calling <function>pcm_register(dev, sc, nplay,
           nrec)</function>, where <varname>sc</varname> is the address
           for the device data structure, used in further calls from
           <devicename>pcm</devicename>, and <varname>nplay</varname>
           and <varname>nrec</varname> are the number of play and
           record channels.</para>
       </listitem>
 
       <listitem>
         <para>The sound driver attach routine declares each of its
           channel objects by calls to
           <function>pcm_addchan()</function>.  This sets up the
           channel glue in <devicename>pcm</devicename> and causes in
           turn a call to
             <link linkend="xxxchannel-init">
             <function>xxxchannel_init()</function></link>.</para>
       </listitem>
 
       <listitem>
         <para>The sound driver detach routine should call
         <function>pcm_unregister()</function> before releasing its
         resources.</para>
       </listitem>
     </itemizedlist>
       
     <para>There are two possible methods to handle non-PnP devices:</para>
     <itemizedlist>
       <listitem>
         <para>Use a <function>device_identify()</function> method
           (example: <filename>sound/isa/es1888.c</filename>).  The
           <function>device_identify()</function> method probes for the
           hardware at known addresses and, if it finds a supported
           device, creates a new pcm device which is then passed to
           probe/attach.</para>
       </listitem>
       <listitem>
         <para>Use a custom kernel configuration with appropriate hints
           for pcm devices (example:
           <filename>sound/isa/mss.c</filename>).</para>
       </listitem>
     </itemizedlist>
 
     <para><devicename>pcm</devicename> drivers should implement
     <function>device_suspend</function>,
     <function>device_resume</function> and
     <function>device_shutdown</function> routines, so that power
     management and module unloading function correctly.</para>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="oss-interfaces">
     <title>Interfaces</title>
 
     <para>The interface between the <devicename>pcm</devicename> core
       and the sound drivers is defined in terms of <link
       linkend="kernel-objects">kernel objects</link>.</para>
 
     <para>There are two main interfaces that a sound driver will
       usually provide: <emphasis>CHANNEL</emphasis> and either
       <emphasis>MIXER</emphasis> or <emphasis>AC97</emphasis>.</para>
       
     <para>The <emphasis>AC97</emphasis> interface is a very small
       hardware access (register read/write) interface, implemented by
       drivers for hardware with an AC97 codec.  In this case, the
       actual MIXER interface is provided by the shared AC97 code in
       <devicename>pcm</devicename>.</para>
 
     <sect2>
       <title>The CHANNEL interface</title>
 
       <sect3>
         <title>Common notes for function parameters</title>
 
         <para>Sound drivers usually have a private data structure to
           describe their device, and one structure for each play and
           record data channel that it supports.</para>
 
         <para>For all CHANNEL interface functions, the first parameter
           is an opaque pointer.</para>
 
         <para>The second parameter is a pointer to the private
           channel data structure, except for
           <function>channel_init()</function> which has a pointer to the
           private device structure (and returns the channel pointer
           for further use by <devicename>pcm</devicename>).</para>
 
       </sect3>
 
       <sect3>
         <title>Overview of data transfer operations</title>
 
         <para>For sound data transfers, the
           <devicename>pcm</devicename> core and the sound drivers
           communicate through a shared memory area, described by a
           <structname>struct snd_dbuf</structname>.</para>
 
         <para><structname>struct snd_dbuf</structname> is private to
           <devicename>pcm</devicename>, and sound drivers obtain
           values of interest by calls to accessor functions
           (<function>sndbuf_getxxx()</function>).</para>
 
         <para>The shared memory area has a size of
           <function>sndbuf_getsize()</function> and is divided into
           fixed size blocks of <function>sndbuf_getblksz()</function>
           bytes.</para>
           
         <para>When playing, the general transfer mechanism is as
           follows (reverse the idea for recording):</para>
 
         <itemizedlist>
           <listitem>
             <para><devicename>pcm</devicename> initially fills up the
               buffer, then calls the sound driver's <link
               linkend="channel-trigger">
               <function>xxxchannel_trigger()</function></link>
               function with a parameter of PCMTRIG_START.</para>
           </listitem>
 
           <listitem>
             <para>The sound driver then arranges to repeatedly
               transfer the whole memory area
               (<function>sndbuf_getbuf()</function>,
               <function>sndbuf_getsize()</function>) to the device, in
               blocks of <function>sndbuf_getblksz()</function> bytes.
               It calls back the <function>chn_intr()</function>
               <devicename>pcm</devicename> function for each
               transferred block (this will typically happen at
               interrupt time).</para>
           </listitem>
 
           <listitem>
             <para><function>chn_intr()</function> arranges to copy new
               data to the area that was transferred to the device (now
               free), and make appropriate updates to the
               <structname>snd_dbuf</structname> structure.</para>
           </listitem>
 
         </itemizedlist>
 
       <sect3 id="xxxchannel-init">
         <title>channel_init</title>
 
         <para><function>xxxchannel_init()</function> is called to
           initialize each of the play or record channels.  The calls
           are initiated from the sound driver attach routine.  (See
           the <link linkend="pcm-probe-and-attach">probe and attach
           section</link>).</para>
           
           <programlisting>          static void *
           xxxchannel_init(kobj_t obj, void *data, 
              struct snd_dbuf *b, struct pcm_channel *c, int dir)<co id="co-chinit-params">
           {
               struct xxx_info *sc = data;
               struct xxx_chinfo *ch;
                ...
               return ch;<co id="co-chinit-return">
            }</programlisting>
 
         <calloutlist>
 
           <callout arearefs="co-chinit-params">
             <para><varname>b</varname> is the address for the channel
               <structname>struct snd_dbuf</structname>.  It should be
               initialized in the function by calling
               <function>sndbuf_alloc()</function>.  The buffer size to
               use is normally a small multiple of the 'typical' unit
               transfer size for your device.</para>
 
             <para><varname>c</varname> is the
               <devicename>pcm</devicename> channel control structure
               pointer.  This is an opaque object.  The function should
               store it in the local channel structure, to be used in
               later calls to <devicename>pcm</devicename> (ie:
               <function>chn_intr(c)</function>).</para>
 
             <para><varname>dir</varname> indicates the channel
               direction (<literal>PCMDIR_PLAY</literal> or
               <literal>PCMDIR_REC</literal>).</para>
           </callout>
 
           <callout arearefs="co-chinit-return">
             <para>The function should return a pointer to the private
               area used to control this channel.  This will be passed
               as a parameter to other channel interface calls.</para>
           </callout>
 
         </calloutlist>
 
       </sect3>
 
       <sect3>
         <title>channel_setformat</title>
 
         <para><function>xxxchannel_setformat()</function> should set
           up the hardware for the specified channel for the specified
           sound format.</para>
           
           <programlisting>          static int
           xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format)<co id="co-chsetformat-params">
           {
               struct xxx_chinfo *ch = data;
                ...
               return 0;
            }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-chsetformat-params">
             <para><varname>format</varname> is specified as an
               <literal>AFMT_XXX value</literal>
               (<filename>soundcard.h</filename>).</para>
           </callout>
 
         </calloutlist>
       </sect3>
 
       <sect3>
         <title>channel_setspeed</title>
 
         <para><function>xxxchannel_setspeed()</function> sets up the
           channel hardware for the specified sampling speed, and
           returns the possibly adjusted speed.</para>
 
         <programlisting>          static int
           xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed)
           {
               struct xxx_chinfo *ch = data;
                ...
               return speed;
            }</programlisting>
 
       </sect3>
 
       <sect3>
         <title>channel_setblocksize</title>
 
         <para><function>xxxchannel_setblocksize()</function> sets the
           block size, which is the size of unit transactions between
           <devicename>pcm</devicename> and the sound driver, and
           between the sound driver and the device.  Typically, this
           would be the number of bytes transferred before an interrupt
           occurs.  During a transfer, the sound driver should call
           <devicename>pcm</devicename>'s
           <function>chn_intr()</function> every time this size has
           been transferred.</para>
 
         <para>Most sound drivers only take note of the block size
           here, to be used when an actual transfer will be
           started.</para>
           
         <programlisting>          static int
           xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize)
           {
               struct xxx_chinfo *ch = data;
                 ...
               return blocksize;<co id="co-chsetblocksize-return">
            }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-chsetblocksize-return">
             <para>The function returns the possibly adjusted block
               size.  In case the block size is indeed changed,
               <function>sndbuf_resize()</function> should be called to
               adjust the buffer.</para> 
 
           </callout>
         </calloutlist>
 
       </sect3>
 
       <sect3 id="channel-trigger">
         <title>channel_trigger</title>
 
         <para><function>xxxchannel_trigger()</function> is called by
           <devicename>pcm</devicename> to control data transfer
           operations in the driver.</para> 
           
         <programlisting>          static int
           xxxchannel_trigger(kobj_t obj, void *data, int go)<co id="co-chtrigger-params">
           {
               struct xxx_chinfo *ch = data;
                ...
               return 0;
            }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-chtrigger-params">
             <para><varname>go</varname> defines the action for the
               current call.  The possible values are:</para>
               <itemizedlist>
 
               <listitem>
                 <para><literal>PCMTRIG_START</literal>: the driver
                   should start a data transfer from or to the channel
                   buffer.  If needed, the buffer base and size can be
                   retrieved through
                   <function>sndbuf_getbuf()</function> and
                   <function>sndbuf_getsize()</function>.</para>
               </listitem>
 
               <listitem>
                 <para><literal>PCMTRIG_EMLDMAWR</literal> /
                   <literal>PCMTRIG_EMLDMARD</literal>: this tells the
                   driver that the input or output buffer may have been
                   updated.  Most drivers just ignore these
                   calls.</para>
               </listitem>
 
               <listitem>
                 <para><literal>PCMTRIG_STOP</literal> /
                   <literal>PCMTRIG_ABORT</literal>: the driver should
                   stop the current transfer.</para>
               </listitem>
             </itemizedlist>
 
           </callout> 
         </calloutlist>
 
         <note><para>If the driver uses ISA DMA,
           <function>sndbuf_isadma()</function> should be called before
           performing actions on the device, and will take care of the
           DMA chip side of things.</para>
           </note>
 
       </sect3>
 
       <sect3>
         <title>channel_getptr</title>
 
         <para><function>xxxchannel_getptr()</function> returns the
           current offset in the transfer buffer.  This will typically
           be called by <function>chn_intr()</function>, and this is how
           <devicename>pcm</devicename> knows where it can transfer
           new data.</para>
           
       </sect3>
 
       <sect3>
         <title>channel_free</title>
 
         <para><function>xxxchannel_free()</function> is called to free
           up channel resources, for example when the driver is
           unloaded, and should be implemented if the channel data
           structures are dynamically allocated or if
           <function>sndbuf_alloc()</function> was not used for buffer
           allocation.</para> 
 
       </sect3>
 
       <sect3>
         <title>channel_getcaps</title>
 
         <programlisting>          struct pcmchan_caps *
           xxxchannel_getcaps(kobj_t obj, void *data)
           {
               return &amp;xxx_caps;<co id="co-chgetcaps-return">
            }</programlisting>
 
         <calloutlist>
 
           <callout arearefs="co-chgetcaps-return">
             <para>The routine returns a pointer to a (usually
               statically-defined) <structname>pcmchan_caps</structname>
               structure (defined in
               <filename>sound/pcm/channel.h</filename>.  The structure holds
               the minimum and maximum sampling frequencies, and the
               accepted sound formats.  Look at any sound driver for an
               example.</para>
           </callout>
 
         </calloutlist>
 
       </sect3>
 
       <sect3>
         <title>More functions</title>
 
         <para><function>channel_reset()</function>,
           <function>channel_resetdone()</function>, and
           <function>channel_notify()</function> are for special purposes
           and should not be implemented in a driver without discussing
           it with the authorities (&a.cg;).</para>
 
         <para><function>channel_setdir()</function> is deprecated.</para>
       </sect3>
 
     </sect2>
 
     <sect2>
       <title>The MIXER interface</title>
         
       <sect3 id="xxxmixer-init">
         <title>mixer_init</title>
 
         <para><function>xxxmixer_init()</function> initializes the
           hardware and tells <devicename>pcm</devicename> what mixer
           devices are available for playing and recording</para>
 
         <programlisting>          static int
           xxxmixer_init(struct snd_mixer *m)
           {
               struct xxx_info   *sc = mix_getdevinfo(m);
               u_int32_t v;
 
               [Initialize hardware]
 
               [Set appropriate bits in v for play mixers]<co id="co-mxini-sd">
               mix_setdevs(m, v);
               [Set appropriate bits in v for record mixers]
               mix_setrecdevs(m, v)
 
               return 0;              
           }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-mxini-sd">
             <para>Set bits in an integer value and call
               <function>mix_setdevs()</function> and
               <function>mix_setrecdevs()</function> to tell
               <devicename>pcm</devicename> what devices exist.</para>
           </callout>
         </calloutlist>
 
         <para>Mixer bits definitions can be found in
           <filename>soundcard.h</filename>
           (<literal>SOUND_MASK_XXX</literal> values and
           <literal>SOUND_MIXER_XXX</literal> bit shifts).</para>
 
       </sect3>
 
       <sect3>
         <title>mixer_set</title>
 
         <para><function>xxxmixer_set()</function> sets the volume
           level for one mixer device.</para>
 
         <programlisting>          static int
           xxxmixer_set(struct snd_mixer *m, unsigned dev, 
                            unsigned left, unsigned right)<co id="co-mxset-params">
           {
               struct sc_info *sc = mix_getdevinfo(m);
               [set volume level]
               return left | (right << 8);<co id="co-mxset-return">
           }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-mxset-params">
             <para>The device is specified as a SOUND_MIXER_XXX
               value</para> <para>The volume values are specified in
               range [0-100].  A value of zero should mute the
               device.</para>
           </callout>
 
           <callout arearefs="co-mxset-return">
             <para>As the hardware levels probably won't match the
               input scale, and some rounding will occur, the routine
               returns the actual level values (in range 0-100) as
               shown.</para>
           </callout>
         </calloutlist>
 
       </sect3>
 
       <sect3>
         <title>mixer_setrecsrc</title>
 
         <para><function>xxxmixer_setrecsrc()</function> sets the
           recording source device.</para>
           
         <programlisting>          static int
           xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src)<co id="co-mxsr-params">
           {
               struct xxx_info *sc = mix_getdevinfo(m);
 
               [look for non zero bit(s) in src, set up hardware]
 
               [update src to reflect actual action]
               return src;<co id="co-mxsr-return">
            }</programlisting>
 
         <calloutlist>
           <callout arearefs="co-mxsr-params">
             <para>The desired recording devices are specified as a
               bit field</para>
           </callout>
 
           <callout arearefs="co-mxsr-return">
             <para>The actual devices set for recording are returned.
               Some drivers can only set one device for recording.  The
               function should return -1 if an error occurs.</para>
           </callout>
         </calloutlist>
       </sect3>
 
       <sect3>
         <title>mixer_uninit, mixer_reinit</title>
 
         <para><function>xxxmixer_uninit()</function> should ensure
           that all sound is muted and if possible mixer hardware
           should be powered down </para>
 
         <para><function>xxxmixer_reinit()</function> should ensure
           that the mixer hardware is powered up and any settings not
           controlled by <function>mixer_set()</function> or
           <function>mixer_setrecsrc()</function> are restored.</para> 
 
       </sect3>
     </sect2>
 
     <sect2>
       <title>The AC97 interface</title>
 
       <para>The <emphasis>AC97</emphasis> interface is implemented
         by drivers with an AC97 codec.  It only has three methods:</para>
 
       <itemizedlist>
 
         <listitem><para><function>xxxac97_init()</function> returns
           the number of ac97 codecs found.</para>
         </listitem>
 
         <listitem><para><function>ac97_read()</function> and
           <function>ac97_write()</function> read or write a specified
           register.</para>
         </listitem>
 
       </itemizedlist>
 
       <para>The <emphasis>AC97</emphasis> interface is used by the
         AC97 code in <devicename>pcm</devicename> to perform higher
         level operations.  Look at
         <filename>sound/pci/maestro3.c</filename> or many others under
         <filename>sound/pci/</filename> for an example.</para>
 
     </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/developers-handbook/sysinit/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/sysinit/chapter.sgml
index 1b8a0b4cdb..083d21c8b4 100644
--- a/en_US.ISO8859-1/books/developers-handbook/sysinit/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/sysinit/chapter.sgml
@@ -1,161 +1,161 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="sysinit">
   <title>The Sysinit Framework</title>
 
   <para>Sysinit is the framework for a generic call sort and dispatch
     mechanism. FreeBSD currently uses it for the dynamic
     initialization of the kernel. Sysinit allows FreeBSD's kernel
     subsystems to be reordered, and added, removed, and replaced at
     kernel link time when the kernel or one of its modules is loaded
     without having to edit a statically ordered initialization routing
     and recompile the kernel. This system also allows kernel modules,
     currently called <firstterm>KLD's</firstterm>, to be separately
     compiled, linked, and initialized at boot time and loaded even
     later while the system is already running. This is accomplished
     using the <quote>kernel linker</quote> and <quote>linker
     sets</quote>.</para>
 
-  <sect1>
+  <sect1 id="sysinit-term">
     <title>Terminology</title>
 
     <variablelist>
       <varlistentry>
         <term>Linker Set</term>
         <listitem>
           <para>A linker technique in which the linker gathers
             statically declared data throughout a program's source files
             into a single contiguously addressable unit of
             data.</para>
         </listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
-  <sect1>
+  <sect1 id="sysinit-operation">
     <title>Sysinit Operation</title>
 
     <para>Sysinit relies on the ability of the linker to take static
       data declared at multiple locations throughout a program's
       source and group it together as a single contiguous chunk of
       data. This linker technique is called a <quote>linker
       set</quote>. Sysinit uses two linker sets to maintain two data
       sets containing each consumer's call order, function, and a
       pointer to the data to pass to that function.</para>
 
     <para>Sysinit uses two priorities when ordering the functions for
       execution.  The first priority is a subsystem ID giving an
       overall order Sysinit's dispatch of functions. Current predeclared
       ID's are in <filename>&lt;sys/kernel.h></filename> in the enum
       list <literal>sysinit_sub_id</literal>. The second priority used
       is an element order within the subsystem. Current predeclared
       subsystem element orders are in
       <filename>&lt;sys/kernel.h></filename> in the enum list
       <literal>sysinit_elem_order</literal>.</para>
 
     <para>There are currently two uses for Sysinit. Function dispatch
       at system startup and kernel module loads, and function dispatch
       at system shutdown and kernel module unload.</para>
   </sect1>
 
 
-  <sect1>
+  <sect1 id="sysinit-using">
     <title>Using Sysinit</title>
 
     <sect2>
       <title>Interface</title>
 
       <sect3>
         <title>Headers</title>
 
           <programlisting>&lt;sys/kernel.h></programlisting>
       </sect3>
 
       <sect3>
         <title>Macros</title>
 
         <programlisting>SYSINIT(uniquifier, subsystem, order, func, ident)
         SYSUNINIT(uniquifier, subsystem, order, func, ident)</programlisting>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Startup</title>
 
       <para>The <literal>SYSINIT()</literal> macro creates the
         necessary sysinit data in Sysinit's startup data set for
         Sysinit to sort and dispatch a function at system startup and
         module load.  <literal>SYSINIT()</literal> takes a uniquifier
         that Sysinit uses identify the particular function dispatch
         data, the subsystem order, the subsystem element order, the
         function to call, and the data to pass the function. All
         functions must take a constant pointer argument.
         </para>
 
       <para>For example:</para>
 
       <programlisting>#include &lt;sys/kernel.h>
 
 void foo_null(void *unused)
 {
         foo_doo();
 }
 SYSINIT(foo_null, SI_SUB_FOO, SI_ORDER_FOO, NULL);
 
 struct foo foo_voodoo = {
         FOO_VOODOO;
 }
 
 void foo_arg(void *vdata)
 {
         struct foo *foo = (struct foo *)vdata;
         foo_data(foo);
 }
 SYSINIT(foo_arg, SI_SUB_FOO, SI_ORDER_FOO, foo_voodoo);
       </programlisting>
     </sect2>
 
     <sect2>
       <title>Shutdown</title>
 
       <para>The <literal>SYSUNINIT()</literal> macro behaves similarly
         to the <literal>SYSINIT()</literal> macro except that it adds
         the Sysinit data to Sysinit's shutdown data set.</para>
 
       <para>For example:</para>
 
       <programlisting>#include &lt;sys/kernel.h>
 
 void foo_cleanup(void *unused)
 {
         foo_kill();
 }
 SYSUNINIT(foo_cleanup, SI_SUB_FOO, SI_ORDER_FOO, NULL);
 
 struct foo_stack foo_stack = {
         FOO_STACK_VOODOO;
 }
 
 void foo_flush(void *vdata)
 {
 }
 SYSUNINIT(foo_flush, SI_SUB_FOO, SI_ORDER_FOO, foo_stack);
       </programlisting>
     </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/tools/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
index 556c8c6bed..d42b803076 100644
--- a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml
@@ -1,2357 +1,2357 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="tools">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>James</firstname>
 	<surname>Raynard</surname>
 	<contrib>Written by </contrib>
       </author>
     </authorgroup>
     <authorgroup>
       <author>
         <firstname>Murray</firstname>
 	<surname>Stokely</surname>
 	<contrib>Modifications for the Developer's Handbook by </contrib>
       </author>
     </authorgroup>
   </chapterinfo>
   <title>Programming Tools</title>
 
-  <sect1><title>Synopsis</title>
+  <sect1 id="tools-synopsis"><title>Synopsis</title>
 
     <para>This chapter is an introduction to using some of the
       programming tools supplied with FreeBSD, although much of it
       will be applicable to many other versions of Unix.  It does
       <emphasis>not</emphasis> attempt to describe coding in any
       detail.  Most of the chapter assumes little or no previous
       programming knowledge, although it is hoped that most
       programmers will find something of value in it.</para>
 
   </sect1>
 
-  <sect1><title>Introduction</title>
+  <sect1 id="tools-intro"><title>Introduction</title>
   
     <para>FreeBSD offers an excellent development environment.
       Compilers for C, C++, and Fortran and an assembler come with the
       basic system, not to mention a Perl interpreter and classic Unix
       tools such as <command>sed</command> and <command>awk</command>.
       If that is not enough, there are many more compilers and
       interpreters in the Ports collection.  FreeBSD is very
       compatible with standards such as <acronym>POSIX</acronym> and
       <acronym>ANSI</acronym> C, as well with its own BSD heritage, so
       it is possible to write applications that will compile and run
       with little or no modification on a wide range of
       platforms.</para>
 
     <para>However, all this power can be rather overwhelming at first
       if you have never written programs on a Unix platform before.
       This document aims to help you get up and running, without
       getting too deeply into more advanced topics.  The intention is
       that this document should give you enough of the basics to be
       able to make some sense of the documentation.</para>
 
     <para>Most of the document requires little or no knowledge of
       programming, although it does assume a basic competence with
       using Unix and a willingness to learn!</para>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="tools-programming">
     <title>Introduction to Programming</title>
 
     <para>A program is a set of instructions that tell the computer to
       do various things; sometimes the instruction it has to perform
       depends on what happened when it performed a previous
       instruction.  This section gives an overview of the two main
       ways in which you can give these instructions, or
       <quote>commands</quote> as they are usually called.  One way
       uses an <firstterm>interpreter</firstterm>, the other a
       <firstterm>compiler</firstterm>.  As human languages are too
       difficult for a computer to understand in an unambiguous way,
       commands are usually written in one or other languages specially
       designed for the purpose.</para>
 
     <sect2>
       <title>Interpreters</title>
 
       <para>With an interpreter, the language comes as an environment,
 	where you type in commands at a prompt and the environment
 	executes them for you.  For more complicated programs, you can
 	type the commands into a file and get the interpreter to load
 	the file and execute the commands in it.  If anything goes
 	wrong, many interpreters will drop you into a debugger to help
 	you track down the problem.</para>
 
       <para>The advantage of this is that you can see the results of
 	your commands immediately, and mistakes can be corrected
 	readily.  The biggest disadvantage comes when you want to
 	share your programs with someone.  They must have the same
 	interpreter, or you must have some way of giving it to them,
 	and they need to understand how to use it.  Also users may not
 	appreciate being thrown into a debugger if they press the
 	wrong key! From a performance point of view, interpreters can
 	use up a lot of memory, and generally do not generate code as
 	efficiently as compilers.</para>
 
       <para>In my opinion, interpreted languages are the best way to
 	start if you have not done any programming before.  This kind
 	of environment is typically found with languages like Lisp,
 	Smalltalk, Perl and Basic.  It could also be argued that the
 	Unix shell (<command>sh</command>, <command>csh</command>) is itself an
 	interpreter, and many people do in fact write shell
 	<quote>scripts</quote> to help with various
 	<quote>housekeeping</quote> tasks on their machine.  Indeed, part
 	of the original Unix philosophy was to provide lots of small
 	utility programs that could be linked together in shell
 	scripts to perform useful tasks.</para>
     </sect2>
 
     <sect2>
       <title>Interpreters available with FreeBSD</title>
 
       <para>Here is a list of interpreters that are available as
 	<ulink
 	  URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/">FreeBSD
 	  packages</ulink>, with a brief discussion of some of the
 	more popular interpreted languages.</para>
 
       <para>To get one of these packages, all you need to do is to
 	click on the hotlink for the package, to download the package
 	and then install the package by running:</para>
 
       <screen>&prompt.root; <userinput>pkg_add <replaceable>package name</></userinput></screen>
 
       <para>as root.  Obviously, you will need to have a fully
 	functional FreeBSD 2.1.0 or later system for the package to
 	work!</para>
 
       <variablelist>
 	<varlistentry>
 	  <term><acronym>BASIC</acronym></term>
 
 	  <listitem>
 	    <para>Short for Beginner's All-purpose Symbolic
 	      Instruction Code.  Developed in the 1950s for teaching
 	      University students to program and provided with every
 	      self-respecting personal computer in the 1980s,
 	      <acronym>BASIC</acronym> has been the first programming
 	      language for many programmers.  It is also the foundation
 	      for Visual Basic.</para>
 
 	    <para>The <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/bwbasic.tgz">Bywater
 		Basic Interpreter</ulink> and the <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/pbasic.tgz">Phil
 		Cockroft's Basic Interpreter</ulink> (formerly Rabbit
 	      Basic) are available as <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/">FreeBSD
 		packages</ulink>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Lisp</term>
 
 	  <listitem>
 	    <para>A language that was developed in the late 1950s as
 	      an alternative to the <quote>number-crunching</quote>
 	      languages that were popular at the time.  Instead of
 	      being based on numbers, Lisp is based on lists; in fact
 	      the name is short for <quote>List Processing</quote>.
 	      Very popular in <acronym>AI</acronym> (Artificial Intelligence)
 	      circles.</para>
 
 	    <para>Lisp is an extremely powerful and sophisticated
 	      language, but can be rather large and unwieldy.</para>
 
 	    <para>Various implementations of Lisp that can run on UNIX
 	      systems are available as packages for FreeBSD.
 	      <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/gcl.tgz">GNU Common Lisp</ulink>,
 	      <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/clisp.tgz">CLISP</ulink>
 	      by Bruno Haible and Michael Stoll,
 	      <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/cmucl.tgz">CMUCL</ulink>
 	      which includes a highly-optimizing compiler too, or
 	      simpler Lisp implementations, like
 	      <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/slisp.tgz">SLisp</ulink>
 	      which implements most of the Common Lisp constructs in a
 	      few hundred lines of C code.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Perl</term>
 
 	  <listitem>
 	    <para>Very popular with system administrators for writing
 	      scripts; also often used on World Wide Web servers for
 	      writing <acronym>CGI</acronym> scripts.</para>
 
 	    <para>Perl is available as a <ulink
 	      URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/perl.tgz">package</ulink>
 	      for all FreeBSD releases, and is installed as <command>/usr/bin/perl</command> in the
 	      base system of 4.x releases.</para>
 
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Scheme</term>
 
 	  <listitem>
 	    <para>A dialect of Lisp that is rather more compact and
 	      cleaner than Common Lisp.  Popular in Universities as it
 	      is simple enough to teach to undergraduates as a first
 	      language, while it has a high enough level of
 	      abstraction to be used in research work.</para>
 
 	    <para>FreeBSD has packages of the <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/elk.tgz">Elk
 		Scheme Interpreter</ulink>, the <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/mit-scheme.tgz">MIT
 		Scheme Interpreter</ulink> and the <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/scm.tgz">SCM
 		Scheme Interpreter</ulink>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Icon</term>
 
 	  <listitem>
 	    <para>Icon is a high-level language with extensive
 	      facilities for processing strings and structures.
 	      A <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/icon.tgz">package</ulink>
 	      is available for FreeBSD.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Logo</term>
 
 	  <listitem>
 	    <para>Logo is a language that is easy to learn, and has
 	      been used as an introductory programming language in
 	      various courses.  It is an excellent tool to work with
 	      when teaching programming in small ages, as it makes the
 	      creation of elaborate geometric shapes an easy task even
 	      for very small children.</para>
 
 	    <para>A package is available for FreeBSD of Brian Harvey's <ulink
 		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/ucblogo.tgz">LOGO
 		Interpreter</ulink>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Python</term>
 
 	  <listitem>
 	    <para>Python is an Object-Oriented, intepreted language.
 	      Its advocates argue that it is one of the best languages
 	      to start programming with, since it is relatively easy
 	      to start with, but is not limited in comparison to other
 	      popular intepreted languages that are used for the
 	      development of large, complex applications (Perl and
 	      Tcl are two other languages that are popular for such tasks).</para>
 
 	    <para>A package of the latest version of Python for
 	      FreeBSD is available
 	      <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/python.tgz">here</ulink>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Tcl and Tk</term>
 
 	  <listitem>
 	    <para>Tcl is an embeddable, intepreted language, that has
 	      become widely used and became popular mostly because of its portability to many
 	      platforms.  It can be used both for quickly writing
 	      small, prototype applications, or (when combined with
 	      Tk, a GUI toolkit) fully-fledged, featureful
 	      programs.</para>
 
 	    <para>Various versions of Tcl are available as packages
 	      for FreeBSD.  The latest version is, as of this writing,
 	      <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/tcl83.tgz">Tcl
 		version 8.3</ulink>.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2>
       <title>Compilers</title>
 
       <para>Compilers are rather different.  First of all, you write
 	your code in a file (or files) using an editor.  You then run
 	the compiler and see if it accepts your program.  If it did
 	not compile, grit your teeth and go back to the editor; if it
 	did compile and gave you a program, you can run it either at a
 	shell command prompt or in a debugger to see if it works
 	properly.
 	
 	<footnote>
 	  <para>If you run it in the shell, you may get a core
 	    dump.</para>
 	</footnote></para>
 
       <para>Obviously, this is not quite as direct as using an
 	interpreter.  However it allows you to do a lot of things
 	which are very difficult or even impossible with an
 	interpreter, such as writing code which interacts closely with
 	the operating system&mdash;or even writing your own operating
 	system! It is also useful if you need to write very efficient
 	code, as the compiler can take its time and optimise the code,
 	which would not be acceptable in an interpreter.  Moreover,
 	distributing a program written for a compiler is usually more
 	straightforward than one written for an interpreter&mdash;you
 	can just give them a copy of the executable, assuming they
 	have the same operating system as you.</para>
 
       <para>Compiled languages include Pascal, C and C++.  C and C++
 	are rather unforgiving languages, and best suited to more
 	experienced programmers; Pascal, on the other hand, was
 	designed as an educational language, and is quite a good
 	language to start with.  FreeBSD does not include Pascal
 	support in the base system, but the GNU Pascal Compiler (gpc)
 	is available in the ports collection as
 	<filename role="package">lang/gpc</filename>.</para>
 
       <para>As the edit-compile-run-debug cycle is rather tedious when
 	using separate programs, many commercial compiler makers have
 	produced Integrated Development Environments
 	(<acronym>IDE</acronym>s for short).  FreeBSD does not include
 	an IDE in the base system, but <filename role="package">devel/kdevelop</filename> is
 	available in the ports tree and many use
 	<application>Emacs</application> for this purpose.  Using
 	<application>Emacs</application> as an IDE is discussed in
 	<xref linkend="emacs">.</para>
     </sect2>
 
 
   </sect1>
 
 
-  <sect1>
+  <sect1 id="tools-compiling">
     <title>Compiling with <command>cc</command></title>
 
     <para>This section deals only with the GNU compiler for C and C++,
       since that comes with the base FreeBSD system.  It can be
       invoked by either <command>cc</command> or <command>gcc</command>.  The
       details of producing a program with an interpreter vary
       considerably between interpreters, and are usually well covered
       in the documentation and on-line help for the
       interpreter.</para>
 
     <para>Once you have written your masterpiece, the next step is to
       convert it into something that will (hopefully!) run on FreeBSD.
       This usually involves several steps, each of which is done by a
       separate program.</para>
 
     <procedure>
       <step>
 	<para>Pre-process your source code to remove comments and do
 	  other tricks like expanding macros in C.</para>
       </step>
 
       <step>
 	<para>Check the syntax of your code to see if you have obeyed
 	  the rules of the language.  If you have not, it will
 	  complain!</para>
       </step>
 
       <step>
 	<para>Convert the source code into assembly
 	  language&mdash;this is very close to machine code, but still
 	  understandable by humans.  Allegedly.
 
 	  <footnote>
 	    <para>To be strictly accurate, <command>cc</command> converts the
 	      source code into its own, machine-independent
 	      <firstterm>p-code</firstterm> instead of assembly language at
 	      this stage.</para>
 	  </footnote></para>
       </step>
 
       <step>
 	<para>Convert the assembly language into machine
 	  code&mdash;yep, we are talking bits and bytes, ones and
 	  zeros here.</para>
       </step>
 
       <step>
 	<para>Check that you have used things like functions and
 	  global variables in a consistent way.  For example, if you
 	  have called a non-existent function, it will
 	  complain.</para>
       </step>
 
       <step>
 	<para>If you are trying to produce an executable from several
 	  source code files, work out how to fit them all
 	  together.</para>
       </step>
 
       <step>
 	<para>Work out how to produce something that the system's
 	  run-time loader will be able to load into memory and
 	  run.</para>
       </step>
 
       <step>
 	<para>Finally, write the executable on the filesystem.</para>
       </step>
     </procedure>
 
     <para>The word <firstterm>compiling</firstterm> is often used to refer to
       just steps 1 to 4&mdash;the others are referred to as
       <firstterm>linking</firstterm>.  Sometimes step 1 is referred to as
       <firstterm>pre-processing</firstterm> and steps 3-4 as
       <firstterm>assembling</firstterm>.</para>
 
     <para>Fortunately, almost all this detail is hidden from you, as
       <command>cc</command> is a front end that manages calling all these
       programs with the right arguments for you; simply typing</para>
 
     <screen>&prompt.user; <userinput>cc foobar.c</userinput></screen>
 
     <para>will cause <filename>foobar.c</filename> to be compiled by all the
       steps above.  If you have more than one file to compile, just do
       something like</para>
 
     <screen>&prompt.user; <userinput>cc foo.c bar.c</userinput></screen>
 
     <para>Note that the syntax checking is just that&mdash;checking
       the syntax.  It will not check for any logical mistakes you may
       have made, like putting the program into an infinite loop, or
       using a bubble sort when you meant to use a binary
       sort.
 
       <footnote>
 	<para>In case you did not know, a binary sort is an efficient
 	  way of sorting things into order and a bubble sort
 	  is not.</para>
       </footnote></para>
 
     <para>There are lots and lots of options for <command>cc</command>, which
       are all in the manual page.  Here are a few of the most important
       ones, with examples of how to use them.</para>
 
     <variablelist>
       <varlistentry>
 	<term><option>-o <replaceable>filename</replaceable></option></term>
 
 	<listitem>
 	  <para>The output name of the file.  If you do not use this
 	    option, <command>cc</command> will produce an executable called
 	    <filename>a.out</filename>.
 
 	    <footnote>
 	      <para>The reasons for this are buried in the mists of
 		history.</para>
 	    </footnote></para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc foobar.c</userinput>               <lineannotation>executable is <filename>a.out</filename></lineannotation>
 &prompt.user; <userinput>cc -o foobar foobar.c</userinput>     <lineannotation>executable is <filename>foobar</filename></lineannotation>
 	    </screen>
 	  </informalexample>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-c</option></term>
 	
 	<listitem>
 	  <para>Just compile the file, do not link it.  Useful for toy
 	    programs where you just want to check the syntax, or if
 	    you are using a <filename>Makefile</filename>.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -c foobar.c</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>This will produce an <firstterm>object file</firstterm> (not an
 	    executable) called <filename>foobar.o</filename>.  This
 	    can be linked together with other object files into an
 	    executable.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-g</option></term>
 
 	<listitem>
 	  <para>Create a debug version of the executable.  This makes
 	    the compiler put information into the executable about
 	    which line of which source file corresponds to which
 	    function call.  A debugger can use this information to show
 	    the source code as you step through the program, which is
 	    <emphasis>very</emphasis> useful; the disadvantage is that
 	    all this extra information makes the program much bigger.
 	    Normally, you compile with <option>-g</option> while you
 	    are developing a program and then compile a <quote>release
 	      version</quote> without <option>-g</option> when you are
 	    satisfied it works properly.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -g foobar.c</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>This will produce a debug version of the
 	    program.
 
 	    <footnote>
 	      <para>Note, we did not use the <option>-o</option> flag
 		to specify the executable name, so we will get an
 		executable called <filename>a.out</filename>.
 		Producing a debug version called
 		<filename>foobar</filename> is left as an exercise for
 		the reader!</para>
 	    </footnote></para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-O</option></term>
 
 	<listitem>
 	  <para>Create an optimised version of the executable.  The
 	    compiler performs various clever tricks to try and produce
 	    an executable that runs faster than normal.  You can add a
 	    number after the <option>-O</option> to specify a higher
 	    level of optimisation, but this often exposes bugs in the
 	    compiler's optimiser.  For instance, the version of
 	    <command>cc</command> that comes with the 2.1.0 release of
 	    FreeBSD is known to produce bad code with the
 	    <option>-O2</option> option in some circumstances.</para>
 
 	  <para>Optimisation is usually only turned on when compiling
 	    a release version.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>This will produce an optimised version of
 	    <filename>foobar</filename>.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>The following three flags will force <command>cc</command>
       to check that your code complies to the relevant international
       standard, often referred to as the <acronym>ANSI</acronym>
       standard, though strictly speaking it is an
       <acronym>ISO</acronym> standard.</para>
 
     <variablelist>
       <varlistentry>
 	<term><option>-Wall</option></term>
 
 	<listitem>
 	  <para>Enable all the warnings which the authors of
 	    <command>cc</command> believe are worthwhile.  Despite the
 	    name, it will not enable all the warnings
 	    <command>cc</command> is capable of.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-ansi</option></term>
 
 	<listitem>
 	  <para>Turn off most, but not all, of the
 	    non-<acronym>ANSI</acronym>&nbsp;C features provided by
 	    <command>cc</command>.  Despite the name, it does not
 	    guarantee strictly that your code will comply to the
 	    standard.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><option>-pedantic</option></term>
 
 	<listitem>
 	  <para>Turn off <emphasis>all</emphasis>
 	    <command>cc</command>'s non-<acronym>ANSI</acronym>&nbsp;C
 	    features.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>Without these flags, <command>cc</command> will allow you to
       use some of its non-standard extensions to the standard.  Some
       of these are very useful, but will not work with other
       compilers&mdash;in fact, one of the main aims of the standard is
       to allow people to write code that will work with any compiler
       on any system.  This is known as <firstterm>portable
 	code</firstterm>.</para>
 
     <para>Generally, you should try to make your code as portable as
       possible, as otherwise you may have to completely rewrite the
       program later to get it to work somewhere else&mdash;and who
       knows what you may be using in a few years time?</para>
 
     <informalexample>
       <screen>&prompt.user; <userinput>cc -Wall -ansi -pedantic -o foobar foobar.c</userinput></screen>
     </informalexample>
 
     <para>This will produce an executable <filename>foobar</filename>
       after checking <filename>foobar.c</filename> for standard
       compliance.</para>
 
     <variablelist>
       <varlistentry>
 	<term><option>-l<replaceable>library</replaceable></option></term>
 
 	<listitem>
 	  <para>Specify a function library to be used during when
 	    linking.</para>
 
 	  <para>The most common example of this is when compiling a
 	    program that uses some of the mathematical functions in C.
 	    Unlike most other platforms, these are in a separate
 	    library from the standard C one and you have to tell the
 	    compiler to add it.</para>
 
 	  <para>The rule is that if the library is called
 	    <filename>lib<replaceable>something</replaceable>.a</filename>,
 	    you give <command>cc</command> the argument
 	    <option>-l<replaceable>something</replaceable></option>.
 	    For example, the math library is
 	    <filename>libm.a</filename>, so you give
 	    <command>cc</command> the argument <option>-lm</option>.
 	    A common <quote>gotcha</quote> with the math library is
 	    that it has to be the last library on the command
 	    line.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>This will link the math library functions into
 	    <filename>foobar</filename>.</para>
 
 	  <para>If you are compiling C++ code, you need to add
 	    <option>-lg++</option>, or <option>-lstdc++</option> if
 	    you are using FreeBSD 2.2 or later, to the command line
 	    argument to link the C++ library functions.
 	    Alternatively, you can run <command>c++</command> instead
 	    of <command>cc</command>, which does this for you.
 	    <command>c++</command> can also be invoked as
 	    <command>g++</command> on FreeBSD.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -o foobar foobar.cc -lg++</userinput>     <lineannotation>For FreeBSD 2.1.6 and earlier</lineannotation>
 &prompt.user; <userinput>cc -o foobar foobar.cc -lstdc++</userinput>  <lineannotation>For FreeBSD 2.2 and later</lineannotation>
 &prompt.user; <userinput>c++ -o foobar foobar.cc</userinput>
 	    </screen>
 	  </informalexample>
 
 	  <para>Each of these will both produce an executable
 	    <filename>foobar</filename> from the C++ source file
 	    <filename>foobar.cc</filename>.  Note that, on Unix
 	    systems, C++ source files traditionally end in
 	    <filename>.C</filename>, <filename>.cxx</filename> or
 	    <filename>.cc</filename>, rather than the
 	    MS-DOS style
 	    <filename>.cpp</filename> (which was already used for
 	    something else).  <command>gcc</command> used to rely on
 	    this to work out what kind of compiler to use on the
 	    source file; however, this restriction no longer applies,
 	    so you may now call your C++ files
 	    <filename>.cpp</filename> with impunity!</para>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <sect2>
       <title>Common <command>cc</command> Queries and Problems</title>
 
       <qandaset>
 	<qandaentry>
 	  <question>
 	    <para>I am trying to write a program which uses the
 	      <function>sin()</function> function and I get an error
 	      like this.  What does it mean?</para>
 
 	    <informalexample>
 	      <screen>/var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment
 	      </screen>
 	    </informalexample>
 	  </question>
 
 	  <answer>
 	    <para>When using mathematical functions like
 	      <function>sin()</function>, you have to tell
 	      <command>cc</command> to link in the math library, like
 	      so:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>cc -o foobar foobar.c -lm</userinput>
 	      </screen>
 	    </informalexample>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>All right, I wrote this simple program to practice
 	      using <option>-lm</option>.  All it does is raise 2.1 to
 	      the power of 6.</para>
 
 	    <informalexample>
 	      <programlisting>#include &lt;stdio.h&gt;
 
 int main() {
 	float f;
 
 	f = pow(2.1, 6);
 	printf("2.1 ^ 6 = %f\n", f);
 	return 0;
 }
 	      </programlisting>
 	    </informalexample>
 
 	    <para>and I compiled it as:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>cc temp.c -lm</userinput>
 	      </screen>
 	    </informalexample>
 
 	    <para>like you said I should, but I get this when I run
 	      it:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>./a.out</userinput>
 2.1 ^ 6 = 1023.000000
 	      </screen>
 	    </informalexample>
 
 	    <para>This is <emphasis>not</emphasis> the right answer!
 	      What is going on?</para>
 	  </question>
 
 	  <answer>
 	    <para>When the compiler sees you call a function, it
 	      checks if it has already seen a prototype for it.  If it
 	      has not, it assumes the function returns an
 	      <type>int</type>, which is definitely not what you want
 	      here.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>So how do I fix this?</para>
 	  </question>
 
 	  <answer>
 	    <para>The prototypes for the mathematical functions are in
 	      <filename>math.h</filename>.  If you include this file,
 	      the compiler will be able to find the prototype and it
 	      will stop doing strange things to your
 	      calculation!</para>
 
 	    <informalexample>
 	      <programlisting>#include &lt;math.h&gt;
 #include &lt;stdio.h&gt;
 
 int main() {
 ...
 	      </programlisting>
 	    </informalexample>
 
 	    <para>After recompiling it as you did before, run
 	      it:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>./a.out</userinput>
 2.1 ^ 6 = 85.766121
 	      </screen>
 	    </informalexample>
 
 	    <para>If you are using any of the mathematical functions,
 	      <emphasis>always</emphasis> include
 	      <filename>math.h</filename> and remember to link in the
 	      math library.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>I compiled a file called
 	      <filename>foobar.c</filename> and I cannot find an
 	      executable called <filename>foobar</filename>.  Where's
 	      it gone?</para>
 	  </question>
 
 	  <answer>
 	    <para>Remember, <command>cc</command> will call the
 	      executable <filename>a.out</filename> unless you tell it
 	      differently.  Use the
 	      <option>-o&nbsp;<replaceable>filename</replaceable></option>
 	      option:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>cc -o foobar foobar.c</userinput>
 	      </screen>
 	    </informalexample>
 	  </answer>
 	</qandaentry>
 	
 	<qandaentry>
 	  <question>
 	    <para>OK, I have an executable called
 	      <filename>foobar</filename>, I can see it when I run
 	      <command>ls</command>, but when I type in
 	      <command>foobar</command> at the command prompt it tells
 	      me there is no such file.  Why can it not find
 	      it?</para>
 	  </question>
 
 	  <answer>
 	    <para>Unlike MS-DOS, Unix does not
 	      look in the current directory when it is trying to find
 	      out which executable you want it to run, unless you tell
 	      it to.  Either type <command>./foobar</command>, which
 	      means <quote>run the file called
 		<filename>foobar</filename> in the current
 		directory</quote>, or change your <envar>PATH</envar>
 	      environment
 	      variable so that it looks something like</para>
 
 	    <informalexample>
 	      <screen>bin:/usr/bin:/usr/local/bin:.
 	      </screen>
 	    </informalexample>
 
 	    <para>The dot at the end means <quote>look in the current
 		directory if it is not in any of the
 		others</quote>.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>I called my executable <filename>test</filename>,
 	      but nothing happens when I run it.  What is going
 	      on?</para>
 	  </question>
 
 	  <answer>
 	    <para>Most Unix systems have a program called
 	      <command>test</command> in <filename>/usr/bin</filename>
 	      and the shell is picking that one up before it gets to
 	      checking the current directory.  Either type:</para>
 
 	    <informalexample>
 	      <screen>&prompt.user; <userinput>./test</userinput>
 	      </screen>
 	    </informalexample>
 
 	    <para>or choose a better name for your program!</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>I compiled my program and it seemed to run all right
 	      at first, then there was an error and it said something
 	      about <errorname>core dumped</errorname>.  What does that
 	      mean?</para>
 	  </question>
 
 	  <answer>
 	    <para>The name <firstterm>core dump</firstterm> dates back
 	      to the very early days of Unix, when the machines used
 	      core memory for storing data.  Basically, if the program
 	      failed under certain conditions, the system would write
 	      the contents of core memory to disk in a file called
 	      <filename>core</filename>, which the programmer could
 	      then pore over to find out what went wrong.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Fascinating stuff, but what I am supposed to do
 	      now?</para>
 	  </question>
 
 	  <answer>
 	    <para>Use <command>gdb</command> to analyse the core (see
 	      <xref linkend="debugging">).</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>When my program dumped core, it said something about
 	      a <errorname>segmentation fault</errorname>.  What is
 	      that?</para>
 	  </question>
 
 	  <answer>
 	    <para>This basically means that your program tried to
 	      perform some sort of illegal operation on memory; Unix
 	      is designed to protect the operating system and other
 	      programs from rogue programs.</para>
 
 	    <para>Common causes for this are:</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para>Trying to write to a <symbol>NULL</symbol>
 		  pointer, eg</para>
 
 		<programlisting>char *foo = NULL;
 strcpy(foo, "bang!");
 		</programlisting>
 	      </listitem>
 
 	      <listitem>
 		<para>Using a pointer that has not been initialised,
 		  eg</para>
 
 		<programlisting>char *foo;
 strcpy(foo, "bang!");
 		</programlisting>
 
 		<para>The pointer will have some random value that,
 		  with luck, will point into an area of memory that
 		  is not available to your program and the kernel will
 		  kill your program before it can do any damage.  If
 		  you are unlucky, it will point somewhere inside your
 		  own program and corrupt one of your data structures,
 		  causing the program to fail mysteriously.</para>
 	      </listitem>
 
 	      <listitem>
 		<para>Trying to access past the end of an array,
 		  eg</para>
 
 		<programlisting>int bar[20];
 bar[27] = 6;
 		</programlisting>
 	      </listitem>
 
 	      <listitem>
 		<para>Trying to store something in read-only memory,
 		  eg</para>
 
 		<programlisting>char *foo = "My string";
 strcpy(foo, "bang!");
 		</programlisting>
 
 		<para>Unix compilers often put string literals like
 		  <literal>"My string"</literal> into read-only areas
 		  of memory.</para>
 	      </listitem>
 
 	      <listitem>
 		<para>Doing naughty things with
 		  <function>malloc()</function> and
 		  <function>free()</function>, eg</para>
 
 		<programlisting>char bar[80];
 free(bar);
 		</programlisting>
 
 		<para>or</para>
 
 		<programlisting>char *foo = malloc(27);
 free(foo);
 free(foo);
 		</programlisting>
 	      </listitem>
 	    </itemizedlist>
 
 	    <para>Making one of these mistakes will not always lead to
 	      an error, but they are always bad practice.  Some
 	      systems and compilers are more tolerant than others,
 	      which is why programs that ran well on one system can
 	      crash when you try them on an another.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Sometimes when I get a core dump it says
 	      <errorname>bus error</errorname>.  It says in my Unix
 	      book that this means a hardware problem, but the
 	      computer still seems to be working.  Is this
 	      true?</para>
 	  </question>
 
 	  <answer>
 	    <para>No, fortunately not (unless of course you really do
 	      have a hardware problem&hellip;).  This is usually
 	      another way of saying that you accessed memory in a way
 	      you should not have.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>This dumping core business sounds as though it could
 	      be quite useful, if I can make it happen when I want to.
 	      Can I do this, or do I have to wait until there is an
 	      error?</para>
 	  </question>
 
 	  <answer>
 	    <para>Yes, just go to another console or xterm, do</para>
 
 	    <screen>&prompt.user; <userinput>ps</userinput>
 	    </screen>
 
 	    <para>to find out the process ID of your program, and
 	      do</para>
 
 	    <screen>&prompt.user; <userinput>kill -ABRT <replaceable>pid</replaceable></userinput>
 	    </screen>
 
 	    <para>where
 	      <parameter><replaceable>pid</replaceable></parameter> is
 	      the process ID you looked up.</para>
 
 	    <para>This is useful if your program has got stuck in an
 	      infinite loop, for instance.  If your program happens to
 	      trap <symbol>SIGABRT</symbol>, there are several other
 	      signals which have a similar effect.</para>
 
 	    <para>Alternatively, you can create a core dump from
 	      inside your program, by calling the
 	      <function>abort()</function> function. See the manual page
 	      of &man.abort.3; to learn more.</para>
 
             <para>If you want to create a core dump from outside your
               program, but do not want the process to terminate, you
               can use the <command>gcore</command> program. See the
               manual page of &man.gcore.1; for more information.</para>
 
 	  </answer>
 	</qandaentry>
       </qandaset>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="tools-make">
     <title>Make</title>
 
     <sect2>
       <title>What is <command>make</command>?</title>
 
       <para>When you are working on a simple program with only one or
 	two source files, typing in</para>
 
       <screen>&prompt.user; <userinput>cc file1.c file2.c</userinput></screen>
 
       <para>is not too bad, but it quickly becomes very tedious when
 	there are several files&mdash;and it can take a while to
 	compile, too.</para>
 
       <para>One way to get around this is to use object files and only
 	recompile the source file if the source code has changed.  So
 	we could have something like:</para>
 
       <screen>&prompt.user; <userinput>cc file1.o file2.o</userinput> &hellip; <userinput>file37.c</userinput> &hellip;</screen>
 
       <para>if we had changed <filename>file37.c</filename>, but not any
 	of the others, since the last time we compiled.  This may
 	speed up the compilation quite a bit, but does not solve the
 	typing problem.</para>
 
       <para>Or we could write a shell script to solve the typing
 	problem, but it would have to re-compile everything, making it
 	very inefficient on a large project.</para>
 
       <para>What happens if we have hundreds of source files lying
 	about? What if we are working in a team with other people who
 	forget to tell us when they have changed one of their source
 	files that we use?</para>
 
       <para>Perhaps we could put the two solutions together and write
 	something like a shell script that would contain some kind of
 	magic rule saying when a source file needs compiling.  Now all
 	we need now is a program that can understand these rules, as
 	it is a bit too complicated for the shell.</para>
 
       <para>This program is called <command>make</command>.  It reads
 	in a file, called a <firstterm>makefile</firstterm>, that
 	tells it how different files depend on each other, and works
 	out which files need to be re-compiled and which ones do not.
 	For example, a rule could say something like <quote>if
 	  <filename>fromboz.o</filename> is older than
 	  <filename>fromboz.c</filename>, that means someone must have
 	  changed <filename>fromboz.c</filename>, so it needs to be
 	  re-compiled.</quote> The makefile also has rules telling
 	make <emphasis>how</emphasis> to re-compile the source file,
 	making it a much more powerful tool.</para>
 
       <para>Makefiles are typically kept in the same directory as the
 	source they apply to, and can be called
 	<filename>makefile</filename>, <filename>Makefile</filename>
 	or <filename>MAKEFILE</filename>.  Most programmers use the
 	name <filename>Makefile</filename>, as this puts it near the
 	top of a directory listing, where it can easily be
 	seen.
 
 	<footnote>
 	  <para>They do not use the <filename>MAKEFILE</filename> form
 	    as block capitals are often used for documentation files
 	    like <filename>README</filename>.</para>
 	</footnote></para>
     </sect2>
 
     <sect2>
       <title>Example of using <command>make</command></title>
 
       <para>Here is a very simple make file:</para>
 
       <programlisting>foo: foo.c
 	cc -o foo foo.c</programlisting>
 
       <para>It consists of two lines, a dependency line and a creation
 	line.</para>
 
       <para>The dependency line here consists of the name of the
 	program (known as the <firstterm>target</firstterm>), followed
 	by a colon, then whitespace, then the name of the source file.
 	When <command>make</command> reads this line, it looks to see
 	if <filename>foo</filename> exists; if it exists, it compares
 	the time <filename>foo</filename> was last modified to the
 	time <filename>foo.c</filename> was last modified.  If
 	<filename>foo</filename> does not exist, or is older than
 	<filename>foo.c</filename>, it then looks at the creation line
 	to find out what to do.  In other words, this is the rule for
 	working out when <filename>foo.c</filename> needs to be
 	re-compiled.</para>
 
       <para>The creation line starts with a <token>tab</token> (press
 	the <keycap>tab</keycap> key) and then the command you would
 	type to create <filename>foo</filename> if you were doing it
 	at a command prompt.  If <filename>foo</filename> is out of
 	date, or does not exist, <command>make</command> then executes
 	this command to create it.  In other words, this is the rule
 	which tells make how to re-compile
 	<filename>foo.c</filename>.</para>
 
       <para>So, when you type <userinput>make</userinput>, it will
 	make sure that <filename>foo</filename> is up to date with
 	respect to your latest changes to <filename>foo.c</filename>.
 	This principle can be extended to
 	<filename>Makefile</filename>s with hundreds of
 	targets&mdash;in fact, on FreeBSD, it is possible to compile
 	the entire operating system just by typing <userinput>make
 	  world</userinput> in the appropriate directory!</para>
 
       <para>Another useful property of makefiles is that the targets
 	do not have to be programs.  For instance, we could have a make
 	file that looks like this:</para>
 
       <programlisting>foo: foo.c
 	cc -o foo foo.c
 
 install:
 	cp foo /home/me</programlisting>
 
       <para>We can tell make which target we want to make by
 	typing:</para>
 
       <screen>&prompt.user; <userinput>make <replaceable>target</replaceable></userinput></screen>
 
       <para><command>make</command> will then only look at that target
 	and ignore any others.  For example, if we type
 	<userinput>make foo</userinput> with the makefile above, make
 	will ignore the <maketarget>install</maketarget> target.</para>
 
       <para>If we just type <userinput>make</userinput> on its own,
 	make will always look at the first target and then stop
 	without looking at any others.  So if we typed
 	<userinput>make</userinput> here, it will just go to the
 	<maketarget>foo</maketarget> target, re-compile
 	<filename>foo</filename> if necessary, and then stop without
 	going on to the <maketarget>install</maketarget> target.</para>
 
       <para>Notice that the <maketarget>install</maketarget> target does not
 	actually depend on anything! This means that the command on
 	the following line is always executed when we try to make that
 	target by typing <userinput>make install</userinput>.  In this
 	case, it will copy <filename>foo</filename> into the user's
 	home directory.  This is often used by application makefiles,
 	so that the application can be installed in the correct
 	directory when it has been correctly compiled.</para>
 
       <para>This is a slightly confusing subject to try to explain.
 	If you do not quite understand how <command>make</command>
 	works, the best thing to do is to write a simple program like
 	<quote>hello world</quote> and a make file like the one above
 	and experiment.  Then progress to using more than one source
 	file, or having the source file include a header file.  The
 	<command>touch</command> command is very useful here&mdash;it
 	changes the date on a file without you having to edit
 	it.</para>
     </sect2>
 
     <sect2>
       <title>Make and include-files</title>
 
       <para>C code often starts with a list of files to include, for
 	example stdio.h. Some of these files are system-include
 	files, some of them are from the project you are now working
 	on:
       </para>
 
       <programlisting>#include &lt;stdio.h&gt;
 #include "foo.h"
 
 int main(....</programlisting>
 
       <para>To make sure that this file is recompiled the moment
         <filename>foo.h</filename> is changed, you have to add it in
         your <filename>Makefile</filename>:</para>
 
       <programlisting>foo: foo.c foo.h</programlisting>
 
       <para>The moment your project is getting bigger and you have
 	more and more own include-files to maintain, it will be a
 	pain to keep track of all include files and the files which
 	are depending on it. If you change an include-file but
 	forget to recompile all the files which are depending on
 	it, the results will be devastating. <command>gcc</command>
 	has an option to analyze your files and to produce a list
 	of include-files and their dependencies: <option>-MM</option>.
       </para>
 
       <para>If you add this to your Makefile:</para>
 
       <programlisting>depend:
 	gcc -E -MM *.c &gt; .depend</programlisting>
 
       <para>and run <userinput>make depend</userinput>, the file
 	<filename>.depend</filename> will appear with a list of
 	object-files, C-files and the include-files:</para>
 
       <programlisting>foo.o: foo.c foo.h</programlisting>
 
       <para>If you change <filename>foo.h</filename>, next time
 	you run <command>make</command> all files depending on
 	<filename>foo.h</filename> will be recompiled.</para>
 
       <para>Do not forget to run <command>make depend</command> each
         time you add an include-file to one of your files.</para>
     </sect2>
 
     <sect2>
       <title>FreeBSD Makefiles</title>
 
       <para>Makefiles can be rather complicated to write.  Fortunately,
 	BSD-based systems like FreeBSD come with some very powerful
 	ones as part of the system.  One very good example of this is
 	the FreeBSD ports system.  Here is the essential part of a
 	typical ports <filename>Makefile</filename>:</para>
 
       <programlisting>MASTER_SITES=   ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/
 DISTFILES=      scheme-microcode+dist-7.3-freebsd.tgz
 
 .include &lt;bsd.port.mk&gt;</programlisting>
 
       <para>Now, if we go to the directory for this port and type
 	<userinput>make</userinput>, the following happens:</para>
 
       <procedure>
 	<step>
 	  <para>A check is made to see if the source code for this
 	    port is already on the system.</para>
 	</step>
 
 	<step>
 	  <para>If it is not, an FTP connection to the URL in
 	    <symbol>MASTER_SITES</symbol> is set up to download the
 	    source.</para>
 	</step>
 
 	<step>
 	  <para>The checksum for the source is calculated and compared
 	    it with one for a known, good, copy of the source.  This
 	    is to make sure that the source was not corrupted while in
 	    transit.</para>
 	</step>
 
 	<step>
 	  <para>Any changes required to make the source work on
 	    FreeBSD are applied&mdash;this is known as
 	    <firstterm>patching</firstterm>.</para>
 	</step>
 
 	<step>
 	  <para>Any special configuration needed for the source is
 	    done.  (Many Unix program distributions try to work out
 	    which version of Unix they are being compiled on and which
 	    optional Unix features are present&mdash;this is where
 	    they are given the information in the FreeBSD ports
 	    scenario).</para>
 	</step>
 
 	<step>
 	  <para>The source code for the program is compiled.  In
 	    effect, we change to the directory where the source was
 	    unpacked and do <command>make</command>&mdash;the
 	    program's own make file has the necessary information to
 	    build the program.</para>
 	</step>
 
 	<step>
 	  <para>We now have a compiled version of the program.  If we
 	    wish, we can test it now; when we feel confident about the
 	    program, we can type <userinput>make install</userinput>.
 	    This will cause the program and any supporting files it
 	    needs to be copied into the correct location; an entry is
 	    also made into a <database>package database</database>, so
 	    that the port can easily be uninstalled later if we change
 	    our mind about it.</para>
 	</step>
       </procedure>
 
       <para>Now I think you will agree that is rather impressive for a
 	four line script!</para>
 
       <para>The secret lies in the last line, which tells
 	<command>make</command> to look in the system makefile called
 	<filename>bsd.port.mk</filename>.  It is easy to overlook this
 	line, but this is where all the clever stuff comes
 	from&mdash;someone has written a makefile that tells
 	<command>make</command> to do all the things above (plus a
 	couple of other things I did not mention, including handling
 	any errors that may occur) and anyone can get access to that
 	just by putting a single line in their own make file!</para>
 
       <para>If you want to have a look at these system makefiles,
 	they are in <filename>/usr/share/mk</filename>, but it is
 	probably best to wait until you have had a bit of practice with
 	makefiles, as they are very complicated (and if you do look at
 	them, make sure you have a flask of strong coffee
 	handy!)</para>
     </sect2>
 
     <sect2>
       <title>More advanced uses of <command>make</command></title>
 
       <para><command>Make</command> is a very powerful tool, and can
 	do much more than the simple example above shows.
 	Unfortunately, there are several different versions of
 	<command>make</command>, and they all differ considerably.
 	The best way to learn what they can do is probably to read the
 	documentation&mdash;hopefully this introduction will have
 	given you a base from which you can do this.</para>
 
       <para>The version of make that comes with FreeBSD is the
 	<application>Berkeley make</application>; there is a tutorial
 	for it in <filename>/usr/share/doc/psd/12.make</filename>.  To
 	view it, do</para>
 
       <screen>&prompt.user; <userinput>zmore paper.ascii.gz</userinput></screen>
 
       <para>in that directory.</para>
 
       <para>Many applications in the ports use <application>GNU
 	  make</application>, which has a very good set of
 	<quote>info</quote> pages.  If you have installed any of these
 	ports, <application>GNU make</application> will automatically
 	have been installed as <command>gmake</command>.  It is also
 	available as a port and package in its own right.</para>
 
       <para>To view the info pages for <application>GNU
 	make</application>, you will have to edit the
 	<filename>dir</filename> file in the
 	<filename>/usr/local/info</filename> directory to add an entry
 	for it.  This involves adding a line like</para>
 
       <programlisting> * Make: (make).                 The GNU Make utility.</programlisting>
 
       <para>to the file.  Once you have done this, you can type
 	<userinput>info</userinput> and then select
 	<guimenuitem>make</guimenuitem> from the menu (or in
 	<application>Emacs</application>, do <userinput>C-h
 	  i</userinput>).</para>
     </sect2>
   </sect1>
 
   <sect1 id="debugging">
     <title>Debugging</title>
 
     <sect2>
       <title>The Debugger</title>
 
       <para>The debugger that comes with FreeBSD is called
 	<command>gdb</command> (<application>GNU
 	  debugger</application>).  You start it up by typing</para>
 
       <screen>&prompt.user; <userinput>gdb <replaceable>progname</replaceable></userinput></screen>
 
       <para>although most people prefer to run it inside
 	<application>Emacs</application>.  You can do this by:</para>
 
       <screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput></screen>
 
       <para>Using a debugger allows you to run the program under more
 	controlled circumstances.  Typically, you can step through the
 	program a line at a time, inspect the value of variables,
 	change them, tell the debugger to run up to a certain point
 	and then stop, and so on.  You can even attach to a program
 	that is already running, or load a core file to investigate why
 	the program crashed.  It is even possible to debug the kernel,
 	though that is a little trickier than the user applications
 	we will be discussing in this section.</para>
 
       <para><command>gdb</command> has quite good on-line help, as
 	well as a set of info pages, so this section will concentrate
 	on a few of the basic commands.</para>
 
       <para>Finally, if you find its text-based command-prompt style
 	off-putting, there is a graphical front-end for it (<ulink
 	  URL="../../../../ports/devel.html">xxgdb</ulink>) in the ports
 	collection.</para>
 
       <para>This section is intended to be an introduction to using
 	<command>gdb</command> and does not cover specialised topics
 	such as debugging the kernel.</para>
     </sect2>
 
     <sect2>
       <title>Running a program in the debugger</title>
 
       <para>You will need to have compiled the program with the
 	<option>-g</option> option to get the most out of using
 	<command>gdb</command>.  It will work without, but you will only
 	see the name of the function you are in, instead of the source
 	code.  If you see a line like:</para>
 
       <screen>&hellip; (no debugging symbols found) &hellip;</screen>
 
       <para>when <command>gdb</command> starts up, you will know that
 	the program was not compiled with the <option>-g</option>
 	option.</para>
 
       <para>At the <command>gdb</command> prompt, type
 	<userinput>break main</userinput>.  This will tell the
 	debugger to skip over the preliminary set-up code in the
 	program and start at the beginning of your code.  Now type
 	<userinput>run</userinput> to start the program&mdash;it will
 	start at the beginning of the set-up code and then get stopped
 	by the debugger when it calls <function>main()</function>.
 	(If you have ever wondered where <function>main()</function>
 	gets called from, now you know!).</para>
 
       <para>You can now step through the program, a line at a time, by
 	pressing <command>n</command>.  If you get to a function call,
 	you can step into it by pressing <command>s</command>.  Once
 	you are in a function call, you can return from stepping into a
 	function call by pressing <command>f</command>.  You can also
 	use <command>up</command> and <command>down</command> to take
 	a quick look at the caller.</para>
 
       <para>Here is a simple example of how to spot a mistake in a
 	program with <command>gdb</command>.  This is our program
 	(with a deliberate mistake):</para>
 
       <programlisting>#include &lt;stdio.h&gt;
 
 int bazz(int anint);
 
 main() {
 	int i;
 
 	printf("This is my program\n");
 	bazz(i);
 	return 0;
 }
 
 int bazz(int anint) {
 	printf("You gave me %d\n", anint);
 	return anint;
 }</programlisting>
 
       <para>This program sets <symbol>i</symbol> to be
 	<literal>5</literal> and passes it to a function
 	<function>bazz()</function> which prints out the number we
 	gave it.</para>
 
       <para>When we compile and run the program we get</para>
 
       <screen>&prompt.user; <userinput>cc -g -o temp temp.c</userinput>
 &prompt.user; <userinput>./temp</userinput>
 This is my program
 anint = 4231</screen>
 
       <para>That was not what we expected! Time to see what is going
 	on!</para>
 
       <screen>&prompt.user; <userinput>gdb temp</userinput>
 GDB is free software and you are welcome to distribute copies of it
  under certain conditions; type "show copying" to see the conditions.
 There is absolutely no warranty for GDB; type "show warranty" for details.
 GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
 (gdb) <userinput>break main</userinput>				<lineannotation>Skip the set-up code</lineannotation>
 Breakpoint 1 at 0x160f: file temp.c, line 9.	<lineannotation><command>gdb</command> puts breakpoint at <function>main()</function></lineannotation>
 (gdb) <userinput>run</userinput>					<lineannotation>Run as far as <function>main()</function></lineannotation>
 Starting program: /home/james/tmp/temp		<lineannotation>Program starts running</lineannotation>
 
 Breakpoint 1, main () at temp.c:9		<lineannotation><command>gdb</command> stops at <function>main()</function></lineannotation>
 (gdb) <userinput>n</userinput>						<lineannotation>Go to next line</lineannotation>
 This is my program				<lineannotation>Program prints out</lineannotation>
 (gdb) <userinput>s</userinput>						<lineannotation>step into <function>bazz()</function></lineannotation>
 bazz (anint=4231) at temp.c:17			<lineannotation><command>gdb</command> displays stack frame</lineannotation>
 (gdb)</screen>
 
       <para>Hang on a minute! How did <symbol>anint</symbol> get to be
 	<literal>4231</literal>? Did we not we set it to be
 	<literal>5</literal> in <function>main()</function>? Let's
 	move up to <function>main()</function> and have a look.</para>
 
       <screen>(gdb) <userinput>up</userinput>					<lineannotation>Move up call stack</lineannotation>
 #1  0x1625 in main () at temp.c:11		<lineannotation><command>gdb</command> displays stack frame</lineannotation>
 (gdb) <userinput>p i</userinput>					<lineannotation>Show us the value of <symbol>i</symbol></lineannotation>
 $1 = 4231					<lineannotation><command>gdb</command> displays <literal>4231</literal></lineannotation></screen>
 
       <para>Oh dear! Looking at the code, we forgot to initialise
 	<symbol>i</symbol>.  We meant to put</para>
 
       <programlisting><lineannotation>&hellip;</lineannotation>
 main() {
 	int i;
 
 	i = 5;
 	printf("This is my program\n");
 <lineannotation>&hellip;</lineannotation></programlisting>
 
       <para>but we left the <literal>i=5;</literal> line out.  As we
 	did not initialise <symbol>i</symbol>, it had whatever number
 	happened to be in that area of memory when the program ran,
 	which in this case happened to be
 	<literal>4231</literal>.</para>
 
       <note>
 	<para><command>gdb</command> displays the stack frame every
 	  time we go into or out of a function, even if we are using
 	  <command>up</command> and <command>down</command> to move
 	  around the call stack.  This shows the name of the function
 	  and the values of its arguments, which helps us keep track
 	  of where we are and what is going on.  (The stack is a
 	  storage area where the program stores information about the
 	  arguments passed to functions and where to go when it
 	  returns from a function call).</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Examining a core file</title>
 
       <para>A core file is basically a file which contains the
 	complete state of the process when it crashed.  In <quote>the
 	  good old days</quote>, programmers had to print out hex
 	listings of core files and sweat over machine code manuals,
 	but now life is a bit easier.  Incidentally, under FreeBSD and
 	other 4.4BSD systems, a core file is called
 	<filename><replaceable>progname</replaceable>.core</filename> instead of just
 	<filename>core</filename>, to make it clearer which program a
 	core file belongs to.</para>
 
       <para>To examine a core file, start up <command>gdb</command> in
 	the usual way.  Instead of typing <command>break</command> or
 	<command>run</command>, type</para>
 
       <screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput></screen>
 
       <para>If you are not in the same directory as the core file,
 	you will have to do <userinput>dir
 	  /path/to/core/file</userinput> first.</para>
 
       <para>You should see something like this:</para>
 
       <screen>&prompt.user; <userinput>gdb a.out</userinput>
 GDB is free software and you are welcome to distribute copies of it
  under certain conditions; type "show copying" to see the conditions.
 There is absolutely no warranty for GDB; type "show warranty" for details.
 GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc.
 (gdb) <userinput>core a.out.core</userinput>
 Core was generated by `a.out'.
 Program terminated with signal 11, Segmentation fault.
 Cannot access memory at address 0x7020796d.
 #0  0x164a in bazz (anint=0x5) at temp.c:17
 (gdb)</screen>
 
       <para>In this case, the program was called
 	<filename>a.out</filename>, so the core file is called
 	<filename>a.out.core</filename>.  We can see that the program
 	crashed due to trying to access an area in memory that was not
 	available to it in a function called
 	<function>bazz</function>.</para>
 
       <para>Sometimes it is useful to be able to see how a function was
 	called, as the problem could have occurred a long way up the
 	call stack in a complex program.  The <command>bt</command>
 	command causes <command>gdb</command> to print out a
 	back-trace of the call stack:</para>
 
       <screen>(gdb) <userinput>bt</userinput>
 #0  0x164a in bazz (anint=0x5) at temp.c:17
 #1  0xefbfd888 in end ()
 #2  0x162c in main () at temp.c:11
 (gdb)</screen>
 
       <para>The <function>end()</function> function is called when a
 	program crashes; in this case, the <function>bazz()</function>
 	function was called from <function>main()</function>.</para>
     </sect2>
 
     <sect2>
       <title>Attaching to a running program</title>
 
       <para>One of the neatest features about <command>gdb</command>
 	is that it can attach to a program that is already running.  Of
 	course, that assumes you have sufficient permissions to do so.
 	A common problem is when you are stepping through a program
 	that forks, and you want to trace the child, but the debugger
 	will only let you trace the parent.</para>
 
       <para>What you do is start up another <command>gdb</command>,
 	use <command>ps</command> to find the process ID for the
 	child, and do</para>
 
       <screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput></screen>
 
       <para>in <command>gdb</command>, and then debug as usual.</para>
 
       <para><quote>That is all very well,</quote> you are probably
 	thinking, <quote>but by the time I have done that, the child
 	  process will be over the hill and far away</quote>.  Fear
 	not, gentle reader, here is how to do it (courtesy of the
 	<command>gdb</command> info pages):</para>
 
       <screen><lineannotation>&hellip;</lineannotation>
 if ((pid = fork()) < 0)		/* _Always_ check this */
 	error();
 else if (pid == 0) {		/* child */
 	int PauseMode = 1;
 
 	while (PauseMode)
 		sleep(10);	/* Wait until someone attaches to us */
 	<lineannotation>&hellip;</lineannotation>
 } else {			/* parent */
 	<lineannotation>&hellip;</lineannotation></screen>
 
       <para>Now all you have to do is attach to the child, set
 	<symbol>PauseMode</symbol> to <literal>0</literal>, and wait
 	for the <function>sleep()</function> call to return!</para>
     </sect2>
   </sect1>
 
   <sect1 id="emacs">
     <title>Using Emacs as a Development Environment</title>
 
     <sect2>
       <title>Emacs</title>
 
       <para>Unfortunately, Unix systems do not come with the kind of
 	everything-you-ever-wanted-and-lots-more-you-did-not-in-one-gigantic-package
 	integrated development environments that other systems
 	have.
 
 	<footnote>
 	  <para>Some powerful, free IDEs now exist, such as KDevelop
 	    in the ports collection.</para>
 	</footnote>
 
 	However, it is possible to set up your own environment.  It
 	may not be as pretty, and it may not be quite as integrated,
 	but you can set it up the way you want it.  And it is free.
 	And you have the source to it.</para>
 
       <para>The key to it all is Emacs.  Now there are some people who
 	loathe it, but many who love it.  If you are one of the former,
 	I am afraid this section will hold little of interest to you.
 	Also, you will need a fair amount of memory to run it&mdash;I would
 	recommend 8MB in text mode and 16MB in X as the bare minimum
 	to get reasonable performance.</para>
 
       <para>Emacs is basically a highly customisable
 	editor&mdash;indeed, it has been customised to the point where
 	it is more like an operating system than an editor! Many
 	developers and sysadmins do in fact spend practically all
 	their time working inside Emacs, leaving it only to log
 	out.</para>
 
       <para>It is impossible even to summarise everything Emacs can do
 	here, but here are some of the features of interest to
 	developers:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Very powerful editor, allowing search-and-replace on
 	    both strings and regular expressions (patterns), jumping
 	    to start/end of block expression, etc, etc.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Pull-down menus and online help.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Language-dependent syntax highlighting and
 	    indentation.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Completely customisable.</para>
 	</listitem>
 
 	<listitem>
 	  <para>You can compile and debug programs within
 	    Emacs.</para>
 	</listitem>
 
 	<listitem>
 	  <para>On a compilation error, you can jump to the offending
 	    line of source code.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Friendly-ish front-end to the <command>info</command>
 	    program used for reading GNU hypertext documentation,
 	    including the documentation on Emacs itself.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Friendly front-end to <command>gdb</command>, allowing
 	    you to look at the source code as you step through your
 	    program.</para>
 	</listitem>
 
 	<listitem>
 	  <para>You can read Usenet news and mail while your program
 	    is compiling.</para>
 	</listitem>
       </itemizedlist>
 
       <para>And doubtless many more that I have overlooked.</para>
 
       <para>Emacs can be installed on FreeBSD using <ulink
 	  URL="../../../../ports/editors.html">the Emacs
 	  port</ulink>.</para>
 
       <para>Once it is installed, start it up and do <userinput>C-h
 	  t</userinput> to read an Emacs tutorial&mdash;that means
 	hold down the <keycap>control</keycap> key, press
 	<keycap>h</keycap>, let go of the <keycap>control</keycap>
 	key, and then press <keycap>t</keycap>.  (Alternatively, you
 	can you use the mouse to select <guimenuitem>Emacs
 	  Tutorial</guimenuitem> from the <guimenu>Help</guimenu>
 	menu).</para>
 
       <para>Although Emacs does have menus, it is well worth learning
 	the key bindings, as it is much quicker when you are editing
 	something to press a couple of keys than to try and find the
 	mouse and then click on the right place.  And, when you are
 	talking to seasoned Emacs users, you will find they often
 	casually throw around expressions like <quote><literal>M-x
 	    replace-s RET foo RET bar RET</literal></quote> so it is
 	useful to know what they mean.  And in any case, Emacs has far
 	too many useful functions for them to all fit on the menu
 	bars.</para>
 
       <para>Fortunately, it is quite easy to pick up the key-bindings,
 	as they are displayed next to the menu item.  My advice is to
 	use the menu item for, say, opening a file until you
 	understand how it works and feel confident with it, then try
 	doing C-x C-f.  When you are happy with that, move on to
 	another menu command.</para>
 
       <para>If you can not remember what a particular combination of
 	keys does, select <guimenuitem>Describe Key</guimenuitem> from
 	the <guimenu>Help</guimenu> menu and type it in&mdash;Emacs
 	will tell you what it does.  You can also use the
 	<guimenuitem>Command Apropos</guimenuitem> menu item to find
 	out all the commands which contain a particular word in them,
 	with the key binding next to it.</para>
 
       <para>By the way, the expression above means hold down the
 	<keysym>Meta</keysym> key, press <keysym>x</keysym>, release
 	the <keysym>Meta</keysym> key, type
 	<userinput>replace-s</userinput> (short for
 	<literal>replace-string</literal>&mdash;another feature of
 	Emacs is that you can abbreviate commands), press the
 	<keysym>return</keysym> key, type <userinput>foo</userinput>
 	(the string you want replaced), press the
 	<keysym>return</keysym> key, type bar (the string you want to
 	replace <literal>foo</literal> with) and press
 	<keysym>return</keysym> again.  Emacs will then do the
 	search-and-replace operation you have just requested.</para>
 
       <para>If you are wondering what on earth the
 	<keysym>Meta</keysym> key is, it is a special key that many
 	Unix workstations have.  Unfortunately, PC's do not have one,
 	so it is usually the <keycap>alt</keycap> key (or if you are
 	unlucky, the <keysym>escape</keysym> key).</para>
 
       <para>Oh, and to get out of Emacs, do <command>C-x C-c</command>
 	(that means hold down the <keysym>control</keysym> key, press
 	<keysym>x</keysym>, press <keysym>c</keysym> and release the
 	<keysym>control</keysym> key).  If you have any unsaved files
 	open, Emacs will ask you if you want to save them.  (Ignore
 	the bit in the documentation where it says
 	<command>C-z</command> is the usual way to leave
 	Emacs&mdash;that leaves Emacs hanging around in the
 	background, and is only really useful if you are on a system
 	which does not have virtual terminals).</para>
     </sect2>
 
     <sect2>
       <title>Configuring Emacs</title>
 
       <para>Emacs does many wonderful things; some of them are built
 	in, some of them need to be configured.</para>
 
       <para>Instead of using a proprietary macro language for
 	configuration, Emacs uses a version of Lisp specially adapted
 	for editors, known as Emacs Lisp.  This can be quite useful if
 	you want to go on and learn something like Common Lisp, as
 	it is considerably smaller than Common Lisp (although still
 	quite big!).</para>
 
       <para>The best way to learn Emacs Lisp is to download the <ulink
 	  URL="ftp://ftp.gnu.org/old-gnu/emacs/elisp-manual-19-2.4.tar.gz">Emacs
 	  Tutorial</ulink></para>
 
       <para>However, there is no need to actually know any Lisp to get
 	started with configuring Emacs, as I have included a sample
 	<filename>.emacs</filename> file, which should be enough to
 	get you started.  Just copy it into your home directory and
 	restart Emacs if it is already running; it will read the
 	commands from the file and (hopefully) give you a useful basic
 	setup.</para>
     </sect2>
 
     <sect2>
       <title>A sample <filename>.emacs</filename> file</title>
 
       <para>Unfortunately, there is far too much here to explain it in
 	detail; however there are one or two points worth
 	mentioning.</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Everything beginning with a <literal>;</literal> is a comment
 	    and is ignored by Emacs.</para>
 	</listitem>
 
 	<listitem>
 	  <para>In the first line, the
 	    <literal>-*-&nbsp;Emacs-Lisp&nbsp;-*-</literal> is so that
 	    we can edit the <filename>.emacs</filename> file itself
 	    within Emacs and get all the fancy features for editing
 	    Emacs Lisp.  Emacs usually tries to guess this based on
 	    the filename, and may not get it right for
 	    <filename>.emacs</filename>.</para>
 	</listitem>
 
 	<listitem>
 	  <para>The <keysym>tab</keysym> key is bound to an
 	    indentation function in some modes, so when you press the
 	    tab key, it will indent the current line of code.  If you
 	    want to put a <token>tab</token> character in whatever
 	    you are writing, hold the <keysym>control</keysym> key down
 	    while you are pressing the <keysym>tab</keysym> key.</para>
 	</listitem>
 
 	<listitem>
 	  <para>This file supports syntax highlighting for C, C++,
 	    Perl, Lisp and Scheme, by guessing the language from the
 	    filename.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Emacs already has a pre-defined function called
 	    <function>next-error</function>.  In a compilation output
 	    window, this allows you to move from one compilation error
 	    to the next by doing <command>M-n</command>; we define a
 	    complementary function,
 	    <function>previous-error</function>, that allows you to go
 	    to a previous error by doing <command>M-p</command>.  The
 	    nicest feature of all is that <command>C-c C-c</command>
 	    will open up the source file in which the error occurred
 	    and jump to the appropriate line.</para>
 	</listitem>
 
 	<listitem>
 	  <para>We enable Emacs's ability to act as a server, so that
 	    if you are doing something outside Emacs and you want to
 	    edit a file, you can just type in</para>
 
 	  <screen>&prompt.user; <userinput>emacsclient <replaceable>filename</replaceable></userinput>
 	  </screen>
 
 	  <para>and then you can edit the file in your
 	    Emacs!
 
 	    <footnote>
 	      <para>Many Emacs users set their <envar>EDITOR</envar>
 		environment to
 		<literal>emacsclient</literal> so this happens every
 		time they need to edit a file.</para>
 	    </footnote></para>
 	</listitem>
       </itemizedlist>
 
       <example>
 	<title>A sample <filename>.emacs</filename> file</title>
 
 	<programlisting>;; -*-Emacs-Lisp-*-
 
 ;; This file is designed to be re-evaled; use the variable first-time
 ;; to avoid any problems with this.
 (defvar first-time t 
   "Flag signifying this is the first time that .emacs has been evaled")
 
 ;; Meta
 (global-set-key "\M- " 'set-mark-command)
 (global-set-key "\M-\C-h" 'backward-kill-word)
 (global-set-key "\M-\C-r" 'query-replace)
 (global-set-key "\M-r" 'replace-string)
 (global-set-key "\M-g" 'goto-line)
 (global-set-key "\M-h" 'help-command)
 
 ;; Function keys
 (global-set-key [f1] 'manual-entry)
 (global-set-key [f2] 'info)
 (global-set-key [f3] 'repeat-complex-command)
 (global-set-key [f4] 'advertised-undo)
 (global-set-key [f5] 'eval-current-buffer)
 (global-set-key [f6] 'buffer-menu)
 (global-set-key [f7] 'other-window)
 (global-set-key [f8] 'find-file)
 (global-set-key [f9] 'save-buffer)
 (global-set-key [f10] 'next-error)
 (global-set-key [f11] 'compile)
 (global-set-key [f12] 'grep)
 (global-set-key [C-f1] 'compile)
 (global-set-key [C-f2] 'grep)
 (global-set-key [C-f3] 'next-error)
 (global-set-key [C-f4] 'previous-error)
 (global-set-key [C-f5] 'display-faces)
 (global-set-key [C-f8] 'dired)
 (global-set-key [C-f10] 'kill-compilation)
 
 ;; Keypad bindings
 (global-set-key [up] "\C-p")
 (global-set-key [down] "\C-n")
 (global-set-key [left] "\C-b")
 (global-set-key [right] "\C-f")
 (global-set-key [home] "\C-a")
 (global-set-key [end] "\C-e")
 (global-set-key [prior] "\M-v")
 (global-set-key [next] "\C-v")
 (global-set-key [C-up] "\M-\C-b")
 (global-set-key [C-down] "\M-\C-f")
 (global-set-key [C-left] "\M-b")
 (global-set-key [C-right] "\M-f")
 (global-set-key [C-home] "\M-&lt;")
 (global-set-key [C-end] "\M-&gt;")
 (global-set-key [C-prior] "\M-&lt;")
 (global-set-key [C-next] "\M-&gt;")
 
 ;; Mouse
 (global-set-key [mouse-3] 'imenu)
 
 ;; Misc
 (global-set-key [C-tab] "\C-q\t")	; Control tab quotes a tab.
 (setq backup-by-copying-when-mismatch t)
 
 ;; Treat 'y' or &lt;CR&gt; as yes, 'n' as no.
 (fset 'yes-or-no-p 'y-or-n-p)
     (define-key query-replace-map [return] 'act)
     (define-key query-replace-map [?\C-m] 'act)
 
 ;; Load packages
 (require 'desktop)
 (require 'tar-mode)
 
 ;; Pretty diff mode
 (autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t)
 (autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t)
 (autoload 'ediff-files-remote "ediff"
   "Intelligent Emacs interface to diff")
 
 (if first-time
     (setq auto-mode-alist
 	  (append '(("\\.cpp$" . c++-mode)
 		    ("\\.hpp$" . c++-mode)
                     ("\\.lsp$" . lisp-mode)
 		    ("\\.scm$" . scheme-mode)
 		    ("\\.pl$" . perl-mode)
 		    ) auto-mode-alist)))
 
 ;; Auto font lock mode
 (defvar font-lock-auto-mode-list 
   (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode)
   "List of modes to always start in font-lock-mode")
 
 (defvar font-lock-mode-keyword-alist
   '((c++-c-mode . c-font-lock-keywords)
     (perl-mode . perl-font-lock-keywords))
   "Associations between modes and keywords")
 
 (defun font-lock-auto-mode-select ()
   "Automatically select font-lock-mode if the current major mode is
 in font-lock-auto-mode-list"
   (if (memq major-mode font-lock-auto-mode-list) 
       (progn
 	(font-lock-mode t))
     )
   )
 
 (global-set-key [M-f1] 'font-lock-fontify-buffer)
 
 ;; New dabbrev stuff
 ;(require 'new-dabbrev)
 (setq dabbrev-always-check-other-buffers t)
 (setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_")
 (add-hook 'emacs-lisp-mode-hook
 	  '(lambda () 
 	     (set (make-local-variable 'dabbrev-case-fold-search) nil)
 	     (set (make-local-variable 'dabbrev-case-replace) nil)))
 (add-hook 'c-mode-hook
 	  '(lambda () 
 	     (set (make-local-variable 'dabbrev-case-fold-search) nil)
 	     (set (make-local-variable 'dabbrev-case-replace) nil)))
 (add-hook 'text-mode-hook
 	  '(lambda () 
 	     (set (make-local-variable 'dabbrev-case-fold-search) t)
 	     (set (make-local-variable 'dabbrev-case-replace) t)))
 
 ;; C++ and C mode...
 (defun my-c++-mode-hook ()
   (setq tab-width 4)
   (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
   (define-key c++-mode-map "\C-ce" 'c-comment-edit)
   (setq c++-auto-hungry-initial-state 'none)
   (setq c++-delete-function 'backward-delete-char)
   (setq c++-tab-always-indent t)
   (setq c-indent-level 4)
   (setq c-continued-statement-offset 4)
   (setq c++-empty-arglist-indent 4))
 
 (defun my-c-mode-hook ()
   (setq tab-width 4)
   (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent)
   (define-key c-mode-map "\C-ce" 'c-comment-edit)
   (setq c-auto-hungry-initial-state 'none)
   (setq c-delete-function 'backward-delete-char)
   (setq c-tab-always-indent t)
 ;; BSD-ish indentation style
   (setq c-indent-level 4)
   (setq c-continued-statement-offset 4)
   (setq c-brace-offset -4)
   (setq c-argdecl-indent 0)
   (setq c-label-offset -4))
 
 ;; Perl mode
 (defun my-perl-mode-hook ()
   (setq tab-width 4)
   (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent)
   (setq perl-indent-level 4)
   (setq perl-continued-statement-offset 4))
 
 ;; Scheme mode...
 (defun my-scheme-mode-hook ()
   (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent))
 
 ;; Emacs-Lisp mode...
 (defun my-lisp-mode-hook ()
   (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent)
   (define-key lisp-mode-map "\C-i" 'lisp-indent-line)
   (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp))
 
 ;; Add all of the hooks...
 (add-hook 'c++-mode-hook 'my-c++-mode-hook)
 (add-hook 'c-mode-hook 'my-c-mode-hook)
 (add-hook 'scheme-mode-hook 'my-scheme-mode-hook)
 (add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook)
 (add-hook 'lisp-mode-hook 'my-lisp-mode-hook)
 (add-hook 'perl-mode-hook 'my-perl-mode-hook)
 
 ;; Complement to next-error
 (defun previous-error (n)
   "Visit previous compilation error message and corresponding source code."
   (interactive "p")
   (next-error (- n)))
 
 ;; Misc...
 (transient-mark-mode 1)
 (setq mark-even-if-inactive t)
 (setq visible-bell nil)
 (setq next-line-add-newlines nil)
 (setq compile-command "make")
 (setq suggest-key-bindings nil)
 (put 'eval-expression 'disabled nil)
 (put 'narrow-to-region 'disabled nil)
 (put 'set-goal-column 'disabled nil)
 
 ;; Elisp archive searching
 (autoload 'format-lisp-code-directory "lispdir" nil t)
 (autoload 'lisp-dir-apropos "lispdir" nil t)
 (autoload 'lisp-dir-retrieve "lispdir" nil t)
 (autoload 'lisp-dir-verify "lispdir" nil t)
 
 ;; Font lock mode
 (defun my-make-face (face colour &amp;optional bold)
   "Create a face from a colour and optionally make it bold"
   (make-face face)
   (copy-face 'default face)
   (set-face-foreground face colour)
   (if bold (make-face-bold face))
   )
 
 (if (eq window-system 'x)
     (progn
       (my-make-face 'blue "blue")
       (my-make-face 'red "red")
       (my-make-face 'green "dark green")
       (setq font-lock-comment-face 'blue)
       (setq font-lock-string-face 'bold)
       (setq font-lock-type-face 'bold)
       (setq font-lock-keyword-face 'bold)
       (setq font-lock-function-name-face 'red)
       (setq font-lock-doc-string-face 'green)
       (add-hook 'find-file-hooks 'font-lock-auto-mode-select)
 
       (setq baud-rate 1000000)
       (global-set-key "\C-cmm" 'menu-bar-mode)
       (global-set-key "\C-cms" 'scroll-bar-mode)
       (global-set-key [backspace] 'backward-delete-char)
 					;      (global-set-key [delete] 'delete-char)
       (standard-display-european t)
       (load-library "iso-transl")))
 
 ;; X11 or PC using direct screen writes
 (if window-system
     (progn
       ;;      (global-set-key [M-f1] 'hilit-repaint-command)
       ;;      (global-set-key [M-f2] [?\C-u M-f1])
       (setq hilit-mode-enable-list  
 	    '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode
 		  scheme-mode)
 	    hilit-auto-highlight nil
 	    hilit-auto-rehighlight 'visible
 	    hilit-inhibit-hooks nil
 	    hilit-inhibit-rebinding t)
       (require 'hilit19)
       (require 'paren))
   (setq baud-rate 2400)			; For slow serial connections
   )
 
 ;; TTY type terminal
 (if (and (not window-system) 
 	 (not (equal system-type 'ms-dos)))
     (progn
       (if first-time
 	  (progn
 	    (keyboard-translate ?\C-h ?\C-?)
 	    (keyboard-translate ?\C-? ?\C-h)))))
 
 ;; Under UNIX
 (if (not (equal system-type 'ms-dos))
     (progn
       (if first-time
 	  (server-start))))
 
 ;; Add any face changes here
 (add-hook 'term-setup-hook 'my-term-setup-hook)
 (defun my-term-setup-hook ()
   (if (eq window-system 'pc)
       (progn
 ;;	(set-face-background 'default "red")
 	)))
 
 ;; Restore the "desktop" - do this as late as possible
 (if first-time
     (progn
       (desktop-load-default)
       (desktop-read)))
 
 ;; Indicate that this file has been read at least once
 (setq first-time nil)
 
 ;; No need to debug anything now
 
 (setq debug-on-error nil)
 
 ;; All done
 (message "All done, %s%s" (user-login-name) ".")
 	</programlisting>
       </example>
     </sect2>
 
     <sect2>
       <title>Extending the Range of Languages Emacs Understands</title>
 
       <para>Now, this is all very well if you only want to program in
 	the languages already catered for in the
 	<filename>.emacs</filename> file (C, C++, Perl, Lisp and
 	Scheme), but what happens if a new language called
 	<quote>whizbang</quote> comes out, full of exciting
 	features?</para>
 
       <para>The first thing to do is find out if whizbang comes with
 	any files that tell Emacs about the language.  These usually
 	end in <filename>.el</filename>, short for <quote>Emacs
 	  Lisp</quote>.  For example, if whizbang is a FreeBSD port, we
 	can locate these files by doing</para>
 
       <screen>&prompt.user; <userinput>find /usr/ports/lang/whizbang -name "*.el" -print</userinput></screen>
 
       <para>and install them by copying them into the Emacs site Lisp
 	directory.  On FreeBSD 2.1.0-RELEASE, this is
 	<filename>/usr/local/share/emacs/site-lisp</filename>.</para>
 
       <para>So for example, if the output from the find command
 	was</para>
 
       <screen>/usr/ports/lang/whizbang/work/misc/whizbang.el</screen>
 
       <para>we would do</para>
 
       <screen>&prompt.root; <userinput>cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp</userinput></screen>
 
       <para>Next, we need to decide what extension whizbang source
 	files have.  Let's say for the sake of argument that they all
 	end in <filename>.wiz</filename>.  We need to add an entry to
 	our <filename>.emacs</filename> file to make sure Emacs will
 	be able to use the information in
 	<filename>whizbang.el</filename>.</para>
 
       <para>Find the <symbol>auto-mode-alist entry</symbol> in
 	<filename>.emacs</filename> and add a line for whizbang, such
 	as:</para>
 
       <programlisting><lineannotation>&hellip;</lineannotation>
 ("\\.lsp$" . lisp-mode)
 ("\\.wiz$" . whizbang-mode)
 ("\\.scm$" . scheme-mode)
 <lineannotation>&hellip;</lineannotation></programlisting>
 
       <para>This means that Emacs will automatically go into
 	<function>whizbang-mode</function> when you edit a file ending
 	in <filename>.wiz</filename>.</para>
 
       <para>Just below this, you will find the
 	<symbol>font-lock-auto-mode-list</symbol> entry.  Add
 	<function>whizbang-mode</function> to it like so:</para>
 
       <programlisting>;; Auto font lock mode
 (defvar font-lock-auto-mode-list 
   (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode)
   "List of modes to always start in font-lock-mode")</programlisting>
 
       <para>This means that Emacs will always enable
 	<function>font-lock-mode</function> (ie syntax highlighting)
 	when editing a <filename>.wiz</filename> file.</para>
 
       <para>And that is all that is needed.  If there is anything else
 	you want done automatically when you open up a
 	<filename>.wiz</filename> file, you can add a
 	<function>whizbang-mode hook</function> (see
 	<function>my-scheme-mode-hook</function> for a simple example
 	that adds <function>auto-indent</function>).</para>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="tools-reading">
     <title>Further Reading</title>
 
     <itemizedlist>
       <listitem>
 	<para>Brian Harvey and Matthew Wright
 	  <emphasis>Simply Scheme</emphasis>
 	  MIT 1994.<!-- <br> -->
 	  ISBN 0-262-08226-8</para>
       </listitem>
 
       <listitem>
 	<para>Randall Schwartz
 	  <emphasis>Learning Perl</emphasis>
 	  O'Reilly 1993<!-- <br> -->
 	  ISBN 1-56592-042-2</para>
       </listitem>
 
       <listitem>
 	<para>Patrick Henry Winston and Berthold Klaus Paul Horn
 	  <emphasis>Lisp (3rd Edition)</emphasis>
 	  Addison-Wesley 1989<!-- <br> -->
 	  ISBN 0-201-08319-1</para>
       </listitem>
 
       <listitem>
 	<para>Brian W. Kernighan and Rob Pike
 	  <emphasis>The Unix Programming Environment</emphasis>
 	  Prentice-Hall 1984<!-- <br> -->
 	  ISBN 0-13-937681-X</para>
       </listitem>
 
       <listitem>
 	<para>Brian W. Kernighan and Dennis M. Ritchie
 	  <emphasis>The C Programming Language (2nd Edition)</emphasis>
 	  Prentice-Hall 1988<!-- <br> -->
 	  ISBN 0-13-110362-8</para>
       </listitem>
 
       <listitem>
 	<para>Bjarne Stroustrup
 	<emphasis>The C++ Programming Language</emphasis>
 	Addison-Wesley 1991<!-- <br> -->
 	ISBN 0-201-53992-6</para>
       </listitem>
 
       <listitem>
 	<para>W. Richard Stevens
 	  <emphasis>Advanced Programming in the Unix Environment</emphasis>
 	  Addison-Wesley 1992<!-- <br> -->
 	  ISBN 0-201-56317-7</para>
       </listitem>
 
       <listitem>
 	<para>W. Richard Stevens
 	  <emphasis>Unix Network Programming</emphasis>
 	  Prentice-Hall 1990<!-- <br> -->
 	  ISBN 0-13-949876-1</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
 </chapter>
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/developers-handbook/usb/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/usb/chapter.sgml
index 3a483a1cf7..847666a67b 100644
--- a/en_US.ISO8859-1/books/developers-handbook/usb/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/usb/chapter.sgml
@@ -1,623 +1,623 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="usb">
   <title>USB Devices</title>
 
   <para><emphasis>This chapter was written by &a.nhibma;.  Modifications made for
     the handbook by &a.murray;.</emphasis></para>
 
-  <sect1>
+  <sect1 id="usb-intro">
     <title>Introduction</title>
 
     <para>The Universal Serial Bus (USB) is a new way of attaching
       devices to personal computers. The bus architecture features
       two-way communication and has been developed as a response to
       devices becoming smarter and requiring more interaction with the
       host.  USB support is included in all current PC chipsets and is
       therefore available in all recently built PCs.  Apple's
       introduction of the USB-only iMac has been a major incentive for
       hardware manufacturers to produce USB versions of their devices.
       The future PC specifications specify that all legacy connectors
       on PCs should be replaced by one or more USB connectors,
       providing generic plug and play capabilities.  Support for USB
       hardware was available at a very early stage in NetBSD and was
       developed by Lennart Augustsson for the NetBSD project.  The
       code has been ported to FreeBSD and we are currently maintaining
       a shared code base.  For the implementation of the USB subsystem
       a number of features of USB are important.</para>
 
     <para><emphasis>Lennart Augustsson has done most of the implementation of
       the USB support for the NetBSD project. Many thanks for this
       incredible amount of work. Many thanks also to Ardy and Dirk for
       their comments and proofreading of this paper.</emphasis></para>
 
     <itemizedlist>
 
       <listitem><para>Devices connect to ports on the computer
         directly or on devices called hubs, forming a treelike device
         structure.</para></listitem>
 
       <listitem><para>The devices can be connected and disconnected at
         run time.</para></listitem>
 
       <listitem><para>Devices can suspend themselves and trigger
         resumes of the host system</para></listitem>
 
       <listitem><para>As the devices can be powered from the bus, the
         host software has to keep track of power budgets for each
         hub.</para></listitem>
 
       <listitem><para>Different quality of service requirements by the
         different device types together with the maximum of 126
         devices that can be connected to the same bus, require proper
         scheduling of transfers on the shared bus to take full
         advantage of the 12Mbps bandwidth available. (over 400Mbps
         with USB 2.0)</para></listitem>
 
       <listitem><para>Devices are intelligent and contain easily
         accessible information about themselves</para></listitem>
 
     </itemizedlist>
 
     <para>The development of drivers for the USB subsystem and devices
       connected to it is supported by the specifications that have
       been developed and will be developed. These specifications are
       publicly available from the USB home pages.  Apple has been very
       strong in pushing for standards based drivers, by making drivers
       for the generic classes available in their operating system
       MacOS and discouraging the use of separate drivers for each new
       device.  This chapter tries to collate essential information for a
       basic understanding of the present implementation of the USB
       stack in FreeBSD/NetBSD.  It is recommended however to read it
       together with the relevant specifications mentioned in the
       references below.</para>
     
     <sect2>
       <title>Structure of the USB Stack</title>
 
       <para>The USB support in FreeBSD can be split into three
         layers. The lowest layer contains the host controller driver,
         providing a generic interface to the hardware and its scheduling
         facilities.  It supports initialisation of the hardware,
         scheduling of transfers and handling of completed and/or failed
         transfers.  Each host controller driver implements a virtual hub
         providing hardware independent access to the registers
         controlling the root ports on the back of the machine.</para>
 
       <para>The middle layer handles the device connection and
         disconnection, basic initialisation of the device, driver
         selection, the communication channels (pipes) and does
         resource management.  This services layer also controls the
         default pipes and the device requests transferred over
         them.</para>
   
       <para>The top layer contains the individual drivers supporting
         specific (classes of) devices. These drivers implement the
         protocol that is used over the pipes other than the default
         pipe. They also implement additional functionality to make the
         device available to other parts of the kernel or userland. They
         use the USB driver interface (USBDI) exposed by the services
         layer.</para>
     </sect2>
   </sect1>
 
   <sect1 id="usb-hc">
     <title>Host Controllers</title>
 
     <para>The host controller (HC) controls the transmission of
       packets on the bus. Frames of 1 millisecond are used. At the
       start of each frame the host controller generates a Start of
       Frame (SOF) packet.</para>
 
     <para>The SOF packet is used to synchronise to the start of the
       frame and to keep track of the frame number. Within each frame
       packets are transferred, either from host to device (out) or
       from device to host (in). Transfers are always initiated by the
       host (polled transfers). Therefore there can only be one host
       per USB bus. Each transfer of a packet has a status stage in
       which the recipient of the data can return either ACK
       (acknowledge reception), NAK (retry), STALL (error condition) or
       nothing (garbled data stage, device not available or
       disconnected). Section 8.5 of the <ulink
       url="http://www.usb.org/developers/docs.html">USB
       specification</ulink> explains the details of packets in more
       detail. Four different types of transfers can occur on a USB
       bus: control, bulk, interrupt and isochronous.  The types of
       transfers and their characteristics are described below (`Pipes'
       subsection).</para>
 
     <para>Large transfers between the device on the USB bus and the
       device driver are split up into multiple packets by the host
       controller or the HC driver.</para>
 
     <para>Device requests (control transfers) to the default endpoints
       are special. They consist of two or three phases: SETUP, DATA
       (optional) and STATUS. The set-up packet is sent to the
       device. If there is a data phase, the direction of the data
       packet(s) is given in the set-up packet. The direction in the
       status phase is the opposite of the direction during the data
       phase, or IN if there was no data phase. The host controller
       hardware also provides registers with the current status of the
       root ports and the changes that have occurred since the last
       reset of the status change register. Access to these registers
       is provided through a virtualised hub as suggested in the USB
       specification [ 2]. The virtual hub must comply with the hub
       device class given in chapter 11 of that specification. It must
       provide a default pipe through which device requests can be sent
       to it. It returns the standard andhub class specific set of
       descriptors. It should also provide an interrupt pipe that
       reports changes happening at its ports. There are currently two
       specifications for host controllers available: <ulink
       url="http://developer.intel.com/design/USB/UHCI11D.htm">Universal
       Host Controller Interface</ulink> (UHCI; Intel) and <ulink
       url="http://www.compaq.com/productinfo/development/openhci.html">Open
       Host Controller Interface</ulink> (OHCI; Compaq, Microsoft,
       National Semiconductor). The UHCI specification has been
       designed to reduce hardware complexity by requiring the host
       controller driver to supply a complete schedule of the transfers
       for each frame. OHCI type controllers are much more independent
       by providing a more abstract interface doing alot of work
       themselves. </para>
 
     <sect2>
       <title>UHCI</title>
 
       <para>The UHCI host controller maintains a framelist with 1024
         pointers to per frame data structures. It understands two
         different data types: transfer descriptors (TD) and queue
         heads (QH). Each TD represents a packet to be communicated to
         or from a device endpoint. QHs are a means to groupTDs (and
         QHs) together.</para>
 
       <para>Each transfer consists of one or more packets. The UHCI
         driver splits large transfers into multiple packets. For every
         transfer, apart from isochronous transfers, a QH is
         allocated. For every type of transfer these QHs are collected
         at a QH for that type. Isochronous transfers have to be
         executed first because of the fixed latency requirement and
         are directly referred to by the pointer in the framelist. The
         last isochronous TD refers to the QH for interrupt transfers
         for that frame. All QHs for interrupt transfers point at the
         QH for control transfers, which in turn points at the QH for
         bulk transfers. The following diagram gives a graphical
         overview of this:</para>
 
       <para>This results in the following schedule being run in each
         frame. After fetching the pointer for the current frame from
         the framelist the controller first executes the TDs for all
         the isochronous packets in that frame. The last of these TDs
         refers to the QH for the interrupt transfers for
         thatframe. The host controller will then descend from that QH
         to the QHs for the individual interrupt transfers. After
         finishing that queue, the QH for the interrupt transfers will
         refer the controller to the QH for all control transfers. It
         will execute all the subqueues scheduled there, followed by
         all the transfers queued at the bulk QH. To facilitate the
         handling of finished or failed transfers different types of
         interrupts are generated by the hardware at the end of each
         frame. In the last TD for a transfer the Interrupt-On
         Completion bit is set by the HC driver to flag an interrupt
         when the transfer has completed. An error interrupt is flagged
         if a TD reaches its maximum error count. If the short packet
         detect bit is set in a TD and less than the set packet length
         is transferred this interrupt is flagged to notify
         the controller driver of the completed transfer. It is the host
         controller driver's task to find out which transfer has
         completed or produced an error. When called the interrupt
         service routine will locate all the finished transfers and
         call their callbacks.</para>
 
       <para>See for a more elaborate description the <ulink
         url="http://developer.intel.com/design/USB/UHCI11D.htm">UHCI
         specification.</ulink></para>
 
     </sect2>
 
     <sect2>
       <title>OHCI</title>
       
       <para>Programming an OHCI host controller is much simpler. The
         controller assumes that a set of endpoints is available, and
         is aware of scheduling priorities and the ordering of the
         types of transfers in a frame. The main data structure used by
         the host controller is the endpoint descriptor (ED) to which
         aqueue of transfer descriptors (TDs) is attached. The ED
         contains the maximum packet size allowed for an endpoint and
         the controller hardware does the splitting into packets. The
         pointers to the data buffers are updated after each transfer
         and when the start and end pointer are equal, the TD is
         retired to the done-queue. The four types of endpoints have
         their own queues. Control and bulk endpoints are queued each at
         their own queue. Interrupt EDs are queued in a tree, with the
         level in the tree defining the frequency at which they
         run.</para>
 
       <para>framelist interruptisochronous control bulk</para>
 
       <para>The schedule being run by the host controller in each
         frame looks as follows. The controller will first run the
         non-periodic control and bulk queues, up to a time limit set
         by the HC driver. Then the interrupt transfers for that frame
         number are run, by using the lower five bits of the frame
         number as an index into level 0 of the tree of interrupts
         EDs. At the end of this tree the isochronous EDs are connected
         and these are traversed subsequently. The isochronous TDs
         contain the frame number of the first frame the transfer
         should be run in. After all the periodic transfers have been
         run, the control and bulk queues are traversed
         again. Periodically the interrupt service routine is called to
         process the done queue and call the callbacks for each
         transfer and reschedule interrupt and isochronous
         endpoints.</para>
 
       <para>See for a more elaborate description the <ulink
         url="http://www.compaq.com/productinfo/development/openhci.html">
         OHCI specification</ulink>. Services layer The middle layer
         provides access to the device in a controlled way and
         maintains resources in use by the different drivers and the
         services layer. The layer takes care of the following
         aspects:</para>
 
       <itemizedlist>
         <listitem><para>The device configuration
           information</para></listitem>
 	<listitem><para>The pipes to communicate with a
 	  device</para></listitem>
 	<listitem><para>Probing and attaching and detaching form a
   	  device.</para></listitem>
       </itemizedlist>
 
     </sect2>
   </sect1>
 
   <sect1 id="usb-dev">
     <title>USB Device Information</title>
 
     <sect2>
       <title>Device configuration information</title>
 
       <para>Each device provides different levels of configuration
         information. Each device has one or more configurations, of
         which one is selected during probe/attach. A configuration
         provides power and bandwidth requirements. Within each
         configuration there can be multiple interfaces. A device
         interface is a collection of endpoints. For example USB
         speakers can have an interface for the audio data (Audio
         Class) and an interface for the knobs, dials and buttons (HID
         Class). All interfaces in a configuration are active at the
         same time and can be attached to by different drivers. Each
         interface can have alternates, providing different quality of
         service parameters. In for example cameras this is used to
         provide different frame sizes and numbers of frames per
         second.</para>
 
       <para>Within each interface 0 or more endpoints can be
         specified. Endpoints are the unidirectional access points for
         communicating with a device. They provide buffers to
         temporarily store incoming or outgoing data from the
         device. Each endpoint has a unique address within
         a configuration, the endpoint's number plus its direction. The
         default endpoint, endpoint 0, is not part of any interface and
         available in all configurations. It is managed by the services
         layer and not directly available to device drivers.</para>
 
       <para>Level 0 Level 1 Level 2 Slot 0</para>
       <para>Slot 3 Slot 2 Slot 1</para>
       <para>(Only 4 out of 32 slots shown)</para>
 
       <para>This hierarchical configuration information is described
         in the device by a standard set of descriptors (see section 9.6
         of the USB specification [ 2]). They can be requested through
         the Get Descriptor Request. The services layer caches these
         descriptors to avoid unnecessary transfers on the USB
         bus. Access to the descriptors is provided through function
         calls.</para>
 
       <itemizedlist>
         <listitem><para>Device descriptors: General information about
           the device, like Vendor, Product and Revision Id, supported
           device class, subclass and protocol if applicable, maximum
           packet size for the default endpoint, etc.</para></listitem>
 
 	<listitem><para>Configuration descriptors: The number of
    	  interfaces in this configuration, suspend and resume
    	  functionality supported and power
    	  requirements.</para></listitem>
 
 	<listitem><para>Interface descriptors: interface class,
   	  subclass and protocol if applicable, number of alternate
   	  settings for the interface and the number of
   	  endpoints.</para></listitem>
 
 	<listitem><para>Endpoint descriptors: Endpoint address,
 	  direction and type, maximum packet size supported and
 	  polling frequency if type is interrupt endpoint. There is no
 	  descriptor for the default endpoint (endpoint 0) and it is
 	  never counted in an interface descriptor.</para></listitem>
 
 	<listitem><para>String descriptors: In the other descriptors
   	  string indices are supplied for some fields.These can be
   	  used to retrieve descriptive strings, possibly in multiple
   	  languages.</para></listitem>
 
       </itemizedlist>
 
       <para>Class specifications can add their own descriptor types
         that are available through the GetDescriptor Request.</para>
 
       <para>Pipes Communication to end points on a device flows
         through so-called pipes. Drivers submit transfers to endpoints
         to a pipe and provide a callback to be called on completion or
         failure of the transfer (asynchronous transfers) or wait for
         completion (synchronous transfer). Transfers to an endpoint
         are serialised in the pipe. A transfer can either complete,
         fail or time-out (if a time-out has been set). There are two
         types of time-outs for transfers. Time-outs can happen due to
         time-out on the USBbus (milliseconds). These time-outs are
         seen as failures and can be due to disconnection of the
         device. A second form of time-out is implemented in software
         and is triggered when a transfer does not complete within a
         specified amount of time (seconds). These are caused by a
         device acknowledging negatively (NAK) the transferred
         packets. The cause for this is the device not being ready to
         receive data, buffer under- or overrun or protocol
         errors.</para>
 
       <para>If a transfer over a pipe is larger than the maximum
         packet size specified in the associated endpoint descriptor,
         the host controller (OHCI) or the HC driver (UHCI) will split
         the transfer into packets of maximum packet size, with the
         last packet possibly smaller than the maximum
         packet size.</para>
 
       <para>Sometimes it is not a problem for a device to return less
         data than requested. For example abulk-in-transfer to a modem
         might request 200 bytes of data, but the modem has only 5
         bytes available at that time. The driver can set the short
         packet (SPD) flag. It allows the host controller to accept a
         packet even if the amount of data transferred is less than
         requested. This flag is only valid for in-transfers, as the
         amount of data to be sent to a device is always known
         beforehand. If an unrecoverable error occurs in a device
         during a transfer the pipe is stalled. Before any more data is
         accepted or sent the driver needs to resolve the cause of the
         stall and clear the endpoint stall condition through send the
         clear endpoint halt device request over the default
         pipe. The default endpoint should never stall.</para>
 
       <para>There are four different types of endpoints and
         corresponding pipes: - Control pipe / default pipe: There is
         one control pipe per device, connected to the default endpoint
         (endpoint 0). The pipe carries the device requests and
         associated data. The difference between transfers over the
         default pipe and other pipes is that the protocol for
         the transfers is described in the USB specification [ 2]. These
         requests are used to reset and configure the device. A basic
         set of commands that must be supported by each device is
         provided in chapter 9 of the USB specification [ 2]. The
         commands supported on this pipe can be extended by a device
         class specification to support additional
         functionality.</para>
 
       <itemizedlist>
         <listitem><para>Bulk pipe: This is the USB equivalent to a raw
           transmission medium.</para></listitem>
         <listitem><para>Interrupt pipe: The host sends a request for
           data to the device and if the device has nothing to send, it
           will NAK the data packet. Interrupt transfers are scheduled
           at a frequency specified when creating the
           pipe.</para></listitem>
 
 	<listitem><para>Isochronous pipe: These pipes are intended for
 	    isochronous data, for example video or audio streams, with
 	fixed latency, but no guaranteed delivery. Some support for
 	pipes of this type is available in the current
 	implementation. Packets in control, bulk and interrupt
 	transfers are retried if an error occurs during transmission
 	or the device acknowledges the packet negatively (NAK) due to
 	for example lack of buffer space to store the incoming
 	data. Isochronous packets are however not retried in case of
 	failed delivery or NAK of a packet as this might violate the
 	timing constraints.</para></listitem>
       </itemizedlist>
 
       <para>The availability of the necessary bandwidth is calculated
         during the creation of the pipe. Transfers are scheduled within
         frames of 1 millisecond. The bandwidth allocation within a
         frame is prescribed by the USB specification, section 5.6 [
         2]. Isochronous and interrupt transfers are allowed to consume
         up to 90% of the bandwidth within a frame. Packets for control
         and bulk transfers are scheduled after all isochronous and
         interrupt packets and will consume all the remaining
         bandwidth.</para>
 
       <para>More information on scheduling of transfers and bandwidth
         reclamation can be found in chapter 5of the USB specification
         [ 2], section 1.3 of the UHCI specification [ 3] and section
         3.4.2 of the OHCI specification [4].</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="usb-devprobe">
     <title>Device probe and attach</title>
 
     <para>After the notification by the hub that a new device has been
       connected, the service layer switches on the port, providing the
       device with 100 mA of current. At this point the device is in
       its default state and listening to device address 0. The
       services layer will proceed to retrieve the various descriptors
       through the default pipe. After that it will send a Set Address
       request to move the device away from the default device address
       (address 0). Multiple device drivers might be able to support
       the device. For example a modem driver might be able to support
       an ISDN TA through the AT compatibility interface. A driver for
       that specific model of the ISDN adapter might however be able to
       provide much better support for this device. To support this
       flexibility, the probes return priorities indicating their level
       of support. Support for a specific revision of a product ranks
       the highest and the generic driver the lowest priority. It might
       also be that multiple drivers could attach to one device if
       there are multiple interfaces within one configuration. Each
       driver only needs to support a subset of the interfaces.</para>
 
     <para>The probing for a driver for a newly attached device checks
       first for device specific drivers. If not found, the probe code
       iterates over all supported configurations until a driver
       attaches in a configuration. To support devices with multiple
       drivers on different interfaces, the probe iterates over all
       interfaces in a configuration that have not yet been claimed by
       a driver. Configurations that exceed the power budget for the
       hub are ignored. During attach the driver should initialise the
       device to its proper state, but not reset it, as this will make
       the device disconnect itself from the bus and restart the
       probing process for it. To avoid consuming unnecessary bandwidth
       should not claim the interrupt pipe at attach time, but
       should postpone allocating the pipe until the file is opened and
       the data is actually used. When the file is closed the pipe
       should be closed again, even though the device might still be
       attached.</para>
 
     <sect2>
       <title>Device disconnect and detach</title>
 
       <para>A device driver should expect to receive errors during any
         transaction with the device. The design of USB supports and
         encourages the disconnection of devices at any point in
         time. Drivers should make sure that they do the right thing
         when the device disappears.</para>
 
       <para>Furthermore a device that has been disconnected and
         reconnected will not be reattached at the same device
         instance. This might change in the future when more devices
         support serial numbers (see the device descriptor) or other
         means of defining an identity for a device have been
         developed.</para>
 
       <para>The disconnection of a device is signaled by a hub in the
         interrupt packet delivered to the hub driver. The status
         change information indicates which port has seen a connection
         change. The device detach method for all device drivers for
         the device connected on that port are called and the structures
         cleaned up. If the port status indicates that in the mean time
         a device has been connected to that port, the procedure for
         probing and attaching the device will be started. A device
         reset will produce a disconnect-connect sequence on the hub
         and will be handled as described above.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="usb-protocol">
     <title>USB Drivers Protocol Information</title>
 
     <para>The protocol used over pipes other than the default pipe is
       undefined by the USB specification.  Information on this can be
       found from various sources. The most accurate source is the
       developer's section on the USB home pages [ 1]. From these pages
       a growing number of deviceclass specifications are
       available. These specifications specify what a compliant device
       should look like from a driver perspective, basic functionality
       it needs to provide and the protocol that is to be used over the
       communication channels.  The USB specification [ 2] includes the
       description of the Hub Class. A class specification for Human
       Interface Devices (HID) has been created to cater for keyboards,
       tablets, bar-code readers, buttons, knobs, switches, etc. A
       third example is the class specification for mass storage
       devices. For a full list of device classes see the developers
       section on the USB home pages [ 1].</para>
 
     <para>For many devices the protocol information has not yet been
       published however. Information on the protocol being used might
       be available from the company making the device. Some companies
       will require you to sign a Non -Disclosure Agreement (NDA)
       before giving you the specifications. This in most cases
       precludes making the driver open source.</para>
 
     <para>Another good source of information is the Linux driver
       sources, as a number of companies have started to provide drivers
       for Linux for their devices. It is always a good idea to contact
       the authors of those drivers for their source of
       information.</para>
 
     <para>Example: Human Interface Devices The specification for the
       Human Interface Devices like keyboards, mice, tablets, buttons,
       dials,etc. is referred to in other device class specifications
       and is used in many devices.</para>
 
     <para>For example audio speakers provide endpoints to the digital
       to analogue converters and possibly an extra pipe for a
       microphone. They also provide a HID endpoint in a separate
       interface for the buttons and dials on the front of the
       device. The same is true for the monitor control class. It is
       straightforward to build support for these interfaces through
       the available kernel and userland libraries together with the
       HID class driver or the generic driver. Another device that
       serves as an example for interfaces within one configuration
       driven by different device drivers is a cheap keyboard with
       built-in legacy mouse port. To avoid having the cost of
       including the hardware for a USB hub in the device,
       manufacturers combined the mouse data received from the PS/2 port
       on the back of the keyboard and the key presses from the keyboard
       into two separate interfaces in the same configuration. The
       mouse and keyboard drivers each attach to the appropriate
       interface and allocate the pipes to the two independent
       endpoints.</para>
 
     <para>Example: Firmware download Many devices that have been
       developed are based on a general purpose processor with
       an additional USB core added to it. Because the development of
       drivers and firmware for USB devices is still very new, many
       devices require the downloading of the firmware after they
       have been connected.</para>
 
     <para>The procedure followed is straightforward. The device
       identifies itself through a vendor and product Id. The first
       driver probes and attaches to it and downloads the firmware into
       it. After that the device soft resets itself and the driver is
       detached. After a short pause the device announces its presence
       on the bus. The device will have changed its
       vendor/product/revision Id to reflect the fact that it has been
       supplied with firmware and as a consequence a second driver will
       probe it and attach to it.</para>
 
     <para>An example of these types of devices is the ActiveWire I/O
       board, based on the EZ-USB chip. For this chip a generic firmware
       downloader is available. The firmware downloaded into the
       ActiveWire board changes the revision Id. It will then perform a
       soft reset of the USB part of the EZ-USB chip to disconnect from
       the USB bus and again reconnect.</para>
 
     <para>Example: Mass Storage Devices Support for mass storage
       devices is mainly built around existing protocols. The Iomega
       USB Zipdrive is based on the SCSI version of their drive. The
       SCSI commands and status messages are wrapped in blocks and
       transferred over the bulk pipes to and from the device,
       emulating a SCSI controller over the USB wire. ATAPI and UFI
       commands are supported in a similar fashion.</para>
 
     <para>The Mass Storage Specification supports 2 different types of
       wrapping of the command block.The initial attempt was based on
       sending the command and status through the default pipe and
       using bulk transfers for the data to be moved between the host
       and the device. Based on experience a second approach was
       designed that was based on wrapping the command and status
       blocks and sending them over the bulk out and in endpoint. The
       specification specifies exactly what has to happen when and what
       has to be done in case an error condition is encountered. The
       biggest challenge when writing drivers for these devices is to
       fit USB based protocol into the existing support for mass storage
       devices. CAM provides hooks to do this in a fairly straight
       forward way. ATAPI is less simple as historically the IDE
       interface has never had many different appearances.</para>
 
     <para>The support for the USB floppy from Y-E Data is again less
       straightforward as a new command set has been designed.</para>
 
   </sect1>
 
 </chapter>
diff --git a/en_US.ISO8859-1/books/developers-handbook/vm/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/vm/chapter.sgml
index da0fc92672..2b78f50828 100644
--- a/en_US.ISO8859-1/books/developers-handbook/vm/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/vm/chapter.sgml
@@ -1,260 +1,260 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="vm">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Matthew</firstname>
 	<surname>Dillon</surname>
 	<contrib>Contributed by </contrib>
       </author>
     </authorgroup>
     <!-- 6 Feb 1999 -->
   </chapterinfo>
 
   <title>Virtual Memory System</title>
 
-    <sect1>
+    <sect1 id="vm-physmem">
       <title>Management of physical
 	memory&mdash;<literal>vm_page_t</literal></title>
       
       <para>Physical memory is managed on a page-by-page basis through the
 	<literal>vm_page_t</literal> structure.  Pages of physical memory are
 	categorized through the placement of their respective
 	<literal>vm_page_t</literal> structures on one of several paging
 	queues.</para>
 
       <para>A page can be in a wired, active, inactive, cache, or free state.
 	Except for the wired state, the page is typically placed in a doubly
 	link list queue representing the state that it is in.  Wired pages
 	are not placed on any queue.</para>
 
       <para>FreeBSD implements a more involved paging queue for cached and
 	free pages in order to implement page coloring.  Each of these states
 	involves multiple queues arranged according to the size of the
 	processor's L1 and L2 caches.  When a new page needs to be allocated,
 	FreeBSD attempts to obtain one that is reasonably well aligned from
 	the point of view of the L1 and L2 caches relative to the VM object
 	the page is being allocated for.</para>
 
       <para>Additionally, a page may be held with a reference count or locked
 	with a busy count.  The VM system also implements an <quote>ultimate
 	locked</quote> state for a page using the PG_BUSY bit in the page's
 	flags.</para>
 
       <para>In general terms, each of the paging queues operates in a LRU
 	fashion.  A page is typically placed in a wired or active state
 	initially.  When wired, the page is usually associated with a page
 	table somewhere.  The VM system ages the page by scanning pages in a
 	more active paging queue (LRU) in order to move them to a less-active
 	paging queue.  Pages that get moved into the cache are still
 	associated with a VM object but are candidates for immediate reuse.
 	Pages in the free queue are truly free.  FreeBSD attempts to minimize
 	the number of pages in the free queue, but a certain minimum number of
 	truly free pages must be maintained in order to accommodate page
 	allocation at interrupt time.</para>
 
       <para>If a process attempts to access a page that does not exist in its
 	page table but does exist in one of the paging queues (such as the
 	inactive or cache queues), a relatively inexpensive page reactivation
 	fault occurs which causes the page to be reactivated. If the page
 	does not exist in system memory at all, the process must block while
 	the page is brought in from disk.</para>
 
       <para>FreeBSD dynamically tunes its paging queues and attempts to
 	maintain reasonable ratios of pages in the various queues as well as
 	attempts to maintain a reasonable breakdown of clean vs. dirty pages.
 	The amount of rebalancing that occurs depends on the system's memory
 	load.  This rebalancing is implemented by the pageout daemon and
 	involves laundering dirty pages (syncing them with their backing
 	store), noticing when pages are activity referenced (resetting their
 	position in the LRU queues or moving them between queues), migrating
 	pages between queues when the queues are out of balance, and so forth.
 	FreeBSD's VM system is willing to take a reasonable number of
 	reactivation page faults to determine how active or how idle a page
 	actually is.  This leads to better decisions being made as to when to
 	launder or swap-out a page.</para>
     </sect1>
     
-    <sect1>
+    <sect1 id="vm-cache">
       <title>The unified buffer
 	cache&mdash;<literal>vm_object_t</literal></title>
 	  
       <para>FreeBSD implements the idea of a generic <quote>VM object</quote>.
 	VM objects can be associated with backing store of various
 	types&mdash;unbacked, swap-backed, physical device-backed, or
 	file-backed storage.  Since the filesystem uses the same VM objects to
 	manage in-core data relating to files, the result is a unified buffer
 	cache.</para>
 
       <para>VM objects can be <emphasis>shadowed</emphasis>.  That is, they
 	can be stacked on top of each other.  For example, you might have a
 	swap-backed VM object stacked on top of a file-backed VM object in
 	order to implement a MAP_PRIVATE mmap()ing.  This stacking is also
 	used to implement various sharing properties, including
 	copy-on-write, for forked address spaces.</para>
 
       <para>It should be noted that a <literal>vm_page_t</literal> can only be
 	associated with one VM object at a time.  The VM object shadowing
 	implements the  perceived sharing of the same page across multiple
 	instances.</para>
     </sect1>
     
-    <sect1>
+    <sect1 id="vm-fileio">
       <title>Filesystem I/O&mdash;<literal>struct buf</literal></title>
       
       <para>vnode-backed VM objects, such as file-backed objects, generally
 	need to maintain their own clean/dirty info independent from the VM
 	system's idea of clean/dirty.  For example, when the VM system decides
 	to  synchronize a physical page to its backing store, the VM system
 	needs to mark the page clean before the page is actually written to
 	its backing store.  Additionally, filesystems need to be able to map
 	portions of a file or file metadata into KVM in order to operate on
 	it.</para>
 
       <para>The entities used to manage this are known as filesystem buffers,
 	<literal>struct buf</literal>'s, or
 	<literal>bp</literal>'s.  When a filesystem needs to operate on a
 	portion of a VM object, it typically maps part of the object into a
 	struct buf and the maps the pages in the struct buf into KVM.  In the
 	same manner, disk I/O is typically issued by mapping portions of
 	objects into buffer structures and  then issuing the I/O on the buffer
 	structures.  The underlying  vm_page_t's are typically busied for the
 	duration of the I/O.  Filesystem buffers also have their own notion of
 	being busy, which is useful to filesystem driver code which would
 	rather operate on filesystem buffers instead of hard VM pages.</para>
 
       <para>FreeBSD reserves a limited amount of KVM to hold mappings from
 	struct bufs, but it should be made clear that this KVM is used solely
 	to hold mappings and does not limit the ability to cache data.
 	Physical data caching is strictly a function of
 	<literal>vm_page_t</literal>'s, not filesystem buffers.  However,
 	since filesystem buffers are used to placehold I/O, they do inherently
 	limit the amount of concurrent I/O possible.  However, as there are usually a
 	few thousand filesystem buffers available, this is not usually a
 	problem.</para>
     </sect1>
     
-    <sect1>
+    <sect1 id="vm-pagetables">
       <title>Mapping Page Tables&mdash;<literal>vm_map_t, vm_entry_t</literal></title>
       
       <para>FreeBSD separates the physical page table topology from the VM
 	system.  All hard per-process page tables can be reconstructed on  the
 	fly and are usually considered throwaway.  Special page tables such as
 	those managing KVM are typically permanently preallocated. These page
 	tables are not throwaway.</para>
 
       <para>FreeBSD associates portions of vm_objects with address ranges in
 	virtual memory through <literal>vm_map_t</literal> and
 	<literal>vm_entry_t</literal> structures.  Page tables are directly
 	synthesized from the
 	<literal>vm_map_t</literal>/<literal>vm_entry_t</literal>/
 	<literal>vm_object_t</literal> hierarchy.  Recall that I mentioned
 	that physical pages  are only directly associated with a
 	<literal>vm_object</literal>; that is not quite true.
 	<literal>vm_page_t</literal>'s are also linked into page tables that
 	they are actively associated with.  One <literal>vm_page_t</literal>
 	can be linked into  several <emphasis>pmaps</emphasis>, as page tables
 	are called.  However, the hierarchical association holds, so all
 	references to the same page in the same object reference the same
 	<literal>vm_page_t</literal> and thus give us buffer cache unification
 	across the board.</para>
     </sect1>
       
-    <sect1>
+    <sect1 id="vm-kvm">
       <title>KVM Memory Mapping</title>
       
       <para>FreeBSD uses KVM to hold various kernel structures.  The single
 	largest entity held in KVM is the filesystem buffer cache.  That is,
 	mappings relating to <literal>struct buf</literal> entities.</para>
 
       <para>Unlike Linux, FreeBSD does <emphasis>not</emphasis> map all of physical memory into
 	KVM.  This means that FreeBSD can handle memory configurations up to
 	4G on 32 bit platforms.  In fact, if the mmu were capable of it,
 	FreeBSD could theoretically handle memory configurations up to 8TB on
 	a 32 bit platform.  However, since most 32 bit platforms are only
 	capable of mapping 4GB of ram, this is a moot point.</para>
 
         <para>KVM is managed through several mechanisms.  The main mechanism
 	  used to manage KVM is the <emphasis>zone allocator</emphasis>.  The
 	  zone allocator takes a chunk of KVM and splits it up into
 	  constant-sized blocks of memory in order to allocate a specific type
 	  of structure.  You can use <command>vmstat -m</command> to get an
 	  overview of current KVM  utilization broken down by zone.</para>
     </sect1>
     
-    <sect1>
+    <sect1 id="vm-tuning">
       <title>Tuning the FreeBSD VM system</title>
       
       <para>A concerted effort has been made to make the FreeBSD kernel
 	dynamically tune itself.  Typically you do not need to mess with
 	anything beyond the <option>maxusers</option> and
 	<option>NMBCLUSTERS</option> kernel config options.  That is, kernel
 	compilation options specified in (typically)
 	<filename>/usr/src/sys/i386/conf/<replaceable>CONFIG_FILE</replaceable></filename>.
 	A description of all available kernel configuration options can be
 	found in <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
 
       <para>In a large system configuration you may wish to increase
 	<option>maxusers</option>.  Values typically range from 10 to 128.
 	Note that raising <option>maxusers</option> too high can cause the
 	system to overflow available KVM resulting in unpredictable operation.
 	It is better to leave <option>maxusers</option> at some reasonable number and add other
 	options, such as <option>NMBCLUSTERS</option>, to increase specific
 	resources.</para>
 
       <para>If your system is going to use the network heavily, you may want
 	to increase <option>NMBCLUSTERS</option>.  Typical values range from
 	1024 to 4096.</para>
 
       <para>The <literal>NBUF</literal> parameter is also traditionally used
 	to scale the system.  This parameter determines the amount of KVA the
 	system can use to map filesystem buffers for I/O.  Note that this
 	parameter has nothing whatsoever to do with the unified buffer cache!
 	This parameter is dynamically tuned in 3.0-CURRENT and later kernels
 	and should generally not be adjusted manually.  We recommend that you
 	<emphasis>not</emphasis> try to specify an <literal>NBUF</literal>
 	parameter.  Let the system pick it.  Too small a value can result in
 	extremely inefficient filesystem operation while too large a value can
 	starve the page queues by causing too many pages to become wired
 	down.</para>
 
       <para>By default, FreeBSD kernels are not optimized.  You can set
 	debugging and optimization flags with the
 	<literal>makeoptions</literal> directive in the kernel configuration.
 	Note that you should not use <option>-g</option> unless you can
 	accommodate the large (typically 7 MB+) kernels that result.</para>
 
       <programlisting>makeoptions      DEBUG="-g"
 makeoptions      COPTFLAGS="-O -pipe"</programlisting>
 
       <para>Sysctl provides a way to tune kernel parameters at run-time. You
 	typically do not need to mess with any of the sysctl variables,
 	especially the VM related ones.</para>
 
       <para>Run time VM and system tuning is relatively straightforward.
 	First, use Soft Updates on your UFS/FFS filesystems whenever possible.
 	<filename>/usr/src/sys/ufs/ffs/README.softupdates</filename> contains
 	instructions (and restrictions) on how to configure it.</para>
 
       <para>Second, configure  sufficient swap.  You should have a swap
 	partition configured on each physical disk, up to four, even on your
 	<quote>work</quote> disks.  You should have at least 2x the swap space
 	as you have main memory, and possibly even more if you do not have a
 	lot of memory.  You should also size your swap partition based on the
 	maximum memory configuration you ever intend to put on the machine so
 	you do not have to repartition your disks later on. If you want to be
 	able to accommodate a crash dump, your first swap partition must be at
 	least as large as main memory and <filename>/var/crash</filename> must
 	have sufficient free space to hold the dump.</para>
 
       <para>NFS-based swap is perfectly acceptable on 4.X or later systems,
 	but you must be aware that the NFS server will take the brunt of the
 	paging load.</para>
     </sect1>
 
 </chapter>
diff --git a/en_US.ISO8859-1/books/fdp-primer/book.sgml b/en_US.ISO8859-1/books/fdp-primer/book.sgml
index 0916b71b84..5bf5c89a1c 100644
--- a/en_US.ISO8859-1/books/fdp-primer/book.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/book.sgml
@@ -1,305 +1,305 @@
 <!-- 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$
 -->
 
 <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
 <!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
 %mailing-lists;
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
 
 <!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
 <!ENTITY % not.published "INCLUDE">
 <!-- ENTITY index SYSTEM "index.sgml" -->
 ]>
 
 <book>
   <bookinfo>
     <title>FreeBSD Documentation Project Primer for New Contributors</title>
     
     <author>
       <firstname>Nik</firstname>
       <surname>Clayton</surname>
       <affiliation>
         <address><email>nik@FreeBSD.org</email></address>
       </affiliation>
     </author>
 
     <copyright>
       <year>1998</year>
       <year>1999</year>
       <year>2000</year>
       <year>2001</year>
       <year>2002</year>
       <holder role="mailto:nik@FreeBSD.org">Nik Clayton</holder>
     </copyright>
 
     <pubdate role="rcs">$FreeBSD$</pubdate>
 
     <releaseinfo>$FreeBSD$</releaseinfo>
 
     <legalnotice>
       <para>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:</para>
 
       <orderedlist>
 	<listitem>
 	  <para>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.</para>
 	</listitem>
 
 	<listitem>
 	  <para>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.</para>
 	</listitem>
       </orderedlist>
 
       <important>
 	<para>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.</para>
       </important>
     </legalnotice>
     
     <abstract>
       <para>Thank you for becoming a part of the FreeBSD Documentation
         Project. Your contribution is extremely valuable.</para>
 
       <para>This primer covers everything you will need to know in order
         to start contributing to the FreeBSD Documentation Project, from
         the tools and software you will be using (both mandatory and
         recommended) to the philosophy behind the Documentation 
         Project.</para>
 
       <para>This document is a work in progress, and is not complete. Sections
 	that are known to be incomplete are indicated with a
 	<literal>*</literal> in their name.</para>
     </abstract>
   </bookinfo>
 
-  <preface>
+  <preface id="preface">
     <title>Preface</title>
 
-    <sect1>
+    <sect1 id="preface-prompts">
       <title>Shell Prompts</title>
       
       <para>The following table shows the default system prompt and superuser
 	prompt. The examples will use this prompt to indicate which user you
 	should be running the example as.</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>User</entry>
 	      <entry>Prompt</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	      <entry>Normal user</entry>
 	      <entry>&prompt.user;</entry>
 	    </row>
 
 	    <row>
 	      <entry><username>root</username></entry>
 	      <entry>&prompt.root;</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect1>
     
-    <sect1>
+    <sect1 id="preface-conventions">
       <title>Typographic Conventions</title>
 
       <para>The following table describes the typographic conventions used in
 	this book.</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Meaning</entry>
 	      <entry>Examples</entry>
 	    </row>
 	  </thead>
 	  
 	  <tbody>
 	    <row>
 	      <entry>The name of commands, files, and directories. On screen
 		computer output.</entry>
 	      <entry><para>Edit your <filename>.login</filename>
 		  file.</para><para>Use <command>ls -a</command> to list all
 		  files.</para><para><screen>You have mail.</screen>
 		</para></entry>
 	    </row>
 
 	    <row>
 	      <entry>What you type, when contrasted with on-screen computer
 		output.</entry>
 
 	      <entry><screen>&prompt.user; <userinput>su</userinput>
 Password:</screen></entry>
 	    </row>
 
 	    <row>
 	      <entry>Manual page references.</entry>
 
 	      <entry>Use <citerefentry>
 		  <refentrytitle>su</refentrytitle>
 		  <manvolnum>1</manvolnum>
 		</citerefentry> to change user names.</entry>
 	    </row>
 
 	    <row>
 	      <entry>User and group names</entry>
 
 	      <entry>Only <username>root</username> can do this.</entry>
 	    </row>
 
 	    <row>
 	      <entry>Emphasis</entry>
 
 	      <entry>You <emphasis>must</emphasis> do this.</entry>
 	    </row>
 
 	    <row>
 	      <entry>Command line variables; replace with the real name or
 		variable.</entry>
 
 	      <entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry>
 	    </row>
 
 	    <row>
 	      <entry>Environment variables</entry>
 
 	      <entry><envar>$HOME</envar> is your home directory.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect1>
 
-    <sect1>
+    <sect1 id="preface-notes">
       <title>Notes, tips, important information, warnings, and examples</title>
 
       <para>Within the text appear notes, warnings, and examples.</para>
 
       <note>
 	<para>Notes are represented like this, and contain information that
 	  you should take note of, as it may affect what you do.</para>
       </note>
 
       <tip>
 	<para>Tips are represented like this, and contain information that you 
 	  might find useful, or lead to an easier way to do something.</para>
       </tip>
 
       <important>
 	<para>Important information is represented like this.  Typically they
 	  flag extra steps you may need to carry out.</para>
       </important>
 
       <warning>
 	<para>Warnings are represented like this, and contain information
 	  warning you about possible damage if you do not follow the
 	  instructions. This damage may be physical, to your hardware or to
 	  you, or it may be non-physical, such as the inadvertent deletion of
 	  important files.</para>
       </warning>
 
       <example>
 	<title>A sample example</title>
 
 	<para>Examples are represented like this, and typically contain
 	  examples you should walk through, or show you what the results of a
 	  particular action should be.</para>
       </example>
     </sect1>
 
-    <sect1>
+    <sect1 id="preface-acknowledgements">
       <title>Acknowledgments</title>
 
       <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter
 	Flynn, and Christopher Maden, who took the time to read early drafts
 	of this document and offer many valuable comments and
 	criticisms.</para>
     </sect1>
   </preface>
   
   &chap.overview;
   &chap.tools;
   &chap.sgml-primer;
   &chap.sgml-markup;
   &chap.stylesheets;
   &chap.structure;
   &chap.doc-build;
   &chap.the-website;
   &chap.translations;
   &chap.writing-style;
   &chap.psgml-mode;
   &chap.see-also;
 
   &app.examples;
 
 <!--
   &index;  
 -->
 </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/fdp-primer/doc-build/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
index 125df5c5ee..bb2001bc61 100644
--- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
@@ -1,498 +1,498 @@
 <!-- Copyright (c) 1999 Neil Blakey-Milner, 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 THE AUTHOR "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="doc-build">
   <title>The Documentation Build Process</title>
 
   <para>This chapter's main purpose is to clearly explain <emphasis>how
     the documentation build process is organised</emphasis>, and
     <emphasis>how to affect modifications to this process</emphasis>.
     </para>
 
   <para>After you have finished reading this chapter you should:</para>
 
   <itemizedlist>
     <listitem>
       <para>Know what you need to build the FDP documentation, in
 	addition to those mentioned in the <link
 	linkend="tools">SGML tools chapter</link>.</para>
     </listitem>
 
     <listitem>
       <para>Be able to read and understand the
 	<application>make</application> instructions that are present in
 	each document's <filename>Makefile</filename>s, as well as an
 	overview of the <filename>doc.project.mk</filename> includes.</para>
     </listitem>
  
     <listitem>
       <para>Be able to customize the build process by using
 	<application>make</application> variables and
 	<application>make</application> targets.</para>
     </listitem>
   </itemizedlist>
 
-  <sect1>
+  <sect1 id="doc-build-toolset">
     <title>The FreeBSD Documentation Build Toolset</title>
 
     <para>Here are your tools.  Use them every way you can.</para>
 
     <itemizedlist>
       <listitem>
 	<para>The primary build tool you will need is
 	  <application>make</application>, but specifically
 	  <application>Berkeley Make</application>.</para>
       </listitem>
 
       <listitem>
 	<para>Package building is handled by FreeBSD's
 	  <application>pkg_create</application>.  If you are not using
 	  FreeBSD, you will either have to live without packages, or
 	  compile the source yourself.</para>
       </listitem>
 
       <listitem>
 	<para><application>gzip</application> is needed to create
 	  compressed versions of the document.
 	  <application>bzip2</application> compression and
 	  <application>zip</application> archives are also supported.
 	  <application>tar</application> is supported, but package
 	  building demands it.</para>
       </listitem>
 
       <listitem>
 	<para><application>install</application> is the default method
 	  to install the documentation.  There are alternatives,
 	  however.</para>
       </listitem>
     </itemizedlist>
 
     <note>
       <para>It is unlikely you will not be able to find these last two, they
 	are mentioned for completeness.</para>
     </note>
   </sect1>
 
-  <sect1>
+  <sect1 id="doc-build-makefiles">
     <title>Understanding Makefiles in the Documentation tree</title>
 
     <para>There are three main types of <filename>Makefile</filename>s 
       in the FreeBSD Documentation Project tree.</para>
 
     <itemizedlist>
       <listitem>
 	<para><link linkend="sub-make">Subdirectory
 	  <filename>Makefile</filename>s</link> simply pass
 	  commands to those directories below them.</para>
       </listitem>
 
       <listitem>
 	<para><link linkend="doc-make">Documentation
 	  <filename>Makefile</filename>s</link> describe the
 	  document(s) that should be produced from this directory.</para>
       </listitem>
 
       <listitem>
 	<para><link linkend="make-includes"><application>Make</application>
 	  includes</link> are the glue that perform the document production,
 	  and are usually of the form
 	  <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
       </listitem>
     </itemizedlist>
 
     <sect2 id="sub-make">
       <title>Subdirectory Makefiles</title>
 
       <para>These <filename>Makefile</filename>s usually take the form of:</para>
 
       <programlisting>SUBDIR =articles
 SUBDIR+=books
 
 COMPAT_SYMLINK = en
 
 DOC_PREFIX?= ${.CURDIR}/..
 .include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
 
       <para>In quick summary, the first four non-empty lines define the
 	<application>make</application> variables,
 	<makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>,
 	and <makevar>DOC_PREFIX</makevar>.</para>
 
       <para>The first <makevar>SUBDIR</makevar> statement, as well as
 	the <makevar>COMPAT_SYMLINK</makevar> statement, shows how to
 	assign a value to a variable, overriding any previous
 	value.</para>
 
       <para>The second <makevar>SUBDIR</makevar> statement shows how a
 	value is appended to the current value of a variable.  The
 	<makevar>SUBDIR</makevar> variable is now <literal>articles
 	books</literal>.</para>
 
       <para>The <makevar>DOC_PREFIX</makevar> assignment shows how a
 	value is assigned to the variable, but only if it is not already
 	defined.  This is useful if <makevar>DOC_PREFIX</makevar> is not
 	where this <filename>Makefile</filename> thinks it is - the user
 	can override this and provide the correct value.</para>
 
       <para>Now what does it all mean?  <makevar>SUBDIR</makevar>
 	mentions which subdirectories below this one the build process
 	should pass any work on to.</para>
 
       <para><makevar>COMPAT_SYMLINK</makevar> is specific to
 	compatibility symlinks (amazingly enough) for languages to their
 	official encoding (<filename>doc/en</filename> would point to
 	<filename>en_US.ISO-8859-1</filename>).</para>
 
       <para><makevar>DOC_PREFIX</makevar> is the path to the root of the
 	FreeBSD Document Project tree.  This is not always that easy to
 	find, and is also easily overridden, to allow for flexibility.
 	<makevar>.CURDIR</makevar> is a <application>make</application>
 	builtin variable with the path to the current directory.</para>
 
       <para>The final line includes the FreeBSD Documentation Project's
 	project-wide <application>make</application> system file
 	<filename>doc.project.mk</filename> which is the glue which
 	converts these variables into build instructions.</para>
 
     </sect2>
     <sect2 id="doc-make">
       <title>Documentation Makefiles</title>
 
       <para>These <filename>Makefile</filename>s set a bunch of
 	<application>make</application> variables that describe how to
 	build the documentation contained in that directory.</para>
 
       <para>Here is an example:</para>
 
       <programlisting>MAINTAINER=nik@FreeBSD.org
 
 DOC?= book
 
 FORMATS?= html-split html
 
 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=
 
 # SGML content
 SRCS=  book.sgml
 
 DOC_PREFIX?= ${.CURDIR}/../../..
 
 .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
 
       <para>The <makevar>MAINTAINER</makevar> variable is a very 
 	important one.  This variable provides the ability to claim
 	ownership over a document in the FreeBSD Documentation
 	Project, whereby you gain the responsibility for maintaining 
 	it.</para>
 
       <para><makevar>DOC</makevar> is the name (sans the
 	<filename>.sgml</filename> extension) of the main document
 	created by this directory.  <makevar>SRCS</makevar> lists all
 	the individual files that make up the document.  This should
 	also include important files in which a change should result
 	in a rebuild.</para>
 
       <para><makevar>FORMATS</makevar> indicates the default formats
 	that should be built for this document.
 	<makevar>INSTALL_COMPRESSED</makevar> is the default list of
 	compression techniques that should be used in the document
 	build.  <makevar>INSTALL_ONLY_COMPRESS</makevar>, empty by
 	default, should be non-empty if only compressed documents are
 	desired in the build.</para>
 
       <note>
 	<para>We covered optional variable assignments in the 
 	  <link linkend="sub-make">previous section</link>.</para>
       </note>
 
       <para>The <makevar>DOC_PREFIX</makevar> and include statements
 	should be familiar already.</para>
     </sect2>
   </sect1>
 
   <sect1 id="make-includes">
     <title>FreeBSD Documentation Project make includes</title>
 
     <para>This is best explained by inspection of the code.  Here are
       the system include files:</para>
 
     <itemizedlist>
       <listitem>
 	<para><filename>doc.project.mk</filename> is the main project
 	  include file, which includes all the following include files, as
 	  necessary.</para>
       </listitem>
 
       <listitem>
 	<para><filename>doc.subdir.mk</filename> handles traversing of
 	  the document tree during the build and install processes.</para>
       </listitem>
 
       <listitem>
 	<para><filename>doc.install.mk</filename> provides variables
 	  that affect ownership and installation of documents.</para>
       </listitem>
 
       <listitem>
 	<para><filename>doc.docbook.mk</filename> is included if
 	  <makevar>DOCFORMAT</makevar> is <literal>docbook</literal>
 	  and <makevar>DOC</makevar> is set.</para>
       </listitem>
     </itemizedlist>
 
     <sect2>
       <title>doc.project.mk</title>
 
       <para>By inspection:</para>
 
       <programlisting>DOCFORMAT?=	docbook
 MAINTAINER?=	doc@FreeBSD.org
 
 PREFIX?=	/usr/local
 PRI_LANG?=	en_US.ISO8859-1
 
 .if defined(DOC)
 .if ${DOCFORMAT} == "docbook"
 .include "doc.docbook.mk"
 .endif
 .endif
 
 .include "doc.subdir.mk"
 .include "doc.install.mk"</programlisting>
 
       <sect3>
 
 	<title>Variables</title>
 
 	<para><makevar>DOCFORMAT</makevar> and <makevar>MAINTAINER</makevar>
 	  are assigned default values, if these are not set by the
 	  document make file.</para>
 
 	<para><makevar>PREFIX</makevar> is the prefix under which the
 	  <link linkend="tools">documentation building tools</link> are
 	  installed.  For normal package and port installation, this is
 	  <filename>/usr/local</filename>.</para>
 
 	<para><makevar>PRI_LANG</makevar> should be set to whatever
 	  language and encoding is natural amongst users these documents are
 	  being built for.  US English is the default.</para>
 
 	<note>
 	  <para><makevar>PRI_LANG</makevar> in no way affects what documents
 	    can, or even will, be built.  Its main use is creating links to
 	    commonly referenced documents into the FreeBSD documentation
 	    install root.</para>
 	</note>
       </sect3>
 
       <sect3>
 	<title>Conditionals</title>
        
 	<para>The <literal>.if defined(DOC)</literal> line is an example of
 	  a <application>make</application> conditional which, like in
 	  other programs, defines behavior if some condition is true or
 	  if it is false.  <literal>defined</literal> is a function which
 	  returns whether the variable given is defined or not.</para>
 
 	<para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
 	  tests whether the <makevar>DOCFORMAT</makevar> variable is
 	  <literal>"docbook"</literal>, and in this case, includes
 	  <filename>doc.docbook.mk</filename>.</para>
 
 	<para>The two <literal>.endif</literal>s close the two above
 	  conditionals, marking the end of their application.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>doc.subdir.mk</title>
 
       <para>This is too long to explain by inspection, you should be
 	able to work it out with the knowledge gained from the previous
 	chapters, and a little help given here.</para>
 
       <sect3>
 	<title>Variables</title>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><makevar>SUBDIR</makevar> is a list of subdirectories 
 	      that the build process should go further down
 	      into.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><makevar>ROOT_SYMLINKS</makevar> is the name of
 	      directories that should be linked to the document
 	      install root from their actual locations, if the current
 	      language is the primary language (specified by
 	      <makevar>PRI_LANG</makevar>).</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><makevar>COMPAT_SYMLINK</makevar> is described in the
 	      <link linkend="sub-make">Subdirectory Makefile</link>
 	      section.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Targets and macros</title>
 
 	<para>Dependencies are described by 
 	  <literal><replaceable>target</replaceable>:
 	  <replaceable>dependency1 dependency2 ...</replaceable></literal>
 	  tuples, where to build <literal>target</literal>, you need to build
 	  the given dependencies first.</para>
 
 	<para>After that descriptive tuple, instructions on how to build
 	  the target may be given, if the conversion process between the
 	  target and its dependencies are not previously defined, or if
 	  this particular conversion is not the same as the default
 	  conversion method.</para>
 
 	<para>A special dependency <literal>.USE</literal> defines
 	  the equivalent of a macro.</para>
 
 <programlisting>_SUBDIRUSE: .USE
 .for entry in ${SUBDIR}
 	@${ECHO} "===> ${DIRPRFX}${entry}"
 	@(cd ${.CURDIR}/${entry} && \
 	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor</programlisting>
 
 	<para>In the above, <maketarget>_SUBDIRUSE</maketarget> is now a
 	  macro which will execute the given commands when it is listed
 	  as a dependency.</para>
 
 	<para>What sets this macro apart from other targets?  Basically,
 	  it is executed <emphasis>after</emphasis> the instructions
 	  given in the build procedure it is listed as a dependency to,
 	  and it does not adjust <makevar>.TARGET</makevar>, which is the
 	  variable which contains the name of the target currently
 	  being built.</para>
 
 <programlisting>clean: _SUBDIRUSE
 	rm -f ${CLEANFILES}</programlisting>
 
 	<para>In the above, <maketarget>clean</maketarget> will use the
 	  <maketarget>_SUBDIRUSE</maketarget> macro after it has
 	  executed the instruction 
 	  <command>rm -f ${CLEANFILES}</command>.  In effect, this causes
 	  <maketarget>clean</maketarget> to go further and further down
 	  the directory tree, deleting built files as it goes
 	  <emphasis>down</emphasis>, not on the way back up.</para>
 
 	<sect4>
 	  <title>Provided targets</title>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><maketarget>install</maketarget> and
 		<maketarget>package</maketarget> both go down the
 		directory tree calling the real versions of themselves
 		in the subdirectories.
 		(<maketarget>realinstall</maketarget> and
 		<maketarget>realpackage</maketarget>
 		 respectively)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para><maketarget>clean</maketarget> removes files created
 		by the build process (and goes down the directory tree
 		too).  <maketarget>cleandir</maketarget> does the same,
 		and also removes the object directory, if any.</para>
 	    </listitem>
 	  </itemizedlist>
 	</sect4>
       </sect3>
 
       <sect3>
 	<title>More on conditionals</title>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><literal>exists</literal> is another condition
 	      function which returns true if the given file exists.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><literal>empty</literal> returns true if the given
 	      variable is empty.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><literal>target</literal> returns true if the given
 	      target does not already exist.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3>
 	<title>Looping constructs in make (.for)</title>
 
 	<para><literal>.for</literal> provides a way to repeat a set of
 	  instructions for each space-separated element in a variable.
 	  It does this by assigning a variable to contain the current
 	  element in the list being examined.</para>
 
 <programlisting>_SUBDIRUSE: .USE
 .for entry in ${SUBDIR}
 	@${ECHO} "===> ${DIRPRFX}${entry}"
 	@(cd ${.CURDIR}/${entry} && \
 	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor</programlisting>
 
 	<para>In the above, if <makevar>SUBDIR</makevar> is empty, no
 	  action is taken; if it has one or more elements, the
 	  instructions between <literal>.for</literal> and
 	  <literal>.endfor</literal> would repeat for every element,
 	  with <makevar>entry</makevar> being replaced with the value of
 	  the current element.</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/fdp-primer/examples/appendix.sgml b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml
index 306e04ef9e..7edda5053b 100644
--- a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml
@@ -1,355 +1,355 @@
 <!-- Copyright (c) 2000 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$
 -->
 
 <appendix id="examples">
   <title>Examples</title>
 
   <para>This appendix contains example SGML files and command lines you can
     use to convert them from one output format to another.  If you have
     successfully installed the Documentation Project tools then you should
     be able to use these examples directly.</para>
 
   <para>These examples are not exhaustive&mdash;they do not contain all the
     elements you might want to use, particularly in your document's front
     matter.  For more examples of DocBook markup you should examine the SGML
     source for this and other documents, available in the
     <application>CVSup</application> <literal>doc</literal> collection, or
     available online starting at <ulink
       url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/">http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/</ulink>.</para>
 
   <para>To avoid confusion, these examples use the standard DocBook 3.1 DTD
     rather than the FreeBSD extension.  They also use the stock stylesheets
     distributed by Norm Walsh, rather than any customisations made to those
     stylesheets by the FreeBSD Documentation Project.  This makes them more
     useful as generic DocBook examples.</para>
 
-  <sect1>
+  <sect1 id="examples-docbook-book">
     <title>DocBook <sgmltag>book</sgmltag></title>
 
     <example>
       <title>DocBook <sgmltag>book</sgmltag></title>
 
       <programlisting><![ CDATA [<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
 
 <book>
   <bookinfo>
     <title>An Example Book</title>
     
     <author>
       <firstname>Your first name</firstname>
       <surname>Your surname</surname>
       <affiliation>
         <address><email>foo@example.com</email></address>
       </affiliation>
     </author>
 
     <copyright>
       <year>2000</year>
       <holder>Copyright string here</holder>
     </copyright>
 
     <abstract>
       <para>If your book has an abstract then it should go here.</para>
     </abstract>
   </bookinfo>
 
   <preface>
     <title>Preface</title>
 
     <para>Your book may have a preface, in which case it should be placed
       here.</para>
   </preface>
       
   <chapter>
     <title>My first chapter</title>
 
     <para>This is the first chapter in my book.</para>
 
     <sect1>
       <title>My first section</title>
 
       <para>This is the first section in my book.</para>
     </sect1>
   </chapter>
 </book>]]></programlisting>
     </example>
   </sect1>
 
-  <sect1>
+  <sect1 id="examples-docbook-article">
     <title>DocBook <sgmltag>article</sgmltag></title>
 
     <example>
       <title>DocBook <sgmltag>article</sgmltag></title>
 
       <programlisting><![ CDATA [<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
 
 <article>
   <articleinfo>
     <title>An example article</title>
 
     <author>
       <firstname>Your first name</firstname>
       <surname>Your surname</surname>
       <affiliation>
         <address><email>foo@example.com</email></address>
       </affiliation>
     </author>
 
     <copyright>
       <year>2000</year>
       <holder>Copyright string here</holder>
     </copyright>
 
     <abstract>
       <para>If your article has an abstract then it should go here.</para>
     </abstract>
   </articleinfo>
 
   <sect1>
     <title>My first section</title>
 
     <para>This is the first section in my article.</para>
 
     <sect2>
       <title>My first sub-section</title>
 
       <para>This is the first sub-section in my article.</para>
     </sect2>	
   </sect1>
 </article>]]></programlisting>
     </example>
   </sect1>
 
-  <sect1>
+  <sect1 id="examples-formatted">
     <title>Producing formatted output</title>
 
     <para>This section assumes that you have installed the software listed in
       the <filename role="package">textproc/docproj</filename> port, either by hand, or by
       using the port.  Further, it is assumed that your software is installed
       in subdirectories under <filename>/usr/local/</filename>, and the
       directory where binaries have been installed is in your
       <envar>PATH</envar>.  Adjust the paths as necessary for your
       system.</para>
 
     <sect2>
       <title>Using Jade</title>
 
       <example>
 	<title>Converting DocBook to HTML (one large file)</title>
 	
 	<screen>&prompt.user; <userinput>jade -V nochunks \  <co id="examples-co-jade-1-nochunks">
     -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-1-catalog">
     -c /usr/local/share/sgml/docbook/catalog \
     -c /usr/local/share/sgml/jade/catalog \
     -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \<co id="examples-co-jade-1-dsssl">
     -t sgml <co id="examples-co-jade-1-transform"> file.sgml > file.html <co id="examples-co-jade-1-filename"></userinput></screen>
 
 	<calloutlist>
 	  <callout arearefs="examples-co-jade-1-nochunks">
 	    <para>Specifies the <literal>nochunks</literal> parameter to the
 	      stylesheets, forcing all output to be written to
 	      <abbrev>STDOUT</abbrev> (using Norm Walsh's stylesheets).</para>
 	  </callout>
 
 	  <callout arearefs="examples-co-jade-1-catalog">
 	    <para>Specifies the catalogs that Jade will need to process.
 	      Three catalogs are required.  The first is a catalog that
 	      contains information about the DSSSL stylesheets.  The second
 	      contains information about the DocBook DTD.  The third contains
 	      information specific to Jade.</para>
 	  </callout>
 
 	  <callout arearefs="examples-co-jade-1-dsssl">
 	    <para>Specifies the full path to the DSSSL stylesheet that Jade
 	      will use when processing the document.</para>
 	  </callout>
 
 	  <callout arearefs="examples-co-jade-1-transform">
 	    <para>Instructs Jade to perform a
 	      <emphasis>transformation</emphasis> from one DTD to another.  In 
 	      this case, the input is being transformed from the DocBook DTD
 	      to the HTML DTD.</para>
 	  </callout>
 
 	  <callout arearefs="examples-co-jade-1-filename">
 	    <para>Specifies the file that Jade should process, and redirects
 	      output to the specified <filename>.html</filename> file.</para>
 	  </callout>
 	</calloutlist>
       </example>
 
       <example>
 	<title>Converting DocBook to HTML (several small files)</title>
 	
 	<screen>&prompt.user; <userinput>jade \
     -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-2-catalog">
     -c /usr/local/share/sgml/docbook/catalog \
     -c /usr/local/share/sgml/jade/catalog \
     -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \<co id="examples-co-jade-2-dsssl">
     -t sgml <co id="examples-co-jade-2-transform"> <replaceable>file</replaceable>.sgml <co id="examples-co-jade-2-filename"></userinput></screen>
 
 	<calloutlist>
 	  <callout arearefs="examples-co-jade-2-catalog">
 	    <para>Specifies the catalogs that Jade will need to process.
 	      Three catalogs are required.  The first is a catalog that
 	      contains information about the DSSSL stylesheets.  The second
 	      contains information about the DocBook DTD.  The third contains
 	      information specific to Jade.</para>
 	  </callout>
 
 	  <callout arearefs="examples-co-jade-2-dsssl">
 	    <para>Specifies the full path to the DSSSL stylesheet that Jade
 	      will use when processing the document.</para>
 	  </callout>
 
 	  <callout arearefs="examples-co-jade-2-transform">
 	    <para>Instructs Jade to perform a
 	      <emphasis>transformation</emphasis> from one DTD to another.  In 
 	      this case, the input is being transformed from the DocBook DTD
 	      to the HTML DTD.</para>
 	  </callout>
 
 	  <callout arearefs="examples-co-jade-2-filename">
 	    <para>Specifies the file that Jade should process.  The
 	      stylesheets determine how the individual HTML files will be
 	      named, and the name of the <quote>root</quote> file (i.e., the 
 	      one that contains the start of the document.</para>
 	  </callout>
 	</calloutlist>
 
 	<para>This example may still only generate one HTML file, depending on 
 	  the structure of the document you are processing, and the
 	  stylesheet's rules for splitting output.</para>
       </example>
 
       <example id="examples-docbook-postscript">
 	<title>Converting DocBook to Postscript</title>
 
 	<para>The source SGML file must be converted to a TeX file.</para>
 
 	<screen>&prompt.user; <userinput>jade -Vtex-backend \ <co id="examples-co-jade-3-tex-backend">
     -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-3-catalog">
     -c /usr/local/share/sgml/docbook/catalog \
     -c /usr/local/share/sgml/jade/catalog \
     -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \<co id="examples-co-jade-3-dsssl">
     -t tex <co id="examples-co-jade-3-tex"> <replaceable>file</replaceable>.sgml</userinput></screen>
 
 	<calloutlist>
 	  <callout arearefs="examples-co-jade-3-tex-backend">
 	    <para>Customises the stylesheets to use various options
 	      specific to producing output for TeX.</para>
 	  </callout>
 	  
 	  <callout arearefs="examples-co-jade-3-catalog">
 	    <para>Specifies the catalogs that Jade will need to process. Three
 	      catalogs are required.  The first is a catalog that contains
 	      information about the DSSSL stylesheets.  The second contains
 	      information about the DocBook DTD.  The third contains
 	      information specific to Jade.</para>
 	  </callout>
 
 	  <callout arearefs="examples-co-jade-3-dsssl">
 	    <para>Specifies the full path to the DSSSL stylesheet that
 	      Jade will use when processing the document.</para>
 	  </callout>
 
 	  <callout arearefs="examples-co-jade-3-tex">
 	    <para>Instructs Jade to convert the output to TeX.</para>
 	  </callout>
 	</calloutlist>
 
 	<para>The generated <filename>.tex</filename> file must now be run 
 	  through <command>tex</command>, specifying the
 	  <literal>&amp;jadetex</literal> macro package.</para>
 	    
 	<screen>&prompt.user; <userinput>tex "&amp;jadetex" <replaceable>file</replaceable>.tex</userinput></screen>
 
 	<para>You have to run <command>tex</command> <emphasis>at
 	  least</emphasis> three times.  The first run processes the
 	  document, and determines areas of the document which are referenced
 	  from other parts of the document, for use in indexing, and so
 	  on.</para>
 
 	<para>Do not be alarmed if you see warning messages such as
 	  <literal>LaTeX Warning: Reference `136' on page 5 undefined on input
 	  line 728.</literal> at this point.</para>
 	
 	<para>The second run reprocesses the document now that certain pieces
 	  of information are known (such as the document's page length).  This
 	  allows index entries and other cross-references to be fixed
 	  up.</para>
 
 	<para>The third pass performs any final cleanup necessary.</para>
 	
 	<para>The output from this stage will be
 	  <filename><replaceable>file</replaceable>.dvi</filename>.</para>
 	
 	<para>Finally, run <command>dvips</command> to convert the
 	  <filename>.dvi</filename> file to Postscript.</para>
 
 	<screen>&prompt.user; <userinput>dvips -o <replaceable>file</replaceable>.ps <replaceable>file.dvi</replaceable></userinput></screen>
       </example>
 
       <example>
 	<title>Converting DocBook to PDF</title>
 
 	<para>The first part of this process is identical to that when
 	  converting DocBook to Postscript, using the same
 	  <command>jade</command> command line (<xref
 	    linkend="examples-docbook-postscript">).</para>
 
 	<para>When the <filename>.tex</filename> file has been generated you
 	  run pdfTeX.  However, use the &amp;pdfjadetex macro package
 	  instead.</para>
 
 	<screen>&prompt.user; <userinput>pdftex "&amp;pdfjadetex" <replaceable>file</replaceable>.tex</userinput></screen>
 
 	<para>Again, run this command three times.</para>
 
 	<para>This will generate
 	  <filename><replaceable>file</replaceable>.pdf</filename>, which does 
 	  not need to be processed any further.</para>
       </example>
     </sect2>
   </sect1>
 </appendix>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../appendix.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "appendix")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
index 9bf070131d..3b6d15154b 100644
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml
@@ -1,300 +1,300 @@
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="overview">
   <title>Overview</title>
   
   <para>Welcome to the FreeBSD Documentation Project.  Good quality
     documentation is very important to the success of FreeBSD, and the
     FreeBSD Documentation Project (FDP) is how a lot of that documentation
     is produced.  Your contributions are very valuable.</para>
   
   <para>This document's main purpose is to clearly explain <emphasis>how
     the FDP is organised</emphasis>, <emphasis>how to write and submit
     documentation to the FDP</emphasis>, and <emphasis>how to
     effectively use the tools available to you when writing
     documentation</emphasis>.</para>
   
   <para><indexterm>
       <primary>Membership</primary>
     </indexterm>
     Everyone is welcome to join the FDP.  There is no minimum
     membership requirement, no quota of documentation you need to
     produce per month.  All you need to do is subscribe to the
     &a.doc;.</para>
 
   <para>After you have finished reading this document you should:</para>
   
   <itemizedlist>
     <listitem> 
       <para>Know which documentation is maintained by the FDP.</para>
     </listitem>
     
     <listitem>
       <para>Be able to read and understand the SGML source code for the
 	documentation maintained by the FDP.</para>
     </listitem>
     
     <listitem> 
       <para>Be able to make changes to the documentation.</para>
     </listitem>
     
     <listitem>
       <para>Be able to submit your changes back for review and eventual
 	inclusion in the FreeBSD documentation.</para>
     </listitem> 
   </itemizedlist>
 
-  <sect1>
+  <sect1 id="overview-doc">
     <title>The FreeBSD Documentation Set</title>
 
     <para>The FDP is responsible for four categories of FreeBSD
       documentation.</para>
     
     <variablelist>
       <varlistentry>
         <term>Manual pages</term>
 
         <listitem>
           <para>The English language system manual pages are not written by
 	    the FDP, as they are part of the base system. However, the FDP can
 	    (and has) re-worded parts of existing manual pages to make them
 	    clearer, or to correct inaccuracies.</para>
 
           <para>The translation teams are responsible for translating the
 	    system manual pages into different languages.  These translations
 	    are kept within the FDP.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
         <term>FAQ</term>
 	
         <listitem>
           <para>The FAQ aims to address (in short question and answer format)
 	    questions that are asked, or should be asked, on the various
 	    mailing lists and newsgroups devoted to FreeBSD.  The format does
 	    not permit long and comprehensive answers.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
         <term>Handbook</term>
 
         <listitem>
           <para>The Handbook aims to be the comprehensive on-line resource and
 	    reference for FreeBSD users.</para>
         </listitem>
       </varlistentry>
  
       <varlistentry>
          <term>Web site</term>
 	
          <listitem>
            <para>This is the main FreeBSD presence on the World Wide Web,
 	    visible at <ulink
 	      url="../../../../index.html">http://www.FreeBSD.org/</ulink>
 	    and many mirrors around the world.  The web site is many people's
 	    first exposure to FreeBSD.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
     
     <para>These four groups of documentation are all available in the
       FreeBSD CVS tree.  This means that the logs of changes to these
       files are visible to anyone, and anyone can use a program such as
       <application>CVSup</application> or
       <application>CTM</application> to keep local copies of
       this documentation.</para>
     
     <para>In addition, many people have written tutorials or other web
       sites relating to FreeBSD.  Some of these are stored in the CVS
       repository as well (where the author has agreed to this).  In
       other cases the author has decided to keep his documentation
       separate from the main FreeBSD repository.  The FDP endeavours to
       provide links to as much of this documentation as
       possible.</para>
   </sect1>                                                                     
   
-  <sect1>                                                                      
+  <sect1 id="overview-before">
     <title>Before you start</title>                                            
     
     <para>This document assumes that you already know:</para>                  
     
     <itemizedlist>                                                             
       <listitem>                                                               
 	<para>How to maintain an up-to-date local copy of the FreeBSD
 	  documentation by maintaining a local copy of the
 	  FreeBSD CVS repository (using <application>CVS</application>
 	  and either <application>CVSup</application> or
 	  <application>CTM</application>) or by using
 	  <application>CVSup</application> to download just a
 	  <emphasis>checked-out</emphasis> copy.</para>
       </listitem>
       
       <listitem>                                                               
 	<para>How to download and install new software using either the
 	  FreeBSD Ports system or &man.pkg.add.1;.</para>
       </listitem>                                                              
     </itemizedlist>                                                            
   </sect1>
 
-  <sect1>
+  <sect1 id="overview-quick-start">
     <title>Quick Start</title>
 
     <para>If you just want to get going, and feel confident you can pick
       things up as you go along, follow these instructions.</para>
 
     <procedure>
       <step>
 	<para>Install the <filename role="package">textproc/docproj</filename>
 	  meta-port.</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
 &prompt.root; <userinput>make JADETEX=no install</userinput></screen>
       </step>
 
       <step>
 	<para>Get a local copy of the FreeBSD <filename>doc</filename> tree.
 	  Either use CVSup in <literal>checkout</literal> mode to do this, or
 	  get a full copy of the CVS repository locally.</para>
 
 	<para>If you have the CVS repository locally then as a minimum you
 	  will need to checkout the <filename>doc/share</filename>, and
 	  <filename>doc/en_US.ISO8859-1/share</filename>
 	  directories.</para>
 
 	<screen>&prompt.user; <userinput>cvs checkout doc/share</userinput>
 &prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/share</userinput></screen>
 
 	<para>If you have plenty of disk space then you could check out
 	  everything.</para>
 
 	<screen>&prompt.user; <userinput>cvs checkout doc</userinput></screen>
       </step>
 
       <step>
 	<para>If you are preparing a change to an existing book or article,
 	  check it out of the repository as necessary.  If you are planning on
 	  contributing a new book or article then use an existing one as a
 	  guide.</para>
 
 	<para>For example, if you want to contribute a new article about
 	  setting up a VPN between FreeBSD and Windows 2000 you might do the
 	  following.</para>
 
 	<procedure>
 	  <step>
 	    <para>Check out the <filename>articles</filename>
 	      directory.</para>
 
 	    <screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/articles</userinput></screen>
 	  </step>
 
 	  <step>
 	    <para>Copy an existing article to use as a template.  In this
 	      case, you have decided that your new article belongs in a
 	      directory called <filename>vpn-w2k</filename>.</para>
 
 	    <screen>&prompt.user; <userinput>cd doc/en_US.ISO8859-1/articles</userinput>
 &prompt.user; <userinput>cp -r committers-guide vpn-w2k</userinput></screen>
 	  </step>
 	</procedure>
 
 	<para>If you wanted to edit an existing document, such as the FAQ,
 	  which is in <filename>doc/en_US.ISO8859-1/books/faq</filename> you
 	  would check it out of the repository like this.</para>
 
 	<screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/books/faq</userinput></screen>
       </step>
 
       <step>
 	<para>Edit the <filename>.sgml</filename> files using your editor of
 	  choice.</para>
       </step>
 
       <step>
 	<para>Test the markup using the <maketarget>lint</maketarget>
 	  target.  This will quickly find any errors in the document
 	  without actually performing the time-consuming
 	  transformation.</para>
 
 	<screen>&prompt.user; <userinput>make lint</userinput></screen>
 
 	<para>When you are ready to actually build the document, you
   	  may specify a single format or a list of formats in the
   	  <varname>FORMATS</varname> variable.  Currently,
   	  <literal>html</literal>, <literal>html-split</literal>,
   	  <literal>txt</literal>, <literal>ps</literal>,
   	  <literal>pdf</literal>, and <literal>rtf</literal> are
   	  supported.  The most up to date list of supported formats is
   	  listed at the top of the
   	  <filename>doc/share/mk/doc.docbook.mk</filename> file.  Make
   	  sure to use quotes around the list of formats when you build
   	  more than one format with a single command.</para>
 
         <para>For example, to convert the document to
           <literal>html</literal> only, you would use:</para>
 
 	<screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>
 
         <para>But when you want to convert the document to both
           <literal>html</literal> and <literal>txt</literal> format,
           you could use either two separate &man.make.1; runs,
           with:</para>
 
 	<screen>&prompt.user; <userinput>make FORMATS=html</userinput>
 &prompt.user; <userinput>make FORMATS=txt</userinput></screen>
 
         <para>or, you can do it in one command:</para>
 
 	<screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
       </step>
 
       <step>
 	<para>Submit your changes using &man.send-pr.1;.</para>
       </step>
     </procedure>
   </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/see-also/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
index 0d7f5b2aa0..7c5a57b981 100644
--- a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml
@@ -1,134 +1,134 @@
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="see-also">
   <title>See Also</title>
 
   <para>This document is deliberately not an exhaustive discussion of SGML,
     the DTDs listed, and the FreeBSD Documentation Project. For more
     information about these, you are encouraged to see the following web
     sites.</para>
 
-  <sect1>
+  <sect1 id="see-also-fdp">
     <title>The FreeBSD Documentation Project</title>
 
     <itemizedlist>
       <listitem>
 	<para><ulink url="../../../../docproj/index.html">The FreeBSD
 	    Documentation Project web pages</ulink></para>
       </listitem>
 
       <listitem>
 	<para><ulink url="../handbook/index.html">The FreeBSD Handbook</ulink></para>
       </listitem>
     </itemizedlist>
   </sect1>
 
-  <sect1>
+  <sect1 id="see-also-sgml">
     <title>SGML</title>
 
     <itemizedlist>
       <listitem>
 	<para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web
 	    page</ulink>, a comprehensive SGML resource</para>
       </listitem>
       
       <listitem>
 	<para><ulink
 	    url="http://etext.virginia.edu/bin/tei-tocs?div=DIV1&amp;id=SG">Gentle introduction to SGML</ulink></para>
       </listitem>
     </itemizedlist>
   </sect1>
 
-  <sect1>
+  <sect1 id="see-also-html">
     <title>HTML</title>
 
     <itemizedlist>
       <listitem>
 	<para><ulink url="http://www.w3.org/">The World Wide Web
 	    Consortium</ulink></para>
       </listitem>
 
       <listitem>
 	<para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0
 	    specification</ulink></para>
       </listitem>
     </itemizedlist>
   </sect1>
 
-  <sect1>
+  <sect1 id="see-also-docbook">
     <title>DocBook</title>
 
     <itemizedlist>
       <listitem>
 	<para><ulink url="http://www.oasis-open.org/docbook/">The DocBook
 	    Technical Committee</ulink>, maintainers of the DocBook DTD</para>
       </listitem>
 
       <listitem>
 	<para><ulink url="http://www.docbook.org/">DocBook: The Definitive
 	    Guide</ulink>, the online documentation for the DocBook
 	  DTD.</para>
 	
       </listitem>
 
       <listitem>
 	<para><ulink url="http://docbook.sourceforge.net/">The DocBook Open
 	    Repository</ulink> contains DSSSL stylesheets and other resources
 	  for people using DocBook.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
-  <sect1>
+  <sect1 id="see-also-linuxdoc">
     <title>The Linux Documentation Project</title>
 
     <itemizedlist>
       <listitem>
 	<para><ulink url="http://www.linuxdoc.org/">The Linux Documentation
 	  Project web pages</ulink></para>
       </listitem>
     </itemizedlist>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index f6c1949ec3..9439a7e162 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,2680 +1,2680 @@
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="sgml-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 &a.doc;.</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>
+  <sect1 id="sgml-markup-html">
     <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 documentation, 
       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 role="package">textproc/html</filename> port.  They are automatically
       installed as part of the <filename role="package">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 into 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, preceding 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
   preceded 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 into 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 is a new copy of my primer for contributors 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 into 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 into
          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
 	  <quote>teletype</quote>).</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
 	  color, 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 preceding <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>
+  <sect1 id="sgml-markup-docbook">
     <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 role="package">textproc/docbook</filename> port.  It is automatically
       installed as part of the <filename role="package">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
 	<quote>DocBook</quote> 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 &a.nik;.</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="../../../../docs.html">FreeBSD
 	  tutorials</ulink> are all marked up as articles, while this
 	document, the <ulink url="../faq/index.html">FreeBSD
 	  FAQ</ulink>, and the <ulink
 	  url="../handbook/index.html">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;releaseinfo>&#36;FreeBSD&#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;releaseinfo>&#36;FreeBSD&#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 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 <quote>meta</quote>
 	  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
     hard disk.</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 hard disk.</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 are 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 analogous 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 do not 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 into 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 operating system, 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>Quotations</title>
 
 	<para>To quote text from another document or source, or to denote
 	  a phrase that is used figuratively, use <sgmltag>quote</sgmltag>.
 	  Within a <sgmltag>quote</sgmltag> tag, you may use most of the
 	  markup tags available for normal text.</para>
 
 	<example>
 	  <title>Quotations</title>
 
 	  <para>Use:</para>
 
 	  <programlisting><![ CDATA [<para>However, make sure that the search does not go beyond the
   <quote>boundary between local and public administration</quote>,
   as RFC 1535 calls it.</para>]]></programlisting>
 
 	  <para>Appearance:</para>
 
 	  <para>However, make sure that the search does not go beyond the
 	    <quote>boundary between local and public administration</quote>,
 	    as RFC 1535 calls it.</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 <quote>command(number)</quote> 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 <quote>in-line</quote> 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>The name of ports</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 might need to include the name of a program from the
           FreeBSD Ports Collection in the documentation.  Use the
           <sgmltag>filename</sgmltag> tag with the <literal>role</literal>
           attribute set to <literal>package</literal> to identify these.
           Since ports
           can be installed in any number of locations, only include
           the category and the port name; do not include
           <filename>/usr/ports</filename>.</para>
 
         <example>
           <title><sgmltag>filename</sgmltag> tag with
             <literal>package</literal> role</title>
 
           <para>Use:</para>
 
           <programlisting><![ CDATA [<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>]]></programlisting>
 
           <para>Appearance:</para>
 	  
           <para>Install the <filename role="package">net/ethereal</filename>
             port to view network traffic.</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 <quote>literal</quote> 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 <quote>in-line</quote> 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
 	  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>
 
       <sect3>
         <title>Quoting system errors</title>
 
         <para>You might want to show errors generated by FreeBSD.
           Mark these with <sgmltag>errorname</sgmltag>.  This
           indicates the exact error that appears.</para>
 
         <example>
           <title><sgmltag>errorname</sgmltag></title>
 
           <para>Use:</para>
 
 	  <programlisting><![ CDATA [ 
 <screen><errorname>Panic: cannot mount root</errorname></screen> ]]>
 </programlisting>
 
 
           <para>Appearance:</para>
 
           <informalexample>
             <screen><errorname>Panic: cannot mount root</errorname></screen>
           </informalexample>
         </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 is not guaranteed.</para>
 
 	<para>You will also need to install the
 	  <filename role="package">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 are working on the
 	  <filename>Makefile</filename>s and other infrastructure it makes
 	  things easier.  This port is <emphasis>not</emphasis> in the
 	  <filename role="package">textproc/docproj</filename> meta port, you must install it
 	  by hand.</para>
 
 	<para>The best example of what follows in practice is the
 	  <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> document.
 	  If you are unsure of the description that follows, take a look at the
 	  files in that directory to see how everything hangs together.
 	  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, time lines, 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 into
 	  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 will not 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>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> 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
 	    <quote>this</quote> or <quote>here</quote> 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="../../../../index.html">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="../../../../index.html">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 5ef285dcee..253f3c935a 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
@@ -1,1580 +1,1580 @@
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="sgml-primer">
   <title>SGML Primer</title>
 
   <para>The majority of FDP documentation is written in applications of
     SGML.  This chapter explains exactly what that means, how to read
     and understand the source to the documentation, and the sort of SGML
     tricks you will see used in the documentation.</para>
 
   <para>Portions of this section were inspired by Mark Galassi's <ulink
       url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para>
   
-  <sect1>
+  <sect1 id="sgml-primer-overview">
     <title>Overview</title>
 
     <para>Way back when, electronic text was simple to deal with.  Admittedly, 
       you had to know which character set your document was written in (ASCII, 
       EBCDIC, or one of a number of others) but that was about it.  Text was
       text, and what you saw really was what you got.  No frills, no
       formatting, no intelligence.</para>
 
     <para>Inevitably, this was not enough.  Once you have text in a
       machine-usable format, you expect machines to be able to use it and
       manipulate it intelligently.  You would like to indicate that certain
       phrases should be emphasised, or added to a glossary, or be hyperlinks.
       You might want filenames to be shown in a <quote>typewriter</quote> style 
       font for viewing on screen, but as <quote>italics</quote> when printed,
       or any of a myriad of other options for presentation.</para>
 
     <para>It was once hoped that Artificial Intelligence (AI) would make this
       easy.  Your computer would read in the document and automatically
       identify key phrases, filenames, text that the reader should type in,
       examples, and more.  Unfortunately, real life has not happened quite
       like that, and our computers require some assistance before they can
       meaningfully process our text.</para>
 
     <para>More precisely, they need help identifying what is what.  You or I
       can look at
 
       <blockquote>
 	<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
 
 	<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
       </blockquote>
 
       and easily see which parts are filenames, which are commands to be typed
       in, which parts are references to manual pages, and so on.  But the
       computer processing the document cannot.  For this we need
       markup.</para>
     
     <para><quote>Markup</quote> is commonly used to describe <quote>adding
       value</quote> or <quote>increasing cost</quote>.  The term takes on both
       these meanings when applied to text.  Markup is additional text included 
       in the document, distinguished from the document's content in some way,
       so that programs that process the document can read the markup and use
       it when making decisions about the document.  Editors can hide the
       markup from the user, so the user is not distracted by it.</para>
 
     <para>The extra information stored in the markup <emphasis>adds
       value</emphasis> to the document.  Adding the markup to the document
       must typically be done by a person&mdash;after all, if computers could
       recognise the text sufficiently well to add the markup then there would
       be no need to add it in the first place.  This <emphasis>increases the
       cost</emphasis> (i.e., the effort required) to create the
       document.</para>
 
     <para>The previous example is actually represented in this document like
       this;</para>
 
     <programlisting><![ CDATA [
 <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para>
 
 <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting>
 
     <para>As you can see, the markup is clearly separate from the
       content.</para>
 
     <para>Obviously, if you are going to use markup you need to define what
       your markup means, and how it should be interpreted.  You will need a
       markup language that you can follow when marking up your
       documents.</para>
     
    <para>Of course, one markup language might not be enough.  A markup
       language for technical documentation has very different requirements
       than a markup language that was to be used for cookery recipes.  This,
       in turn, would be very different from a markup language used to describe
       poetry.  What you really need is a first language that you use to write
       these other markup languages.  A <emphasis>meta markup
       language</emphasis>.</para>
     
     <para>This is exactly what the Standard Generalised Markup Language (SGML)
       is.  Many markup languages have been written in SGML, including the two
       most used by the FDP, HTML and DocBook.</para>
     
     <para>Each language definition is more properly called a Document Type
       Definition (DTD).  The DTD specifies the name of the elements that can
       be used, what order they appear in (and whether some markup can be used
       inside other markup) and related information.  A DTD is sometimes
       referred to as an <emphasis>application</emphasis> of SGML.</para>
 
     <para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis>
       specification of all the elements that are allowed to appear, the order
       in which they should appear, which elements are mandatory, which are
       optional, and so forth. This makes it possible to write an SGML
       <emphasis>parser</emphasis> which reads in both the DTD and a document
       which claims to conform to the DTD.  The parser can then confirm whether
       or not all the elements required by the DTD are in the document in the
       right order, and whether there are any errors in the markup.  This is
       normally referred to as <quote>validating  the document</quote>.</para>
 
     <note>
       <para>This processing simply confirms that the choice of elements, their 
 	ordering, and so on, conforms to that listed in the DTD.  It does
 	<emphasis>not</emphasis> check that you have used
 	<emphasis>appropriate</emphasis> markup for the content.  If you
 	tried to mark up all the filenames in your document as function
 	names, the parser would not flag this as an error (assuming, of
 	course, that your DTD defines elements for filenames and functions,
 	and that they are allowed to appear in the same place).</para>
     </note>
     
     <para>It is likely that most of your contributions to the Documentation
       Project will consist of content marked up in either HTML or DocBook,
       rather than alterations to the DTDs.  For this reason this book will
       not touch on how to write a DTD.</para>
   </sect1>
   
   <sect1 id="sgml-primer-elements">
     <title>Elements, tags, and attributes</title>
 
     <para>All the DTDs written in SGML share certain characteristics.  This is
       hardly surprising, as the philosophy behind SGML will inevitably show
       through. One of the most obvious manifestations of this philosophy is
       that of <emphasis>content</emphasis> and
       <emphasis>elements</emphasis>.</para>
 
     <para>Your documentation (whether it is a single web page, or a lengthy
       book) is considered to consist of content.  This content is then divided
       (and further subdivided) into elements.  The purpose of adding markup is
       to name and identify the boundaries of these elements for further
       processing.</para>
 
     <para>For example, consider a typical book.  At the very top level, the
       book is itself an element.  This <quote>book</quote> element obviously
       contains chapters, which can be considered to be elements in their own
       right.  Each chapter will contain more elements, such as paragraphs,
       quotations, and footnotes.  Each paragraph might contain further
       elements, identifying content that was direct speech, or the name of a
       character in the story.</para>
 
     <para>You might like to think of this as <quote>chunking</quote> content.
       At the very top level you have one chunk, the book.  Look a little
       deeper, and you have more chunks, the individual chapters.  These are
       chunked further into paragraphs, footnotes, character names, and so
       on.</para>
 
     <para>Notice how you can make this differentiation between different
       elements of the content without resorting to any SGML terms.  It really
       is surprisingly straightforward.  You could do this with a highlighter
       pen and a printout of the book, using different colors to indicate
       different chunks of content.</para>
 
     <para>Of course, we do not have an electronic highlighter pen, so we need
       some other way of indicating which element each piece of content belongs
       to.  In languages written in SGML (HTML, DocBook, et al) this is done by
       means of <emphasis>tags</emphasis>.</para>
 
     <para>A tag is used to identify where a particular element starts, and
       where the element ends.  <emphasis>The tag is not part of the element
       itself</emphasis>. Because each DTD was normally written to mark up
       specific types of information, each one will recognise different
       elements, and will therefore have different names for the tags.</para>
 
     <para>For an element called <replaceable>element-name</replaceable> the
       start tag will normally look like
       <literal>&lt;<replaceable>element-name</replaceable>&gt;</literal>.  The
       corresponding closing tag for this element is
       <literal>&lt;/<replaceable>element-name</replaceable>&gt;</literal>.</para>
 
     <example>
       <title>Using an element (start and end tags)</title>
 
       <para>HTML has an element for indicating that the content enclosed by
 	the element is a paragraph, called <literal>p</literal>.  This
 	element has both start and end tags.</para>
       
       <programlisting><![ CDATA [<p>This is a paragraph.  It starts with the start tag for
   the 'p' element, and it will end with the end tag for the 'p'
   element.</p>
 
 <p>This is another paragraph.  But this one is much shorter.</p>]]></programlisting>	  
     </example>
 
     <para>Not all elements require an end tag.  Some elements have no content.
       For example, in HTML you can indicate that you want a horizontal line to
       appear in the document.  Obviously, this line has no content, so just
       the start tag is required for this element.</para>
 
     <example>
       <title>Using an element (start tag only)</title>
 
       <para>HTML has an element for indicating a horizontal rule, called
 	<literal>hr</literal>.  This element does not wrap content, so only
 	has a start tag.</para>
 
       <programlisting><![ CDATA [<p>This is a paragraph.</p>
 
 <hr>
 
 <p>This is another paragraph.  A horizontal rule separates this
   from the previous paragraph.</p>]]></programlisting>
     </example>
     
     <para>If it is not obvious by now, elements can contain other elements.
       In the book example earlier, the book element contained all the chapter
       elements, which in turn contained all the paragraph elements, and so
       on.</para>
 
     <example>
       <title>Elements within elements; <sgmltag>em</sgmltag></title>
       
       <programlisting><![ CDATA [<p>This is a simple <em>paragraph</em> where some
   of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting>
     </example>
     
     <para>The DTD will specify the rules detailing which elements can contain
       other elements, and exactly what they can contain.</para>
 
     <important>
       <para>People often confuse the terms tags and elements, and use the
 	terms as if they were interchangeable.  They are not.</para>
 
       <para>An element is a conceptual part of your document.  An element has
 	a defined start and end.  The tags mark where the element starts and
 	end.</para>
 
       <para>When this document (or anyone else knowledgeable about SGML) refers
 	to <quote>the &lt;p&gt; tag</quote> they mean the literal text
 	consisting of the three characters <literal>&lt;</literal>,
 	<literal>p</literal>, and <literal>&gt;</literal>.  But the phrase
 	<quote>the &lt;p&gt; element</quote> refers to the whole
 	element.</para>
 
       <para>This distinction <emphasis>is</emphasis> very subtle.  But keep it 
 	in mind.</para>
     </important>
       
     <para>Elements can have attributes.  An attribute has a name and a value,
       and is used for adding extra information to the element.  This might be
       information that indicates how the content should be rendered, or might
       be something that uniquely identifies that occurrence of the element, or
       it might be something else.</para>
 
     <para>An element's attributes are written <emphasis>inside</emphasis> the
       start tag for that element, and take the form
       <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para>
 
     <para>In sufficiently recent versions of HTML, the <sgmltag>p</sgmltag>
       element has an attribute called <literal>align</literal>, which suggests
       an alignment (justification) for the paragraph to the program displaying
       the HTML.</para>
 
     <para>The <literal>align</literal> attribute can take one of four defined
       values, <literal>left</literal>, <literal>center</literal>,
       <literal>right</literal> and <literal>justify</literal>.  If the
       attribute is not specified then the default is
       <literal>left</literal>.</para>
 
     <example>
       <title>Using an element with an attribute</title>
       
       <programlisting><![ CDATA [<p align="left">The inclusion of the align attribute
   on this paragraph was superfluous, since the default is left.</p>
 
 <p align="center">This may appear in the center.</p>]]></programlisting>
     </example>
     
     <para>Some attributes will only take specific values, such as
       <literal>left</literal> or <literal>justify</literal>.  Others will
       allow you to enter anything you want.  If you need to include quotes
       (<literal>"</literal>) within an attribute then use single quotes around
       the attribute value.</para>
 
     <example>
       <title>Single quotes around attributes</title>
       
       <programlisting><![ CDATA [<p align='right'>I am on the right!</p>]]></programlisting>
     </example>
 
     <para>Sometimes you do not need to use quotes around attribute values at
       all.  However, the rules for doing this are subtle, and it is far
       simpler just to <emphasis>always</emphasis> quote your attribute
       values.</para>
 
     <para>The information on attributes, elements, and tags is stored
       in SGML catalogs.  The various Documentation Project tools use
       these catalog files to validate your work.  The tools in
       <filename role="package">textproc/docproj</filename> include a variety of SGML catalog
       files.  The FreeBSD Documentation Project includes its own set
       of catalog files.  Your tools need to know about both sorts of
       catalog files.</para>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <para>In order to run the examples in this document you will need to
         install some software on your system and ensure that an environment
         variable is set correctly.</para>
     
       <procedure>
 	<step>
 	  <para>Download and install <filename role="package">textproc/docproj</filename>
 	    from the FreeBSD ports system.  This is a
             <emphasis>meta-port</emphasis> that should download and install
             all of the programs and supporting files that are used by the
             Documentation Project.</para>
 	</step>
 	
         <step>
           <para>Add lines to your shell startup files to set
             <envar>SGML_CATALOG_FILES</envar>. (If you are not working
             on the English version of the documentation, you will want
             to substitute the correct directory for your
             language.)</para>
     
 	  <example id="sgml-primer-envars">
 	    <title><filename>.profile</filename>, for &man.sh.1; and
 	      &man.bash.1; users</title>
 	    
 	    <programlisting>SGML_ROOT=/usr/local/share/sgml	    
 SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
 SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=/usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES
 export SGML_CATALOG_FILES</programlisting>
 	  </example>
 
 	  <example>
 	    <title><filename>.login</filename>, for &man.csh.1; and
 	      &man.tcsh.1; users</title>
 	    
 	    <programlisting>setenv SGML_ROOT /usr/local/share/sgml
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES</programlisting>
           </example>
     
           <para>Then either log out, and log back in again, or run those
             commands from the command line to set the variable values.</para>
 	</step>
       </procedure>
     
       <procedure>
 	<step>
 	  <para>Create <filename>example.sgml</filename>, and enter the
             following text;</para>
 
 	  <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 
 <html>
   <head>	     
     <title>An example HTML file</title>
   </head>
 
   <body>	    
     <p>This is a paragraph containing some text.</p>
 
     <p>This paragraph contains some more text.</p>
 
     <p align="right">This paragraph might be right-justified.</p>
   </body>	    
 </html>]]></programlisting>
 	</step>
 
 	<step>
 	  <para>Try and validate this file using an SGML parser.</para>
 
 	  <para>Part of <filename role="package">textproc/docproj</filename> is the
 	    &man.nsgmls.1; <link linkend="sgml-primer-validating">validating
 	    parser</link>.  Normally, &man.nsgmls.1; reads in a document
 	    marked up according to an SGML DTD and returns a copy of the
 	    document's Element Structure Information Set (ESIS, but that is
 	    not important right now).</para>
 
 	  <para>However, when &man.nsgmls.1; is given the <option>-s</option>
 	    parameter, &man.nsgmls.1; will suppress its normal output, and
 	    just print error messages.  This makes it a useful way to check to
 	    see if your document is valid or not.</para>
 
 	  <para>Use &man.nsgmls.1; to check that your document is
 	    valid;</para>
 
           <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen>
 
 	  <para>As you will see, &man.nsgmls.1; returns without displaying any
 	    output.  This means that your document validated
 	    successfully.</para>
 	</step>
 
 	<step>
 	  <para>See what happens when required elements are omitted.  Try
 	    removing the <sgmltag>title</sgmltag> and
 	    <sgmltag>/title</sgmltag> tags, and re-run the validation.</para>
 
           <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput>
 nsgmls:example.sgml:5:4:E: character data is not allowed here
 nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
 
 	  <para>The error output from &man.nsgmls.1; is organised into
 	    colon-separated groups, or columns.</para>
 
 	  <informaltable frame="none">
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>Column</entry>
 		  <entry>Meaning</entry>
 		</row>
 	      </thead>
 	      
 	      <tbody>
 		<row>
 		  <entry>1</entry>
 		  <entry>The name of the program generating the error.  This
 		    will always be <literal>nsgmls</literal>.</entry>
 		</row>
 
 		<row>
 		  <entry>2</entry>
 		  <entry>The name of the file that contains the error.</entry>
 		</row>
 
 		<row>
 		  <entry>3</entry>
 		  <entry>Line number where the error appears.</entry>
 		</row>
 
 		<row>
 		  <entry>4</entry>
 		  <entry>Column number where the error appears.</entry>
 		</row>
 
 		<row>
 		  <entry>5</entry>
 		  <entry>A one letter code indicating the nature of the
 		    message.  <literal>I</literal> indicates an informational
 		    message, <literal>W</literal> is for warnings, and
 		    <literal>E</literal> is for errors<footnote>
 		      <para>It is not always the fifth column either.
 			<command>nsgmls -sv</command> displays
 			<literal>nsgmls:I: SP version "1.3"</literal>
 			(depending on the installed version).  As you can see,
 			this is an informational message.</para>
 		    </footnote>, and <literal>X</literal> is for
 		    cross-references.  As you can see, these messages are
 		    errors.</entry>
 		</row>
 
 		<row>
 		  <entry>6</entry>
 		  <entry>The text of the error message.</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 
 	  <para>Simply omitting the <sgmltag>title</sgmltag> tags has
 	    generated 2 different errors.</para>
 
 	  <para>The first error indicates that content (in this case,
 	    characters, rather than the start tag for an element) has occurred
 	    where the SGML parser was expecting something else.  In this case,
 	    the parser was expecting to see one of the start tags for elements
 	    that are valid inside <sgmltag>head</sgmltag> (such as
 	    <sgmltag>title</sgmltag>).</para>
 
 	  <para>The second error is because <sgmltag>head</sgmltag> elements
 	    <emphasis>must</emphasis> contain a <sgmltag>title</sgmltag>
 	    element.  Because it does not &man.nsgmls.1; considers that the
 	    element has not been properly finished.  However, the closing tag
 	    indicates that the element has been closed before it has been
 	    finished.</para>
 	</step>
 
 	<step>
 	  <para>Put the <literal>title</literal> element back in.</para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
 
   <sect1 id="sgml-primer-doctype-declaration">
     <title>The DOCTYPE declaration</title>
 
     <para>The beginning of each document that you write must specify the name
       of the DTD that the document conforms to.  This is so that SGML parsers
       can determine the DTD and ensure that the document does conform to 
       it.</para>
 
     <para>This information is generally expressed on one line, in the DOCTYPE
       declaration.</para>
 
     <para>A typical declaration for a document written to conform with version
       4.0 of the HTML DTD looks like this;</para>
 
     <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting>
 
     <para>That line contains a number of different components.</para>
 
     <variablelist>
       <varlistentry>
 	<term><literal>&lt;!</literal></term>
 	
 	<listitem>
 	  <para>Is the <emphasis>indicator</emphasis> that indicates that this
 	    is an SGML declaration.  This line is declaring the document type.
 	  </para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><literal>DOCTYPE</literal></term>
 	
 	<listitem>
 	  <para>Shows that this is an SGML declaration for the document
 	    type.</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term><literal>html</literal></term>
 	
 	<listitem>
 	  <para>Names the first <link linkend="sgml-primer-elements">element</link> that
 	    will appear in the document.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term>
 
 	<listitem>
 	  <para>Lists the Formal Public Identifier (FPI)<indexterm>
 	      <primary>Formal Public Identifier</primary>
 	    </indexterm>
 	    for the DTD that this
 	    document conforms to.  Your SGML parser will use this to find the
 	    correct DTD when processing this document.</para>
 
 	  <para><literal>PUBLIC</literal> is not a part of the FPI, but
 	    indicates to the SGML processor how to find the DTD referenced in
 	    the FPI.  Other ways of telling the SGML parser how to find the
 	    DTD are shown <link
 	      linkend="sgml-primer-fpi-alternatives">later</link>.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><literal>&gt;</literal></term>
 	
 	<listitem>
 	  <para>Returns to the document.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
     
     <sect2>
       <title>Formal Public Identifiers (FPIs)<indexterm significance="preferred">
 	  <primary>Formal Public Identifier</primary>
 	</indexterm>
 </title>
 
       <note>
 	<para>You do not need to know this, but it is useful background, and
 	  might help you debug problems when your SGML processor can not locate
 	  the DTD you are using.</para>
       </note>
       
       <para>FPIs must follow a specific syntax.  This syntax is as
 	follows;</para>
 
       <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting>
 
       <variablelist>
 	<varlistentry>
 	  <term><replaceable>Owner</replaceable></term>
 	  
 	  <listitem>
 	    <para>This indicates the owner of the FPI.</para>
 
 	    <para>If this string starts with <quote>ISO</quote> then this is an
 	      ISO owned FPI.  For example, the FPI <literal>"ISO
 		8879:1986//ENTITIES Greek Symbols//EN"</literal> lists
 	      <literal>ISO 8879:1986</literal> as being the owner for the set
 	      of entities for Greek symbols.  ISO 8879:1986 is the ISO number
 	      for the SGML standard.</para>
 
 	    <para>Otherwise, this string will either look like
 	      <literal>-//<replaceable>Owner</replaceable></literal> or
 	      <literal>+//<replaceable>Owner</replaceable></literal> (notice
 	      the only difference is the leading <literal>+</literal> or
 	      <literal>-</literal>).</para>
 
 	    <para>If the string starts with <literal>-</literal> then the
 	      owner information is unregistered, with a <literal>+</literal>
 	      it identifies it as being registered.</para>
 
 	    <para>ISO 9070:1991 defines how registered names are generated; it
 	      might be derived from the number of an ISO publication, an ISBN
 	      code, or an organisation code assigned according to ISO 6523.
 	      In addition, a registration authority could be created in order
 	      to assign registered names.  The ISO council delegated this to
 	      the American National Standards Institute (ANSI).</para>
 
 	    <para>Because the FreeBSD Project has not been registered the
 	      owner string is <literal>-//FreeBSD</literal>.  And as you can
 	      see, the W3C are not a registered owner either.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Keyword</replaceable></term>
 	  
 	  <listitem>
 	    <para>There are several keywords that indicate the type of
 	      information in the file.  Some of the most common keywords are
 	      <literal>DTD</literal>, <literal>ELEMENT</literal>,
 	      <literal>ENTITIES</literal>, and <literal>TEXT</literal>.
 	      <literal>DTD</literal> is used only for DTD files,
 	      <literal>ELEMENT</literal> is usually used for DTD fragments
 	      that contain only entity or element declarations.
 	      <literal>TEXT</literal> is used for SGML content (text and
 	      tags).</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Description</replaceable></term>
 	  
 	  <listitem>
 	    <para>Any description you want to supply for the contents of this
 	      file.  This may include version numbers or any short text that
 	      is meaningful to you and unique for the SGML system.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><replaceable>Language</replaceable></term>
 	  
 	  <listitem>
 	    <para>This is an ISO two-character code that identifies the native
 	      language for the file.  <literal>EN</literal> is used for
 	      English.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <sect3>
 	<title><filename>catalog</filename> files</title>
 	
 	<para>If you use the syntax above and process this document
 	  using an SGML processor, the processor will need to have some way of
 	  turning the FPI into the name of the file on your computer that
 	  contains the DTD.</para>
 	
 	<para>In order to do this it can use a catalog file.  A catalog file
 	  (typically called <filename>catalog</filename>) contains lines that
 	  map FPIs to filenames.  For example, if the catalog file contained
 	  the line;</para>
 	
 	<programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"</programlisting>
 
 	<para>The SGML processor would know to look up the DTD from
 	  <filename>strict.dtd</filename> in the <filename>4.0</filename>
 	  subdirectory of whichever directory held the
 	  <filename>catalog</filename> file that contained that line.</para>
 
 	<para>Look at the contents of
 	  <filename>/usr/local/share/sgml/html/catalog</filename>.  This is
 	  the catalog file for the HTML DTDs that will have been installed as
 	  part of the <filename role="package">textproc/docproj</filename> port.</para>
       </sect3>
 
       <sect3>
 	<title><envar>SGML_CATALOG_FILES</envar></title>
 
 	<para>In order to locate a <filename>catalog</filename> file, your
 	  SGML processor will need to know where to look.  Many of them
 	  feature command line parameters for specifying the path to one or
 	  more catalogs.</para>
 
 	<para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to
 	  point to the files.  This environment variable should consist of a
 	  colon-separated list of catalog files (including their full
 	  path).</para>
 
 	<para>Typically, you will want to include the following files;</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/docbook/4.1/catalog</filename></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/html/catalog</filename></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/share/sgml/jade/catalog</filename></para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>You should <link linkend="sgml-primer-envars">already have done
 	    this</link>.</para>
       </sect3>
     </sect2>
     
     <sect2 id="sgml-primer-fpi-alternatives">
       <title>Alternatives to FPIs</title>
       
       <para>Instead of using an FPI to indicate the DTD that the document
 	conforms to (and therefore, which file on the system contains the DTD)
 	you can explicitly specify the name of the file.</para>
       
       <para>The syntax for this is slightly different:</para>
       
       <programlisting><![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting>
       
       <para>The <literal>SYSTEM</literal> keyword indicates that the SGML
 	processor should locate the DTD in a system specific fashion.  This
 	typically (but not always) means the DTD will be provided as a
 	filename.</para>
       
       <para>Using FPIs is preferred for reasons of portability.  You do not
 	want to have to ship a copy of the DTD around with your document, and
 	if you used the <literal>SYSTEM</literal> identifier then everyone
 	would need to keep their DTDs in the same place.</para>
     </sect2>
   </sect1>
   
   <sect1 id="sgml-primer-sgml-escape">
     <title>Escaping back to SGML</title>
 
     <para>Earlier in this primer I said that SGML is only used when writing a
       DTD.  This is not strictly true.  There is certain SGML syntax that you
       will want to be able to use within your documents.  For example,
       comments can be included in your document, and will be ignored by the
       parser.  Comments are entered using SGML syntax.  Other uses for SGML
       syntax in your document will be shown later too.</para>
       
     <para>Obviously, you need some way of indicating to the SGML processor
       that the following content is not elements within the document, but is
       SGML that the parser should act upon.</para>
 
     <para>These sections are marked by <literal>&lt;! ...  &gt;</literal> in
       your document.  Everything between these delimiters is SGML syntax as
       you might find within a DTD.</para>
 
     <para>As you may just have realised, the <link
 	linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link>
       is an example of SGML syntax that you need to include in your
       document&hellip;</para>
   </sect1>
   
-  <sect1>
+  <sect1 id="sgml-primer-comments">
     <title>Comments</title>
     
     <para>Comments are an SGML construction, and are normally only valid
       inside a DTD.  However, as <xref linkend="sgml-primer-sgml-escape">
       shows, it is possible to use SGML syntax within your document.</para>
 
     <para>The delimiter for SGML comments is the string
       <quote><literal>--</literal></quote>.  The first occurrence of this string
       opens a comment, and the second closes it.</para>
 
     <example>
       <title>SGML generic comment</title>
 
       <programlisting>&lt;!-- test comment --></programlisting>
       
       <programlisting><![ CDATA [
 <!-- This is inside the comment -->
 
 <!-- This is another comment    -->
 
 <!-- This is one way
      of doing multiline comments -->
 
 <!-- This is another way of   --
   -- doing multiline comments -->]]></programlisting>
     </example>
 
     <![ %output.print; [
     <important>
       <title>Use 2 dashes</title>
 
       <para>There is a problem with producing the Postscript and PDF versions
 	of this document.  The above example probably shows just one hyphen
 	symbol, <literal>-</literal> after the <literal>&lt;!</literal> and
 	before the <literal>&gt;</literal>.</para>
 
       <para>You <emphasis>must</emphasis> use two <literal>-</literal>,
 	<emphasis>not</emphasis> one.  The Postscript and PDF versions have
 	translated the two <literal>-</literal> in the original to a longer,
 	more professional <emphasis>em-dash</emphasis>, and broken this
 	example in the process.</para>
 
       <para>The HTML, plain text, and RTF versions of this document are not
 	affected.</para>
     </important>
     ]]>
     
     <para>If you have used HTML before you may have been shown different rules
       for comments.  In particular, you may think that the string
       <literal>&lt;!--</literal> opens a comment, and it is only closed by
       <literal>--&gt;</literal>.</para>
 
     <para>This is <emphasis>not</emphasis> the case.  A lot of web browsers
       have broken HTML parsers, and will accept that as valid.  However, the
       SGML parsers used by the Documentation Project are much stricter, and
       will reject documents that make that error.</para>
 
     <example>
       <title>Erroneous SGML comments</title>
 
       <programlisting><![ CDATA [
 <!-- This is in the comment --
 
      THIS IS OUTSIDE THE COMMENT!
 
   -- back inside the comment -->]]></programlisting>
 
       <para>The SGML parser will treat this as though it were actually;</para>
 
       <programlisting>&lt;!THIS IS OUTSIDE THE COMMENT&gt;</programlisting>
 
       <para>This is not valid SGML, and may give confusing error
 	messages.</para>
 
       <programlisting><![ CDATA [<!--------------- This is a very bad idea --------------->]]></programlisting>
 
       <para>As the example suggests, <emphasis>do not</emphasis> write
 	comments like that.</para>
 
       <programlisting><![ CDATA [<!--===================================================-->]]></programlisting>
 
       <para>That is a (slightly) better approach, but it still potentially
 	confusing to people new to SGML.</para>
     </example>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <procedure>
 	<step>
 	  <para>Add some comments to <filename>example.sgml</filename>, and
 	    check that the file still validates using &man.nsgmls.1;</para>
 	</step>
 
 	<step>
 	  <para>Add some invalid comments to
 	    <filename>example.sgml</filename>, and see the error messages that
 	    &man.nsgmls.1; gives when it encounters an invalid comment.</para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
     
-  <sect1>
+  <sect1 id="sgml-primer-entities">
     <title>Entities</title>
 
     <para>Entities are a mechanism for assigning names to chunks of content.
       As an SGML parser processes your document, any entities it finds are
       replaced by the content of the entity.</para>
     
     <para>This is a good way to have re-usable, easily changeable chunks of
       content in your SGML documents.  It is also the only way to include one
       marked up file inside another using SGML.</para>
     
     <para>There are two types of entities which can be used in two different
       situations; <emphasis>general entities</emphasis> and
       <emphasis>parameter entities</emphasis>.</para>
     
     <sect2 id="sgml-primer-general-entities">
       <title>General Entities</title>
       
       <para>You cannot use general entities in an SGML context (although you
 	define them in one).  They can only be used in your document.
 	Contrast this with <link
 	  linkend="sgml-primer-parameter-entities">parameter
 	  entities</link>.</para>
 
       <para>Each general entity has a name.  When you want to reference a
 	general entity (and therefore include whatever text it represents in
 	your document), you write
 	<literal>&amp;<replaceable>entity-name</replaceable>;</literal>.  For
 	example, suppose you had an entity called
 	<literal>current.version</literal> which expanded to the current
 	version number of your product.  You could write;</para>
 
       <programlisting><![ CDATA [<para>The current version of our product is
   &current.version;.</para>]]></programlisting>
 
       <para>When the version number changes you can simply change the
 	definition of the value of the general entity and reprocess your
 	document.</para>
 
       <para>You can also use general entities to enter characters that you
 	could not otherwise include in an SGML document.  For example, &lt;
 	and &amp; cannot normally appear in an SGML document.  When the SGML
 	parser sees the &lt; symbol it assumes that a tag (either a start tag
 	or an end tag) is about to appear, and when it sees the &amp; symbol
 	it assumes the next text will be the name of an entity.</para>
 
       <para>Fortunately, you can use the two general entities &amp;lt; and
 	&amp;amp; whenever you need to include one or other of these </para>
 	
       <para>A general entity can only be defined within an SGML context.
 	Typically, this is done immediately after the DOCTYPE
 	declaration.</para>
 
       <example>
 	<title>Defining general entities</title>
 
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY current.version    "3.0-RELEASE">
 <!ENTITY last.version       "2.2.7-RELEASE">
 ]>]]></programlisting>
 	  
 	<para>Notice how the DOCTYPE declaration has been extended by adding a
 	  square bracket at the end of the first line.  The two entities are
 	  then defined over the next two lines, before the square bracket is
 	  closed, and then the DOCTYPE declaration is closed.</para>
 
 	<para>The square brackets are necessary to indicate that we are
 	  extending the DTD indicated by the DOCTYPE declaration.</para>
       </example>
     </sect2>
     
     <sect2 id="sgml-primer-parameter-entities">
       <title>Parameter entities</title>
 
       <para>Like <link linkend="sgml-primer-general-entities">general
 	  entities</link>, parameter entities are used to assign names to
 	reusable chunks of text.  However, where as general entities can only
 	be used within your document, parameter entities can only be used
 	within an <link linkend="sgml-primer-sgml-escape">SGML
 	  context</link>.</para>
 
       <para>Parameter entities are defined in a similar way to general
 	entities.  However, instead of using
 	<literal>&amp;<replaceable>entity-name</replaceable>;</literal> to
 	refer to them, use
 	<literal>%<replaceable>entity-name</replaceable>;</literal><footnote>
 	  <para><emphasis>P</emphasis>arameter entities use the
 	    <emphasis>P</emphasis>ercent symbol.</para>
 	</footnote>.  The definition also includes the <literal>%</literal>
 	between the <literal>ENTITY</literal> keyword and the name of the
 	entity.</para>
       
       <example>
 	<title>Defining parameter entities</title>
 	
 	<programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % param.some "some">
 <!ENTITY % param.text "text">
 <!ENTITY % param.new  "%param.some more %param.text">
 
 <!-- %param.new now contains "some more text" -->
 ]>]]></programlisting>
       </example>
 	
       <para>This may not seem particularly useful.  It will be.</para>
     </sect2>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <procedure>
 	<step>
 	  <para>Add a general entity to
 	    <filename>example.sgml</filename>.</para>
 
 	  <programlisting><![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
 <!ENTITY version "1.1">
 ]>	  
 
 <html>
   <head>	     
     <title>An example HTML file</title>
   </head>
 
   <!-- You might well have some comments in here as well -->
 	  
   <body>	    
     <p>This is a paragraph containing some text.</p>
 
     <p>This paragraph contains some more text.</p>
 
     <p align="right">This paragraph might be right-justified.</p>
 
     <p>The current version of this document is: &version;</p>	  
   </body>	    
 </html>]]></programlisting>	  
 	</step>
 
 	<step>
 	  <para>Validate the document using &man.nsgmls.1;</para>
 	</step>
 
 	<step>
 	  <para>Load <filename>example.sgml</filename> into your web browser
 	    (you may need to copy it to <filename>example.html</filename>
 	    before your browser recognises it as an HTML document).</para>
 
 	  <para>Unless your browser is very advanced, you will not see the entity
 	    reference <literal>&amp;version;</literal> replaced with the
 	    version number.  Most web browsers have very simplistic parsers
 	    which do not handle proper SGML<footnote>
 	      <para>This is a shame.  Imagine all the problems and hacks (such
 		as Server Side Includes) that could be avoided if they
 		did.</para>
 	    </footnote>.</para>
 	</step>
 
 	<step>
 	  <para>The solution is to <emphasis>normalise</emphasis> your
 	    document using an SGML normaliser.  The normaliser reads in valid
 	    SGML and outputs equally valid SGML which has been transformed in
 	    some way.  One of the ways in which the normaliser transforms the
 	    SGML is to expand all the entity references in the document,
 	    replacing the entities with the text that they represent.</para>
 
 	  <para>You can use &man.sgmlnorm.1; to do this.</para>
 
           <screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen>
 
 	  <para>You should find a normalised (i.e., entity references
 	    expanded) copy of your document in
 	    <filename>example.html</filename>, ready to load into your web
 	    browser.</para>
 	</step>
 
 	<step>
 	  <para>If you look at the output from &man.sgmlnorm.1; you will see
 	    that it does not include a DOCTYPE declaration at the start.  To
 	    include this you need to use the <option>-d</option>
 	    option;</para>
 
           <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen>
 	</step>
       </procedure>
     </sect2>
   </sect1>
   
-  <sect1>
+  <sect1 id="sgml-primer-include">
     <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> into 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> into your web
 	      browser, and confirm that the
 	      <filename>para<replaceable>n</replaceable>.sgml</filename> files
 	      have been included in <filename>example.html</filename>.</para>
 	  </step>
 	</procedure>
       </sect3>
     </sect2>
   </sect1>
   
   <sect1 id="sgml-primer-marked-sections">
     <title>Marked sections</title>
     
     <para>SGML provides a mechanism to indicate that particular pieces of the
       document should be processed in a special way.  These are termed
       <quote>marked sections</quote>.</para>
 
     <example>
       <title>Structure of a marked section</title>
 
       <programlisting>&lt;![ <replaceable>KEYWORD</replaceable> [
   Contents of marked section
 ]]&gt;</programlisting>
     </example>
 
     <para>As you would expect, being an SGML construct, a marked section
       starts with <literal>&lt!</literal>.</para>
 
     <para>The first square bracket begins to delimit the marked
       section.</para>
 
     <para><replaceable>KEYWORD</replaceable> describes how this marked
       section should be processed by the parser.</para>
 
     <para>The second square bracket indicates that the content of the marked
       section starts here.</para>
     
     <para>The marked section is finished by closing the two square brackets,
       and then returning to the document context from the SGML context with
       <literal>&gt;</literal></para>
     
     <sect2>
       <title>Marked section keywords</title>
       
       <sect3>
 	<title><literal>CDATA</literal>, <literal>RCDATA</literal></title>
 	
 	<para>These keywords denote the marked sections <emphasis>content
 	    model</emphasis>, and allow you to change it from the
 	  default.</para>
 	
 	<para>When an SGML parser is processing a document it keeps track
 	  of what is called the <quote>content model</quote>.</para>
 	
 	<para>Briefly, the content model describes what sort of content the
 	  parser is expecting to see, and what it will do with it when it
 	  finds it.</para>
 
 	<para>The two content models you will probably find most useful are
 	  <literal>CDATA</literal> and <literal>RCDATA</literal>.</para>
 	
 	<para><literal>CDATA</literal> is for <quote>Character Data</quote>.
 	  If the parser is in this content model then it is expecting to see
 	  characters, and characters only.  In this model the &lt; and &amp;
 	  symbols lose their special status, and will be treated as ordinary
 	  characters.</para>
 	
 	<para><literal>RCDATA</literal> is for <quote>Entity references and
 	  character data</quote> If the parser is in this content model then it
 	  is expecting to see characters <emphasis>and</emphasis> entities.
 	  &lt; loses its special status, but &amp; will still be treated as
 	  starting the beginning of a general entity.</para>
 	
 	<para>This is particularly useful if you are including some verbatim
 	  text that contains lots of &lt; and &amp; characters.  While you
 	  could go through the text ensuring that every &lt; is converted to a
 	  &amp;lt; and every &amp; is converted to a &amp;amp;, it can be
 	  easier to mark the section as only containing CDATA.  When the SGML
 	  parser encounters this it will ignore the &lt; and &amp; symbols
 	  embedded in the content.</para>
 
         <note>
           <para>When you use <literal>CDATA</literal> or
             <literal>RCDATA</literal> in examples of text marked up in SGML,
             keep in mind that the content of <literal>CDATA</literal> is not
             validated.  You have to check the included SGML text using other
             means.  You could, for example, write the example in another
             document, validate the example code, and then paste it to your
             <literal>CDATA</literal> content.</para>
         </note>
 	<!-- The nesting of CDATA within the next example is disgusting -->
 	  
 	<example>
 	  <title>Using a CDATA marked section</title>
 	  
 	  <programlisting>&lt;para>Here is an example of how you would include some text
   that contained many &amp;lt; and &amp;amp; symbols.  The sample
   text is a fragment of HTML.  The surrounding text (&lt;para> and
   &lt;programlisting>) are from DocBook.&lt;/para>
 
 &lt;programlisting>
   &lt;![ CDATA [  <![ CDATA [
     <p>This is a sample that shows you some of the elements within
       HTML.  Since the angle brackets are used so many times, it is
       simpler to say the whole example is a CDATA marked section
       than to use the entity names for the left and right angle
       brackets throughout.</p>
 
     <ul>
       <li>This is a listitem</li>
       <li>This is a second listitem</li>
       <li>This is a third listitem</li>
     </ul>
 
     <p>This is the end of the example.</p>]]>
   ]]&gt;
 &lt/programlisting></programlisting>
 
 	  <para>If you look at the source for this document you will see this
 	    technique used throughout.</para>
 	</example>
       </sect3>
       
       <sect3>
 	<title><literal>INCLUDE</literal> and
 	  <literal>IGNORE</literal></title>
 	
 	<para>If the keyword is <literal>INCLUDE</literal> then the contents
 	  of the marked section will be processed.  If the keyword is
 	  <literal>IGNORE</literal> then the marked section is ignored and
 	  will not be processed.  It will not appear in the output.</para>
 
 	<example>
 	  <title>Using <literal>INCLUDE</literal> and
 	    <literal>IGNORE</literal> in marked sections</title>
 
 	  <programlisting>&lt;![ INCLUDE [
   This text will be processed and included.
 ]]&gt;
 
 &lt;![ IGNORE [
   This text will not be processed or included.
 ]]&gt;</programlisting>
 	</example>
 	
 	<para>By itself, this is not too useful.  If you wanted to remove text
 	  from your document you could cut it out, or wrap it in
 	  comments.</para>
 	  
 	<para>It becomes more useful when you realise you can use <link
 	    linkend="sgml-primer-parameter-entities">parameter entities</link>
 	  to control this.  Remember that parameter entities can only be used
 	  in SGML contexts, and the keyword of a marked section
 	  <emphasis>is</emphasis> an SGML context.</para>
 
 	<para>For example, suppose that you produced a hard-copy version of
 	  some documentation and an electronic version.  In the electronic
 	  version you wanted to include some extra content that was not to
 	  appear in the hard-copy.</para>
 
 	<para>Create a parameter entity, and set its value to
 	  <literal>INCLUDE</literal>.  Write your document, using marked
 	  sections to delimit content that should only appear in the
 	  electronic version.  In these marked sections use the parameter
 	  entity in place of the keyword.</para>
 
 	<para>When you want to produce the hard-copy version of the document,
 	  change the parameter entity's value to <literal>IGNORE</literal> and
 	  reprocess the document.</para>
 
 	<example>
 	  <title>Using a parameter entity to control a marked
 	    section</title>
 	  
 	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 &lt;!ENTITY % electronic.copy "INCLUDE">	     
 ]]&gt;
 
 ...
 
 &lt;![ %electronic.copy [
   This content should only appear in the electronic
   version of the document.
 ]]&gt;</programlisting>
 
 	  <para>When producing the hard-copy version, change the entity's
 	    definition to;</para>
 	  
 	  <programlisting>&lt;!ENTITY % electronic.copy "IGNORE"></programlisting>
 
 	  <para>On reprocessing the document, the marked sections that use
 	    <literal>%electronic.copy</literal> as their keyword will be
 	    ignored.</para>
 	</example>
       </sect3>
     </sect2>
 
     <sect2>
       <title>For you to do&hellip;</title>
 
       <procedure>
 	<step>
 	  <para>Create a new file, <filename>section.sgml</filename>, that
 	    contains the following;</para>
 
 	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 &lt;!ENTITY % text.output "INCLUDE">
 ]&gt;
 
 &lt;html>
   &lt;head>
     &lt;title>An example using marked sections&lt;/title>
   &lt;/head>
 
   &lt;body>	    
     &lt;p>This paragraph &lt;![ CDATA [contains many &lt;
       characters (&lt; &lt; &lt; &lt; &lt;) so it is easier
       to wrap it in a CDATA marked section ]]&gt;&lt;/p>
 
     &lt;![ IGNORE [
     &lt;p>This paragraph will definitely not be included in the
       output.&lt;/p>
     ]]&gt;
 
     &lt;![ <![ CDATA [%text.output]]> [
     &lt;p>This paragraph might appear in the output, or it
       might not.&lt;/p>
 
     &lt;p>Its appearance is controlled by the <![CDATA[%text.output]]>
       parameter entity.&lt;/p>	    
     ]]&gt;
   &lt;/body>
 &lt;/html></programlisting>	    
 	</step>
 
 	<step>
 	  <para>Normalise this file using &man.sgmlnorm.1; and examine the
 	    output.  Notice which paragraphs have appeared, which have
 	    disappeared, and what has happened to the content of the CDATA
 	    marked section.</para>
 	</step>
 
 	<step>
 	  <para>Change the definition of the <literal>text.output</literal>
 	    entity from <literal>INCLUDE</literal> to
 	    <literal>IGNORE</literal>.  Re-normalise the file, and examine the
 	    output to see what has changed.  </para>
 	</step>
       </procedure>
     </sect2>
   </sect1>
   
-  <sect1>
+  <sect1 id="sgml-primer-conclusion">
     <title>Conclusion</title>
     
     <para>That is the conclusion of this SGML primer.  For reasons of space
       and complexity several things have not been covered in depth (or at
       all).  However, the previous sections cover enough SGML for you to be
       able to follow the organisation of the FDP documentation.</para>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
index 245b4e3a2b..472578508d 100644
--- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
@@ -1,294 +1,294 @@
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="structure">
   <title>Structuring documents under <filename>doc/</filename></title>
 
   <para>The <filename>doc/</filename> tree is organised in a particular
     fashion, and the documents that are part of the FDP are in turn organised
     in a particular fashion.  The aim is to make it simple to add new
     documentation into the tree and:</para>
 
   <orderedlist>
     <listitem>
       <para>make it easy to automate converting the document to other formats</para>
     </listitem>
 
     <listitem>
       <para>promote consistency between the different documentation
 	organisations, to make it easier to switch between working on
 	different documents</para>
     </listitem>
 
     <listitem>
       <para>make it easy to decide where in the tree new documentation should
 	be placed</para>
     </listitem>
   </orderedlist>
 
   <para>In addition, the documentation tree has to accommodate documentation
     that could be in many different languages and in many different
     encodings.  It is important that the structure of the documentation tree
     does not enforce any particular defaults or cultural preferences.</para>
 
-  <sect1>
+  <sect1 id="structure-top">
     <title>The top level, <filename>doc/</filename></title>
 
     <para>There are two types of directory under <filename>doc/</filename>,
       each with very specific directory names and meanings.</para>
 
     <segmentedlist>
       <segtitle>Directory</segtitle>
 
       <segtitle>Meaning</segtitle>
 
       <seglistitem>
 	<seg><filename>share/</filename></seg>
 	
 	<seg>Contains files that are not specific to the various translations
 	  and encodings of the documentation.  Contains subdirectories to
 	  further categorise the information.  For example, the files that
 	  comprise the &man.make.1; infrastructure are in
 	  <filename>share/mk</filename>, while the additional SGML support
 	  files (such as the FreeBSD extended DocBook DTD) are in
 	  <filename>share/sgml</filename>.</seg>
       </seglistitem>
 
       <seglistitem>
 	<seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg>
 	
 	<seg>One directory exists for each available translation and encoding
 	  of the documentation, for example
 	  <filename>en_US.ISO8859-1/</filename> and
 	  <filename>zh_TW.Big5/</filename>.  The names are long, but by fully
 	  specifying the language and encoding we prevent any future headaches 
 	  should a translation team want to provide the documentation in the
 	  same language but in more than one encoding.  This also completely
 	  isolates us from any problems that might be caused by a switch to
 	  Unicode.</seg>
       </seglistitem>
     </segmentedlist>
   </sect1>
 
-  <sect1>
+  <sect1 id="structure-locale">
     <title>The
       <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> directories</title>
 
     <para>These directories contain the documents themselves.  The
 	documentation is split into up to three more categories at this
 	level, indicated by the different directory names.</para>
 
     <segmentedlist>
       <segtitle>Directory</segtitle>
 
       <segtitle>Contents</segtitle>
 
       <seglistitem>
 	<seg><filename>articles</filename></seg>
 	
 	<seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag> 
 	  (or equivalent).  Reasonably short, and broken up into sections.
 	  Normally only available as one HTML file.</seg>
       </seglistitem>
 	
       <seglistitem>
 	<seg><filename>books</filename></seg>
 	
 	<seg>Documentation marked up as a DocBook <sgmltag>book</sgmltag> (or
 	  equivalent).  Book length, and broken up into chapters.  Normally
 	  available as both one large HTML file (for people with fast
 	  connections, or who want to print it easily from a browser) and
 	  as a collection of linked, smaller files.</seg>
       </seglistitem>
 
       <seglistitem>
 	<seg><filename>man</filename></seg>
 	
 	<seg>For translations of the system manual pages.  This directory will 
 	  contain one or more
 	  <filename>man<replaceable>n</replaceable></filename> directories,
 	  corresponding to the sections that have been translated.</seg>
       </seglistitem>
     </segmentedlist>
 
     <para>Not every
       <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> directory will contain all of these directories.  It depends
       on how much translation has been accomplished by that translation
       team.</para>
   </sect1>
   
-  <sect1>
+  <sect1 id="structure-document">
     <title>Document specific information</title>
 
     <para>This section contains specific notes about particular documents
       managed by the FDP.</para>
 
     <sect2>
       <title>The Handbook</title>
 
       <subtitle><filename>books/handbook/</filename></subtitle>
 
       <para>The Handbook is written to comply with the FreeBSD DocBook
 	extended DTD.</para>
     
       <para>The Handbook is organised as a DocBook <sgmltag>book</sgmltag>.
 	It is then divided into <sgmltag>part</sgmltag>s, each of which may
 	contain several <sgmltag>chapter</sgmltag>s.
 	<sgmltag>chapter</sgmltag>s are further subdivided into sections
 	(<sgmltag>sect1</sgmltag>) and subsections (<sgmltag>sect2</sgmltag>,
 	<sgmltag>sect3</sgmltag>) and so on.</para>
   
       <sect3>
 	<title>Physical organisation</title>
 	
 	<para>There are a number of files and directories within the
 	  <filename>handbook</filename> directory.</para>
 
 	<note>
 	  <para>The Handbook's organisation may change over time, and this
 	    document may lag in detailing the organisational changes.  If you
 	    have any questions about how the Handbook is organised, please
 	    contact the &a.doc;.</para>
 	</note>
 	
 	<sect4>
 	  <title><filename>Makefile</filename></title>
 	  
 	  <para>The <filename>Makefile</filename> defines some variables that
 	    affect how the SGML source is converted to other formats, and
 	    lists the various source files that make up the Handbook.  It then 
 	    includes the standard <filename>doc.project.mk</filename> file, to 
 	    bring in the rest of the code that handles converting documents
 	    from one format to another.</para>
 	</sect4>
 
 	<sect4>
 	  <title><filename>book.sgml</filename></title>
 	  
 	  <para>This is the top level document in the Handbook.  It contains
 	    the Handbook's <link
 	      linkend="sgml-primer-doctype-declaration">DOCTYPE
 	      declaration</link>, as well as the elements that describe the
 	    Handbook's structure.</para>
 
 	  <para><filename>book.sgml</filename> uses <link
 	      linkend="sgml-primer-parameter-entities">parameter
 	      entities</link> to load in the files with the
 	    <filename>.ent</filename> extension. These files (described later)
 	    then define <link linkend="sgml-primer-general-entities">general
 	      entities</link> that are used throughout the rest of the
 	    Handbook.</para>
 	</sect4>
 
 	<sect4>
 	  <title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title>
 
 	  <para>Each chapter in the Handbook is stored in a file called
 	    <filename>chapter.sgml</filename> in a separate directory from the
 	    other chapters.  Each directory is named after the value of the
 	    <literal>id</literal> attribute on the <sgmltag>chapter</sgmltag>
 	    element.</para>
 
 	  <para>For example, if one of the chapter files contains:</para>
 	  
 	  <programlisting><![ CDATA [
 <chapter id="kernelconfiguration">
 ...
 </chapter>]]></programlisting>
 
 	  <para>then it will be called <filename>chapter.sgml</filename> in
 	    the <filename>kernelconfiguration</filename> directory.  In
 	    general, the entire contents of the chapter will be held in this
 	    file.</para>
       
 	  <para>When the HTML version of the Handbook is produced, this will
 	    yield <filename>kernelconfiguration.html</filename>.  This is
 	    because of the <literal>id</literal> value, and is not related to
 	    the name of the directory.</para>
 
 	  <para>In earlier versions of the Handbook the files were stored in
 	    the same directory as <filename>book.sgml</filename>, and named
 	    after the value of the <literal>id</literal> attribute on the
 	    file's <sgmltag>chapter</sgmltag> element.  Moving them into
 	    separate directories prepares for future plans for the Handbook.
 	    Specifically, it will soon be possible to include images in each
 	    chapter.  It makes more sense for each image to be stored in a
 	    directory with the text for the chapter than to try and keep the
 	    text for all the chapters, and all the images, in one large
 	    directory.  Namespace collisions would be inevitable, and it is
 	    easier to work with several directories with a few files in them
 	    than it is to work with one directory that has many files in
 	    it.</para>
 
 	  <para>A brief look will show that there are many directories with
 	    individual <filename>chapter.sgml</filename> files, including
 	    <filename>basics/chapter.sgml</filename>,
 	    <filename>introduction/chapter.sgml</filename>, and
 	    <filename>printing/chapter.sgml</filename>.</para>
 	  
 	  <important>
 	    <para>Chapters and/or directories should not be named in a fashion
 	      that reflects their ordering within the Handbook.  This ordering
 	      might change as the content within the Handbook is reorganised;
 	      this sort of reorganisation should not (generally) include the
 	      need to rename files (unless entire chapters are being promoted
 	      or demoted within the hierarchy).</para>
 	  </important>
 	  
 	  <para>Each <filename>chapter.sgml</filename> file will not be a
 	    complete SGML document.  In particular, they will not have their
 	    own DOCTYPE lines at the start of the files.</para>
       
 	  <para>This is unfortunate as
 	    it makes it impossible to treat these as generic SGML
 	    files and simply convert them to HTML, RTF, PS, and other
 	    formats in the same way the main Handbook is generated.  This
 	    <emphasis>would</emphasis> force you to rebuild the Handbook
 	    every time you want to see the effect a change has had on just
 	    one chapter.</para>
 	</sect4>
       </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/stylesheets/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml
index 795956d0ff..528fed3ed9 100644
--- a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml
@@ -1,102 +1,102 @@
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="stylesheets">
   <title>* Stylesheets</title>
     
   <para>SGML says nothing about how a document should be displayed to the
     user, or rendered on paper.  To do that, various languages have been
     developed to describe stylesheets, including DynaText, Panorama, SPICE,
     JSSS, FOSI, CSS, and DSSSL.</para>
   
   <para>For DocBook, we are using stylesheets written in DSSSL.  For HTML we
     are using CSS.</para>
 
-  <sect1>
+  <sect1 id="stylesheets-dsssl">
     <title>* DSSSL</title>
     
     <para>The Documentation Project uses a slightly customised version of
       Norm Walsh's modular DocBook stylesheets.</para>
     
     <para>These can be found in
       <filename role="package">textproc/dsssl-docbook-modular</filename>.</para>
 
     <para>The modified stylesheets are not in the ports system.  Instead they
       are part of the Documentation Project source repository, and can be
       found in <filename>doc/share/sgml/freebsd.dsl</filename>.  It is well
       commented, and pending completion of this section you are encouraged to
       examine that file to see how some of the available options in the
       standard stylesheets have been configured in order to customise the
       output for the FreeBSD Documentation Project.  That file also contains
       examples showing how to extend the elements that the stylesheet
       understands, which is how the FreeBSD specific elements have been
       formatted.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="stylesheets-css">
     <title>CSS</title>
 
     <para>Cascading Stylesheets (CSS) are a mechanism for attaching style
       information (font, weight, size, color, and so forth) to elements in an
       HTML document without abusing HTML to do so.</para>
 
     <sect2>
       <title>The Web site (HTML documents)</title>
 
       <para>The FreeBSD web site does not currently use CSS.  Unfortunately,
 	the look and feel is constructed using abuses of HTML of varying
 	degrees.  This should be fixed, and would be a good project for
 	someone looking to contribute to the documentation project.</para>
     </sect2>
 
     <sect2>
       <title>The DocBook documents</title>
 
       <para>The FreeBSD DSSSL stylesheets include a reference to a stylesheet,
 	<filename>docbook.css</filename>, which is expected to appear in the
 	same directory as the HTML files.  The project-wide CSS file is copied
 	from <filename>doc/share/misc/docbook.css</filename> when documents
 	are converted to HTML, and is installed automatically.</para>
     </sect2>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
index 5b696a288a..4e4bafdc97 100644
--- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
@@ -1,218 +1,218 @@
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="the-website">
   <title>The Website</title>
   
-  <sect1>
+  <sect1 id="the-website-prep">
     <title>Preparation</title>
     
     <para>Get 200MB free disk space. You will need the disk space for the
       SGML tools, a subset of the CVS tree, temporary build space and the
       installed web pages. If you already have installed the SGML tools and
       the CVS tree, you need only ~100MB free disk space.</para>
     
     <note>
       <para>Make sure your documentation ports are up to date!  When in
 	doubt, remove the old ports using &man.pkg.delete.1; command before
 	installing the port.  For example, we currently depend on
 	jade-1.2 and if you have installed jade-1.1, please do</para>
 
       <screen>&prompt.root; <userinput>pkg_delete jade-1.1</userinput></screen>
     </note>
 
     <para>Setup a CVS repository. You need the directories www, doc and
       ports in the CVS tree (plus the CVSROOT of course).  Please read the
       CVSup introduction <ulink
 	url="../handbook/synching.html#CVSUP">
 	http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/synching.html#CVSUP</ulink> how to
       mirror a CVS tree or parts of a CVS tree.</para>
     
     <para>The essential cvsup collections are: <literal>www</literal>,
       <literal>doc-all</literal>, <literal>cvs-base</literal>, and
       <literal>ports-base</literal>.</para>
     
     <para>These collections require ~100MB free disk space.</para>
     
     <para>A full CVS tree - including <literal>src</literal>,
       <literal>doc</literal>, <literal>www</literal>, and
       <literal>ports</literal> - is currently 650MB large.</para>
   </sect1>
   
-  <sect1>
+  <sect1 id="the-website-build">
     <title>Build the web pages from scratch</title>
     
     <procedure> 
       <step>
 	<para>Go to into a build directory with at least 60MB of free
 	  space.</para>
 	
 	<screen>&prompt.root; <userinput>mkdir /var/tmp/webbuild</userinput>
 &prompt.root; <userinput>cd /var/tmp/webbuild</userinput></screen>
       </step>
 
       <step>
 	<para>Checkout the SGML files from the CVS tree.</para>
 	
 	<screen>&prompt.root; <userinput>cvs -R co www doc</userinput></screen>
       </step>
       
       <step>
         <para>Change into the <filename>www</filename> directory, and
 	  run the &man.make.1; <maketarget>links</maketarget> target, to
 	  create the necessary symbolic links.</para>
 	
 	<screen>&prompt.root; <userinput>cd www</userinput>
 &prompt.root; <userinput>make links</userinput></screen>
       </step>
 
       <step>
 	<para>Change into the <filename>en</filename> directory, and run
 	  the &man.make.1; <maketarget>all</maketarget> target, to create
 	  the web pages.</para>
 	
 	<screen>&prompt.root; <userinput>cd en</userinput>
 &prompt.root; <userinput>make all</userinput></screen>
       </step>
     </procedure>
   </sect1>
   
-  <sect1>
+  <sect1 id="the-website-install">
     <title>Install the web pages into your web server</title>
     
     <procedure>
       <step>
 	<para>If you have moved out of the <filename>en</filename>
 	  directory, change back to it.</para>
 	
 	  <screen>&prompt.root; <userinput>cd <replaceable>path</replaceable>/www/en</userinput></screen>
       </step>
 
       <step>
 	<para>Run the &man.make.1; <maketarget>install</maketarget> target,
 	  setting the <makevar>DESTDIR</makevar> variable to the name of the 
 	  directory you want to install the files to.</para>
 	
 	<screen>&prompt.root; <userinput>make DESTDIR=<replaceable>/usr/local/www</replaceable> install</userinput></screen>
       </step>
 
       <step>
 	<para>If you have previously installed the web pages into the same
 	  directory the install process will not have deleted any old or
 	  outdated pages.  For example, if you build and install a new copy
 	  of the site every day, this command will find and delete all
 	  files that have not been updated in three days.</para>
 	
 	<screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -print0 | xargs -0 rm</userinput></screen>
       </step>
     </procedure>
   </sect1>
   
-  <sect1>
+  <sect1 id="the-website-env">
     <title>Environment variables</title>
     
     <variablelist>
       <varlistentry>
 	<term><envar>CVSROOT</envar></term>
 	
 	<listitem>
 	  <para>Location of the CVS tree. Essential.</para>
 	  
 	  <screen><userinput>&prompt.root; CVSROOT=/home/ncvs; export CVSROOT</userinput></screen>
 	</listitem>
       </varlistentry>
 	
       <varlistentry>
 	<term><makevar>ENGLISH_ONLY</makevar></term>
 	
 	<listitem>
 	  <para>If set and not empty, the makefiles will build and
 	    install only the English documents. All translations will be
 	    ignored. E.g.:</para>
 	  
 	  <screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen>
 
 	  <para>If you want unset the variable
 	    <makevar>ENGLISH_ONLY</makevar> and build all pages, including
 	    translations, set the variable <makevar>ENGLISH_ONLY</makevar>
 	    to an empty value</para>
 	  
 	  <screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term><makevar>WEB_ONLY</makevar></term>
 	
 	<listitem>
 	  <para>If set and not empty, the makefiles will build and install
 	    only the HTML pages from the www directory. All documents from
 	    the doc directory (Handbook, FAQ, Tutorials) will be ignored.
 	    E.g.:</para>
 	  
 	  <screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen>
 	</listitem>
       </varlistentry>
 	
       <varlistentry>
 	<term><makevar>NOPORTSCVS</makevar></term>
 	
 	<listitem>
 	  <para>If set, the makefiles will not checkout files from the ports
 	    cvs repository. Instead, it will copy the files from
 	    <filename>/usr/ports</filename> (or where the variable
 	    <envar>PORTSBASE</envar> points to).</para>
 	</listitem>
       </varlistentry>
     </variablelist>
     
     <para><envar>CVSROOT</envar> is an environment variable. You must set it
       on the command line or in your dot files (~/.profile).</para>
     
     <para><makevar>WEB_ONLY</makevar>, <makevar>ENGLISH_ONLY</makevar> and
       <makevar>NOPORTSCVS</makevar> are makefile variables. You can set the
       variables in <filename>/etc/make.conf</filename>,
       <filename>Makefile.inc</filename> or as environment variables on the
       command line or in your dot files.</para>
   </sect1>
 </chapter>
   
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
index 2fb91eb8ac..826dc5fa58 100644
--- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
@@ -1,286 +1,286 @@
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="tools">
   <title>Tools</title>
   
   <para>The FDP uses a number of different software tools to help
     manage the FreeBSD documentation, convert it to different output
     formats, and so on.  You will need to use these tools yourself if
     you are to work with the FreeBSD documentation.</para>                    
 
   <para>All these tools are available as FreeBSD Ports and Packages,
     greatly simplifying the work you have to do to install
     them.</para>                                                              
   
   <para>You will need to install these tools before you work through
     any of the examples in later chapters.  The actual usage of these
     tools is covered in later chapters.</para>     
 
   <tip>
     <title>Use <filename role="package">textproc/docproj</filename> if possible</title>
 
     <para>You can save yourself a lot of time if you install the
       <filename role="package">textproc/docproj</filename> port.  This is a
       <emphasis>meta-port</emphasis> which does not contain any software
       itself.  Instead, it depends on various other ports being installed
       correctly.  Installing this port <emphasis>should</emphasis>
       automatically download and install all of the packages listed in this
       chapter that you need.</para>
 
     <para>One of the packages that you might need is the JadeTeX macro set.
       In turn, this macro set requires TeX to be installed.  TeX is a large
       package, and you only need it if you want to produce Postscript or PDF
       output.</para>
 
     <para>To save yourself time and space you must specify whether or not you
       want JadeTeX (and therefore TeX) installed when you install this port.
       Either do;
 
       <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen>
 
       or
 
       <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
 
       as necessary.  Note that you can produce only HTML or ASCII
       text output if you install the tools using <makevar>JADETEX=no</makevar>.
       PostScript or PDF output require TeX.</para>
   </tip>
 
-  <sect1>
+  <sect1 id="tools-mandatory">
     <title>Mandatory tools</title>
 
     <sect2>
       <title>Software</title>
       
       <para>These programs are required before you can usefully work with the
 	FreeBSD documentation, and they will allow you to convert the
 	documentation to HTML, plain text, and RTF formats.  They are all
 	included in <filename role="package">textproc/docproj</filename>.</para>
       
       <variablelist>
 	<varlistentry>
 	  <term><application>SP</application>
 	    (<filename role="package">textproc/sp</filename>)</term>
 	  
 	  <listitem>
 	    <para>A suite of applications, including a validating SGML parser,
 	      and an SGML normaliser.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><application>Jade</application>
 	    (<filename role="package">textproc/jade</filename>)</term>
 	  
 	  <listitem>
 	    <para>A DSSSL implementation.  Used for converting marked up
 	      documents to other formats, including HTML and TeX.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><application>Tidy</application>
 	    (<filename role="package">www/tidy</filename>)</term>
 	  
 	  <listitem>
 	    <para>An HTML 'pretty printer', used to reformat some of the
 	      automatically generated HTML so that it is easier to
 	      follow.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><application>Links</application>
 	    (<filename role="package">www/links</filename>)</term>
 	  
 	  <listitem>
 	    <para>A text-mode WWW browser that can also convert
 	      HTML files to plain text.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><application>peps</application>
 	    (<filename role="package">graphics/peps</filename>)</term>
 	  
 	  <listitem>
 	    <para>Some of the documentation includes images, some of which are
 	      stored as EPS files.  These must be converted to PNG before most
 	      web browsers will display them.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2>
       <title>DTDs and Entities</title>
 
       <para>These are the DTDs and entity sets used by the FDP.  They need to
 	be installed before you can work with any of the documentation.</para>
       
       <variablelist>
 	<varlistentry>
 	  <term>HTML DTD (<filename role="package">textproc/html</filename>)</term>
 	  
 	  <listitem>
 	    <para>HTML is the markup language of choice for the World Wide
 	      Web, and is used throughout the FreeBSD web site.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term>DocBook DTD (<filename role="package">textproc/docbook</filename>)</term>
 	  
 	  <listitem>
 	    <para>DocBook is designed for marking up technical documentation.
 	      All the FreeBSD documentation is written in DocBook.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term>ISO 8879 entities
 	    (<filename role="package">textproc/iso8879</filename>)</term>
 	  
 	  <listitem>
 	    <para>19 of the ISO 8879:1986 character entity sets used by many
 	      DTDs.  Includes named mathematical symbols, additional
 	      characters in the 'Latin' character set (accents, diacriticals,
 	      and so on), and Greek symbols.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2>
       <title>Stylesheets</title>
 
       <para>The stylesheets are used when converting and formatting the
 	documentation for display on screen, printing, and so on.</para>
       
       <variablelist>
 	<varlistentry>
 	  <term>Modular DocBook Stylesheets
 	    (<filename role="package">textproc/dsssl-docbook-modular</filename>)</term>
 	  
 	  <listitem>
 	    <para>The Modular DocBook Stylesheets are used when converting
 	      documentation marked up in DocBook to other formats, such as
 	      HTML or RTF.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="tools-optional">
     <title>Optional tools</title>
 
     <para>You do not need to have any of the following installed.  However,
       you may find it easier to work with the documentation if you do, and
       they may give you more flexibility in the output formats that can be
       generated.</para>
 
     <sect2>
       <title>Software</title>
       
       <variablelist>
 	<varlistentry>
 	  <term><application>JadeTeX</application> and
 	    <application>teTeX</application>
 	    (<filename role="package">print/jadetex</filename> and
 	    <filename role="package">print/teTeX</filename>)</term>
 	  
 	  <listitem>
 	    <para><application>Jade</application> and
 	      <application>teTeX</application> are used to convert DocBook
 	      documents to DVI, Postscript, and PDF formats.  The
 	      <application>JadeTeX</application> macros are needed in order to
 	      do this.</para>
 
 	    <para>If you do not intend to convert your documentation to one of
 	      these formats (i.e., HTML, plain text, and RTF are sufficient)
 	      then you do not need to install
 	      <application>JadeTeX</application> and
 	      <application>teTeX</application>.  This can be a significant
 	      space and time saver, as <application>teTeX</application> is
 	      over 30MB in size.</para>
 
 	    <important>
 	      <para>If you decide to install
 		<application>JadeTeX</application> and
 		<application>teTeX</application> then you will need to
 		configure <application>teTeX</application> after
 		<application>JadeTeX</application> has been installed.
 		<filename>print/jadetex/pkg-message</filename> contains
 		detailed instructions explaining what you need to do.</para>
 	    </important>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><application>Emacs</application> or
 	    <application>XEmacs</application> 
 	    (<filename role="package">editors/emacs</filename> or
 	    <filename role="package">editors/xemacs</filename>)</term>
 	  
 	  <listitem>
 	    <para>Both these editors include a special mode for editing
 	      documents marked up according to an SGML DTD.  This mode
 	      includes commands to reduce the amount of typing you need, and
 	      help reduce the possibility of errors.</para>
 
 	    <para>You do not need to use them; any text editor can be used to
 	      edit marked up documents.  You may find they make you more
 	      efficient.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <para>If anyone has recommendations for other software that is useful
 	when manipulating SGML documents, please let &a.nik; know, so they
 	can be added to this list.</para>
     </sect2>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
index 454e290dae..61caa8d76c 100644
--- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
@@ -1,440 +1,440 @@
 <!-- Copyright (c) 1998 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
      $FreeBSD$
 -->
 
 <chapter id="writing-style">
   <title>Writing style</title>
   
   <para>In order to promote consistency between the myriad authors of the
     FreeBSD documentation, some guidelines have been drawn up for authors to
     follow.</para>
   
   <variablelist>
     <varlistentry>
       <term>Use American English spelling</term>
 
       <listitem>
 	<para>There are several variants of English, with different spellings
 	  for the same word.  Where spellings differ, use the American English
 	  variant. <quote>color</quote>, not <quote>colour</quote>,
 	  <quote>rationalize</quote>, not <quote>rationalise</quote>, and so
 	  on.</para>
       </listitem>
     </varlistentry>
 
     <varlistentry>
       <term>Do not use contractions</term>
       
       <listitem>
 	<para>Do not use contractions.  Always spell the phrase out in full.
 	  <quote>Don't use contractions</quote> would be wrong.</para>
 
 	<para>Avoiding contractions makes for a more formal tone, is more
 	  precise, and is slightly easier for translators.</para>
       </listitem>
     </varlistentry>
     
     <varlistentry>
       <term>Use the serial comma</term>
       
       <listitem>
 	<para>In a list of items within a paragraph, separate each item from
 	  the others with a comma.  Separate the last item from the others with
 	  a comma and the word <quote>and</quote>.</para>
 
 	<para>For example, look at the following:</para>
 	
 	<blockquote>
 	  <para>This is a list of one, two and three items.</para>
 	</blockquote>
 	
 	<para>Is this a list of three items, <quote>one</quote>,
 	  <quote>two</quote>, and <quote>three</quote>, or a list of two items,
 	  <quote>one</quote> and <quote>two and three</quote>?</para>
 	
 	<para>It is better to be explicit and include a serial comma:</para>
 	
 	<blockquote>
 	  <para>This is a list of one, two, and three items.</para>
 	</blockquote>
       </listitem>
     </varlistentry>
     
     <varlistentry>
       <term>Avoid redundant phrases</term>
       
       <listitem>
 	<para>Try not to use redundant phrases.  In particular, <quote>the
 	  command</quote>, <quote>the file</quote>, and <quote>man
 	  command</quote> are probably redundant.</para>
 
 	<para>These two examples show this for commands.  The second example
 	  is preferred.</para>
 	
 	<informalexample>
 	  <para>Use the command <command>cvsup</command> to update your
 	    sources</para>
 	</informalexample>
       
 	<informalexample>
 	  <para>Use <command>cvsup</command> to update your sources</para>
 	</informalexample>
 	
 	<para>These two examples show this for filenames.  The second example
 	  is preferred.</para>
 	
 	<informalexample>
 	  <para>&hellip; in the filename
 	    <filename>/etc/rc.local</filename>&hellip;</para>
 	</informalexample>
 	
 	<informalexample>
 	  <para>&hellip; in
 	    <filename>/etc/rc.local</filename>&hellip;</para>
 	</informalexample>
 	
 	<para>These two examples show this for manual references.  The second
 	  example is preferred (the second example uses
 	  <sgmltag>citerefentry</sgmltag>).</para>
 	
 	<informalexample>
 	  <para>See <command>man csh</command> for more
 	    information.</para>
 	</informalexample>
 	
 	<informalexample>
 	  <para>See &man.csh.1;</para>
 	</informalexample>
       </listitem>
     </varlistentry>
     <varlistentry>
       <term>Two spaces at the end of sentences</term>
 
       <listitem>
 	<para>Always use two spaces at the end of sentences, as this
 	  improves readability, and eases use of tools such as
 	  <application>Emacs</application>.</para>
 
 	<para>While it may be argued that a capital letter following
 	  a period denotes a new sentence, this is not the case, especially
 	  in name usage.  <quote>Jordan K. Hubbard</quote> is a good
 	  example; it has a capital <literal>H</literal> following a
 	  period and a space, and there certainly is not a new sentence
 	  there.</para>
       </listitem>
     </varlistentry>
   </variablelist>
 
   <para>For more information about writing style, see <ulink
       url="http://www.bartleby.com/141/">Elements of
       Style</ulink>, by William Strunk.</para>
 
-  <sect1>
+  <sect1 id="writing-style-guide">
     <title>Style guide</title>
 
     <para>To keep the source for the Handbook consistent when many different
       people are editing it, please follow these style conventions.</para>
 
     <sect2>
       <title>Letter case</title>
 
       <para>Tags are entered in lower case, <literal>&lt;para&gt;</literal>,
 	<emphasis>not</emphasis> <literal>&lt;PARA&gt;</literal>.</para>
 
       <para>Text that appears in SGML contexts is generally written in upper
 	case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and
 	<literal>&lt;!DOCTYPE&hellip;&gt;</literal>, <emphasis>not</emphasis>
 	<literal>&lt;!entity&hellip;&gt;</literal> and
 	<literal>&lt;!doctype&hellip;&gt;</literal>.</para>
     </sect2>
 
     <sect2>
       <title>Indentation</title>
 
       <para>Each file starts with indentation set at column 0,
 	<emphasis>regardless</emphasis> of the indentation level of the file
 	which might contain this one.</para>
 
       <para>Every start tag increases the indentation level by 2 spaces, and
 	every end tag decreases the indentation level by 2 spaces.  Replace
 	as many leading spaces with tabs as appropriate.  Do not use
 	spaces in front of tabs, and do not add extraneous whitespace at the
 	end of a line.  Content
 	within elements should be indented by two spaces if the content runs
 	over more than one line.</para>
 
       <para>For example, the source for this section looks something
 	like:</para>
 
       <programlisting><![ CDATA [+--- This is column 0
 V
 <chapter>
   <title>...</title>
 
   <sect1>
     <title>...</title>
 
     <sect2>
       <title>Indentation</title>
 
       <para>Each file starts with indentation set at column 0,
         <emphasis>regardless</emphasis> of the indentation level of the file
         which might contain this one.</para>
 
       <para>Every start tag increases the indentation level by 2 spaces, and
         every end tag decreases the indentation level by 2 spaces.  Content
         within elements should be indented by two spaces if the content runs
         over more than one line.</para>
 
       ...	
     </sect2>
   </sect1>
 </chapter>]]></programlisting>
 
       <para>If you use <application>Emacs</application> or
 	<application>XEmacs</application> to edit the files then
 	<literal>sgml-mode</literal> should be loaded automatically, and the
 	<application>Emacs</application> local variables at the bottom of each file should enforce these
 	styles.</para>
     </sect2>
 
     <sect2>
       <title>Tag style</title>
 
       <sect3>
 	<title>Tag spacing</title>
 	
 	<para>Tags that start at the same indent as a previous tag
 	  should be separated by a blank line, and those that are not
 	  at the same indent as a previous tag should not:</para>
 
 	<informalexample>
 	  <programlisting><![ CDATA [<article>
   <articleinfo>
     <title>NIS</title>
 
     <pubdate>October 1999</pubdata>
 
     <abstract>
       <para>...
 	...
 	...</para>
     </abstract>
   </articleinfo>
 
   <sect1>
     <title>...</title>
 
     <para>...</para>
   </sect1>
 
   <sect1>
     <title>...</title>
 
     <para>...</para>
   </sect1>
 </article>]]></programlisting>
 	</informalexample>
       </sect3>
 
       <sect3>
 	<title>Separating tags</title>
 
 	<para>Tags like <sgmltag>itemizedlist</sgmltag> which will
 	  always have further tags inside them, and in fact do not take
 	  character data themselves, are always on a line by
 	  themselves.</para>
 
 	<para>Tags like <sgmltag>para</sgmltag> and
 	  <sgmltag>term</sgmltag> do not need other tags to contain
 	  normal character data, and their contents begin immediately
 	  after the tag, <emphasis>on the same line</emphasis>.</para>
 
 	<para>The same applies to when these two types of tags
 	  close.</para>
 
 	<para>This leads to an obvious problem when mixing these
 	  tags.</para>
 
 	<para>When a starting tag which cannot contain character data
 	  directly follows a tag of the type that requires other tags
 	  within it to use character data, they are on separate lines.
 	  The second tag should be properly indented.</para>
 
 	<para>When a tag which can contain character data closes
 	  directly after a tag which cannot contain character data
 	  closes, they co-exist on the same line.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>White space changes</title>
 
       <para>When committing changes, <emphasis>do not commit changes to the
 	  content at the same time as changes to the
 	  formatting</emphasis>.</para>
       
       <para>This is so that the teams that convert the Handbook to other
 	languages can quickly see what content has actually changed in your
 	commit, without having to decide whether a line has changed because of
 	the content, or just because it has been refilled.</para>
 
       <para>For example, if you have added two sentences to a paragraph, such
 	that the line lengths on the paragraph now go over 80 columns, first
 	commit your change with the too-long line lengths.  Then fix the line
 	wrapping, and commit this second change.  In the commit message for
 	the second change, be sure to indicate that this is a whitespace-only
 	change, and that the translation team can ignore it.</para>
     </sect2>
 
     <sect2>
       <title>Nonbreaking space</title>
 
       <para>Avoid line breaks in places where they look ugly
 	or make it difficult to follow a sentence.  Line breaks depend
 	on the width of the chosen output medium.  In particular, viewing
 	the HTML documentation with a text browser can lead to badly
 	formatted paragraphs like the next one:</para>
 
       <literallayout class="monospaced">Data capacity ranges from 40 MB to 15
 GB.  Hardware compression &hellip;</literallayout>
 
       <para>The general entity <literal>&amp;nbsp;</literal> prohibits
 	line breaks between parts belonging together.  Use nonbreaking
 	spaces in the following places:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>between numbers and units:</para>
 	  <programlisting><![ CDATA [57600&nbsp;bps]]></programlisting>
 	</listitem>
 
 	<listitem>
 	  <para>between program names and version numbers:</para>
 	  <programlisting><![ CDATA [FreeBSD&nbsp;4.7]]></programlisting>
 	</listitem>
 
 	<listitem>
 	  <para>between multiword names (use with caution when applying this
 	    to more than 3-4 word names like <quote>The FreeBSD Brazilian
 	      Portuguese Documentation Project</quote>):</para>
 	  <programlisting><![ CDATA [Sun&nbsp;Microsystems]]></programlisting>  
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="writing-style-word-list">
     <title>Word list</title>
 
     <para>The following is a small list of words spelled the way they
       should be used in the FreeBSD Documentation Project.  If the
       word you are looking for is not in this list, then please
       consult the <ulink
       url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly
       word list</ulink>.</para>
 
     <itemizedlist>
       <listitem>
 	<para>2.2.X</para>
       </listitem>
 
       <listitem>
 	<para>4.X-STABLE</para>
       </listitem>
 
       <listitem>
 	<para>CDROM</para>
       </listitem>
 
       <listitem>
 	<para>DoS <emphasis>(Denial of Service)</emphasis> </para>
       </listitem>
 
       <listitem>
 	<para>FreeBSD Ports Collection</para>
       </listitem>
 
       <listitem>
 	<para>Internet</para>
       </listitem>
 
       <listitem>
 	<para>MHz</para>
       </listitem>
 
       <listitem>
 	<para>Unix</para>
       </listitem>
 
       <listitem>
 	<para>email</para>
       </listitem>
 
       <listitem>
 	<para>file system</para>
       </listitem>
 
       <listitem>
 	<para>manual page(s)</para>
       </listitem>
 
       <listitem>
 	<para>mail server</para>
       </listitem>
 
       <listitem>
 	<para>name server</para>
       </listitem>
 
       <listitem>
 	<para>ports collection</para>
       </listitem>
 
       <listitem>
 	<para>web server</para>
       </listitem>
     </itemizedlist>
 
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
index 81b6a63f55..72a404302d 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,6571 +1,6571 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="advanced-networking">
   <title>Advanced Networking</title>
 
-  <sect1>
+  <sect1 id="advanced-networking-synopsis">
     <title>Synopsis</title>
 
     <para>This chapter will cover some of the more frequently used network
       services on Unix systems.  We will cover how to define, setup, test and
       maintain all of the network services that FreeBSD utilizes.  In addition,
       there have been example configuration files included throughout this
       chapter for you to benefit from.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The basics of gateways and routes.</para>
       </listitem>
 
       <listitem>
 	<para>How to make FreeBSD act as a bridge.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup a network filesystem.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup network booting on a diskless machine.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup a network information server for sharing user
 	  accounts.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup automatic network settings using DHCP.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup a domain name server.</para>
       </listitem>
 
       <listitem>
 	<para>How to synchronize the time and date, and setup a
 	  time server, with the NTP protocol.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup network address translation.</para>
       </listitem>
 
       <listitem>
 	<para>How to manage the <command>inetd</command> daemon.</para>
       </listitem>
 
       <listitem>
 	<para>How to connect two computers via PLIP.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup IPv6 on a FreeBSD machine.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Understand the basics of the <filename>/etc/rc</filename> scripts.</para>
       </listitem>
 
       <listitem>
 	<para>Be familiar with basic network terminology.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="routing">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Coranth</firstname>
       	  <surname>Gryphon</surname>
 	  <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Gateways and Routes</title>
 
     <indexterm><primary>routing</primary></indexterm>
     <indexterm><primary>gateway</primary></indexterm>
     <indexterm><primary>subnet</primary></indexterm>
     <para>For one machine to be able to find another over a network, there
       must be a
       mechanism in place to describe how to get from one to the other.  This is
       called <firstterm>routing</firstterm>.  A <quote>route</quote> is a defined pair of addresses: a
       <quote>destination</quote> and a <quote>gateway</quote>.  The pair
       indicates that if you are trying to get to this
       <emphasis>destination</emphasis>, communicate through this
       <emphasis>gateway</emphasis>.  There are three types of destinations:
       individual hosts, subnets, and <quote>default</quote>.  The
       <quote>default route</quote> is used if none of the other routes apply.
       We will talk a little bit more about default routes later on.  There are
       also three types of gateways: individual hosts, interfaces (also called
       <quote>links</quote>), and Ethernet hardware addresses (MAC addresses).
     </para>
 
     <sect2>
       <title>An Example</title>
 
       <para>To illustrate different aspects of routing, we will use the
 	following example from <command>netstat</command>:</para>
 
       <screen>&prompt.user; <userinput>netstat -r</userinput>
 Routing tables
 
 Destination      Gateway            Flags     Refs     Use     Netif Expire
 
 default          outside-gw         UGSc       37      418      ppp0
 localhost        localhost          UH          0      181       lo0
 test0            0:e0:b5:36:cf:4f   UHLW        5    63288       ed0     77
 10.20.30.255     link#1             UHLW        1     2421
 example.com      link#1             UC          0        0
 host1            0:e0:a8:37:8:1e    UHLW        3     4601       lo0
 host2            0:e0:a8:37:8:1e    UHLW        0        5       lo0 =>
 host2.example.com link#1             UC          0        0
 224              link#1             UC          0        0</screen>
 
       <indexterm><primary>default route</primary></indexterm>
       <para>The first two lines specify the default route (which we
 	will cover in the <link linkend="routing-default">next
 	  section</link>) and the <hostid>localhost</hostid> route.</para>
 
       <indexterm><primary>loopback device</primary></indexterm>
       <para>The interface (<literal>Netif</literal> column) that this routing table specifies
 	to use for <literal>localhost</literal> is
 	<devicename>lo0</devicename>, also known as the loopback device.  This
 	says to keep all traffic for this destination internal, rather than
 	sending it out over the LAN, since it will only end up back where it
 	started.</para>
 
       <indexterm>
         <primary>Ethernet</primary>
         <secondary>MAC address</secondary>
       </indexterm>
       <para>The next thing that stands out are the addresses beginning
 	with <hostid role="mac">0:e0:</hostid>.  These are Ethernet
 	hardware addresses, which are also known as MAC addresses.
 	FreeBSD will automatically identify any hosts
 	(<hostid>test0</hostid> in the example) on the local Ethernet and add
 	a route for that host, directly to it over the Ethernet interface,
 	<devicename>ed0</devicename>.  There is also a timeout
 	(<literal>Expire</literal> column) associated with this type of route,
 	which is used if we fail to hear from the host in a specific amount of
 	time.  When this happens, the route to this host will be automatically deleted.  These
 	hosts are identified using a mechanism known as RIP (Routing
 	Information Protocol), which figures out routes to local hosts based
 	upon a shortest path determination.</para>
 
       <indexterm><primary>subnet</primary></indexterm>
       <para>FreeBSD will also add subnet routes for the local subnet (<hostid
 	  role="ipaddr">10.20.30.255</hostid> is the broadcast address for the
 	subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid
 	  role="domainname">example.com</hostid> is the domain name associated
 	with that subnet).  The designation <literal>link#1</literal> refers
 	to the first Ethernet card in the machine.  You will notice no
 	additional interface is specified for those.</para>
 
       <para>Both of these groups (local network hosts and local subnets) have
 	their routes automatically configured by a daemon called
 	<application>routed</application>.  If this is not run, then only
 	routes which are statically defined (i.e. entered explicitly) will
 	exist.</para>
 
       <para>The <literal>host1</literal> line refers to our host, which it
 	knows by Ethernet address.  Since we are the sending host, FreeBSD
 	knows to use the loopback interface (<devicename>lo0</devicename>)
 	rather than sending it out over the Ethernet interface.</para>
 
       <para>The two <literal>host2</literal> lines are an example of what
 	happens when we use an &man.ifconfig.8; alias (see the section on 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 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 routes.</para>
 
       <para>The final line (destination subnet <literal>224</literal>) deals
 	with multicasting, which will be covered in another section.</para>
 
       <para>Finally, various attributes of each route can be seen in the
 	<literal>Flags</literal> column.  Below is a short table of some of these
 	flags and their meanings:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <tbody>
 	    <row>
 	      <entry>U</entry>
 	      <entry>Up: The route is active.</entry>
 	    </row>
 
 	    <row>
 	      <entry>H</entry>
 	      <entry>Host: The route destination is a single host.</entry>
 	    </row>
 
 	    <row>
 	      <entry>G</entry>
 	      <entry>Gateway: Send anything for this destination on to this
 		remote system, which will figure out from there where to send
 		it.</entry>
 	    </row>
 
 	    <row>
 	      <entry>S</entry>
 	      <entry>Static: This route was configured manually, not
 		automatically generated by the system.</entry>
 	    </row>
 
 	    <row>
 	      <entry>C</entry>
 	      <entry>Clone: Generates a new route based upon this route for
 		machines we connect to.  This type of route is normally used
 		for local networks.</entry>
 	    </row>
 
 	    <row>
 	      <entry>W</entry>
 	      <entry>WasCloned: Indicated a route that was auto-configured
 		based upon a local area network (Clone) route.</entry>
 	    </row>
 
 	    <row>
 	      <entry>L</entry>
 	      <entry>Link: Route involves references to Ethernet
 		hardware.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
 
     <sect2 id="routing-default">
       <title>Default Routes</title>
 
       <indexterm><primary>default route</primary></indexterm>
       <para>When the local system needs to make a connection to a remote host,
 	it checks the routing table to determine if a known path exists.  If
 	the remote host falls into a subnet that we know how to reach (Cloned
 	routes), then the system checks to see if it can connect along that
 	interface.</para>
 
       <para>If all known paths fail, the system has one last option: the
 	<quote>default</quote> route.  This route is a special type of gateway
 	route (usually the only one present in the system), and is always
 	marked with a <literal>c</literal> in the flags field.  For hosts on a
 	local area network, this gateway is set to whatever machine has a
 	direct connection to the outside world (whether via PPP link,
 	DSL, cable modem, T1, or another network interface).</para>
 
       <para>If you are configuring the default route for a machine which
 	itself is functioning as the gateway to the outside world, then the
 	default route will be the gateway machine at your Internet Service
 	Provider's (ISP) site.</para>
 
       <para>Let us look at an example of default routes.  This is a common
 	configuration:</para>
 
       <literallayout>
 [Local2]  &lt;--ether--&gt;  [Local1]  &lt;--PPP--&gt; [ISP-Serv]  &lt;--ether--&gt;  [T1-GW]
       </literallayout>
 
       <para>The hosts <hostid>Local1</hostid> and
 	<hostid>Local2</hostid> are at your site.
 	<hostid>Local1</hostid> is connected to an ISP via a dial up
 	PPP connection.  This PPP server computer is connected through
 	a local area network to another gateway computer through an
 	external interface to the ISPs Internet feed.</para>
 
       <para>The default routes for each of your machines will be:</para>
 
       <informaltable frame="none">
 	<tgroup cols="3">
 	  <thead>
 	    <row>
 	      <entry>Host</entry>
 	      <entry>Default Gateway</entry>
 	      <entry>Interface</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>Local2</entry>
 	      <entry>Local1</entry>
 	      <entry>Ethernet</entry>
 	    </row>
 
 	    <row>
 	      <entry>Local1</entry>
 	      <entry>T1-GW</entry>
 	      <entry>PPP</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>A common question is <quote>Why (or how) would we set
 	the <hostid>T1-GW</hostid> to be the default gateway for
 	<hostid>Local1</hostid>, 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 <hostid>T1-GW</hostid>
 	machine, so there is no need for the intermediate step
 	of sending traffic to the ISP server.</para>
 
       <para>As a final note, it is common to use the address <hostid
 	  role="ipaddr">X.X.X.1</hostid> as the gateway address for your local
 	network.  So (using the same example), if your local class-C address
 	space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was
 	using <hostid role="ipaddr">10.9.9</hostid> then the default routes
 	would be:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Host</entry>
 	      <entry>Default Route</entry>
 	    </row>
 	  </thead>
 	  <tbody>
 	    <row>
 	      <entry>Local2 (10.20.30.2)</entry>
 	      <entry>Local1 (10.20.30.1)</entry>
 	    </row>
 	    <row>
 	      <entry>Local1 (10.20.30.1, 10.9.9.30)</entry>
 	      <entry>T1-GW (10.9.9.1)</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
 
     <sect2>
       <title>Dual Homed Hosts</title>
       <indexterm><primary>dual homed hosts</primary></indexterm>
       <para>There is one other type of configuration that we should cover, and
 	that is a host that sits on two different networks.  Technically, any
 	machine functioning as a gateway (in the example above, using a PPP
 	connection) counts as a dual-homed host.  But the term is really only
 	used to refer to a machine that sits on two local-area
 	networks.</para>
 
       <para>In one case, the machine has two Ethernet cards, each having an
 	address on the separate subnets.  Alternately, the machine may only
 	have one Ethernet card, and be using &man.ifconfig.8; aliasing.  The former is
 	used if two physically separate Ethernet networks are in use, the
 	latter if there is one physical network segment, but two logically
 	separate subnets.</para>
 
       <para>Either way, routing tables are set up so that each subnet knows
 	that this machine is the defined gateway (inbound route) to the other
 	subnet.  This configuration, with the machine acting as a router
 	between the two subnets, is often used when we need to implement
 	packet filtering or firewall security in either or both
 	directions.</para>
 
       <para>If you want this machine to actually forward packets
         between the two interfaces, you need to tell FreeBSD to enable
         this ability.</para>
     </sect2>
 
     <sect2 id="dedicated-router">
       <title>Building a Router</title>
 
       <indexterm><primary>router</primary></indexterm>
 
       <para>A network router is simply a system that forwards packets
 	from one interface to another.  Internet standards and good
 	engineering practice prevent the FreeBSD Project from enabling
 	this by default in FreeBSD.  You can enable this feature by
 	changing the following variable to <literal>YES</literal> in
 	&man.rc.conf.5;:</para>
 
       <programlisting>gateway_enable=YES          # Set to YES if this host will be a gateway</programlisting>
 
       <para>This option will set the &man.sysctl.8; variable
 	<varname>net.inet.ip.forwarding</varname> to
 	<literal>1</literal>.  If you should need to stop routing
 	temporarily, you can reset this to <literal>0</literal> temporarily.</para>
 
       <para>Your new router will need routes to know where to send the
 	traffic.  If your network is simple enough you can use static
 	routes.  FreeBSD also comes with the standard BSD routing
 	daemon &man.routed.8;, which speaks RIP (both version 1 and
 	version 2) and IRDP.  For more complex situations you may want
 	to try <filename role="package">net/gated</filename>.</para>
 
       <para>Even when FreeBSD is configured in this way, it does not
 	completely comply with the Internet standard requirements for
 	routers.  It comes close enough for ordinary use,
 	however.</para>
     </sect2>
 
     <sect2>
       <title>Routing Propagation</title>
       <indexterm><primary>routing propagation</primary></indexterm>
       <para>We have already talked about how we define our routes to the
 	outside world, but not about how the outside world finds us.</para>
 
       <para>We already know that routing tables can be set up so that all
 	traffic for a particular address space (in our examples, a class-C
 	subnet) can be sent to a particular host on that network, which will
 	forward the packets inbound.</para>
 
       <para>When you get an address space assigned to your site, your service
 	provider will set up their routing tables so that all traffic for your
 	subnet will be sent down your PPP link to your site.  But how do sites
 	across the country know to send to your ISP?</para>
 
       <para>There is a system (much like the distributed DNS information) that
 	keeps track of all assigned address-spaces, and defines their point of
 	connection to the Internet Backbone.  The <quote>Backbone</quote> are
 	the main trunk lines that carry Internet traffic across the country,
 	and around the world.  Each backbone machine has a copy of a master
 	set of tables, which direct traffic for a particular network to a
 	specific backbone carrier, and from there down the chain of service
 	providers until it reaches your network.</para>
 
       <para>It is the task of your service provider to advertise to the
 	backbone sites that they are the point of connection (and thus the
 	path inward) for your site.  This is known as route
 	propagation.</para>
     </sect2>
 
     <sect2>
       <title>Troubleshooting</title>
       <indexterm>
         <primary><command>traceroute</command></primary>
       </indexterm>
       <para>Sometimes, there is a problem with routing propagation, and some
 	sites are unable to connect to you.  Perhaps the most useful command
 	for trying to figure out where 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="wireless">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Eric</firstname>
           <surname>Anderson</surname>
           <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Wireless</title>
 
    <sect2>
       <title>Introduction</title>
       <para>It can be very useful to be able to use a computer without the 
       annoyance of having a network cable attached at all times.  FreeBSD can
       be used as a wireless client, and even as a wireless <quote>access 
       point</quote>.</para>
    </sect2>
 
    <sect2>
      <title>Wireless background</title>
      <para>There are two different ways to configure 802.11 wireless devices:
       BSS and IBSS.</para>
 
      <sect3>
        <title>BSS mode</title>
        <para>BSS mode is the mode that typically is used.  BSS mode is
         also called infrastructure mode.  In this mode, a number of
         wireless access points are connected to a wired network.  Each
         wireless network has its own name.  This name is called the
         SSID of the network.</para>
 
        <para>Wireless clients connect to these wireless access
         points. The IEEE 802.11 standard defins the protocol that
         wireless networks use to connect.  A wireless client can be
         tied to a specific network, when a SSID is set.  A wireless
         client can also attach to any network by not excplicitly
         setting a SSID.</para>
      </sect3>
 
      <sect3>
        <title>IBSS Mode</title>
        <para>IBSS mode, also called ad-hoc mode, is designed for point
          to point connections.  There are actually two types of ad-hoc
          mode.  One is IBSS mode, also called ad-hoc or IEEE ad-hoc
          mode.  This mode is defined by the IEEE 802.11 standards.
          The second is called demo ad-hoc mode or Lucent ad-hoc mode
          (and sometimes confusingly ad-hoc mode).  This is the old,
          pre-802.11 ad-hoc mode and should only be used for legacy
 	 installations.</para>
      </sect3>
    </sect2>
 
    <sect2>
      <title>Infrastructure mode</title>
      <sect3>
        <title>Access Points</title>
        <para>Access points are wireless networking devices that allow one or more wireless 
         clients to use the device as a central hub.  When using an access point, all 
         clients communicate through the access point.  Multiple access points are often 
         used to cover a complete area such as a house, business, or park with a wireless 
         network.</para>
 
        <para>Access points typically have multiple network connections: the wireless card,
        and one or more wired ethernet adapters for connection to the rest of the network.
        </para>
 
        <para>Access points can either be purchased prebuilt, or you can build 
         your own with FreeBSD and a supported wireless card.  Several vendors make 
         wireless access points and wireless cards with various features.</para>
      </sect3>
 
      <sect3>
        <title>Building a FreeBSD Access Point</title>
        
        <sect4><title>Requirements</title>
          <para>In order to set up a wireless access point with FreeBSD, you need to have 
           a compatible wireless card.  Currently, only cards with the Prism chipset are 
           supported. You will also need a wired network card that is supported by FreeBSD 
           (this should not be difficult to find, FreeBSD supports a lot of different 
           devices).  For this guide, we will assume you want to &man.bridge.4; all traffic between 
           the wireless device and the network attached to the wired network card.</para>
 
 	 <para>The hostap functionality that FreeBSD uses to implement
            the access point works best with certain versions of
            firmware.  Prism 2 cards should use firmware version 1.3.4
            or newer.  Prism 2.5 and Prism 3 cards should use firmware
            1.4.9.  Older versions of the firmware way or may not
            function correctly.  At this time, the only way to update
            cards is with windows firmware update utilities available
            from your card's manufacturer.</para>
        </sect4>
 
        <sect4>
          <title>Setting it up</title>
          <para>First, make sure your system can see the wireless card:</para>
          <screen>&prompt.root; <userinput>ifconfig -a</userinput>
 wi0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
         inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7 
         inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
         ether 00:09:2d:2d:c9:50
         media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
         status: no carrier
         ssid ""
         stationname "FreeBSD Wireless node"
         channel 10 authmode OPEN powersavemode OFF powersavesleep 100
         wepmode OFF weptxkey 1</screen>
 
          <para>Do not worry about the details now, just make sure it shows you 
           something to indicate you have a wireless card installed.</para>
 
          <para>Next, you will need to load a module in order to get the bridging part 
           of FreeBSD ready for the access point.  In order to load the &man.bridge.4; module, 
           simply run the following command:</para>
 
          <screen>&prompt.root; <userinput>kldload bridge</userinput></screen>
 
          <para>It should not have produced any errors when loading the module.  If it 
           did, you may need to compile the &man.bridge.4; code into your kernel.  The 
           <link linkend="bridging">Bridging</link> section of the handbook should be able 
           to help you accomplish that task.</para>
 
          <para>Now that you have the bridging stuff done, we need to tell the FreeBSD 
           kernel which interfaces to bridge together.  We do that by using &man.sysctl.8;:</para>
 
          <screen>&prompt.root; <userinput>sysctl net.link.ether.bridge=1</userinput>
 &prompt.root; <userinput>sysctl net.link.ether.bridge_cfg="wi0 xl0"</userinput>
 &prompt.root; <userinput>sysctl net.inet.ip.forwarding=1</userinput></screen>
 
          <para>Now it is time for the wireless card setup.</para>
          <para>The following command will set the card into an access point:</para>
 
          <screen>
 &prompt.root; <userinput>ifconfig wi0 ssid my_net channel 11 media DS/11Mbps mediaopt hostap up stationname "FreeBSD AP"</userinput>
          </screen>
 
          <para>The &man.ifconfig.8; line brings the <devicename>wi0</devicename> interface up,
 	  sets its SSID to <literal>my_net</literal>,  
           and sets the station name to <literal>FreeBSD AP</literal>.
           The <option>media DS/11Mbps</option> sets the card into 11Mbps mode and is needed
           for any <option>mediaopt</option> to take effect.
           The <option>mediaopt hostap</option> option places the interface into
 	  access point mode.
           The <option>channel 11</option> option sets the 802.11b channel to use.  The &man.wicontrol.8;
           man page has valid channel options for your regulatory domain.
          </para>
 
          <para>Now you should have a complete functioning access point up and running.  You 
           are encouraged to read &man.wicontrol.8;, &man.ifconfig.8;, and &man.wi.4; for further information.
          </para>
 
          <para>It is also suggested that you read the section on encryption that follows.</para>
        </sect4>
 
        <sect4>
          <title>Status information</title>
 	 <para>Once the access point is configured and operational,
 	   operators will want to see the clients that are associated
 	   with the access point.  At any time, the operator may type:</para>
 
          <screen>&prompt.root; <userinput>wicontrol -l</userinput>
 1 station:
 00:09:b7:7b:9d:16  asid=04c0, flags=3&lt;ASSOC,AUTH&gt;, caps=1&lt;ESS&gt;, rates=f&lt;1M,2M,5.5M,11M&gt;, sig=38/15
 </screen>
 
          <para>This shows that there's one station associated, along
            with its parameters.  The signal indicated should be used
            as a realative indication of strength only.  Its
            translation to dBm or other units varies between different
            firmware revisions.</para>
        </sect4>
      </sect3>
 
      <sect3>
        <title>Clients</title>
        <para>A wireless client is a system that accesses an access point or another client
        directly. </para>
 
        <para>Typically, wireless clients only have one network device, the wireless 
        networking card.<para>
 
        <para>There are a few different ways to configure a wireless client.  These are based 
         on the different wireless modes, generally BSS (infrastructure mode, which requires an 
         access point), and IBSS (ad-hoc, or peer-to-peer mode).  In our example, we will use the 
         most popular of the two, BSS mode, to talk to an access point.</para>
 
        <sect4>
        <title>Requirements</title>
        <para>There is only one real requirement for setting up FreeBSD as a wireless client.  
         You will need a wireless card that is supported by FreeBSD.</para>
        </sect4>
 
        <sect4>
        <title>Setting Up A Wireless FreeBSD Client</title>
        <para>You will need to know a few things about the wireless network you are joining before 
         you start.  In this example, we are joining a network that has a name of <literal>my_net</literal>, and 
         encryption turned off.</para>
 
        <para>Note:  In this example, we are not using encryption, which is a dangerous situation.  
         In the next section, you will learn how to turn on encryption, and why it is important to 
          do so, and why some encryption technologies still do not completely protect you.</para>
 
        <para>Make sure your card is recognized by FreeBSD:</para>
 
        <screen>&prompt.root; <userinput>ifconfig -a</userinput>
 wi0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
         inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7 
         inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
         ether 00:09:2d:2d:c9:50
         media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
         status: no carrier
         ssid ""
         stationname "FreeBSD Wireless node"
         channel 10 authmode OPEN powersavemode OFF powersavesleep 100
         wepmode OFF weptxkey 1</screen>
 
        <para>Now, we will set the card to the correct settings for our network:</para>
 
        <screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net</userinput></screen>
 
        <para>Replace <hostid role="IPAddr">192.168.0.20</hostid> and <hostid role="Netmask">255.255.255.0</hostid> with a valid IP address and netmask on 
         your wired network.  Remember, our access point is bridging the data between the 
         wireless network, and the wired network, so it will appear to the other devices on 
         your network that you are on the wired network just as they are.</para>
 
        <para>Once you have done that, you should be able to ping hosts on the wired network 
         just as if you were connected using a standard wired connection.</para>
 
        <para>If you are experiencing problems with your wireless connection, check to make 
         sure that your are associated (connected) to the access point:</para>
      
        <screen>&prompt.root; <userinput>ifconfig wi0</userinput></screen>
 
        <para>should return some information, and you should see:</para>
        <screen>status: associated</screen>
 
        <para>If it does not show associated, then you may be out of range of the access point, do not have 
        encryption on, or possibly have a configuration problem.</para>
 
        </sect4>
      </sect3>
 
      <sect3>
       <title>Encryption</title>
 
       <para>Encryption on a wireless network is important because you no longer have the 
        ability to keep the network contained in a well protected area.  Your wireless data 
        will be broadcast across your entire neighborhood, so anyone who cares to read it 
        can.  This is where encryption comes in.  By encrypting the data that is sent over 
        the airwaves, you make it much more difficult for any interested party to grab your 
        data right out of the air. </para>
 
      <para>The two most common ways to encrypt the data between your client and the access 
       point, are WEP, and &man.ipsec.4;.</para>
 
      <sect4>
      <title>WEP</title>
       <para>WEP is an abbreviation for Wired Equivalency Protocol.  WEP is an attempt to 
        make wireless networks as safe and secure as a wired network.  Unfortunately, it 
        has been cracked, and is fairly trivial to break.  This also means it is not something 
        to rely on when it comes to encrypting sensitive data.  </para>
 
       <para>It is better than nothing, so use the following to turn on WEP on your new FreeBSD 
        access point:</para>
 
       <screen>&prompt.root; <userinput>ifconfig wi0 inet up ssid my_net wepmode on wepkey 0x1234567890 media DS/11Mbps mediaopt hostap</userinput></screen>
 
       <para>And you can turn on WEP on a client with this command:</para>
 
       <screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net wepmode on wepkey 0x1234567890</userinput></screen>
 
       <para>Note that you should replace the <literal>0x1234567890</literal> with a more unique key.</para>
 
      </sect4>
     
      <sect4>
      <title>IPsec</title>
       <para>&man.ipsec.4; is a much more robust and powerful tool for encrypting data across a 
        network.  This is definitely the preferred way to encrypt wireless data over a 
        network.  You can read more about &man.ipsec.4; security and how to implement it in the 
        <link linkend="ipsec">IPsec</link> section of the handbook.</para>
      </sect4>
     </sect3>
 
     <sect3>
     <title>Tools</title>
     <para>There are a small number of tools available for use in debugging and setting 
     up your wireless network, and here we will attempt to describe some of them and what 
     they do.</para>
 
     <sect4>
     <title><application>bsd-airtools</application></title>
     <para>The <application>bsd-airtools</application> package is a complete toolset that includes wireless auditing tools for WEP key 
     cracking, access point detection, etc.</para>
    
     <para>The <application>bsd-airtools</application> utilities can be installed from the <filename role="package">net/bsd-airtools</filename> port.  Information on 
     installing ports can be found in <xref linkend="ports"> of the handbook.<para>
  
     <para>The program <command>dstumbler</command> is the packaged tool that allows for access point discovery and 
     signal to noise ratio graphing.  If you are having a hard time getting your access 
     point up and running, <command>dstumbler</command> may help you get started.</para>
 
     <para>To test your wireless network security, you may choose to use <quote>dweputils</quote> (<command>dwepcrack</command>, <command>dwepdump</command> and <command>dwepkeygen</command>) to 
     help you determine if WEP is the right solution to your wireless security needs.</para>
 
     </sect4>
 
     <sect4>
     <title>wicontrol, ancontrol, raycontrol</title>
     <para>These are the tools you use to control how your wireless card behaves on the 
     wireless network.  In the examples above, we have chosen to use &man.wicontrol.8;, since our 
     wireless card is a <devicename>wi0</devicename> interface.  If you had a Cisco wireless device, it would come 
     up as <devicename>an0</devicename>, and therefore you would use &man.ancontrol.8;.<para>
 
     </sect4>
 
     <sect4>
     <title>ifconfig</title>
     <para>&man.ifconfig.8; can be used to do many of the same options as &man.wicontrol.8;, however it 
     does lack a few options.  Check &man.ifconfig.8; for command line parameters and options.</para>
 
     </sect4>
 
     </sect3>
 
     <sect3>
     <title>Supported Cards</title>
     <sect4>
     <title>Access Points</title>
     <para>The only cards that are currently supported for BSS (as an access point) mode are 
     devices based on the Prism 2, 2.5, or 3 chipsets. For a complete list, look 
     at &man.wi.4;.</para>
 
     </sect4>
 
     <sect4>
     <title>Clients</title>
     <para>Almost all 802.11b wireless cards are currently supported under FreeBSD.  Most 
      cards based on Prism, Spectrum24, Hermes, Aironet, and Raylink will work as a wireless
      network card in IBSS (ad-hoc, peer-to-peer, and BSS) mode.</para>
 
     </sect4>
     </sect3>
 
    </sect2>
   </sect1>
 
 
   <sect1 id="bridging">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Steve</firstname>
       	  <surname>Peterson</surname>
 	  <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Bridging</title>
 
     <sect2>
       <title>Introduction</title>
       <indexterm><primary>IP subnet</primary></indexterm>
       <indexterm><primary>bridge</primary></indexterm>
       <para>It is sometimes useful to divide one physical network (such as an
 	Ethernet segment) into two separate network segments without having
 	to create IP subnets and use a router to connect the segments
 	together.  A device that connects two networks together in this
 	fashion is called a <quote>bridge</quote>.  A FreeBSD system with two network
 	interface cards can act as a bridge.</para>
 
       <para>The bridge works by learning the MAC layer addresses
 	(Ethernet addresses) of the devices on each of its network interfaces.
 	It forwards traffic between two networks only when its source and
 	destination are on different networks.</para>
 
       <para>In many respects, a bridge is like an Ethernet switch with very
 	few ports.</para>
     </sect2>
 
     <sect2>
       <title>Situations Where Bridging Is Appropriate</title>
 
       <para>There are two common situations in which a bridge is used
 	today.</para>
 
       <sect3>
 	<title>High Traffic on a Segment</title>
 
 	<para>Situation one is where your physical network segment is
 	  overloaded with traffic, but you do not want for whatever reason to
 	  subnet the network and interconnect the subnets with a
 	  router.</para>
 
 	<para>Let us consider an example of a newspaper where the Editorial and
 	  Production departments are on the same subnetwork.  The Editorial
 	  users all use server A for file service, and the Production users
 	  are on server B.  An Ethernet is used to connect all users together,
 	  and high loads on the network are slowing things down.</para>
 
 	<para>If the Editorial users could be segregated on one network
 	  segment and the Production users on another, the two network
 	  segments could be connected with a bridge.  Only the network traffic
 	  destined for interfaces on the <quote>other</quote> side of the bridge would be
 	  sent to the other network, reducing congestion on each network
 	  segment.</para>
       </sect3>
 
       <sect3>
 	<title>Filtering/Traffic Shaping Firewall</title>
 	<indexterm><primary>firewall</primary></indexterm>
 	<indexterm><primary>IP Masquerading</primary></indexterm>
 
 	<para>The second common situation is where firewall functionality is
 	  needed without IP Masquerading (NAT).</para>
 
 	<para>An example is a small company that is connected via DSL or ISDN
 	  to their ISP.  They have a 13 globally-accessible IP addresses
 	  from their ISP and have 10 PCs on their network.  In this situation, using a
 	  router-based firewall is difficult because of subnetting
 	  issues.</para>
 
 	<indexterm><primary>router</primary></indexterm>
 	<indexterm><primary>DSL</primary></indexterm>
 	<indexterm><primary>ISDN</primary></indexterm>
 	<para>A bridge-based firewall can be configured and dropped into the
 	  path just downstream of their DSL/ISDN router without any IP
 	  numbering issues.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Configuring a Bridge</title>
 
       <sect3>
 	<title>Network Interface Card Selection</title>
 
 	<para>A bridge requires at least two network cards to function.
 	  Unfortunately, not all network interface cards as of FreeBSD&nbsp;4.0
 	  support bridging.  Read &man.bridge.4; for details on the cards that
 	  are supported.</para>
 
 	<para>Install and test the two network cards before continuing.</para>
       </sect3>
 
       <sect3>
 	<title>Kernel Configuration Changes</title>
 	<indexterm><primary>kernel configuration</primary></indexterm>
 	<indexterm>
 	  <primary>kernel configuration</primary>
 	  <secondary>options BRIDGE</secondary>
 	</indexterm>
 
 	<para>To enable kernel support for bridging, add the:</para>
 
 	<programlisting>options BRIDGE</programlisting>
 
 	<para>statement to your kernel configuration file, and rebuild your
 	  kernel.</para>
       </sect3>
 
       <sect3>
 	<title>Firewall Support</title>
 	<indexterm><primary>firewall</primary></indexterm>
 	<para>If you are planning to use the bridge as a firewall, you will
 	  need to add the <varname>IPFIREWALL</varname> option as well.  Read <xref
 	    linkend="firewalls"> for general information on configuring the
 	  bridge as a firewall.</para>
 
 	<para>If you need to allow non-IP packets (such as ARP) to flow
 	  through the bridge, there is an undocumented firewall option that
 	  must be set.  This option is
 	  <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal>.  Note that this
 	  changes the default rule for the firewall to accept any packet.
 	  Make sure you know how this changes the meaning of your ruleset
 	  before you set it.</para>
       </sect3>
 
       <sect3>
 	<title>Traffic Shaping Support</title>
 
 	<para>If you want to use the bridge as a traffic shaper, you will need
 	  to add the <literal>DUMMYNET</literal> option to your kernel
 	  configuration.  Read &man.dummynet.4; for further
 	  information.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Enabling the Bridge</title>
 
       <para>Add the line:</para>
 
       <programlisting>net.link.ether.bridge=1</programlisting>
 
       <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at
 	runtime, and the line:</para>
 
       <programlisting>net.link.ether.bridge_cfg=<replaceable>if1</replaceable>,<replaceable>if2</replaceable></programlisting>
 
       <para>to enable bridging on the specified interfaces (replace <replaceable>if1</replaceable> and
 	<replaceable>if2</replaceable> with the names of your two network interfaces).  If you want the
 	   bridged packets to be filtered by &man.ipfw.8;, you should 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 10&nbsp;mbps half duplex
 	and the connection between the bridge and my router (a Cisco 675) runs
 	at 100&nbsp;mbps full duplex.  With no filtering enabled, I have found that
 	the bridge adds about 0.4&nbsp;milliseconds of latency to pings from the
 	protected 10&nbsp;mbps network to the Cisco 675.</para>
     </sect2>
 
     <sect2>
       <title>Other Information</title>
 
       <para>If you want to be able to telnet into the bridge from the network,
 	it is OK to assign one of the network cards an IP address.  The
 	consensus is that assigning both cards an address is a bad
 	idea.</para>
 
       <para>If you have multiple bridges on your network, there cannot be more
 	than one path between any two workstations.  Technically, this means
 	that there is no support for spanning tree link management.</para>
     </sect2>
   </sect1>
 
   <sect1 id="nfs">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Tom</firstname>
           <surname>Rhodes</surname>
           <contrib>Reorganized and enhanced by </contrib>
         </author>
       </authorgroup>
       <authorgroup>
         <author>
           <firstname>Bill</firstname>
       	  <surname>Swingle</surname>
 	  <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>NFS</title>
 
     <indexterm><primary>NFS</primary></indexterm>
     <para>Among the many different filesystems that FreeBSD supports is
       the Network File System, also known as <acronym>NFS</acronym>.
       <acronym>NFS</acronym> allows a system to share directories and files
       with others over a network.  By using <acronym>NFS</acronym>, users and
       programs can access files on remote systems almost as if they were local
       files.</para>
 
     <para>Some of the most notable benefits that <acronym>NFS</acronym> can provide are:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Local workstations use less disk space because
 	  commonly used data can be stored on a single machine and still
 	  remain accessible to others over the network.</para>
       </listitem>
 
       <listitem>
 	<para>There is no need for users to have separate home directories
 	  on every network machine.  Home directories could be setup on the
 	  <acronym>NFS</acronym> server and made available throughout
 	  the network.</para>
       </listitem>
 
       <listitem>
 	<para>Storage devices such as floppy disks, CDROM drives, and
 	  ZIP drives can be used by other machines on the network.
 	  This may reduce the number of removable media drives
 	  throughout the network.</para>
       </listitem>
     </itemizedlist>
 
     <sect2>
       <title>How <acronym>NFS</acronym> Works</title>
 
       <para><acronym>NFS</acronym> consists of at least two main parts:
         a server and one or more clients.  The client remotely accesses
         the data that is stored
         on the server machine.  In order for this to function properly a few
         processes have to be configured and running:</para>
 
       <para>The server has to be running the following daemons:</para>
       <indexterm>
         <primary>NFS</primary>
         <secondary>server</secondary>
       </indexterm>
       <indexterm>
         <primary><application>portmap</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>mountd</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>nfsd</application></primary>
       </indexterm>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Daemon</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  <tbody>
 	    <row>
 	      <entry>nfsd</entry>
 	      <entry>The <acronym>NFS</acronym> daemon which services requests from
               the <acronym>NFS</acronym> clients.</entry>
 	    </row>
 	    <row>
 	      <entry>mountd</entry>
 	      <entry>The <acronym>NFS</acronym> mount daemon which carries out
 		the requests that &man.nfsd.8; passes on to it.</entry>
 	    </row>
 	    <row>
 	      <entry>portmap</entry>
 	      <entry> The portmapper daemon
                 allows <acronym>NFS</acronym> clients to discover which port the <acronym>NFS</acronym> server
                 is using.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>The client can also run a daemon, known as
         <application>nfsiod</application>.  The <application>nfsiod</application>
         daemon services the requests from the <acronym>NFS</acronym> server.  This
         is optional, and improves performance, but is not required for normal
         and correct operation.  See the &man.nfsiod.8; manual page for more information.
       </para>
     </sect2>
 
     <sect2 id="configuring-nfs">
       <title>Configuring <acronym>NFS</acronym></title>
       <indexterm>
         <primary>NFS</primary>
         <secondary>configuration</secondary>
       </indexterm>
 
       <para><acronym>NFS</acronym> configuration is a relatively straightforward
         process.  The processes that need to be running can all start at boot time with
 	a few modifications to your <filename>/etc/rc.conf</filename>
         file.</para>
 
       <para>On the <acronym>NFS</acronym> server, make sure that the following options
         are configured in the <filename>/etc/rc.conf</filename> file:</para>
 
       <programlisting>portmap_enable="YES"
 nfs_server_enable="YES"
 mountd_flags="-r"</programlisting>
 
       <para><command>mountd</command> runs automatically whenever the
         <acronym>NFS</acronym> server is enabled.</para>
 
       <para>On the client, make sure this option is present in
         <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>nfs_client_enable="YES"</programlisting>
 
       <para>
         The <filename>/etc/exports</filename>
         file specifies which filesystems <acronym>NFS</acronym> should export (sometimes
         referred to as <quote>share</quote>).
         Each line in <filename>/etc/exports</filename> specifies a filesystem to be exported and
         which machines have access to that filesystem.  Along with what machines have access
         to that filesystem, access options may also be specified.  There are many such options
         that can be used in this file but only a few will be mentioned here.  You can easily discover
 	other options by reading over the &man.exports.5; manual page.</para>
 
       <para>Here are a few example <filename>/etc/exports</filename>
 	entries:</para>
 
       <indexterm>
         <primary>NFS</primary>
         <secondary>Examples of exporting filesystems</secondary>
       </indexterm>
 
       <para>The following examples give an idea of how to export filesystems,
         although the settings may be different depending on
         your environment and network configuration.
         For instance, to export the <filename>/cdrom</filename> directory to
 	three example machines that have the same domain name as the server
 	(hence the lack of a domain name for each) or have entries in your
 	<filename>/etc/hosts</filename> file.  The <option>-ro</option>
 	flag makes the exported filesystem read-only.  With this flag, the
 	remote system will not be able to write any changes to the
 	exported filesystem.</para>
 
       <programlisting>/cdrom -ro host1 host2 host3</programlisting>
 
       <para>The following line exports <filename>/home</filename> to three
 	hosts by IP address.  This is a useful setup if you have a
 	private network without a <acronym>DNS</acronym> server configured.
         Optionally the <filename>/etc/hosts</filename> file could be configured
         for internal hostnames; please review &man.hosts.5; for more
         information.  The <option>-alldirs</option> flag allows the subdirectories
         to be mount points.  In other words, it will not mount the subdirectories
         but permit the client to mount only the directories that are required or
         needed.</para>
 
       <programlisting>/home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4</programlisting>
 
       <para>The following line exports <filename>/a</filename> so that two
 	clients from different domains may access the filesystem.  The
 	<option>-maproot=root</option> flag allows the <username>root</username>
         user on the remote system to write data on the exported filesystem as
         <username>root</username>.  If the <literal>-maproot=root</literal> flag is not specified, then even if
         a user has <username>root</username> access on the remote system, they will not
         be able to modify files on the exported filesystem.</para>
 
       <programlisting>/a  -maproot=root  host.example.com box.example.org</programlisting>
 
       <para>In order for a client to access an exported filesystem, the client must
 	have permission to do so.  Make sure the client is listed in your
 	<filename>/etc/exports</filename> file.</para>
 
       <para>In <filename>/etc/exports</filename>, each line represents
 	the export information for one filesystem to one host.  A
 	remote host can only be specified once per filesystem, and may only
         have one default entry.  For example, assume that <filename>/usr</filename>
         is a single filesystem.  The following <filename>/etc/exports</filename>
         would be invalid:</para>
 
       <programlisting>/usr/src   client
 /usr/ports client</programlisting>
 
       <para>One filesystem, <filename>/usr</filename>, has two lines
 	specifying exports to the same host, <hostid>client</hostid>.
         The correct format for this situation is:</para>
 
       <programlisting>/usr/src /usr/ports  client</programlisting>
 
       <para>The properties of one filesystem exported to a given host
 	must all occur on one line.  Lines without a client specified
 	are treated as a single host.  This limits how you can export
 	filesystems, but for most people this is not an issue.</para>
 
       <para>The following is an example of a valid export list, where
 	<filename>/usr</filename> and <filename>/exports</filename>
 	are local filesystems:</para>
 
       <programlisting># Export src and ports to client01 and client02, but only
 # client01 has root privileges on it
 /usr/src /usr/ports -maproot=root    client01
 /usr/src /usr/ports               client02
 # The client machines have root and can mount anywhere
 # on /exports. Anyone in the world can mount /exports/obj read-only
 /exports -alldirs -maproot=root      client01 client02
 /exports/obj -ro</programlisting>
 
       <para>You must restart
         <command>mountd</command> whenever you modify
         <filename>/etc/exports</filename> so the changes can take effect.
         This can be accomplished by sending the HUP signal
         to the <command>mountd</command> process:</para>
 
       <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
 
       <para>Alternatively, a reboot will make FreeBSD set everything
         up properly.  A reboot is not necessary though.
         Executing the following commands as <username>root</username>
         should start everything up.</para>
 
       <para>On the <acronym>NFS</acronym> server:</para>
 
       <screen>&prompt.root; <userinput>portmap</userinput>
 &prompt.root; <userinput>nfsd -u -t -n 4</userinput>
 &prompt.root; <userinput>mountd -r</userinput></screen>
 
       <para>On the <acronym>NFS</acronym> client:</para>
 
       <screen>&prompt.root; <userinput>nfsiod -n 4</userinput></screen>
 
       <para>Now everything should be ready to actually mount a remote file
 	system.  In these examples the
 	server's name will be <literal>server</literal> and the client's
 	name will be <literal>client</literal>.  If you only want to
 	temporarily mount a remote filesystem or would rather test the
 	configuration, just execute a command like this as <username>root</username> on the
         client:</para>
       <indexterm>
         <primary>NFS</primary>
         <secondary>mounting filesystems</secondary>
       </indexterm>
       <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>
 
       <para>This will mount the <filename>/home</filename> directory
 	on the server at <filename>/mnt</filename> on the client.  If
 	everything is set up correctly you should be able to enter
 	<filename>/mnt</filename> on the client and see all the files
         that are on the server.</para>
 
       <para>If you want to automatically mount a remote filesystem
 	each time the computer boots, add the filesystem to the
 	<filename>/etc/fstab</filename> file.  Here is an example:</para>
 
       <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>
 
       <para>The &man.fstab.5; manual page lists all the available options.</para>
     </sect2>
 
     <sect2>
       <title>Practical Uses</title>
 
       <para><acronym>NFS</acronym> has many practical uses.  Some of the more common
         ones are listed below:</para>
 
       <indexterm>
         <primary>NFS</primary>
         <secondary>uses</secondary>
       </indexterm>
       <itemizedlist>
         <listitem>
 	  <para>Set several machines to share a CDROM or
 	    other media among them.  This is cheaper and often
             a more convenient method to install software on multiple machines.</para>
 	</listitem>
 
 	<listitem>
 	  <para>On large networks, it might be more convenient to configure a
 	    central <acronym>NFS</acronym> server in which to store all the user
             home directories.  These home directories can then be exported to
             the network so that users would always have the same home directory,
             regardless of which workstation they log in to.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Several machines could have a common
             <filename>/usr/ports/distfiles</filename> directory.
             That way, when you need to install a port on several machines, you can
             quickly access the source without downloading it on each machine.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2 id="amd">
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Wylie</firstname>
 	    <surname>Stilwell</surname>
 	    <contrib>Contributed by </contrib>
 	  </author>
 	</authorgroup>
 	<authorgroup>
 	  <author>
 	    <firstname>Chern</firstname>
 	    <surname>Lee</surname>
 	    <contrib>Rewritten by </contrib>
 	  </author>
 	</authorgroup>
       </sect2info>
       <title>amd</title>
 
       <indexterm><primary>amd</primary></indexterm>
       <indexterm><primary>automatic mounter daemon</primary></indexterm>
 
       <para>&man.amd.8; (the automatic mounter daemon)
 	automatically mounts a
 	remote filesystem whenever a file or directory within that
 	filesystem is accessed.  Filesystems that are inactive for a
 	period of time will also be automatically unmounted by
 	<application>amd</application>.  Using
 	<application>amd</application> provides a simple alternative
 	to permanent mounts, as permanent mounts are usually listed in
         <filename>/etc/fstab</filename>.</para>
 
       <para><application>amd</application> operates by attaching
 	itself as an NFS server to the <filename>/host</filename> and
 	<filename>/net</filename> directories.  When a file is accessed
 	within one of these directories, <application>amd</application>
 	looks up the corresponding remote mount and automatically mounts
 	it.  <filename>/net</filename> is used to mount an exported
 	filesystem from an IP address, while <filename>/host</filename>
 	is used to mount an export from a remote hostname.</para>
 
       <para>An access to a file within
 	<filename>/host/foobar/usr</filename> would tell
 	<application>amd</application> to attempt to mount the
 	<filename>/usr</filename> export on the host
 	<hostid>foobar</hostid>.</para>
 
       <example>
 	<title>Mounting an Export with <application>amd</application></title>
 
 	<para>You can view the available mounts of a remote host with
 	  the <command>showmount</command> command.  For example, to
 	  view the mounts of a host named <hostid>foobar</hostid>, you
 	  can use:</para>
 
 	<screen>&prompt.user; <userinput>showmount -e foobar</userinput>
 Exports list on foobar:
 /usr                               10.10.10.0
 /a                                 10.10.10.0
 &prompt.user; cd /host/foobar/usr</screen>
       </example>
 
       <para>As seen in the example, the <command>showmount</command> shows
 	<filename>/usr</filename> as an export.  When changing directories to
 	<filename>/host/foobar/usr</filename>, <application>amd</application>
 	attempts to resolve the hostname <hostid>foobar</hostid> and
 	automatically mount the desired export.</para>
 
       <para><application>amd</application> can be started by the
 	startup scripts by placing the following lines in
 	<filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>amd_enable="YES"</programlisting>
 
       <para>Additionally, custom flags can be passed to
       <application>amd</application> from the
       <varname>amd_flags</varname> option.  By default,
       <varname>amd_flags</varname> is set to:</para>
 
       <programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting>
 
       <para>The <filename>/etc/amd.map</filename> file defines the
 	default options that exports are mounted with.  The
 	<filename>/etc/amd.conf</filename> file defines some of the more
 	advanced features of <application>amd</application>.</para>
 
       <para>Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more
 	information.</para>
     </sect2>
 
     <sect2 id="nfs-integration">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>John</firstname>
             <surname>Lind</surname>
             <contrib>Contributed by </contrib>
           </author>
         </authorgroup>
       </sect2info>
       <title>Problems Integrating with Other Systems</title>
 
       <para>Certain Ethernet adapters for ISA PC systems have limitations
 	which can lead to serious network problems, particularly with NFS.
 	This difficulty is not specific to FreeBSD, but FreeBSD systems
 	are affected by it.</para>
 
       <para>The problem nearly always occurs when (FreeBSD) PC systems are
 	networked with high-performance workstations, such as those made
 	by Silicon Graphics, Inc., and Sun Microsystems, Inc.  The NFS
 	mount will work fine, and some operations may succeed, but
 	suddenly the server will seem to become unresponsive to the
 	client, even though requests to and from other systems continue to
 	be processed.  This happens to the client system, whether the
 	client is the FreeBSD system or the workstation.  On many systems,
 	there is no way to shut down the client gracefully once this
 	problem has manifested itself.  The only solution is often to
 	reset the client, because the NFS situation cannot be
 	resolved.</para>
 
       <para>Though the <quote>correct</quote> solution is to get a higher
 	performance and capacity Ethernet adapter for the FreeBSD system,
 	there is a simple workaround that will allow satisfactory
 	operation.  If the FreeBSD system is the
 	<emphasis>server</emphasis>, include the option
 	<option>-w=1024</option> on the mount from the client.  If the
 	FreeBSD system is the <emphasis>client</emphasis>, then mount the
 	NFS filesystem with the option <option>-r=1024</option>.  These
 	options may be specified using the fourth field of the
 	<filename>fstab</filename> entry on the client for automatic
 	mounts, or by using the <option>-o</option> parameter of the mount
 	command for manual mounts.</para>
 
       <para>It should be noted that there is a different problem,
 	sometimes mistaken for this one, when the NFS servers and clients
 	are on different networks.  If that is the case, make
 	<emphasis>certain</emphasis> that your routers are routing the
 	necessary UDP information, or you will not get anywhere, no matter
 	what else you are doing.</para>
 
       <para>In the following examples, <hostid>fastws</hostid> is the host
 	(interface) name of a high-performance workstation, and
 	<hostid>freebox</hostid> is the host (interface) name of a FreeBSD
 	system with a lower-performance Ethernet adapter.  Also,
 	<filename>/sharedfs</filename> will be the exported NFS
 	filesystem (see &man.exports.5;), and
 	<filename>/project</filename> will be the mount point on the
 	client for the exported filesystem.  In all cases, note that
 	additional options, such as <option>hard</option> or
 	<option>soft</option> and <option>bg</option> may be desirable in
 	your application.</para>
 
       <para>Examples for the FreeBSD system (<hostid>freebox</hostid>) as
 	the client in <filename>/etc/fstab</filename> on 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 8&nbsp;k (though it
 	may do fragments of smaller sizes).  Since the maximum Ethernet
 	packet is around 1500&nbsp;bytes, the NFS <quote>block</quote> gets
 	split into multiple Ethernet packets, even though it is still a
 	single unit to the upper-level code, and must be received,
 	assembled, and <emphasis>acknowledged</emphasis> as a unit.  The
 	high-performance workstations can pump out the packets which
 	comprise the NFS unit one right after the other, just as close
 	together as the standard allows.  On the smaller, lower capacity
 	cards, the later packets overrun the earlier packets of the same
 	unit before they can be transferred to the host and the unit as a
 	whole cannot be reconstructed or acknowledged.  As a result, the
 	workstation will time out and try again, but it will try again
 	with the entire 8&nbsp;K unit, and the process will be repeated, ad
 	infinitum.</para>
 
       <para>By keeping the unit size below the Ethernet packet size
 	limitation, we ensure that any complete Ethernet packet received
 	can be acknowledged individually, avoiding the deadlock
 	situation.</para>
 
       <para>Overruns may still occur when a high-performance workstations
 	is slamming data out to a PC system, but with the better cards,
 	such overruns are not guaranteed on NFS <quote>units</quote>.  When
 	an overrun occurs, the units affected will be retransmitted, and
 	there will be a fair chance that they will be received, assembled,
 	and acknowledged.</para>
     </sect2>
   </sect1>
 
   <sect1 id="diskless">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Jean-Fran&ccedil;ois</firstname>
           <surname>Dock&egrave;s</surname>
           <contrib>Updated by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Diskless Operation</title>
 
     <indexterm><primary>diskless workstation</primary></indexterm>
     <indexterm><primary>diskless operation</primary></indexterm>
 
     <para>A FreeBSD machine can boot over the network and operate without a
       local disk, using filesystems mounted from an NFS server.  No system
       modification is necessary, beyond standard configuration files.
       Such a system is easy to  set up because all the necessary elements
       are readily available:</para>
     <itemizedlist>
       <listitem>
 	<para>There are at least two possible methods to load the kernel over
 	  the network:</para>
 	<itemizedlist>
 	  <listitem>
 	    <para><emphasis>PXE</emphasis>: Intel's Preboot Execution
 	      Environment system is a form of smart boot ROM built into some
 	      networking cards or motherboards.  See &man.pxeboot.8; for more
 	      details.</para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>The <application>etherboot</application>
 		port</emphasis> (<filename role="package">net/etherboot</filename>)
 	      produces ROM-able code to boot kernels over the network.  The code
 	      can be either burnt into a boot PROM on a network card, or loaded
 	      from a local floppy (or hard) disk drive, or from a running
 	      MS-DOS system.  Many network cards are supported.</para>
 	  </listitem>
 	</itemizedlist>
 	</listitem>
 
       <listitem>
 	<para>A sample script
 	  (<filename>/usr/share/examples/diskless/clone_root</filename>) eases
 	  the creation and maintenance of the workstation's root filesystem
 	  on the server.  The script will probably require a little
 	  customization but it will get you started very quickly.</para>
       </listitem>
 
       <listitem>
 	<para>Standard system startup files exist in <filename>/etc</filename>
 	  to detect and support a diskless system startup.</para>
       </listitem>
 
       <listitem>
 	<para>Swapping, if needed, can be done either to an NFS file or to
 	  a local disk.</para>
       </listitem>
     </itemizedlist>
 
     <para>There are many ways to set up diskless workstations.  Many
       elements are involved, and most can be customized to suit local
       taste.  The following will describe the setup of a complete system,
       emphasizing simplicity and compatibility with the
       standard FreeBSD startup scripts.  The system described has the
       following characteristics:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The diskless workstations use a shared
 	  read-only <filename>root</filename> filesystem, and a shared
 	  read-only <filename>/usr</filename>.</para>
 	<para>The <filename>root</filename> filesystem is a copy of a
 	  standard FreeBSD root (typically the server's), with some
 	  configuration files overridden by ones specific to diskless
 	  operation or, possibly, to the workstation they belong to.</para>
 	<para>The parts of the <filename>root</filename> which have to be
 	  writable are overlaid with &man.mfs.8; filesystems.  Any changes
 	  will be lost when the system reboots.</para>
       </listitem>
       <listitem>
 	<para>The kernel is loaded by <application>etherboot
 	  </application>, using DHCP (or BOOTP) and TFTP.</para>
       </listitem>
     </itemizedlist>
 
     <caution><para>As described, this system is insecure.  It should
 	live in a protected area of a network, and be untrusted by
 	other hosts.</para>
     </caution>
 
 
     <sect2>
       <title>Setup Instructions</title>
 
       <sect3>
 	<title>Configuring DHCP/BOOTP</title>
 
 	<para>There are two protocols that are commonly used to boot a
 	  workstation that retrieves its configuration over the network: BOOTP
 	  and DHCP.  They are used at several points in the workstation
 	  bootstrap:</para>
 	<itemizedlist>
 	  <listitem><para><application>etherboot</application> uses
 	      DHCP (by default) or BOOTP (needs a configuration option) to
 	      find the kernel.  (PXE uses DHCP).</para>
 	  </listitem>
 	  <listitem><para>The kernel uses BOOTP to locate the NFS
 	      root.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>It is possible to configure a system to use only BOOTP.
 	  The &man.bootpd.8; server program is included in the
 	  base FreeBSD system.</para>
 
 	<para>However, DHCP has a number of advantages over BOOTP (nicer
 	  configuration files, possibility of using PXE, plus many others
 	  not directly related to diskless operation), and we shall describe
 	  both a pure BOOTP, and a BOOTP+DHCP configuration, with an
 	  emphasis on the latter, which will use the ISC DHCP software
 	  package.</para>
 
 	<sect4>
 	  <title>Configuration Using ISC DHCP</title>
 
 	  <para>The <application>isc-dhcp</application> server can answer
 	    both BOOTP and DHCP requests.</para>
 
 	  <para>As of release 4.4, <application>isc-dhcp
   	    3.0</application> is not part of the base
 	    system.  You will first need to install the
 	    <filename role="package">net/isc-dhcp3</filename> port or the
 	    corresponding package.  Please refer to <xref linkend="ports">
 	    for general information about ports and packages.</para>
 
 	  <para>Once <application>isc-dhcp</application> is installed, it
 	    needs a configuration file to run, (normally named
 	    <filename>/usr/local/etc/dhcpd.conf</filename>).  Here follows
 	    a commented example:</para>
 
           <programlisting>
           default-lease-time 600;
           max-lease-time 7200;
           authoritative;
 
           option domain-name "example.com";
           option domain-name-servers 192.168.4.1;
           option routers 192.168.4.1;
 
           subnet 192.168.4.0 netmask 255.255.255.0 {
             use-host-decl-names on; <co id="co-dhcp-host-name">
             option subnet-mask 255.255.255.0;
             option broadcast-address 192.168.4.255;
 
             host margaux {
               hardware ethernet 01:23:45:67:89:ab;
               fixed-address margaux.example.com;
               next-server 192.168.4.4;<co id="co-dhcp-next-server">
               filename "/tftpboot/kernel.diskless";<co id="co-dhcp-filename">
               option root-path "192.168.4.4:/data/misc/diskless";<co id="co-dhcp-root-path">
             }
           }
           </programlisting>
 
 	  <calloutlist>
 	    <callout arearefs="co-dhcp-host-name"><para>This option tells
 		<command>dhcpd</command> to send the value in the
 		<literal>host</literal> declarations as the hostname for the
 		diskless host.  An alternate way would be to add an
 		<literal>option host-name
 		  <replaceable>margaux</replaceable></literal> inside the
 		host declarations.</para>
 	    </callout>
 
 	    <callout arearefs="co-dhcp-next-server"><para>The
 		<literal>next-server</literal> directive designates
 		the TFTP server (the default is to use the same host as the
 		DHCP server).</para>
 	    </callout>
 
 	    <callout arearefs="co-dhcp-filename"><para>The
 		<literal>filename</literal> directive defines the file that
 		<application>etherboot</application> will load as a
 		kernel.
 		<note><para>PXE appears to prefer a relative file
 		    name, and it loads <command>pxeboot</command>, not the
 		    kernel (<literal>option filename
 		      "pxeboot"</literal>).</para>
 		</note>
 	      </para>
 	    </callout>
 
 	    <callout arearefs="co-dhcp-root-path"><para>The
 		<literal>root-path</literal> option defines the path to
 		the root filesystem, in usual NFS notation.</para>
 	    </callout>
 	  </calloutlist>
 
 	</sect4>
 	<sect4>
 	  <title>Configuration Using BOOTP</title>
 
 	  <para>Here follows an equivalent <command>bootpd</command>
 	    configuration.  This would be found in
 	    <filename>/etc/bootptab</filename>.</para>
 
 	  <para>Please note that <application>etherboot</application> must
 	  be compiled with the non-default option
 	  <literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP, and that PXE
 	  <emphasis>needs</emphasis> DHCP.  The only obvious advantage of
 	  <application>bootpd</application> is that it exists in the base system.</para>
 
           <programlisting>
           .def100:\
             :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
             :sm=255.255.255.0:\
             :ds=192.168.4.1:\
             :gw=192.168.4.1:\
             :hd="/tftpboot":\
             :bf="/kernel.diskless":\
             :rp="192.168.4.4:/data/misc/diskless":
 
           margaux:ha=0123456789ab:tc=.def100
           </programlisting>
 	</sect4>
       </sect3>
 
       <sect3>
 	<title>Preparing a Boot Program with
 	  <application>Etherboot</application></title>
 
 	<para><ulink url="http://etherboot.sourceforge.net">Etherboot's Web
 	  site</ulink> contains
 	  <ulink url="http://etherboot.sourceforge.net/doc/html/userman.html">
 	  extensive documentation</ulink> mainly intended for Linux
 	  systems, but nonetheless containing useful information.  The following
 	  will just outline how you would use
 	  <application>etherboot</application> on a FreeBSD system.</para>
 
 	<para>You must first install the
 	  <filename role="package">net/etherboot</filename> package or port.  The
 	  <application>etherboot</application> port can normally be found in
 	  <filename>/usr/ports/net/etherboot</filename>.  If the ports tree is
 	  installed on your system, just typing <literal>make</literal> in
 	  this directory should take care of everything.  Else refer to
 	  <xref linkend="ports"> for information about ports and
 	  packages.</para>
 
 	<para>For our setup, we shall use a boot floppy.  For other methods
 	  (PROM, or dos program), please refer to the
 	  <application>etherboot</application> documentation.</para>
 
 	<para>To make a boot floppy, insert a floppy in the drive on the
 	  machine where you installed <application>etherboot</application>,
 	  then change your current directory to the <filename>src</filename>
 	  directory in the <application>etherboot</application> tree and
 	  type:</para>
 
 	<screen>
 	  &prompt.root; <userinput>gmake bin32/<replaceable>devicetype</replaceable>.fd0</userinput>
 	</screen>
 
 	<para><replaceable>devicetype</replaceable> depends on the type of
 	  the Ethernet card in the diskless workstation.  Refer to the
 	  <filename>NIC</filename> file in the same directory to determine the
 	  right <replaceable>devicetype</replaceable>.</para>
 
       </sect3>
 
 
       <sect3>
 	<title>Configuring the TFTP and NFS Servers</title>
 
 	<para>You need to enable <command>tftpd</command> on the TFTP
 	  server:</para>
         <procedure>
           <step>
             <para>Create a directory from which <command>tftpd</command>
             will serve the files, i.e.: <filename>/tftpboot</filename></para>
           </step>
 
           <step>
             <para>Add this line to your
 	      <filename>/etc/inetd.conf</filename>:</para>
 
 	    <programlisting>tftp    dgram   udp     wait    nobody  /usr/libexec/tftpd    tftpd /tftpboot</programlisting>
 
 	    <note><para>It appears that at least some PXE versions want
 		the TCP version of TFTP.  In this case, add a second line,
 		replacing <literal>dgram udp</literal> with <literal>stream
 		tcp</literal>.</para>
 	    </note>
           </step>
 	  <step>
 	    <para>Tell <command>inetd</command> to reread its configuration
 	      file:</para>
 	    <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
 	  </step>
         </procedure>
 
 	<para>You can place the <filename>tftpboot</filename>
 	  directory anywhere on the server.  Make sure that the
 	  location is set in both <filename>inetd.conf</filename> and
 	  <filename>dhcpd.conf</filename>.</para>
 
 	<para>You also need to enable NFS and export the
 	  appropriate filesystem on the NFS server.</para>
 
         <procedure>
           <step>
             <para>Add this to <filename>/etc/rc.conf</filename>:</para>
 	    <programlisting>nfs_server_enable="YES"</programlisting>
           </step>
 
           <step>
             <para>Export the filesystem where the diskless root directory
 	      is located by adding the following to
 	      <filename>/etc/exports</filename> (adjust the volume mount
 	      point and replace <replaceable>margaux</replaceable>
 	      with the name of the diskless workstation):</para>
 
 	    <programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux</replaceable></programlisting>
           </step>
 	  <step>
 	    <para>Tell <command>mountd</command> to reread its configuration
 	      file.  If you actually needed to enable NFS in
 	      <filename>/etc/rc.conf</filename>
 	      at the first step, you probably want to reboot instead.</para>
 	    <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
 	  </step>
         </procedure>
 
       </sect3>
 
       <sect3>
 	<title>Building a Diskless Kernel</title>
 
 	<para>Create a kernel configuration file for the diskless client
 	  with the following options (in addition to the usual
 	  ones):</para>
 
 	<programlisting>
           options     BOOTP          # Use BOOTP to obtain IP address/hostname
           options     BOOTP_NFSROOT  # NFS mount root filesystem using BOOTP info
           options     BOOTP_COMPAT   # Workaround for broken bootp daemons.
 	</programlisting>
 
 	<para>You may also want to use <literal>BOOTP_NFSV3</literal> and
 	  <literal>BOOTP_WIRED_TO</literal> (refer to <filename>LINT</filename>).</para>
 
 	<para>Build the kernel (See <xref linkend="kernelconfig">),
 	  and copy it to the tftp directory, under the name listed
 	  in <filename>dhcpd.conf</filename>.</para>
 
 
       </sect3>
 
       <sect3>
 	  <title>Preparing the root Filesystem</title>
 
 	<para>You need to create a root filesystem for the diskless
 	  workstations, in the location listed as
 	  <literal>root-path</literal> in
 	  <filename>dhcpd.conf</filename>.</para>
 
 	<para>The easiest way to do this is to use the
 	  <filename>/usr/share/examples/diskless/clone_root</filename>
 	  shell script.  This script needs customization, at least to adjust
 	  the place where the filesystem will be created (the
 	  <literal>DEST</literal> variable).
 
 	<para>Refer to the comments at the top of the script for
 	    instructions.  They explain how the base filesystem is built,
 	    and how files may be selectively overridden by versions specific
 	    to diskless operation, to a subnetwork, or to an individual
 	    workstation.  They also give examples for the diskless
 	    <filename>/etc/fstab</filename> and <filename>
 	    /etc/rc.conf</filename> files.</para>
 
 	  <para>The <filename>README</filename> files in
 	    <filename>/usr/share/examples/diskless</filename> contain a lot
 	    of interesting background information, but, together with the
 	    other examples in the <filename>diskless</filename> directory,
 	    they actually document a configuration method which is distinct
 	    from the one used by <filename>clone_root</filename> and
 	    <filename>/etc/rc.diskless[12]</filename>, which is a little
 	    confusing.  Use them for reference only, except if you prefer
 	    the method that they describe, in which case you will need
 	    customized <filename>rc</filename> scripts.</para>
       </sect3>
 
       <sect3>
 	<title>Configuring Swap</title>
 
 	<para>If needed, a swap file located on the server can be
 	  accessed via NFS.  The exact <filename>bootptab</filename>
 	  or <filename>dhcpd.conf</filename> options are not clearly
 	  documented at this time.  The following configuration
 	  suggestions have been reported to work in some installations
 	  using isc-dhcp 3.0rc11.</para>
 	<procedure>
 	  <step><para>Add the following lines to
 	  <filename>dhcpd.conf</filename>:</para>
 	    <programlisting>
               # Global section
               option swap-path code 128 = string;
               option swap-size code 129 = integer 32;
 
               host margaux {
                 ... # Standard lines, see above
                 option swap-path <replaceable>"192.168.4.4:/netswapvolume/netswap"</replaceable>;
                 option swap-size <replaceable>64000</replaceable>;
               }
 	    </programlisting>
 	    <para>The idea is that, at least for a FreeBSD client,
 	      DHCP/BOOTP option code 128 is the path to the NFS swap file,
 	      and option code 129 is the swap size in kilobytes.  Older
 	      versions of <command>dhcpd</command> allowed a syntax of
 	      <literal>option option-128 "...</literal>, which does not
 	      seem to work any more.</para>
 	    <para><filename>/etc/bootptab</filename> would use the
 	      following syntax instead:</para>
 
 	    <para><literal>T128="192.168.4.4:/netswapvolume/netswap":T129=64000
 	      </literal></para>
 	  </step>
 
 	  <step>
 	    <para>On the NFS swap file server, create the swap
 	    file(s)</para>
             <screen>
               &prompt.root; <userinput>mkdir <replaceable>/netswapvolume/netswap</replaceable></userinput>
               &prompt.root; <userinput>cd <replaceable>/netswapvolume/netswap</replaceable></userinput>
               &prompt.root; <userinput>dd if=/dev/zero bs=1024 count=<replaceable>64000</replaceable> of=swap.<replaceable>192.168.4.6</replaceable></userinput>
               &prompt.root; <userinput>chmod 0600 swap.<replaceable>192.168.4.6</replaceable></userinput>
             </screen>
 	    <para><replaceable>192.168.4.6</replaceable> is the IP address
 	      for the diskless client.</para>
 	  </step>
 
 	  <step>
 	    <para>On the NFS swap file server, add the following line to
 	    <filename>/etc/exports</filename>:</para>
 	    <programlisting>
 	      <replaceable>/netswapvolume</replaceable>  -maproot=0:10 -alldirs <replaceable>margaux</replaceable>
 	    </programlisting>
 	    <para>Then tell <application>mountd</application> to reread the
 		exports file, as above.</para>
 	  </step>
 	</procedure>
 
       </sect3>
 
       <sect3>
 	<title>Miscellaneous Issues</title>
 
 
 	<sect4>
 	  <title>Running with a read-only <filename>/usr</filename></title
 	    <para>If the diskless workstation is configured to run X, you
 	    will have to adjust the xdm configuration file, which puts
 	    the error log on <filename>/usr</filename> by default.</para>
 	</sect4>
 	<sect4>
 	  <title>Using a non-FreeBSD Server</title>
 
 	  <para>When the server for the root filesystem is not running FreeBSD,
 	    you will have to create the root filesystem on a
 	    FreeBSD machine, then copy it to its destination, using
 	    <command>tar</command> or <command>cpio</command>.</para>
 	  <para>In this situation, there are sometimes
 	    problems with the special files in <filename>/dev</filename>,
 	    due to differing major/minor integer sizes.  A solution to this
 	    problem is to export a directory from the non-FreeBSD server,
 	    mount this directory onto a FreeBSD machine, and run
 	    <command>MAKEDEV</command> on the FreeBSD machine
 	    to create the correct device entries (FreeBSD 5.0 and later
 	    use &man.devfs.5; to allocate device nodes transparently for
 	    the user, running <command>MAKEDEV</command> on these
 	    versions is useless).</para>
 
 	</sect4>
 
       </sect3>
 
     </sect2>
   </sect1>
 
   <sect1 id="isdn">
     <title>ISDN</title>
 
     <para>A good resource for information on ISDN technology and hardware is
       <ulink url="http://alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN
 	Page</ulink>.</para>
 
     <para>A quick simple road map to ISDN follows:</para>
 
     <itemizedlist>
       <listitem>
         <para>If you live in Europe you might want to investigate the ISDN card
           section.</para>
       </listitem>
 
       <listitem>
 	<para>If you are planning to use ISDN primarily to connect to the
 	  Internet with an Internet Provider on a dial-up non-dedicated basis,
 	  you might look into Terminal Adapters.  This will give you the
 	  most flexibility, with the fewest problems, if you change
 	  providers.</para>
       </listitem>
 
       <listitem>
 	<para>If you are connecting two LANs together, or connecting to the
 	  Internet with a dedicated ISDN connection, you might consider
 	  the stand alone router/bridge option.</para>
       </listitem>
     </itemizedlist>
 
     <para>Cost is a significant factor in determining what solution you will
       choose.  The following options are listed from least expensive to most
       expensive.</para>
 
     <sect2 id="isdn-cards">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Hellmuth</firstname>
             <surname>Michaelis</surname>
             <contrib>Contributed by </contrib>
           </author>
         </authorgroup>
       </sect2info>
       <title>ISDN Cards</title>
 
       <indexterm>
         <primary>ISDN</primary>
         <secondary>cards</secondary>
       </indexterm>
 
       <para>FreeBSD's ISDN implementation supports only the DSS1/Q.931
 	(or Euro-ISDN) standard using passive cards.  Starting with
 	FreeBSD&nbsp;4.4, some active cards are supported where the firmware
 	also supports other signaling protocols; this also includes the
 	first supported Primary Rate (PRI) ISDN card.</para>
 
       <para><application>Isdn4bsd</application> allows you to connect
 	to other ISDN routers using either IP over raw HDLC or by using
 	synchronous PPP: either by using kernel PPP with isppp, a
 	modified sppp driver, or by using userland &man.ppp.8;.  By using
 	userland &man.ppp.8;, channel bonding of two or more ISDN
 	B-channels is possible.  A telephone answering machine
 	application is also available as well as many utilities such as
 	a software 300 Baud modem.</para>
 
       <para>Some growing number of PC ISDN cards are supported under
 	FreeBSD and the reports show that it is successfully used all
 	over Europe and in many other parts of the world.</para>
 
       <para>The passive ISDN cards supported are mostly the ones with
 	the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets,
 	but also ISDN cards with chips from Cologne Chip (ISA bus only),
 	PCI cards with Winbond W6692 chips, some cards with the
 	Tiger300/320/ISAC chipset combinations and some vendor specific
 	chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the
 	AVM Fritz!Card PnP.</para>
 
       <para>Currently the active supported ISDN cards are the AVM B1
 	(ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para>
 
       <para>For documentation on <application>isdn4bsd</application>,
 	have a look at <filename>/usr/share/examples/isdn/</filename>
 	directory on your FreeBSD system or at the <ulink
 	  url="http://www.freebsd-support.de/i4b/">homepage of
 	  isdn4bsd</ulink> which also has pointers to hints, erratas and
 	much more documentation such as the <ulink
 	  url="http://people.FreeBSD.org/~hm/">isdn4bsd
 	  handbook</ulink>.</para>
 
       <para>In case you are interested in adding support for a
 	different ISDN protocol, a currently unsupported ISDN PC card or
 	otherwise enhancing <application>isdn4bsd</application>, please
 	get in touch with &a.hm;.</para>
 
       <para>For questions regarding the installation, configuration
 	and troubleshooting <application>isdn4bsd</application>, a
 	majordomo maintained mailing list is available.  To join, send
 	mail to &a.majordomo; and specify:</para>
 
       <para><literal>subscribe freebsd-isdn</literal></para>
 
       <para>in the body of your message.</para>
     </sect2>
 
     <sect2>
       <title>ISDN Terminal Adapters</title>
 
       <para>Terminal adapters(TA), are to ISDN what modems are to regular
 	phone lines.</para>
       <indexterm><primary>modem</primary></indexterm>
       <para>Most TA's use the standard hayes modem AT command set, and can be
 	used as a drop in replacement for a modem.</para>
 
       <para>A TA will operate basically the same as a modem except connection
 	and throughput speeds will be much faster than your old modem.  You
 	will need to configure <link linkend="ppp">PPP</link> exactly the same
 	as for a modem setup.  Make sure you set your serial speed as high as
 	possible.</para>
       <indexterm><primary>PPP</primary></indexterm>
       <para>The main advantage of using a TA to connect to an Internet
 	Provider is that you can do Dynamic PPP.  As IP address space becomes
 	more and more scarce, most providers are not willing to provide you
 	with a static IP anymore.  Most stand-alone routers are not able to
 	accommodate dynamic IP allocation.</para>
 
       <para>TA's completely rely on the PPP daemon that you are running for
 	their features and stability of connection.  This allows you to
 	upgrade easily from using a modem to ISDN on a FreeBSD machine, if you
 	already have PPP setup.  However, at the same time any problems you
 	experienced with the PPP program and are going to persist.</para>
 
       <para>If you want maximum stability, use the kernel <link
 	  linkend="ppp">PPP</link> option, not the user-land <link
 	  linkend="userppp">iijPPP</link>.</para>
 
       <para>The following TA's are known 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 that, like modems, you need a good
 	serial card in your computer.</para>
 
       <para>You should read the <ulink
 	url="../../articles/serial-uart/index.html">FreeBSD Serial
 	Hardware</ulink> tutorial for a detailed understanding of
 	serial devices, and the differences between asynchronous and
 	synchronous serial ports.</para>
 
       <para>A TA running off a standard PC serial port (asynchronous) limits
 	you to 115.2&nbsp;Kbs, even though you have a 128&nbsp;Kbs connection.
 	To fully utilize the 128&nbsp;Kbs that ISDN is capable of,
 	you must move the TA to a synchronous serial card.</para>
 
       <para>Do not be fooled into buying an internal TA and thinking you have
 	avoided the synchronous/asynchronous issue.  Internal TA's simply have
 	a standard PC serial port chip built into them.  All this will do is
 	save you having to buy another serial cable and find another empty
 	electrical socket.</para>
 
       <para>A synchronous card with a TA is at least as fast as a stand-alone
 	router, and with a simple 386 FreeBSD box driving it, probably more
 	flexible.</para>
 
       <para>The choice of sync/TA v.s. stand-alone router is largely a
 	religious issue.  There has been some discussion of this in
 	the mailing lists.  I suggest you search the <ulink
 	url="../../../../search/index.html">archives</ulink> for
 	the complete discussion.</para>
     </sect2>
 
     <sect2>
       <title>Stand-alone ISDN Bridges/Routers</title>
       <indexterm>
         <primary>ISDN</primary>
 	<secondary>stand-alone bridges/routers</secondary>
       </indexterm>
       <para>ISDN bridges or routers are not at all specific to FreeBSD
 	or any other operating system.  For a more complete
 	description of routing and bridging technology, please refer
 	to a Networking reference book.</para>
 
       <para>In the context of this page, the terms router and bridge will
 	be used interchangeably.</para>
 
       <para>As the cost of low end ISDN routers/bridges comes down, it
 	will likely become a more and more popular choice.  An ISDN
 	router is a small box that plugs directly into your local
 	Ethernet network, and manages its own connection to the other
 	bridge/router.  It has built in software to communicate via
 	PPP and other popular protocols.</para>
 
       <para>A router will allow you much faster throughput than a
 	standard TA, since it will be using a full synchronous ISDN
 	connection.</para>
 
       <para>The main problem with ISDN routers and bridges is that
 	interoperability between manufacturers can still be a problem.
 	If you are planning to connect to an Internet provider, you
 	should discuss your needs with them.</para>
 
       <para>If you are planning to connect two LAN segments together,
 	such as your home LAN to the office LAN, this is the simplest
 	lowest
 	maintenance solution.  Since you are buying the equipment for
 	both sides of the connection you can be assured that the link
 	will work.</para>
 
       <para>For example to connect a home computer or branch office
 	network to a head office network the following setup could be
 	used.</para>
 
       <example>
 	<title>Branch Office or Home Network</title>
 
 	<indexterm><primary>10 base 2</primary></indexterm>
 	<para>Network uses a bus based topology with 10 base 2
 	  Ethernet (<quote>thinnet</quote>).  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
   	  (<quote>Twisted Pair</quote>).</para>
 
         <mediaobject>
           <imageobject>
             <imagedata fileref="advanced-networking/isdn-twisted-pair">
           </imageobject>
 
 	  <textobject>
 	    <literallayout class="monospaced">    -------Novell Server
     | H |
     |   ---Sun
     |   |
     | U ---FreeBSD
     |   |
     |   ---Windows 95
     | B |
     |___---Stand-alone router
                 |
         ISDN BRI line</literallayout>
 	  </textobject>
 
 	  <textobject>
 	    <phrase>ISDN Network Diagram</phrase>
 	  </textobject>
 	</mediaobject>
       </example>
 
       <para>One large advantage of most routers/bridges is that they allow you
 	to have 2 <emphasis>separate independent</emphasis> PPP connections to
 	2 separate sites at the <emphasis>same</emphasis> time.  This is not
 	supported on most TA's, except for specific (usually expensive) models
 	that
 	have two serial ports.  Do not confuse this with channel bonding, MPP,
 	etc.</para>
 
       <para>This can be a very useful feature if, for example, you have an
 	dedicated ISDN connection at your office and would like to
 	tap into it, but do not want to get another ISDN line at work.  A router
 	at the office location can manage a dedicated B channel connection
 	(64&nbsp;Kbps) to the Internet and use the other B channel for a
 	separate data connection.  The second B channel can be used for
 	dial-in, dial-out or dynamically bonding (MPP, etc.) with the first
 	B channel for more bandwidth.</para>
 
       <indexterm><primary>IPX/SPX</primary></indexterm>
       <para>An Ethernet bridge will also allow you to transmit more than just
 	IP traffic.  You can also send IPX/SPX or whatever other protocols you
 	use.</para>
     </sect2>
   </sect1>
 
   <sect1 id="nis">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Bill</firstname>
       	  <surname>Swingle</surname>
 	  <contrib>Written by </contrib>
          </author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Eric</firstname>
 	  <surname>Ogren</surname>
 	  <contrib>Enhanced by </contrib>
 	</author>
 	<author>
 	  <firstname>Udo</firstname>
 	  <surname>Erdelhoff</surname>
 	</author>
       </authorgroup>
     </sect1info>
     <title>NIS/YP</title>
 
     <sect2>
       <title>What Is It?</title>
       <indexterm><primary>NIS</primary></indexterm>
       <indexterm><primary>Solaris</primary></indexterm>
       <indexterm><primary>HP-UX</primary></indexterm>
       <indexterm><primary>AIX</primary></indexterm>
       <indexterm><primary>Linux</primary></indexterm>
       <indexterm><primary>NetBSD</primary></indexterm>
       <indexterm><primary>OpenBSD</primary></indexterm>
       <para>NIS, which stands for Network Information Services, was
         developed by Sun Microsystems to centralize administration of Unix
         (originally SunOS) systems.  It has now essentially become an
         industry standard; all major Unix systems (Solaris, HP-UX, AIX, Linux,
         NetBSD, OpenBSD, FreeBSD, etc) support NIS.</para>
 
       <indexterm><primary>yellow pages</primary><see>NIS</see></indexterm>
       <para>NIS was formerly known as Yellow Pages, but because of
 	trademark issues, Sun changed the name.  The old term (and yp) is
 	still often seen and used.</para>
 
       <indexterm>
         <primary>NIS</primary>
         <secondary>domains</secondary>
       </indexterm>
       <para>It is a RPC-based client/server system that allows a group
 	of machines within an NIS domain to share a common set of
 	configuration files.  This permits a system administrator to set
 	up NIS client systems with only minimal configuration data and
 	add, remove or modify configuration data from a single
 	location.</para>
 
       <indexterm><primary>Windows NT</primary></indexterm>
       <para>It is similar to Windows NT's domain system; although the
         internal implementation of the two are not at all similar,
         the basic functionality can be compared.</para>
     </sect2>
 
     <sect2>
       <title>Terms/Processes You Should Know</title>
 
       <para>There are several terms and several important user processes
         that you will come across when
         attempting to implement NIS on FreeBSD, whether you are trying to
         create an NIS server or act as an NIS client:</para>
 
       <indexterm>
 	<primary><application>portmap</application></primary>
       </indexterm>
 
       <informaltable>
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Term</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  <tbody>
 	    <row>
 	      <entry>NIS domainname</entry>
 	      <entry>An NIS master server and all of its clients
 		(including its slave servers) have a NIS
 		domainname.  Similar to an NT domain name, the NIS
 		domainname does not have anything to do with DNS.</entry>
 	    </row>
 	    <row>
 	      <entry>portmap</entry>
 	      <entry>Must be running in order to enable RPC (Remote
 		Procedure Call, a network protocol used by NIS).  If
 		<command>portmap</command> is not running, it will be
 		impossible to run an NIS server, or to act as an NIS
 		client.</entry>
 	    </row>
 	    <row>
 	      <entry>ypbind</entry>
 
 	      <entry><quote>binds</quote> an NIS client to its NIS
 		server.  It will take the NIS domainname from the
 		system, and using RPC, connect to the
 		server.  <command>ypbind</command> is the core of
 		client-server communication in an NIS environment; if
 		<command>ypbind</command> dies on a client machine, it
 		will not be able to access the NIS server.</entry>
 	    </row>
 	    <row>
 	      <entry>ypserv</entry>
 	      <entry>Should only be running on NIS servers, is the NIS
 		server process itself.  If &man.ypserv.8; dies, then the
 		server will no longer be able to respond to NIS requests
 		(hopefully, there is a slave server to take over for
 		it).  There are some implementations of NIS (but not the
 		FreeBSD one), that do not try to reconnect to another
 		server if the server it used before dies.  Often, the
 		only thing that helps in this case is to restart the
 		server process (or even the whole server) or the
 		<command>ypbind</command> process on the client.
 	      </entry>
 	    </row>
 	    <row>
 	      <entry>rpc.yppasswdd</entry>
 	      <entry>Another process that should only be running on
 		NIS master servers, is a daemon that will allow NIS
 		clients to change their NIS passwords.  If this daemon
 		is not running, users will have to login to the NIS
 		master server and change their passwords there.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
       <!-- XXX Missing: rpc.ypxfrd (not important, though) May only run
       on the master -->
 
     </sect2>
 
     <sect2>
       <title>How Does It Work?</title>
 
       <para>There are three types of hosts in an NIS environment: master
 	servers, slave servers, and clients.  Servers act as a central
 	repository for host configuration information.  Master servers
 	hold the authoritative copy of this information, while slave
 	servers mirror this information for redundancy.  Clients rely on
 	the servers to provide this information to them.</para>
 
       <para>Information in many files can be shared in this manner.  The
 	<filename>master.passwd</filename>, <filename>group</filename>,
 	and <filename>hosts</filename> files are commonly shared via NIS.
 	Whenever a process on a client needs information that would
 	normally be found in these files locally, it makes a query to the
 	NIS server that it is bound to instead.</para>
 
       <sect3>
         <title>Machine Types</title>
 
         <itemizedlist>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>master server</secondary>
 	  </indexterm>
           <listitem>
             <para>A <emphasis>NIS master server</emphasis>.
               This server, analogous to a Windows
               NT primary domain controller, maintains the files used by all
               of the NIS clients.  The <filename>passwd</filename>,
               <filename>group</filename>, and other various files used by the
               NIS clients live on the master server.</para>
 
             <note><para>It is possible for one machine to be an NIS
               master server for more than one NIS domain.  However, this will
               not be covered in this introduction, which assumes a relatively
               small-scale NIS environment.</para></note>
           </listitem>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>slave server</secondary>
 	  </indexterm>
           <listitem>
             <para><emphasis>NIS slave servers</emphasis>.
               Similar to NT's backup domain
               controllers, NIS slave servers maintain copies of the NIS
               master's data files.  NIS slave servers provide the redundancy,
               which is needed in important environments.  They also help
               to balance the load of the master server:  NIS Clients always
               attach to the NIS server whose response they get first, and
               this includes slave-server-replies.</para>
           </listitem>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>client</secondary>
 	  </indexterm>
           <listitem>
             <para><emphasis>NIS clients</emphasis>.  NIS clients, like most
               NT workstations, authenticate against the NIS server (or the NT
               domain controller in the NT Workstation case) to log on.</para>
           </listitem>
         </itemizedlist>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Using NIS/YP</title>
 
       <para>This section will deal with setting up a sample NIS
         environment.</para>
 
       <note><para>This section assumes that you are running FreeBSD&nbsp;3.3
         or later.  The instructions given here will
         <emphasis>probably</emphasis> work for any version of FreeBSD greater
         than 3.0, but there are no guarantees that this is
         true.</para></note>
 
 
       <sect3>
         <title>Planning</title>
 
         <para>Let us assume that you are the administrator of a small
           university lab.  This lab, which consists of 15 FreeBSD machines,
           currently has no centralized point of administration;  each machine
           has its own <filename>/etc/passwd</filename> and
           <filename>/etc/master.passwd</filename>.  These files are kept in
           sync with each other only through manual intervention;
           currently, when you add a user to the lab, you must run
           <command>adduser</command> on all 15 machines.
           Clearly, this has to change, so you have decided to convert the
           lab to use NIS, using two of the machines as servers.</para>
 
         <para>Therefore, the configuration of the lab now looks something
           like:</para>
 
         <informaltable>
           <tgroup cols="3">
             <thead>
               <row>
                 <entry>Machine name</entry>
                 <entry>IP address</entry>
                 <entry>Machine role</entry>
               </row>
             </thead>
             <tbody>
               <row>
                 <entry><hostid>ellington</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.2</hostid></entry>
                 <entry>NIS master</entry>
               </row>
               <row>
                 <entry><hostid>coltrane</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.3</hostid></entry>
                 <entry>NIS slave</entry>
               </row>
               <row>
                 <entry><hostid>basie</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.4</hostid></entry>
                 <entry>Faculty workstation</entry>
               </row>
               <row>
                 <entry><hostid>bird</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.5</hostid></entry>
                 <entry>Client machine</entry>
               </row>
               <row>
                 <entry><hostid>cli[1-11]</hostid></entry>
                 <entry><hostid role="ipaddr">10.0.0.[6-17]</hostid></entry>
                 <entry>Other client machines</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
         <para>If you are setting up a NIS scheme for the first time, it
 	  is a good idea to think through how you want to go about it.  No
 	  matter what the size of your network, there are a few decisions
 	  that need to be made.</para>
 
         <sect4>
           <title>Choosing a NIS Domain Name</title>
 
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>domainname</secondary>
 	  </indexterm>
           <para>This might not be the <quote>domainname</quote> that you
 	    are used to.  It is more accurately called the
 	    <quote>NIS domainname</quote>.  When a client broadcasts its
 	    requests for info, it includes the name of the NIS domain
 	    that it is part of.  This is how multiple servers on one
 	    network can tell which server should answer which request.
 	    Think of the NIS domainname as the name for a group of hosts
 	    that are related in some way.</para>
 
 	  <para>Some organizations choose to use their Internet domainname
 	    for their NIS domainname.  This is not recommended as it can
 	    cause confusion when trying to debug network problems.  The
 	    NIS domainname should be unique within your network and it is
 	    helpful if it describes the group of machines it represents.
 	    For example, the Art department at Acme Inc. might be in the
 	    <quote>acme-art</quote> NIS domain.  For this example, assume you have
             chosen the name <emphasis>test-domain</emphasis>.</para>
 
 	  <indexterm><primary>SunOS</primary></indexterm>
           <para>However, some operating systems (notably SunOS) use their
             NIS domain name as their Internet domain name.
             If one or more machines on your network have this restriction,
             you <emphasis>must</emphasis> use the Internet domain name as
             your NIS domain name.</para>
         </sect4>
 
         <sect4>
           <title>Physical Server Requirements</title>
 
 	  <para>There are several things to keep in mind when choosing a
 	    machine to use as a NIS server.  One of the unfortunate things
 	    about NIS is the level of dependency the clients have on the
 	    server.  If a client cannot contact the server for its NIS
 	    domain, very often the machine becomes unusable.  The lack of
 	    user and group information causes most systems to temporarily
 	    freeze up.  With this in mind you should make sure to choose a
 	    machine that will not be prone to being rebooted regularly, or
 	    one that might be used for development.  The NIS server should
 	    ideally be a stand alone machine whose sole purpose in life is
 	    to be an NIS server.  If you have a network that is not very
 	    heavily used, it is acceptable to put the NIS server on a
 	    machine running other services, just keep in mind that if the
 	    NIS server becomes unavailable, it will affect
 	    <emphasis>all</emphasis> of your NIS clients adversely.</para>
         </sect4>
       </sect3>
 
       <sect3>
         <title>NIS Servers</title>
 
 	<para> The canonical copies of all NIS information are stored on
 	  a single machine called the NIS master server.  The databases
 	  used to store the information are called NIS maps.  In FreeBSD,
 	  these maps are stored in
 	  <filename>/var/yp/[domainname]</filename> where
 	  <filename>[domainname]</filename> is the name of the NIS domain
 	  being served.  A single NIS server can support several domains
 	  at once, therefore it is possible to have several such
 	  directories, one for each supported domain.  Each domain will
 	  have its own independent set of maps.</para>
 
 	<para>NIS master and slave servers handle all NIS requests with
 	  the <command>ypserv</command> daemon.  <command>ypserv</command>
 	  is responsible for receiving incoming requests from NIS clients,
 	  translating the requested domain and map name to a path to the
 	  corresponding database file and transmitting data from the
 	  database back to the client.</para>
 
         <sect4>
 	  <title>Setting Up a NIS Master Server</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>server configuration</secondary>
 	  </indexterm>
 	  <para>Setting up a master NIS server can be relatively straight
 	    forward, depending on your needs.  FreeBSD comes with support
             for NIS out-of-the-box.  All you need is to add the following
             lines to <filename>/etc/rc.conf</filename>, and FreeBSD will
             do the rest for you.</para>
 
           <procedure>
             <step>
               <para><programlisting>nisdomainname="test-domain"</programlisting>
                 This line will set the NIS domainname to
                 <emphasis>test-domain</emphasis>
                 upon network setup (e.g. after reboot).</para>
             </step>
             <step>
               <para><programlisting>nis_server_enable="YES"</programlisting>
                 This will tell FreeBSD to start up the NIS server processes
                 when the networking is next brought up.</para>
             </step>
             <step>
               <para><programlisting>nis_yppasswdd_enable="YES"</programlisting>
                 This will enable the <command>rpc.yppasswdd</command>
                 daemon which, as mentioned above, will allow users to
                 change their NIS password from a client machine.</para>
             </step>
           </procedure>
 
           <note>
             <para>Depending on your NIS setup, you may need to add
               further entries.  See the <link
               linkend="nis-server-is-client">section about NIS servers
               that are also NIS clients</link>, below, for
               details.</para>
           </note>
 
           <para>Now, all you have to do is to run the command
             <command>/etc/netstart</command> as superuser.  It will
             set up everything for you, using the values you defined in
             <filename>/etc/rc.conf</filename>.</para>
         </sect4>
 
         <sect4>
           <title>Initializing the NIS Maps</title>
           <indexterm>
             <primary>NIS</primary>
             <secondary>maps</secondary>
           </indexterm>
           <para>The <emphasis>NIS maps</emphasis> are database files,
             that are kept in the <filename>/var/yp</filename> directory.
             They are generated from configuration files in the
             <filename>/etc</filename> directory of the NIS master, with one
             exception: the <filename>/etc/master.passwd</filename> file.
             This is for a good reason; you do not want to propagate
             passwords to your <username>root</username> and other
 	    administrative accounts to all the servers in the NIS domain.
 	    Therefore, before we initialize the NIS maps, you should:</para>
 
           <screen>&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput>
 &prompt.root; <userinput>cd /var/yp</userinput>
 &prompt.root; <userinput>vi master.passwd</userinput></screen>
 
           <para>You should remove all entries regarding system accounts
             (<username>bin</username>, <username>tty</username>,
 	    <username>kmem</username>, <username>games</username>, etc), as
 	    well as any accounts that you do not want to be propagated to the
 	    NIS clients (for example <username>root</username> and any other
 	    UID 0 (superuser) accounts).</para>
 
           <note><para>Make sure the
             <filename>/var/yp/master.passwd</filename> is neither group
             nor world readable (mode 600)!  Use the
             <command>chmod</command> command, if appropriate.</para></note>
 
 	  <indexterm><primary>Tru64 Unix</primary></indexterm>
           <para>When you have finished, it is time to initialize the NIS
             maps!  FreeBSD includes a script named
             <command>ypinit</command> to do this for you
             (see its manual page for more information).  Note that this
             script is available on most Unix Operating Systems, but not on all.
             On Digital Unix/Compaq Tru64 Unix it is called
             <command>ypsetup</command>.
             Because we are generating maps for an NIS master, we are
             going to pass the <option>-m</option> option to
             <command>ypinit</command>.
             To generate the NIS maps, assuming you already performed
             the steps above, run:</para>
 
           <screen>ellington&prompt.root; <userinput>ypinit -m test-domain</userinput>
 Server Type: MASTER Domain: test-domain
 Creating an YP server will require that you answer a few questions.
 Questions will all be asked at the beginning of the procedure.
 Do you want this procedure to quit on non-fatal errors? [y/n: n] <userinput>n</userinput>
 Ok, please remember to go back and redo manually whatever fails.
 If you don't, something might not work.
 At this point, we have to construct a list of this domains YP servers.
 rod.darktech.org is already known as master server.
 Please continue to add any slave servers, one per line. When you are
 done with the list, type a &lt;control D&gt;.
 master server   :  ellington
 next host to add:  <userinput>coltrane</userinput>
 next host to add:  <userinput>^D</userinput>
 The current list of NIS servers looks like this:
 ellington
 coltrane
 Is this correct?  [y/n: y] <userinput>y</userinput>
 
 [..output from map generation..]
 
 NIS Map update completed.
 ellington has been setup as an YP master server without any errors.</screen>
 
           <para><command>ypinit</command> should have created
             <filename>/var/yp/Makefile</filename> from
             <filename>/var/yp/Makefile.dist</filename>.
             When created, this file assumes that you are operating
             in a single server NIS environment with only FreeBSD
             machines.  Since <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</para>
 
 	  <programlisting>NOPUSH = "True"</programlisting>
 
 	  <para>(if it is not commented out already).</para>
         </sect4>
 
         <sect4>
 	  <title>Setting up a NIS Slave Server</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>configuring a slave server</secondary>
 	  </indexterm>
 	  <para>Setting up an NIS slave server is even more simple than
 	    setting up the master.  Log on to the slave server and edit the
             file <filename>/etc/rc.conf</filename> as you did before.
             The only difference is that we now must use the
             <option>-s</option> option when running <command>ypinit</command>.
             The <option>-s</option> option requires the name of the NIS
             master be passed to it as well, so our command line looks
             like:</para>
 
   <screen>coltrane&prompt.root; <userinput>ypinit -s ellington test-domain</userinput>
 
 Server Type: SLAVE Domain: test-domain Master: ellington
 
 Creating an YP server will require that you answer a few questions.
 Questions will all be asked at the beginning of the procedure.
 
 Do you want this procedure to quit on non-fatal errors? [y/n: n]  <userinput>n</userinput>
 
 Ok, please remember to go back and redo manually whatever fails.
 If you don't, something might not work.
 There will be no further questions. The remainder of the procedure
 should take a few minutes, to copy the databases from ellington.
 Transferring netgroup...
 ypxfr: Exiting: Map successfully transferred
 Transferring netgroup.byuser...
 ypxfr: Exiting: Map successfully transferred
 Transferring netgroup.byhost...
 ypxfr: Exiting: Map successfully transferred
 Transferring master.passwd.byuid...
 ypxfr: Exiting: Map successfully transferred
 Transferring passwd.byuid...
 ypxfr: Exiting: Map successfully transferred
 Transferring passwd.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring group.bygid...
 ypxfr: Exiting: Map successfully transferred
 Transferring group.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring services.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring rpc.bynumber...
 ypxfr: Exiting: Map successfully transferred
 Transferring rpc.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring protocols.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring master.passwd.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring networks.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring networks.byaddr...
 ypxfr: Exiting: Map successfully transferred
 Transferring netid.byname...
 ypxfr: Exiting: Map successfully transferred
 Transferring hosts.byaddr...
 ypxfr: Exiting: Map successfully transferred
 Transferring protocols.bynumber...
 ypxfr: Exiting: Map successfully transferred
 Transferring ypservers...
 ypxfr: Exiting: Map successfully transferred
 Transferring hosts.byname...
 ypxfr: Exiting: Map successfully transferred
 
 coltrane has been setup as an YP slave server without any errors.
 Don't forget to update map ypservers on ellington.</screen>
 
 	  <para>You should now have a directory called
 	    <filename>/var/yp/test-domain</filename>.  Copies of the NIS
 	    master server's maps should be in this directory.  You will
 	    need to make sure that these stay updated.  The following
 	    <filename>/etc/crontab</filename> entries on your slave
 	    servers should do the job:</para>
 
 	  <programlisting>20      *       *       *       *       root   /usr/libexec/ypxfr passwd.byname
 21      *       *       *       *       root   /usr/libexec/ypxfr passwd.byuid</programlisting>
 
 	  <para>These two lines force the slave to sync its maps with
 	    the maps on the master server.  Although these entries are
 	    not mandatory, since the master server attempts to ensure
 	    any changes to its NIS maps are communicated to its slaves
 	    and because password information is vital to systems
 	    depending on the server, it is a good idea to force the
 	    updates.  This is more important on busy networks where map
 	    updates might not always complete.</para>
 
           <para>Now, run the command <command>/etc/netstart</command> on the
             slave server as well, which again starts the NIS server.</para>
 	</sect4>
       </sect3>
 
       <sect3>
         <title>NIS Clients</title>
 
 	<para> An NIS client establishes what is called a binding to a
 	  particular NIS server using the
 	  <command>ypbind</command> daemon.
 	  <command>ypbind</command> checks the system's default
 	  domain (as set by the <command>domainname</command> command),
 	  and begins broadcasting RPC requests on the local network.
 	  These requests specify the name of the domain for which
 	  <command>ypbind</command> is attempting to establish a binding.
 	  If a server that has been configured to serve the requested
 	  domain receives one of the broadcasts, it will respond to
 	  <command>ypbind</command>,  which will record the server's
 	  address.  If there are several servers available (a master and
 	  several slaves, for example), <command>ypbind</command> will
 	  use the address of the first one to respond.  From that point
 	  on, the client system will direct all of its NIS requests to
 	  that server.  <command>ypbind</command> will
 	  occasionally <quote>ping</quote> the server to make sure it is
 	  still up and running.  If it fails to receive a reply to one of
 	  its pings within a reasonable amount of time,
 	  <command>ypbind</command> will mark the domain as unbound and
 	  begin broadcasting again in the hopes of locating another
 	  server.</para>
 
 	<sect4>
 	  <title>Setting Up an NIS Client</title>
 	  <indexterm>
 	    <primary>NIS</primary>
 	    <secondary>client configuration</secondary>
 	  </indexterm>
 	  <para>Setting up a FreeBSD machine to be a NIS client is fairly
 	    straightforward.</para>
 
 	  <procedure>
 	    <step>
 	      <para>Edit the file <filename>/etc/rc.conf</filename> and
                 add the following lines in order to set the NIS domainname
                 and start <command>ypbind</command> upon network
                 startup:</para>
 
 	      <programlisting>nisdomainname="test-domain"
 nis_client_enable="YES"</programlisting>
 	    </step>
 
 	    <step>
 	      <para>To import all possible password entries from the NIS
 		server, remove all user accounts from your
 		<filename>/etc/master.passwd</filename> file and use
 		<command>vipw</command> to add the following line to
                 the end of the file:</para>
 
 	      <programlisting>+:::::::::</programlisting>
 
 	      <note>
 		<para>This line will afford anyone with a valid account in
 		  the NIS server's password maps an account.  There are
 		  many ways to configure your NIS client by changing this
 		  line.  See the <link linkend="netgroups">netgroups
 		  section</link> below for more information.
                   For more detailed reading see O'Reilly's book on
 		  <literal>Managing NFS and NIS</literal>.</para>
 	      </note>
 
               <note>
                 <para>You should keep at least one local account (i.e.
                   not imported via NIS) in your
                   <filename>/etc/master.passwd</filename> and this
                   account should also be a member of the group
                   <groupname>wheel</groupname>.  If there is something
                   wrong with NIS, this account can be used to log in
                   remotely, become root, and fix things.</para>
               </note>
             </step>
 
 	    <step>
 	      <para>To import all possible group entries from the NIS
 		server, add this line to your
 		<filename>/etc/group</filename> file:</para>
 
 	      <programlisting>+:*::</programlisting>
 	    </step>
 	  </procedure>
 
 	  <para>After completing these steps, you should be able to run
 	    <command>ypcat passwd</command> and see the NIS server's
 	    passwd map.</para>
 	</sect4>
       </sect3>
     </sect2>
 
     <sect2>
       <title>NIS Security</title>
 
       <para>In general, any remote user can issue an RPC to &man.ypserv.8; and
 	retrieve the contents of your NIS maps, provided the remote user
 	knows your domainname.  To prevent such unauthorized transactions,
 	&man.ypserv.8; supports a feature called securenets which can be used to
 	restrict access to a given set of hosts.  At startup, &man.ypserv.8; will
 	attempt to load the securenets information from a file called
 	<filename>/var/yp/securenets</filename>.</para>
 
       <note>
 	<para>This path varies depending on the path specified with the
 	  <option>-p</option> option.  This file contains entries that
 	  consist of a network specification and a network mask separated
 	  by white space.  Lines starting with <quote>#</quote> are
 	  considered to be comments.  A sample securenets file might look
 	  like this:</para>
       </note>
 
       <programlisting># allow connections from local host -- mandatory
 127.0.0.1     255.255.255.255
 # allow connections from any host
 # on the 192.168.128.0 network
 192.168.128.0 255.255.255.0
 # allow connections from any host
 # between 10.0.0.0 to 10.0.15.255
 # this includes the machines in the testlab
 10.0.0.0      255.255.240.0</programlisting>
 
       <para>If &man.ypserv.8; receives a request from an address that matches one
 	of these rules, it will process the request normally.  If the
 	address fails to match a rule, the request will be ignored and a
 	warning message will be logged.  If the
 	<filename>/var/yp/securenets</filename> file does not exist,
 	<command>ypserv</command> will allow connections from any host.</para>
 
       <para>The <command>ypserv</command> program also has support for Wietse
 	Venema's
 	<application>tcpwrapper</application> package.  This allows the
 	administrator to use the <application>tcpwrapper</application> configuration
 	files for access control instead of
 	<filename>/var/yp/securenets</filename>.</para>
 
       <note>
         <para>While both of these access control mechanisms provide some
           security, they, like the privileged port test, are
           vulnerable to <quote>IP spoofing</quote> attacks.  All
           NIS-related traffic should be blocked at your firewall.</para>
 
         <para>Servers using <filename>/var/yp/securenets</filename>
           may fail to serve legitimate NIS clients with archaic TCP/IP
           implementations.  Some of these implementations set all
           host bits to zero when doing broadcasts and/or fail to
           observe the subnet mask when calculating the broadcast
           address.  While some of these problems can be fixed by
           changing the client configuration, other problems may force
           the retirement of the client systems in question or the
           abandonment of <filename>/var/yp/securenets</filename>.</para>
 
         <para>Using <filename>/var/yp/securenets</filename> on a
           server with such an archaic implementation of TCP/IP is a
           really bad idea and will lead to loss of NIS functionality
           for large parts of your network.</para>
 
 	<indexterm><primary>tcpwrapper</primary></indexterm>
         <para>The use of the <application>tcpwrapper</application>
           package increases the latency of your NIS server.  The
           additional delay may be long enough to cause timeouts in
           client programs, especially in busy networks or with slow
           NIS servers.  If one or more of your client systems
           suffers from these symptoms, you should convert the client
           systems in question into NIS slave servers and force them
           to bind to themselves.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Barring Some Users from Logging On</title>
 
       <para>In our lab, there is a machine <hostid>basie</hostid> that is
         supposed to be a faculty only workstation.  We do not want to take this
          machine out of the NIS domain, yet the <filename>passwd</filename>
        file on the master NIS server contains accounts for both faculty and
         students.  What can we do?</para>
 
       <para>There is a way to bar specific users from logging on to a
         machine, even if they are present in the NIS database.  To do this,
         all you must do is add
         <emphasis>-<replaceable>username</replaceable></emphasis> to the end of
         the <filename>/etc/master.passwd</filename> file on the client
         machine, where <replaceable>username</replaceable> is the username of
         the user you wish to bar from logging in.  This should preferably be
         done using <command>vipw</command>, since <command>vipw</command>
         will sanity check your changes to
         <filename>/etc/master.passwd</filename>, as well as
         automatically rebuild the password database when you
         finish editing.  For example, if we wanted to bar user
         <emphasis>bill</emphasis> from logging on to <hostid>basie</hostid>
         we would:</para>
 
         <screen>basie&prompt.root; <userinput>vipw</userinput>
 <userinput>[add -bill to the end, exit]</userinput>
 vipw: rebuilding the database...
 vipw: done
 
 basie&prompt.root; <userinput>cat /etc/master.passwd</userinput>
 
 root:[password]:0:0::0:0:The super-user:/root:/bin/csh
 toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
 daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
 operator:*:2:5::0:0:System &:/:/sbin/nologin
 bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
 tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
 kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
 games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
 news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
 man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
 bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
 uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
 xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
 pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
 nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
 +:::::::::
 -bill
 
 basie&prompt.root;</screen>
     </sect2>
 
     <sect2 id="netgroups">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Udo</firstname>
             <surname>Erdelhoff</surname>
             <contrib>Contributed by </contrib>
           </author>
         </authorgroup>
       </sect2info>
 
       <title>Using Netgroups</title>
       <indexterm><primary>netgroups</primary></indexterm>
 
       <para>The method shown in the previous section works reasonably
         well if you need special rules for a very small number of
         users and/or machines.  On larger networks, you
         <emphasis>will</emphasis> forget to bar some users from logging
         onto sensitive machines, or you may even have to modify each
         machine separately, thus losing the main benefit of NIS,
         <emphasis>centralized</emphasis> administration.</para>
 
       <para>The NIS developers' solution for this problem is called
         <emphasis>netgroups</emphasis>.  Their purpose and semantics
         can be compared to the normal groups used by Unix file
         systems.  The main differences are the lack of a numeric id
         and the ability to define a netgroup by including both user
         accounts and other netgroups.</para>
 
       <para>Netgroups were developed to handle large, complex networks
         with hundreds of users and machines.  On one hand, this is
         a Good Thing if you are forced to deal with such a situation.
         On the other hand, this complexity makes it almost impossible to
         explain netgroups with really simple examples.  The example
         used in the remainder of this section demonstrates this
         problem.</para>
 
       <para>Let us assume that your successful introduction of NIS in
         your laboratory caught your superiors' interest.  Your next
         job is to extend your NIS domain to cover some of the other
         machines on campus.  The two tables contain the names of the
         new users and new machines as well as brief descriptions of
         them.</para>
 
       <informaltable>
         <tgroup cols="2">
           <thead>
             <row>
               <entry>User Name(s)</entry>
               <entry>Description</entry>
             </row>
           </thead>
 
           <tbody>
             <row>
               <entry>alpha, beta</entry>
               <entry>Normal employees of the IT department</entry>
             </row>
 
             <row>
               <entry>charlie, delta</entry>
               <entry>The new apprentices of the IT department</entry>
             </row>
 
             <row>
               <entry>echo, foxtrott, golf, ...</entry>
               <entry>Ordinary employees</entry>
             </row>
 
             <row>
               <entry>able, baker, ...</entry>
               <entry>The current interns</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <informaltable>
         <tgroup cols="2">
           <thead>
             <row>
               <entry>Machine Name(s)</entry>
               <entry>Description</entry>
             </row>
           </thead>
 
           <tbody>
             <row>
               <!--  Names taken from "Good Omens" by Neil Gaiman and Terry
                     Pratchett.  Many thanks for a brilliant book.  -->
               <entry>war, death, famine, pollution</entry>
               <entry>Your most important servers.  Only the IT
                 employees are allowed to log onto these
                 machines.</entry>
             </row>
             <row>
               <!-- gluttony was omitted because it was too fat -->
               <entry>pride, greed, envy, wrath, lust, sloth</entry>
               <entry>Less important servers.  All members of the IT
                 department are allowed to login onto these machines.</entry>
             </row>
 
             <row>
               <entry>one, two, three, four, ...</entry>
               <entry>Ordinary workstations.  Only the
                 <emphasis>real</emphasis> employees are allowed to use
                 these machines.</entry>
             </row>
 
             <row>
               <entry>trashcan</entry>
               <entry>A very old machine without any critical data.
                 Even the intern is allowed to use this box.</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>If you tried to implement these restrictions by separately
         blocking each user, you would have to add one
         -<replaceable>user</replaceable> line to each system's
 	<filename>passwd</filename>
         for each user who is not allowed to login onto that system.
         If you forget just one entry, you could be in trouble.  It may
         be feasible to do this correctly during the initial setup,
         however you <emphasis>will</emphasis> eventually forget to add
         the lines for new users during day-to-day operations.  After
         all, Murphy was an optimist.</para>
 
       <para>Handling this situation with netgroups offers several
         advantages.  Each user need not be handled separately;
         you assign a user to one or more netgroups and allow or forbid
         logins for all members of the netgroup.  If you add a new
         machine, you will only have to define login restrictions for
         netgroups.  If a new user is added, you will only have to add
         the user to one or more netgroups.  Those changes are
         independent of each other; no more <quote>for each combination
         of user and machine do...</quote> If your NIS setup is planned
         carefully, you will only have to modify exactly one central
         configuration file to grant or deny access to machines.</para>
 
       <para>The first step is the initialization of the NIS map
         netgroup.  FreeBSD's &man.ypinit.8; does not create this map by
         default, but its NIS implementation will support it once it has
         been created.  To create an empty map, simply type</para>
 
       <screen>ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput></screen>
 
       <para>and start adding content.  For our example, we need at
          least four netgroups: IT employees, IT apprentices, normal
          employees and interns.</para>
 
       <programlisting>IT_EMP  (,alpha,test-domain)    (,beta,test-domain)
 IT_APP  (,charlie,test-domain)  (,delta,test-domain)
 USERS   (,echo,test-domain)     (,foxtrott,test-domain) \
         (,golf,test-domain)
 INTERNS (,able,test-domain)     (,baker,test-domain)</programlisting>
 
       <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc.
         are the names of the netgroups.  Each bracketed group adds
         one or more user accounts to it.  The three fields inside a
         group are:</para>
 
       <orderedlist>
         <listitem>
           <para>The name of the host(s) where the following items are
             valid.  If you do not specify a hostname, the entry is
             valid on all hosts.  If you do specify a hostname, you
             will enter a realm of darkness, horror and utter confusion.</para>
         </listitem>
 
         <listitem>
           <para>The name of the account that belongs to this
             netgroup.</para>
         </listitem>
 
         <listitem>
           <para>The NIS domain for the account.  You can import
             accounts from other NIS domains into your netgroup if you
             are one of the unlucky fellows with more than one NIS
             domain.</para>
         </listitem>
       </orderedlist>
 
       <para>Each of these fields can contain wildcards.  See
         &man.netgroup.5; for details.</para>
 
       <note>
         <indexterm><primary>netgroups</primary></indexterm>
         <para>Netgroup names longer than 8 characters should not be
           used, especially if you have machines running other
           operating systems within your NIS domain.  The names are
           case sensitive; using capital letters for your netgroup
           names is an easy way to distinguish between user, machine
           and netgroup names.</para>
 
         <para>Some NIS clients (other than FreeBSD) cannot handle
           netgroups with a large number of entries.  For example, some
           older versions of SunOS start to cause trouble if a netgroup
           contains more than 15 <emphasis>entries</emphasis>.  You can
           circumvent this limit by creating several sub-netgroups with
           15 users or less and a real netgroup that consists of the
           sub-netgroups:</para>
 
         <programlisting>BIGGRP1  (,joe1,domain)  (,joe2,domain)  (,joe3,domain) [...]
 BIGGRP2  (,joe16,domain)  (,joe17,domain) [...]
 BIGGRP3  (,joe31,domain)  (,joe32,domain)
 BIGGROUP  BIGGRP1 BIGGRP2 BIGGRP3</programlisting>
 
         <para>You can repeat this process if you need more than 225
           users within a single netgroup.</para>
       </note>
 
       <para>Activating and distributing your new NIS map is
         easy:</para>
 
       <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput>
 ellington&prompt.root; <userinput>make</userinput></screen>
 
       <para>This will generate the three NIS maps
         <filename>netgroup</filename>,
         <filename>netgroup.byhost</filename> and
         <filename>netgroup.byuser</filename>.  Use &man.ypcat.1; to
         check if your new NIS maps are available:</para>
 
       <screen>ellington&prompt.user; <userinput>ypcat -k netgroup</userinput>
 ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput>
 ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen>
 
       <para>The output of the first command should resemble the
         contents of <filename>/var/yp/netgroup</filename>.  The second
         command will not produce output if you have not specified
         host-specific netgroups.  The third command can be used to
         get the list of netgroups for a user.</para>
 
       <para>The client setup is quite simple.  To configure the server
         <replaceable>war</replaceable>, you only have to start
         &man.vipw.8; and replace the line</para>
 
       <programlisting>+:::::::::</programlisting>
 
       <para>with</para>
 
       <programlisting>+@IT_EMP:::::::::</programlisting>
 
       <para>Now, only the data for the users defined in the netgroup
         <replaceable>IT_EMP</replaceable> is imported into
         <replaceable>war</replaceable>'s password database and only
         these users are allowed to login.</para>
 
       <para>Unfortunately, this limitation also applies to the ~
 	function of the shell and all routines converting between user
 	names and numerical user ids.  In other words,
 	<command>cd ~<replaceable>user</replaceable></command> will not work,
 	<command>ls -l</command> will show the numerical id instead of
 	the username and <command>find . -user joe -print</command> will
 	fail with <errorname>No such user</errorname>.  To fix this, you will
 	have to import all user entries <emphasis>without allowing them
 	to login onto your servers</emphasis>.</para>
 
       <para>This can be achieved by adding another line to
         <filename>/etc/master.passwd</filename>.  This line should
         contain:</para>
 
       <para><literal>+:::::::::/sbin/nologin</literal>, meaning
         <quote>Import all entries but replace the shell with
         <filename>/sbin/nologin</filename> in the imported
         entries</quote>.  You can replace any field
         in the passwd entry by placing a default value in your
         <filename>/etc/master.passwd</filename>.</para>
 
       <!-- Been there, done that, got the scars to prove it - ue -->
       <warning>
         <para>Make sure that the line
         <literal>+:::::::::/sbin/nologin</literal> is placed after
         <literal>+@IT_EMP:::::::::</literal>.  Otherwise, all user
         accounts imported from NIS will have /sbin/nologin as their
         login shell.</para>
       </warning>
 
       <para>After this change, you will only have to change one NIS
         map if a new employee joins the IT department.  You could use
         a similar approach for the less important servers by replacing
         the old <literal>+:::::::::</literal> in their local version
         of <filename>/etc/master.passwd</filename> with something like
         this:</para>
 
       <programlisting>+@IT_EMP:::::::::
 +@IT_APP:::::::::
 +:::::::::/sbin/nologin</programlisting>
 
       <para>The corresponding lines for the normal workstations
         could be:</para>
 
       <programlisting>+@IT_EMP:::::::::
 +@USERS:::::::::
 +:::::::::/sbin/nologin</programlisting>
 
       <para>And everything would be fine until there is a policy
         change a few weeks later:  The IT department starts hiring
         interns.  The IT interns are allowed to use the normal
         workstations and the less important servers; and the IT
         apprentices are allowed to login onto the main servers.  You
         add a new netgroup IT_INTERN, add the new IT interns to this
         netgroup and start to change the config on each and every
         machine...  As the old saying goes:  <quote>Errors in
         centralized planning lead to global mess</quote>.</para>
 
       <para>NIS' ability to create netgroups from other netgroups can
         be used to prevent situations like these.  One possibility
         is the creation of role-based netgroups.  For example, you
         could create a netgroup called
         <replaceable>BIGSRV</replaceable> to define the login
         restrictions for the important servers, another netgroup
         called <replaceable>SMALLSRV</replaceable> for the less
         important servers and a third netgroup called
         <replaceable>USERBOX</replaceable> for the normal
         workstations.  Each of these netgroups contains the netgroups
         that are allowed to login onto these machines.  The new
         entries for your NIS map netgroup should look like this:</para>
 
       <programlisting>BIGSRV    IT_EMP  IT_APP
 SMALLSRV  IT_EMP  IT_APP  ITINTERN
 USERBOX   IT_EMP  ITINTERN USERS</programlisting>
 
       <para>This method of defining login restrictions works
         reasonably well if you can define groups of machines with
         identical restrictions.  Unfortunately, this is the exception
         and not the rule.  Most of the time, you will need the ability
         to define login restrictions on a per-machine basis.</para>
 
       <para>Machine-specific netgroup definitions are the other
         possibility to deal with the policy change outlined above.  In
         this scenario, the <filename>/etc/master.passwd</filename> of
         each box contains two lines starting with <quote>+</quote>.  The first of
         them adds a netgroup with the accounts allowed to login onto
         this machine, the second one adds all other accounts with
         <filename>/sbin/nologin</filename> as shell.  It is a good
         idea to use the 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 of
         dozen or even hundreds of identical machines for student labs,
         you should use role-based netgroups instead of machine-based
         netgroups to keep the size of the NIS map within reasonable
         limits.</para>
     </sect2>
 
     <sect2>
       <title>Important Things to Remember</title>
 
       <para>There are still a couple of things that you will need to do
         differently now that you are in an NIS environment.</para>
 
       <itemizedlist>
         <listitem>
           <para>Every time you wish to add a user to the lab, you
             must add it to the master NIS server <emphasis>only</emphasis>,
             and <emphasis>you must remember to rebuild the NIS
             maps</emphasis>.  If you forget to do this, the new user will
             not be able to login anywhere except on the NIS master.
             For example, if we needed to add a new user
             <quote>jsmith</quote> to the lab, we would:</para>
 
           <screen>&prompt.root; <userinput>pw useradd jsmith</userinput>
 &prompt.root; <userinput>cd /var/yp</userinput>
 &prompt.root; <userinput>make test-domain</userinput></screen>
 
           <para>You could also run <command>adduser jsmith</command> instead
             of <command>pw useradd jsmith</command>.</para>
         </listitem>
         <listitem>
           <para><emphasis>Keep the administration accounts out of the NIS
             maps</emphasis>.  You do not want to be propagating administrative
             accounts and passwords to machines that will have users that
             should not have access to those accounts.</para>
         </listitem>
         <listitem>
           <para><emphasis>Keep the NIS master and slave
             secure, and minimize their downtime</emphasis>.
             If somebody either hacks or simply turns off
             these machines, they have effectively rendered many people without
             the ability to login to the lab.</para>
 
           <para>This is the chief weakness of any centralized administration
             system, and it is probably the most important weakness.  If you do
             not protect your NIS servers, you will have a lot of angry
             users!</para>
         </listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>NIS v1 Compatibility</title>
 
       <para> FreeBSD's <application>ypserv</application> has some support
 	for serving NIS v1 clients.  FreeBSD's NIS implementation only
 	uses the NIS v2 protocol, however other implementations include
 	support for the v1 protocol for backwards compatibility with older
 	systems.  The <application>ypbind</application> daemons supplied
 	with these systems will try to establish a binding to an NIS v1
 	server even though they may never actually need it (and they may
 	persist in broadcasting in search of one even after they receive a
 	response from a v2 server).  Note that while support for normal
 	client calls is provided, this version of ypserv does not handle
 	v1 map transfer requests; consequently, it cannot be used as a
 	master or slave in conjunction with older NIS servers that only
 	support the v1 protocol.  Fortunately, there probably are not any
 	such servers still in use today.</para>
     </sect2>
 
     <sect2 id="nis-server-is-client">
       <title>NIS Servers that are also NIS Clients</title>
 
       <para> Care must be taken when running ypserv in a multi-server
 	domain where the server machines are also NIS clients.  It is
 	generally a good idea to force the servers to bind to themselves
 	rather than allowing them to broadcast bind requests and possibly
 	become bound to each other.  Strange failure modes can result if
 	one server goes down and others are dependent upon it.
 	Eventually all the clients will time out and attempt to bind to
 	other servers, but the delay involved can be considerable and the
 	failure mode is still present since the servers might bind to each
 	other all over again.</para>
 
       <para>You can force a host to bind to a particular server by running
 	<command>ypbind</command> with the <option>-S</option>
 	flag.  If you do not want to do this manually each time you
         reboot your NIS server, you can add the following lines to
         your <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>nis_client_enable="YES"	# run client stuff as well
 nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</replaceable>"</programlisting>
 
       <para>See &man.ypbind.8; for further information.</para>
     </sect2>
 
     <sect2>
       <title>libscrypt v.s. libdescrypt</title>
       <indexterm>
         <primary>NIS</primary>
 	<secondary>crypto library</secondary>
       </indexterm>
       <para>One of the most common issues that people run into when trying
 	to implement NIS is crypt library compatibility.  If your NIS
 	server is using the DES crypt libraries, it will only support
 	clients that are using DES as well.  To check which one your server
 	and clients are using look at the symlinks in
 	<filename>/usr/lib</filename>.  If the machine is configured to
 	use the DES libraries, it will look something like this:</para>
 
       <screen>&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
 lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 libcrypt.a@ -> libdescrypt.a
 lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 libcrypt.so@ -> libdescrypt.so
 lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 libcrypt.so.2@ -> libdescrypt.so.2
 lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 libcrypt_p.a@ -> libdescrypt_p.a
 -r--r--r--  1 root  wheel  13018 Nov  8 14:27 libdescrypt.a
 lrwxr-xr-x  1 root  wheel     16 Nov  8 14:27 libdescrypt.so@ -> libdescrypt.so.2
 -r--r--r--  1 root  wheel  12965 Nov  8 14:27 libdescrypt.so.2
 -r--r--r--  1 root  wheel  14750 Nov  8 14:27 libdescrypt_p.a</screen>
 
       <para>If the machine is configured to use the standard FreeBSD MD5
 	crypt libraries they will look something like this:</para>
 
       <screen>&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
 lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 libcrypt.a@ -> libscrypt.a
 lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 libcrypt.so@ -> libscrypt.so
 lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 libcrypt.so.2@ -> libscrypt.so.2
 lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 libcrypt_p.a@ -> libscrypt_p.a
 -r--r--r--  1 root  wheel   6194 Nov  8 14:27 libscrypt.a
 lrwxr-xr-x  1 root  wheel     14 Nov  8 14:27 libscrypt.so@ -> libscrypt.so.2
 -r--r--r--  1 root  wheel   7579 Nov  8 14:27 libscrypt.so.2
 -r--r--r--  1 root  wheel   6684 Nov  8 14:27 libscrypt_p.a</screen>
 
       <para>If you have trouble authenticating on an NIS client, this
         is a pretty good place to start looking for possible problems.
         If you want to deploy an NIS server for a heterogenous
         network, you will probably have to use DES on all systems
         because it is the lowest common standard.</para>
     </sect2>
   </sect1>
 
   <sect1 id="dhcp">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Greg</firstname>
       	  <surname>Sutter</surname>
 	  <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>DHCP</title>
 
     <sect2>
       <title>What Is DHCP?</title>
       <indexterm>
         <primary>Dynamic Host Configuration Protocol</primary>
         <see>DHCP</see>
       </indexterm>
       <indexterm>
         <primary>Internet Software Consortium (ISC)</primary>
       </indexterm>
 
       <para>DHCP, the Dynamic Host Configuration Protocol, describes
         the means by which a system can connect to a network and obtain the
         necessary information for communication upon that network.  FreeBSD
         uses the ISC (Internet Software Consortium) DHCP implementation, so
         all implementation-specific information here is for use with the ISC
         distribution.</para>
     </sect2>
 
     <sect2>
       <title>What this Section Covers</title>
 
       <para>This section describes both the client-side and server-side
         components of the ISC DHCP system.  The client-side program,
         <command>dhclient</command>, comes integrated within FreeBSD, and
         the server-side portion is available from the 
         <filename role="package">net/isc-dhcp3</filename> port.  The
         &man.dhclient.8;, &man.dhcp-options.5;, and &man.dhclient.conf.5;
         manual pages, in addition to the references below, are useful
         resources.</para>
     </sect2>
 
     <sect2>
       <title>How It Works</title>
       <indexterm><primary>UDP</primary></indexterm>
       <para>When <command>dhclient</command>, the DHCP client, is executed on
 	the client
         machine, it begins broadcasting requests for configuration
         information.  By default, these requests are on UDP port 68.  The
         server replies on UDP 67, giving the client an IP address and
         other relevant network information such as netmask, router, and
         DNS servers.  All of this information comes in the form of a DHCP
         <quote>lease</quote> and is only valid for a certain time (configured by the
         DHCP server maintainer).  In this manner, stale IP addresses for
         clients no longer connected to the network can be automatically
         reclaimed.</para>
 
       <para>DHCP clients can obtain a great deal of information from
         the server.  An exhaustive list may be found in
         &man.dhcp-options.5;.</para>
     </sect2>
 
     <sect2>
       <title>FreeBSD Integration</title>
 
       <para>FreeBSD fully integrates the ISC DHCP client,
         <command>dhclient</command>.  DHCP client support is provided
         within both the installer and the base system, obviating the need
         for detailed knowledge of network configurations on any network
         that runs a DHCP server.  <command>dhclient</command> has been
         included in all FreeBSD distributions since 3.2.</para>
         <indexterm>
           <primary><application>sysinstall</application></primary>
         </indexterm>
         <para>DHCP is supported by <application>sysinstall</application>.
           When configuring a network interface within sysinstall,
           the first question asked is, <quote>Do you want to try DHCP
           configuration of this interface?</quote>  Answering affirmatively will
           execute <command>dhclient</command>, and if successful, will fill
 	  in the network configuration information automatically.</para>
 
         <para>There are two things you must do to have your system use
 	  DHCP upon startup:</para>
         <indexterm>
           <primary>DHCP</primary>
           <secondary>requirements</secondary>
         </indexterm>
 	<itemizedlist>
 	  <listitem>
             <para>Make sure that the <devicename>bpf</devicename>
 	      device is compiled into your kernel.  To do this, add
 	      <literal>pseudo-device bpf</literal> to your kernel
 	      configuration file, and rebuild the kernel.  For more
 	      information about building kernels, see <xref
 	      linkend="kernelconfig">.</para>
 	    <para>The <devicename>bpf</devicename> device is already
 	      part of the <filename>GENERIC</filename> kernel that is
 	      supplied with FreeBSD, so if you do not have a custom
 	      kernel, you should not need to create one in order to get
 	      DHCP working.</para>
 	    <note>
 	      <para>For those who are particularly security conscious,
 	        you should be warned that <devicename>bpf</devicename>
 		is also the device that allows packet sniffers to work
 		correctly (although they still have to be run as
 		<username>root</username>).  <devicename>bpf</devicename>
 		<emphasis>is</emphasis> required to use DHCP, but if
 		you are very sensitive about security, you probably
 		should not add <devicename>bpf</devicename> to your
 		kernel in the expectation that at some point in the
 		future you will be using DHCP.</para>
 	    </note>
 	  </listitem>
           <listitem>
             <para>Edit your <filename>/etc/rc.conf</filename> to
 	      include the following:</para>
 
             <programlisting>ifconfig_fxp0="DHCP"</programlisting>
 
             <note>
               <para>Be sure to replace <literal>fxp0</literal> with the
                 designation for the interface that you wish to dynamically
                  configure.</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 <filename role="package">net/isc-dhcp3</filename> port in the ports
           collection.  This port contains the full ISC DHCP distribution,
           consisting of client, server, relay agent and documentation.
           </para>
     </sect2>
 
     <sect2>
       <title>Files</title>
       <indexterm>
         <primary>DHCP</primary>
         <secondary>configuration files</secondary>
       </indexterm>
       <itemizedlist>
         <listitem><para><filename>/etc/dhclient.conf</filename></para>
           <para><command>dhclient</command> requires a configuration file,
             <filename>/etc/dhclient.conf</filename>.  Typically the file
             contains only comments, the defaults being reasonably sane.  This
             configuration file is described by the &man.dhclient.conf.5;
             manual page.</para>
         </listitem>
 
         <listitem><para><filename>/sbin/dhclient</filename></para>
           <para><command>dhclient</command> is statically linked and
             resides in <filename>/sbin</filename>.  The &man.dhclient.8;
             manual page gives more information about
             <command>dhclient</command>.</para>
         </listitem>
 
         <listitem><para><filename>/sbin/dhclient-script</filename></para>
           <para><command>dhclient-script</command> is the FreeBSD-specific
             DHCP client configuration script.  It is described in
             &man.dhclient-script.8;, but should not need any user
             modification to function properly.</para>
         </listitem>
 
         <listitem><para><filename>/var/db/dhclient.leases</filename></para>
           <para>The DHCP client keeps a database of valid leases in this
             file, which is written as a log.  &man.dhclient.leases.5;
             gives a slightly longer description.</para>
         </listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
 
       <para>The DHCP protocol is fully described in
         <ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>.
         An informational resource has also been set up at
         <ulink url="http://www.dhcp.org/">dhcp.org</ulink>.</para>
     </sect2>
 
     <sect2 id="dhcp-server">
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Ceri</firstname>
 	    <surname>Davies</surname>
 	    <contrib>Written by </contrib>
 	    <affiliation>
 	      <address><email>ceri@FreeBSD.org</email></address>
 	    </affiliation>
 	  </author>
         </authorgroup>
       </sect2info>
 	<title>Installing And Configuring A DHCP Server</title>
 
 	<sect3>
 	  <title>What this Section Covers</title>
 
 	  <para>This section provides information on how to configure
 	    a FreeBSD system to act as a DHCP server using the ISC
 	    (Internet Software Consortium) implementation of the DHCP
 	    suite.</para>
 
 	  <para>The server portion of the suite is not provided as part of
 	    FreeBSD, and so you will need to install the
 	    <filename role="package">net/isc-dhcp3</filename>
 	    port to provide this service.  See <xref linkend="ports"> for
 	    more information on using the ports collection.</para>
 	</sect3>
 
 	<sect3>
 	  <title>DHCP Server Installation</title>
 	  <indexterm>
 	    <primary>DHCP</primary>
 	    <secondary>installation</secondary>
 	  </indexterm>
 	  <para>In order to configure your FreeBSD system as a DHCP server,
 	    you will need to ensure that the &man.bpf.4;
 	    device is compiled into your kernel.  To do this, add
 	    <literal>pseudo-device bpf</literal> to your kernel
 	    configuration file, and rebuild the kernel.  For more
 	    information about building kernels, see <xref
 	    linkend="kernelconfig">.</para>
 
 	  <para>The <devicename>bpf</devicename> device is already
 	    part of the <filename>GENERIC</filename> kernel that is
 	    supplied with FreeBSD, so you do not need to create a custom
 	    kernel in order to get DHCP working.</para>
 
 	    <note>
 	      <para>Those who are particularly security conscious
 	        should note that <devicename>bpf</devicename>
 		is also the device that allows packet sniffers to work
 		correctly (although such programs still need privileged
 		access).  <devicename>bpf</devicename>
 		<emphasis>is</emphasis> required to use DHCP, but if
 		you are very sensitive about security, you probably
 		should not include <devicename>bpf</devicename> in your
 		kernel purely because you expect to use DHCP at some
 		point in the future.</para>
 	    </note>
 
 	  <para>The next thing that you will need to do is edit the sample
 	    <filename>dhcpd.conf</filename> which was installed by the
 	    <filename role="package">net/isc-dhcp3</filename> port.
 	    By default, this will be
 	    <filename>/usr/local/etc/dhcpd.conf.sample</filename>, and you
 	    should copy this to
 	    <filename>/usr/local/etc/dhcpd.conf</filename> before proceeding
 	    to make changes.</para>
 	</sect3>
 
 	<sect3>
 	  <title>Configuring the DHCP Server</title>
 	  <indexterm>
 	    <primary>DHCP configuration</primary>
 	    <secondary>dhcpd.conf</secondary>
 	  </indexterm>
 	  <para><filename>dhcpd.conf</filename> is
 	    comprised of declarations regarding subnets and hosts, and is
 	    perhaps most easily explained using an example :</para>
 
 	  <programlisting>option domain-name "example.com";<co id="domain-name">
 option domain-name-servers 192.168.4.100;<co id="domain-name-servers">
 option subnet-mask 255.255.255.0;<co id="subnet-mask">
 
 default-lease-time 3600;<co id="default-lease-time">
 max-lease-time 86400;<co id="max-lease-time">
 ddns-update-style none;<co id="ddns-update-style">
 
 subnet 192.168.4.0 netmask 255.255.255.0 {
   range 192.168.4.129 192.168.4.254;<co id="range">
   option routers 192.168.4.1;<co id="routers">
 }
 
 host mailhost {
   hardware ethernet 02:03:04:05:06:07;<co id="hardware">
   fixed-address mailhost.example.com;<co id="fixed-address">
 }</programlisting>
 
 	  <calloutlist>
 	    <callout arearefs="domain-name">
 	      <para>This option specifies the domain that will be provided
 		to clients as the default search domain.  See
 		&man.resolv.conf.5; for more information on what this
 		means.</para>
 	    </callout>
 
 	    <callout arearefs="domain-name-servers">
 	      <para>This option specifies a comma separated list of DNS
 		servers that the client should use.</para>
 	    </callout>
 
 	    <callout arearefs="subnet-mask">
 	      <para>The netmask that will be provided to clients.</para>
 	    </callout>
 
 	    <callout arearefs="default-lease-time">
 	      <para>A client may request a specific length of time that a
 		lease will be valid.  Otherwise the server will assign
 		a lease with this expiry value (in seconds).</para>
 	    </callout>
 
 	    <callout arearefs="max-lease-time">
 	      <para>This is the maximum length of time that the server will
 		lease for.  Should a client request a longer lease, a lease
 		will be issued, although it will only be valid for
 		<literal>max-lease-time</literal> seconds.</para>
 	    </callout>
 
 	    <callout arearefs="ddns-update-style">
 	      <para>This option specifies whether the DHCP server should
 		attempt to update DNS when a lease is accepted or released.
 		In the ISC implementation, this option is
 		<emphasis>required</emphasis>.</para>
 	    </callout>
 
 	    <callout arearefs="range">
 	      <para>This denotes which IP addresses should be used in the
 		pool reserved for allocating to clients.  IP addresses between,
 		and including, the ones stated are handed out to clients.</para>
 	    </callout>
 
 	    <callout arearefs="routers">
 	      <para>Declares the default gateway that will be provided to
 		clients.</para>
 	    </callout>
 
 	    <callout arearefs="hardware">
 	      <para>The hardware MAC address of a host (so that the DHCP server
 		can recognise a host when it makes a request).</para>
 	    </callout>
 
 	    <callout arearefs="fixed-address">
 	      <para>Specifies that the host should always be given the same
 		IP address.  Note that a hostname is OK here, since the DHCP
 		server will resolve the hostname itself before returning the
 		lease information.</para>
 	    </callout>
 	  </calloutlist>
 
 	  <para>Once you have finished writing your
 	    <filename>dhcpd.conf</filename>, you can proceed to start the
 	    server by issuing the following command:</para>
 
 	  <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/isc-dhcpd.sh start</userinput></screen>
 
 	  <para>Should you need to make changes to the configuration of your
 	    server in the future, it is important to note that sending a
 	    <literal>SIGHUP</literal> signal to
 	    <application>dhcpd</application> does <emphasis>not</emphasis>
 	    result in the configuration being reloaded, as it does with most
 	    daemons.  You will need to send a <literal>SIGTERM</literal>
 	    signal to stop the process, and then restart it using the command
 	    above.</para>
 	</sect3>
 
 	<sect3>
 	  <title>Files</title>
 	  <indexterm>
 	    <primary>DHCP</primary>
 	    <secondary>configuration files</secondary>
 	  </indexterm>
 	  <itemizedlist>
 	    <listitem><para><filename>/usr/local/sbin/dhcpd</filename></para>
 	      <para><application>dhcpd</application> is statically linked and
 		resides in <filename>/usr/local/sbin</filename>.  The
 		dhcpd(8) manual page installed with the
 		port gives more information about
 		<application>dhcpd</application>.</para>
 	    </listitem>
 
 	    <listitem><para><filename>/usr/local/etc/dhcpd.conf</filename></para>
 	      <para><application>dhcpd</application> requires a configuration
 		file, <filename>/usr/local/etc/dhcpd.conf</filename> before it
 		will start providing service to clients.  This file needs to
 		contain all the information that should be provided to clients
 		that are being serviced, along with information regarding the
 		operation of the server.  This configuration file is described
 		by the dhcpd.conf(5) manual page installed
 		by the port.</para>
 	    </listitem>
 
 	    <listitem><para><filename>/var/db/dhcpd.leases</filename></para>
 	      <para>The DHCP server keeps a database of leases it has issued
 		in this file, which is written as a log.  The manual page
 		dhcpd.leases(5), installed by the port
 		gives a slightly longer description.</para>
 	    </listitem>
 
 	    <listitem><para><filename>/usr/local/sbin/dhcrelay</filename></para>
 	      <para><application>dhcrelay</application> is used in advanced
 		environments where one DHCP server forwards a request from a
 		client to another DHCP server on a separate network.  The
 		dhcrelay(8) manual page provided with the
 		port contains more detail.</para>
 	    </listitem>
 	  </itemizedlist>
 	</sect3>
 
       </sect2>
 
   </sect1>
 
   <sect1 id="dns">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
           <surname>Lee</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>DNS</title>
 
     <sect2>
       <title>Overview</title>
       <indexterm><primary>BIND</primary></indexterm>
 
       <para>FreeBSD utilizes, by default, a version of BIND (Berkeley
         Internet Name Domain), which is the most common implementation of the
         DNS protocol.  DNS is the protocol through which names are mapped to
         IP addresses, and vice versa.  For example, a query for
 	<hostid>www.FreeBSD.org</hostid>
         will receive a reply with the IP address of The FreeBSD Project's
         web server, whereas, a query for <hostid>ftp.FreeBSD.org</hostid>
 	will return the IP
 	address of the corresponding FTP machine.  Likewise, the opposite can
         happen.  A query for an IP address can resolve its hostname.  It is
 	not necessary to run a name server to perform DNS lookups on a system.
       </para>
 
       <indexterm><primary>DNS</primary></indexterm>
       <para>DNS is coordinated across the Internet through a somewhat
         complex system of authoritative root name servers, and other
         smaller-scale name servers who host and cache individual domain
         information.
       </para>
 
       <para>
         This document refers to BIND 8.x, as it is the stable version
 	used in FreeBSD.  BIND 9.x in FreeBSD can be installed through
 	the <filename role="package">net/bind9</filename> port.
       </para>
 
       <para>
         RFC1034 and RFC1035 dictates the DNS protocol.
       </para>
 
       <para>
         Currently, BIND is maintained by the <ulink
         url="http://www.isc.org/">
         Internet Software Consortium (www.isc.org)</ulink>
       </para>
     </sect2>
 
     <sect2>
       <title>Terminology</title>
 
       <para>To understand this document, some terms related to DNS must be
 	understood.</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Term</entry>
 	      <entry>Definition</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>forward DNS</entry>
 	      <entry>mapping of hostnames to IP addresses</entry>
 	    </row>
 
 	    <row>
 	      <entry>origin</entry>
 	      <entry>refers to the domain covered for the particular zone
 		file</entry>
 	    </row>
 
 	    <row>
 	      <entry>named, bind, name server</entry>
 	      <entry>common names for the BIND name server package within
 		FreeBSD</entry>
 	    </row>
 
 	    <indexterm><primary>resolver</primary></indexterm>
 	    <row>
 	      <entry>resolver</entry>
 	      <entry>a system process through which a
 		machine queries a name server for zone information</entry>
 	    </row>
 
 	    <indexterm><primary>reverse DNS</primary></indexterm>
 	    <row>
 	      <entry>reverse DNS</entry>
 	      <entry>the opposite of forward DNS, mapping of IP addresses to
 		hostnames</entry>
 	    </row>
 
 	    <indexterm><primary>root zone</primary></indexterm>
 	    <row>
 	      <entry>root zone</entry>
 
 	      <entry>literally, a <quote>.</quote>, refers to the
 		root, or beginning zone.  All zones fall under this, as
 		do all files in fall under the root directory.  It is
 		the beginning of the Internet zone hierarchy.</entry>
 	    </row>
 
 	    <row>
 	      <entry>zone</entry>
 	      <entry>Each individual domain, subdomain, or area dictated by
 		DNS</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <indexterm>
 	<primary>zones</primary>
 	<secondary>examples</secondary>
       </indexterm>
 
       <para>Examples of zones:
       </para>
       <itemizedlist>
         <listitem>
           <para>. is the root zone</para>
         </listitem>
         <listitem>
           <para><hostid>org.</hostid> is a zone under the root zone</para>
         </listitem>
         <listitem>
           <para><hostid>example.org</hostid> is a zone under the org. zone</para>
         </listitem>
         <listitem>
           <para><hostid>foo.example.org.</hostid> is a subdomain, a zone under the
              <hostid>example.org.</hostid> zone
           </para>
         </listitem>
         <listitem>
           <para>
             <hostid>1.2.3.in-addr.arpa</hostid> is a zone referencing all IP addresses
 	    which fall under the 3.2.1.* IP space.
           </para>
         </listitem>
       </itemizedlist>
 
       <para>As one can see, the more specific part of a hostname appears to
         its left.  For example, <hostid>example.org.</hostid> is more
         specific than <hostid>org.</hostid>, as <hostid>org.</hostid> is
         more specific than the root zone.  The layout of each part of
         a hostname is much like a filesystem: the <filename>/dev</filename>
         directory falls within the root, and so on.</para>
 
 
     </sect2>
 
     <sect2>
       <title>Reasons to Run a Name Server</title>
 
       <para>Name servers usually come in two forms: an authoritative
 	name server, and a caching name server.</para>
 
       <para>An authoritative name server is needed when:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>one wants to serve DNS information to the
 	    world, replying authoritatively to queries.</para>
 	</listitem>
 	<listitem>
 	  <para>a domain, such as <hostid>example.org</hostid>, is
 	    registered and IP addresses need to be assigned to hostnames
 	    under it.</para>
 	</listitem>
 	<listitem>
 	  <para>an IP address block requires reverse DNS entries (IP to
 	    hostname).</para>
 	</listitem>
 	<listitem>
 	  <para>a backup name server, called a slave, must reply to queries
 	    when the primary is down or inaccessible.</para>
 	  </listitem>
       </itemizedlist>
 
       <para>A caching name server is needed when:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>a local DNS server may cache and respond more quickly
 	    then querying an outside name server.</para>
 	</listitem>
 	<listitem>
 	  <para>a reduction in overall network traffic is desired (DNS
 	    traffic has been measured to account for 5% or more of total
 	    Internet traffic).</para>
 	</listitem>
       </itemizedlist>
 
       <para>When one queries for <hostid>www.FreeBSD.org</hostid>, the
 	resolver usually queries the uplink ISP's name server, and retrieves
 	the reply.  With a local, caching DNS server, the query only has to
 	be made once to the outside world by the caching DNS server.  Every
 	additional query will not have to look to the outside of the local
 	network, since the information is cached locally.</para>
 
     </sect2>
 
     <sect2>
       <title>How It Works</title>
       <para>In FreeBSD, the BIND daemon is called
 	<application>named</application> for obvious reasons.</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>File</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><application>named</application></entry>
 	      <entry>the BIND daemon</entry>
 	    </row>
 
 	    <row>
 	      <entry><command>ndc</command></entry>
 	      <entry>name daemon control program</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>/etc/namedb</filename></entry>
 	      <entry>directory where BIND zone information resides</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename>/etc/namedb/named.conf</filename></entry>
 	      <entry>daemon configuration file</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>
         Zone files are usually contained within the
         <filename>/etc/namedb</filename>
         directory, and contain the DNS zone information
 	served by the name server.
       </para>
     </sect2>
 
     <sect2>
       <title>Starting BIND</title>
       <indexterm>
         <primary>BIND</primary>
 	<secondary>starting</secondary>
       </indexterm>
       <para>
         Since BIND is installed by default, configuring it all is
         relatively simple.
       </para>
       <para>
         To ensure the named daemon is started at boot, put the following
          modifications in <filename>/etc/rc.conf</filename>:
       </para>
       <programlisting>named_enable="YES"</programlisting>
       <para>To start the daemon manually (after configuring it)</para>
       <screen>&prompt.root; <userinput>ndc start</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Configuration Files</title>
       <indexterm>
         <primary>BIND</primary>
 	<secondary>configuration files</secondary>
       </indexterm>
       <sect3>
         <title>make-localhost</title>
         <para>Be sure to:
         </para>
         <screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
 &prompt.root; <userinput>sh make-localhost</userinput></screen>
         <para>to properly create the local reverse DNS zone file in
           <filename>/etc/namedb/localhost.rev</filename>.
         </para>
       </sect3>
 
       <sect3>
         <title><filename>/etc/namedb/named.conf</filename></title>
 
         <programlisting>// &dollar;FreeBSD$
 //
 // Refer to the named(8) manual page for details.  If you are ever going
 // to setup a primary server, make sure you've understood the hairy
 // details of how DNS is working.  Even with simple mistakes, you can
 // break connectivity for affected parties, or cause huge amount of
 // useless Internet traffic.
 
 options {
         directory "/etc/namedb";
 
 // In addition to the "forwarders" clause, you can force your name
 // server to never initiate queries of its own, but always ask its
 // forwarders only, by enabling the following line:
 //
 //      forward only;
 
 // If you've got a DNS server around at your upstream provider, enter
 // its IP address here, and enable the line below.  This will make you
 // benefit from its cache, thus reduce overall DNS traffic in the
 Internet.
 /*
         forwarders {
                 127.0.0.1;
         };
 */</programlisting>
 
         <para>
 	  Just as the comment says, to benefit from an uplink's cache,
           <literal>forwarders</literal> can be enabled here.  Under normal
           circumstances, a name server will recursively query the Internet
           looking at certain name servers until it finds the answer it is
           looking for.  Having this enabled will have it query the uplink's
           name server (or name server provided) first, taking advantage of
           its cache.  If the uplink name server in question is a heavily
           trafficked, fast name server, enabling this may be worthwhile.
         </para>
 
 	<warning><para><hostid role="ipaddr">127.0.0.1</hostid>
             will <emphasis>not</emphasis> work here.
             Change this IP address to a name server at your uplink.</para>
         </warning>
 
         <programlisting>        /*
          * If there is a firewall between you and name servers you want
          * to talk to, you might need to uncomment the query-source
          * directive below.  Previous versions of BIND always asked
          * questions using port 53, but BIND 8.1 uses an unprivileged
          * port by default.
          */
         // query-source address * port 53;
 
         /*
          * If running in a sandbox, you may have to specify a different
          * location for the dumpfile.
          */
         // dump-file "s/named_dump.db";
 };
 
 // Note: the following will be supported in a future release.
 /*
 host { any; } {
         topology {
                 127.0.0.0/8;
         };
 };
 */
 
 // Setting up secondaries is way easier and the rough picture for this
 // is explained below.
 //
 // If you enable a local name server, don't forget to enter 127.0.0.1
 // into your /etc/resolv.conf so this server will be queried first.
 // Also, make sure to enable it in /etc/rc.conf.
 
 zone "." {
         type hint;
         file "named.root";
 };
 
 zone "0.0.127.IN-ADDR.ARPA" {
         type master;
         file "localhost.rev";
 };
 
 zone
 "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.INT" {
         type master;
         file "localhost.rev";
 };
 
 // NB: Do not use the IP addresses below, they are faked, and only
 // serve demonstration/documentation purposes!
 //
 // Example secondary config entries.  It can be convenient to become
 // a secondary at least for the zone where your own domain is in.  Ask
 // your network administrator for the IP address of the responsible
 // primary.
 //
 // Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
 // (This is the first bytes of the respective IP address, in reverse
 // order, with ".IN-ADDR.ARPA" appended.)
 //
 // Before starting to setup a primary zone, better make sure you fully
 // understand how DNS and BIND works, however.  There are sometimes
 // unobvious pitfalls.  Setting up a secondary is comparably simpler.
 //
 // NB: Don't blindly enable the examples below. :-)  Use actual names
 // and addresses instead.
 //
 // NOTE!!! FreeBSD runs bind in a sandbox (see named_flags in rc.conf).
 // The directory containing the secondary zones must be write accessible
 // to bind.  The following sequence is suggested:
 //
 //      mkdir /etc/namedb/s
 //      chown bind:bind /etc/namedb/s
 //      chmod 750 /etc/namedb/s</programlisting>
 
 	<para>For more information on running BIND in a sandbox, see
 	  <link linkend="named-sandbox">Running named in a sandbox</link>.
 	</para>
 
 	<programlisting>/*
 zone "example.com" {
         type slave;
         file "s/example.com.bak";
         masters {
                 192.168.1.1;
         };
 };
 
 zone "0.168.192.in-addr.arpa" {
         type slave;
         file "s/0.168.192.in-addr.arpa.bak";
         masters {
                 192.168.1.1;
         };
 };
 */</programlisting>
         <para>In <filename>named.conf</filename>, these are examples of slave
 	  entries for a forward and reverse zone.</para>
 
         <para>For each new zone served, a new zone entry must be added to
 	  <filename>named.conf</filename></para>
 
         <para>For example, the simplest zone entry for
 	  <hostid role="domainname">example.org</hostid> can look like:</para>
 
         <programlisting>zone "example.org" {
 	type master;
 	file "example.org";
 };</programlisting>
 
 	<para>The zone is a master, as indicated by the <option>type</option>
 	  statement, holding its zone information in
 	  <filename>/etc/namedb/example.org</filename> indicated by
 	  the <option>file</option> statement.</para>
 
         <programlisting>zone "example.org" {
 	type slave;
 	file "example.org";
 };</programlisting>
 
         <para>In the slave case, the zone information is transferred from
 	  the master name server for the particular zone, and saved in the
 	  file specified.  If and when the master server dies or is
 	  unreachable, the slave name server will have the transferred
 	  zone information and will be able to serve it.</para>
       </sect3>
 
       <sect3>
         <title>Zone Files</title>
         <para>
           An example master zone file for <hostid>example.org</hostid>
 	  (existing within <filename>/etc/namedb/example.org</filename>)
 	  is as follows:
         </para>
 
         <programlisting>$TTL 3600
 
 example.org. IN SOA ns1.example.org. admin.example.org. (
                         5               ; Serial
                         10800           ; Refresh
                         3600            ; Retry
                         604800          ; Expire
                         86400 )         ; Minimum TTL
 
 ; DNS Servers
 @       IN NS           ns1.example.org.
 @       IN NS           ns2.example.org.
 
 ; Machine Names
 localhost       IN A    127.0.0.1
 ns1             IN A    3.2.1.2
 ns2             IN A    3.2.1.3
 mail            IN A    3.2.1.10
 @               IN A    3.2.1.30
 
 ; Aliases
 www             IN CNAME        @
 
 ; MX Record
 @               IN MX   10      mail.example.org.</programlisting>
 
         <para>
           Note that every hostname ending in a <quote>.</quote> is an
           exact hostname, whereas everything without a trailing
           <quote>.</quote> is referenced to the origin.  For example,
           <literal>www</literal> is translated into <literal>www +
 	    origin</literal>.  In our fictitious zone file, our origin
           is <hostid>example.org.</hostid>, so
           <literal>www</literal> would translate to
           <hostid>www.example.org.</hostid>
         </para>
 
         <para>
           The format of a zone file follows:
         </para>
         <programlisting>recordname      IN recordtype   value</programlisting>
 
 	<indexterm>
 	  <primary>DNS</primary>
 	  <secondary>records</secondary>
 	</indexterm>
         <para>
           The most commonly used DNS records:
         </para>
 
 	<variablelist>
 	  <varlistentry>
 	    <term>SOA</term>
 
 	    <listitem><para>start of zone authority</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>NS</term>
 
 	    <listitem><para>an authoritative name server</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>A</term>
 
 	    <listitem><para>A host address</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>CNAME</term>
 
 	    <listitem><para>the canonical name for an alias</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>MX</term>
 
 	    <listitem><para>mail exchanger</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term>PTR</term>
 
 	    <listitem><para>a domain name pointer (used in reverse DNS)
 	      </para></listitem>
 	  </varlistentry>
 	</variablelist>
 
         <programlisting>
 example.org. IN SOA ns1.example.org. admin.example.org. (
                         5               ; Serial
                         10800           ; Refresh after 3 hours
                         3600            ; Retry after 1 hour
                         604800          ; Expire after 1 week
                         86400 )         ; Minimum TTL of 1 day</programlisting>
 
 
 
 	<variablelist>
 	  <varlistentry>
 	    <term><hostid>example.org.</hostid></term>
 
 	    <listitem><para>the domain name, also the origin for this
 		zone file.</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><hostid>ns1.example.org.</hostid></term>
 
 	    <listitem><para>the primary/authoritative name server for this
 		zone</para></listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>admin.example.org.</literal></term>
 
 	    <listitem><para>the responsible person for this zone,
 		email address with @
           replaced.  (<email>admin@example.org</email> becomes
 		<literal>admin.example.org</literal>)</para>
 	    </listitem>
 	  </varlistentry>
 
 	  <varlistentry>
 	    <term><literal>5</literal></term>
 
 	      <listitem><para>the serial number of the file.  this
 		  must be incremented each time the zone file is modified.
 		  Nowadays, many admins prefer a
 		  <literal>yyyymmddrr</literal> format for the serial
 		  number.  2001041002 would mean last modified 04/10/2001,
 		  the latter 02 being the second time the zone file has
 		  been modified this day.  The serial number is important
 		  as it alerts slave name servers for a zone when it is
 		  updated.</para>
 	      </listitem>
 	  </varlistentry>
 	</variablelist>
 
         <programlisting>
 @       IN NS           ns1.example.org.</programlisting>
 
         <para>
           This is an <varname>NS</varname> entry.  Every name server that is going to reply
           authoritatively for the zone must have one of these entries.
 	  The <literal>@</literal> as seen here could have been
 	  <hostid role="domainname">example.org.</hostid>
 	  The <literal>@</literal> translates to the origin.
         </para>
 
         <programlisting>
 localhost       IN A    127.0.0.1
 ns1             IN A    3.2.1.2
 ns2             IN A    3.2.1.3
 mail            IN A    3.2.1.10
 @               IN A    3.2.1.30</programlisting>
 
         <para>
           The A record indicates machine names.  As seen above,
           <hostid>ns1.example.org</hostid> would resolve to
           <hostid role="ipaddr">3.2.1.2</hostid>.  Again,
           the origin symbol, <literal>@</literal>, is
           used here, thus meaning <hostid>example.org</hostid>
           would resolve to <hostid role="ipaddr">3.2.1.30</hostid>.
         </para>
 
         <programlisting>
 www             IN CNAME        @</programlisting>
 
         <para>
           The canonical name record is usually used for giving aliases
           to a machine.  In the example, <hostid>www</hostid> is
           aliased to the machine addressed to the origin, or
           <hostid>example.org</hostid>
           (<hostid role="ipaddr">3.2.1.30</hostid>).
           <varname>CNAME</varname>s can be used to provide alias
           hostnames, or round robin one hostname among multiple
           machines.
         </para>
 
         <programlisting>
 @               IN MX   10      mail.example.org.</programlisting>
 
         <para>
           The <varname>MX</varname> record indicates which mail servers are responsible
           for handling incoming mail for the zone.
           <hostid role="fqdn">mail.example.org</hostid> is the hostname of the mail server,
           and 10 being the priority of that mail server.
         </para>
 
         <para>
           One can have several mail servers, with priorities of 3, 2,
           1.  A mail server attempting to deliver to <hostid role="domainname">example.org</hostid>
           would first try the highest priority MX, then the second
           highest, etc, until the mail can be properly delivered.
         </para>
 
         <para>
           For in-addr.arpa zone files (reverse DNS), the same format is
           used, except with <varname>PTR</varname> entries instead of
 	  <varname>A</varname> or <varname>CNAME</varname>.
         </para>
 
         <programlisting>$TTL 3600
 
 1.2.3.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
                         5               ; Serial
                         10800           ; Refresh
                         3600            ; Retry
                         604800          ; Expire
                         3600 )          ; Minimum
 
 @       IN NS   ns1.example.org.
 @       IN NS   ns2.example.org.
 
 2       IN PTR  ns1.example.org.
 3       IN PTR  ns2.example.org.
 10      IN PTR  mail.example.org.
 30      IN PTR  example.org.</programlisting>
         <para>
          This file gives the proper IP address to hostname mappings of our above
          fictitious domain.
         </para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Caching Name Server</title>
       <indexterm>
         <primary>BIND</primary>
         <secondary>caching name server</secondary>
       </indexterm>
       <para>
         A caching name server is a name server that is not
         authoritative for any zones.  It simply asks queries of its own,
         and remembers them for later use.  To set one up, just configure
         the name server as usual, omitting any inclusions of zones.
       </para>
     </sect2>
 
     <sect2 id="named-sandbox">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Ceri</firstname>
             <surname>Davies</surname>
             <contrib>Contributed by </contrib>
           </author>
         </authorgroup>
       </sect2info>
 
       <title>Running named in a Sandbox</title>
       <indexterm>
         <primary>BIND</primary>
         <secondary>running in a sandbox</secondary>
       </indexterm>
 
       <indexterm>
         <primary><command>chroot</command></primary>
       </indexterm>
       <para>For added security you may want to run &man.named.8; as an
 	unprivileged user, and configure it to &man.chroot.8; into a
 	sandbox directory.  This makes everything outside of the sandbox
 	inaccessible to the <application>named</application> daemon.  Should
 	<application>named</application> be compromised, this will help to
 	reduce the damage that can be caused.  By default, FreeBSD has a user
 	and a group called <groupname>bind</groupname>, intended for this
 	use.</para>
 
       <note><para>Various people would recommend that instead of configuring
 	<application>named</application> to <command>chroot</command>, you
 	should run <application>named</application> inside a &man.jail.8;.
 	This section does not attempt to cover this situation.</para>
       </note>
 
       <para>Since <application>named</application> will not be able to
 	access anything outside of the sandbox (such as shared
 	libraries, log sockets, and so on), there are a number of steps
 	that need to be followed in order to allow
 	<application>named</application> to function correctly.  In the
 	following checklist, it is assumed that the path to the sandbox
 	is <filename>/etc/namedb</filename> and that you have made no
 	prior modifications to the contents of this directory.  Perform
 	the following steps as <username>root</username>.</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Create all directories that <application>named</application>
 	    expects to see:</para>
 
 	  <screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
 &prompt.root; <userinput>mkdir -p bin dev etc var/tmp var/run master slave</userinput>
 &prompt.root; <userinput>chown bind:bind slave var/*</userinput><co id="chown-slave"></screen>
 
 
 
 	  <calloutlist>
 	    <callout arearefs="chown-slave">
 	      <para><application>named</application> only needs write access to
 		these directories, so that is all we give it.</para>
 	    </callout>
 	  </calloutlist>
 	</listitem>
 
 	<listitem>
 	  <para>Rearrange and create basic zone and configuration files:</para>
 	  <screen>&prompt.root; <userinput>cp /etc/localtime etc</userinput><co id="localtime">
 &prompt.root; <userinput>mv named.conf etc && ln -sf etc/named.conf</userinput>
 &prompt.root; <userinput>mv named.root master</userinput>
 <!-- I don't like this next bit -->
 &prompt.root; <userinput>sh make-localhost && mv localhost.rev localhost-v6.rev master</userinput>
 &prompt.root; <userinput>cat > master/named.localhost
 $ORIGIN localhost.
 $TTL 6h
 @	IN	SOA	localhost. postmaster.localhost. (
 			1	; serial
 			3600	; refresh
 			1800	; retry
 			604800	; expiration
 			3600 )	; minimum
 	IN	NS	localhost.
 	IN	A		127.0.0.1
 ^D</userinput></screen>
 
 	  <calloutlist>
 	    <callout arearefs="localtime">
 	      <para>This allows <application>named</application> to log the
 		correct time to &man.syslogd.8;</para>
 	    </callout>
 	  </calloutlist>
 	</listitem>
 
 	<listitem>
 	  <para>Build a statically linked copy of
 	    <application>named-xfer</application>, and copy it into the sandbox:</para>
 
 	      <screen>&prompt.root; <userinput>cd /usr/src/lib/libisc && make clean all</userinput>
 &prompt.root; <userinput>cd /usr/src/lib/libbind && make clean all</userinput>
 &prompt.root; <userinput>cd /usr/src/libexec/named-xfer && make NOSHARED=yes all</userinput>
 &prompt.root; <userinput>cp named-xfer /etc/namedb/bin && chmod 555 /etc/namedb/bin/named-xfer</userinput><co id="clean-cruft"></screen>
          <calloutlist>
            <callout arearefs="clean-cruft">
              <para>This step has been reported to fail occasionally.  If this
                happens to you, then issue the command:</para>
 
                  <screen>&prompt.root; <userinput>cd /usr/src && make cleandir && make cleandir</userinput></screen>
 
              <para>This will clean out any <quote>cruft</quote> from your
                source tree, and retrying the steps above should then work.</para>
            </callout>
          </calloutlist>
 	</listitem>
 
 	<listitem>
 	  <para>Make a <devicename>dev/null</devicename> that
 	    <application>named</application> can see and write to:</para>
 
 	  <screen>&prompt.root; <userinput>cd /etc/namedb/dev && mknod null c 2 2</userinput>
 &prompt.root; <userinput>chmod 666 null</userinput></screen>
 	</listitem>
 
 	<listitem>
 	  <para>Symlink <filename> /var/run/ndc</filename> to
 	    <filename>/etc/namedb/var/run/ndc</filename>:</para>
 
 	  <screen>&prompt.root; <userinput>ln -sf /etc/namedb/var/run/ndc /var/run/ndc</userinput></screen>
 
 	  <note>
 	    <para>This simply avoids having to specify the
 	      <option>-c</option> option to &man.ndc.8; every time you
 	      run it.  Since the contents of /var/run are deleted on boot,
 	      if this is something that you find useful you
 	      may wish to add this command to root's crontab, making use
 	      of the <option>@reboot</option> option.  See
 	      &man.crontab.5; for more information regarding
 	      this.</para>
 	  </note>
 
 	</listitem>
 
 	<listitem>
 	  <para>Configure &man.syslogd.8; to create an extra
 	    <devicename>log</devicename> socket that
 	    <application>named</application> can write to.  To do this,
 	    add <literal>-l /etc/namedb/dev/log</literal> to the
 	    <varname>syslogd_flags</varname> variable in
 	    <filename>/etc/rc.conf</filename>.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Arrange to have <application>named</application> start
 	    and <command>chroot</command> itself to the sandbox by
 	    adding the following to
 	    <filename>/etc/rc.conf</filename>:</para>
 
 	  <programlisting>named_enable="YES"
 named_flags="-u bind -g bind -t /etc/namedb /etc/named.conf"</programlisting>
 
 	  <note>
 	    <para>Note that the configuration file
 	    <replaceable>/etc/named.conf</replaceable> is denoted by a full
 	    pathname <emphasis>relative to the sandbox</emphasis>, i.e. in
 	    the line above, the file referred to is actually
 	    <filename>/etc/namedb/etc/named.conf</filename>.</para>
 	  </note>
 	</listitem>
       </itemizedlist>
 
       <para>The next step is to edit
 	<filename>/etc/namedb/etc/named.conf</filename> so that
 	<application>named</application> knows which zones to load and
 	where to find them on the disk.  There follows a commented
 	example (anything not specifically commented here is no
 	different from the setup for a DNS server not running in a
 	sandbox):</para>
 
 	<programlisting>options {
         directory "/";<co id="directory">
         named-xfer "/bin/named-xfer";<co id="named-xfer">
         version "";		// Don't reveal BIND version
         query-source address * port 53;
 };
 // ndc control socket
 controls {
         unix "/var/run/ndc" perm 0600 owner 0 group 0;
 };
 // Zones follow:
 zone "localhost" IN {
         type master;
         file "master/named.localhost";<co id="master">
         allow-transfer { localhost; };
         notify no;
 };
 zone "0.0.127.in-addr.arpa" IN {
         type master;
         file "master/localhost.rev";
         allow-transfer { localhost; };
         notify no;
 };
 zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.int" {
 	type master;
 	file "master/localhost-v6.rev";
 	allow-transfer { localhost; };
 	notify no;
 };
 zone "." IN {
         type hint;
         file "master/named.root";
 };
 zone "private.example.net" in {
         type master;
         file "master/private.example.net.db";
 	allow-transfer { 192.168.10.0/24; };
 };
 zone "10.168.192.in-addr.arpa" in {
         type slave;
         masters { 192.168.10.2; };
         file "slave/192.168.10.db";<co id="slave">
 };</programlisting>
 
       <calloutlist>
 	<callout arearefs="directory">
 	  <para>The
 	    <literal>directory</literal> statement is specified as
 	    <filename>/</filename>, since all files that
 	    <application>named</application> needs are within this
 	    directory (recall that this is equivalent to a
 	    <quote>normal</quote> user's
 	    <filename>/etc/namedb</filename>.</para>
 	</callout>
 
 	<callout arearefs="named-xfer">
 	  <para>Specifies the full path
 	    to the <command>named-xfer</command> binary (from
 	    <application>named</application>'s frame of reference).  This
 	    is necessary since <application>named</application> is
 	    compiled to look for <command>named-xfer</command> in
 	    <filename>/usr/libexec</filename> by default.</para>
 	</callout>
 	<callout arearefs="master"><para>Specifies the filename (relative
 	  to the <literal>directory</literal> statement above) where
 	  <application>named</application> can find the zonefile for this
 	  zone.</para>
 	</callout>
 	<callout arearefs="slave"><para>Specifies the filename
 	    (relative to the <literal>directory</literal> statement above)
 	    where <application>named</application> should write a copy of
 	    the zonefile for this zone after successfully transferring it
 	    from the master server.  This is why we needed to change the
 	    ownership of the directory <filename>slave</filename> to
 	    <groupname>bind</groupname> in the setup stages above.</para>
 	</callout>
       </calloutlist>
 
       <para>After completing the steps above, either reboot your
 	server or restart &man.syslogd.8; and start &man.named.8;, making
 	sure to use the new options specified in
 	<varname>syslogd_flags</varname> and
 	<varname>named_flags</varname>.  You should now be running a
 	sandboxed copy of <application>named</application>!</para>
 
     </sect2>
 
     <sect2>
       <title>Security</title>
 
       <para>Although BIND is the most common implementation of DNS,
         there is always the issue of security.  Possible and
         exploitable security holes are sometimes found.
       </para>
 
       <para>
         It is a good idea to subscribe to <ulink
         url="http://www.cert.org/">CERT</ulink> and
         <ulink url="../handbook/eresources.html#ERESOURCES-MAIL">freebsd-security-notifications</ulink>
         to stay up to date with the current Internet and FreeBSD security
         issues.
       </para>
 
       <tip><para>If a problem arises, keeping sources up to date and having a
         fresh build of named would not hurt.</para></tip>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
       <para>
         BIND/named manual pages: &man.ndc.8; &man.named.8; &man.named.conf.5;
       </para>
 
       <itemizedlist>
 	<listitem>
 	  <para><ulink
 	      url="http://www.isc.org/products/BIND/">Official ISC Bind
 	      Page</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	  url="http://www.nominum.com/resources/faqs/bind-faqs.html">
 	  BIND FAQ</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink url="http://www.oreilly.com/catalog/dns4/">O'Reilly
          DNS and BIND 4th Edition</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="ftp://ftp.isi.edu/in-notes/rfc1034.txt">RFC1034
 	      - Domain Names - Concepts and Facilities</ulink></para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="ftp://ftp.isi.edu/in-notes/rfc1035.txt">RFC1035
 	      - Domain Names - Implementation and Specification</ulink></para>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="ntp">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Hukins</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>NTP</title>
 
     <indexterm><primary>NTP</primary></indexterm>
 
     <sect2>
       <title>Overview</title>
 
       <para>Over time, a computer's clock is prone to drift.  As time
 	passes, the computer's clock becomes less accurate.  NTP
 	(Network Time Protocol) is one way to ensure your clock is
 	right.</para>
 
       <para>Many Internet services rely on, or greatly benefit from,
 	computers' clocks being accurate.  For example, a Web server
 	may receive requests to send a file if it has modified since a
 	certain time.  Services such as &man.cron.8; run commands at a
 	given time.  If the clock is inaccurate, these commands may
 	not run when expected.</para>
 
       <indexterm>
 	<primary>NTP</primary>
 	<secondary>ntpd</secondary>
       </indexterm>
       <para>FreeBSD ships with the &man.ntpd.8; NTP server which can
 	be used to query other NTP servers to set the clock on your
 	machine or provide time services to others.</para>
     </sect2>
 
     <sect2>
       <title>Choosing Appropriate NTP Servers</title>
 
       <indexterm>
 	<primary>NTP</primary>
 	<secondary>choosing servers</secondary>
       </indexterm>
 
       <para>In order to synchronize your clock, you will need to find
 	one or more NTP servers to use.  Your network administrator or
 	ISP may have setup an NTP server for this purpose&mdash;check
 	their documentation to see if this is the case.  There is a
 	<ulink
 	url="http://www.eecis.udel.edu/~mills/ntp/servers.html">list of
 	publicly accessible NTP servers</ulink> which you can use to
 	find an NTP server near to you.  Make sure you are aware of
 	the policy for any servers you choose, and ask for permission
 	if required.</para>
 
       <para>Choosing several unconnected NTP servers is a good idea in
 	case one of the servers you are using becomes unreachable or
 	its clock is unreliable.  &man.ntpd.8; uses the responses it
 	receives from other servers intelligently&mdash;it will favor
 	unreliable servers less than reliable ones.</para>
     </sect2>
 
     <sect2>
       <title>Configuring Your Machine</title>
 
       <indexterm>
 	<primary>NTP</primary>
 	<secondary>configuration</secondary>
       </indexterm>
 
       <sect3>
 	<title>Basic Configuration</title>
 	<indexterm><primary>ntpdate</primary></indexterm>
 
 	<para>If you only wish to synchronize your clock when the
 	  machine boots up, you can use &man.ntpdate.8;.  This may be
 	  appropriate for some desktop machines which are frequently
 	  rebooted and only require infrequent synchronization, but
 	  most machines should run &man.ntpd.8;.</para>
 
 	<para>Using &man.ntpdate.8; at boot time is also a good idea
 	  for machines that run &man.ntpd.8;.  &man.ntpd.8; changes the
 	  clock gradually, whereas &man.ntpdate.8; sets the clock, no
 	  matter how great the difference between a machine's current
 	  clock setting and the correct time.</para>
 
 	<para>To enable &man.ntpdate.8; at boot time, add
 	  <programlisting>ntpdate_enable="YES"</programlisting> to
 	  <filename>/etc/rc.conf</filename>.  You will also need to
 	  specify all servers you wish to synchronize with and any
 	  flags to be passed to &man.ntpdate.8; in
 	  <varname>ntpdate_flags</varname>.</para>
       </sect3>
 
       <sect3>
 	<indexterm>
 	  <primary>NTP</primary>
 	  <secondary>ntp.conf</secondary>
 	</indexterm>
 
 	<title>General Configuration</title>
 
 	<para>NTP is configured by the
 	  <filename>/etc/ntp.conf</filename> file in the format
 	  described in &man.ntp.conf.5;.  Here is a simple
 	  example:</para>
 
 	<programlisting>server ntplocal.example.com prefer
 server timeserver.example.org
 server ntp2a.example.net
 
 driftfile /var/db/ntp.drift</programlisting>
 
 	<para>The <literal>server</literal> option specifies which
 	  servers are to be used, with one server listed on each line.
 	  If a server is specified with the <literal>prefer</literal>
 	  argument, as with <hostid
 	  role="fqdn">ntplocal.example.com</hostid>, that server is
 	  preferred over other servers.  A response from a preferred
 	  server will be discarded if it differs significantly from
 	  other servers' responses, otherwise it will be used without
 	  any consideration to other responses.  The
 	  <literal>prefer</literal> argument is normally used for NTP
 	  servers that are known to be highly accurate, such as those
 	  with special time monitoring hardware.</para>
 
 	<para>The <literal>driftfile</literal> option specifies which
 	  file is used to store the system clock's frequency offset.
 	  &man.ntpd.8; uses this to automatically compensate for the
 	  clock's natural drift, allowing it to maintain a reasonably
 	  correct setting even if it is cut off from all external time
 	  sources for a period of time.</para>
 
 	<para>The <literal>driftfile</literal> option specifies which
 	  file is used to store information about previous responses
 	  from the NTP servers you are using.  This file contains
 	  internal information for NTP.  It should not be modified by
 	  any other process.</para>
       </sect3>
 
       <sect3>
 	<title>Controlling Access to Your Server</title>
 
 	<para>By default, your NTP server will be accessible to all
 	  hosts on the Internet.  The <literal>restrict</literal>
 	  option in &man.ntp.conf.5; allows you to control which
 	  machines can access your server.</para>
 
 	<para>If you want to deny all machines from accessing your NTP
 	  server, add the line <programlisting>restrict default ignore</programlisting>
 	  to <filename>/etc/ntp.conf</filename>.  If you only want to
 	  allow machines within your own network to synchronize their
 	  clocks with your server, but ensure they are not allowed to
 	  configure the server or used as peers to synchronize
 	  against, add <programlisting>restrict 192.168.1.0 mask 255.255.255.0 notrust nomodify notrap</programlisting>
 	  instead, where <hostid role="ipaddr">192.168.1.0</hostid> is
 	  an IP address on your network and <hostid
 	  role="netmask">255.255.255.0</hostid> is your network's
 	  netmask.</para>
 
 	<para><filename>/etc/ntp.conf</filename> can contain multiple
 	  <literal>restrict</literal> options.  For more details, see
 	  the <literal>Access Control Support</literal> subsection of
 	  &man.ntp.conf.5;.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Running the NTP Server</title>
 
       <para>To ensure the NTP server is started at boot time, add the
 	line <programlisting>xntpd_enable="YES"</programlisting> to
 	<filename>/etc/rc.conf</filename>.  If you wish to pass
 	additional flags to &man.ntpd.8; edit the
 	<varname>xntpd_flags</varname> parameter in
 	<filename>/etc/rc.conf</filename>.</para>
 
       <para>To start the server without rebooting your machine, run
 	<command>ntpd</command> being sure to specify any additional
 	parameters from <varname>xntpd_flags</varname> in
 	<filename>/etc/rc.conf</filename>.  For example:</para>
       <screen>&prompt.root; <userinput>ntpd -p /var/run/ntpd.pid</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Using &man.ntpd.8; with a temporary Internet
 	connection</title>
 
       <para><command>ntpd</command> does not need a permanent
 	connection to the Internet to function properly.  However, if
 	you have a temporary connection that is configured to dial out
 	on demand, it is a good idea to prevent NTP traffic from
 	triggering a dial out or keeping the connection alive.  If you
 	are using user PPP, you can use <literal>filter</literal>
 	directives in <filename>/etc/ppp/ppp.conf</filename>.  For
 	example:</para>
 
       <programlisting> set filter dial 0 deny udp src eq 123
  # Prevent NTP traffic from initiating dial out
  set filter dial 1 permit 0 0
  set filter alive 0 deny udp src eq 123
  # Prevent incoming NTP traffic from keeping the connection open
  set filter alive 1 deny udp dst eq 123
  # Prevent outgoing NTP traffic from keeping the connection open
  set filter alive 2 permit 0/0 0/0</programlisting>
 
       <para>For more details see the <literal>PACKET
 	FILTERING</literal> section in &man.ppp.8; and the examples in
 	<filename>/usr/share/examples/ppp/</filename>.</para>
 
       <note>
 	<para>Some Internet access providers block low-numbered ports,
 	  preventing NTP from functioning since replies never
 	  reach your machine.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Further Information</title>
 
       <para>Documentation for the NTP server can be found in
 	<filename>/usr/share/doc/ntp/</filename> in HTML
 	format.</para>
     </sect2>
   </sect1>
 
   <sect1 id="natd">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
           <surname>Lee</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Network Address Translation</title>
 
     <sect2 id="overview">
       <title>Overview</title>
       <indexterm>
         <primary><application>natd</application></primary>
       </indexterm>
       <para>FreeBSD's Network Address Translation daemon, commonly known as
         &man.natd.8; is a daemon that accepts incoming raw IP packets,
         changes the source to the local machine and re-injects these packets
         back into the outgoing IP packet stream.  natd does this by changing
         the source IP address and port such that when data is received back,
         it is able to determine the original location of the data and forward
         it back to its original requester.</para>
       <indexterm><primary>Internet connection sharing</primary></indexterm>
       <indexterm><primary>IP masquerading</primary></indexterm>
       <para>The most common use of NAT is to perform what is commonly known as
         Internet Connection Sharing.</para>
     </sect2>
 
     <sect2 id="setup">
       <title>Setup</title>
       <para>Due to the diminishing IP space in IPv4, and the increased number
         of users on high-speed consumer lines such as cable or DSL, people are
         increasingly in need of an Internet Connection Sharing solution.  The
         ability to connect several computers online through one connection and
         IP address makes &man.natd.8; a reasonable choice.</para>
 
       <para>Most commonly, a user has a machine connected to a cable or DSL
         line with one IP address and wishes to use this one connected computer to
         provide Internet access to several more over a LAN.</para>
 
       <para>To do this, the FreeBSD machine on the Internet must act as a
         gateway.  This gateway machine must have two NICs--one for connecting
         to the Internet router, the other connecting to a LAN.  All the
         machines on the LAN are connected through a hub or switch.</para>
 
       <mediaobject>
         <imageobject>
           <imagedata fileref="advanced-networking/natd">
         </imageobject>
 
 	<textobject>
 	  <literallayout class="monospaced">  _______       __________       ________
  |       |     |          |     |        |
  |  Hub  |-----| Client B |-----| Router |----- Internet
  |_______|     |__________|     |________|
      |
  ____|_____
 |          |
 | Client A |
 |__________|</literallayout>
         </textobject>
 
 	<textobject>
 	  <phrase>Network Layout</phrase>
 	</textobject>
       </mediaobject>
 
       <para>A setup like this is commonly used to share an Internet
         connection.  One of the <acronym>LAN</acronym> machines is
         connected to the Internet.  The rest of the machines access
         the Internet through that <quote>gateway</quote>
         machine.</para>
     </sect2>
 
     <sect2 id="configuration">
       <indexterm>
         <primary>kernel</primary>
 	<secondary>configuration</secondary>
       </indexterm>
       <title>Configuration</title>
       <para>The following options must be in the kernel configuration
         file:</para>
       <programlisting>options IPFIREWALL
 options IPDIVERT</programlisting>
 
       <para>Additionally, at choice, the following may also be suitable:</para>
       <programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT
 options IPFIREWALL_VERBOSE</programlisting>
 
       <para>The following must be in <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>gateway_enable="YES"
 firewall_enable="YES"
 firewall_type="OPEN"
 natd_enable="YES"
 natd_interface="<replaceable>fxp0</replaceable>"
 natd_flags=""</programlisting>
 
       <informaltable frame="none">
         <tgroup cols="2">
           <tbody>
             <row>
               <entry>gateway_enable="YES"</entry>
               <entry>Sets up the machine to act as a gateway.  Running
                 <command>sysctl net.inet.ip.forwarding=1</command>
                 would have the same effect.</entry>
             </row>
             <row><entry>firewall_enable="YES"</entry>
              <entry>Enables the firewall rules in
                <filename>/etc/rc.firewall</filename> at boot.</entry>
             </row>
             <row><entry>firewall_type="OPEN"</entry>
               <entry>This specifies a predefined firewall ruleset that
                 allows anything in.  See
                 <filename>/etc/rc.firewall</filename> for additional
                 types.</entry>
             </row>
             <row>
               <entry>natd_interface="fxp0"</entry>
               <entry>Indicates which interface to forward packets through
                 (the interface connected to the Internet).</entry>
             </row>
             <row>
               <entry>natd_flags=""</entry>
               <entry>Any additional configuration options passed to
                 &man.natd.8; on boot.</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>Having the previous options defined in
         <filename>/etc/rc.conf</filename> would run
         <command>natd -interface fxp0</command> at boot.  This can also
         be run manually.</para>
 
       <para>Each machine and interface behind the LAN should be assigned IP address
         numbers in the private network space as defined by
         <ulink url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC 1918</ulink>
         and have a default gateway of the natd machine's internal IP address.</para>
 
       <para>For example, client <hostid>a</hostid> and <hostid>b</hostid> behind the LAN have IP addresses
         of <hostid role="ipaddr">192.168.0.2</hostid> and
         <hostid role="ipaddr">192.168.0.3</hostid>, while the natd
         machine's LAN interface has an IP address of
         <hostid role="ipaddr">192.168.0.1</hostid>.  Client <hostid>a</hostid> and <hostid>b</hostid>'s
         default gateway must be set to that of the natd machine,
         <hostid role="ipaddr">192.168.0.1</hostid>.
         The natd machine's external, or
         Internet interface does not require any special modification for natd
         to work.</para>
     </sect2>
 
     <sect2 id="port-redirection">
       <title>Port Redirection</title>
 
       <para>The drawback with natd is that the LAN clients are not accessible
         from the Internet.  Clients on the LAN can make outgoing connections to
         the world but cannot receive incoming ones.  This presents a problem
         if trying to run Internet services on one of the LAN client machines.
         A simple way around this is to redirect selected Internet ports on the
         natd machine to a LAN client.
       </para>
 
       <para>For example, an IRC server runs on Client A, and a web server runs
         on Client B.  For this to work properly, connections received on ports
         6667 (irc) and 80 (web) must be redirected to the respective machines.
       </para>
 
       <para>The <command>-redirect_port</command> must be passed to
         &man.natd.8; with the proper options.  The syntax is as follows:</para>
       <para><programlisting>     -redirect_port proto targetIP:targetPORT[-targetPORT]
                  [aliasIP:]aliasPORT[-aliasPORT]
                  [remoteIP[:remotePORT[-remotePORT]]]</programlisting></para>
 
       <para>In the above example, the argument should be:
         <programlisting>    -redirect_port tcp 192.168.0.2:6667 6667
     -redirect_port tcp 192.168.0.3:80 80</programlisting>
         This will redirect the proper <emphasis>tcp</emphasis> ports to the
         LAN client machines.
       </para>
 
       <para>The -redirect_port argument can be used to indicate port
         ranges over individual ports.  For example, <replaceable>tcp
         192.168.0.2:2000-3000 2000-3000</replaceable> would redirect
         all connections received on ports 2000 to 3000 to ports 2000
         to 3000 on Client A.</para>
 
       <para>These options can be used when directly running
         &man.natd.8; or placed within the
         <programlisting>natd_flags=""</programlisting> option in
         <filename>/etc/rc.conf</filename>.</para>
 
       <para>For further configuration options, consult &man.natd.8;</para>
     </sect2>
 
     <sect2 id="address-redirection">
       <title>Address Redirection</title>
       <indexterm><primary>address redirection</primary></indexterm>
       <para>Address redirection is useful if several IP addresses are
         available, yet they must be on one machine.  With this,
         &man.natd.8; can assign each LAN client its own external IP address.
         &man.natd.8; then rewrites outgoing packets from the LAN clients
         with the proper external IP address and redirects
         all traffic incoming on that particular IP address back to
         the specific LAN client.  This is also known as static NAT.
         For example, the IP addresses <hostid role="ipaddr">128.1.1.1</hostid>,
         <hostid role="ipaddr">128.1.1.2</hostid>, and
         <hostid role="ipaddr">128.1.1.3</hostid> belong to the natd gateway
         machine.  <hostid role="ipaddr">128.1.1.1</hostid> can be used
         as the natd gateway machine's external IP address, while
         <hostid role="ipaddr">128.1.1.2</hostid> and
         <hostid role="ipaddr">128.1.1.3</hostid> are forwarded back to LAN
         clients A and B.</para>
 
       <para>The -redirect_address syntax is as follows:</para>
       <para><option> -redirect_address localIP publicIP</option>
       </para>
 
       <informaltable frame="none">
         <tgroup cols="2">
           <tbody>
             <row>
               <entry>localIP</entry>
               <entry>The internal IP address of the LAN client.</entry>
             </row>
             <row>
               <entry>publicIP</entry>
               <entry>The external IP address corresponding to the LAN client.</entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
       <para>In the example, this argument would read:</para>
       <para><option>    -redirect_address 192.168.0.2 128.1.1.2
     -redirect_address 192.168.0.3 128.1.1.3</option></para>
 
       <para>Like -redirect_port, these arguments are also placed within
         natd_flags of <filename>/etc/rc.conf</filename>.  With address
         redirection, there is no need for port redirection since all data
         received on a particular IP address is redirected.</para>
 
       <para>The external IP addresses on the natd machine must be active and aliased
         to the external interface.  Look at &man.rc.conf.5; to do so.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="inetd">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
           <surname>Lee</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
 
     <title>inetd <quote>Super-Server</quote></title>
 
     <sect2 id="inetd-overview">
       <title>Overview</title>
 
       <para>&man.inetd.8; is referred to as the <quote>Internet
 	  Super-Server</quote> because it manages connections for several
 	daemons.  Programs that provide network service are commonly
 	known as daemons.  <application>inetd</application> serves as a
 	managing server for other daemons.  When a connection is
 	received by <application>inetd</application>, it determines
 	which daemon the connection is destined for, spawns the
 	particular daemon and delegates the socket to it.  Running one
 	instance of <application>inetd</application> reduces the overall
 	system load as compared to running each daemon individually in
 	stand-alone mode.</para>
 
       <para>Primarily, <application>inetd</application> is used to
 	spawn other daemons, but several trivial protocols are handled
 	directly, such as <application>chargen</application>,
 	<application>auth</application>, and
 	<application>daytime</application>.</para>
 
       <para>This section will cover the basics in configuring
 	<application>inetd</application> through its command-line
 	options and its configuration file,
 	<filename>/etc/inetd.conf</filename>.</para>
     </sect2>
 
     <sect2 id="inetd-settings">
       <title>Settings</title>
 
       <para><application>inetd</application> is initialized through
 	the <filename>/etc/rc.conf</filename> system.  The
 	<literal>inetd_enable</literal> option is set to
 	<quote>NO</quote> by default, but is often times turned on by
 	<application>sysinstall</application> with the medium security
 	profile.  Placing:
 	<programlisting>inetd_enable="YES"</programlisting> or
 	<programlisting>inetd_enable="NO"</programlisting> into
 	<filename>/etc/rc.conf</filename> can enable or disable
 	<application>inetd</application> starting at boot time.</para>
 
       <para>Additionally, different command-line options can be passed
 	to <application>inetd</application> via the
 	<literal>inetd_flags</literal> option.</para>
     </sect2>
 
     <sect2 id="inetd-cmdline">
       <title>Command-Line Options</title>
 
       <para><application>inetd</application> synopsis:</para>
 
       <para><option>     inetd [-d] [-l] [-w] [-W] [-c maximum] [-C rate] [-a address | hostname]
            [-p filename] [-R rate] [configuration file]</option></para>
 
       <variablelist>
 	<varlistentry>
 	  <term>-d</term>
 
 	  <listitem>
 	    <para>Turn on debugging.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-l</term>
 
 	  <listitem>
 	    <para>Turn on logging of successful connections.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-w</term>
 
 	  <listitem>
 	    <para>Turn on TCP Wrapping for external services (on by
 	      default).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-W</term>
 
 	  <listitem>
 	    <para>Turn on TCP Wrapping for internal services which are
 	      built into <application>inetd</application> (on by
 	      default).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-c maximum</term>
 
 	  <listitem>
 	    <para>Specify the default maximum number of simultaneous
 	      invocations of each service; the default is unlimited.
 	      May be overridden on a per-service basis with the
 	      <option>max-child</option> parameter.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-C rate</term>
 
 	  <listitem>
 	    <para>Specify the default maximum number of times a
 	      service can be invoked from a single IP address in one
 	      minute; the default is unlimited.  May be overridden on a
 	      per-service basis with the
 	      <option>max-connections-per-ip-per-minute</option>
 	      parameter.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-R rate</term>
 
 	  <listitem>
 	    <para>Specify the maximum number of times a service can be
 	      invoked in one minute; the default is 256.  A rate of 0
 	      allows an unlimited number of invocations.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-a</term>
 
 	  <listitem>
 	    <para>Specify one specific IP address to bind to.
 	      Alternatively, a hostname can be specified, in which case
 	      the IPv4 or IPv6 address which corresponds to that
 	      hostname is used.  Usually a hostname is specified when
 	      <application>inetd</application> is run inside a
 	      &man.jail.8;, in which case the hostname corresponds to
 	      the &man.jail.8; environment.</para>
 
 	    <para>When hostname specification is used and both IPv4
 	      and IPv6 bindings are desired, one entry with the
 	      appropriate protocol type for each binding is required for
 	      each service in <filename>/etc/inetd.conf</filename>.  For
 	      example, a TCP-based service would need two entries, one
 	      using <quote>tcp4</quote> for the protocol and the other using
 	      <quote>tcp6</quote>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>-p</term>
 
 	  <listitem>
 	    <para>Specify an alternate file in which to store the
 	      process ID.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
       <para>These options can be passed to
 	<application>inetd</application> using the
 	<literal>inetd_flags</literal> option in
 	<filename>/etc/rc.conf</filename>.  By default,
 	<literal>inetd_flags</literal> is set to <quote>-wW</quote>,
 	which turns on TCP wrapping for
 	<application>inetd</application>'s internal and external
 	services.  For novice users, these parameters usually do not need
 	to be modified or even entered in
 	<filename>/etc/rc.conf</filename>.</para>
 
       <note>
 	<para>An external service is a daemon outside of
 	  <application>inetd</application>, which is invoked when a
 	  connection is received for it.  On the other hand, an internal
 	  service is one that <application>inetd</application> has the
 	  facility of offering within itself.</para>
       </note>
 
     </sect2>
 
     <sect2 id="inetd-conf">
       <title><filename>inetd.conf</filename></title>
 
       <para>Configuration of <application>inetd</application> is
 	controlled through the <filename>/etc/inetd.conf</filename>
 	file.</para>
 
       <para>When a modification is made to
 	<filename>/etc/inetd.conf</filename>,
 	<application>inetd</application> can be forced to re-read its
 	configuration file by sending a HangUP signal to the
 	<application>inetd</application> process as shown:</para>
 
       <example id="inetd-hangup">
 	<title>Sending <application>inetd</application> a HangUP Signal</title>
 
 	<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
       </example>
 
       <para>Each line of the configuration file specifies an
 	individual daemon.  Comments in the file are preceded by a
 	<quote>#</quote>.  The format of
 	<filename>/etc/inetd.conf</filename> is as follows:</para>
 
       <programlisting>service-name
 socket-type
 protocol
 {wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
 user[:group][/login-class]
 server-program
 server-program-arguments</programlisting>
 
       <para>An example entry for the <application>ftpd</application> daemon
 	using IPv4:</para>
 
       <programlisting>ftp     stream  tcp     nowait  root    /usr/libexec/ftpd       ftpd -l</programlisting>
 
       <variablelist>
 	<varlistentry>
 	  <term>service-name</term>
 
 	  <listitem>
 	    <para>This is the service name of the particular daemon.
 	      It must correspond to a service listed in
 	      <filename>/etc/services</filename>.  This determines which
 	      port <application>inetd</application> must listen to.  If
 	      a new service is being created, it must be placed in
 	      <filename>/etc/services</filename>
 	      first.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>socket-type</term>
 
 	  <listitem>
 	    <para>Either <literal>stream</literal>,
 	      <literal>dgram</literal>, <literal>raw</literal>, or
 	      <literal>seqpacket</literal>.  <literal>stream</literal>
 	      must be used for connection-based, TCP daemons, while
 	      <literal>dgram</literal> is used for daemons utilizing the
 	      UDP transport protocol.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>protocol</term>
 
 	  <listitem>
 	    <para>One of the following:</para>
 
 	    <informaltable>
 	      <tgroup cols="2">
 		<thead>
 		  <row>
 		    <entry>Protocol</entry>
 		    <entry>Explanation</entry>
 		  </row>
 		</thead>
 		<tbody>
 		  <row>
 		    <entry>tcp, tcp4</entry>
 		    <entry>TCP IPv4</entry>
 		  </row>
 		  <row>
 		    <entry>udp, udp4</entry>
 		    <entry>UDP IPv4</entry>
 		  </row>
 		  <row>
 		    <entry>tcp6</entry>
 		    <entry>TCP IPv6</entry>
 		  </row>
 		  <row>
 		    <entry>udp6</entry>
 		    <entry>UDP IPv6</entry>
 		  </row>
 		  <row>
 		    <entry>tcp46</entry>
 		    <entry>Both TCP IPv4 and v6</entry>
 		  </row>
 		  <row>
 		    <entry>udp46</entry>
 		    <entry>Both UDP IPv4 and v6</entry>
 		  </row>
 		</tbody>
 	      </tgroup>
 	    </informaltable>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]</term>
 
 	  <listitem>
 	    <para><option>wait|nowait</option> indicates whether the
 	      daemon invoked from <application>inetd</application> is
 	      able to handle its own socket or not.
 	      <option>dgram</option> socket types must use the wait
 	      option, while stream socket daemons, which are usually
 	      multi-threaded, should use <option>nowait</option>.
 	      <option>wait</option> usually hands off multiple sockets
 	      to a single daemon, while <option>nowait</option> spawns a
 	      child daemon for each new socket.</para>
 
 	    <para>The maximum number of child daemons
 	      <application>inetd</application> may spawn can be set using
 	      the <option>max-child</option> option.  If a limit of ten
 	      instances of a particular daemon is needed, a
 	      <literal>/10</literal> would be placed after
 	      <option>nowait</option>.</para>
 
 	    <para>In addition to <option>max-child</option>, another
 	      option limiting the maximum connections from a single
 	      place to a particular daemon can be enabled.
 	      <option>max-connections-per-ip-per-minute</option> does
 	      just this.  A value of ten here would limit any particular
 	      IP address connecting to a particular service to ten
 	      attempts per minute.  This is useful to prevent
 	      intentional or unintentional resource consumption and
 	      Denial of Service (DoS) attacks to a machine.</para>
 
 	    <para>In this field, <option>wait</option> or
 	      <option>nowait</option> is mandatory.
 	      <option>max-child</option> and
 	      <option>max-connections-per-ip-per-minute</option> are
 	      optional.</para>
 
 	    <para>A stream-type multi-threaded daemon without any
 	      <option>max-child</option> or
 	      <option>max-connections-per-ip-per-minute</option> limits
 	      would simply be: <literal>nowait</literal></para>
 
 	    <para>The same daemon with a maximum limit of ten daemons
 	      would read: <literal>nowait/10</literal></para>
 
 	    <para>Additionally, the same setup with a limit of twenty
 	      connections per IP address per minute and a maximum
 	      total limit of ten child daemons would read:
 	      <literal>nowait/10/20</literal></para>
 
 	    <para>These options are all utilized by the default
 	      settings of the <application>fingerd</application> daemon,
 	      as seen here:</para>
 
 	    <programlisting>finger stream  tcp     nowait/3/10 nobody /usr/libexec/fingerd fingerd -s</programlisting>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>user</term>
 
 	  <listitem>
 	    <para>The user is the username that the particular daemon
 	      should run as.  Most commonly, daemons run as the
 	      <username>root</username> user.  For security purposes, it is
 	      common to find some servers running as the
 	      <username>daemon</username> user, or the least privileged
 	      <username>nobody</username> user.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>server-program</term>
 
 	  <listitem>
 	    <para>The full path of the daemon to be executed when a
 	      connection is received.  If the daemon is a service
 	      provided by <application>inetd</application> internally,
 	      then <option>internal</option> should be
 	      used.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>server-program-arguments</term>
 
 	  <listitem>
 	    <para>This works in conjunction with
 	      <option>server-program</option> by specifying the
 	      arguments, starting with argv[0], passed to the daemon on
 	      invocation.  If <application>mydaemon -d</application> is
 	      the command line, <literal>mydaemon -d</literal> would be
 	      the value of <option>server program arguments</option>.
 	      Again, if the daemon is an internal service, use
 	      <option>internal</option> here.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2 id="inetd-security">
       <title>Security</title>
 
       <para>Depending on the security profile chosen at install, many
 	of <application>inetd</application>'s daemons may be enabled by
 	default.  If there is no apparent need for a particular daemon,
 	disable it!  Place a <quote>#</quote> in front of the daemon in
 	question, and send a <link linkend="inetd-hangup">hangup signal
 	  to inetd</link>.
 	Some daemons, such as <application>fingerd</application>, may
 	not be desired at all because they provide an attacker with too
 	much information.</para>
 
       <para>Some daemons are not security-conscious and have long, or
 	non-existent timeouts for connection attempts.  This allows an
 	attacker to slowly send connections to a particular daemon, thus
 	saturating available resources.  It may be a good idea to place
 	<option>ip-per-minute</option> and <option>max-child</option>
 	limitations on certain daemons.</para>
 
       <para>By default, TCP wrapping is turned on.  Consult the
 	&man.hosts.access.5; manual page for more information on placing
 	TCP restrictions on various <application>inetd</application>
 	invoked daemons.</para>
     </sect2>
 
     <sect2 id="inetd-misc">
       <title>Miscellaneous</title>
 
       <para><application>daytime</application>,
 	<application>time</application>,
 	<application>echo</application>,
 	<application>discard</application>,
 	<application>chargen</application>, and
 	<application>auth</application> are all internally provided
 	services of <application>inetd</application>.</para>
 
       <para>The <application>auth</application> service provides identity
 	(ident, identd) network services, and is configurable to a certain
 	degree.</para>
 
       <para>Consult the &man.inetd.8; manual page for more in-depth
 	information.</para>
     </sect2>
   </sect1>
 
   <sect1 id="plip">
     <title>Parallel Line IP (PLIP)</title>
 
     <indexterm><primary>PLIP</primary></indexterm>
     <indexterm><primary>Parallel Line IP</primary></indexterm>
 
     <para>PLIP lets us run TCP/IP between parallel ports.  It is
       useful on machines without network cards, or to install on
       laptops.  In this section, we will discuss:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Creating a parallel (laplink) cable.</para>
       </listitem>
 
       <listitem>
 	<para>Connecting two computers with PLIP.</para>
       </listitem>
     </itemizedlist>
 
     <sect2 id="create-parallel-cable">
       <title>Creating a Parallel Cable</title>
 
       <para>You can purchase a parallel cable at most computer supply
         stores.  If you cannot do that, or you just want to know how
         it is done, the following table shows how to make one out of a normal parallel
         printer cable.</para>
 
       <table>
 	<title>Wiring a parallel cable for networking</title>
 
 	<tgroup cols="5">
 	  <thead>
 	    <row>
 	      <entry>A-name</entry>
 
 	      <entry>A-End</entry>
 
 	      <entry>B-End</entry>
 
 	      <entry>Descr.</entry>
 
 	      <entry>Post/Bit</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><literallayout>DATA0
 -ERROR</literallayout></entry>
 
 	      <entry><literallayout>2
 15</literallayout></entry>
 
 	      <entry><literallayout>15
 2</literallayout></entry>
 
 	      <entry>Data</entry>
 
 	      <entry><literallayout>0/0x01
 1/0x08</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry><literallayout>DATA1
 +SLCT</literallayout></entry>
 
 	      <entry><literallayout>3
 13</literallayout></entry>
 
 	      <entry><literallayout>13
 3</literallayout></entry>
 
 	      <entry>Data</entry>
 
 	      <entry><literallayout>0/0x02
 1/0x10</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry><literallayout>DATA2
 +PE</literallayout></entry>
 
 	      <entry><literallayout>4
 12</literallayout></entry>
 
 	      <entry><literallayout>12
 4</literallayout></entry>
 
 	      <entry>Data</entry>
 
 	      <entry><literallayout>0/0x04
 1/0x20</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry><literallayout>DATA3
 -ACK</literallayout></entry>
 
 	      <entry><literallayout>5
 10</literallayout></entry>
 
 	      <entry><literallayout>10
 5</literallayout></entry>
 
 	      <entry>Strobe</entry>
 
 	      <entry><literallayout>0/0x08
 1/0x40</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry><literallayout>DATA4
 BUSY</literallayout></entry>
 
 	      <entry><literallayout>6
 11</literallayout></entry>
 
 	      <entry><literallayout>11
 6</literallayout></entry>
 
 	      <entry>Data</entry>
 
 	      <entry><literallayout>0/0x10
 1/0x80</literallayout></entry>
 	    </row>
 
 	    <row>
 	      <entry>GND</entry>
 
 	      <entry>18-25</entry>
 
 	      <entry>18-25</entry>
 
 	      <entry>GND</entry>
 
 	      <entry>-</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
     </sect2>
 
     <sect2 id="plip-setup">
       <title>Setting up PLIP</title>
 
       <para>Get a laplink cable.</para>
 
       <para>Confirm that both computers have a kernel with &man.lpt.4; driver
 	support.</para>
 
       <screen>&prompt.root; <userinput>dmesg | grep lp</userinput>
 lpt0 at 0x378-0x37f irq 7 on isa
 lpt0: Interrupt-driven
 lp0: TCP/IP capable interface</screen>
 
       <para>Plug in the laplink cable into the parallel interface on
 	both computers.</para>
 
       <para>Configure the network interface parameters for <devicename>lp0</devicename> on both
 	sites as <username>root</username>.  For example, if you want connect
 	the host <hostid>host1</hostid> with <hostid>host2</hostid>:</para>
 
       <programlisting>                 host1 &lt;-----&gt; host2
 IP Address    10.0.0.1      10.0.0.2</programlisting>
 
       <para>Configure the interface on <hostid>host1</hostid> by doing:</para>
 
       <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.1 10.0.0.2</userinput></screen>
 
       <para>Configure the interface on host2 by doing:</para>
 
       <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.2 10.0.0.1</userinput></screen>
 
 
       <para>You now should have a working connection.  Please read the
         manual pages &man.lp.4; and &man.lpt.4; for more details.</para>
 
       <para>You should also add both hosts to
 	<filename>/etc/hosts</filename>:</para>
 
       <programlisting>127.0.0.1               localhost.my.domain localhost
 10.0.0.1                host1.my.domain host1
 10.0.0.2                host2.my.domain</programlisting>
 
       <para>To confirm the connection works, go to each host and ping
 	the other.  For example, on <hostid>host1</hostid>:</para>
 
           <screen>&prompt.root; <userinput>ifconfig lp0</userinput>
 lp0: flags=8851&lt;UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
         inet 10.0.0.1 --&gt; 10.0.0.2 netmask 0xff000000
 &prompt.root; <userinput>netstat -r</userinput>
 Routing tables
 
 Internet:
 Destination        Gateway          Flags     Refs     Use      Netif Expire
 host2              host1              UH          4   127592       lp0
 &prompt.root; <userinput>ping -c 4 host2</userinput>
 PING host2 (10.0.0.2): 56 data bytes
 64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
 
 --- host2 ping statistics ---
 4 packets transmitted, 4 packets received, 0% packet loss
 round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms</screen>
 
     </sect2>
   </sect1>
 
   <sect1 id="ipv6">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Aaron</firstname>
 	  <surname>Kaplan</surname>
 	  <contrib>Originally Written by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Rhodes</surname>
 	  <contrib>Restructured and Added by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title>IPv6</title>
     <para>IPv6 (also know as IPng <quote>IP next generation</quote>) is
       the new version of the well known IP protocol (also know as
       <acronym>IPv4</acronym>).  Like the other current *BSD systems,
       FreeBSD includes the <acronym>KAME</acronym> IPv6 reference implementation.
       So your FreeBSD system comes with all you will need to experiment with IPv6.
       This section focuses on getting IPv6 configured and running.</para>
 
     <para>In the early 1990s, people became aware of the rapidly
       diminishing address space of IPv4.  Given the expansion rate of the
       Internet there were two major concerns:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Running out of addresses.  Today this is not so much of a concern
 	  anymore since private address spaces
 	  (<hostid role="ipaddr">10.0.0.0/8</hostid>,
 	  <hostid role="ipaddr">192.168.0.0/24</hostid>,
 	  etc.) and Network Address Translation (<acronym>NAT</acronym>) are
 	  being employed.</para>
       </listitem>
 
       <listitem>
 	<para>Router table entries were getting too large.  This is
 	  still a concern today.</para>
       </listitem>
     </itemizedlist>
 
     <para>IPv6 deals with these and many other issues:</para>
 
     <itemizedlist>
       <listitem>
 	<para>128 bit address space.  In other words theoretically there are
 	  340,282,366,920,938,463,463,374,607,431,768,211,456 addresses
 	  available.  This means there are approximately
 	  6.67 * 10^27 IPv6 addresses per square meter on our planet.</para>
       </listitem>
 
       <listitem>
 	<para>Routers will only store network aggregation addresses in their routing
 	  tables thus reducing the average space of a routing table to 8192
 	  entries.</para>
       </listitem>
     </itemizedlist>
 
     <para>There are also lots of other useful features of IPv6 such as:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Address autoconfiguration (RFC2462)</para>
       </listitem>
 
       <listitem>
 	<para>Anycast addresses (<quote>one-out-of many</quote>)</para>
       </listitem>
 
       <listitem>
 	<para>Mandatory multicast addresses</para>
       </listitem>
 
       <listitem>
 	<para>IPsec (IP security)</para>
       </listitem>
 
       <listitem>
 	<para>Simplified header structure</para>
       </listitem>
 
       <listitem>
 	<para>Mobile <acronym>IP</acronym></para>
       </listitem>
 
       <listitem>
 	<para>IPv4-to-IPv6 transition mechanisms</para>
       </listitem>
     </itemizedlist>
 
 
     <para>For more information see:</para>
 
     <itemizedlist>
       <listitem>
 	<para>IPv6 overview at <ulink url="http://www.sun.com">Sun.com</ulink></para>
       </listitem>
 
       <listitem>
 	<para><ulink url="http://www.ipv6.org">IPv6.org</ulink></para>
       </listitem>
 
       <listitem>
 	<para><ulink url="http://www.kame.net">KAME.net</ulink></para>
       </listitem>
 
       <listitem>
 	<para><ulink url="http://www.6bone.net">6bone.net</ulink></para>
       </listitem>
     </itemizedlist>
 
     <sect2>
       <title>Background on IPv6 Addresses</title>
       <para>There are different types of IPv6 addresses: Unicast, Anycast and
 	Multicast.<para>
 
       <para>Unicast addresses are the well known addresses.  A packet sent
 	to a unicast address arrives exactly at the interface belonging to
 	the address.</para>
 
       <para>Anycast addresses are syntactically indistinguishable from unicast
 	addresses but they address a group of interfaces.  The packet destined for
 	an anycast address will arrive at the nearest (in router metric)
 	interface.  Anycast addresses may only be used by routers.</para>
 
       <para>Multicast addresses identify a group of interfaces.  A packet destined
 	for a multicast address will arrive at all interfaces belonging to the
 	multicast group.</para>
 
 	<note><para>The IPv4 broadcast address (usually xxx.xxx.xxx.255) is expressed
 	  by multicast addresses in IPv6.</para></note>
 
       <para>Reserved IPv6 addresses:</para>
 
 <screen>ipv6-address 	prefixlength(Bits)	description	Notes
 
 	::			128 Bits			unspecified cf. 0.0.0.0 in IPv4 address
 	::1			128 Bits			loopback address cf. 127.0.0.1 in IPv4
 	::00:xx:xx:xx:xx	96 Bits				embedded IPv4	The lower 32 bits are the
 								address	IPv4 address. Also called
 								<quote>IPv4 compatible IPv6
 								address</quote>
 	::ff:xx:xx:xx:xx	96 Bits		IPv4 mapped     The lower 32 bits are the
 						IPv6 address	IPv4 address. For hosts
 								which do not support IPv6
 	fe80:: - feb::		10 Bits		link-local	cf. loopback address in
 						IPv4
 	fec0:: - fef::		10 Bits		site-local
 	ff::			8 Bits		multicast
 	001 (base 2)		3 Bits		global unicast	All global unicast
 								addresses are assigned from
 								this pool. The first 3 Bits
 								are <quote>001</quote>.</screen>
 
     </sect2>
 
     <sect2>
       <title>Reading IPv6 Addresses</title>
       <para>The canonical form is represented as: x:x:x:x:x:x:x:x, each
 	<quote>x</quote> being a 16 Bit hex value.  For example
 	<hostid role="ip6addr">FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</hostid></para>
 
       <para>Often an address will have long substrings of all zeros
 	therefore each such substring can be abbreviated by <quote>::</quote>.
 	For example <hostid role="ip6addr">fe80::1</hostid>
 	corresponds to the canonical form
 	<hostid role="ip6addr">fe80:0000:0000:0000:0000:0000:0000:0001</hostid></para>
 
       <para>A third form is to write the last 32 Bit part in the
 	well known (decimal) IPv4 style with dots <quote>.</quote>
 	as separators.  For example
 	<hostid role="ip6addr">2002::10.0.0.1</hostid>
 	corresponds to the (hexadecimal) canonical representation
 	<hostid role="ip6addr">2002:0000:0000:0000:0000:0000:000a:0001</hostid>
 	which in turn is equivalent to
 	writing <hostid role="ip6addr">2002::a:1</hostid></para>
 
       <para>By now the reader should be able to understand the following:</para>
 
       <screen>&prompt.root; <userinput>ifconfig</userinput></screen>
 
       <programlisting>rl0: flags=8943&lt;UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST&gt; mtu 1500
          inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
          inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1
          ether 00:00:21:03:08:e1
          media: Ethernet autoselect (100baseTX )
          status: active</programlisting>
 
       <para><hostid role="ip6addr">fe80::200:21ff:fe03:8e1%rl0</hostid>
 	is an auto configured link-local address.  It includes the
 	enscrambled Ethernet MAC as part of the auto configuration.</para>
 
       <para>For further information on the structure of IPv6 addresses
 	see RFC2373.</para>
     </sect2>
 
     <sect2>
       <title>Getting Connected</title>
 
       <para>Currently there are four ways to connect to other IPv6 hosts and networks:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Join the experimental 6bone</para>
 	</listitem>
 
 	<listitem>
 	  <para>Getting an IPv6 network from your upstream provider.  Talk to your
 	    Internet provider for instructions.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Tunnel via 6-to-4</para>
 	</listitem>
 
 	<listitem>
 	  <para>Use the freenet6 port if you are on a dial-up connection.</para>
 	</listitem>
       </itemizedlist>
 
       <para>Here we will talk on how to connect to the 6bone since it currently seems
 	to be the most popular way.</para>
 
       <para>First take a look at the 6bone site and find a 6bone connection nearest to
 	you.  Write to the responsible person and with a little bit of luck you
 	will be given instructions on how to set up your connection.  Usually this
 	involves setting up a GRE (gif) tunnel.</para>
 
       <para>Here is a typical example on setting up a &man.gif.4; tunnel:</para>
 
       <screen>&prompt.root; <userinput>ifconfig gif0 create</userinput>
 &prompt.root; <userinput>ifconfig gif0</userinput>
 gif0: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1280
 &prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>MY_IPv4_ADDR</replaceable>  <replaceable>HIS_IPv4_ADDR</replaceable></userinput>
 &prompt.root; <userinput>ifconfig gif0 inet6 alias <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable></userinput></screen>
 
       <para>Replace the capitalized words by the information you received from the
 	upstream 6bone node.</para>
 
       <para>This establishes the tunnel.  Check if the tunnel is working by &man.ping6.8;
 	'ing ff02::1%gif0.  You should receive two ping replies.</para>
 
 	<note><para>In case you are intrigued by the address ff02:1%gif0, this is a
 	  multicast address.  %gif0 states that the multicast address at network
 	  interface gif0 is to be used.  Since we <command>ping</command> a multicast address the
 	  other endpoint of the tunnel should reply as well).</para></note>
 
       <para>By now setting up a route to your 6bone uplink should be rather
 	straightforward:</para>
 
       <screen>&prompt.root; <userinput>route add -inet6 default -interface gif0</userinput>
 &prompt.root; <userinput>ping6 -n <replaceable>MY_UPLINK</replaceable></userinput></screen>
 
       <screen>&prompt.root; <userinput>traceroute6 www.jp.freebsd.org</userinput>
 (3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets
      1  atnet-meta6  14.147 ms  15.499 ms  24.319 ms
      2  6bone-gw2-ATNET-NT.ipv6.tilab.com  103.408 ms  95.072 ms *
      3  3ffe:1831:0:ffff::4  138.645 ms  134.437 ms  144.257 ms
      4  3ffe:1810:0:6:290:27ff:fe79:7677  282.975 ms  278.666 ms  292.811 ms
      5  3ffe:1800:0:ff00::4  400.131 ms  396.324 ms  394.769 ms
      6  3ffe:1800:0:3:290:27ff:fe14:cdee  394.712 ms  397.19 ms  394.102 ms</screen>
 
       <para>This output will differ from machine to machine.  By now you should be
 	able to reach the IPv6 site <ulink url="http://www.kame.net">www.kame.net</ulink>
 	and see the dancing tortoise - that is if you have a IPv6 enabled browser such as
 	<filename role="package">mozilla</filename>.</para>
 
     </sect2>
 
     <sect2>
       <title>DNS in the IPv6 World</title>
       <para>There are two new types of DNS records for IPv6:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>AAAA records,</para>
 	</listitem>
 
 	<listitem>
 	  <para>A6 records</para>
 	</listitem>
       </itemizedlist>
 
       <para>Using AAAA records is straightforward.  Assign your hostname to the new
 	IPv6 address you just got by adding:</para>
 
       <programlisting>MYHOSTNAME           AAAA    MYIPv6ADDR</programlisting>
 
       <para>To your primary zone DNS file.  In case you do not serve your own
 	<acronym>DNS</acronym> zones ask your <acronym>DNS</acronym> provider.
 	Current versions of <application>bind</application> (version 8.3 and 9)
 	support AAAA records.</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/backups/chapter.sgml b/en_US.ISO8859-1/books/handbook/backups/chapter.sgml
index 95cc00512d..b8f1e7be55 100644
--- a/en_US.ISO8859-1/books/handbook/backups/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/backups/chapter.sgml
@@ -1,861 +1,861 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="backups">
   <title>Backups</title>
 
-  <sect1>
+  <sect1 id="backups-synopsis">
     <title>Synopsis</title>
 
     <para>The following chapter will cover methods of backing up data, and
       the programs used to create those backups.</para>
   </sect1>
 
   <sect1 id="backups-tapebackups">
     <title>Tape Media</title>
     
     <indexterm><primary>tape media</primary></indexterm>
     <para>The major tape media are the 4mm, 8mm, QIC, mini-cartridge and
       DLT.</para>
     
     <sect2 id="backups-tapebackups-4mm">
       <title>4mm (DDS: Digital Data Storage)</title>
 
       <indexterm>
         <primary>tape media</primary>
 	<secondary>DDS (4mm) tapes</secondary>
       </indexterm>
       <indexterm>
         <primary>tape media</primary>
 	<secondary>QIC tapes</secondary>
       </indexterm>
       <para>4mm tapes are replacing QIC as the workstation backup media of
 	choice.  This trend accelerated greatly when Conner purchased Archive,
 	a leading manufacturer of QIC drives, and then stopped production of
 	QIC drives.  4mm drives are small and quiet but do not have the
 	reputation for reliability that is enjoyed by 8mm drives.  The
 	cartridges are less expensive and smaller (3 x 2 x 0.5 inches, 76 x 51
 	x 12 mm) than 8mm cartridges.  4mm, like 8mm, has comparatively short
 	head life for the same reason, both use helical scan.</para>
 
       <para>Data throughput on these drives starts ~150kB/s, peaking at ~500kB/s.
 	Data capacity starts at 1.3 GB and ends at 2.0 GB.  Hardware
 	compression, available with most of these drives, approximately
 	doubles the capacity.  Multi-drive tape library units can have 6
 	drives in a single cabinet with automatic tape changing.  Library
 	capacities reach 240 GB.</para>
 
       <para>The DDS-3 standard now supports tape capacities up to 12 GB (or
 	24 GB compressed).</para>
 
       <para>4mm drives, like 8mm drives, use helical-scan.  All the benefits
 	and drawbacks of helical-scan apply to both 4mm and 8mm drives.</para>
 
       <para>Tapes should be retired from use after 2,000 passes or 100 full
 	backups.</para>
     </sect2>
     
     <sect2 id="backups-tapebackups-8mm">
       <title>8mm (Exabyte)</title>
       <indexterm>
         <primary>tape media</primary>
 	<secondary>Exabyte (8mm) tapes</secondary>
       </indexterm>
 
       <para>8mm tapes are the most common SCSI tape drives; they are the best
 	choice of exchanging tapes.  Nearly every site has an Exabyte 2 GB 8mm
 	tape drive.  8mm drives are reliable, convenient and quiet. Cartridges
 	are inexpensive and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm).
 	One downside of 8mm tape is relatively short head and tape life due to
 	the high rate of relative motion of the tape across the heads.</para>
 
       <para>Data throughput ranges from ~250kB/s to ~500kB/s.  Data sizes start
 	at 300 MB and go up to 7 GB.  Hardware compression, available with
 	most of these drives, approximately doubles the capacity.  These
 	drives are available as single units or multi-drive tape libraries
 	with 6 drives and 120 tapes in a single cabinet.  Tapes are changed
 	automatically by the unit.  Library capacities reach 840+ GB.</para>
 
       <para>The Exabyte <quote>Mammoth</quote> model supports 12 GB on one tape
 	(24 GB with compression) and costs approximately twice as much as
 	conventional tape drives.</para>
 
       <para>Data is recorded onto the tape using helical-scan, the heads are
 	positioned at an angle to the media (approximately 6 degrees).  The
 	tape wraps around 270 degrees of the spool that holds the heads.  The
 	spool spins while the tape slides over the spool.  The result is a
 	high density of data and closely packed tracks that angle across the
 	tape from one edge to the other.</para>
     </sect2>
     
     <sect2 id="backups-tapebackups-qic">
       <title>QIC</title>
       <indexterm>
         <primary>tape media</primary>
 	<secondary>QIC-150</secondary>
       </indexterm>            
 
       <para>QIC-150 tapes and drives are, perhaps, the most common tape drive
 	and media around.  QIC tape drives are the least expensive "serious"
 	backup drives.  The downside is the cost of media.  QIC tapes are
 	expensive compared to 8mm or 4mm tapes, up to 5 times the price per GB
 	data storage.  But, if your needs can be satisfied with a half-dozen
 	tapes, QIC may be the correct choice.  QIC is the
 	<emphasis>most</emphasis> common tape drive.  Every site has a QIC
 	drive of some density or another.  Therein lies the rub, QIC has a
 	large number of densities on physically similar (sometimes identical)
 	tapes.  QIC drives are not quiet.  These drives audibly seek before
 	they begin to record data and are clearly audible whenever reading,
 	writing or seeking.  QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x
 	10.2 x 1.7 mm).  <link
 	  linkend="backups-tapebackups-mini">Mini-cartridges</link>, which
 	also use 1/4" wide tape are discussed separately.  Tape libraries and
 	changers are not available.</para>
 
       <para>Data throughput ranges from ~150kB/s to ~500kB/s.  Data capacity
 	ranges from 40 MB to 15 GB.  Hardware compression is available on many
 	of the newer QIC drives.  QIC drives are less frequently installed;
 	they are being supplanted by DAT drives.</para>
 
       <para>Data is recorded onto the tape in tracks.  The tracks run along
 	the long axis of the tape media from one end to the other.  The number
 	of tracks, and therefore the width of a track, varies with the tape's
 	capacity.  Most if not all newer drives provide backward-compatibility
 	at least for reading (but often also for writing).  QIC has a good
 	reputation regarding the safety of the data (the mechanics are simpler
 	and more robust than for helical scan drives).</para>
 
       <para>Tapes should be retired from use after 5,000 backups.</para>
     </sect2>
 
     <sect2 id="backups-tapebackups-mini">
       <title>XXX* Mini-Cartridge</title>
       
       <para></para>
     </sect2>
     
     <sect2 id="backups-tapebackups-dlt">
       <title>DLT</title>
       <indexterm>
         <primary>tape media</primary>
 	<secondary>DLT</secondary>
       </indexterm>            
 
       <para>DLT has the fastest data transfer rate of all the drive types
 	listed here.  The 1/2" (12.5mm) tape is contained in a single spool
 	cartridge (4 x 4 x 1 inches; 100 x 100 x 25 mm).  The cartridge has a
 	swinging gate along one entire side of the cartridge.  The drive
 	mechanism opens this gate to extract the tape leader.  The tape leader
 	has an oval hole in it which the drive uses to "hook" the tape.  The
 	take-up spool is located inside the tape drive.  All the other tape
 	cartridges listed here (9 track tapes are the only exception) have
 	both the supply and take-up spools located inside the tape cartridge
 	itself.</para>
 
       <para>Data throughput is approximately 1.5MB/s, three times the throughput of
 	4mm, 8mm, or QIC tape drives.  Data capacities range from 10 GB to 20 GB
 	for a single drive.  Drives are available in both multi-tape changers
 	and multi-tape, multi-drive tape libraries containing from 5 to 900
 	tapes over 1 to 20 drives, providing from 50 GB to 9 TB of
 	storage.</para>
 
       <para>With compression, DLT Type IV format supports up to 70 GB
 	capacity.</para>
 
       <para>Data is recorded onto the tape in tracks parallel to the direction
 	of travel (just like QIC tapes).  Two tracks are written at once.
 	Read/write head lifetimes are relatively long; once the tape stops
 	moving, there is no relative motion between the heads and the
 	tape.</para>
     </sect2>
 
     <sect2>
       <title id="backups-tapebackups-ait">AIT</title>
       <indexterm>
         <primary>tape media</primary>
 	<secondary>AIT</secondary>
       </indexterm>            
 
       <para>AIT is a new format from Sony, and can hold up to 50 GB (with
 	compression) per tape.  The tapes contain memory chips which retain an 
 	index of the tape's contents.  This index can be rapidly read by the
 	tape drive to determine the position of files on the tape, instead of
 	the several minutes that would be required for other tapes.  Software
 	such as SAMS:Alexandria can operate forty or more AIT tape libraries,
 	communicating directly with the tape's memory chip to display the
 	contents on screen, determine what files were backed up to which
 	tape, locate the correct tape, load it, and restore the data from the
 	tape.</para>
 
       <para>Libraries like this cost in the region of $20,000, pricing them a
 	little out of the hobbyist market.</para>
     </sect2>
     
     <sect2>
       <title>Using a New Tape for the First Time</title>
       
       <para>The first time that you try to read or write a new, completely
 	blank tape, the operation will fail.  The console messages should be
 	similar to:</para>
       
       <screen>sa0(ncr1:4:0): NOT READY asc:4,1
 sa0(ncr1:4:0):  Logical unit is in process of becoming ready</screen>
       
       <para>The tape does not contain an Identifier Block (block number 0).
 	All QIC tape drives since the adoption of QIC-525 standard write an
 	Identifier Block to the tape.  There are two solutions:</para>
       
       <para><command>mt fsf 1</command> causes the tape drive to write an
 	Identifier Block to the tape.</para>
       
       <para>Use the front panel button to eject the tape.</para>
       
       <para>Re-insert the tape and <command>dump</command> data to the tape.</para>
       
       <para><command>dump</command> will report <literal>DUMP: End of tape
 	  detected</literal> and the console will show: <literal>HARDWARE
 	  FAILURE info:280 asc:80,96</literal>.</para>
       
       <para>rewind the tape using: <command>mt rewind</command>.</para>
       
       <para>Subsequent tape operations are successful.</para>
     </sect2>
   </sect1>
   
   <sect1 id="backup-programs">
     <title>Backup Programs</title>
     <indexterm><primary>backup software</primary></indexterm>
 
     <para>The three major programs are
 	&man.dump.8;,
 	&man.tar.1;,
       and
 	&man.cpio.1;.</para>
     
     <sect2>
       <title>Dump and Restore</title>
       <indexterm>
         <primary>backup software</primary>
 	<secondary>dump / restore</secondary>
       </indexterm>      
       <indexterm><primary><command>dump</command></primary></indexterm>      
       <indexterm><primary><command>restore</command></primary></indexterm>
 
       <para>The traditional Unix backup programs are
 	<command>dump</command> and <command>restore</command>.  They
 	operate on the drive as a collection of disk blocks, below the
 	abstractions of files, links and directories that are created by
 	the filesystems. <command>dump</command> backs up an entire
 	filesystem on a device.  It is unable to backup only part of a
 	filesystem or a directory tree that spans more than one
 	filesystem.  <command>dump</command> does not write files and
 	directories to tape, but rather writes the raw data blocks that
 	comprise files and directories.</para>
 
       <note><para>If you use <command>dump</command> on your root directory, you
         would not back up <filename>/home</filename>,
         <filename>/usr</filename> or many other directories since
         these are typically mount points for other filesystems or
         symbolic links into those filesystems.</para></note>
 
       <para><command>dump</command>has quirks that remain from its early days in
 	Version 6 of AT&amp;T Unix (circa 1975).  The default
 	parameters are suitable for 9-track tapes (6250 bpi), not the
 	high-density media available today (up to 62,182 ftpi).  These
 	defaults must be overridden on the command line to utilize the
 	capacity of current tape drives.</para>
 
       <indexterm><primary><filename>rhosts</filename></primary></indexterm>
       <para>It is also possible to backup data across the network to a
         tape drive attached to another computer with <command>rdump</command> and
         <command>rrestore</command>.  Both programs rely upon <command>rcmd</command> and
         <command>ruserok</command> to access the remote tape drive.  Therefore,
         the user performing the backup must have
         <literal>rhosts</literal> access to the remote computer.  The
         arguments to <command>rdump</command> and <command>rrestore</command> must be suitable
         to use on the remote computer.  (e.g. When
         <command>rdump</command>ing from a FreeBSD computer to an
         Exabyte tape drive connected to a Sun called
         <hostid>komodo</hostid>, use: <command>/sbin/rdump 0dsbfu
         54000 13000 126 komodo:/dev/nrsa8 /dev/rda0a
         2>&amp;1</command>) Beware: there are security implications to
         allowing <literal>rhosts</literal> commands.  Evaluate your
         situation carefully.</para>
 
       <para>It is also possible to use <command>rdump</command> and
         <command>rrestore</command> in a more secure fashion over
         <command>ssh</command>.</para>
 
       <example>
 	<title>Using <command>rdump</command> over <application>ssh</application></title>
 
 	<screen>&prompt.root; <userinput>/sbin/dump -0uan -f - /usr | gzip -2 | ssh1 -c blowfish \
           targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz</userinput></screen>
 
       </example>
     </sect2>
 
     <sect2>
       <title><command>tar</command></title>
       <indexterm>
         <primary>backup software</primary>
         <secondary><command>tar</command></secondary>
       </indexterm>
       
       <para>&man.tar.1; also dates back to Version 6 of AT&amp;T Unix
 	(circa 1975).  <command>tar</command> operates in cooperation
 	with the filesystem; <command>tar</command> writes files and
 	directories to tape. <command>tar</command> does not support the
 	full range of options that are available from &man.cpio.1;, but
 	<command>tar</command> does not require the unusual command
 	pipeline that <command>cpio</command> uses.</para>
 
       <indexterm><primary><command>tar</command></primary></indexterm>
       <para>Most versions of <command>tar</command> do not support
 	backups across the network.  The GNU version of
 	<command>tar</command>, which FreeBSD utilizes, supports remote
 	devices using the same syntax as <command>rdump</command>.  To
 	<command>tar</command> to an Exabyte tape drive connected to a
 	Sun called <hostid>komodo</hostid>, use: <command>/usr/bin/tar
 	  cf komodo:/dev/nrsa8 . 2>&amp;1</command>.  For versions without
 	remote device support, you can use a pipeline and
 	<command>rsh</command> to send the data to a remote tape
 	drive.</para>
 
       <screen>&prompt.root; <userinput>tar cf - . | rsh <replaceable>hostname</replaceable> dd of=<replaceable>tape-device</replaceable> obs=20b</userinput></screen>
 
       <para>If you are worried about the security of backing up over a
 	network you should use the <command>ssh</command> command
 	instead of <command>rsh</command>.</para>
     </sect2>
     
     <sect2>
       <title><command>cpio</command></title>
       <indexterm>
         <primary>backup software</primary>
         <secondary><command>cpio</command></secondary>
       </indexterm>
 
       <para>&man.cpio.1; is the original Unix file interchange tape
 	program for magnetic media.  <command>cpio</command> has options
 	(among many others) to perform byte-swapping, write a number of
 	different archive formats, and pipe the data to other programs.
 	This last feature makes <command>cpio</command> and excellent
 	choice for installation media.  <command>cpio</command> does not
 	know how to walk the directory tree and a list of files must be
 	provided through <filename>stdin</filename>.</para>
       <indexterm><primary><command>cpio</command></primary></indexterm>
 
       <para><command>cpio</command> does not support backups across
 	the network.  You can use a pipeline and <command>rsh</command>
 	to send the data to a remote tape drive.</para>
 
       <screen>&prompt.root; <userinput>for f in <replaceable>directory_list; do</replaceable></userinput>
 <userinput>find $f >> backup.list</userinput>
 <userinput>done</userinput>
 &prompt.root; <userinput>cpio -v -o --format=newc < backup.list | ssh <replaceable>user</replaceable>@<replaceable>host</replaceable> "cat > <replaceable>backup_device</replaceable></userinput></screen>
 
       <para>Where <replaceable>directory_list</replaceable> is the list of
 	directories you want to back up,
 	<replaceable>user</replaceable>@<replaceable>host</replaceable> is the
 	user/hostname combination that will be performing the backups, and
 	<replaceable>backup_device</replaceable> is where the backups should
 	be written to (e.g., <filename>/dev/nrsa0</filename>).</para>
     </sect2>
     
     <sect2>
       <title><command>pax</command></title>
       <indexterm>
         <primary>backup software</primary>
         <secondary><command>pax</command></secondary>
       </indexterm>
       <indexterm><primary><command>pax</command></primary></indexterm>
       <indexterm><primary>POSIX</primary></indexterm>
       <indexterm><primary>IEEE</primary></indexterm>
 
       <para>&man.pax.1; is IEEE/POSIX's answer to
 	<command>tar</command> and <command>cpio</command>.  Over the
 	years the various versions of <command>tar</command> and
 	<command>cpio</command> have gotten slightly incompatible.  So
 	rather than fight it out to fully standardize them, POSIX
 	created a new archive utility. <command>pax</command> attempts
 	to read and write many of the various <command>cpio</command>
 	and <command>tar</command> formats, plus new formats of its own.
 	Its command set more resembles <command>cpio</command> than
 	<command>tar</command>.</para>
     </sect2>
 
     <sect2 id="backups-programs-amanda">
       <title><application>Amanda</application></title>
       <indexterm>
         <primary>backup software</primary>
         <secondary><application>Amanda</application></secondary>
       </indexterm>      
       <indexterm><primary><application>Amanda</application></primary></indexterm>
       
       <!-- Remove link until <port> tag is available -->
       <para><application>Amanda</application> (Advanced Maryland
         Network Disk Archiver) is a client/server backup system,
         rather than a single program.  An Amanda server will backup to
         a single tape drive any number of computers that have Amanda
         clients and a network connection to the Amanda server.  A
         common problem at sites with a number of large disks is
         that the length of time required to backup to data directly to tape
         exceeds the amount of time available for the task.  Amanda
         solves this problem.  Amanda can use a "holding disk" to
         backup several filesystems at the same time.  Amanda creates
         "archive sets": a group of tapes used over a period of time to
         create full backups of all the filesystems listed in Amanda's
         configuration file.  The "archive set" also contains nightly
         incremental (or differential) backups of all the filesystems.
         Restoring a damaged filesystem requires the most recent full
         backup and the incremental backups.</para>
 
       <para>The configuration file provides fine control of backups and the
 	network traffic that Amanda generates.  Amanda will use any of the
 	above backup programs to write the data to tape.  Amanda is available
 	as either a port or a package, it is not installed by default.</para>
       </sect2>
 
     <sect2>
       <title>Do Nothing</title>
       
       <para><quote>Do nothing</quote> is not a computer program, but it is the
 	most widely used backup strategy.  There are no initial costs.  There
 	is no backup schedule to follow.  Just say no.  If something happens
 	to your data, grin and bear it!</para>
 
       <para>If your time and your data is worth little to nothing, then
 	<quote>Do nothing</quote> is the most suitable backup program for your
 	computer.  But beware, Unix is a useful tool, you may find that within
 	six months you have a collection of files that are valuable to
 	you.</para>
 
       <para><quote>Do nothing</quote> is the correct backup method for
 	<filename>/usr/obj</filename> and other directory trees that can be
 	exactly recreated by your computer.  An example is the files that
 	comprise the HTML or Postscript version of this Handbook.
 	These document formats have been created from SGML input
 	files.  Creating backups of the HTML or PostScript files is
 	not necessary.  The SGML files are backed up regularly.</para>
     </sect2>
     
     <sect2>
       <title>Which Backup Program Is Best?</title>
       <indexterm>
         <primary>LISA</primary>
       </indexterm>
 
       <para>&man.dump.8; <emphasis>Period.</emphasis> Elizabeth D. Zwicky
 	torture tested all the backup programs discussed here.  The clear
 	choice for preserving all your data and all the peculiarities of Unix
 	filesystems is <command>dump</command>.  Elizabeth created filesystems containing
 	a large variety of unusual conditions (and some not so unusual ones)
 	and tested each program by doing a backup and restore of those
 	filesystems.  The peculiarities included: files with holes, files with
 	holes and a block of nulls, files with funny characters in their
 	names, unreadable and unwritable files, devices, files that change
 	size during the backup, files that are created/deleted during the
 	backup and more.  She presented the results at LISA V in Oct. 1991.
 	See <ulink
 	  url="http://reality.sgi.com/zwicky_neu/testdump.doc.html">torture-testing
 	  Backup and Archive Programs</ulink>.</para>
     </sect2>
     
     <sect2>
       <title>Emergency Restore Procedure</title>
       
       <sect3>
 	<title>Before the Disaster</title>
 
 	<para>There are only four steps that you need to perform in
 	  preparation for any disaster that may occur.</para>
 	<indexterm>
     <primary><command>disklabel</command></primary>
   </indexterm>	    
 
 	<para>First, print the disklabel from each of your disks
 	  (<command>e.g. disklabel da0 | lpr</command>), your filesystem table
 	  (<filename>/etc/fstab</filename>) and all boot messages,
 	  two copies of
 	  each.</para>
 
 	<indexterm><primary>fix-it floppies</primary></indexterm>	    
 	<para>Second, determine that the boot and fix-it floppies
 	  (<filename>boot.flp</filename> and <filename>fixit.flp</filename>)
 	  have all your devices.  The easiest way to check is to reboot your
 	  machine with the boot floppy in the floppy drive and check the boot
 	  messages.  If all your devices are listed and functional, skip on to
 	  step three.</para>
 
 	<para>Otherwise, you have to create two custom bootable
 	  floppies which have a kernel that can mount all of your disks
 	  and access your tape drive.  These floppies must contain:
 	  <command>fdisk</command>, <command>disklabel</command>,
 	  <command>newfs</command>, <command>mount</command>, and
 	  whichever backup program you use.  These programs must be
 	  statically linked.  If you use <command>dump</command>, the
 	  floppy must contain <command>restore</command>.</para>
 
 	<para>Third, create backup tapes regularly.  Any changes that you make
 	  after your last backup may be irretrievably lost.  Write-protect the
 	  backup tapes.</para>
 
 	<para>Fourth, test the floppies (either <filename>boot.flp</filename>
 	  and <filename>fixit.flp</filename> or the two custom bootable
 	  floppies you made in step two.) and backup tapes.  Make notes of the
 	  procedure.  Store these notes with the bootable floppy, the
 	  printouts and the backup tapes.  You will be so distraught when
 	  restoring that the notes may prevent you from destroying your backup
 	  tapes (How? In place of <command>tar xvf /dev/rsa0</command>, you
 	  might accidentally type <command>tar cvf /dev/rsa0</command> and
 	  over-write your backup tape).</para>
 
 	<para>For an added measure of security, make bootable floppies and two
 	  backup tapes each time.  Store one of each at a remote location.  A
 	  remote location is NOT the basement of the same office building.  A
 	  number of firms in the World Trade Center learned this lesson the
 	  hard way.  A remote location should be physically separated from
 	  your computers and disk drives by a significant distance.</para>
 
 	<example>
 	  <title>A Script for Creating a Bootable Floppy</title>
 	  
 	<programlisting><![ CDATA [#!/bin/sh
 #
 # create a restore floppy
 #
 # format the floppy
 #
 PATH=/bin:/sbin:/usr/sbin:/usr/bin
 
 fdformat -q fd0
 if [ $? -ne 0 ]
 then
 	 echo "Bad floppy, please use a new one"
 	 exit 1
 fi
 
 # place boot blocks on the floppy
 #
 disklabel -w -B /dev/fd0c fd1440
 
 #
 # newfs the one and only partition
 #
 newfs -t 2 -u 18 -l 1 -c 40 -i 5120 -m 5 -o space /dev/fd0a
 
 #
 # mount the new floppy
 #
 mount /dev/fd0a /mnt
 
 #
 # create required directories 
 #
 mkdir /mnt/dev
 mkdir /mnt/bin
 mkdir /mnt/sbin
 mkdir /mnt/etc
 mkdir /mnt/root
 mkdir /mnt/mnt			# for the root partition
 mkdir /mnt/tmp
 mkdir /mnt/var
 
 #
 # populate the directories
 #
 if [ ! -x /sys/compile/MINI/kernel ] 
 then
 	 cat << EOM
 The MINI kernel does not exist, please create one.
 Here is an example config file:
 #
 # MINI -- A kernel to get FreeBSD onto a disk.
 #
 machine         "i386"
 cpu             "I486_CPU"
 ident           MINI
 maxusers        5
 
 options         INET                    # needed for _tcp _icmpstat _ipstat
                                         #            _udpstat _tcpstat _udb
 options         FFS                     #Berkeley Fast File System
 options         FAT_CURSOR              #block cursor in syscons or pccons
 options         SCSI_DELAY=15           #Be pessimistic about Joe SCSI device
 options         NCONS=2                 #1 virtual consoles
 options         USERCONFIG              #Allow user configuration with -c XXX
 
 config          kernel	root on da0 swap on da0 and da1 dumps on da0
 
 device          isa0
 device          pci0
 
 device          fdc0	at isa? port "IO_FD1" bio irq 6 drq 2 vector fdintr
 device          fd0	at fdc0 drive 0
 
 device          ncr0
 
 device          scbus0
 
 device          sc0	at isa? port "IO_KBD" tty irq 1 vector scintr
 device          npx0	at isa? port "IO_NPX" irq 13 vector npxintr
 
 device          da0
 device          da1
 device          da2
 
 device          sa0
 
 pseudo-device   loop            # required by INET
 pseudo-device   gzip            # Exec gzipped a.out's
 EOM
 	 exit 1
 fi
 
 cp -f /sys/compile/MINI/kernel /mnt
 
 gzip -c -best /sbin/init > /mnt/sbin/init
 gzip -c -best /sbin/fsck > /mnt/sbin/fsck
 gzip -c -best /sbin/mount > /mnt/sbin/mount
 gzip -c -best /sbin/halt > /mnt/sbin/halt
 gzip -c -best /sbin/restore > /mnt/sbin/restore
 
 gzip -c -best /bin/sh > /mnt/bin/sh
 gzip -c -best /bin/sync > /mnt/bin/sync
 
 cp /root/.profile /mnt/root
 
 cp -f /dev/MAKEDEV /mnt/dev
 chmod 755 /mnt/dev/MAKEDEV
 
 chmod 500 /mnt/sbin/init
 chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt
 chmod 555 /mnt/bin/sh /mnt/bin/sync
 chmod 6555 /mnt/sbin/restore
 
 #
 # create the devices nodes 
 #
 cd /mnt/dev
 ./MAKEDEV std
 ./MAKEDEV da0
 ./MAKEDEV da1
 ./MAKEDEV da2
 ./MAKEDEV sa0
 ./MAKEDEV pty0
 cd /
 
 #
 # create minimum filesystem table
 #
 cat > /mnt/etc/fstab <<EOM
 /dev/fd0a    /    ufs    rw  1  1
 EOM
 
 #
 # create minimum passwd file
 #
 cat > /mnt/etc/passwd <<EOM
 root:*:0:0:Charlie &:/root:/bin/sh
 EOM
 
 cat > /mnt/etc/master.passwd <<EOM
 root::0:0::0:0:Charlie &:/root:/bin/sh
 EOM
 
 chmod 600 /mnt/etc/master.passwd
 chmod 644 /mnt/etc/passwd
 /usr/sbin/pwd_mkdb -d/mnt/etc /mnt/etc/master.passwd
 
 #
 # umount the floppy and inform the user
 #
 /sbin/umount /mnt
 echo "The floppy has been unmounted and is now ready."]]></programlisting>
 
         </example>
 
       </sect3>
       
       <sect3>
 	<title>After the Disaster</title>
 
 	<para>The key question is: did your hardware survive?  You have been
 	  doing regular backups so there is no need to worry about the
 	  software.</para>
 
 	<para>If the hardware has been damaged.  First, replace those parts
 	  that have been damaged.</para>
 
 	<para>If your hardware is okay, check your floppies.  If you are using
 	  a custom boot floppy, boot single-user (type <literal>-s</literal>
 	  at the <prompt>boot:</prompt> prompt).  Skip the following
 	  paragraph.</para>
 	  
 	<para>If you are using the <filename>boot.flp</filename> and
 	  <filename>fixit.flp</filename> floppies, keep reading.  Insert the
 	  <filename>boot.flp</filename> floppy in the first floppy drive and
 	  boot the computer.  The original install menu will be displayed on
 	  the screen.  Select the <literal>Fixit--Repair mode with CDROM or
 	    floppy.</literal> option.  Insert the
 	  <filename>fixit.flp</filename> when prompted.
 	  <command>restore</command> and the other programs that you need are
 	  located in <filename>/mnt2/stand</filename>.</para>
 
 	<para>Recover each filesystem separately.</para>
 
 	<indexterm>
     <primary><command>mount</command></primary>
   </indexterm>	    
 	<indexterm><primary>root partition</primary></indexterm>
 	<indexterm>
     <primary><command>disklabel</command></primary>
   </indexterm> 
 	<indexterm>
     <primary><command>newfs</command></primary>
   </indexterm> 
 	<para>Try to <command>mount</command> (e.g. <command>mount /dev/da0a
 	    /mnt</command>)  the root partition of your first disk.  If the
 	  disklabel was damaged, use <command>disklabel</command> to re-partition and
 	  label the disk to match the label that you printed and saved.  Use
 	    <command>newfs</command> to re-create the filesystems.  Re-mount the root
 	  partition of the floppy read-write (<command>mount -u -o rw
 	    /mnt</command>).  Use your backup program and backup tapes to
 	  recover the data for this filesystem (e.g. <command>restore vrf
 	    /dev/sa0</command>).  Unmount the filesystem (e.g. <command>umount
 	    /mnt</command>) Repeat for each filesystem that was
 	  damaged.</para>
 
 	<para>Once your system is running, backup your data onto new tapes.
 	  Whatever caused the crash or data loss may strike again.  Another
 	  hour spent now may save you from further distress later.</para>
       </sect3>
 
 <![ %not.published; [
 
       <sect3>
 	<title>* I did not prepare for the Disaster, What Now?</title>
 
 	<para></para>
       </sect3>
 ]]>
 
     </sect2>
   </sect1>
 
   <sect1 id="backups-floppybackups">
     <title>What About Backups to Floppies?</title>
 
     <sect2 id="floppies-using">
       <title>Can I Use floppies for Backing Up My Data?</title>
       <indexterm><primary>backup floppies</primary></indexterm> 
       <indexterm><primary>floppy disks</primary></indexterm> 
       
       <para>Floppy disks are not really a suitable media for
         making backups as:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>The media is unreliable, especially over long periods of
 	    time</para>
 	</listitem>
 
 	<listitem>
 	  <para>Backing up and restoring is very slow</para>
 	</listitem>
 
 	<listitem>
 	  <para>They have a very limited capacity (the days of backing up
 	    an entire hard disk onto a dozen or so floppies has long since
 	    passed).</para>
 	</listitem>
       </itemizedlist>
 
       <para>However, if you have no other method of backing up your data then
 	floppy disks are better than no backup at all.</para>
 
       <para>If you do have to use floppy disks then ensure that you use good
 	quality ones. Floppies that have been lying around the office for a
 	couple of years are a bad choice. Ideally use new ones from a
 	reputable manufacturer.</para>
     </sect2>
     
     <sect2 id="floppies-creating">
       <title>So How Do I Backup My Data to Floppies?</title>
 
       <para>The best way to backup to floppy disk is to use
 	<command>tar</command> with the <option>-M</option> (multi
 	volume) option, which allows backups to span multiple
 	floppies.</para>
 
       <para>To backup all the files in the current directory and sub-directory
 	use this (as <username>root</username>):</para>
 
       <screen>&prompt.root; <userinput>tar Mcvf /dev/fd0 *</userinput></screen>
 
       <para>When the first floppy is full <command>tar</command> will prompt you to
 	insert the next volume (because <command>tar</command> is media independent it
 	refers to volumes. In this context it means floppy disk)</para>
 
       <screen>Prepare volume #2 for /dev/fd0 and hit return:</screen>
 
       <para>This is repeated (with the volume number incrementing) until all
 	the specified files have been archived.</para>
     </sect2>
 
     <sect2 id="floppies-compress">
       <title>Can I Compress My Backups?</title>
       <indexterm>
         <primary><command>tar</command></primary>
       </indexterm> 
       <indexterm>
         <primary><command>gzip</command></primary>
       </indexterm> 
       <indexterm><primary>compression</primary></indexterm> 
 
       <para>Unfortunately, <command>tar</command> will not allow the
 	<option>-z</option> option to be used for multi-volume archives.
 	You could, of course, <command>gzip</command> all the files,
 	<command>tar</command> them to the floppies, then
 	<command>gunzip</command> the files again!</para>
     </sect2>
 
     <sect2 id="floppies-restoring">
       <title>How Do I Restore My Backups?</title>
       
       <para>To restore the entire archive use:</para>
 
       <screen>&prompt.root; <userinput>tar Mxvf /dev/fd0</userinput></screen>
 
       <para>There are two ways that you can use to restore only
 	specific files.  First, you can start with the first floppy
 	and use:</para>
 
       <screen>&prompt.root; <userinput>tar Mxvf /dev/fd0 <replaceable>filename</replaceable></userinput></screen>
 
       <para><command>tar</command> will prompt you to insert subsequent floppies until it
 	finds the required file.</para>
 
       <para>Alternatively, if you know which floppy the file is on then you
 	can simply insert that floppy and use the same command as above. Note
 	that if the first file on the floppy is a continuation from the
 	previous one then <command>tar</command> will warn you that it cannot
 	restore it, even if you have not asked it to!</para>
     </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
index d54feaff0c..40ae37695b 100644
--- a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
@@ -1,1799 +1,1799 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="basics">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Chris</firstname>
 	<surname>Shumway</surname>
 	<contrib>Rewritten by </contrib>
       </author>
     </authorgroup>
     <!-- 10 Mar 2000 -->
   </chapterinfo>
 
   <title>Unix Basics</title>
   
-  <sect1>
+  <sect1 id="basics-synopsis">
     <title>Synopsis</title>
     <indexterm><primary>basics</primary></indexterm>
 
 
    <para>The following chapter will cover the basic commands and
      functionality of the FreeBSD operating system.  Much of this
      material is relevant for any Unix-like operating system.  Feel
      free to skim over this chapter if you are familiar with the
      material.  If you are new to FreeBSD, then you will definitely
      want to read through this chapter carefully.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How Unix file permissions work.</para>
       </listitem>
       <listitem>
 	<para>What file system <acronym>ACL</acronym>s are and how to use them.</para>
       </listitem>
       <listitem>
 	<para>What processes, daemons, and signals are.</para>
       </listitem>
       <listitem>
 	<para>What a shell is, and how to change your default login
 	environment.</para>
       </listitem>
       <listitem>
 	<para>How to use basic text editors.</para>
       </listitem>
       <listitem>
 	<para>How to read manual pages for more information.</para>
       </listitem>
       <listitem>
         <para>How to use the <quote>virtual consoles</quote> of
 	  FreeBSD.</para>
       </listitem>
     </itemizedlist>
 
   </sect1>
 
   <sect1 id="permissions">
     <title>Permissions</title>
     <indexterm><primary>Unix</primary></indexterm>
 
     <para>FreeBSD, being a direct descendant of BSD Unix, is based on
       several key Unix concepts.  The first, and
       most pronounced, is that FreeBSD is a multi-user operating system.
       The system can handle several users all working simultaneously on
       completely unrelated tasks.  The system is responsible for properly
       sharing and managing requests for hardware devices, peripherals,
       memory, and CPU time evenly to each user.</para>
 
     <para>Because the system is capable of supporting multiple users,
       everything the system manages has a set of permissions governing who
       can read, write, and execute the resource.  These permissions are
       stored as two octets broken into three pieces, one for the owner of
       the file, one for the group that the file belongs to, and one for
       everyone else.  This numerical representation works like
       this:</para>
 
     <indexterm><primary>permissions</primary></indexterm>
     <indexterm>
       <primary>file permissions</primary>
     </indexterm>
     <informaltable frame="none">
       <tgroup cols="3">
 	<thead>
 	  <row>
 	    <entry>Value</entry>
 	    <entry>Permission</entry>
 	    <entry>Directory Listing</entry>
 	  </row>
 	</thead>
 
 	<tbody>
 	  <row>
 	    <entry>0</entry>
 	    <entry>No read, no write, no execute</entry>
 	    <entry><literal>---</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>1</entry>
 	    <entry>No read, no write, execute</entry>
 	    <entry><literal>--x</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>2</entry>
 	    <entry>No read, write, no execute</entry>
 	    <entry><literal>-w-</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>3</entry>
 	    <entry>No read, write, execute</entry>
 	    <entry><literal>-wx</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>4</entry>
 	    <entry>Read, no write, no execute</entry>
 	    <entry><literal>r--</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>5</entry>
 	    <entry>Read, no write, execute</entry>
 	    <entry><literal>r-x</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>6</entry>
 	    <entry>Read, write, no execute</entry>
 	    <entry><literal>rw-</literal></entry>
 	  </row>
 
 	  <row>
 	    <entry>7</entry>
 	    <entry>Read, write, execute</entry>
 	    <entry><literal>rwx</literal></entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
     <indexterm>
       <primary><command>ls</command></primary>
     </indexterm>
     <indexterm><primary>directories</primary></indexterm>
 
     <para>You can use the <option>-l</option> command line
       argument to &man.ls.1; to view a long directory listing that
       includes a column with information about a file's permissions
       for the owner, group, and everyone else.  Here is how the first
       column of <command>ls -l</command> is broken up:</para>
 
     <screen>-rw-r--r--</screen>
 
     <para>The first (leftmost) character
       tells if this file is a regular file, a directory, a special
       character device, a socket, or any other special
       pseudo-file device.  In this case, the <literal>-</literal>
       indicates a regular file.  The next three characters,
       <literal>rw-</literal> in this example, give the permissions for the owner of the
       file.  The next three characters, <literal>r--</literal>, give the
       permissions for the group that the file belongs to.  The final three
       characters, <literal>r--</literal>, give the permissions for the
       rest of the world.  A dash means that the permission is turned off.
       In the case of this file, the permissions are set so the owner can
       read and write to the file, the group can read the file, and the
       rest of the world can only read the file.  According to the table
       above, the permissions for this file would be
       <literal>644</literal>, where each digit represents the three parts
       of the file's permission.</para>
 
     <para>This is all well and good, but how does the system control
       permissions on devices? FreeBSD actually treats most hardware
       devices as a file that programs can open, read, and write data to
       just like any other file.  These special device files are stored on
       the <filename>/dev</filename> directory.</para>
 
     <para>Directories are also treated as files.  They have read, write,
       and execute permissions.  The executable bit for a directory has a
       slightly different meaning than that of files.  When a directory is
       marked executable, it means it can be moved into, i.e. it is
       possible to <quote>cd</quote> into it.  This also means that
       within the directory it is possible to access files whose names are
       known (subject, of course, to the permissions on the files
       themselves).</para>
 
     <para>In particular, in order to perform a directory listing,
       read permission must be set on the directory, whilst to delete a file
       that one knows the name of, it is necessary to have write
       <emphasis>and</emphasis> execute permissions to the directory
       containing the file.</para>
 
     <para>There are more permission bits, but they are primarily used in
       special circumstances such as setuid binaries and sticky
       directories.  If you want more information on file permissions and
       how to set them, be sure to look at the &man.chmod.1; manual
       page.</para>
   </sect1>
   
     <sect1 id="fs-acl">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Rhodes</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <indexterm>
       <primary>ACL</primary>
     </indexterm>
     <title>File System Access Control Lists</title>
 
     <para>In conjunction with file system enhancements like snapshots, FreeBSD 5.0
       and later offers the security of File System Access Control Lists
       (<acronym>ACLs</acronym>).</para>
 
     <para>Access Control Lists extend the standard UNIX
       permission model in a highly compatible (POSIX.1e) way.  This feature
       permits an administrator to make use of and take advantage of a
       more sophisticated security model.</para>
 
     <para>To enable <acronym>ACL</acronym> support for <acronym>UFS</acronym>
       file systems, the following:</para>
 
     <programlisting>options UFS_ACL</programlisting>
 
     <para>must be compiled into the kernel.  If this option has
       not been compiled in, a warning message will be displayed
       when attempting to mount a file system supporting <acronym>ACLs</acronym>.
       This option is included in the <filename>GENERIC</filename> kernel.
       <acronym>ACLs</acronym> rely on extended attributes being enabled on
       the file system.  Extended attributes are natively supported in the next generation
       UNIX file system, <acronym>UFS2</acronym>.</para>
 
     <note><para>A higher level of administrative overhead is required to
       configure extended attributes on <acronym>UFS1</acronym> than on
       <acronym>UFS2</acronym>.  The performance of extended attributes
       on <acronym>UFS2</acronym> is also substantially higher.  As a
       result, <acronym>UFS2</acronym> is generally recommended in preference
       to <acronym>UFS1</acronym> for use with access control lists.</para></note>
 
     <para><acronym>ACLs</acronym> are enabled by the mount-time administrative
       flag, <option>acls</option>, which may be added to <filename>/etc/fstab</filename>.
       The mount-time flag can also be automatically set in a persistent manner using
       &man.tunefs.8; to modify a superblock <acronym>ACLs</acronym> flag in the
       file system header.  In general, it is preferred to use the superblock flag
       for several reasons:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The mount-time <acronym>ACLs</acronym> flag cannot be changed by a
 	remount (&man.mount.8; <option>-u</option>), only by means of a complete
 	&man.umount.8; and fresh &man.mount.8;.  This means that
 	<acronym>ACLs</acronym> cannot be enabled on the root file system after boot.
 	It also means that you cannot change the disposition of a file system once
 	it is in use.</para>
       </listitem>
 
       <listitem>
 	<para>Setting the superblock flag will cause the file system to always be
 	mounted with <acronym>ACLs</acronym> enabled even if there is not an
 	<filename>fstab</filename> entry or if the devices re-order.  This prevents
 	accidental mounting of the file system without <acronym>ACLs</acronym>
 	enabled, which can result in <acronym>ACLs</acronym> being improperly enforced,
 	and hence security problems.</para>
       </listitem>
     </itemizedlist>
 
     <note><para>We may change the <acronym>ACLs</acronym> behavior to allow the flag to
       be enabled without a complete fresh &man.mount.8;, but we consider it desirable to
       discourage accidental mounting without <acronym>ACLs</acronym> enabled, because you
       can shoot your feet quite nastily if you enable <acronym>ACLs</acronym>, then disable
       them, then re-enable them without flushing the extended attributes.  In general, once
       you have enabled <acronym>ACLs</acronym> on a file system, they should not be disabled,
       as the resulting file protections may not be compatible with those intended by the
       users of the system, and re-enabling <acronym>ACLs</acronym> may re-attach the previous
       <acronym>ACLs</acronym> to files that have since had their permissions changed,
       resulting in other unpredictable behavior.</para></note>
       
     <para>File systems with <acronym>ACLs</acronym> enabled will show a <literal>+</literal>
       (plus) sign in their permission settings when viewed.  For example:</para>
 
     <programlisting>drwx------  2 robert  robert  512 Dec 27 11:54 private
 drwxrwx---+ 2 robert  robert  512 Dec 23 10:57 directory1
 drwxrwx---+ 2 robert  robert  512 Dec 22 10:20 directory2
 drwxrwx---+ 2 robert  robert  512 Dec 27 11:57 directory3
 drwxr-xr-x  2 robert  robert  512 Nov 10 11:54 public_html</programlisting>
 
     <para>Here we see that the <filename>directory1</filename>,
       <filename>directory2</filename>, and <filename>directory3</filename>
       directories are all taking advantage of <acronym>ACLs</acronym>.  The
       <filename>public_html</filename> directory is not.</para>
   </sect1>
 
   <sect1 id="dirstructure">
     <title>Directory Structure</title>
     <indexterm><primary>directory hierarchy</primary></indexterm>
 
     <para>The FreeBSD directory hierarchy is fundamental to obtaining
       an overall understanding of the system.  The most important
       concept to grasp is that of the root directory,
       <quote>/</quote>.  This directory is the first one mounted at
       boot time and it contains the base system necessary to prepare
       the operating system for multi-user operation.  The root
       directory also contains mount points for every other file system
       that you may want to mount.</para>
 
     <para>A mount point is a directory where additional file systems can
       be grafted onto the root file system.  Standard mount points include
       <filename>/usr</filename>, <filename>/var</filename>,
       <filename>/mnt</filename>, and <filename>/cdrom</filename>.  These
       directories are usually referenced to entries in the file
       <filename>/etc/fstab</filename>.  <filename>/etc/fstab</filename> is
       a table of various file systems and mount points for reference by the
       system.  Most of the file systems in <filename>/etc/fstab</filename>
       are mounted automatically at boot time from the script &man.rc.8;
       unless they contain the <option>noauto</option> option.  Consult the
       &man.fstab.5; manual page for more information on the format of the
       <filename>/etc/fstab</filename> file and the options it
       contains.</para>
 
     <para>A complete description of the file system hierarchy is
       available in &man.hier.7;.  For now, a brief overview of the
       most common directories will suffice.</para>
 
     <para>
       <informaltable frame="none">
         <tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Directory</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 	  <tbody>
             <row>
 	      <entry><filename class="directory">/</filename></entry>
 	      <entry>Root directory of the file system.</entry>
             </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/bin/</filename></entry>
 	      <entry>User utilities fundamental to both single-user
 	      and multi-user environments.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/boot/</filename></entry>
 	      <entry>Programs and configuration files used during
 	      operating system bootstrap.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/boot/defaults/</filename></entry>
 	      <entry>Default bootstrapping configuration files; see
 	      &man.loader.conf.5;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/dev/</filename></entry>
 	      <entry>Device nodes; see &man.intro.4;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/</filename></entry>
 	      <entry>System configuration files and scripts.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/defaults/</filename></entry>
 	      <entry>Default system configuration files; see &man.rc.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/mail/</filename></entry>
 	      <entry>Configuration files for mail transport agents such
 		as &man.sendmail.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/namedb/</filename></entry>
 	      <entry><command>named</command> configuration files; see
 	      &man.named.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/periodic/</filename></entry>
 	      <entry>Scripts that are run daily, weekly, and monthly,
 		via &man.cron.8;; see &man.periodic.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/etc/ppp/</filename></entry>
 	      <entry><command>ppp</command> configuration files; see
 	      &man.ppp.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/mnt/</filename></entry>
 	      <entry>Empty directory commonly used by system administrators as a 
 		temporary mount point.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/proc/</filename></entry>
 	      <entry>Process file system; see &man.procfs.5;,
 	      &man.mount.procfs.8;.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/root/</filename></entry>
 	      <entry>Home directory for the <username>root</username>
 	      account.</entry>
 	    </row>
 
 	    <row>
 	      <entry><filename class="directory">/sbin/</filename></entry>
 	      <entry>System programs and administration utilities fundamental to
 		both single-user and multi-user environments.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/stand/</filename></entry>
 	      <entry>Programs used in a standalone environment.</entry>
 	    </row>
 	    
 	    
 	    <row>
 	      <entry><filename class="directory">/tmp/</filename></entry>
 	      <entry>Temporary files, usually a &man.mfs.8;
 		memory-based file system (the contents of <filename
 		class="directory">/tmp</filename> are usually NOT
 		preserved across a system reboot).</entry>
 	    </row>
 	    
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/</filename></entry>
 	      <entry>The majority of user utilities and applications.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/bin/</filename></entry>
 	      <entry>Common utilities, programming tools, and applications.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/include/</filename></entry>
 	      <entry>Standard C include files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/lib/</filename></entry>
 	      <entry>Archive libraries.</entry>
 	    </row>
 	    
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/libdata/</filename></entry>
 	      <entry>Miscellaneous utility data files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/libexec/</filename></entry>
 	      <entry>System daemons & system utilities (executed by other
 		programs).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename
 	      class="directory">/usr/local/</filename></entry>
 
 	      <entry>Local executables, libraries, etc.  Also used as
 	        the default destination for the FreeBSD ports
 	        framework.  Within <filename>/usr/local</filename>,
 	        the general layout sketched out by &man.hier.7; for
 	        <filename>/usr</filename> should be used.  Exceptions
 	        are the man directory, which is directly under
 	        <filename>/usr/local</filename> rather than under
 	        <filename>/usr/local/share</filename>, and the ports
 	        documentation is in
 	        <filename>share/doc/<replaceable>port</replaceable></filename>.
 	      </entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/obj/</filename></entry>
 	      <entry>Architecture-specific target tree produced by building
 		the <filename>/usr/src</filename> tree.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/ports</filename></entry>
 	      <entry>The FreeBSD ports collection (optional).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/sbin/</filename></entry>
 	      <entry>System daemons & system utilities (executed by users).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/share/</filename></entry>
 	      <entry>Architecture-independent files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/usr/src/</filename></entry>
 	      <entry>BSD and/or local source files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename
 	      class="directory">/usr/X11R6/</filename></entry>
 	      <entry>X11R6 distribution executables, libraries, etc
 	      (optional).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/var/</filename></entry>
 	      <entry>Multi-purpose log, temporary, transient, and spool files.
 	      </entry>
 	    </row>
 	    
 	    
 	    <row>
 	      <entry><filename class="directory">/var/log/</filename></entry>
 	      <entry>Miscellaneous system log files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/var/mail/</filename></entry>
 	      <entry>User mailbox files.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/var/spool/</filename></entry>
 	      <entry>Miscellaneous printer and mail system spooling directories.
 	      </entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename class="directory">/var/tmp/</filename></entry>
 	      <entry>Temporary files that are kept between system reboots.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><filename>/var/yp</filename></entry>
 	      <entry>NIS maps.</entry>
 	    </row>
 
 	  </tbody>
 	</tgroup>
       </informaltable>
     </para>
 
   </sect1>
 
   <sect1 id="mount-unmount">
     <title>Mounting and Unmounting File systems</title>
 
     <para>The file system is best visualized as a tree,
       rooted, as it were, at <filename>/</filename>.
       <filename>/dev</filename>, <filename>/usr</filename>, and the
       other directories in the root directory are branches, which may
       have their own branches, such as
       <filename>/usr/local</filename>, and so on.</para>
 
     <indexterm><primary>root file system</primary></indexterm>
     <para>There are various reasons to house some of these
       directories on separate file systems.  <filename>/var</filename>
       contains the directories <filename>log/</filename>,
       <filename>spool/</filename>,
       and various types of temporary files, and
       as such, may get filled up.  Filling up the root file system
       is not a good idea, so splitting <filename>/var</filename> from
       <filename>/</filename> is often favorable.</para>
 
     <para>Another common reason to contain certain directory trees on
       other file systems is if they are to be housed on separate
       physical disks, or are separate virtual disks, such as <link
 	linkend="nfs">Network File System</link> mounts, or CDROM
       drives.</para>
 
     <sect2 id="disks-fstab">
       <title>The <filename>fstab</filename> File</title>
       <indexterm>
 	<primary>file systems</primary>
 	<secondary>mounted with fstab</secondary>
       </indexterm>
 
       <para>During the <link linkend="boot">boot process</link>,
 	file systems listed in <filename>/etc/fstab</filename> are
 	automatically mounted (unless they are listed with the
 	<option>noauto</option> option).</para>
 
       <para>The <filename>/etc/fstab</filename> file contains a list
 	of lines of the following format:</para>
 
       <programlisting><replaceable>device</replaceable>       <replaceable>/mount-point</replaceable> <replaceable>fstype</replaceable>     <replaceable>options</replaceable>      <replaceable>dumpfreq</replaceable>     <replaceable>passno</replaceable></programlisting>
 
       <variablelist>
 	<varlistentry>
 	  <term><literal>device</literal></term>
 	  <listitem>
 	    <para>A device name (which should exist), as explained in
 	      <xref linkend="disks-naming">.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>mount-point</literal></term>
             
 	  <listitem><para>A directory (which should exist), on which
 	      to mount the file system.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><literal>fstype</literal></term>
             
 	  <listitem><para>The file system type to pass to
 		&man.mount.8;.  The default FreeBSD file system is
 	      <literal>ufs</literal>.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><literal>options</literal></term>
             
 	  <listitem><para>Either <option>rw</option> for read-write
 	      file systems, or <option>ro</option> for read-only
 	      file systems, followed by any other options that may be
 	      needed.  A common option is <option>noauto</option> for
 	      file systems not normally mounted during the boot sequence.
 	      Other options are listed in the &man.mount.8; manual page.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><literal>dumpfreq</literal></term>
           
          <listitem><para>This is used by &man.dump.8; to determine which
              file systems require dumping.  If the field is missing,
              a value of zero is assumed.</para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><literal>passno</literal></term>
 
          <listitem>
            <para>This determines the order in which file systems should
            be checked.  File systems that should be skipped should have
            their <literal>passno</literal> set to zero.  The root
            file system (which needs to be checked before everything
            else) should have it's <literal>passno</literal> set to
            one, and other file systems' <literal>passno</literal>
            should be set to values greater than one.  If more than one
            file systems have the same <literal>passno</literal> then
            &man.fsck.8; will attempt to check file systems in parallel
            if possible.</para>
          </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2 id="disks-mount">
       <title>The <command>mount</command> Command</title>
       <indexterm>
 	<primary>file systems</primary>
 	<secondary>mounting</secondary>
       </indexterm>
         
       <para>The &man.mount.8; command is what is ultimately used to
 	mount file systems.</para>
         
       <para>In its most basic form, you use:</para>
 
       <informalexample>
 	<screen>&prompt.root; <userinput>mount <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></userinput></screen>
       </informalexample>
 
       <para>There are plenty of options, as mentioned in the
 	  &man.mount.8; manual page, but the most common are:</para>
 
       <variablelist>
 	<title>Mount Options</title>
 
 	<varlistentry>
 	  <term><option>-a</option></term>
             
 	  <listitem>
 	    <para>Mount all the file systems listed in
 	      <filename>/etc/fstab</filename>.  Exceptions are those
 	      marked as <quote>noauto</quote>, excluded by the
 	      <option>-t</option> flag, or those that are already
 	      mounted.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-d</option></term>
             
 	  <listitem>
 	    <para>Do everything except for the actual system call.
 	      This option is useful in conjunction with the
 	      <option>-v</option> flag to determine what
 	      &man.mount.8; is actually trying to do.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-f</option></term>
 
 	  <listitem>
 	    <para>Force the mount of an unclean file system
 	      (dangerous), or forces the revocation of write access
 	      when downgrading a file system's mount status from
 	      read-write to read-only.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
           <term><option>-r</option></term>
             
 	  <listitem>
 	    <para>Mount the file system read-only.  This is identical
 	      to using the <option>rdonly</option> argument to the
 	      <option>-o</option> option.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-t</option>
 	    <replaceable>fstype</replaceable></term>
 
 	  <listitem>
 	    <para>Mount the given file system as the given file system
 	      type, or mount only file systems of the given type, if
 	      given the <option>-a</option> option.</para>
               
 	    <para><quote>ufs</quote> is the default file system
 	      type.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-u</option></term>
             
 	  <listitem>
 	    <para>Update mount options on the file system.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-v</option></term>
             
 	  <listitem>
 	    <para>Be verbose.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term><option>-w</option></term>
             
 	  <listitem>
 	    <para>Mount the file system read-write.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
         
       <para>The <option>-o</option> option takes a comma-separated list of
 	the options, including the following:</para>
         
       <variablelist>
 	<varlistentry>
 	  <term>nodev</term>
             
 	  <listitem>
 	    <para>Do not interpret special devices on the
 	      file system.  This is a useful security option.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term>noexec</term>
             
 	  <listitem>
               <para>Do not allow execution of binaries on this
 	      file system.  This is also a useful security option.</para>
 	  </listitem>
 	</varlistentry>
           
 	<varlistentry>
 	  <term>nosuid</term>
             
 	  <listitem>
 	    <para>Do not interpret setuid or setgid flags on the
 	      file system.  This is also a useful security option.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2 id="disks-umount">
       <title>The <command>umount</command> Command</title>
       <indexterm>
 	<primary>file systems</primary>
 	<secondary>unmounting</secondary>
       </indexterm>
         
       <para>The &man.umount.8; command takes, as a parameter, one of a
 	mountpoint, a device name, or the <option>-a</option> or
 	<option>-A</option> option.</para>
         
       <para>All forms take <option>-f</option> to force unmounting,
         and <option>-v</option> for verbosity.  Be warned that
         <option>-f</option> is not generally a good idea.  Forcibly
         unmounting file systems might crash the computer or damage data
         on the file system.</para>
         
       <para><option>-a</option> and <option>-A</option> are used to
 	unmount all mounted file systems, possibly modified by the
 	file system types listed after <option>-t</option>.
 	<option>-A</option>, however, does not attempt to unmount the
 	root file system.</para>
     </sect2>
   </sect1>
 
   <sect1 id="basics-processes">
     <title>Processes</title>
 
     <para>FreeBSD is a multi-tasking operating system.  This means that it
       seems as though more than one program is running at once.  Each program
       running at any one time is called a <firstterm>process</firstterm>.
       Every command you run will start at least one new process, and there are
       a number of system processes that run all the time, keeping the system
       functional.</para>
 
     <para>Each process is uniquely identified by a number called a
       <firstterm>process ID</firstterm>, or <firstterm>PID</firstterm>, and,
       like files, each process also has one owner and group.  The owner and
       group information is used to determine what files and devices the
       process can open, using the file permissions discussed earlier.  Most
       processes also have a parent process.  The parent process is the process
       that started them.  For example, if you are typing commands to the shell
       then the shell is a process, and any commands you run are also
       processes.  Each process you run in this way will have your shell as its
       parent process.  The exception to this is a special process called
       <command>init</command>.  <command>init</command> is always the first
       process, so its PID is always 1.  <command>init</command> is started
       automatically by the kernel when FreeBSD starts.</para>
 
     <para>Two commands are particularly useful to see the processes on the
       system, &man.ps.1; and &man.top.1;.  The &man.ps.1; command is used to
       show a static list of the currently running processes, and can show
       their PID, how much memory they are using, the command line they were
       started with, and so on.  The &man.top.1; command displays all the
       running processes, and updates the display every few seconds, so that
       you can interactively see what your computer is doing.</para>
 
     <para>By default, &man.ps.1; only shows you the commands that are running
       and are owned by you.  For example:</para>
 
     <screen>&prompt.user; <userinput>ps</userinput>
   PID  TT  STAT      TIME COMMAND
   298  p0  Ss     0:01.10 tcsh
  7078  p0  S      2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
 37393  p0  I      0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
 48630  p0  S      2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
 48730  p0  IW     0:00.00 (dns helper) (navigator-linux-)
 72210  p0  R+     0:00.00 ps
   390  p1  Is     0:01.14 tcsh
  7059  p2  Is+    1:36.18 /usr/local/bin/mutt -y
  6688  p3  IWs    0:00.00 tcsh
 10735  p4  IWs    0:00.00 tcsh
 20256  p5  IWs    0:00.00 tcsh
   262  v0  IWs    0:00.00 -tcsh (tcsh)
   270  v0  IW+    0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
   280  v0  IW+    0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
   284  v0  IW     0:00.00 /bin/sh /home/nik/.xinitrc
   285  v0  S      0:38.45 /usr/X11R6/bin/sawfish</screen>
 
     <para>As you can see in this example, the output from &man.ps.1; is
       organized into a number of columns.  <literal>PID</literal> is the
       process ID discussed earlier.  PIDs are assigned starting from 1, go up
       to 99999, and wrap around back to the beginning when you run out.
       <literal>TT</literal> shows the tty the program is running on, and can
       safely be ignored for the moment.  <literal>STAT</literal> shows the
       program's state, and again, can be safely ignored.
       <literal>TIME</literal> is the amount of time the program has been
       running on the CPU&mdash;this is not necessarily the elapsed time since
       you started the program, as some programs spend a lot of time waiting
       for things to happen before they need to spend time on the CPU.
       Finally, <literal>COMMAND</literal> is the command line that was used to
       run the program.</para>
 
     <para>&man.ps.1; supports a number of different options to change the
       information that is displayed.  One of the most useful sets is
       <literal>auxww</literal>.  <option>a</option> displays information
       about all the running processes, not just your own.  <option>u</option>
       displays the username of the process' owner, as well as memory usage.
       <option>x</option> displays information about daemon processes, and
       <option>ww</option> causes &man.ps.1; to display the full command line,
       rather than truncating it once it gets too long to fit on the
       screen.</para>
 
     <para>The output from &man.top.1; is similar.  A sample session looks like
       this:</para>
 
     <screen>&prompt.user; <userinput>top</userinput>
 last pid: 72257;  load averages:  0.13,  0.09,  0.03    up 0+13:38:33  22:39:10
 47 processes:  1 running, 46 sleeping
 CPU states: 12.6% user,  0.0% nice,  7.8% system,  0.0% interrupt, 79.7% idle
 Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
 Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
 
   PID USERNAME PRI NICE  SIZE    RES STATE    TIME   WCPU    CPU COMMAND
 72257 nik       28   0  1960K  1044K RUN      0:00 14.86%  1.42% top
  7078 nik        2   0 15280K 10960K select   2:54  0.88%  0.88% xemacs-21.1.14
   281 nik        2   0 18636K  7112K select   5:36  0.73%  0.73% XF86_SVGA
   296 nik        2   0  3240K  1644K select   0:12  0.05%  0.05% xterm
 48630 nik        2   0 29816K  9148K select   3:18  0.00%  0.00% navigator-linu
   175 root       2   0   924K   252K select   1:41  0.00%  0.00% syslogd
  7059 nik        2   0  7260K  4644K poll     1:38  0.00%  0.00% mutt
 ...</screen>
 
     <para>The output is split into two sections.  The header (the first five
       lines) shows the PID of the last process to run, the system load averages
       (which are a measure of how busy the system is), the system uptime (time
       since the last reboot) and the current time.  The other figures in the
       header relate to how many processes are running (47 in this case), how
       much memory and swap space has been taken up, and how much time the
       system is spending in different CPU states.</para>
 
     <para>Below that are a series of columns containing similar information
       to the output from &man.ps.1;.  As before you can see the PID, the
       username, the amount of CPU time taken, and the command that was run.
       &man.top.1; also defaults to showing you the amount of memory space
       taken by the process.  This is split into two columns, one for total
       size, and one for resident size&mdash;total size is how much memory the
       application has needed, and the resident size is how much it is actually
       using at the moment.  In this example you can see that <application>Netscape</application> has
       required almost 30&nbsp;MB of RAM, but is currently only using 9&nbsp;MB.</para>
 
     <para>&man.top.1; automatically updates this display every two seconds;
       this can be changed with the <option>s</option> option.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="basics-daemons">
     <title>Daemons, Signals, and Killing Processes</title>
 
     <para>When you run an editor it is easy to control the editor, tell it to
       load files, and so on.  You can do this because the editor provides
       facilities to do so, and because the editor is attached to a
       <firstterm>terminal</firstterm>.  Some programs are not designed to be
       run with continuous user input, and so they disconnect from the terminal
       at the first opportunity.  For example, a web server spends all day
       responding to web requests, it normally does not need any input from
       you.  Programs that transport email from site to site are another
       example of this class of application.</para>
 
     <para>We call these programs <firstterm>daemons</firstterm>.  Daemons were
       characters in Greek mythology; neither good or evil, they were little
       attendant spirits that, by and large, did useful things for mankind.
       Much like the web servers and mail servers of today do useful things.
       This is why the BSD mascot has, for a long time, been the cheerful
       looking daemon with sneakers and a pitchfork.</para>
 
     <para>There is a convention to name programs that normally run as daemons
       with a trailing <quote>d</quote>. <application>BIND</application> is the
       Berkeley Internet Name Daemon (and the actual program that executes is called
       <command>named</command>), the <application>Apache</application> web
       server program is called <command>httpd</command>, the line printer
       spooling daemon is <command>lpd</command> and so on.  This is a
       convention, not a hard and fast rule; for example, the main mail daemon
       for the <application>Sendmail</application> application is called
       <command>sendmail</command>, and not <command>maild</command>, as you
       might imagine.</para>
 
     <para>Sometimes you will need to communicate with a daemon process.  These
       communications are called <firstterm>signals</firstterm>, and you can
       communicate with daemons (or with any running process) by sending it a
       signal.  There are a number of different signals that you can
       send&mdash;some of them have a specific meaning, others are interpreted
       by the application, and the application's documentation will tell you
       how that application interprets signals.  You can only send a signal to
       a process that you own.  If you send a signal to someone else's
       process with &man.kill.1; or &man.kill.2; permission will be denied.
       The exception to this is the
       <username>root</username> user, who can send signals to everyone's
       processes.</para>
 
     <para>FreeBSD will also send applications signals in some cases.  If an
       application is badly written, and tries to access memory that it is not
       supposed to, FreeBSD sends the process the <firstterm>Segmentation
 	Violation</firstterm> signal (<literal>SIGSEGV</literal>).  If an
       application has used the &man.alarm.3; system call to be alerted after a
       period of time has elapsed then it will be sent the Alarm signal
       (<literal>SIGALRM</literal>), and so on.</para>
 
     <para>Two signals can be used to stop a process,
       <literal>SIGTERM</literal> and <literal>SIGKILL</literal>.
       <literal>SIGTERM</literal> is the polite way to kill a process; the
       process can <emphasis>catch</emphasis> the signal, realize that you want
       it to shut down, close any log files it may have open, and generally
       finish whatever it is doing at the time before shutting down.  In some
       cases a process may even ignore <literal>SIGTERM</literal> if it is in
       the middle of some task that can not be interrupted.</para>
 
     <para><literal>SIGKILL</literal> can not be ignored by a process.  This is
       the <quote>I do not care what you are doing, stop right now</quote>
       signal.  If you send <literal>SIGKILL</literal> to a process then
       FreeBSD will stop that process there and then<footnote>
 	<para>Not quite true&mdash;there are a few things that can not be
 	  interrupted.  For example, if the process is trying to read from a
 	  file that is on another computer on the network, and the other
 	  computer has gone away for some reason (been turned off, or the
 	  network has a fault), then the process is said to be
 	  <quote>uninterruptible</quote>.  Eventually the process will time
 	  out, typically after two minutes.  As soon as this time out occurs
 	  the process will be killed.</para>
       </footnote>.</para>
 
     <para>The other signals you might want to use are
       <literal>SIGHUP</literal>, <literal>SIGUSR1</literal>, and
       <literal>SIGUSR2</literal>.  These are general purpose signals, and
       different applications will do different things when they are
       sent.</para>
 
     <para>Suppose that you have changed your web server's configuration
       file&mdash;you would like to tell the web server to re-read its
       configuration.  You could stop and restart <command>httpd</command>, but
       this would result in a brief outage period on your web server, which may
       be undesirable.  Most daemons are written to respond to the
       <literal>SIGHUP</literal> signal by re-reading their configuration
       file.  So instead of killing and restarting <command>httpd</command> you
       would send it the <literal>SIGHUP</literal> signal.  Because there is no
       standard way to respond to these signals, different daemons will have
       different behavior, so be sure and read the documentation for the
       daemon in question.</para>
     
     <para>Signals are sent using the &man.kill.1; command, as this example
       shows.</para>
 
     <procedure>
       <title>Sending a Signal to a Process</title>
 
       <para>This example shows how to send a signal to &man.inetd.8;.  The
 	  &man.inetd.8; configuration file is
 	<filename>/etc/inetd.conf</filename>, and &man.inetd.8; will re-read
 	this configuration file when it is sent
 	<literal>SIGHUP</literal>.</para>
 
       <step>
 	<para>Find the process ID of the process you want to send the signal
 	  to.  Do this using &man.ps.1; and &man.grep.1;.  The &man.grep.1;
 	  command is used to search through output, looking for the string you
 	  specify.  This command is run as a normal user, and &man.inetd.8; is
 	  run as <username>root</username>, so the <option>ax</option> options
 	  must be given to &man.ps.1;.</para>
 
 	<screen>&prompt.user; <userinput>ps -ax | grep inetd</userinput>
   198  ??  IWs    0:00.00 inetd -wW</screen>
 
 	<para>So the &man.inetd.8; PID is 198.  In some cases the
 	  <literal>grep inetd</literal> command might also occur in this
 	  output.  This is because of the way &man.ps.1; has to find the list
 	  of running processes.</para>
       </step>
 
       <step>
 	<para>Use &man.kill.1; to send the signal.  Because &man.inetd.8; is
 	  being run by <username>root</username> you must use &man.su.1; to
 	  become <username>root</username> first.</para>
 
 	<screen>&prompt.user; <userinput>su</userinput>
 <prompt>Password:</prompt>
 &prompt.root; <userinput>/bin/kill -s HUP 198</userinput></screen>
 
 	<para>In common most with Unix commands, &man.kill.1; will not print any
 	  output if it is successful.  If you send a signal to a
 	  process that you do not own then you will see <errorname>kill:
 	    <replaceable>PID</replaceable>: Operation not
 	    permitted</errorname>.  If you mistype the PID you will either
 	  send the signal to the wrong process, which could be bad, or, if
 	  you are lucky, you will have sent the signal to a PID that is not
 	  currently in use, and you will see <errorname>kill:
 	    <replaceable>PID</replaceable>: No such process</errorname>.</para>
 
 	<note>
 	  <title>Why Use <command>/bin/kill</command>?</title>
 
 	  <para>Many shells provide the <command>kill</command> command as a
 	    built in command; that is, the shell will send the signal
 	    directly, rather than running <filename>/bin/kill</filename>.
 	    This can be very useful, but different shells have a different
 	    syntax for specifying the name of the signal to send.  Rather than
 	    try to learn all of them, it can be simpler just to use the
 	    <command>/bin/kill <replaceable>...</replaceable></command>
 	    command directly.</para>
 	</note>
       </step>
     </procedure>
 
     <para>Sending other signals is very similar, just substitute
       <literal>TERM</literal> or <literal>KILL</literal> in the command line
       as necessary.</para>
 
     <important>
       <para>Killing random process on the system can be a bad idea.  In
 	particular, &man.init.8;, process ID 1, is very special.  Running
 	<command>/bin/kill -s KILL 1</command> is a quick way to shutdown your
 	system.  <emphasis>Always</emphasis> double check the arguments you
 	run &man.kill.1; with <emphasis>before</emphasis> you press
 	<keycap>Return</keycap>.</para>
     </important>
   </sect1>
 
   <sect1 id="shells">
     <title>Shells</title>
     <indexterm><primary>shells</primary></indexterm>
     <indexterm><primary>command line</primary></indexterm>
 
     <para>In FreeBSD, a lot of everyday work is done in a command line
       interface called a shell.  A shell's main job is to take commands
       from the input channel and execute them.  A lot of shells also have
       built in functions to help everyday tasks such as file management,
       file globbing, command line editing, command macros, and environment
       variables.  FreeBSD comes with a set of shells, such as 
       <command>sh</command>, the Bourne Shell, and <command>tcsh</command>, 
       the improved C-shell.  Many other shells are available
       from the FreeBSD Ports Collection, such as
       <command>zsh</command> and <command>bash</command>.</para>
 
     <para>Which shell do you use?  It is really a matter of taste.  If you
       are a C programmer you might feel more comfortable with a C-like shell
       such as <command>tcsh</command>.  If you have come from Linux or are new 
       to a Unix command line interface you might try <command>bash</command>.  
       The point is that each
       shell has unique properties that may or may not work with your
       preferred working environment, and that you have a choice of what
       shell to use.</para>
 
     <para>One common feature in a shell is filename completion.  Given
       the typing of the first few letters of a command or filename, you
       can usually have the shell automatically complete the rest of the
       command or filename by hitting the <keycap>Tab</keycap> key on the keyboard.  Here is
       an example.  Suppose you have two files called
       <filename>foobar</filename> and <filename>foo.bar</filename>.  You
       want to delete <filename>foo.bar</filename>.  So what you would type
       on the keyboard is: <command>rm fo[<keycap>Tab</keycap>].[<keycap>Tab</keycap>]</command>.</para>
 
     <para>The shell would print out <command>rm
       foo[BEEP].bar</command>.</para>
 
     <para>The [BEEP] is the console bell, which is the shell telling me it
       was unable to totally complete the filename because there is more
       than one match.  Both <filename>foobar</filename> and
       <filename>foo.bar</filename> start with <literal>fo</literal>, but
       it was able to complete to <literal>foo</literal>.  If you type in
       <literal>.</literal>, then hit <keycap>Tab</keycap> again, the shell would be able to
       fill in the rest of the filename for you.</para>
     <indexterm><primary>environment variables</primary></indexterm>
 
     <para>Another feature of the shell is the use of environment variables.
       Environment variables are a variable key pair stored in the shell's
       environment space.  This space can be read by any program invoked by
       the shell, and thus contains a lot of program configuration.  Here
       is a list of common environment variables and what they mean:</para>
     <indexterm><primary>environment variables</primary></indexterm>
 
     <informaltable frame="none">
       <tgroup cols="2">
 	<thead>
 	  <row>
 	    <entry>Variable</entry>
 	    <entry>Description</entry>
 	  </row>
 	</thead>
 
 	<tbody>
 	  <row>
 	    <entry><envar>USER</envar></entry>
 	    <entry>Current logged in user's name.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>PATH</envar></entry>
 	    <entry>Colon separated list of directories to search for
 	      binaries.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>DISPLAY</envar></entry>
 	    <entry>Network name of the X11 display to connect to, if
 	      available.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>SHELL</envar></entry>
 	    <entry>The current shell.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>TERM</envar></entry>
 	    <entry>The name of the user's terminal.  Used to determine the
 	      capabilities of the terminal.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>TERMCAP</envar></entry>
 	    <entry>Database entry of the terminal escape codes to perform
 	      various terminal functions.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>OSTYPE</envar></entry>
 	    <entry>Type of operating system.  e.g., FreeBSD.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>MACHTYPE</envar></entry>
 	    <entry>The CPU architecture that the system is running
 	      on.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>EDITOR</envar></entry>
 	    <entry>The user's preferred text editor.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>PAGER</envar></entry>
 	    <entry>The user's preferred text pager.</entry>
 	  </row>
 
 	  <row>
 	    <entry><envar>MANPATH</envar></entry>
 	    <entry>Colon separated list of directories to search for
 	      manual pages.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
 
     <indexterm><primary>Bourne shells</primary></indexterm>
     <para>To set an environment variable differs somewhat from
       shell to shell.  For example, in the C-Style shells such as
       <command>tcsh</command> and <command>csh</command>, you would use
       <command>setenv</command> to set environment variables.
       Under Bourne shells such as <command>sh</command> and
       <command>bash</command>, you would use
       <command>export</command> to set your current environment
       variables.  For example, to set or modify the
       <envar>EDITOR</envar> environment variable, under <command>csh</command> or 
       <command>tcsh</command> a
       command like this would set <envar>EDITOR</envar> to
       <filename>/usr/local/bin/emacs</filename>:</para>
 
     <screen>&prompt.user; <userinput>setenv EDITOR /usr/local/bin/emacs</userinput></screen>
 
     <para>Under Bourne shells:</para>
 
     <screen>&prompt.user; <userinput>export EDITOR="/usr/local/bin/emacs"</userinput></screen>
 
     <para>You can also make most shells expand the environment variable by
       placing a <literal>$</literal> character in front of it on the
       command line.  For example, <command>echo $TERM</command> would
       print out whatever <envar>$TERM</envar> is set to, because the shell
       expands <envar>$TERM</envar> and passes it on to <command>echo</command>.</para>
 
     <para>Shells treat a lot of special characters, called meta-characters
       as special representations of data.  The most common one is the
       <literal>*</literal> character, which represents any number of
       characters in a filename.  These special meta-characters can be used
       to do filename globbing.  For example, typing in
       <command>echo *</command> is almost the same as typing in
       <command>ls</command> because the shell takes all the files that
       match <literal>*</literal> and puts them on the command line for
       <command>echo</command> to see.</para>
 
     <para>To prevent the shell from interpreting these special characters,
       they can be escaped from the shell by putting a backslash
       (<literal>\</literal>) character in front of them.  <command>echo
       $TERM</command> prints whatever your terminal is set to.
       <command>echo \$TERM</command> prints <envar>$TERM</envar> as
       is.</para>
 
     <sect2 id="changing-shells">
       <title>Changing Your Shell</title>
 
       <para>The easiest way to change your shell is to use the
 	<command>chsh</command> command.  Running <command>chsh</command> will
 	place you into the editor that is in your <envar>EDITOR</envar>
 	environment variable; if it is not set, you will be placed in
 	<command>vi</command>.  Change the <quote>Shell:</quote> line
 	accordingly.</para>
 
       <para>You can also give <command>chsh</command> the
 	<option>-s</option> option; this will set your shell for you,
 	without requiring you to enter an editor.  
 	For example, if you wanted to
 	change your shell to <command>bash</command>, the following should do the
 	trick:</para>
 	
       <screen>&prompt.user; <userinput>chsh -s /usr/local/bin/bash</userinput></screen>
 
       <para>Running <command>chsh</command> with no parameters and editing
 	the shell from there would work also.</para>
 
       <note>
 	<para>The shell that you wish to use <emphasis>must</emphasis> be
 	  present in the <filename>/etc/shells</filename> file.  If you
 	  have installed a shell from the <link linkend="ports">ports
 	  collection</link>, then this should have been done for you
 	  already.  If you installed the shell by hand, you must do
 	  this.</para>
      
       <para>For example, if you installed <command>bash</command> by hand
 	and placed it into <filename>/usr/local/bin</filename>, you would
 	want to:</para>
 
       <screen>&prompt.root; <userinput>echo &quot;/usr/local/bin/bash&quot; &gt;&gt; /etc/shells</userinput></screen>
 
        <para>Then rerun <command>chsh</command>.</para>
      </note>
    </sect2>
   </sect1>
 
   <sect1 id="editors">
     <title>Text Editors</title>
     <indexterm><primary>text editors</primary></indexterm>
     <indexterm><primary>editors</primary></indexterm>
 
     <para>A lot of configuration in FreeBSD is done by editing text files.
       Because of this, it would be a good idea to become familiar
       with a text editor.  FreeBSD comes with a few as part of the base
       system, and many more are available in the ports collection.</para>
 
     <indexterm>
       <primary><command>ee</command></primary>
     </indexterm>
     <para>The easiest and simplest editor to learn is an editor called
       <application>ee</application>, which stands for easy editor.  To
       start <application>ee</application>, one would type at the command
       line <command>ee filename</command> where
       <literal>filename</literal> is the name of the file to be edited.
       For example, to edit <filename>/etc/rc.conf</filename>, type in
       <command>ee /etc/rc.conf</command>.  Once inside of 
       <command>ee</command>, all of the
       commands for manipulating the editor's functions are listed at the
       top of the display. The caret <literal>^</literal> character means
       the <keycap>Ctrl</keycap> key on the keyboard, so <literal>^e</literal> expands to the key combination
       <keycombo action="simul"><keycap>Ctrl</keycap><keycap>e</keycap></keycombo>.  To leave
       <application>ee</application>, hit the <keycap>Esc</keycap> key, then choose leave
       editor.  The editor will prompt you to save any changes if the file
       has been modified.</para>
 
     <indexterm>
       <primary><command>vi</command></primary>
     </indexterm>
     <indexterm>
       <primary>editors</primary>
       <secondary><command>vi</command></secondary>
     </indexterm>
     <indexterm>
       <primary><command>emacs</command></primary>
     </indexterm>
     <indexterm>
       <primary>editors</primary>
       <secondary><command>emacs</command></secondary>
     </indexterm>
     <para>FreeBSD also comes with more powerful text editors such as
       <command>vi</command> as part of the base system, while other editors, like
       <command>emacs</command> and <command>vim</command>,
       are part of the FreeBSD Ports Collection.  These editors offer much
       more functionality and power at the expense of being a little more
       complicated to learn.  However if you plan on doing a lot of text
       editing, learning a more powerful editor such as
       <command>vim</command> or <command>emacs</command>
       will save you much more time in the long run.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="basics-devices">
     <title>Devices and Device Nodes</title>
 
     <para>A device is a term used mostly for hardware-related
       activities in a system, including disks, printers, graphics
       cards, and keyboards.  When FreeBSD boots, the majority
       of what FreeBSD displays are devices being detected.
       You can look through the boot messages again by viewing
       <filename>/var/run/dmesg.boot</filename>.</para>
 
     <para>For example, <devicename>acd0</devicename> is the
       first IDE CDROM drive, while <devicename>kbd0</devicename>
       represents the keyboard.</para>
 
     <para>Most of these devices in a Unix operating system must be
       accessed through special files called device nodes, which are
       located in the <filename>/dev</filename> directory.</para>
 
     <sect2>
       <title>Creating Device Nodes</title>
       <para>When adding a new device to your system, or compiling
 	in support for additional devices, you may need to create one or
 	more device nodes for the new devices.</para>
 
       <sect3>
 	<title>MAKEDEV Script</title>
 	<para>On systems without <literal>DEVFS</literal> (this concerns all FreeBSD versions before 5.0), device nodes are created
 	  using the &man.MAKEDEV.8; script as shown below:</para>
 
 	<screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV ad1</userinput>
 	</screen>
 
 	<para>This example would make the proper device nodes
 	  for the second IDE drive when installed.</para>
       </sect3>
 
       <sect3>
 	<title><literal>DEVFS</literal> (DEVice File System)</title>
 
 	<para> The device file system, or <literal>DEVFS</literal>, provides access to
 	  kernel's device namespace in the global file system namespace.
 	  Instead of having to create and modify device nodes,
 	  <literal>DEVFS</literal> maintains this particular file system for you.</para>
 
 	<para>See the &man.devfs.5; manual page for more
 	  information.</para>
 
 	<para><literal>DEVFS</literal> is used by default in FreeBSD&nbsp;5.0.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="consoles">
     <title>Virtual consoles &amp; terminals</title>
     <indexterm><primary>virtual consoles</primary></indexterm>
     <indexterm><primary>terminal</primary></indexterm>
 
     <para>FreeBSD can be used in various ways.  One of them is typing commands
       to a text terminal.  A lot of the flexibility and power of a &unix;
       operating system is readily available at your hands when using FreeBSD
       this way.  This section describes what <quote>terminals</quote> and
       <quote>consoles</quote> are, and how you can use them in FreeBSD.</para>
 
     <sect2 id="consoles-intro">
       <title>The console</title>
       <indexterm><primary>console</primary></indexterm>
 
       <para>If you have not configured FreeBSD to automatically start a
 	graphical environment during startup, the system will present you with
 	a login prompt after it boots, right after the startup scripts finish
 	running.  You will see something similar to:</para>
 
       <screen>Additional ABI support:.
 Local package initialization:.
 Additional TCP options:.
 
 Fri Sep 20 13:01:06 EEST 2002
 
 FreeBSD/i386 (pc3.example.org) (ttyv0)
 
 login:</screen>
 
       <para>The messages might be a bit different on your system, but you will
 	see something similar.  The last two lines are what we are interested
 	in right now.  The second last line reads:</para>
 
       <programlisting>FreeBSD/i386 (pc3.example.org) (ttyv0)</programlisting>
 
       <para>This line contains some bits of information about the system you
         have just booted.  You are looking at a <quote>FreeBSD</quote>
 	console, running on an Intel or compatible processor of the x86
 	architecture<footnote>
 	  <para>This is what <literal>i386</literal> means.  Note that even if
 	    you are not running FreeBSD on an Intel 386 CPU, this is going to
 	    be <literal>i386</literal>.  It is not the type of your processor,
 	    but the processor <quote>architecture</quote> that is shown
 	    here.</para>
 	</footnote>.  The name of this machine (every &unix; machine has a
 	name) is <hostid>pc3.example.org</hostid>, and you are now looking
 	at its system console&mdash;the <devicename>ttyv0</devicename>
 	terminal.</para>
 
       <para>Finally, the last line is always:</para>
 
       <programlisting>login:</programlisting>
 
       <para>This is the part where you are supposed to type in your
 	<quote>username</quote> to log into FreeBSD.  The next section
 	describes how you can do this.</para>
     </sect2>
 
     <sect2 id="consoles-login">
       <title>Logging into FreeBSD</title>
 
       <para>FreeBSD is a multiuser, multiprocessing system.  This is
 	the formal description that is usually given to a system that can be
 	used by many different people, who simultaneously run a lot of
 	programs on a single machine.</para>
 
       <para>Every multiuser system needs some way to distinguish one
 	<quote>user</quote> from the rest.  In FreeBSD (and all the
 	&unix;-like operating systems), this is accomplished by requiring that
 	every user must <quote>log into</quote> the system before being able
 	to run programs.  Every user has a unique name (the
 	<quote>username</quote>) and a personal, secret key (the
 	<quote>password</quote>).  FreeBSD will ask for these two before
 	allowing a user to run any programs.</para>
 
       <indexterm><primary>startup scripts</primary></indexterm>
       <para>Right after FreeBSD boots and finishes running its startup
 	scripts<footnote>
 	  <para>Startup scripts are programs that are run automatically by
 	    FreeBSD when booting.  Their main function is to set things up for
 	    everything else to run, and start any services that you have
 	    configured to run in the background doing useful things.</para>
 	</footnote>, it will present you with a prompt and ask for a valid
 	username:</para>
 
       <screen>login:</screen>
 
       <para>For the sake of this example, let us assume that your username is
 	<username>john</username>.  Type <literal>john</literal> at this prompt and press
 	<keycap>Enter</keycap>.  You should then be presented with a prompt to
 	enter a <quote>password</quote>:</para>
 
       <screen>login: <userinput>john</userinput>
 Password:</screen>
 
       <para>Type in <username>john</username>'s password now, and press
 	<keycap>Enter</keycap>.  The password is <emphasis>not
 	echoed!</emphasis>  You need not worry about this right now.  Suffice
 	it to say that it is done for security reasons.</para>
 
       <para>If you have typed your password correctly, you should by now be
 	logged into FreeBSD and ready to try out all the available
 	commands.</para>
     </sect2>
 
     <sect2 id="consoles-virtual">
       <title>Multiple consoles</title>
 
       <para>Running &unix; commands in one console is fine, but FreeBSD can
 	run many programs at once.  Having one console where commands can be
 	typed would be a bit of a waste when an operating system like FreeBSD
 	can run dozens of programs at the same time.  This is where
 	<quote>virtual consoles</quote> can be very helpful.</para>
 
       <para>FreeBSD can be configured to present you with many different
 	virtual consoles.  You can switch from one of them to any other
 	virtual console by pressing a couple of keys on your keyboard.  Each
 	console has its own different output channel, and FreeBSD takes care
 	of properly redirecting keyboard input and monitor output as you
 	switch from one virtual console to the next.</para>
 
       <para>Special key combinations have been reserved by FreeBSD for
 	switching consoles<footnote>
 	  <para>A fairly technical and accurate description of all the details
 	    of the FreeBSD console and keyboard drivers can be found in the
 	    manual pages of &man.syscons.4;, &man.atkbd.4;, &man.vidcontrol.1;
 	    and &man.kbdcontrol.1;.  We will not expand on the details here,
 	    but the interested reader can always consult the manual pages for
 	    a more detailed and thorough explanation of how things
 	    work.</para>
 	</footnote>.  You can use
 	<keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo>,
 	<keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo>, through
 	<keycombo><keycap>Alt</keycap><keycap>F8</keycap></keycombo> to switch
 	to a different virtual console in FreeBSD.</para>
 
       <para>As you are switching from one console to the next, FreeBSD takes
 	care of saving and restoring the screen output.  The result is an
 	<quote>illusion</quote> of having multiple <quote>virtual</quote>
 	screens and keyboards that you can use to type commands for
 	FreeBSD to run.  The programs that you launch on one virtual console
 	do not stop running when that console is not visible.  They continue
 	running when you have switched to a different virtual console.</para>
     </sect2>
 
     <sect2 id="consoles-ttys">
       <title>The <filename>/etc/ttys</filename> file</title>
 
       <para>The default configuration of FreeBSD will start up with 8
         virtual consoles.  This is not a hardwired setting though, and
         you can easily customize your installation to boot with more
         or fewer virtual consoles.  The number and settings of the
         virtual consoles are configured in the
         <filename>/etc/ttys</filename> file.</para>
 
       <para>You can use the <filename>/etc/ttys</filename> file to configure
 	the virtual consoles of FreeBSD.  Each uncommented line in this file
 	(lines that do not start with a <literal>#</literal> character) contains
 	settings for a single terminal or virtual console.  The default
 	version of this file that ships with FreeBSD configures 9 virtual
 	consoles, and enables 8 of them.  They are the lines that start with
 	<literal>ttyv</literal>:</para>
 
       <programlisting># name  getty                           type    status          comments
 #
 ttyv0   "/usr/libexec/getty Pc"         cons25  on  secure
 # Virtual terminals
 ttyv1   "/usr/libexec/getty Pc"         cons25  on  secure
 ttyv2   "/usr/libexec/getty Pc"         cons25  on  secure
 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/X11R6/bin/xdm -nodaemon"  xterm   off secure</programlisting>
 
       <para>For a detailed description of every column in this file and all
 	the options you can use to set things up for the virtual consoles,
 	consult the &man.ttys.5; manual page.</para>
     </sect2>
 
     <sect2 id="consoles-singleuser">
       <title>Single user mode console</title>
 
       <para>A detailed description of what <quote>single user mode</quote> is
 	can be found in <xref linkend="boot-singleuser">.  It is worth noting
 	that there is only one console when you are running FreeBSD in single
 	user mode.  There are no virtual consoles available.  The settings of
 	the single user mode console can also be found in the
 	<filename>/etc/ttys</filename> file.  Look for the line that starts
 	with <literal>console</literal>:</para>
 
       <programlisting># name  getty                           type    status          comments
 #
 # If console is marked "insecure", then init will ask for the root password
 # when going to single-user mode.
 console none                            unknown off secure</programlisting>
 
       <note>
         <para>As the comments above the <literal>console</literal> line
 	  indicate, you can edit this line and change <literal>secure</literal> to
 	  <literal>insecure</literal>.  If you do that, when FreeBSD boots
 	  into single user mode, it will still ask for the
 	  <username>root</username> password.</para>
 
 	<para><emphasis>Be careful when changing this to
 	  <literal>insecure</literal> though.</emphasis>  If you ever forget
 	  the <username>root</username> password, booting into single user
 	  mode is a bit involved.  It is still possible, but it might be a bit
 	  hard for someone who is not very comfortable with the FreeBSD
 	  booting process and the programs involved.</para>
       </note>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="basics-more-information">
     <title>For More Information</title>
 
     <sect2 id="basics-man">
       <title>Manual Pages</title>
       <indexterm><primary>manual pages</primary></indexterm>
 
       <para>The most comprehensive documentation on FreeBSD is in the form
 	of manual pages. Nearly every program on the system comes with a
 	short reference manual explaining the basic operation and various
 	arguments. These manuals can be viewed with the <command>man</command> command.  Use
 	of the <command>man</command> command is simple:</para>
 
       <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
 
       <para><literal>command</literal> is the name of the command you
         wish to learn about.  For example, to learn more about
 	<command>ls</command> command type:</para>
 
       <screen>&prompt.user; <userinput>man ls</userinput></screen>
 
       <para>The online manual is divided up into numbered sections:</para>
 
       <orderedlist>
 	<listitem>
 	  <para>User commands.</para>
 	</listitem>
 
 	<listitem>
 	  <para>System calls and error numbers.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Functions in the C libraries.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Device drivers.</para>
 	</listitem>
 
 	<listitem>
 	  <para>File formats.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Games and other diversions.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Miscellaneous information.</para>
 	</listitem>
 
 	<listitem>
 	  <para>System maintenance and operation commands.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Kernel developers.</para>
 	</listitem>
       </orderedlist>
 
       <para>In some cases, the same topic may appear in more than one
 	section of the online manual.  For example, there is a
 	<command>chmod</command> user command and a
 	<function>chmod()</function> system call.  In this case, you can
 	tell the <command>man</command> command which one you want by specifying the
 	section:</para>
 
       <screen>&prompt.user; <userinput>man 1 chmod</userinput></screen>
 
       <para>This will display the manual page for the user command
         <command>chmod</command>. References to a particular section of
 	the online manual are traditionally placed in parenthesis in
 	written documentation, so &man.chmod.1; refers to the
 	<command>chmod</command> user command and &man.chmod.2; refers to
 	the system call.</para>
 
       <para>This is fine if you know the name of the command and simply
 	wish to know how to use it, but what if you cannot recall the
 	command name?  You can use <command>man</command> to search for keywords in the
 	command descriptions by using the <option>-k</option>
 	switch:</para>
 
       <screen>&prompt.user; <userinput>man -k mail</userinput></screen>
 
       <para>With this command you will be presented with a list of
         commands that have the keyword <quote>mail</quote> in their
 	descriptions.  This is actually functionally equivalent to using
 	the <command>apropos</command> command.</para>
 
       <para>So, you are looking at all those fancy commands in
 	<filename>/usr/bin</filename> but do not have the faintest idea
 	what most of them actually do?  Simply do:</para>
 
 	<screen>&prompt.user; <userinput>cd /usr/bin</userinput>
 &prompt.user; <userinput>man -f *</userinput></screen>
 
 	<para>or</para>
 
 	<screen>&prompt.user; <userinput>cd /usr/bin</userinput>
 &prompt.user; <userinput>whatis *</userinput></screen>
 
 	<para>which does the same thing.</para>
     </sect2>
 
     <sect2 id="basics-info">
       <title>GNU Info Files</title>
       <indexterm><primary>Free Software Foundation</primary></indexterm>
 
       <para>FreeBSD includes many applications and utilities produced by
 	the Free Software Foundation (FSF).  In addition to manual pages,
 	these programs come with more extensive hypertext documents called
 	<literal>info</literal> files which can be viewed with the
 	<command>info</command> command or, if you installed
 	<application>emacs</application>, the info mode of
 	<application>emacs</application>.</para>
 
       <para>To use the &man.info.1; command, simply type:</para>
 
       <screen>&prompt.user; <userinput>info</userinput></screen>
 
       <para>For a brief introduction, type <literal>h</literal>.  For a
 	quick command reference, type <literal>?</literal>.</para>
     </sect2>
   </sect1>
 </chapter>
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml
index dfd004be84..04ab4ebcd4 100644
--- a/en_US.ISO8859-1/books/handbook/book.sgml
+++ b/en_US.ISO8859-1/books/handbook/book.sgml
@@ -1,210 +1,210 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <!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 % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
 %freebsd;
 
 <!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
 <!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//EN">
 %teams;
 <!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"> %mailing-lists;
 <!ENTITY % newsgroups PUBLIC "-//FreeBSD//ENTITIES DocBook Newsgroup Entities//EN"> %newsgroups;
 <!ENTITY % txtfiles SYSTEM "txtfiles.ent"> %txtfiles;
 
 <!ENTITY % not.published "INCLUDE">
 
 <!ENTITY % chap.introduction "IGNORE">
 <!ENTITY % chap.install "IGNORE">
 <!ENTITY % chap.basics "IGNORE">
 <!ENTITY % chap.ports "IGNORE">
 <!ENTITY % chap.config "IGNORE">
 <!ENTITY % chap.boot "IGNORE">
 <!ENTITY % chap.users "IGNORE">
 <!ENTITY % chap.kernelconfig "IGNORE">
 <!ENTITY % chap.security "IGNORE">
 <!ENTITY % chap.printing "IGNORE">
 <!ENTITY % chap.disks "IGNORE">
 <!ENTITY % chap.vinum "IGNORE">
 <!ENTITY % chap.x11 "IGNORE">
 <!ENTITY % chap.l10n "IGNORE">
 <!ENTITY % chap.multimedia "IGNORE">
 <!ENTITY % chap.desktop "IGNORE">
 <!ENTITY % chap.serialcomms "IGNORE">
 <!ENTITY % chap.ppp-and-slip "IGNORE">
 <!ENTITY % chap.advanced-networking "IGNORE">
 <!ENTITY % chap.mail "IGNORE">
 <!ENTITY % chap.cutting-edge "IGNORE">
 <!ENTITY % chap.policies "IGNORE">
 <!ENTITY % chap.kerneldebug "IGNORE">
 <!ENTITY % chap.linuxemu "IGNORE">
 <!ENTITY % chap.mirrors "IGNORE">
 <!ENTITY % chap.bibliography "IGNORE">
 <!ENTITY % chap.eresources "IGNORE">
 <!ENTITY % chap.pgpkeys "IGNORE">
 <!ENTITY % chap.index "IGNORE">
 
 <!ENTITY % pgpkeys SYSTEM "pgpkeys/pgpkeys.ent"> %pgpkeys;
 ]>
 
 <book>
   <bookinfo>
     <title>FreeBSD Handbook</title>
     
     <corpauthor>The FreeBSD Documentation Project</corpauthor>
     
     <pubdate>February 1999</pubdate>
     
     <copyright>
       <year>1995</year>
       <year>1996</year>
       <year>1997</year>
       <year>1998</year>
       <year>1999</year>
       <year>2000</year>
       <year>2001</year>
       <year>2002</year>
       <year>2003</year>
       <holder>The FreeBSD Documentation Project</holder>
     </copyright>
 
     &bookinfo.legalnotice;
     
     <abstract>
       <para>Welcome to FreeBSD! This handbook covers the installation and day
 	to day use of <emphasis>FreeBSD &rel.current;-RELEASE</emphasis>.
 	This manual is a <emphasis>work in progress</emphasis> and is the work
 	of many individuals.  Many sections do not yet exist and some of those
 	that do exist need to be updated.  If you are interested in helping
 	with this project, send email to the &a.doc;.  The latest version of
 	this document is always available from the <ulink
 	  url="../../../../index.html">FreeBSD web site</ulink>.
 	It may also be downloaded in a variety of formats and compression
 	options from the <ulink 
           url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP 
           server</ulink> or one of the numerous <link
 	  linkend="mirrors-ftp">mirror sites</link>.  If you would prefer
 	  to have a hard copy of the handbook, you can purchase one at the
 	  <ulink
 	  url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>.  You
 	  may also want to <ulink
 	  url="../../../../search/index.html">search the
 	  handbook</ulink>.</para>
     </abstract>
   </bookinfo>
 
   &chap.preface;
 
-  <part>
+  <part id="getting-started">
     <title>Getting Started</title>
     
     <partintro>
       <para>This part of the FreeBSD Handbook is for users and
 	administrators who are new to FreeBSD.  These chapters:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Introduce you to FreeBSD.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Guide you through the installation process.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Teach you some Unix basics.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Show you how to install the wealth of third party
 	    applications available for FreeBSD.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Introduce you to X, the Unix windowing system, and
 	    detail how to configure a desktop environment that makes you
 	    more productive.</para>
 	</listitem>
       </itemizedlist>
 
       <para>We have tried to keep the number of forward references in
 	the text to a minimum so that you can read this section of the
 	Handbook from front to back with the minimum of page flipping
 	required.</para>
     </partintro>
 
     <![ %chap.introduction;             [ &chap.introduction;         ]]>
     <![ %chap.install;                  [ &chap.install;              ]]>
     <![ %chap.basics;                   [ &chap.basics;               ]]>
     <![ %chap.ports;                    [ &chap.ports;                ]]>
     <![ %chap.x11;                      [ &chap.x11;                  ]]>
   </part>
   
-  <part>
+  <part id="system-administration">
     <title>System Administration</title>
 
     <partintro>
       <para>The remaining chapters of the FreeBSD Handbook cover all
 	aspects of FreeBSD system administration.  Each chapter
 	starts by describing what you will learn as a result of reading
 	the chapter, and also details what you are expected to know
 	before tackling the material.</para>
 
       <para>These chapters are designed to be read when
 	you need the information.  You do not have to read them in any
 	particular order, nor do you need to read all of them before you
 	can begin using FreeBSD.</para>
     </partintro>
 
     <![ %chap.config;                   [ &chap.config;               ]]>
     <![ %chap.boot;                     [ &chap.boot;                 ]]>
     <![ %chap.users;                    [ &chap.users;                ]]>
     <![ %chap.kernelconfig;             [ &chap.kernelconfig;         ]]>
     <![ %chap.security;                 [ &chap.security;             ]]>
     <![ %chap.printing;                 [ &chap.printing;             ]]>
     <![ %chap.disks;                    [ &chap.disks;                ]]>
     <![ %chap.vinum;                    [ &chap.vinum;                ]]>
     <![ %chap.l10n;                     [ &chap.l10n;                 ]]>
     <![ %chap.desktop;                  [ &chap.desktop;              ]]>
     <![ %chap.multimedia;               [ &chap.multimedia;           ]]>
     <![ %chap.serialcomms;              [ &chap.serialcomms;          ]]>
     <![ %chap.ppp-and-slip;             [ &chap.ppp-and-slip;         ]]>
     <![ %chap.advanced-networking;      [ &chap.advanced-networking;  ]]>
     <![ %chap.mail;                     [ &chap.mail;                 ]]>
     <![ %chap.cutting-edge;             [ &chap.cutting-edge;         ]]>
     <![ %chap.policies;                 [ &chap.policies;             ]]>
     <![ %chap.kerneldebug;              [ &chap.kerneldebug;          ]]>
     <![ %chap.linuxemu;                 [ &chap.linuxemu;             ]]>
   </part>
   
-  <part>
+  <part id="appendicies">
     <title>Appendices</title>
     
     <![ %chap.mirrors;                  [ &chap.mirrors;              ]]>
     <![ %chap.bibliography;             [ &chap.bibliography;         ]]>
     <![ %chap.eresources;               [ &chap.eresources;           ]]>
     <![ %chap.pgpkeys;                  [ &chap.pgpkeys;              ]]>
     <![ %chap.index;                    [ &chap.index;                ]]>
   </part>
   &chap.colophon;
 </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/handbook/colophon.sgml b/en_US.ISO8859-1/books/handbook/colophon.sgml
index 49d25b3442..a85e4bfe36 100644
--- a/en_US.ISO8859-1/books/handbook/colophon.sgml
+++ b/en_US.ISO8859-1/books/handbook/colophon.sgml
@@ -1,30 +1,30 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
-<colophon>
+<colophon id='colophon'>
   <para>This book is the combined work of hundreds of contributors to
     <quote>The FreeBSD Documentation Project</quote>.  The text is authored in SGML
     according to the DocBook DTD and is formatted from SGML into many
     different presentation formats using <application>Jade</application>, an open source DSSSL
     engine.  Norm Walsh's DSSSL stylesheets were used with an
     additional customization layer to provide the presentation
     instructions for <application>Jade</application>.  The printed
     version of this document would not be possible without Donald
     Knuth's <application>TeX</application> typesetting language,
     Leslie Lamport's <application>LaTeX</application>, or Sebastian
     Rahtz's <application>JadeTeX</application> macro package.</para>
 </colophon>
 
 <!-- 
      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/config/chapter.sgml b/en_US.ISO8859-1/books/handbook/config/chapter.sgml
index a7ee5bce71..85a9d5bcea 100644
--- a/en_US.ISO8859-1/books/handbook/config/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/config/chapter.sgml
@@ -1,1766 +1,1766 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="config-tuning">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Chern</firstname>
 	<surname>Lee</surname>
 	<contrib>Written by </contrib>
       </author>
     </authorgroup>
     <authorgroup>
       <author>
         <firstname>Mike</firstname>
 	<surname>Smith</surname>
 	<contrib>Based on a tutorial written by </contrib>
       </author>
     </authorgroup>
     <authorgroup>
       <author>
         <firstname>Matt</firstname>
 	<surname>Dillon</surname>
 	<contrib>Also based on tuning(7) written by </contrib>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Configuration and Tuning</title>
 
-  <sect1>
+  <sect1 id="config-synopsis">
     <title>Synopsis</title>
 
     <indexterm><primary>system configuration/optimization</primary></indexterm>
 
     <para>One of the important aspects of FreeBSD is system configuration.
       Correct system configuration will help prevent headaches during future upgrades.
       This chapter will explain much of the FreeBSD configuration process,
       including some of the parameters which
       can be set to tune a FreeBSD system.
       </para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How to efficiently work with
 	  file systems and swap partitions.</para>
       </listitem>
       <listitem>
 	<para>The basics of <filename>rc.conf</filename> configuration and
 	  <filename>/usr/local/etc/rc.d</filename> startup systems.</para>
       </listitem>
       <listitem>
 	<para>How to configure virtual hosts on your network devices.</para>
       </listitem>
       <listitem>
 	<para>How to use the various configuration files in
 	  <filename>/etc</filename>.</para>
       </listitem>
       <listitem>
         <para>How to tune FreeBSD using <command>sysctl</command>
           variables.</para>
       </listitem>
       <listitem>
 	<para>How to tune disk performance and modify kernel
 	  limitations.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Understand Unix and FreeBSD basics (<xref
 	    linkend="basics">).</para>
       </listitem>
       <listitem>
 	<para>Be familiar with keeping FreeBSD sources up to date
 	  (<xref linkend="cutting-edge">), and
 	  the basics of kernel configuration/compilation
 	  (<xref linkend="kernelconfig">).</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="configtuning-initial">
     <title>Initial Configuration</title>
 
     <sect2>
       <title>Partition Layout</title>
 
       <indexterm><primary>Partition layout</primary></indexterm>
       <indexterm>
         <primary><filename>/etc</filename></primary>
       </indexterm>
       <indexterm>
         <primary><filename>/var</filename></primary>
       </indexterm>
       <indexterm>
         <primary><filename>/usr</filename></primary>
       </indexterm>
 
       <sect3>
 	<title>Base Partitions</title>
 
 	<para>When laying out file systems with &man.disklabel.8;
 	  or &man.sysinstall.8;, remember that hard
 	  drives transfer data faster from the outer
 	  tracks to the inner.
 	  Thus smaller and heavier-accessed file systems
 	  should be closer to the outside of the drive  While
 	  larger partitions like <filename>/usr</filename> should be placed
 	  toward the inner.  It is a good idea to create
 	  partitions in a similar order to: root, swap,
 	  <filename>/var</filename>, <filename>/usr</filename>.</para>
 
 	<para>The size of <filename>/var</filename>
 	  reflects the intended machine usage.
 	  <filename>/var</filename> is used to hold
 	  mailboxes, log files, and printer spools.  Mailboxes and log
 	  files can grow to unexpected sizes depending
 	  on how many users exist and how long log
 	  files are kept.  Most users would never require a gigabyte,
 	  but remember that <filename>/var/tmp</filename>
 	  must be large enough to contain packages.
 	  </para>
 
 	<para>The <filename>/usr</filename> partition holds much
 	  of the files required to support the system, the &man.ports.7;
 	  collection (recommended) and the source code (optional).  Both
 	  of which are optional at install time.
 	  At least 2 gigabytes would be recommended for this partition.
 
 	<para>When selecting partition sizes, keep the space
 	  requirements in mind.  Running out of space in
 	  one partition while barely using another can be a
 	  hassle.</para>
 
 	<note><para>Some users have found that &man.sysinstall.8;'s
 	    <literal>Auto-defaults</literal> partition sizer will
 	    sometimes select smaller than adequate <filename>/var</filename>
 	    and <filename>/</filename> partitions.  Partition wisely and
 	    generously.</para></note>
 
       </sect3>
 
       <sect3 id="swap-design">
 	<title>Swap Partition</title> 
 
 	<indexterm><primary>swap sizing</primary></indexterm>
 	<indexterm><primary>swap partition</primary></indexterm>
 
 	<para>As a rule of thumb, the swap partition should be
 	  about double the size of system memory (RAM).  For example,
 	  if the machine has 128&nbsp;megabytes of memory,
 	  the swap file should be 256&nbsp;megabytes.  Systems with
 	  less memory may perform better with more swap.
 	  Less than 256&nbsp;megabytes of swap is not recommended and
 	  memory expansion should be considered.
 	  The kernel's VM paging algorithms are tuned to
 	  perform best when the swap partition is at least two times the
 	  size of main memory.  Configuring too little swap can lead to
 	  inefficiencies in the VM page scanning code and might create
 	  issues later if more memory is added.</para>
 
 	<para>On larger systems with multiple SCSI disks (or
 	  multiple IDE disks operating on different controllers), it is
 	  recommend that a swap is configured on each drive (up
 	  to four drives).  The swap partitions should be
 	  approximately the same size.  The kernel can handle arbitrary
 	  sizes but internal data structures scale to 4 times the
 	  largest swap partition.  Keeping the swap partitions near the
 	  same size will allow the kernel to optimally stripe swap space
 	  across disks.
 	  Large swap sizes are fine, regardless if it's not
 	  used much.  It might be easier to recover
 	  from a runaway program before being forced to reboot.</para>
       </sect3>
 
       <sect3>
 	<title>Why Partition?</title>
 
 	<para>Several users think a single large partition will be fine,
 	  but there are several reasons why this is a bad idea.
 	  First, each partition has different operational
 	  characteristics and separating them allows the file system to
 	  tune accordingly.  For example, the root
 	  and <filename>/usr</filename> partitions are read-mostly, without
 	  much writing.  While a lot of reading and writing could
 	  occur in <filename>/var</filename> and
 	  <filename>/var/tmp</filename>.</para>
 
 	<para>By properly partitioning a system, fragmentation
 	  introduced in the smaller write heavy partitions
 	  will not bleed over into the mostly-read partitions.
 	  Keeping the write-loaded partitions closer to
 	  the disk's edge,
 	  will
 	  increase I/O performance in the partitions where it occurs
 	  the most.  Now while I/O
 	  performance in the larger partitions may be needed,
 	  shifting them more toward the edge of the disk will not
 	  lead to a significant performance improvement over moving
 	  <filename>/var</filename> to the edge.
 	  Finally, there are safety concerns.  A smaller, neater root
 	  partition which is mostly read-only has a greater
 	  chance of surviving a bad crash.</para>
       </sect3>
     </sect2>
 
   </sect1>
 
   <sect1 id="configtuning-core-configuration">
     <title>Core Configuration</title>
 
     <indexterm>
       <primary>rc files</primary>
       <secondary><filename>rc.conf</filename></secondary>
     </indexterm>
 
     <para>The principal location for system configuration information
       is within <filename>/etc/rc.conf</filename>.  This file
       contains a wide range of configuration information, principally
       used at system startup to configure the system.  Its name
       directly implies this; it is configuration information for the
       <filename>rc*</filename> files.</para>
 
     <para>An administrator should make entries in the 
       <filename>rc.conf</filename> file to
       override the default settings from
       <filename>/etc/defaults/rc.conf</filename>.  The defaults file
       should not be copied verbatim to <filename>/etc</filename> - it
       contains default values, not examples.  All system-specific
       changes should be made in the <filename>rc.conf</filename>
       file itself.</para>
 
     <para>A number of strategies may be applied in clustered
       applications to separate site-wide configuration from
       system-specific configuration in order to keep administration
       overhead down.  The recommended approach is to place site-wide
       configuration into another file,
       such as <filename>/etc/rc.conf.site</filename>, and then include
       this file into <filename>/etc/rc.conf</filename>, which will
       contain only system-specific information.</para>
 
     <para>As <filename>rc.conf</filename> is read by &man.sh.1; it is
       trivial to achieve this.  For example:</para>
 
     <itemizedlist>
       <listitem><para>rc.conf:</para>
 <programlisting>	. rc.conf.site
 	hostname="node15.example.com"
 	network_interfaces="fxp0 lo0"
 	ifconfig_fxp0="inet 10.1.1.1"</programlisting></listitem>
       <listitem><para>rc.conf.site:</para>
 <programlisting>	defaultrouter="10.1.1.254"
 	saver="daemon"
 	blanktime="100"</programlisting></listitem>
     </itemizedlist>
 
     <para>The <filename>rc.conf.site</filename> file can then be
       distributed to every system using <command>rsync</command> or a
       similar program, while the <filename>rc.conf</filename> file
       remains unique.</para>
 
     <para>Upgrading the system using &man.sysinstall.8;
       or <command>make world</command> will not overwrite the 
       <filename>rc.conf</filename>
       file, so system configuration information will not be lost.</para>
 
   </sect1>
 
   <sect1 id="configtuning-appconfig">
     <title>Application Configuration</title>
 
     <para>Typically, installed applications have their own
       configuration files, with their own syntax, etc.  It is
       important that these files be kept separate from the base
       system, so that they may be easily located and managed by the
       package management tools.</para>
 
     <indexterm><primary>/usr/local/etc</primary></indexterm>
 
     <para>Typically, these files are installed in
       <filename>/usr/local/etc</filename>.  In the case where an
       application has a large number of configuration files, a
       subdirectory will be created to hold them.</para>
 
     <para>Normally, when a port or package is installed, sample
       configuration files are also installed.  These are usually
       identified with a <filename>.default</filename> suffix.  If there 
       are no existing
       configuration files for the application, they will be created by
       copying the <filename>.default</filename> files.</para>
 
     <para>For example, consider the contents of the directory 
     <filename>/usr/local/etc/apache</filename>:</para>
 
 <literallayout class="monospaced">-rw-r--r--  1 root  wheel   2184 May 20  1998 access.conf
 -rw-r--r--  1 root  wheel   2184 May 20  1998 access.conf.default
 -rw-r--r--  1 root  wheel   9555 May 20  1998 httpd.conf
 -rw-r--r--  1 root  wheel   9555 May 20  1998 httpd.conf.default
 -rw-r--r--  1 root  wheel  12205 May 20  1998 magic
 -rw-r--r--  1 root  wheel  12205 May 20  1998 magic.default
 -rw-r--r--  1 root  wheel   2700 May 20  1998 mime.types
 -rw-r--r--  1 root  wheel   2700 May 20  1998 mime.types.default
 -rw-r--r--  1 root  wheel   7980 May 20  1998 srm.conf
 -rw-r--r--  1 root  wheel   7933 May 20  1998 srm.conf.default</literallayout>
 
     <para>The filesize difference shows that only the <filename>srm.conf</filename>
       file has been changed.  A later update of the <application>Apache</application> port would not
       overwrite this changed file.</para>
 
   </sect1>
 
   <sect1 id="configtuning-starting-services">
     <title>Starting Services</title>
 
     <indexterm><primary>services</primary></indexterm>
 
     <para>It is common for a system to host a number of services.
       These may be started in several different fashions, each having
       different advantages.</para>
 
     <indexterm><primary>/usr/local/etc/rc.d</primary></indexterm>
 
     <para>Software installed from a port or the packages collection
       will often place a script in
       <filename>/usr/local/etc/rc.d</filename> which is invoked at
       system startup with a <option>start</option> argument, and at
       system shutdown with a <option>stop</option> argument.
       This is the recommended way for
       starting system-wide services that are to be run as
       <username>root</username>, or that
       expect to be started as <username>root</username>.
       These scripts are registered as
       part of the installation of the package, and will be removed
       when the package is removed.</para>
 
     <para>A generic startup script in 
       <filename>/usr/local/etc/rc.d</filename> looks like:</para>
 
     <programlisting>#!/bin/sh
 echo -n ' FooBar'
 
 case "$1" in
 start)
         /usr/local/bin/foobar
         ;;
 stop)
         kill -9 `cat /var/run/foobar.pid`
         ;;
 *)
         echo "Usage: `basename $0` {start|stop}" >&2
         exit 64
         ;;
 esac
 
 exit 0
     </programlisting>
 
     <para>The startup scripts of FreeBSD will look in
       <filename>/usr/local/etc/rc.d</filename> for scripts that have an
       <literal>.sh</literal> extension and are executable by
       <username>root</username>.  Those scripts that are found are called with
       an option <option>start</option> at startup, and <option>stop</option>
       at shutdown to allow them to carry out their purpose.  So if you wanted
       the above sample script to be picked up and run at the proper time during
       system startup, you should save it to a file called
       <filename>FooBar.sh</filename> in
       <filename>/usr/local/etc/rc.d</filename> and make sure it's
       executable.  You can make a shell script executable with &man.chmod.1;
       as shown below:</para>
 
     <screen>&prompt.root; <userinput>chmod 755 <replaceable>FooBar.sh</replaceable></userinput></screen>
 
     <para>Some services expect to be invoked by &man.inetd.8; when a
       connection is received on a suitable port.  This is common for
       mail reader servers (POP and IMAP, etc.).  These services are
       enabled by editing the file <filename>/etc/inetd.conf</filename>.
       See &man.inetd.8; for details on editing this file.</para>
 
     <para>Some additional system services may not be covered by the
       toggles in <filename>/etc/rc.conf</filename>.  These are
       traditionally enabled by placing the command(s) to invoke them
       in <filename>/etc/rc.local</filename>.  As of FreeBSD&nbsp;3.1 there
       is no default <filename>/etc/rc.local</filename>; if it is
       created by the administrator it will however be honored in the
       normal fashion.  Note that <filename>rc.local</filename> is
       generally regarded as the location of last resort; if there is a
       better place to start a service, do it there.</para>
 
     <note><para>Do <emphasis>not</emphasis> place any commands in 
       <filename>/etc/rc.conf</filename>.  To start daemons, or
       run any commands at boot time, place a script in 
       <filename>/usr/local/etc/rc.d</filename> instead.</para>
     </note>
 
     <para>It is also possible to use the &man.cron.8; daemon to start
       system services.  This approach has a number of advantages, not
       least being that because &man.cron.8; runs these processes as the
       owner of the <command>crontab</command>, services may be started
       and maintained by non-<username>root</username> users.</para>
     
     <para>This takes advantage of a feature of &man.cron.8;: the
       time specification may be replaced by <literal>@reboot</literal>,
       which will
       cause the job to be run when &man.cron.8; is started shortly after
       system boot.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="config-network-setup">
     <sect1info>
       <authorgroup>
         <author>
 	 <firstname>Marc</firstname>
 	 <surname>Fonvieille</surname>
 	 <contrib>Contributed by </contrib>
 	 <!-- 6 October 2002 -->
         </author>
       </authorgroup>
     </sect1info>
 
     <title>Setting Up Network Interface Cards</title>
 
     <indexterm><primary>Network card configuration</primary></indexterm>
 
     <para>Nowadays we can not think about a computer without thinking
       about a network connection.  Adding and configuring a network
       card is a common task for any FreeBSD administrator.</para>
 
     <sect2>
       <title>Locating the Correct Driver</title>
 
       <indexterm>
 	<primary>Network card configuration</primary>
 	<secondary>Locating the driver</secondary>
       </indexterm>
 
       <para>Before you begin, you should know the model of the card
 	you have, the chip it uses, and whether it is a PCI or ISA card.
 	FreeBSD supports a wide variety of both PCI and ISA cards.
 	Check the Hardware Compatibility List for your release to see
 	if your card is supported.</para>
 
       <para>Once you are sure your card is supported, you need
 	to determine the proper driver for the card.  The file
 	<filename>/usr/src/sys/i386/conf/LINT</filename> will give you
 	the list of network interfaces drivers with some information
 	about the supported chipsets/cards.  If you have doubts about
 	which driver is the correct one, read the manual page of the
 	driver.  The manual page will give you more information about
 	the supported hardware and even the possible problems that
 	could occur.</para>
 
       <para>If you own a common card, most of the time you will not
 	have to look very hard for a driver.  Drivers for common
 	network cards are present in the <filename>GENERIC</filename>
 	kernel, so your card should show up during boot, like so:</para>
 
 <screen>dc0: &lt;82c169 PNIC 10/100BaseTX&gt; port 0xa000-0xa0ff mem 0xd3800000-0xd38
 000ff irq 15 at device 11.0 on pci0
 dc0: Ethernet address: 00:a0:cc:da:da:da
 miibus0: &lt;MII bus&gt; on dc0
 ukphy0: &lt;Generic IEEE 802.3u media interface&gt; on miibus0
 ukphy0:  10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
 dc1: &lt;82c169 PNIC 10/100BaseTX&gt; port 0x9800-0x98ff mem 0xd3000000-0xd30
 000ff irq 11 at device 12.0 on pci0
 dc1: Ethernet address: 00:a0:cc:da:da:db
 miibus1: &lt;MII bus&gt; on dc1
 ukphy1: &lt;Generic IEEE 802.3u media interface&gt; on miibus1
 ukphy1:  10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto</screen>
 
       <para>In this example, we see that two cards using the &man.dc.4;
 	driver are present on the system.</para>
 
       <para>To use your network card, you will need to load the proper
 	driver.  This may be accomplished in one of two ways.  The
 	easiest way is to simply load a kernel module for your network
 	card with &man.kldload.8;.  A module is not available for all
 	network card drivers (ISA cards and cards using the &man.ed.4;
 	driver, for example).  Alternatively, you may statically compile
 	the support for your card into your kernel.  Check
 	<filename>/usr/src/sys/i386/conf/LINT</filename> and the
 	manual page of the driver to know what to add in your kernel
 	configuration file.  For more information about recompiling your
 	kernel, please see <xref linkend="kernelconfig">.  If your card
 	was detected at boot by your kernel (<filename>GENERIC</filename>)
 	you do not have to build a new kernel.</para>
     </sect2>
 
     <sect2>
       <title>Configuring the Network Card</title>
 
       <indexterm>
 	<primary>Network card configuration</primary>
 	<secondary>configuration</secondary>
       </indexterm>
 
       <para>Once the right driver is loaded for the network card, the
 	card needs to be configured.  As with many other things, the
 	network card may have been configured at installation time by
 	<application>sysinstall</application>.</para>
 
       <para>To display the configuration for the network interfaces on
 	your system, enter the following command:</para>
 
 <screen>&prompt.user; <userinput>ifconfig</userinput>
 dc0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
         inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
         ether 00:a0:cc:da:da:da
         media: Ethernet autoselect (100baseTX &lt;full-duplex&gt;)
         status: active
 dc1: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
         inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
         ether 00:a0:cc:da:da:db
         media: Ethernet 10baseT/UTP
         status: no carrier
 lp0: flags=8810&lt;POINTOPOINT,SIMPLEX,MULTICAST&gt; mtu 1500
 lo0: flags=8049&lt;UP,LOOPBACK,RUNNING,MULTICAST&gt; mtu 16384
         inet 127.0.0.1 netmask 0xff000000
 tun0: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1500</screen>
 
       <note>
 	<para>Old versions of FreeBSD may require the <option>-a</option>
 	  option following &man.ifconfig.8;, for more details about the
 	  correct syntax of &man.ifconfig.8;, please refer to the manual
 	  page.  Note also that entries concerning IPv6
 	  (<literal>inet6</literal> etc.) were omitted in this
 	  example.</para>
       </note>
 
       <para>In this example, the following devices were
 	displayed:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><devicename>dc0</devicename>: The first Ethernet
 	    interface</para>
 	</listitem>
 
 	<listitem>
 	  <para><devicename>dc1</devicename>: The second Ethernet
 	    interface</para>
 	</listitem>
 
 	<listitem>
 	  <para><devicename>lp0</devicename>: The parallel port
 	    interface</para>
 	</listitem>
 
 	<listitem>
 	  <para><devicename>lo0</devicename>: The loopback device</para>
 	</listitem>
 
 	<listitem>
 	  <para><devicename>tun0</devicename>: The tunnel device used by
 	    <application>ppp</application></para>
 	</listitem>
       </itemizedlist>
 
       <para>FreeBSD uses the driver name followed by the order in
 	which one the card is detected at the kernel boot to name the
 	network card.  For example <devicename>sis2</devicename> would
 	be the third network card on the system using the &man.sis.4;
 	driver.</para>
 
       <para>In this example, the <devicename>dc0</devicename> device is
 	up and running.  The key indicators are:</para>
 
       <orderedlist>
 	<listitem>
 	  <para><literal>UP</literal> means that the card is configured
 	    and ready.</para>
 	</listitem>
 
 	<listitem>
 	  <para>The card has an Internet (<literal>inet</literal>)
 	    address (in this case
 	    <hostid role="ipaddr">192.168.1.3</hostid>).</para>
 	</listitem>
 
 	<listitem>
 	  <para>It has a valid subnet mask (<literal>netmask</literal>;
 	    <hostid role="netmask">0xffffff00</hostid> is the same as
 	    <hostid role="netmask">255.255.255.0</hostid>).</para>
 	</listitem>
 
 	<listitem>
 	  <para>It has a valid broadcast address (in this case,
 	    <hostid role="ipaddr">192.168.1.255</hostid>).</para>
 	</listitem>
 
 	<listitem>
 	  <para>The MAC address of the card (<literal>ether</literal>)
 	    is <hostid role="mac">00:a0:cc:da:da:da</hostid></para>
 	</listitem>
 
 	<listitem>
 	  <para>The physical media selection is on autoselection mode
 	    (<literal>media: Ethernet autoselect (100baseTX
 	    &lt;full-duplex&gt;)</literal>).  We see that
 	    <devicename>dc1</devicename> was configured to run with
 	    <literal>10baseT/UTP</literal> media.  For more
 	    information on available media types for a driver, please
 	    refer to its manual page.</para>
 	</listitem>
 
 	<listitem>
 	  <para>The status of the link (<literal>status</literal>)
 	    is <literal>active</literal>, i.e. the carrier is detected.
 	    For <devicename>dc1</devicename>, we see
 	    <literal>status: no carrier</literal>.  This is normal when
 	    an ethernet cable is not plugged into the card.</para>
 	</listitem>
       </orderedlist>
 
       <para>If the &man.ifconfig.8; output had shown something similar
 	to:</para>
 
 <screen>dc0: flags=8843&lt;BROADCAST,SIMPLEX,MULTICAST&gt; mtu 1500
 	        ether 00:a0:cc:da:da:da</screen>
 
       <para>it would indicate the card has not been configured.</para>
 
       <para>To configure your card, you need <username>root</username>
 	privileges.  The network card configuration can be done from the
 	command line with &man.ifconfig.8; but you would have to do it
 	after each reboot of the system.  The file
 	<filename>/etc/rc.conf</filename> is where to add the network
 	card's configuration.</para>
 
       <para>Open <filename>/etc/rc.conf</filename> in your favorite
 	editor.  You need to add a line for each network card present on
 	the system, for example in our case, we added these lines:</para>
 
 <programlisting>ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0"
 ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlisting>
 
       <para>You have to replace <devicename>dc0</devicename>,
 	<devicename>dc1</devicename>, and so on, with
 	the correct device for your cards, and the addresses with the
 	proper ones.  You should read the card driver and
 	&man.ifconfig.8; manual pages for more details about the allowed
 	options and also &man.rc.conf.5; manual page for more
 	information on the syntax of
 	<filename>/etc/rc.conf</filename>.</para>
 
       <para>If you configured the network during installation, some
 	lines about the network card(s) may be already present.  Double
 	check <filename>/etc/rc.conf</filename> before adding any
 	lines.</para>
 
       <para>You will also have to edit the file
 	<filename>/etc/hosts</filename> to add the names and the IP
 	addresses of various machines of the LAN, if they are not already
 	there.  For more information please refer to &man.hosts.5;
 	and to <filename>/usr/share/examples/etc/hosts</filename>.</para>
     </sect2>
 
     <sect2>
       <title>Testing and Troubleshooting</title>
 
       <para>Once you have made the necessary changes in
 	<filename>/etc/rc.conf</filename>, you should reboot your
 	system.  This will allow the change(s) to the interface(s) to
 	be applied, and verify that the system restarts without any
 	configuration errors.</para>
 
       <para>Once the system has been rebooted, you should test the
 	network interfaces.</para>
 
       <sect3>
 	<title>Testing the Ethernet Card</title>
 
 	<indexterm>
 	  <primary>Network card configuration</primary>
 	  <secondary>Testing the card</secondary>
 	</indexterm>
 
 	<para>To verify that an Ethernet card is configured correctly,
 	  you have to try two things.  First, ping the interface itself,
 	  and then ping another machine on the LAN.</para>
 
 	<para>First let's test the interface:</para>
 
 <screen>&prompt.user; <userinput>ping -c5 192.168.1.3</userinput>
 PING 192.168.1.3 (192.168.1.3): 56 data bytes
 64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms
 64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms
 64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms
 64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms
 64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms
 
 --- 192.168.1.3 ping statistics ---
 5 packets transmitted, 5 packets received, 0% packet loss
 round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms</screen>
 
 	<para>Now we have to ping another machine on the LAN:</para>
 
 <screen>&prompt.user; <userinput>ping -c5 192.168.1.2</userinput>
 PING 192.168.1.2 (192.168.1.2): 56 data bytes
 64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms
 64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms
 64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms
 64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms
 64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms
 
 --- 192.168.1.2 ping statistics ---
 5 packets transmitted, 5 packets received, 0% packet loss
 round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen>
 
 	<para>You could also use the machine name instead of
 	  <hostid role="ipaddr">192.168.1.2</hostid> if you have set up the
 	  <filename>/etc/hosts</filename> file.</para>
       </sect3>
 
       <sect3>
 	<title>Troubleshooting</title>
 
       <indexterm>
 	<primary>Network card configuration</primary>
 	<secondary>Troubleshooting</secondary>
       </indexterm>
 
 	<qandaset>
 	  <qandaentry>
 	    <question>
 	      <para>Where can I find information about possible trouble
 		I may experience with my network card?</para>
 	    </question>
 
 	    <answer>
 	      <para>The manual page of the driver is the first piece of
 		documentation to read.  The mailing lists archives can
 		also be useful.</para>
 	    </answer>
 	  </qandaentry>
 
 	  <qandaentry>
 	    <question>
 	      <para>When I try to ping a machine on my LAN, I get this
 		message: <errorname>ping: sendto: Permission
 		denied</errorname>.</para>
 	    </question>
 
 	    <answer>
 	      <para>This means that you do not have permission to
 		send ICMP packets.  Check to see if a firewall is
 		running on the machine and if there are any rules
 		blocking ICMP.</para>
 	    </answer>
 	  </qandaentry>
 
 	  <qandaentry>
 	    <question>
 	      <para>I see a lot of <errorname>watchdog
 		timeout</errorname> messages in the system logs, and
 		when I try to ping a machine on the LAN, I get this
 		message: <errorname>ping: sendto: No route to
 		host</errorname>.</para>
 	    </question>
 
 	    <answer>
 	      <para>The first thing to do is to check your network
 		cable.  Many cards require a PCI slot supporting the
 		Bus Mastering.  On some old motherboards, only one PCI
 		slot allows it (most of time slot 0).  Check the
 		network card and the motherboard documentation to
 		determine if that may be the problem.</para>
 	    </answer>
 	  </qandaentry>
 
 	  <qandaentry>
 	    <question>
 	      <para>I see a lot of <errorname>device timeout</errorname>
 		messages in the system logs, and my network card does not
 		work.</para>
 	    </question>
 
 	    <answer>
 	      <para>Having one or two of these messages is sometimes
 		normal with some cards.  However, if they persist and the
 		network is not usable, make sure the network cable is
 		plugged in and that there are no IRQ conflicts between
 		the network card and another device (or devices) on the
 		system.</para>
 	    </answer>
 	  </qandaentry>
 
 	  <qandaentry>
 	    <question>
 	      <para>The performance of the card is poor, what can I
 		do?</para>
 	    </question>
 
 	    <answer>
 	      <para>It is difficult to answer to that question.  What is
 		your definition of <quote>poor performance</quote>?  Double
 		check everything in your configuration, read the
 		&man.tuning.7; manual page, and try to avoid cheap
 		network cards.  Many users have noted that setting the
 		media selection mode to <literal>autoselect</literal>
 		results in bad performance on some hardware.</para>
 	    </answer>
 	  </qandaentry>
 
 	  <qandaentry>
 	    <question>
 	      <para>Are there any recommended network cards or cards I
 		should stay away from?</para>
 	    </question>
 
 	    <answer>
 	      <para>You should avoid cheap cards for serious usage.  Cheap
 		cards often use buggy chipsets, and most of time do not
 		provide very good performance.  Many FreeBSD users like
 		cards using the &man.fxp.4; chipset, however, this does
 		not mean that all other chipsets are bad.</para>
 	    </answer>
 	  </qandaentry>
 	</qandaset>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="configtuning-virtual-hosts">
     <title>Virtual Hosts</title>
 
     <indexterm><primary>virtual hosts</primary></indexterm>
     <indexterm><primary>ip aliases</primary></indexterm>
 
     <para>A very common use of FreeBSD is virtual site hosting, where
       one server appears to the network as many servers.  This is
       achieved by assigning multiple network addresses to a single
       interface.</para>
 
     <para>A given network interface has one <quote>real</quote> address,
       and may have any number of <quote>alias</quote> addresses.
       These aliases are
       normally added by placing alias entries in
       <filename>/etc/rc.conf</filename>.</para>
 
     <para>An alias entry for the interface <devicename>fxp0</devicename>
       looks like:</para>
 
 <programlisting>ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"</programlisting>
 
     <para>Note that alias entries must start with alias0 and proceed
       upwards in order, (for example, _alias1, _alias2, and so on).
       The configuration process will stop at the first missing number.
     </para>
 
     <para>The calculation of alias netmasks is important, but
       fortunately quite simple.  For a given interface, there must be
       one address which correctly represents the network's netmask.
       Any other addresses which fall within this network must have a
       netmask of all 1's.</para>
 
     <para>For example, consider the case where the 
       <devicename>fxp0</devicename> interface is
       connected to two networks, the <hostid role="ipaddr">10.1.1.0</hostid>
       network with a netmask of <hostid role="netmask">255.255.255.0</hostid>
       and the <hostid role="ipaddr">202.0.75.16</hostid> network with
       a netmask of <hostid role="netmask">255.255.255.240</hostid>.
       We want the system to appear at <hostid role="ipaddr">10.1.1.1</hostid>
       through <hostid role="ipaddr">10.1.1.5</hostid> and at
       <hostid role="ipaddr">202.0.75.17</hostid> through
       <hostid role="ipaddr">202.0.75.20</hostid>.</para>
 
     <para>The following entries configure the adapter correctly for
       this arrangement:</para>
 
 <programlisting> ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
  ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
  ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
  ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
  ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
  ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
  ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
  ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
  ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting>
 
   </sect1>
 
   <sect1 id="configtuning-configfiles">
     <title>Configuration Files</title>
 
     <sect2>
       <title><filename>/etc</filename> Layout</title>
       <para>There are a number of directories in which configuration
 	information is kept.  These include:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <tbody>
 	    <row>
 	      <entry><filename>/etc</filename></entry>
 	      <entry>Generic system configuration information; data here is 
 		system-specific.</entry>
 	    </row>
 	    <row>
 	      <entry><filename>/etc/defaults</filename></entry>
 	      <entry>Default versions of system configuration files.</entry>
 	    </row>
 	    <row>
 	      <entry><filename>/etc/mail</filename></entry>
 	      <entry>Extra &man.sendmail.8; configuration, other 
 		MTA configuration files.
 	      </entry>
 	    </row>
 	    <row>
 	      <entry><filename>/etc/ppp</filename></entry>
 	      <entry>Configuration for both user- and kernel-ppp programs.
 	      </entry>
 	    </row>
 	    <row>
 	      <entry><filename>/etc/namedb</filename></entry>
 	      <entry>Default location for &man.named.8; data.  Normally
 		<filename>named.conf</filename> and zone files are stored
                 here.</entry>
 	    </row>
 	    <row>
 	      <entry><filename>/usr/local/etc</filename></entry> 
 	      <entry>Configuration files for installed applications.
 		May contain per-application subdirectories.</entry>
 	    </row>
 	    <row>
 	      <entry><filename>/usr/local/etc/rc.d</filename></entry>
 	      <entry>Start/stop scripts for installed applications.</entry>
 	    </row>
 	    <row>
 	      <entry><filename>/var/db</filename></entry>
 	      <entry>Automatically generated system-specific database files,
                  such as the package database, the locate database, and so
                  on</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
 
     <sect2>
       <title>Hostnames</title>
 
       <indexterm><primary>hostname</primary></indexterm>
       <indexterm><primary>DNS</primary></indexterm>
 
       <sect3>
 	<title><filename>/etc/resolv.conf</filename></title>
 
 	<indexterm>
 	  <primary><filename>resolv.conf</filename></primary>
 	</indexterm>
 
 	<para><filename>/etc/resolv.conf</filename> dictates how FreeBSD's
 	  resolver accesses the Internet Domain Name System (DNS).</para>
 
 	<para>The most common entries to <filename>resolv.conf</filename> are:
 	</para>
       
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <tbody>
 	      <row>
 		<entry><literal>nameserver</literal></entry> 
 		<entry>The IP address of a name server the resolver
 		  should query.  The servers are queried in the order
 		  listed with a maximum of three.</entry>
 	      </row>
 	      <row>
 		<entry><literal>search</literal></entry>
 		<entry>Search list for hostname lookup.  This is normally
 		  determined by the domain of the local hostname.</entry>
 	      </row>
 	      <row>
 		<entry><literal>domain</literal></entry>
 		<entry>The local domain name.</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
 	<para>A typical <filename>resolv.conf</filename>:</para>
 
 	<programlisting>search example.com
 nameserver 147.11.1.11
 nameserver 147.11.100.30</programlisting>
 
 	<note><para>Only one of the <literal>search</literal> and
 	  <literal>domain</literal> options should be used.</para></note>
 
 	<para>If you are using DHCP, &man.dhclient.8; usually rewrites 
 	  <filename>resolv.conf</filename> with information received from the 
 	  DHCP server.</para>
       </sect3>
 
       <sect3>
 	<title><filename>/etc/hosts</filename></title>
 
 	<indexterm><primary>hosts</primary></indexterm>
 	
 	<para><filename>/etc/hosts</filename> is a simple text
 	  database reminiscent of the old Internet.  It works in
 	  conjunction with DNS and NIS providing name to IP address
 	  mappings.  Local computers connected via a LAN can be placed
 	  in here for simplistic naming purposes instead of setting up
 	  a &man.named.8; server.  Additionally,
 	  <filename>/etc/hosts</filename> can be used to provide a
 	  local record of Internet names, reducing the need to query
 	  externally for commonly accessed names.</para>
 
 	<programlisting># &dollar;FreeBSD&dollar;
 #
 # Host Database
 # This file should contain the addresses and aliases
 # for local hosts that share this file.
 # In the presence of the domain name service or NIS, this file may
 # not be consulted at all; see /etc/nsswitch.conf for the resolution order.
 #
 #
 ::1                     localhost localhost.my.domain myname.my.domain
 127.0.0.1               localhost localhost.my.domain myname.my.domain
 
 #
 # Imaginary network.
 #10.0.0.2               myname.my.domain myname
 #10.0.0.3               myfriend.my.domain myfriend
 #
 # According to RFC 1918, you can use the following IP networks for
 # private nets which will never be connected to the Internet:
 #
 #       10.0.0.0        -   10.255.255.255
 #       172.16.0.0      -   172.31.255.255
 #       192.168.0.0     -   192.168.255.255
 #
 # In case you want to be able to connect to the Internet, you need
 # real official assigned numbers.  PLEASE PLEASE PLEASE do not try
 # to invent your own network numbers but instead get one from your
 # network provider (if any) or from the Internet Registry (ftp to
 # rs.internic.net, directory `/templates').
 #</programlisting>
 
 	<para><filename>/etc/hosts</filename> takes on the simple format
 	  of:</para>
 	
 	<programlisting>[Internet address] [official hostname] [alias1] [alias2] ...</programlisting>
 
 	<para>For example:</para>
 
 	<programlisting>10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2</programlisting>
 
 	<para>Consult &man.hosts.5; for more information.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Log File Configuration</title>
      
       <indexterm><primary>log files</primary></indexterm>
       
       <sect3>
 	<title><filename>syslog.conf</filename></title>
 	
 	<indexterm><primary>syslog.conf</primary></indexterm>
 	
 	<para><filename>syslog.conf</filename> is the configuration file
 	  for the &man.syslogd.8; program.  It indicates which types
 	  of <command>syslog</command> messages are logged to particular
 	  log files.</para>
 
 	<programlisting># &dollar;FreeBSD&dollar;
 #
 #       Spaces ARE valid field separators in this file. However,
 #       other *nix-like systems still insist on using tabs as field
 #       separators. If you are sharing this file between systems, you
 #       may want to use only tabs as field separators here.
 #       Consult the syslog.conf(5) manual page.
 *.err;kern.debug;auth.notice;mail.crit          /dev/console
 *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
 security.*                                      /var/log/security
 mail.info                                       /var/log/maillog
 lpr.info                                        /var/log/lpd-errs
 cron.*                                          /var/log/cron
 *.err                                           root
 *.notice;news.err                               root
 *.alert                                         root
 *.emerg                                         *
 # uncomment this to log all writes to /dev/console to /var/log/console.log
 #console.info                                   /var/log/console.log
 # uncomment this to enable logging of all log messages to /var/log/all.log
 #*.*                                            /var/log/all.log
 # uncomment this to enable logging to a remote log host named loghost
 #*.*                                            @loghost
 # uncomment these if you're running inn
 # news.crit                                     /var/log/news/news.crit
 # news.err                                      /var/log/news/news.err
 # news.notice                                   /var/log/news/news.notice
 !startslip
 *.*                                             /var/log/slip.log
 !ppp
 *.*                                             /var/log/ppp.log</programlisting>
 
 	<para>Consult the &man.syslog.conf.5; manual page for more
 	  information.</para>
       </sect3>
 
       <sect3>
 	<title><filename>newsyslog.conf</filename></title>
 
 	<indexterm><primary>newsyslog.conf</primary></indexterm>
 	
 	<para><filename>newsyslog.conf</filename> is the configuration
 	  file for &man.newsyslog.8;, a program that is normally scheduled
 	  to run by &man.cron.8;.  &man.newsyslog.8; determines when log
 	  files require archiving or rearranging.
 	  <filename>logfile</filename> is moved to
 	  <filename>logfile.0</filename>, <filename>logfile.0</filename>
 	  is moved to <filename>logfile.1</filename>, and so on.
 	  Alternatively, the log files may be archived in &man.gzip.1; format
 	  causing them to be named: <filename>logfile.0.gz</filename>,
 	  <filename>logfile.1.gz</filename>, and so on.</para>
 
 	<para><filename>newsyslog.conf</filename> indicates which log
 	  files are to be managed, how many are to be kept, and when
 	  they are to be touched.  Log files can be rearranged and/or
 	  archived when they have either reached a certain size, or at a
 	  certain periodic time/date.</para>
 	
 	<programlisting># configuration file for newsyslog
 # &dollar;FreeBSD&dollar;
 #
 # filename          [owner:group]    mode count size when [ZB] [/pid_file] [sig_num]
 /var/log/cron                           600  3     100  *     Z
 /var/log/amd.log                        644  7     100  *     Z
 /var/log/kerberos.log                   644  7     100  *     Z
 /var/log/lpd-errs                       644  7     100  *     Z
 /var/log/maillog                        644  7     *    @T00  Z
 /var/log/sendmail.st                    644  10    *    168   B
 /var/log/messages                       644  5     100  *     Z
 /var/log/all.log                        600  7     *    @T00  Z
 /var/log/slip.log                       600  3     100  *     Z
 /var/log/ppp.log                        600  3     100  *     Z
 /var/log/security                       600  10    100  *     Z
 /var/log/wtmp                           644  3     *    @01T05 B
 /var/log/daily.log                      640  7     *    @T00  Z
 /var/log/weekly.log                     640  5     1    $W6D0 Z
 /var/log/monthly.log                    640  12    *    $M1D0 Z
 /var/log/console.log                    640  5     100  *     Z</programlisting>
 
 	<para>Consult the &man.newsyslog.8; manual page for more
 	  information.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title><filename>sysctl.conf</filename></title>
 
       <indexterm><primary>sysctl.conf</primary></indexterm>
       <indexterm><primary>sysctl</primary></indexterm>
 
       <para><filename>sysctl.conf</filename> looks much like 
 	<filename>rc.conf</filename>.  Values are set in a 
 	<literal>variable=value</literal>
 	form.  The specified values are set after the system goes into
 	multi-user mode.  Not all variables are settable in this mode.</para>
 
       <para>A sample <filename>sysctl.conf</filename> turning off logging
 	of fatal signal exits and letting Linux programs know they are really
 	running under FreeBSD:</para>
 
       <programlisting>kern.logsigexit=0       # Do not log fatal signal exits (e.g. sig 11)
 compat.linux.osname=FreeBSD
 compat.linux.osrelease=4.3-STABLE</programlisting>
     </sect2>
   </sect1>
 
   <sect1 id="configtuning-sysctl">
     <title>Tuning with sysctl</title>
 
     <indexterm><primary>sysctl</primary></indexterm>
     <indexterm><primary>Tuning with sysctl</primary></indexterm>
     
     <para>&man.sysctl.8; is an interface that allows you to make changes
       to a running FreeBSD system.  This includes many advanced
       options of the TCP/IP stack and virtual memory system that can
       dramatically improve performance for an experienced system
       administrator.  Over five hundred system variables can be read
       and set using &man.sysctl.8;.</para>
     
     <para>At its core, &man.sysctl.8; serves two functions: to read and
       to modify system settings.</para>
 
     <para>To view all readable variables:</para>
 
     <screen>&prompt.user; <userinput>sysctl -a</userinput></screen>
     
     <para>To read a particular variable, for example,
       <varname>kern.maxproc</varname>:</para>
     
     <screen>&prompt.user; <userinput>sysctl kern.maxproc</userinput>
 kern.maxproc: 1044</screen>
 
     <para>To set a particular variable, use the intuitive
       <replaceable>variable</replaceable>=<replaceable>value</replaceable>
       syntax:</para>
     
     <screen>&prompt.root; <userinput>sysctl kern.maxfiles=5000</userinput>
 kern.maxfiles: 2088 -> 5000</screen>
 
     <para>Settings of sysctl variables are usually either strings,
       numbers, or booleans (a  boolean being <literal>1</literal> for yes
       or a <literal>0</literal> for no).</para>
   </sect1>
 
   <sect1 id="configtuning-disk">
     <title>Tuning Disks</title>
 
     <sect2>
       <title>Sysctl Variables</title>
       
       <sect3>
 	<title><varname>vfs.vmiodirenable</varname></title>
      
 	<indexterm>
 	  <primary><varname>vfs.vmiodirenable</varname></primary>
 	</indexterm>
 	
 	<para>The <varname>vfs.vmiodirenable</varname> sysctl variable
 	  may be set to either 0 (off) or 1 (on); it is 1 by default.  This variable controls how
 	  directories are cached by the system.  Most directories are
 	  small, using just a single fragment (typically 1&nbsp;K) in the
 	  file system and less (typically 512&nbsp;bytes) in the buffer
 	  cache.  However, when operating in the default mode the buffer
 	  cache will only cache a fixed number of directories even if
 	  you have a huge amount of memory.  Turning on this sysctl
 	  allows the buffer cache to use the VM Page Cache to cache the
 	  directories, making all the memory available for caching
 	  directories.  However,
 	  the minimum in-core memory used to cache a directory is the
 	  physical page size (typically 4&nbsp;K) rather than 512&nbsp;bytes.  We
 	  recommend turning this option on if you are running any
 	  services which manipulate large numbers of files.  Such
 	  services can include web caches, large mail systems, and news
 	  systems.  Turning on this option will generally not reduce
 	  performance even with the wasted memory but you should
 	  experiment to find out.</para>
       </sect3>
      
       <sect3>
 	<title><varname>hw.ata.wc</varname></title>
       
 	<indexterm>
 	  <primary><varname>hw.ata.wc</varname></primary>
 	</indexterm>
 
 	<para>FreeBSD&nbsp;4.3 flirted with turning off IDE write caching.
 	  This reduced write bandwidth to IDE disks but was considered
 	  necessary due to serious data consistency issues introduced
 	  by hard drive vendors.  The problem is that IDE
 	  drives lie about when a write completes.  With IDE write
 	  caching turned on, IDE hard drives not only write data
 	  to disk out of order, but will sometimes delay writing some
 	  blocks indefinitely when under heavy disk loads.  A crash or
 	  power failure may cause serious file system corruption.
 	  FreeBSD's default was changed to be safe.  Unfortunately, the
 	  result was such a huge performance loss that we changed
 	  write caching back to on by default after the release.  You
 	  should check the default on your system by observing the
 	  <varname>hw.ata.wc</varname> sysctl variable.  If IDE write
 	  caching is turned off, you can turn it back on by setting
 	  the kernel variable back to 1.  This must be done from the
 	  boot loader at boot time.  Attempting to do it after the
 	  kernel boots will have no effect.</para>
 	
 	<para>For more information, please see &man.ata.4;.</para>
       </sect3>
     </sect2>
 
     <sect2 id="soft-updates">
       <title>Soft Updates</title>
 
       <indexterm><primary>Soft Updates</primary></indexterm>
       <indexterm><primary>tunefs</primary></indexterm>
       
       <para>The &man.tunefs.8; program can be used to fine-tune a
 	file system.  This program has many different options, but for
 	now we are only concerned with toggling Soft Updates on and
 	off, which is done by:</para>
 
       <screen>&prompt.root; <userinput>tunefs -n enable /filesystem</userinput>
 &prompt.root; <userinput>tunefs -n disable /filesystem</userinput></screen>
 
       <para>A filesystem cannot be modified with &man.tunefs.8; while
 	it is mounted.  A good time to enable Soft Updates is before any
 	partitions have been mounted, in single-user mode.</para>
 
       <note><para>As of FreeBSD&nbsp;4.5, it is possible to enable Soft Updates
 	at filesystem creation time, through use of the <literal>-U</literal>
 	option to &man.newfs.8;.</para></note>
 
       <para>Soft Updates drastically improves meta-data performance, mainly 
         file creation and deletion, through the use of a memory cache.  We
         recommend to use Soft Updates on all of your filesystems.  There
         are two downsides to Soft Updates that you should be aware of:  First,
         Soft Updates guarantees filesystem consistency in the case of a crash
         but could very easily be several seconds (even a minute!) behind
         updating the physical disk.  If your system crashes you may lose more
         work than otherwise.  Secondly, Soft Updates delays the freeing of
         filesystem blocks.  If you have a filesystem (such as the root
 	filesystem) which is almost full, performing a major update, such as
         <command>make installworld</command>, can cause the filesystem to run
 	out of space and the update to fail.</para>
 
       <sect3>
 	<title>More details about Soft Updates</title>
 	
 	<indexterm><primary>Soft Updates (Details)</primary></indexterm>
 
 	<para>There are two traditional approaches to writing a filesystems meta-data
     	  back to disk.  (Meta-data updates are updates to
 	  non-content data like inodes or directories.)</para>
 	
 	<para>Historically, the default behavior was to write out
 	  meta-data updates synchronously.  If a directory had been
 	  changed, the system waited until the change was actually
 	  written to disk.  The file data buffers (file contents) were
 	  passed through the buffer cache and backed up
 	  to disk later on asynchronously.  The advantage of this
 	  implementation is that it operates safely.  If there is
 	  a failure during an update, the meta-data are always in a
 	  consistent state.  A file is either created completely
 	  or not at all.  If the data blocks of a file did not find
 	  their way out of the buffer cache onto the disk by the time
 	  of the crash, &man.fsck.8; is able to recognize this and
 	  repair the filesystem by setting the file length to
 	  0.  Additionally, the implementation is clear and simple.
 	  The disadvantage is that meta-data changes are slow.  An
 	  <command>rm -r</command>, for instance, touches all the files in a
 	  directory sequentially, but each directory
 	  change (deletion of a file) will be written synchronously
 	  to the disk.  This includes updates to the directory itself,
 	  to the inode table, and possibly to indirect blocks
 	  allocated by the file.  Similar considerations apply for
 	  unrolling large hierarchies (<command>tar -x</command>).</para>
 
 	<para>The second case is asynchronous meta-data updates.  This
   	  is the default for Linux/ext2fs and
   	  <command>mount -o async</command> for *BSD ufs.  All
   	  meta-data updates are simply being passed through the buffer
   	  cache too, that is, they will be intermixed with the updates
   	  of the file content data.  The advantage of this
   	  implementation is there is no need to wait until each
   	  meta-data update has been written to disk, so all operations
   	  which cause huge amounts of meta-data updates work much
   	  faster than in the synchronous case.  Also, the
   	  implementation is still clear and simple, so there is a low
   	  risk for bugs creeping into the code.  The disadvantage is
   	  that there is no guarantee at all for a consistent state of
   	  the filesystem.  If there is a failure during an operation
   	  that updated large amounts of meta-data (like a power
   	  failure, or someone pressing the reset button),
 	  the filesystem
   	  will be left in an unpredictable state.  There is no opportunity
   	  to examine the state of the filesystem when the system
   	  comes up again; the data blocks of a file could already have
   	  been written to the disk while the updates of the inode
   	  table or the associated directory were not.  It is actually
   	  impossible to implement a <command>fsck</command> which is
   	  able to clean up the resulting chaos (because the necessary
   	  information is not available on the disk).  If the
 	  filesystem has been damaged beyond repair, the only choice
 	  is to use &man.newfs.8; on it and restore it from backup.
 	  </para>
 
 	<para>The usual solution for this problem was to implement
 	  <emphasis>dirty region logging</emphasis>, which is also
 	  referred to as <emphasis>journaling</emphasis>, although that
 	  term is not used consistently and is occasionally applied
 	  to other forms of transaction logging as well.  Meta-data
 	  updates are still written synchronously, but only into a
 	  small region of the disk.  Later on they will be moved
 	  to their proper location.  Because the logging
 	  area is a small, contiguous region on the disk, there
 	  are no long distances for the disk heads to move, even
 	  during heavy operations, so these operations are quicker
 	  than synchronous updates.
 	  Additionally the complexity of the implementation is fairly
 	  limited, so the risk of bugs being present is low.  A disadvantage
 	  is that all meta-data are written twice (once into the
 	  logging region and once to the proper location) so for
 	  normal work, a performance <quote>pessimization</quote>
 	  might result.  On the other hand, in case of a crash, all
 	  pending meta-data operations can be quickly either rolled-back
 	  or completed from the logging area after the system comes
 	  up again, resulting in a fast filesystem startup.</para>
      
 	<para>Kirk McKusick, the developer of Berkeley FFS,
 	   solved this problem with Soft Updates: all pending
 	   meta-data updates are kept in memory and written out to disk
 	   in a sorted sequence (<quote>ordered meta-data
 	   updates</quote>).  This has the effect that, in case of
 	   heavy meta-data operations, later updates to an item
 	   <quote>catch</quote> the earlier ones if the earlier ones are still in
 	   memory and have not already been written to disk.  So all
 	   operations on, say, a directory are generally performed in
 	   memory before the update is written to disk (the data
 	   blocks are sorted according to their position so
 	   that they will not be on the disk ahead of their meta-data).
 	   If the system crashes, this causes an implicit <quote>log
 	   rewind</quote>: all operations which did not find their way
 	   to the disk appear as if they had never happened.  A
 	   consistent filesystem state is maintained that appears to
 	   be the one of 30 to 60 seconds earlier.  The
 	   algorithm used guarantees that all resources in use
 	   are marked as such in their appropriate bitmaps: blocks and inodes.
 	   After a crash, the only resource allocation error
 	   that occurs is that resources are
 	   marked as <quote>used</quote> which are actually <quote>free</quote>.
 	   &man.fsck.8; recognizes this situation,
 	   and frees the resources that are no longer used.  It is safe to
 	   ignore the dirty state of the filesystem after a crash by
 	   forcibly mounting it with <command>mount -f</command>.  In
 	   order to free resources that may be unused, &man.fsck.8;
 	   needs to be run at a later time.  This is the idea behind
 	   the <emphasis>background fsck</emphasis>: at system startup
 	   time, only a <emphasis>snapshot</emphasis> of the
 	   filesystem is recorded.  The <command>fsck</command> can be
 	   run later on.  All filesystems can then be mounted
 	   <quote>dirty</quote>, so the system startup proceeds in
 	   multiuser mode.  Then, background <command>fsck</command>s
 	   will be scheduled for all filesystems where this is required, to free
 	   resources that may be unused.  (Filesystems that do not use
 	   Soft Updates still need the usual foreground
 	   <command>fsck</command> though.)</para>
 
 	 <para>The advantage is that meta-data operations are nearly as
 	   fast as asynchronous updates (i.e. faster than with
 	   <emphasis>logging</emphasis>, which has to write the
 	   meta-data twice).  The disadvantages are the complexity of
 	   the code (implying a higher risk for bugs in an area that
 	   is highly sensitive regarding loss of user data), and a
 	   higher memory consumption.  Additionally there are some
 	   idiosyncrasies one has to get used to.
 	   After a crash, the state of the filesystem appears to be
 	   somewhat <quote>older</quote>.  In situations where
 	   the standard synchronous approach would have caused some
 	   zero-length files to remain after the
 	   <command>fsck</command>, these files do not exist at all
 	   with a Soft Updates filesystem because neither the meta-data
 	   nor the file contents have ever been written to disk.
 	   Disk space is not released until the updates have been
 	   written to disk, which may take place some time after
 	   running <command>rm</command>.  This may cause problems
 	   when installing large amounts of data on a filesystem
 	   that does not have enough free space to hold all the files
 	   twice.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="configtuning-kernel-limits">
     <title>Tuning Kernel Limits</title>
 
     <indexterm><primary>Tuning kernel limits</primary></indexterm>
     
     <sect2 id="file-process-limits">
       <title>File/Process Limits</title>
 
       <sect3 id="kern-maxfiles">
 	<title><varname>kern.maxfiles</varname></title>
 
 	<indexterm>
 	  <primary><varname>kern.maxfiles</varname></primary>
 	</indexterm>
 	
 	<para><varname>kern.maxfiles</varname> can be raised or
 	  lowered based upon your system requirements.  This variable
 	  indicates the maximum number of file descriptors on your
 	  system.  When the file descriptor table is full,
 	  <errorname>file: table is full</errorname> will show up repeatedly
 	  in the system message buffer, which can be viewed with the
 	  <command>dmesg</command> command.</para>
 
 	<para>Each open file, socket, or fifo uses one file
 	  descriptor.  A large-scale production server may easily
 	  require many thousands of file descriptors, depending on the
 	  kind and number of services running concurrently.</para>
 
 	<para><varname>kern.maxfile</varname>'s default value is
 	  dictated by the <option>MAXUSERS</option> option in your
           kernel configuration file.  <varname>kern.maxfiles</varname> grows
           proportionally to the value of <option>MAXUSERS</option>.  When
           compiling a custom kernel, it is a good idea to set this kernel
           configuration option according to the uses of your system.  From
           this number, the kernel is given most of its pre-defined limits.
           Even though a production machine may not actually have 256 users
           connected as once, the resources needed may be similar to a
           high-scale web server.</para>
 
 	<note><para>As of FreeBSD&nbsp;4.5, setting <option>MAXUSERS</option> to
 	  <literal>0</literal> in your kernel configuration file will choose
 	  a reasonable default value based on the amount of RAM present in
 	  your system.</para></note>
 
       </sect3>
     </sect2>
     <sect2>
       <title>Network Limits</title>
 
       <para>The <option>NMBCLUSTERS</option> kernel configuration
 	option dictates the amount of network mbufs available to the
 	system.  A heavily-trafficked server with a low number of MBUFs
 	will hinder FreeBSD's ability.  Each cluster represents
 	approximately 2&nbsp;K of memory, so a value of 1024 represents 2
 	megabytes of kernel memory reserved for network buffers.  A
 	simple calculation can be done to figure out how many are
 	needed.  If you have a web server which maxes out at 1000
 	simultaneous connections, and each connection eats a 16&nbsp;K receive
 	and 16&nbsp;K send buffer, you need approximately 32&nbsp;MB worth of
 	network buffers to cover the web server.  A good rule of thumb is
 	to multiply by 2, so 2x32&nbsp;MB&nbsp;/&nbsp;2&nbsp;KB&nbsp;= 64&nbsp;MB&nbsp;/&nbsp;2&nbsp;kB&nbsp;= 32768.</para>
     </sect2>
   </sect1>
 
   <sect1 id="adding-swap-space">
     <title>Adding Swap Space</title>
 
     <para>No matter how well you plan, sometimes a system doesn't run
       as you expect.  If you find you need more swap space, it's
       simple enough to add.  You have three ways to increase swap
       space: adding a new hard drive, enabling swap over NFS, and
       creating a swap file on an existing partition.</para>
 
     <sect2 id="new-drive-swap">
       <title>Swap on a New Hard Drive</title>
 
       <para>The best way to add swap, of course, is to use this as an
 	excuse to add another hard drive.  You can always use another
 	hard drive, after all.  If you can do this, go reread the
 	discussion of <ulink
 	url="configtuning-initial.html#SWAP-DESIGN">swap space
 	</ulink> from the <ulink
 	url="configtuning-initial.html">Initial Configuration</ulink>
 	section of the Handbook for some suggestions on how to best
 	arrange your swap.</para>
     </sect2>
 
     <sect2 id="nfs-swap">
       <title>Swapping over NFS</title>
 
       <para>Swapping over NFS is only recommended if you do not have a
 	local hard disk to swap to.  Swapping over NFS is slow and
 	inefficient in versions of FreeBSD prior to 4.X.  It is
 	reasonably fast and efficient in 4.0-RELEASE and newer.  Even
 	with newer versions of FreeBSD, NFS swapping will be limited
 	by the available network bandwidth and puts an additional
 	burden on the NFS server.</para>
     </sect2>
 
     <sect2 id="create-swapfile">
       <title>Swapfiles</title>
 
       <para>You can create a file of a specified size to use as a swap
 	file.  In our example here we will use a 64MB file called
 	<filename>/usr/swap0</filename>.  You can use any name you
 	want, of course.</para>
 
       <example>
         <title>Creating a Swapfile on FreeBSD 4.X</title>
 
       <orderedlist>
         <listitem>
           <para>Be certain that your kernel configuration includes
             the vnode driver.  It is <emphasis>not</emphasis> in recent versions of
             <filename>GENERIC</filename>.</para>
 
           <programlisting>pseudo-device   vn 1   #Vnode driver (turns a file into a device)</programlisting>
         </listitem>
 
 	<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 or to enable the swap file immediately,
             type:</para>
 
           <screen>&prompt.root; <userinput>vnconfig -e /dev/vn0b /usr/swap0 swap</userinput></screen>
         </listitem>
       </orderedlist>
 
       </example>
       <example>
 	<title>Creating a Swapfile on FreeBSD 5.X</title>
 
       <orderedlist>
 	<listitem>
 	  <para>Be certain that your kernel configuration includes
 	    the memory disk driver (&man.md.4;).  It is default in
 	    <filename>GENERIC</filename> kernel.</para>
 
 	  <programlisting>device   md   # Memory "disks"</programlisting>
 	</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 or to enable the swap file immediately,
             type:</para>
 
 	  <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /usr/swap0 -u 0 && swapon /dev/md0</userinput></screen>
         </listitem>
       </orderedlist>
 
       </example>
     </sect2>
   </sect1>
 
   <sect1 id="acpi-overview">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Hiten</firstname>
 	  <surname>Pandya</surname>
 	  <contrib>Written by </contrib>
 	</author>
 	<author>
 	  <firstname>Tom</firstname>
 	  <surname>Rhodes</surname>
 	</author>
       </authorgroup>
     </sect1info>
     
     <title>ACPI and FreeBSD</title>
 
     <para>It is very important to utilize hardware resources in an
       efficient manner.  Before <acronym>ACPI</acronym> was introduced,
       it was very difficult and inflexible for operating systems to manage
       the power usage and thermal properties of a system.  The hardware was
       either controlled by some sort of <acronym>BIOS</acronym> embedded
       interface, i.e.: <emphasis>Plug and Play BIOS (PNPBIOS)</emphasis>,
       <emphasis>Advanced Power Management (APM)</emphasis> and so on.
       Power and Resource Management is one of the key components of a modern
       operating system.  For example, you would want an operating system to
       monitor system limits (and possibly take an action), in case your system
       temperature increased unexpectedly.</para>
 
     <para>In this section of the FreeBSD Handbook, we will provide
       comprehensive information about <acronym>ACPI</acronym>.  References
       will be provided for further reading, at the end.  Please be aware
       that <acronym>ACPI</acronym> is only available on FreeBSD&nbsp;5.X and
       above.</para>
 
     <sect2 id="acpi-intro">
       <title>What is ACPI?</title>
 
       <para>Advanced Configuration and Power Interface
 	(<acronym>ACPI</acronym>) is a standard written by
 	an alliance of vendors to provide a standard interface for
 	hardware resources and power management (hence the name).
 	It is a key element in <emphasis>Operating System-directed
 	configuration and Power Management</emphasis>, i.e.: it provides
 	more control and flexibility to the operating system (<acronym>OS</acronym>).
 	Modern systems <quote>stretched</quote> the limits of the current
 	Plug and Play interfaces (such as APM, which is used in FreeBSD&nbsp;4.X),
 	prior to the introduction of <acronym>ACPI</acronym>.  <acronym>ACPI</acronym>
 	is the direct successor to <acronym>APM</acronym> (Advanced Power
 	Management).</para>
 
     <sect2 id="acpi-config">
       <title>Configuring <acronym>ACPI</acronym></title>
       
       <para>The <filename>acpi.ko</filename> driver is loaded by default
 	at start up by the &man.loader.8; and should <emphasis>not</emphasis>
 	be compiled into the kernel.  The reasoning behind this is that modules
 	are easier to work with, say if switching to another <filename>acpi.ko</filename>
 	without doing a kernel rebuild.  This has the advantage of making testing easier.
 	Another reason is that starting <acronym>ACPI</acronym> after a system has been
 	brought up is not too useful, and in some cases can be fatal.  In doubt, just
 	disable <acronym>ACPI</acronym> all together. This driver should not and can not
 	be unloaded because the system bus uses it for various hardware interactions.
 	<acronym>ACPI</acronym> can be disabled with the &man.acpiconf.8; utility.
 	In fact most of the interaction with <acronym>ACPI</acronym> can be done via
 	&man.acpiconf.8;.  Basically this means, if anything about <acronym>ACPI</acronym>
 	is in the &man.dmesg.8; output, then most likely it is already running.</para>
 
       <note><para><acronym>ACPI</acronym> and <acronym>APM</acronym> cannot coexist and
 	should be used separately.  The last one to load will terminate if the driver
 	notices the other running.</para></note>
 
       <para>In the simplest form, <acronym>ACPI</acronym> can be used to put the
 	system into a sleep mode with &man.acpiconf.8;, the <option>-s</option>
 	flag, and a <literal>1-5</literal> option.  Most users will only need
 	<literal>1</literal>.  Option <literal>5</literal> will do a soft-off
 	which is the same action as:</para>
 
       <screen>&prompt.root; <userinput>halt -p</userinput></screen>
       
       <para>The other options are available.  Check out the &man.acpiconf.8;
 	manual page for more information.</para>
     </sect2>
     
     <sect2 id="acpi-debug">
       <title>Debugging <acronym>ACPI</acronym></title>
 
       <para>Almost everything in <acronym>ACPI</acronym> is transparent, until
 	it does not work.  That is usually when you as a user will know there
 	is something not working properly.</para>
 
     </sect2>
   </sect1>
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
index 67c55e34e8..f82983cd85 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -1,1859 +1,1859 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="cutting-edge">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured, reorganized, and parts updated by </contrib>
       </author>
       <!-- Mar 2000 -->
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Jordan</firstname>
 	<surname>Hubbard</surname>
 	<contrib>Original work by </contrib>
       </author>
       <author>
 	<firstname>Poul-Henning</firstname>
 	<surname>Kamp</surname>
       </author>
       <author>
 	<firstname>John</firstname>
 	<surname>Polstra</surname>
       </author>
       <author>
 	<firstname>Nik</firstname>
 	<surname>Clayton</surname>
       </author>
     </authorgroup>
     <!-- with feedback from various others -->
   </chapterinfo>
 
   <title>The Cutting Edge</title>
 
-  <sect1>
+  <sect1 id="cutting-edge-synopsis">
     <title>Synopsis</title>
 
     <para>&os; is under constant development between releases.  For
       people who want to be on the cutting edge, there are several easy
       mechanisms for keeping your system in sync with the latest
       developments.  Be warned&mdash;the cutting edge is not for everyone!
       This chapter will help you decide if you want to track the
       development system, or stick with one of the released
       versions.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem><para>The difference between the two development
       branches: &os.stable; and &os.current;.</para>
       </listitem>
       <listitem><para>How to keep your system up to date with
 	  <application>CVSup</application>,
 	  <application>CVS</application>, or
 	  <application>CTM</application>.</para>
       </listitem>
       <listitem><para>How to rebuild and reinstall the entire base
       system with <command>make world</command>.</para>
       </listitem>
 
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem><para>Properly setup your network connection (<xref
       linkend="advanced-networking">).</para>
       </listitem>
       <listitem><para>Know how to install additional third-party
         software (<xref linkend="ports">).</para></listitem>
     </itemizedlist>
   </sect1>
   
   <sect1 id="current-stable">
     <title>&os.current; vs. &os.stable;</title>
     <indexterm><primary>-CURRENT</primary></indexterm>
     <indexterm><primary>-STABLE</primary></indexterm>
 
     <para>There are two development branches to FreeBSD: &os.current; and
       &os.stable;.  This section will explain a bit about each and describe
       how to keep your system up-to-date with each respective tree.
       &os.current; will be discussed first, then &os.stable;.</para>
 
     <sect2 id="current">
       <title>Staying Current with &os;</title>
 
       <para>As you read this, keep in mind that &os.current; is the
 	<quote>bleeding edge</quote> of &os; development.
 	&os.current; users are expected to have a high degree of
 	technical skill, and should be capable of solving difficult
 	system problems on their own.  If you are new to &os;, think
 	twice before installing it.  </para>
 
       <sect3>
 	<title>What Is &os.current;?</title>
 	<indexterm><primary>snapshot</primary></indexterm>
 
 	<para>&os.current; is the latest working sources for &os;.
 	  This includes work in progress, experimental changes, and
 	  transitional mechanisms that might or might not be present
 	  in the next official release of the software.  While many
 	  &os; developers compile the &os.current; source code daily,
 	  there are periods of time when the sources are not
 	  buildable.  These problems are resolved as expeditiously as
 	  possible, but whether or not &os.current; brings disaster or
 	  greatly desired functionality can be a matter of which exact
 	  moment you grabbed the source code in!</para>
       </sect3>
 
       <sect3>
 	<title>Who Needs &os.current;?</title>
 
 	<para>&os.current; is made available for 3 primary
 	  interest groups:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>Members of the &os; group who are actively working
 	      on some part of the source tree and for whom keeping
 	      <quote>current</quote> is an absolute
 	      requirement.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Members of the &os; group who are active testers,
 	      willing to spend time solving problems in order to
 	      ensure that &os.current; remains as sane as possible.
 	      These are also people who wish to make topical
 	      suggestions on changes and the general direction of
 	      &os;, and submit patches to implement them.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Those who merely wish to keep an eye on things, or
 	      to use the current sources for reference purposes
 	      (e.g. for <emphasis>reading</emphasis>, not running).
 	      These people also make the occasional comment or
 	      contribute code.</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
 
       <sect3>
 	<title>What Is &os.current; <emphasis>Not</emphasis>?</title>
 
 	<orderedlist>
 	  <listitem>
 	    <para>A fast-track to getting pre-release bits because you
 	      heard there is some cool new feature in there and you
 	      want to be the first on your block to have it.  Being
 	      the first on the block to get the new feature means that
 	      you're the first on the block to get the new
 	      bugs.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>A quick way of getting bug fixes.  Any given version
 	      of &os.current; is just as likely to introduce new bugs
 	      as to fix existing ones.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>In any way <quote>officially supported</quote>.  We
 	      do our best to help people genuinely in one of the 3
 	      <quote>legitimate</quote> &os.current; groups, but we
 	      simply <emphasis>do not have the time</emphasis> to
 	      provide tech support.  This is not because we are mean
 	      and nasty people who do not like helping people out (we
 	      would not even be doing &os; if we were).  We simply
 	      cannot answer hundreds messages a day
 	      <emphasis>and</emphasis> work on FreeBSD!  Given the
 	      choice between improving &os; and answering lots of
 	      questions on experimental code, the developers opt for
 	      the former.</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
 
       <sect3>
 	<title>Using &os.current;</title>
       
 	<indexterm>
 	  <primary>-CURRENT</primary>
 	  <secondary>using</secondary>
 	</indexterm>
 	<orderedlist>
 	  <listitem>
 	    <para>Join the &a.current; and the &a.cvsall;.  This is not
 	      just a good idea, it is <emphasis>essential</emphasis>.  If
 	      you are not on the <emphasis>&a.current;</emphasis>,
 	      you will not see the comments that people are
 	      making about the current state of the system and thus will
 	      probably end up stumbling over a lot of problems that others
 	      have already found and solved.  Even more importantly, you
 	      will miss out on important bulletins which may be critical
 	      to your system's continued health.</para>
 
 	    <para>The &a.cvsall; will allow you to see the
 	      commit log entry for each change as it is made along with
 	      any pertinent information on possible side-effects.</para>
 
 	    <para>To join these lists, send mail to &a.majordomo; and
 	      specify the following in the body of your message:</para>
 
 	    <programlisting>subscribe freebsd-current
 subscribe cvs-all</programlisting>
             <indexterm>
               <primary><application>Majordomo</application></primary>
             </indexterm>
 
 	    <para>Optionally, you can also say <literal>help</literal>
 	      and <application>Majordomo</application> will send you full help on how to subscribe
 	      and unsubscribe to the various other mailing lists we
 	      support.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Grab the sources from <hostid
 	      role="fqdn">ftp.FreeBSD.org</hostid>.  You can do this in
 	      one of three ways:</para>
 
 	    <orderedlist>
               <indexterm>
                 <primary><command>cvsup</command></primary>
               </indexterm>
               <indexterm>
                 <primary><command>cron</command></primary>
               </indexterm>
               <indexterm>
 	        <primary>-CURRENT</primary>
 		<secondary>Syncing with <application>CVSup</application></secondary>
 	      </indexterm>
 
 	      <listitem>
 		<para>Use the <link linkend="cvsup">cvsup</link> program
 		  with <ulink
 		  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/standard-supfile">this
 		  supfile</ulink>.  This is the most recommended
 		  method, since it allows you to grab the entire
 		  collection once and then only what has changed from then
 		  on.  Many people run <command>cvsup</command> from 
 		  <command>cron</command> and keep their
  		  sources up-to-date automatically.  You have to 
  		  customize the sample <filename>supfile</filename> above, and configure 
  		  <link linkend="cvsup">cvsup</link> for your environment.
  		  If you want help doing this configuration,
  		  simply type:</para>
 
  		<screen>&prompt.root; <userinput>pkg_add -f ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages/Latest/cvsupit.tgz</userinput></screen>
 
 	      </listitem>
               <indexterm>
 	        <primary>-CURRENT</primary>
 	        <secondary>Downloading with ftp</secondary>
 	      </indexterm>
 
 	      <listitem>
 		<para>Use <command>ftp</command>.  The source tree for
 		  &os.current; is always <quote>exported</quote> on:
 		  <ulink
 		  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/</ulink>.
 		  Some of our FTP mirrors may also allow
 		  compressed/tarred grabbing of whole trees.  For example you
 		  see:</para>
 
 		<screen>usr.bin/lex</screen>
 
 		<para>You can do the following to get the whole directory
 		  as a tar file:</para>
 
 		<screen><prompt>ftp&gt;</prompt> <userinput>cd usr.bin</userinput>
 <prompt>ftp&gt;</prompt> <userinput>get lex.tar</userinput></screen>
 	      </listitem>
 
               <indexterm>
 	        <primary>-CURRENT</primary>
 		<secondary>Syncing with CTM</secondary>
 	      </indexterm>
 	      <listitem>
 		<para>Use the <application><link
 		  linkend="ctm">CTM</link></application> facility.  If you
 		  have very bad connectivity (high price connections or
 		  only email access) <application>CTM</application> is an option.
 		  However, it is a lot of hassle and can give you broken files.
 		  This leads to it being rarely used, which again increases
 		  the chance of it not working for fairly long periods of
 		  time.  We recommend using
 		  <application><link linkend="cvsup">CVSup</link></application>
 		  for anybody with a 9600&nbsp;bps modem or faster connection.
 		</para>
 	      </listitem>
 	    </orderedlist>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you are grabbing the sources to run, and not just
 	      look at, then grab <emphasis>all</emphasis> of &os.current;, not
 	      just selected portions.  The reason for this is that various
 	      parts of the source depend on updates elsewhere, and trying
 	      to compile just a subset is almost guaranteed to get you
 	      into trouble.</para>
 
 	  <indexterm>
 	    <primary>-CURRENT</primary>
 	    <secondary>compiling</secondary>
 	  </indexterm>
 	    <para>Before compiling &os.current;, read the
 	      <filename>Makefile</filename> in <filename>/usr/src</filename>
 	      carefully.  You should at least run a <link
 	      linkend="makeworld">make world</link> the first time through
 	      as part of the upgrading process.  Reading the &a.current;
 	      will keep you up-to-date on other bootstrapping procedures
 	      that sometimes become necessary as we move toward the next
 	      release.</para>
 	  </listitem>
 	      
 	  <listitem>
 	    <para>Be active! If you are running &os.current;, we want
 	      to know what you have to say about it, especially if you
 	      have suggestions for enhancements or bug fixes.  Suggestions
 	      with accompanying code are received most
 	      enthusiastically!</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
   
     <sect2 id="stable">
       <title>Staying Stable with &os;</title>
 
       <sect3>
 	<title>What Is &os.stable;?</title>
 	<indexterm><primary>-STABLE</primary></indexterm>
 
 	<para>&os.stable; is our development branch from which major releases
 	  are made.  Changes go into this branch at a different pace, and
 	  with the general assumption that they have first gone into
 	  &os.current; for testing.  This is <emphasis>still</emphasis>
 	  a development branch, however, and this means that at any given time,
 	  the sources for &os.stable; may or may not be suitable for any
 	  particular purpose.  It is simply another engineering development
 	  track, not a resource for end-users.</para>
       </sect3>
 
       <sect3>
 	<title>Who Needs &os.stable;?</title>
 
 	<para>If you are interested in tracking or contributing to the
           FreeBSD development process, especially as it relates to the
 	  next <quote>point</quote> release of FreeBSD, then you should
 	  consider following &os.stable;.</para>
 
 	<para>While it is true that security fixes also go into the
 	  &os.stable; branch, you do not <emphasis>need</emphasis> to
 	  track &os.stable; to do this. Every security advisory for
 	  FreeBSD explains how to fix the problem for the releases it
 	  affects
 	  <footnote><para>That is not quite true.  We can not continue to
   	    support old releases of FreeBSD forever, although we do
   	    support them for many years.  For a complete description
   	    of the current security policy for old releases of
   	    FreeBSD, please see <ulink
   	    url="../../../../security/index.html">http://www.FreeBSD.org/security/</ulink></para>
 	  </footnote>
 	  , and tracking an entire development branch just
 	  for security reasons is likely to bring in a lot of unwanted
 	  changes as well.</para>
 
 	<para>Although we endeavor to ensure that the &os.stable; branch
 	  compiles and runs at all times, this cannot be guaranteed.  In
 	  addition, while code is developed in &os.current; before including
 	  it in &os.stable;, more people run &os.stable; than &os.current;, so
 	  it is inevitable that bugs and corner cases will sometimes be found
 	  in &os.stable; that were not apparent in &os.current;.</para>
 
 	<para>For these reasons, we do <emphasis>not</emphasis> recommend that
 	  you blindly track &os.stable;, and it is particularly important that
 	  you do not update any production servers to &os.stable; without
 	  first thoroughly testing the code in your development
 	  environment.</para>
 
 	<para>If you do not have the resources to do this then we recommend
 	  that you run the most recent release of FreeBSD, and use the binary
 	  update mechanism to move from release to release.</para>
       </sect3>
 
       <sect3>
 	<title>Using &os.stable;</title>
       
 	<indexterm>
 	  <primary>-STABLE</primary>
 	  <secondary>using</secondary>
 	</indexterm>
 	<orderedlist>
 	  <listitem>
 	    <para>Join the &a.stable;.  This will keep you informed of
 	      build-dependencies that may appear in &os.stable;
 	      or any other issues requiring
 	      special attention.  Developers will also make announcements
 	      in this mailing list when they are contemplating some
 	      controversial fix or update, giving the users a chance to
 	      respond if they have any issues to raise concerning the
 	      proposed change.</para>
 
 	    <para>The &a.cvsall; will allow you to see the
 	      commit log entry for each change as it is made along with
 	      any pertinent information on possible side-effects.</para>
 
 	    <para>To join these lists, send mail to &a.majordomo; and
 	      specify the following in the body of your message:</para>
 
 	    <programlisting>subscribe freebsd-stable
 subscribe cvs-all</programlisting>
 
 	    <indexterm>
         <primary><application>Majordomo</application></primary>
       </indexterm>
 	    <para>Optionally, you can also say <literal>help</literal>
 	      and <application>Majordomo</application> will send you full help on how to subscribe
 	      and unsubscribe to the various other mailing lists we
 	      support.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you are installing a new system and want it to be as
 	      stable as possible, you can simply grab the latest dated
 	      branch snapshot from <ulink
 	      url="ftp://releng4.FreeBSD.org/pub/FreeBSD/">ftp://releng4.FreeBSD.org/pub/FreeBSD/</ulink>
 	      and install it like any other release.</para>
 
 	    <para>If you are already running a previous release of &os;
 	      and wish to upgrade via sources then you can easily do so
 	      from <hostid role="fqdn">ftp.FreeBSD.org</hostid>.  This can
 	      be done in one of three ways:</para>
 
 	    <orderedlist>
 	      <indexterm>
 		<primary><command>cvsup</command></primary>
 	      </indexterm>
 	      <indexterm>
 		<primary><command>cron</command></primary>
 	      </indexterm>
 	      <indexterm>
 	        <primary>-STABLE</primary>
 		<secondary>syncing with <application>CVSup</application></secondary>
 	      </indexterm>
 	      <listitem>
 		<para>Use the <link linkend="cvsup">cvsup</link> program
 		  with <ulink
 		  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this
 		  supfile</ulink>.  This is the most recommended
 		  method, since it allows you to grab the entire
 		  collection once and then only what has changed from then
 		  on.  Many people run <command>cvsup</command> from 
 		  <command>cron</command> to keep their
 		  sources up-to-date automatically.  You have to
 		  customize the sample <filename>supfile</filename> above,
 		  and configure <link linkend="cvsup">cvsup</link> for your
 		  environment.  If you want help doing this configuration,
 		  simply type:</para>
 	      
 		<blockquote><screen>&prompt.root; <userinput>pkg_add -f ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages/Latest/cvsupit.tgz</userinput></screen></blockquote>
 	      </listitem>
 
 	      <indexterm>
 	        <primary>-STABLE</primary>
 		<secondary>downloading with FTP</secondary>
 	      </indexterm>
 	      <listitem>
 		<para>Use <command>ftp</command>.  The source tree for
 		  &os.stable; is always <quote>exported</quote> on:
 		  <ulink
 		  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/</ulink>.</para>
 
 		<para>Some of our FTP mirrors may also allow
 		  compressed/tarred grabbing of whole trees.  For example you
 		  see:</para>
 
 		<screen>usr.bin/lex</screen>
 
 		<para>You can do the following to get the whole directory
 		  for you as a tar file:</para>
 
 		<screen><prompt>ftp&gt;</prompt> <userinput>cd usr.bin</userinput>
 <prompt>ftp&gt;</prompt> <userinput>get lex.tar</userinput></screen>
 	      </listitem>
 	      <indexterm>
 	        <primary>-STABLE</primary>
 		<secondary>syncing with CTM</secondary>
 	      </indexterm>
 	      <listitem>
 		<para>Use the <application><link
 		  linkend="ctm">CTM</link></application> facility.  If
 		  you do not have a fast and inexpensive connection to
 		  the Internet, this is the method you should consider
 		  using.
 		  </para>
 	      </listitem>
 	   </orderedlist>
 	 </listitem>
 
 	  <listitem>
 	    <para>Essentially, if you need rapid on-demand access to the
 	      source and communications bandwidth is not a consideration,
 	      use <command>cvsup</command> or <command>ftp</command>.
 	      Otherwise, use <application>CTM</application>.</para>
 	  </listitem>
 
 	  <indexterm>
 	    <primary>-STABLE</primary>
 	    <secondary>compiling</secondary>
 	  </indexterm>
 	  <listitem>
 	    <para>Before compiling &os.stable;, read the
 	    <filename>Makefile</filename> in <filename>/usr/src</filename>
 	    carefully.  You should at least run a <link
 	    linkend="makeworld">make world</link> the first time through
 	    as part of the upgrading process.  Reading the &a.stable; will
 	    keep you up-to-date on other bootstrapping procedures that
 	    sometimes become necessary as we move toward the next
 	    release.</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="synching">
     <title>Synchronizing Your Source</title>
     
     <para>There are various ways of using an Internet (or email)
       connection to stay up-to-date with any given area of the &os;
       project sources, or all areas, depending on what interests you.  The
       primary services we offer are <link linkend="anoncvs">Anonymous
       CVS</link>, <link linkend="cvsup">CVSup</link>, and <link
       linkend="ctm">CTM</link>.</para>
 
     <warning>
       <para>While it is possible to update only parts of your source tree,
         the only supported update procedure is to update the entire tree
         and recompile both userland (i.e., all the programs that run in
         user space, such as those in <filename>/bin</filename> and
         <filename>/sbin</filename>) and kernel sources.  Updating only part
         of your source tree, only the kernel, or only userland will often
         result in problems.  These problems may range from compile errors
         to kernel panics or data corruption.</para>
     </warning>
 
     <indexterm><primary>anonymous CVS</primary></indexterm>
     <para><application>Anonymous CVS</application> and
       <application>CVSup</application> use the <emphasis>pull</emphasis>
       model of updating sources.  In the case of
       <application>CVSup</application> the user (or a 
       <command>cron</command> script) invokes
       the <command>cvsup</command> program, and it interacts with a
       <command>cvsupd</command> server somewhere to bring your files
       up-to-date.  The updates you receive are up-to-the-minute and you
       get them when, and only when, you want them.  You can easily
       restrict your updates to the specific files or directories that are
       of interest to you.  Updates are generated on the fly by the server,
       according to what you have and what you want to have.
       <application>Anonymous CVS</application> is quite a bit more
       simplistic than <application>CVSup</application> in that it is just an extension to
       <application>CVS</application> which allows it to pull changes
       directly from a remote CVS repository.
       <application>CVSup</application> can do this far more efficiently,
       but <application>Anonymous CVS</application> is easier to
       use.</para>
 
     <indexterm>
       <primary><application>CTM</application></primary>
     </indexterm>
     <para><application>CTM</application>, on the other hand, does not
       interactively compare the sources you have with those on the master
       archive or otherwise pull them across.  Instead, a script which
       identifies changes in files since its previous run is executed
       several times a day on the master CTM machine, any detected changes
       being compressed, stamped with a sequence-number and encoded for
       transmission over email (in printable ASCII only).  Once received,
       these <quote>CTM deltas</quote> can then be handed to the
       &man.ctm.rmail.1; utility which will automatically decode, verify
       and apply the changes to the user's copy of the sources.  This
       process is far more efficient than <application>CVSup</application>,
       and places less strain on our server resources since it is a
       <emphasis>push</emphasis> rather than a <emphasis>pull</emphasis>
       model.</para>
 
     <para>There are other trade-offs, of course.  If you inadvertently
       wipe out portions of your archive, <application>CVSup</application>
       will detect and rebuild the damaged portions for you.
       <application>CTM</application> will not do this, and if you wipe some
       portion of your source tree out (and do not have it backed up) then
       you will have to start from scratch (from the most recent CVS
       <quote>base delta</quote>) and rebuild it all with <application>CTM</application> or, with
       <application>Anonymous CVS</application>, simply delete the bad bits and resync.</para>
   </sect1>
 
   <sect1 id="makeworld">
     <title>Using <command>make world</command></title>
 
     <indexterm>
       <primary><command>make world</command></primary>
     </indexterm>
     <para>Once you have synchronized your local source tree against a
       particular version of &os; (&os.stable;, &os.current;, and so on)
       you can then use the source
       tree to rebuild the system.</para>
 
     <warning>
       <title>Take a Backup</title>
 
       <para>It cannot be stressed enough how important it is to take a
 	backup of your system <emphasis>before</emphasis> you do this.
 	While rebuilding the world is (as long as you follow these
 	instructions) an easy task to do, there will inevitably be times
 	when you make mistakes, or when mistakes made by others in the
 	source tree render your system unbootable.</para>
 
       <para>Make sure you have taken a backup.  And have a fixit floppy to
 	hand.  You will probably never have to use it, but it is better to be
 	safe than sorry!</para>
     </warning>
 
     <warning>
       <title>Subscribe to the Right Mailing List</title>
 
       <indexterm><primary>mailing list</primary></indexterm>
       <para>The &os.stable; and &os.current; branches are, by their
 	nature, <emphasis>in development</emphasis>.  People that
 	contribute to &os; are human, and mistakes occasionally
 	happen.</para>
 
       <para>Sometimes these mistakes can be quite harmless, just causing
 	your system to print a new diagnostic warning.  Or the change may
 	be catastrophic, and render your system unbootable or destroy your
 	file systems (or worse).</para>
 
       <para>If problems like these occur, a <quote>heads up</quote> is
         posted to the appropriate mailing list, explaining the nature of
 	the problem and which systems it affects.  And an <quote>all
 	clear</quote> announcement is posted when the problem has been
 	solved.</para>
 
       <para>If you try to track &os.stable; or &os.current; and do
 	not read the &a.stable; or the
 	&a.current; respectively, then you are
 	asking for trouble.</para>
     </warning>
 
     <sect2>
       <title>Read <filename>/usr/src/UPDATING</filename></title>
 
       <para>Before you do anything else, read
 	<filename>/usr/src/UPDATING</filename> (or the equivalent file
 	wherever you have a copy of the source code).  This file should
 	contain important information about problems you might encounter, or
 	specify the order in which you might have to run certain commands.
 	If <filename>UPDATING</filename> contradicts something you read here,
 	<filename>UPDATING</filename> takes precedence.</para>
 
       <important>
 	<para>Reading <filename>UPDATING</filename> is not an acceptable
 	  substitute for subscribing to the correct mailing list, as described 
 	  previously.  The two requirements are complementary, not
 	  exclusive.</para>
       </important>
     </sect2>
 
     <sect2>
       <title>Check <filename>/etc/make.conf</filename></title>
       <indexterm>
         <primary><filename>make.conf</filename></primary>
       </indexterm>
 
       <para>Examine the files
 	<filename>/etc/defaults/make.conf</filename> and
 	<filename>/etc/make.conf</filename>.  The first contains some
 	default defines &ndash; most of which are commented out.  To
 	make use of them when you rebuild your system from source, add
 	them to <filename>/etc/make.conf</filename>.  Keep in mind that
 	anything you add to <filename>/etc/make.conf</filename> is also
 	used every time you run <command>make</command>, so it is a good
 	idea to set them to something sensible for your system.</para>
 
       <para>A typical user will probably want to copy the
 	<makevar>CFLAGS</makevar> and
 	<makevar>NOPROFILE</makevar> lines found in
 	<filename>/etc/defaults/make.conf</filename> to
 	<filename>/etc/make.conf</filename> and uncomment them.</para>
 
       <para>Examine the other definitions (<makevar>COPTFLAGS</makevar>, 
 	<makevar>NOPORTDOCS</makevar> and so
 	on) and decide if they are relevant to you.</para>
     </sect2>
 
     <sect2>
       <title>Update the files in <filename>/etc</filename></title>
 
       <para>The <filename>/etc</filename> directory contains a large part
 	of your system's configuration information, as well as scripts
 	that are run at system startup.  Some of these scripts change from
 	version to version of FreeBSD.</para>
 
       <para>Some of the configuration files are also used in the day to
 	day running of the system.  In particular,
 	<filename>/etc/group</filename>.</para>
 
       <para>There have been occasions when the installation part of
         <quote>make world</quote> has expected certain usernames or groups
 	to exist.  When performing an upgrade it is likely that these
 	users or groups did not exist. This caused problems when upgrading.</para>
 
       <para>A recent example of this is when the
 	<username>smmsp</username> user was added.  Users had the
 	installation process fail for them when
 	&man.mtree.8; was trying to create
 	<filename>/var/spool/clientmqueue</filename>.</para>
 
       <para>The solution is to examine
 	<filename>/usr/src/etc/group</filename> and compare its list of
 	groups with your own.  If there are any groups in the new file that
 	are not in your file then copy them over.  Similarly, you should
 	rename any groups in <filename>/etc/group</filename> which have
 	the same GID but a different name to those in
 	<filename>/usr/src/etc/group</filename>.</para>
 
       <para>Since 4.6-RELEASE you can run &man.mergemaster.8; in
 	pre-buildworld mode by providing the <option>-p</option> option.
 	This will compare only those files that are essential for the success
 	of <maketarget>buildworld</maketarget> or
 	<maketarget>installworld</maketarget>.  If your old version of
 	<command>mergemaster</command> does not support <option>-p</option>,
 	use the new version in the source tree when running for the first
 	time:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/mergemaster</userinput>
 &prompt.root; <userinput>./mergemaster.sh -p</userinput></screen>
 
       <tip>
 	<para>If you are feeling particularly paranoid, you can check your
 	  system to see which files are owned by the group you are
 	  renaming or deleting:</para>
 
 	<screen>&prompt.root; <userinput>find / -group <replaceable>GID</replaceable> -print</userinput></screen>
 
 	<para>will show all files owned by group
 	  <replaceable>GID</replaceable> (which can be either a group name
 	  or a numeric group ID).</para>
       </tip>
     </sect2>
 
     <sect2 id="makeworld-singleuser">
       <title>Drop to Single User Mode</title>
       <indexterm><primary>single-user mode</primary></indexterm>
 
       <para>You may want to compile the system in single user mode.  Apart
 	from the obvious benefit of making things go slightly faster,
 	reinstalling the system will touch a lot of important system
 	files, all the standard system binaries, libraries, include files
 	and so on.  Changing these on a running system (particularly if
 	you have active users on the system at the time) is asking for
 	trouble.</para>
 
       <indexterm><primary>multi-user mode</primary></indexterm>
       <para>Another method is to compile the system in multi-user mode, and
         then drop into single user mode for the installation.  If you would
         like to do it this way, simply hold off on the following steps until
         the build has completed.  You can postpone dropping to single user
 	mode until you have to <maketarget>installkernel</maketarget> or
 	<maketarget>installworld</maketarget>.</para>
 
       <para>As the superuser, you can execute:</para>
 
       <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
 
       <para>from a running system, which will drop it to single user
 	mode.</para>
 
       <para>Alternatively, reboot the system, and at the boot prompt,
         enter the <option>-s</option> flag.  The system will then boot
 	single user.  At the shell prompt you should then run:</para>
 
       <screen>&prompt.root; <userinput>fsck -p</userinput>
 &prompt.root; <userinput>mount -u /</userinput>
 &prompt.root; <userinput>mount -a -t ufs</userinput>
 &prompt.root; <userinput>swapon -a</userinput></screen>
 
       <para>This checks the file systems, remounts <filename>/</filename>
 	read/write, mounts all the other UFS file systems referenced in
 	<filename>/etc/fstab</filename> and then turns swapping on.</para>
 
 
         <note>
           <para>If your CMOS clock is set to local time and not to GMT
 	    (this is true if the output of the &man.date.1; command
 	    does not show the correct time and zone),
             you may also need to run the following command:</para>
 <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
 
           <para>This will make sure that your local timezone settings
             get set up correctly &mdash; without this, you may later run into some
             problems.
           </para>
         </note>
 
     </sect2>
 
     <sect2>
       <title>Remove <filename>/usr/obj</filename></title>
 
       <para>As parts of the system are rebuilt they are placed in
 	directories which (by default) go under
 	<filename>/usr/obj</filename>.  The directories shadow those under
 	<filename>/usr/src</filename>.</para>
 
       <para>You can speed up the <quote>make world</quote> process, and
 	possibly save yourself some dependency headaches by removing this
 	directory as well.</para>
 
       <para>Some files below <filename>/usr/obj</filename> may have the
 	immutable flag set (see &man.chflags.1; for more information)
 	which must be removed first.</para>
 
       <screen>&prompt.root; <userinput>cd /usr/obj</userinput>
 &prompt.root; <userinput>chflags -R noschg *</userinput>
 &prompt.root; <userinput>rm -rf *</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Recompile the Source</title>
 
       <sect3>
 	<title>Saving the Output</title>
 
 	<para>It is a good idea to save the output you get from running
 	  &man.make.1; to another file.  If something goes wrong you will
 	  have a copy of the error message.  While this might not help you
 	  in diagnosing what has gone wrong, it can help others if you post
 	  your problem to one of the &os; mailing lists.</para>
 
 	<para>The easiest way to do this is to use the &man.script.1;
 	  command, with a parameter that specifies the name of the file to
 	  save all output to.  You would do this immediately before
 	  rebuilding the world, and then type <userinput>exit</userinput>
 	  when the process has finished.</para>
 
 	<screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput>
 Script started, output file is /var/tmp/mw.out	 
 &prompt.root; <userinput>make TARGET</userinput>
 <emphasis>&hellip; compile, compile, compile &hellip;</emphasis>	  
 &prompt.root; <userinput>exit</userinput>
 Script done, &hellip;</screen>
 
 	<para>If you do this, <emphasis>do not</emphasis> save the output
 	  in <filename>/tmp</filename>.  This directory may be cleared
 	  next time you reboot.  A better place to store it is in
 	  <filename>/var/tmp</filename> (as in the previous example) or
 	  in <username>root</username>'s home directory.</para>
       </sect3>
 
       <sect3 id="make-buildworld">
 	<title>Compile and Install the Base System</title>
 
 	<para>You must be in the <filename>/usr/src</filename>
 	  directory:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
 
 	<para>(unless, of course, your source code is elsewhere, in which
 	  case change to that directory instead).</para>
 	<indexterm><primary><command>make</command></primary></indexterm>
 
 	<para>To rebuild the world you use the &man.make.1; command.  This
           command reads instructions from the <filename>Makefile</filename>,
           which describes how the programs that comprise &os; should be
           rebuilt, the order in which they should be built, and so on.</para>
 
 	<para>The general format of the command line you will type is as
 	  follows:</para>
 
 	<screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>
 
 	<para>In this example, <option>-<replaceable>x</replaceable></option>
 	  is an option that you would pass to &man.make.1;.  See the
 	  &man.make.1; manual page for an example of the options you can
 	  pass.</para>
 
 	<para><option>-D<replaceable>VARIABLE</replaceable></option>
 	  passes a variable to the <filename>Makefile</filename>.  The
 	  behavior of the <filename>Makefile</filename> is controlled by
 	  these variables.  These are the same variables as are set in
 	  <filename>/etc/make.conf</filename>, and this provides another
 	  way of setting them.</para>
 
 	<screen>&prompt.root; <userinput>make -DNOPROFILE <replaceable>target</replaceable></userinput></screen>
 
 	<para>is another way of specifying that profiled libraries should
 	  not be built, and corresponds with the</para>
 
 	<programlisting>NOPROFILE=    true 	#    Avoid compiling profiled libraries</programlisting>
 
 	<para>line in <filename>/etc/make.conf</filename>.</para>
 
 	<para><replaceable>target</replaceable> tells &man.make.1; what
 	  you want to do.  Each <filename>Makefile</filename> defines a
 	  number of different <quote>targets</quote>, and your choice of
 	  target determines what happens.</para>
 
 	<para>Some targets are listed in the
 	  <filename>Makefile</filename>, but are not meant for you to run.
 	  Instead, they are used by the build process to break out the
 	  steps necessary to rebuild the system into a number of
 	  sub-steps.</para>
 
 	<para>Most of the time you will not need to pass any parameters to
 	    &man.make.1;, and so your command like will look like
 	    this:</para>
 
 	<screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen>
 
 	<para>Beginning with version 2.2.5 of &os; (actually, it was
 	  first created on the &os.current; branch, and then retrofitted to
 	  &os.stable; midway between 2.2.2 and 2.2.5) the
 	  <maketarget>world</maketarget> target has been split in
 	  two: <maketarget>buildworld</maketarget> and
 	  <maketarget>installworld</maketarget>.</para>
 
 	<para>As the names imply, <maketarget>buildworld</maketarget>
 	  builds a complete new tree under <filename>/usr/obj</filename>,
 	  and <maketarget>installworld</maketarget> installs this tree on
 	  the current machine.</para>
 
 	<para>This is very useful for 2 reasons.  First, it allows you
 	  to do the build safe in the knowledge that no components of
 	  your running system will be affected.  The build is
 	  <quote>self hosted</quote>.  Because of this, you can safely
 	  run <maketarget>buildworld</maketarget> on a machine running
 	  in multi-user mode with no fear of ill-effects.  It is still
 	  recommended that you run the
 	  <maketarget>installworld</maketarget> part in single user
 	  mode, though.</para>
 
 	<para>Secondly, it allows you to use NFS mounts to upgrade 
 	  multiple machines on your network.  If you have three machines,
 	  <hostid>A</hostid>, <hostid>B</hostid> and <hostid>C</hostid> that you want to upgrade, run <command>make
 	  buildworld</command> and <command>make installworld</command> on
 	  <hostid>A</hostid>.  <hostid>B</hostid> and <hostid>C</hostid> should then NFS mount <filename>/usr/src</filename>
 	  and <filename>/usr/obj</filename> from <hostid>A</hostid>, and you can then run
 	  <command>make installworld</command> to install the results of 
 	  the build on <hostid>B</hostid> and <hostid>C</hostid>.</para>
 
 	<para>Although the <maketarget>world</maketarget> target still exists,
 	  you are strongly encouraged not to use it.</para>
 
 	<para>Run</para>
 
 	<screen>&prompt.root; <userinput>make buildworld</userinput></screen>
  
         <para>It is now possible to specify a <option>-j</option> option to
           <command>make</command> which will cause it to spawn several
           simultaneous processes.  This is most useful on multi-CPU machines.
           However, since much of the compiling process is IO bound rather
           than CPU bound it is also useful on single CPU machines.</para>
 
 	<para>On a typical single-CPU machine you would run:</para>
 	  
 	  <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
 
 	<para>&man.make.1; will then have up to 4 processes running at any one
 	  time.  Empirical evidence posted to the mailing lists shows this
 	  generally gives the best performance benefit.</para>
 
 	<para>If you have a multi-CPU machine and you are using an SMP
 	  configured kernel try values between 6 and 10 and see how they speed
 	  things up.</para>
 
 	<para>Be aware that this is still somewhat experimental, and commits
 	  to the source tree may occasionally break this feature.  If the
 	  world fails to compile using this parameter try again without it
 	  before you report any problems.</para>
       </sect3>
       
       <sect3>
 	<title>Timings</title>
 	<indexterm>
 	  <primary><command>make world</command></primary>
 	  <secondary>timings</secondary>
 	</indexterm>
 
         <para>Many factors influence the build time, but currently a 500&nbsp;MHz
           Pentium&nbsp;III with 128&nbsp;MB of RAM takes about 2&nbsp;hours to build
           the &os.stable; tree, with no tricks or shortcuts used during the
           process.  A &os.current; tree will take somewhat longer.</para>
       </sect3>
     </sect2>
     
     <sect2>
       <title>Compile and Install a New Kernel</title>
       <indexterm>
         <primary>kernel</primary>
 	<secondary>compiling</secondary>
       </indexterm>
 
       <para>To take full advantage of your new system you should recompile the
 	kernel.  This is practically a necessity, as certain memory structures
 	may have changed, and programs like &man.ps.1; and &man.top.1; will
 	fail to work until the kernel and source code versions are the
 	same.</para>
 
       <para>The simplest, safest way to do this is to build and install a
 	kernel based on <filename>GENERIC</filename>.  While
 	<filename>GENERIC</filename> may not have all the necessary devices
 	for your system, it should contain everything necessary to boot your
 	system back to single user mode.  This is a good test that the new
 	system works properly.  After booting from
 	<filename>GENERIC</filename> and verifying that your system works you
 	can then build a new kernel based on your normal kernel	configuration
 	file.</para>
 
       <para>If you are upgrading to &os; 4.0 or above then the old
 	kernel build procedure (as described in <xref linkend="kernelconfig">)
 	is deprecated.  Instead, you should run these commands
 	<emphasis>after</emphasis> you have <link
         linkend="make-buildworld">built the world with
         <maketarget>buildworld</maketarget></link>.</para>
 
       <note><para>If you want to build a custom kernel, and already have a configuration
 	file, just use <literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal>
 	like this:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput>
 &prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
 
 	<para>In FreeBSD&nbsp;4.2 and older you must replace
 	  <literal>KERNCONF=</literal> with <literal>KERNEL=</literal>.
 	  4.2-STABLE that was fetched after Feb 2nd, 2001 does
 	  recognize <literal>KERNCONF=</literal>.</para>
       </note>
 
       <para>Note that if you have raised <literal>kern.securelevel</literal>
 	above 1 <emphasis>and</emphasis> you have set either the
 	<literal>noschg</literal> or similar flags to your kernel binary, you
 	might find it necessary to drop into single user mode to use
 	<maketarget>installkernel</maketarget>.  Otherwise you should be able
 	to run both these commands from multi user mode without
 	problems.  See &man.init.8; for details about
 	<literal>kern.securelevel</literal> and &man.chflags.1; for details
 	about the various file flags.</para>
       <para>If you are upgrading to a version of &os; below 4.0 you should
 	use the old kernel build procedure.  However, it is recommended
 	that you use the new version of &man.config.8;, using a command line
 	like this.</para>
       
       <screen>&prompt.root; <userinput>/usr/obj/usr/src/usr.sbin/config/config <replaceable>KERNELNAME</replaceable></userinput></screen>
     </sect2>
 
     <sect2>
       <title>Reboot into Single User Mode</title>
       <indexterm><primary>single-user mode</primary></indexterm>
 
       <para>You should reboot into single user mode to test the new kernel
 	works.  Do this by following the instructions in
 	<xref linkend="makeworld-singleuser">.</para>
     </sect2>
 
     <sect2>
       <title>Install the New System Binaries</title>
 
       <para>If you were building a version of &os; recent enough to have
 	used <command>make buildworld</command> then you should now use
 	<maketarget>installworld</maketarget> to install the new system
 	binaries.</para>
 
       <para>Run</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make installworld</userinput></screen>
 
       <note>
 	<para>If you specified variables on the <command>make
 	    buildworld</command> command line, you must specify the same
 	  variables in the <command>make installworld</command> command
 	  line.  This does not necessarily hold true for other options;
 	  for example, <option>-j</option> must never be used with
 	  <maketarget>installworld</maketarget>.</para>
 	
 	<para>For example, if you ran:</para>
 
 	<screen>&prompt.root; <userinput>make -DNOPROFILE buildworld</userinput></screen>
 
 	<para>you must install the results with:</para>
 
 	<screen>&prompt.root; <userinput>make -DNOPROFILE installworld</userinput></screen>
 
 	<para>otherwise it would try to install profiled libraries that
 	  had not been built during the <command>make buildworld</command>
 	  phase.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Update Files Not Updated by <command>make world</command></title>
       
       <para>Remaking the world will not update certain directories (in
 	particular, <filename>/etc</filename>, <filename>/var</filename> and
 	<filename>/usr</filename>) with new or changed configuration files.</para>
 
       <para>The simplest way to update these files is to use
         &man.mergemaster.8;, though it is possible to do it manually
         if you would prefer to do that.  Regardless of which way you
 	choose, be sure to make a backup of <filename>/etc</filename> in
 	case anything goes wrong.</para>
 
     <sect3 id="mergemaster">
       <sect3info>
 	<authorgroup>
 	  <author>
 	    <firstname>Tom</firstname>
 	    <surname>Rhodes</surname>
 	    <contrib>Contributed by </contrib>
 	  </author>
 	</authorgroup>
       </sect3info>
       <title><command>mergemaster</command></title>
         <indexterm><primary><command>mergemaster</command></primary></indexterm>
 
       <para>The &man.mergemaster.8; utility is a Bourne script that will
         aid you in determining the differences between your configuration files
         in <filename>/etc</filename>, and the configuration files in
         the source tree <filename>/usr/src/etc</filename>. This is
         the recommended solution for keeping the system configuration files up to date
         with those located in the source tree.</para>
 
       <para><command>mergemaster</command> was integrated into the FreeBSD base
         system between 3.3-RELEASE and 3.4-RELEASE, which means it is
         present in all -STABLE and -CURRENT systems since 3.3.</para>
 
       <para>To begin simply type <command>mergemaster</command> at your prompt, and
         watch it start going.  <command>mergemaster</command> will then build a
         temporary root environment, from <filename>/</filename> down, and populate
         it with various system configuration files.  Those files are then compared
         to the ones currently installed in your system.  At this point, files that
         differ will be shown in &man.diff.1; format, with the <option>+</option> sign
         representing added or modified lines, and <option>-</option> representing
         lines that will be either removed completely, or replaced with a new line.
         See the &man.diff.1; manual page for more information about the &man.diff.1;
         syntax and how file differences are shown.</para>
 
       <para>&man.mergemaster.8; will then show you each file that displays variances,
         and at this point you will have the option of either deleting the new file (referred
         to as the temporary file), installing the temporary file in its unmodified state,
         merging the temporary file with the currently installed file, or viewing the
         &man.diff.1; results again.</para>
 
       <para>Choosing to delete the temporary file will tell &man.mergemaster.8; that we
         wish to keep our current file unchanged, and to delete the new version.
         This option is not recommended, unless you see no
         reason to change the current file.  You can get help at any time by
         typing <keycap>?</keycap> at the &man.mergemaster.8; prompt.  If the user
         chooses to skip a file, it will be presented again after all other files
         have been dealt with.</para>
 
       <para>Choosing to install the unmodified temporary file will replace the
         current file with the new one.  For most unmodified files, this is the best
         option.</para>
 
       <para>Choosing to merge the file will present you with a text editor,
         and the contents of both files.  You can now merge them by
         reviewing both files side by side on the screen, and choosing parts from
         both to create a finished product.  When the files are compared side by side,
         the <keycap>l</keycap> key will select the left contents and the
         <keycap>r</keycap> key will select contents from your right.
         The final output will be a file consisting of both parts, which can then be
         installed.  This option is customarily used for files where settings have been
         modified by the user.</para>
 
       <para>Choosing to view the &man.diff.1; results again will show you the file differences
         just like &man.mergemaster.8; did before prompting you for an option.</para>
 
       <para>After &man.mergemaster.8; is done with the system files you will be
         prompted for other options.  &man.mergemaster.8; may ask if you want to rebuild
         the password file and/or run &man.MAKEDEV.8; if you run a FreeBSD version prior to 5.0, and will finish up with an option to
         remove left-over temporary files.</para>
       </sect3>
 
       <sect3>
 	<title>Manual Update</title>
 
       <para>If you wish to do the update manually, however,
         you cannot just copy over the files from
 	<filename>/usr/src/etc</filename> to <filename>/etc</filename> and
 	have it work.  Some of these files must be <quote>installed</quote>
 	first.  This is because the <filename>/usr/src/etc</filename>
 	directory <emphasis>is not</emphasis> a copy of what your
 	<filename>/etc</filename> directory should look like.  In addition,
 	there are files that should be in <filename>/etc</filename> that are
 	not in <filename>/usr/src/etc</filename>.</para>
 
       <para>If you are using &man.mergemaster.8; (as recommended),
         you can skip forward to the <link linkend="update-dev">next
 	section</link>.</para>
 
       <para>The simplest way to do this by hand is to install the
 	files into a new directory, and then work through them looking
 	for differences.</para>
     
       <warning>
 	<title>Backup Your Existing <filename>/etc</filename></title>
 
 	<para>Although, in theory, nothing is going to touch this directory
 	  automatically, it is always better to be sure.  So copy your
 	  existing <filename>/etc</filename> directory somewhere safe.
 	  Something like:</para>
 
 	<screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
 
 	<para><option>-R</option> does a recursive copy, <option>-p</option>
 	  preserves times, ownerships on files and suchlike.</para>
       </warning>
       
       <para>You need to build a dummy set of directories to install the new
 	<filename>/etc</filename> and other files into.
 	<filename>/var/tmp/root</filename> is a reasonable choice, and
 	there are a number of subdirectories required under this as
 	well.</para>
 
       <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput>
 &prompt.root; <userinput>cd /usr/src/etc</userinput>
 &prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen>
 
       <para>This will build the necessary directory structure and install the
 	files.  A lot of the subdirectories that have been created under
 	<filename>/var/tmp/root</filename> are empty and should be deleted.
 	The simplest way to do this is to:</para>
       
       <screen>&prompt.root; <userinput>cd /var/tmp/root</userinput>
 &prompt.root; <userinput>find -d . -type d | xargs rmdir 2&gt;/dev/null</userinput></screen>
       
       <para>This will remove all empty directories.  (Standard error is
         redirected to <filename>/dev/null</filename> to prevent the warnings
         about the directories that are not empty.)</para>
 
       <para><filename>/var/tmp/root</filename> now contains all the files that
 	should be placed in appropriate locations below
 	<filename>/</filename>.  You now have to go through each of these
 	files, determining how they differ with your existing files.</para>
     
       <para>Note that some of the files that will have been installed in
 	<filename>/var/tmp/root</filename> have a leading <quote>.</quote>.  At the
 	time of writing the only files like this are shell startup files in
 	<filename>/var/tmp/root/</filename> and
 	<filename>/var/tmp/root/root/</filename>, although there may be others
 	(depending on when you are reading this).  Make sure you use
 	<command>ls -a</command> to catch them.</para>
     
       <para>The simplest way to do this is to use &man.diff.1; to compare the
 	two files:</para>
     
       <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen>
       
       <para>This will show you the differences between your
 	<filename>/etc/shells</filename> file and the new
 	<filename>/var/tmp/root/etc/shells</filename> file.  Use these to decide whether to
 	merge in changes that you have made or whether to copy over your old
 	file.</para>
     
       <tip>
 	<title>Name the New Root Directory
 	  (<filename>/var/tmp/root</filename>) with a Time Stamp, So You Can
 	  Easily Compare Differences Between Versions</title>
 
 	<para>Frequently rebuilding the world means that you have to update
 	<filename>/etc</filename> frequently as well, which can be a bit of
 	  a chore.</para>
 
 	<para>You can speed this process up by keeping a copy of the last set
 	  of changed files that you merged into <filename>/etc</filename>.
 	  The following procedure gives one idea of how to do this.</para>
 
 	<procedure>
 	  <step>
 	    <para>Make the world as normal.  When you want to update
 	      <filename>/etc</filename> and the other directories, give the
 	      target directory a name based on the current date.  If you were
 	      doing this on the 14th of February 1998 you could do the
 	      following:</para>
 	  
 	    <screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput>
 &prompt.root; <userinput>cd /usr/src/etc</userinput>
 &prompt.root; <userinput>make DESTDIR=/var/tmp/root-19980214 \
     distrib-dirs distribution</userinput></screen>
 	  </step>
 	  
 	  <step>
 	    <para>Merge in the changes from this directory as outlined
 	      above.</para>
 	    
 	    <para><emphasis>Do not</emphasis> remove the
 	      <filename>/var/tmp/root-19980214</filename> directory when you
 	      have finished.</para>
 	  </step>
 	  
 	  <step>
 	    <para>When you have downloaded the latest version of the source
 	      and remade it, follow step 1.  This will give you a new
 	      directory, which might be called
 	      <filename>/var/tmp/root-19980221</filename> (if you wait a week
 	      between doing updates).</para>
 	  </step>
 	  
 	  <step>
 	    <para>You can now see the differences that have been made in the
 	      intervening week using &man.diff.1; to create a recursive diff
 	      between the two directories:</para>
 	      
 	    <screen>&prompt.root; <userinput>cd /var/tmp</userinput>
 &prompt.root; <userinput>diff -r root-19980214 root-19980221</userinput></screen>
 	  
 	    <para>Typically, this will be a much smaller set of differences
 	      than those between
 	      <filename>/var/tmp/root-19980221/etc</filename> and
 	      <filename>/etc</filename>.  Because the set of differences is
 	      smaller, it is easier to migrate those changes across into your
 	      <filename>/etc</filename> directory.</para>
 	  </step>
 	  
 	  <step>
 	    <para>You can now remove the older of the two
 	      <filename>/var/tmp/root-*</filename> directories:</para>
 	      
 	    <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen>
 	  </step>
 	  
 	  <step>
 	    <para>Repeat this process every time you need to merge in changes
 	      to <filename>/etc</filename>.</para>
 	  </step>
 	</procedure>
 
 	<para>You can use &man.date.1; to automate the generation of the
 	  directory names:</para>
 	  
 	<screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
       </tip>
       </sect3>
     </sect2>
   
     <sect2 id="update-dev">
       <title>Update <filename>/dev</filename></title>
       
       <note>
         <indexterm><primary>DEVFS</primary></indexterm>
 	<para>If you are running FreeBSD&nbsp;5.0 or later you can safely
 	  skip this section.  These versions use &man.devfs.5; to
 	  allocate device nodes transparently for the user.</para>
       </note>
 
       <para>In most cases, the &man.mergemaster.8; tool will realize when
         it is necessary to update the device nodes, and offer to complete it
         automatically.  These instructions tell how to update the device
         nodes manually.</para>
       
       <para>For safety's sake, this is a multi-step process.</para>
 
       <procedure>
 	<step>
 	  <para>Copy <filename>/var/tmp/root/dev/MAKEDEV</filename> to
 	    <filename>/dev</filename>:</para>
 
 	  <screen>&prompt.root; <userinput>cp /var/tmp/root/dev/MAKEDEV /dev</userinput></screen>
 	  <indexterm>
 	    <primary><filename>MAKEDEV</filename></primary>
 	  </indexterm>
 
           <para>If you used &man.mergemaster.8; to
             update <filename>/etc</filename>, then your
             <filename>MAKEDEV</filename> script should have been updated
             already, though it cannot hurt to check (with &man.diff.1;)
             and copy it manually if necessary.</para>
 	</step>
 
 	<step>
 	  <para>Now, take a snapshot of your current
 	    <filename>/dev</filename>.  This snapshot needs to contain the
 	    permissions, ownerships, major and minor numbers of each filename,
 	    but it should not contain the time stamps.  The easiest way to do
 	    this is to use &man.awk.1; to strip out some of the
 	    information:</para>
 
 	  <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.out</userinput></screen>
 	</step>
 
 	<step>
 	  <para>Remake all the device nodes:</para>
 	    
 	    <screen>&prompt.root; <userinput>sh MAKEDEV all</userinput></screen>
 	</step>
 
 	<step>
 	  <para>Write another snapshot of the directory, this time to
 	    <filename>/var/tmp/dev2.out</filename>.  Now look through these
 	    two files for any device node that you missed creating.  There should
 	    not be any, but it is better to be safe than sorry.</para>
 
 	  <screen>&prompt.root; <userinput>diff /var/tmp/dev.out /var/tmp/dev2.out</userinput></screen>
 
 	  <para>You are most likely to notice disk slice discrepancies which
 	    will involve commands such as:</para>
 	  
 	    <screen>&prompt.root; <userinput>sh MAKEDEV sd0s1</userinput></screen>
 
 	  <para>to recreate the slice entries.  Your precise circumstances may
 	    vary.</para>
 	</step>
       </procedure>
     </sect2>
     
     <sect2>
       <title>Update <filename>/stand</filename></title>
       
       <note>
 	<para>This step is included only for completeness.  It can safely be
 	  omitted.</para>
       </note>
       
       <para>For the sake of completeness, you may want to update the files in
 	<filename>/stand</filename> as well.  These files consist of hard
 	links to the <filename>/stand/sysinstall</filename> binary.  This
 	binary should be statically linked, so that it can work when no other
 	file systems (and in particular <filename>/usr</filename>) have been
 	mounted.</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src/release/sysinstall</userinput>
 &prompt.root; <userinput>make all install</userinput></screen>
     </sect2>
     
     <sect2>
       <title>Rebooting</title>
       
       <para>You are now done.  After you have verified that everything appears
 	to be in the right place you can reboot the system.  A simple
 	&man.fastboot.8; should do it:</para>
 
       <screen>&prompt.root; <userinput>fastboot</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Finished</title>
       
       <para>You should now have successfully upgraded your &os; system.
 	Congratulations.</para>
       
       <para>If things went slightly wrong, it is easy to rebuild a particular
         piece of the system.  For example, if you accidentally deleted
         <filename>/etc/magic</filename> as part of the upgrade or merge of
         <filename>/etc</filename>, the &man.file.1; command will stop working.
         In this case, the fix would be to run:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
 &prompt.root; <userinput>make all install</userinput></screen>
     </sect2>    
     
     <sect2>
       <title>Questions</title>
 
       <qandaset>
 	<qandaentry>
 	  <question>
 	    <para>Do I need to re-make the world for every change?</para>
 	  </question>
 
 	  <answer>
             <para>There is no easy answer to this one, as it depends on the
 	      nature of the change.  For example, if you just ran <application>CVSup</application>, and
 	      it has shown the following files as being updated:</para>
       
 	    <screen><filename>src/games/cribbage/instr.c</filename>
 <filename>src/games/sail/pl_main.c</filename>
 <filename>src/release/sysinstall/config.c</filename>
 <filename>src/release/sysinstall/media.c</filename>
 <filename>src/share/mk/bsd.port.mk</filename></screen>
 
 	    <para>it probably is not worth rebuilding the entire world.
 	      You could just go to the appropriate sub-directories and
 	      <command>make all install</command>, and that's about it.  But
 	      if something major changed, for example
 	      <filename>src/lib/libc/stdlib</filename> then you should either
 	      re-make the world, or at least those parts of it that are
 	      statically linked (as well as anything else you might have added
 	      that is statically linked).</para>
       
 	    <para>At the end of the day, it is your call.  You might be happy
 	      re-making the world every fortnight say, and let changes
 	      accumulate over that fortnight.  Or you might want to re-make
 	      just those things that have changed, and be confident you can
 	      spot all the dependencies.</para>
       
 	    <para>And, of course, this all depends on how often you want to
 	      upgrade, and whether you are tracking &os.stable; or
 	      &os.current;.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>My compile failed with lots of signal 11 (or other signal
 	      number) errors.  What has happened?</para>
 	  </question>
     <indexterm><primary>signal 11</primary></indexterm>
 
 	  <answer>
 
 	    <para>This is normally indicative of hardware problems.
 	      (Re)making the world is an effective way to stress test your
 	      hardware, and will frequently throw up memory problems.  These
 	      normally manifest themselves as the compiler mysteriously dying
 	      on receipt of strange signals.</para>
       
 	    <para>A sure indicator of this is if you can restart the make and
 	      it dies at a different point in the process.</para>
       
 	    <para>In this instance there is little you can do except start
 	      swapping around the components in your machine to determine
 	      which one is failing.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Can I remove <filename>/usr/obj</filename> when I have
 	      finished?</para>
 	  </question>
 	  
 	  <answer>
 	    <para>The short answer is yes.</para>
       
 	    <para><filename>/usr/obj</filename> contains all the object files
 	      that were produced during the compilation phase.  Normally, one
 	      of the first steps in the <quote>make world</quote> process is to
 	      remove this directory and start afresh.  In this case, keeping
 	      <filename>/usr/obj</filename> around after you have finished
 	      makes little sense, and will free up a large chunk of disk space
 	      (currently about 340&nbsp;MB).</para>
       
 	    <para>However, if you know what you are doing you can have
 	      <quote>make world</quote> skip this step.  This will make subsequent
 	      builds run much faster, since most of sources will not need to
 	      be recompiled.  The flip side of this is that subtle dependency
 	      problems can creep in, causing your build to fail in odd ways.
 	      This frequently generates noise on the &os; mailing lists,
 	      when one person complains that their build has failed, not
 	      realizing that it is because they have tried to cut
 	      corners.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Can interrupted builds be resumed?</para>
 	  </question>
 
 	  <answer>
 	    <para>This depends on how far through the process you got before
 	      you found a problem.</para>
 
 	    <para><emphasis>In general</emphasis> (and this is not a hard and
 	      fast rule) the <quote>make world</quote> process builds new
 	      copies of essential tools (such as &man.gcc.1;, and
 	      &man.make.1;) and the system libraries.  These tools and
 	      libraries are then installed.  The new tools and libraries are
 	      then used to rebuild themselves, and are installed again. The
 	      entire system (now including regular user programs, such as
 		&man.ls.1; or &man.grep.1;) is then rebuilt with the new
 	      system files.</para>
 
 	    <para>If you are at the last stage, and you know it (because you
 	      have looked through the output that you were storing) then you
 	      can (fairly safely) do:</para>
 
 	    <screen><emphasis>&hellip; fix the problem &hellip;</emphasis>
 &prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make -DNOCLEAN all</userinput></screen>
 
 	    <para>This will not undo the work of the previous
 	      <quote>make world</quote>.</para>
 
 	    <para>If you see the message:</para>
 
 	      <screen>--------------------------------------------------------------
 Building everything..
 --------------------------------------------------------------</screen>
 
 	    <para>in the <quote>make world</quote> output then it is
 	      probably fairly safe to do so.</para>
 	    
 	    <para>If you do not see that message, or you are not sure, then it
 	      is always better to be safe than sorry, and restart the build
 	      from scratch.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>How can I speed up making the world?</para>
           </question>
 
           <answer>
 	    <itemizedlist>
 	      <listitem>
 		<para>Run in single user mode.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Put the <filename>/usr/src</filename> and
 		  <filename>/usr/obj</filename> directories on separate
 		  file systems held on separate disks.  If possible, put these
 		  disks on separate disk controllers.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Better still, put these file systems across multiple
 		  disks using the &man.ccd.4; (concatenated disk
 		  driver) device.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Turn off profiling (set <quote>NOPROFILE=true</quote> in
 		  <filename>/etc/make.conf</filename>).  You almost certainly
 		  do not need it.</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Also in <filename>/etc/make.conf</filename>, set
 		  <makevar>CFLAGS</makevar> to something like <option>-O
 		  -pipe</option>.  The optimization <option>-O2</option> is much
 		  slower, and the optimization difference between
 		  <option>-O</option> and <option>-O2</option> is normally
 		  negligible.  <option>-pipe</option> lets the compiler use
 		  pipes rather than temporary files for communication, which
 		  saves disk access (at the expense of memory).</para>
 	      </listitem>
 	      
 	      <listitem>
 		<para>Pass the <option>-j<replaceable>n</replaceable></option> option to &man.make.1; to
 		  run multiple processes in parallel.  This usually helps 
 		  regardless of whether you have a single or a multi processor
 		  machine.</para>
 	      </listitem>
 	      
 	      <listitem><para>The file system holding
 		  <filename>/usr/src</filename> can be mounted (or remounted)
 		  with the <option>noatime</option> option.  This prevents the
 		  file system from recording the file access time.  You probably
 		  do not need this information anyway.</para>
 		  
 		  <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen>
 		  
 		  <warning>
 		    <para>The example assumes <filename>/usr/src</filename> is
 		      on its own file system.  If it is not (if it is a part of
 		      <filename>/usr</filename> for example) then you will
 		      need to use that file system mount point, and not
 		      <filename>/usr/src</filename>.</para>
 		  </warning>
 	      </listitem>
 	      
 	      <listitem>
 		<para>The file system holding <filename>/usr/obj</filename> can
 		  be mounted (or remounted) with the <option>async</option>
 		  option.  This causes disk writes to happen asynchronously.
 		  In other words, the write completes immediately, and the
 		  data is written to the disk a few seconds later.  This
 		  allows writes to be clustered together, and can be a
 		  dramatic performance boost.</para>
 
 		<warning>
 		  <para>Keep in mind that this option makes your file system
 		    more fragile.  With this option there is an increased
 		    chance that, should power fail, the file system will be in
 		    an unrecoverable state when the machine restarts.</para>
 	   
 		  <para>If <filename>/usr/obj</filename> is the only thing on
 		    this file system then it is not a problem.  If you have
 		    other, valuable data on the same file system then ensure
 		    your backups are fresh before you enable this
 		    option.</para>
 		</warning>
 		
 		<screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen>
 		
 		<warning>
 		  <para>As above, if <filename>/usr/obj</filename> is not on
 		    its own file system, replace it in the example with the
 		    name of the appropriate mount point.</para>
 		</warning>
 	      </listitem>
 	    </itemizedlist>
 	  </answer>
 	</qandaentry>
 
         <qandaentry>
           <question>
             <para>What do I do if something goes wrong?</para>
           </question>
 
           <answer>
             <para>Make absolutely sure your environment has no
               extraneous cruft from earlier builds.  This is simple
               enough.</para>
 
             <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
 &prompt.root; <userinput>rm -rf /usr/obj/usr</userinput>
 &prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make cleandir</userinput>
 &prompt.root; <userinput>make cleandir</userinput></screen>
 
             <para>Yes, <command>make cleandir</command> really should
               be run twice.</para>
 
             <para>Then restart the whole process, starting
               with <command>make buildworld</command>.</para>
 
             <para>If you still have problems, send the error and the
               output of <command>uname -a</command> to &a.questions;.
               Be prepared to answer other questions about your
               setup!</para>
           </answer>
         </qandaentry>
       </qandaset>
     </sect2>
   </sect1>
 
   <sect1 id="small-lan">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Mike</firstname>
 	  <surname>Meyer</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Tracking for multiple machines</title>
     <indexterm>
       <primary>NFS</primary>
       <secondary>installing multiple machines</secondary>
     </indexterm>
     
     <para>If you have multiple machines that you want to track the
       same source tree, then having all of them download sources and
       rebuild everything seems like a waste of resources: disk space,
       network bandwidth, and CPU cycles.  It is, and the solution is
       to have one machine do most of the work, while the rest of the
       machines mount that work via NFS.  This section outlines a
       method of doing so.</para>
 
     <sect2 id="small-lan-preliminaries">
       <title>Preliminaries</title>
 
       <para>First, identify a set of machines that is going to run
 	the same set of binaries, which we will call a
 	<emphasis>build set</emphasis>.  Each machine can have a
 	custom kernel, but they will be running the same userland
 	binaries.  From that set, choose a machine to be the
 	<emphasis>build machine</emphasis>.  It is going to be the
 	machine that the world and kernel are built on. Ideally, it
 	should be a fast machine that has sufficient spare CPU to
 	run <command>make world</command>.  You will also want to
 	choose a machine to be the <emphasis>test
 	machine</emphasis>, which will test software updates before they
 	are put into production.  This <emphasis>must</emphasis> be a
 	machine that you can afford to have down for an extended
 	period of time.  It can be the build machine, but need not be.</para>
 
       <para>All the machines in this build set need to mount
 	<filename>/usr/obj</filename> and
 	<filename>/usr/src</filename> from the same machine, and at
 	the same point.  Ideally, those are on two different drives
 	on the build machine, but they can be NFS mounted on that machine
 	as well.  If you have multiple build sets,
 	<filename>/usr/src</filename> should be on one build machine, and
 	NFS mounted on the rest.</para>
 	  
       <para>Finally make sure that
 	<filename>/etc/make.conf</filename> on all the machines in
 	the build set agrees with the build machine.  That means that
 	the build machine must build all the parts of the base
 	system that any machine in the build set is going to
 	install.  Also, each build machine should have its kernel
 	name set with <makevar>KERNCONF</makevar> in
 	<filename>/etc/make.conf</filename>, and the build machine
 	should list them all in <makevar>KERNCONF</makevar>, listing
 	its own kernel first.  The build machine must have the kernel
 	configuration files for each machine in
 	<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>
 	if it is going to build their kernels.</para>
     </sect2>
 
     <sect2>
       <title>The base system</title>
 
       <para>Now that all that is done, you are ready to build
 	everything.  Build the kernel and world as described in <xref
 	linkend="make-buildworld"> on the build machine,
 	but do not install anything.  After the build has finished, go
 	to the test machine, and install the kernel you just
 	built.  If this machine mounts <filename>/usr/src</filename>
 	and <filename>/usr/obj</filename> via NFS, when you reboot
 	to single user you will need to enable the network and mount
 	them.  The easiest way to do this is to boot to multi-user,
 	then run <command>shutdown now</command> to go to single user
 	mode.  Once there, you can install the new kernel and world and run
 	<command>mergemaster</command> just as you normally would.  When
 	done, reboot to return to normal multi-user operations for this
 	machine.</para>
 
       <para>After you are certain that everything on the test
 	machine is working properly, use the same procedure to
 	install the new software on each of the other machines in
 	the build set.</para>
     </sect2>
 
     <sect2>
       <title>Ports</title>
 
       <para>The same ideas can be used for the ports tree.  The first
 	critical step is mounting <filename>/usr/ports</filename> from
 	the same machine to all the machines in the build set.  You can
 	then set up <filename>/etc/make.conf</filename> properly to share
 	distfiles.  You should set <makevar>DISTDIR</makevar> to a
 	common shared directory that is writable by whichever user
 	<username>root</username> is mapped to by your NFS mounts.  Each
 	machine should set <makevar>WRKDIRPREFIX</makevar> to a
 	local build directory.  Finally, if you are going to be
 	building and distributing packages, you should set
 	<makevar>PACKAGES</makevar> to a directory similar to
 	<makevar>DISTDIR</makevar>.</para> 
     </sect2>
   </sect1>
 </chapter>
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
index 0244ff0120..01430b10af 100644
--- a/en_US.ISO8859-1/books/handbook/install/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
@@ -1,5841 +1,5841 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="install">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured, reorganized, and parts
 	  rewritten by </contrib>
       </author>
     </authorgroup>
 
     <authorgroup>
       <author>
 	<firstname>Randy</firstname>
 	<surname>Pratt</surname>
 	<contrib>The sysinstall walkthrough, screenshots, and general
 	  copy by </contrib>
       </author>
     </authorgroup>
     <!-- January 2000 -->
   </chapterinfo>
 
   <title>Installing FreeBSD</title>
 
-  <sect1>
+  <sect1 id="install-synopsis">
     <title>Synopsis</title>
 
     <indexterm><primary>installation</primary></indexterm>
 
     <para>FreeBSD is provided with a text-based, easy to use installation
       program called <application>sysinstall</application>.  This is the
       default installation program for FreeBSD, although vendors are free to
       provide their own installation suite if they wish.  This chapter
       describes how to use <application>sysinstall</application> to install
       FreeBSD.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How to create the FreeBSD installation disks.</para>
       </listitem>
       
       <listitem>
 	<para>How FreeBSD refers to, and subdivides, your hard disks.</para>
       </listitem>
 
       <listitem>
 	<para>How to start <application>sysinstall</application>.</para>
       </listitem>
 
       <listitem>
 	<para>The questions <application>sysinstall</application> will ask
 	  you, what they mean, and how to answer them.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Read the supported hardware list that shipped with the version
 	  of FreeBSD you are installing, and verify that your hardware is
 	  supported.</para>
       </listitem>
     </itemizedlist>
 
     <note>
       <para>In general, these installation instructions are written
         for i386 (<quote>PC compatible</quote>) architecture
         computers.  Where applicable, instructions specific to other
         platforms (for example, Alpha) will be listed.</para>
     </note>
 
   </sect1>
 
   <sect1 id="install-pre">
     <title>Pre-installation Tasks</title>
 
     <sect2 id="install-inventory">
       <title>Inventory Your Computer</title>
 
       <para>Before installing FreeBSD you should attempt to inventory the
 	components in your computer.  The FreeBSD installation routines will
 	show you the components (hard disks, network cards, CDROM drives, and
 	so forth) with their model number and manufacturer.  FreeBSD will also
 	attempt to determine the correct configuration for these devices,
 	which includes information about IRQ and IO port usage.  Due to the
 	vagaries of PC hardware this process is not always completely
 	successful, and you may need to correct FreeBSD's determination of
 	your configuration.</para>
 
       <para>If you already have another operating system installed, such as
 	Windows or Linux, it is a good idea to use the facilities provided
 	by those operating systems to see how your hardware is already
 	configured.  If you are really not sure what settings an expansion
 	card is using, you may find it printed on the card itself.  Popular IRQ
 	numbers are 3, 5, and 7, and IO port addresses are normally written as
 	hexadecimal numbers, such as 0x330.</para>
 
       <para>We recommend you print or write down this information before
 	installing FreeBSD.  It may help to use a table, like this:</para>
 
       <table pgwide="1" frame="none">
 	<title>Sample Device Inventory</title>
 
 	<tgroup cols="4">
 	  <thead>
 	    <row>
 	      <entry>Device Name</entry>
 
 	      <entry>IRQ</entry>
 
 	      <entry>IO port(s)</entry>
 
 	      <entry>Notes</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>First hard disk</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>4&nbsp;GB, made by Seagate, first IDE master</entry>
 	    </row>
 
 	    <row>
 	      <entry>CDROM</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>First IDE slave</entry>
 	    </row>
 
 	    <row>
 	      <entry>Second hard disk</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>2GB, made by IBM, second IDE master</entry>
 	    </row>
 
 	    <row>
 	      <entry>First IDE controller</entry>
 
 	      <entry>14</entry>
 
 	      <entry>0x1f0</entry>
 
 	      <entry></entry>
 	    </row>
 
 	    <row>
 	      <entry>Network card</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>Intel 10/100</entry>
 	    </row>
 
 	    <row>
 	      <entry>Modem</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>3Com 56K faxmodem, on COM1</entry>
 	    </row>
 
 	    <row>
 	      <entry>&hellip;</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
     </sect2>
 
     <sect2>
       <title>Backup Your Data</title>
       
       <para>If the computer you will be installing FreeBSD on contains
 	valuable data then ensure you have it backed up, and that you have
 	tested the backups before installing FreeBSD.  The FreeBSD
 	installation routine will prompt you several times before writing any
 	data to your disk, but once that process has started it cannot be
 	undone.</para>
     </sect2>
 
     <sect2 id="install-where">
       <title>Decide Where to Install FreeBSD</title>
 
       <para>If you want FreeBSD to use all your disk, then there is nothing
 	more to concern yourself with at this point &mdash; you can skip to the
 	next section.</para>
 
       <para>However, if you need FreeBSD to co-exist with other operating
 	systems then you need to have a rough understanding of how data is
 	laid out on the disk, and how this affects you.</para>
 
       <sect3 id="install-where-i386">
 	<title>Disk Layouts for the i386</title>
 
       <para>A PC disk can be divided into discrete chunks.  These chunks are
 	called <firstterm>partitions</firstterm>.  By design, the PC only
 	supports four partitions per disk.  These partitions are called
 	<firstterm>primary partitions</firstterm>.  To work around this
 	limitation and allow more than four partitions, a new partition type
 	was created, the <firstterm>extended partition</firstterm>.  A disk
 	may contain only one extended partition.  Special partitions, called
 	<firstterm>logical partitions</firstterm>, can be created inside this
 	extended partition.</para>
 
       <para>Each partition has a <firstterm>partition ID</firstterm>, which is
 	a number used to identify the type of data on the partition.  FreeBSD
 	partitions have the partition ID <literal>165</literal>.</para>
 
       <para>In general, each operating system that you use will identify
 	partitions in a particular way.  For example, DOS, and its
 	descendants, like Windows, assign each primary and logical partition a
 	<firstterm>drive letter</firstterm>, starting with
 	<devicename>C:</devicename>.</para>
 
       <para>FreeBSD must be installed into a primary partition.  FreeBSD can
 	keep all its data, including any files that you create, on this one
 	partition.  However, if you have multiple disks, then you can create a
 	FreeBSD partition on all, or some, of them.  When you install FreeBSD,
 	you must have one partition available.  This might be a blank
 	partition that you have prepared, or it might be an existing partition
 	that contains data that you no longer care about.</para>
 
       <para>If you are already using all the partitions on all your disks, then
 	you will have to free one of them for FreeBSD using the tools
 	provided by the other operating systems you use (e.g.,
 	<command>fdisk</command> on DOS or Windows).</para>
 
       <para>If you have a spare partition then you can use that.  However, you
 	may need to shrink one or more of your existing partitions
 	first.</para>
 
       <para>A minimal installation of FreeBSD takes as little as 100&nbsp;MB of disk
 	space.  However, that is a <emphasis>very</emphasis> minimal install,
 	leaving almost no space for your own files.  A more realistic minimum
 	is 250&nbsp;MB without a graphical environment, and 350&nbsp;MB or more if you
 	want a graphical user interface.  If you intend to install a lot of
 	third party software as well, then you will need more space.</para>
 
       <para>You can use a commercial tool such as <application>Partition
 	  Magic</application> to resize your partitions to make space for
 	FreeBSD.  The <filename>tools</filename> directory on the CDROM
 	contains two free software tools which can carry out this task,
 	<application>FIPS</application> and
 	<application>PResizer</application>.  Documentation for both of these
 	is in the same directory.</para>
 
       <warning>
 	<para>Incorrect use of these tools can delete the data on your disk.
 	  Be sure that you have recent, working backups before using
 	  them.</para>
       </warning>
 
       <example>
 	<title>Using an existing partition unchanged</title>
 
 	<para>Suppose that you have a computer with a single 4&nbsp;GB disk that
 	  already has a version of Windows installed, and you have split the
 	  disk into two drive letters, <devicename>C:</devicename> and
 	  <devicename>D:</devicename>, each of which is 2&nbsp;GB in size.  You have
 	  1&nbsp;GB of data on <devicename>C:</devicename>, and 0.5&nbsp;GB of data on
 	  <devicename>D:</devicename>.</para>
 
 	<para>This means that your disk has two partitions on it, one per
 	  drive letter.  You can copy all your existing data from
 	  <devicename>D:</devicename> to <devicename>C:</devicename>, which
 	  will free up the second partition, ready for FreeBSD.</para>
       </example>
 
       <example>
 	<title>Shrinking an existing partition</title>
 
 	<para>Suppose that you have a computer with a single 4&nbsp;GB disk, that
 	  already has a version of Windows installed.  When you installed
 	  Windows you created one large partition, giving you a
 	  <devicename>C:</devicename> drive that is 4&nbsp;GB in size.  You are
 	  currently using 1.5&nbsp;GB of space, and want FreeBSD to have 2&nbsp;GB of
 	  space.</para>
 
 	<para>In order to install FreeBSD you will need to either:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>Backup your Windows data, and then reinstall Windows,
 	      asking for a 2&nbsp;GB partition at install time.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use one of the tools such as <application>Partition
 		Magic</application>, described above, to shrink your Windows
 		partition.</para>
 	  </listitem>
 	</orderedlist>
       </example>
 
       </sect3>
 
       <sect3>
 	<title>Disk Layouts for the Alpha</title>
 
 	<indexterm><primary>Alpha</primary></indexterm>
 
 	<para>You will need a dedicated disk for FreeBSD on the
 	  Alpha.  It is not possible to share a disk with another
 	  operating system at this time.  Depending on the specific
 	  Alpha machine you have, this disk can either be a SCSI disk
 	  or an IDE disk, as long as your machine is capable of
 	  booting from it.</para>
 
 	<para>Following the conventions of the Digital / Compaq
 	  manuals all SRM input is shown in uppercase.  SRM is case
 	  insensitive.</para>
 
 	<para>To find the names and types of disks in your machine, use
 	  the <literal>SHOW DEVICE</literal> command from the SRM
 	  console prompt:</para>
 
 	<screen>&gt;&gt;&gt;<userinput>show device</userinput>
 dka0.0.0.4.0               DKA0           TOSHIBA CD-ROM XM-57  3476
 dkc0.0.0.1009.0            DKC0                       RZ1BB-BS  0658
 dkc100.1.0.1009.0          DKC100             SEAGATE ST34501W  0015
 dva0.0.0.0.1               DVA0
 ewa0.0.0.3.0               EWA0              00-00-F8-75-6D-01
 pkc0.7.0.1009.0            PKC0                  SCSI Bus ID 7  5.27
 pqa0.0.0.4.0               PQA0                       PCI EIDE
 pqb0.0.1.4.0               PQB0                       PCI EIDE</screen>
 
 	<para>This example is from a Digital Personal Workstation
 	  433au and shows three disks attached to the machine.  The
 	  first is a CDROM drive called <devicename>DKA0</devicename> and
 	  the other two are disks and are called
 	  <devicename>DKC0</devicename> and
 	  <devicename>DKC100</devicename> respectively.</para>
 
 	<para>Disks with names of the form <devicename>DKx</devicename>
 	  are SCSI disks.  For example <devicename>DKA100</devicename>
 	  refers to a SCSI with SCSI target ID 1 on the first SCSI bus (A), 
 	  whereas <devicename>DKC300</devicename> refers to a SCSI disk
 	  with SCSI ID 3 on the third SCSI bus (C).  Devicename <devicename>
 	  PKx</devicename> refers to the SCSI host bus adapter.  As
 	  seen in the <literal>SHOW DEVICE</literal> output SCSI
 	  CDROM drives are treated as any other SCSI hard disk drive.</para>
 
 	<para>IDE disks have names similar to <devicename>DQx</devicename>,
 	  while <devicename>PQx</devicename> is the associated IDE
 	  controller.</para>
 
       </sect3>
     </sect2>
 
     <sect2>
       <title>Collect Your Network Configuration Details</title>
 
       <para>If you intend to connect to a network as part of your FreeBSD
 	installation (for example, if you will be installing from an FTP
 	site, or an
 	NFS server), then you need to know your network configuration.  You
 	will be prompted for this information during the installation so that
 	FreeBSD can connect to the network to complete the install.</para>
 
       <sect3>
 	<title>Connecting to an Ethernet Network, or Cable/DSL Modem</title>
 
 	<para>If you connect to an Ethernet network, or you have an Internet
 	  connection via cable or DSL, then you will need the following
 	  information:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>IP address.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>IP address of the default gateway.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Hostname.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>DNS server IP addresses.</para>
 	  </listitem>
 	</orderedlist>
 
 	<para>If you do not know this information, then ask your system
 	  administrator or service provider.  They may say that this
 	  information is assigned automatically, using
 	  <firstterm>DHCP</firstterm>.  If so, make a note of this.</para>
       </sect3>
 
       <sect3>
 	<title>Connecting Using a Modem</title>
 
 	<para>If you dial up to an ISP using a regular modem then you can
 	  still install FreeBSD over the Internet, it will just take a very
 	  long time.</para>
 
 	<para>You will need to know:</para>
 
 	<orderedlist>
 	  <listitem>
 	    <para>The phone number to dial for your ISP.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The COM: port your modem is connected to.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The username and password for your ISP account.</para>
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
     <sect2>
       <title>Check for FreeBSD Errata</title>
       
       <para>Although the FreeBSD project strives to ensure that each release
 	of FreeBSD is as stable as possible, bugs do occasionally creep into
 	the process.  On very rare occasions those bugs affect the
 	installation process.  As these problems are discovered and fixed they
 	are noted in the FreeBSD Errata, posted on the FreeBSD web site.  You
 	should check the errata before installing to make sure that there are
 	no late-breaking problems which you should be aware of.</para>
 
       <para>Information about all the releases, including the errata for each
 	release, can be found on the 
 	<ulink
 	url="../../../../releases/index.html">release
 	information</ulink> section of the 
 	<ulink
 	  url="../../../../index.html">FreeBSD web site</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>Obtain the FreeBSD installation files</title>
 
       <para>The FreeBSD installation process can install FreeBSD from files
 	located in the any of the following places:</para>
 
       <itemizedlist>
 	<title>Local media</title>
 	
 	<listitem>
 	  <para>A CDROM</para>
 	</listitem>
 
 	<listitem>
 	  <para>A DOS partition on the same computer</para>
 	</listitem>
 
 	<listitem>
 	  <para>A tape</para>
 	</listitem>
 
 	<listitem>
 	  <para>Floppy disks</para>
 	</listitem>
       </itemizedlist>
 
       <itemizedlist>
 	<title>Network</title>
 
 	<listitem>
 	  <para>An FTP site, going through a firewall, or using an HTTP proxy,
 	    as necessary</para>
 	</listitem>
 
 	<listitem>
 	  <para>An NFS server</para>
 	</listitem>
 
 	<listitem>
 	  <para>A dedicated parallel or serial connection</para>
 	</listitem>
       </itemizedlist>
 
       <para>If you have purchased FreeBSD on CD or DVD then you already have
 	everything you need, and should proceed to the next section 
 	(<link linkend="install-floppies">Preparing the Boot 
 	  Media</link>).</para>
 
       <para>If you have not obtained the FreeBSD installation files you should
 	skip ahead to <xref linkend="install-diff-media"> which explains how
 	to prepare to install FreeBSD from any of the above.  After reading
 	that section, you should come back here, and read on to 
 	<xref linkend="install-floppies">.</para>
     </sect2>
 
     <sect2 id="install-floppies">
       <title>Prepare the Boot Media</title>
       
       <para>The FreeBSD installation process is started by booting your
 	computer into the FreeBSD installer&mdash;it is not a program you run
 	within another operating system.  Your computer normally boots using
 	the operating system installed on your hard disk, but it can also be
 	configured to use a <quote>bootable</quote> floppy disk.  It may also
 	be able to boot from a disk in the CDROM drive.</para>
 
       <tip>
 	<para>If you have FreeBSD on CDROM or DVD (either one you purchased,
 	  or you prepared yourself), and your computer allows you to boot from
 	  the CDROM or DVD (typically a BIOS option called <quote>Boot
 	    Order</quote> or similar) then you can skip this section.  The
 	  FreeBSD CDROM and DVD images are bootable and can be used to install
 	  FreeBSD without any other special preparation.</para>
       </tip>
     
       <para>To create boot floppy images, follow these steps:</para>
 
       <procedure>
 	<step>
 	  <title>Acquire the Boot Floppy Images</title>
 	  
 	  <para>The boot disks are available on your installation media
 	    in the <filename>floppies/</filename> directory, and
 	    can also be downloaded from the <ulink
 	    url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/">
 	      floppies directory</ulink> for the i386 architecture and from this <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/alpha/&rel.current;-RELEASE/floppies/">floppies directory</ulink> for the Alpha architecture.</para>
 
 	  <para>The floppy images have a <filename>.flp</filename> extension.
 	    The <filename>floppies/</filename> directory contains a number of
 	    different images, and the ones you will need to use depends on the
 	    version of FreeBSD you are installing, and in some cases, the
 	    hardware you are installing to.  In most cases you will just need
 	    two files, <filename>kern.flp</filename> and
 	    <filename>mfsroot.flp</filename>.  Additional device drivers may
 	    be necessary for some systems.  These drivers are provided
 	    on the <filename>drivers.flp</filename> image.  Check
 	    <filename>README.TXT</filename> in the same directory for the
 	    most up to date information about these floppy images.</para>
 
 	  <important>
 	    <para>Your FTP program must use <emphasis>binary mode</emphasis>
 	      to download these disk images.  Some web browsers have been
 	      known to use <emphasis>text</emphasis> (or
 	      <emphasis>ASCII</emphasis>) mode, which will be apparent if you
 	      cannot boot from the disks.</para>
 	  </important>
 	</step>
 
 	<step>
 	  <title>Prepare the Floppy Disks</title>
 	  
 	  <para>You must prepare one floppy disk per image file you had to
 	    download.  It is imperative that these disks are free from
 	    defects.  The easiest way to test this is to format the disks
 	    for yourself.  Do not trust pre-formatted floppies.</para>
 	  
 	  <important>
 	    <para>If you try to install FreeBSD and the installation
 	      program crashes, freezes, or otherwise misbehaves, one of
 	      the first things to suspect is the floppies.  Try writing
 	      the floppy image files to some other disks and try
 	      again.</para>
 	  </important>
 	</step>
 
 	<step>
 	  <title>Write the Image Files to the Floppy Disks</title>
 
 	  <para>The <filename>.flp</filename> files are
 	    <emphasis>not</emphasis> regular files you copy to the disk.
 	    Instead, they are images of the complete contents of the
 	    disk.  This means that you <emphasis>cannot</emphasis> use
 	    commands like DOS' <command>copy</command> to write the
 	    files.  Instead, you must use specific tools to write the
 	    images directly to the disk.</para>
 
 	  <indexterm><primary>DOS</primary></indexterm>
 	  <para>If you are creating the floppies on a computer running
       DOS/Windows, then we provide a tool to do
       this called <command>fdimage</command>.</para>
 
 	  <para>If you are using the floppies from the CDROM, and your
 	    CDROM is the <devicename>E:</devicename> drive, then you would 
 	    run this:</para>
 
 	  <screen><prompt>E:\&gt;</prompt> <userinput>tools\fdimage floppies\kern.flp A:</userinput></screen>
 
 	  <para>Repeat this command for each <filename>.flp</filename>
 	    file, replacing the floppy disk each time, being sure to label
 	    the disks with the name of the file that you copied to them.
 	    Adjust the command line as necessary, depending on where you have
 	    placed the <filename>.flp</filename> files.  If you do not have
 	    the CDROM, then <command>fdimage</command> can be downloaded from
 	    the <ulink
 	    url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/"><filename>tools</filename>
 	    directory</ulink> on the FreeBSD FTP site.</para>
 	  
 	  <para>If you are writing the floppies on a Unix system (such as
 	    another FreeBSD system) you can use the &man.dd.1; command to
 	    write the image files directly to disk.  On FreeBSD, you would
 	    run:</para>
 	  
 	  <screen>&prompt.root; <userinput>dd if=kern.flp of=/dev/fd0</userinput></screen>
 
 	  <para>On FreeBSD, <filename>/dev/fd0</filename> refers to the
 	    first floppy disk (the <devicename>A:</devicename> drive).
 	    <filename>/dev/fd1</filename> would be the
 	    <devicename>B:</devicename> drive, and so on.  Other Unix
 	    variants might have different names for the floppy disk
 	    devices, and you will need to check the documentation for the
 	    system as necessary.</para>
 	</step>
       </procedure>
 
       <para>You are now ready to start installing FreeBSD.</para>
     </sect2>
   </sect1>
 
   <sect1 id="install-start">
     <title>Starting the Installation</title>
 
     <important>
       <para>By default, the installation will not make any changes to your
 	disk(s) until you see the following message:</para>
 
       <literallayout class="monospaced">Last Chance: Are you SURE you want continue the installation?
 
 If you're running this on a disk with data you wish to save then WE
 STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding!
 
 We can take no responsibility for lost disk contents!</literallayout>
 
       <para>The install can be exited at any time prior to the final
 	warning without changing the contents of the hard drive.  If you are
 	concerned that you have configured something incorrectly you can just
 	turn the computer off before this point, and no damage will be
 	done.</para>
     </important>
 
     <sect2 id="install-starting">
       <title>Booting</title>
 
       <sect3 id="install-starting-i386">
         <title>Booting for the i386</title>
 
       <procedure>
 	<step>
 	  <para>Start with your computer turned off.</para>
 	</step>
 
 	<step>
 	  <para>Turn on the computer.  As it starts it should display an
 	    option to enter the system set up menu, or BIOS, commonly reached
 	    by keys like <keycap>F2</keycap>, <keycap>F10</keycap>,
 	    <keycap>Del, </keycap>or
 	    <keycombo action="simul">
 	      <keycap>Alt</keycap>
 	      <keycap>S</keycap>
 	    </keycombo>.  Use whichever keystroke is indicated on screen.  In
 	    some cases your computer may display a graphic while it starts.
 	    Typically, pressing <keycap>Esc</keycap> will dismiss the graphic
 	    and allow you to see the necessary messages.</para>
 	</step>
 
 	<step>
 	  <para>Find the setting that controls which devices the system boots
 	    from.  This is commonly shown as a list of devices, such as
 	    <literal>Floppy</literal>, <literal>CDROM</literal>,
 	    <literal>First Hard Disk</literal>, and so on.</para>
 
 	  <para>If you needed to prepare boot floppies, then make sure that the
 	    floppy disk is selected.  If you are booting from the CDROM then
 	    make sure that that is selected instead.  In case of doubt, you
 	    should consult the manual that came with your computer, and/or its
 	    motherboard.</para>
 
 	  <para>Make the change, then save and exit.  The computer should now
 	    restart.</para>
 	</step>
 
 	<step>
 	  <para>If you needed to prepare boot floppies, as described in 
 	    <xref linkend="install-floppies"> then one of them will be the
 	    first boot disc, probably the one containing
 	    <filename>kern.flp</filename>.  Put this disc in your floppy
 	    drive.</para>
 
 	  <para>If you are booting from CDROM, then you will need to turn on
 	    the computer, and insert the CDROM at the first
 	    opportunity.</para>
 
 	  <para>If your computer starts up as normal, and loads your existing
 	    operating system then either:</para>
 
 	  <orderedlist>
 	    <listitem>
 	      <para>The disks were not inserted early enough in the boot
 		process.  Leave them in, and try restarting your
 		computer.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>The BIOS changes earlier did not work correctly.  You
 		should redo that step until you get the right option.</para>
 	    </listitem>
 	</orderedlist>
 	</step>
     
 	<step>
 	  <para>FreeBSD will start to boot.  If you are booting from CDROM you
 	    will see a display similar to this (version information omitted):</para>
 	  
 	  <screen>Verifying DMI Pool Data ........
 Boot from ATAPI CD-ROM :
  1. FD 2.88MB  System Type-(00)
 Uncompressing ... done
 
 BTX loader 1.00 BTX version is 1.01
 Console: internal video/keyboard
 BIOS drive A: is disk0
 BIOS drive B: is disk1
 BIOS drive C: is disk2
 BIOS drive C: is disk3
 BIOS 639kB/261120kB available memory
 
 FreeBSD/i386 bootstrap loader, Revision 0.8
 
 /kernel text=0x277391 data=0x3268c+0x332a8 |
 
 |
 Hit [Enter] to boot immediately, or any other key for command prompt.
 Booting [kernel] in 9 seconds... _</screen>
 	
 	  <para>If you are booting from floppy disc, you will see a display
 	    similar to this (version information omitted):</para>
 	
 	  <screen>Verifying DMI Pool Data ........ 
 
 BTX loader 1.00  BTX version is 1.01 
 Console: internal video/keyboard 
 BIOS drive A: is disk0 
 BIOS drive C: is disk1 
 BIOS 639kB/261120kB available memory 
 
 FreeBSD/i386 bootstrap loader, Revision 0.8 
 
 /kernel text=0x277391 data=0x3268c+0x332a8 |
 
 Please insert MFS root floppy and press enter:</screen>
 
 	  <para>Follow these instructions by removing the
 	    <filename>kern.flp</filename> disc, insert the
 	    <filename>mfsroot.flp</filename> disc, and press
 	    <keycap>Enter</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>Irrespective of whether you booted from floppy or CDROM, the
 	    boot process will then get to this point:</para>
 
 	  <screen>Hit [Enter] to boot immediately, or any other key for command prompt. 
 Booting [kernel] in 9 seconds... _</screen>
 
 	  <para>Either wait ten seconds, or press <keycap>Enter</keycap>.  This
 	    will then launch the kernel configuration menu.</para>
 	</step>
       </procedure>
 
       </sect3>
       <sect3>
         <title>Booting for the Alpha</title>
 
 	<indexterm><primary>Alpha</primary></indexterm>
 
       <procedure>
 	<step>
 	  <para>Start with your computer turned off.</para>
 	</step>
 
 	<step>
 	  <para>Turn on the computer and wait for a boot monitor
 	    prompt.</para>
         </step>
 
 	<step>
 	  <para>If you needed to prepare boot floppies, as described in 
 	    <xref linkend="install-floppies"> then one of them will be the
 	    first boot disc, probably the one containing
 	    <filename>kern.flp</filename>.  Put this disc in your floppy
 	    drive and type the following command to boot the disk
 	    (substituting the name of your floppy drive if
 	    necessary):</para>
 
 	  <screen>&gt;&gt;&gt;<userinput>BOOT DVA0 -FLAGS '' -FILE ''</userinput></screen>
 
 	  <para>If you are booting from CDROM, insert the CDROM into
 	    the drive and type the following command to start the
 	    installation (substituting the name of the appropriate
 	    CDROM drive if necessary):</para>
 
           <screen>&gt;&gt;&gt;<userinput>BOOT DKA0 -FLAGS '' -FILE ''</userinput></screen>
 	</step>
     
 	<step>
 	  <para>FreeBSD will start to boot.  If you are booting from a
 	    floppy disc, at some point you will see the message:</para>
 
 	  <screen>Please insert MFS root floppy and press enter:</screen>
 
 	  <para>Follow these instructions by removing the
 	    <filename>kern.flp</filename> disc, insert the
 	    <filename>mfsroot.flp</filename> disc, and press
 	    <keycap>Enter</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>Irrespective of whether you booted from floppy or CDROM, the
 	    boot process will then get to this point:</para>
 
 	  <screen>Hit [Enter] to boot immediately, or any other key for command prompt. 
 Booting [kernel] in 9 seconds... _</screen>
 
 	  <para>Either wait ten seconds, or press <keycap>Enter</keycap>.  This
 	    will then launch the kernel configuration menu.</para>
 	</step>
       </procedure>
 
       </sect3>
 
     </sect2>
 
     <sect2 id="start-userconfig">
       <title>Kernel Configuration</title>
 
       <note><para>From FreeBSD versions 5.0 and later, userconfig has been depreciated
 	in favor of the new &man.device.hints.5; method.  For more information
 	on &man.device.hints.5; please visit <xref linkend="device-hints"></para></note>
 
       <para>The <firstterm>kernel</firstterm> is the core of the operating
 	system.  It is responsible for many things, including access to all
 	the devices you may have on your system, such as hard disks, network
 	cards, sound cards, and so on.  Each piece of hardware supported by
 	the FreeBSD kernel has a driver associated with it.  Each driver has a
 	two or three letter name, such as <devicename>sa</devicename> for the
 	SCSI sequential access driver, or <devicename>sio</devicename> for the
 	Serial I/O driver (which manages COM ports).</para>
 
       <para>When the kernel starts, each driver checks the system to see
 	whether or not the hardware it supports exists on your system.  If it
 	does, then the driver configures the hardware and makes it available
 	to the rest of the kernel.</para>
 
       <para>This checking is commonly referred to as <firstterm>device
 	  probing</firstterm>.  Unfortunately, it is not always possible to do
 	this in a safe way.  Some hardware drivers do not co-exist well,
 	and probing for one piece of hardware can sometimes leave
 	another in an inconsistent state.  This is a basic
 	limitation of the <acronym>PC</acronym> design.</para>
 
       <para>Many older devices are called ISA devices&mdash;as opposed
 	to PCI devices.  The ISA specification requires each device to have
 	some information hard coded into it, typically the Interrupt Request
 	Line number (IRQ) and IO port address that the driver uses.  This
 	information is commonly set by using physical
 	<firstterm>jumpers</firstterm> on the card, or by using a DOS based
 	utility.</para>
 
       <para>This was often a source of problems, because it was not possible
 	to have two devices that shared the same IRQ or port address.</para>
 
       <para>Newer devices follow the PCI specification, which does not require
 	this, as the devices are supposed to cooperate with the BIOS, and be
 	told which IRQ and IO port addresses to use.</para>
 
       <para>If you have any ISA devices in your computer then FreeBSD's
 	driver for that device will need to be configured with the IRQ and
 	port address that you have set the card to.  This is why carrying out
 	an inventory of	your hardware (see <xref
 	linkend="install-inventory">) can be useful.</para>
 
       <para>Unfortunately, the default IRQs and memory ports used by some
 	drivers clash.  This is because some ISA devices are shipped with IRQs
 	or memory ports that clash.  The defaults in FreeBSD's drivers are
 	deliberately set to mirror the manufacturer's defaults, so that, out
 	of the box, as many devices as possible will work.</para>
 
       <para>This is almost never an issue when running FreeBSD day-to-day.
 	Your computer will not normally contain two pieces of hardware that
 	clash, because one of them would not work (irrespective of the
 	operating system you are using).</para>
 
       <para>It becomes an issue when you are installing FreeBSD for the first
 	time because the kernel used to carry out the install has to contain
 	as many drivers as possible, so that many different hardware
 	configurations can be supported.  This means that some of
 	those drivers will have conflicting configurations.  The devices are
 	probed in a strict order, and if you own a device that is probed late
 	in the process, but conflicted with an earlier probe, then your
 	hardware might not function or be probed correctly when you install
 	FreeBSD.</para>
 
       <para>Because of this, the first thing you have the opportunity to do
 	when installing FreeBSD is look at the list of drivers that are
 	configured into the kernel, and either disable some of them, if you
 	do not own that device, or confirm (and alter) the driver's
 	configuration if you do own the device but the defaults are
 	wrong.</para>
 
       <para>This probably sounds much more complicated than it actually
 	is.</para>
 
       <para><xref linkend="kernel-config"> shows the first kernel
 	configuration menu.  We recommend that you choose the
 	<guimenuitem>Start kernel configuration in full-screen visual
 	  mode</guimenuitem> option, as it presents the easiest interface for
 	the new user.</para>
 
       <figure id="kernel-config">
 	<title>Kernel Configuration Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/userconfig" format="PNG">
 	  </imageobject>
 
 	  <textobject>
 	    <screen>&txt.install.userconfig;</screen>
 	  </textobject>
 	</mediaobject>
       </figure>
 
       <para>The kernel configuration screen (<xref linkend="fig-userconfig">)
 	is then divided into four sections.</para>
 
       <orderedlist>
 	<listitem>
 	  <para>A collapsible list of all the drivers that are currently
 	    marked as <quote>active</quote>, subdivided into groups such as
 	    <literal>Storage</literal>, and <literal>Network</literal>.  Each
 	    driver is shown as a description, its two or three letter driver
 	    name, and the IRQ and memory port used by that driver.  In
 	    addition, if an active driver conflicts with another active driver
 	    then <literal>CONF</literal> is shown next to the driver name.
 	    This section also shows the total number of conflicting drivers
 	    that are currently active.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Drivers that have been marked inactive.  They remain in the
 	    kernel, but they will not probe for their device when the kernel
 	    starts.  These are subdivided into groups in the same way as the
 	    active driver list.</para>
 	</listitem>
 
 	<listitem>
 	  <para>More detail about the currently selected driver, including its
 	    IRQ and memory port address.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Information about the keystrokes that are valid at this point
 	    in time.</para>
 	</listitem>
       </orderedlist>
 
       <figure id="fig-userconfig">
 	<title>The Kernel Device Configuration Visual Interface</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/userconfig2" format="PNG">
 	  </imageobject>
 
           <textobject>
             <screen>&txt.install.userconfig2;</screen>
           </textobject>
         </mediaobject>
       </figure>
 
       <para>At this point there will always be conflicts listed.  Do not worry
 	about this, it is to be expected; all the drivers are enabled, and
 	as has already been explained, some of them will conflict with one
 	another.</para>
 
       <para>You now have to work through the list of drivers, resolving the
 	conflicts.</para>
 
       <procedure>
 	<title>Resolving Driver Conflicts</title>
 
 	<step>
 	  <para>Press <keycap>X</keycap>.  This will completely expand the
 	    list of drivers, so you can see all of them.  You will need to use
 	    the arrow keys to scroll back and forth through the active driver
 	    list.</para>
 
 	  <para><xref linkend="hardware-conflicts"> shows the result of
 	    pressing <keycap>X</keycap>.  </para>
 
 	  <figure id="hardware-conflicts">
 	    <title>Expanded Driver List</title>
 
 	    <mediaobject>
 	      <imageobject>
 		<imagedata fileref="install/hdwrconf" format="PNG">
 	      </imageobject>
 	    </mediaobject>
 	  </figure>
 	</step>
 
 	<step>
 	  <para>Disable all the drivers for devices that you do not have.  To
 	    disable a driver, highlight it with the arrow keys and press
 	    <keycap>Del</keycap>.  The driver will be moved to the
 	    <literal>Inactive Drivers</literal> list.</para>
 
 	  <para>If you inadvertently disable a device that you need then press
 	    <keycap>Tab</keycap> to switch to the <literal>Inactive
 	    Drivers</literal> list, select the driver that you disabled, and
 	    press <keycap>Enter</keycap> to move it back to the active
 	    list.</para>
 
 	  <important>
 	    <para>Do not disable <devicename>sc0</devicename>.  This controls
 	      the screen, and you will need this unless you are installing
 	      over a serial cable.</para>
 	  </important>
 
 	  <important>
 	    <para>Only disable <devicename>atkbd0</devicename> if you are
 	      using a USB keyboard.  If you have a normal keyboard then you
 	      must keep <devicename>atkbd0</devicename>.</para>
 	  </important>
 	</step>
 
 	<step>
 	  <para>If there are no conflicts listed then you can skip this step.
 	    Otherwise, the remaining conflicts need to be examined.  If they
 	    do not have the indication of an <quote>allowed conflict</quote>
 	    in the message area, then either the IRQ/address for device probe
 	    will need to be changed, <emphasis>or</emphasis> the IRQ/address
 	    on the hardware will need to be changed.</para>
 
 	  <para>To change the driver's configuration for IRQ and IO port
 	    address, select the device and press <keycap>Enter</keycap>.  The
 	    cursor will move to the third section of the screen, and you can
 	    change the values.  You should enter the values for IRQ and port
 	    address that you discovered when you made your hardware inventory.
 	    Press <keycap>Q</keycap> to finish editing the device's
 	    configuration and return to the active driver list.</para>
 	  
 	  <para>If you are not sure what these figures should be then you can
 	    try using <literal>-1</literal>.  Some FreeBSD drivers can safely
 	    probe the hardware to discover what the correct value should be,
 	    and a value of <literal>-1</literal> configures them to do
 	    this.</para>
 
 	  <para>The procedure for changing the address on the hardware varies
 	    from device to device.  For some devices you may need to
 	    physically remove the card from your computer and adjust jumper
 	    settings or DIP switches.  Other cards may have come with a DOS
 	    floppy that contains the programs used to reconfigure the card.
 	    In any case, you should refer to the documentation that came with
 	    the device.  This will obviously entail restarting your computer,
 	    so you will need to boot back into the FreeBSD installation
 	    routine when you have reconfigured the card.</para>
 	</step>
 
 	<step>
 	  <para>When all the conflicts have been resolved the screen will look
 	    similar to <xref linkend="userconfig-done">.</para>
 
 	  <figure id="userconfig-done">
 	    <title>Driver Configuration With No Conflicts</title>
 
 	    <mediaobject>
 	      <imageobject>
 		<imagedata fileref="install/probstart" format="PNG">
 	      </imageobject>
 	    </mediaobject>
 	  </figure>
 
 	  <para>As you can see, the active driver list is now much smaller,
 	    with only drivers for the hardware that actually exists being
 	    listed.</para>
 	  
 	  <para>You can now save these changes, and move on to the next step
 	    of the install.  Press <keycap>Q</keycap> to quit the device
 	    configuration interface.  This message will appear:</para>
 
 	  <screen>Save these parameters before exiting? ([Y]es/[N]o/[C]ancel)</screen>
 
 	  <para>Answer <keycap>Y</keycap> to save the parameters and the
 	    probing will start.  After displaying the probe results in white
 	    on black text <application>sysinstall</application> will start
 	    and display its main menu 
 	    (<xref linkend="sysinstall-main">).</para>
 
 	  <figure id="sysinstall-main">
 	    <title>Sysinstall Main Menu</title>
 	    
 	    <mediaobject>
 	      <imageobject>
 		<imagedata fileref="install/main1" format="PNG">
 	      </imageobject>
 	    </mediaobject>
 	  </figure>
 	</step>
       </procedure>
     </sect2>
 
     <sect2 id="view-probe">
       <title>Reviewing the Device Probe Results</title>
 
       <para>The last few hundred lines that have been displayed on screen are
 	stored and can be reviewed.</para>
 
       <para>To review the buffer, press <keycap>Scroll Lock</keycap>.  This
 	turns on scrolling in the display.  You can then use the arrow keys, or
 	<keycap>PageUp</keycap> and <keycap>PageDown</keycap> to view the
 	results.  Press <keycap>Scroll Lock</keycap> again to stop
 	scrolling.</para>
 
       <para>Do this now, to review the text that scrolled off the screen when
 	the kernel was carrying out the device probes.  You will see text
 	similar to <xref linkend="install-dev-probe">, although the precise
 	text will differ depending on the devices that you have in your
 	computer.</para>
 
       <figure id="install-dev-probe">
 	<title>Typical Device Probe Results</title>
 
 	<screen>avail memory = 253050880 (247120K bytes) 
 Preloaded elf kernel "kernel" at 0xc0817000.
 Preloaded mfs_root "/mfsroot" at 0xc0817084.
 md0: Preloaded image &lt;/mfsroot&gt; 4423680 bytes at 0xc03ddcd4
 
 md1: Malloc disk
 Using $PIR table, 4 entries at 0xc00fde60
 npx0: &lt;math processor&gt; on motherboard   
 npx0: INT 16 interface   
 pcib0: &lt;Host to PCI bridge&gt; on motherboard
 pci0: &lt;PCI bus&gt; on pcib0
 pcib1:&lt;VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge&gt; at device 1.0 on pci0
 pci1: &lt;PCI bus&gt; on pcib1
 pci1: &lt;Matrox MGA G200 AGP graphics accelereator&gt; at 0.0 irq 11
 isab0: &lt;VIA 82C586 PCI-ISA bridge&gt; at device 7.0 on pci0
 isa0: &lt;iSA bus&gt; on isab0
 atapci0: &lt;VIA 82C586 ATA33 controller&gt; port 0xe000-0xe00f at device 7.1 on pci0
 ata0: at 0x1f0 irq 14 on atapci0
 ata1: at 0x170 irq 15 on atapci0
 uhci0 &lt;VIA 83C572 USB controller&gt; port 0xe400-0xe41f irq 10 at device 7.2 on pci
 0
 usb0: &lt;VIA 83572 USB controller&gt; on uhci0
 usb0: USB revision 1.0
 uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr1
 uhub0: 2 ports with 2 removable, self powered
 pci0: &lt;unknown card&gt; (vendor=0x1106, dev=0x3040) at 7.3
 dc0: &lt;ADMtek AN985 10/100BaseTX&gt; port 0xe800-0xe8ff mem 0xdb000000-0xeb0003ff ir
 q 11 at device 8.0 on pci0
 dc0: Ethernet address: 00:04:5a:74:6b:b5
 miibus0: &lt;MII bus&gt; on dc0
 ukphy0: &lt;Generic IEEE 802.3u media interface&gt; on miibus0
 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
 ed0: &lt;NE2000 PCI Ethernet (RealTek 8029)&gt; port 0xec00-0xec1f irq 9 at device 10.
 0 on pci0
 ed0 address 52:54:05:de:73:1b, type NE2000 (16 bit)
 isa0: too many dependant configs (8)
 isa0: unexpected small tag 14
 orm0: &lt;Option ROM&gt; at iomem 0xc0000-0xc7fff on isa0
 fdc0: &lt;NEC 72065B or clone&gt; at port 0x3f0-0x3f5,0x3f7 irq 6 drq2 on isa0
 fdc0: FIFO enabled, 8 bytes threshold
 fd0: &lt;1440-KB 3.5" drive&gt; on fdc0 drive 0
 atkbdc0: &lt;Keyboard controller (i8042)&gt; at port 0x60,0x64 on isa0
 atkbd0: &lt;AT Keyboard&gt; flags 0x1 irq1 on atkbdc0
 kbd0 at atkbd0
 psm0: &lt;PS/2 Mouse&gt; irq 12 on atkbdc0
 psm0: model Generic PS/@ mouse, device ID 0
 vga0: &lt;Generic ISA VGA&gt; at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0
 sc0: &lt;System console&gt; at flags 0x100 on isa0
 sc0: VGA &lt;16 virtual consoles, flags=0x300&gt;
 sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0
 sio0: type 16550A
 sio1 at port 0x2f8-0x2ff irq 3 on isa0
 sio1: type 16550A
 ppc0: &lt;Parallel port&gt; at port 0x378-0x37f irq 7 on isa0
 pppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode
 ppc0: FIFO with 16/16/15 bytes threshold
 plip0: &lt;PLIP network interfce&gt; on ppbus0
 ad0: 8063MB &lt;IBM-DHEA-38451&gt; [16383/16/63] at ata0-master UDMA33
 acd0: CD-RW &lt;LITE-ON LTR-1210B&gt; at ata1-slave PIO4
 Mounting root from ufs:/dev/md0c
 /stand/sysinstall running as init on vty0</screen>
       </figure>
 
       <para>Check the probe results carefully to make sure that FreeBSD found
 	all the devices you expected.  If a device was not found, then it will
 	not be listed.  If the device's driver required configuring
 	with the IRQ and port address then you should check that you entered
 	them correctly.</para>
 
       <para>If you need to make changes to the UserConfig device probing,
 	its easy to exit the <application>sysinstall</application> program
 	and start over again.  Its also a good way to become more familiar
 	with the process.</para>
 
       <figure id="sysinstall-exit">
 	<title>Select Sysinstall Exit</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/sysinstall-exit" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the arrow keys to select 
 	<guimenuitem>Exit Install</guimenuitem> from the Main
 	Install Screen menu.  The following message will display:</para>
 
 
       <screen>                      User Confirmation Requested 
          Are you sure you wish to exit? The system will reboot 
            (be sure to remove any floppies from the drives).
 
                             [ Yes ]    No</screen>
 
       <para>The install program will start again if the CDROM is left
 	in the drive and <guibutton>[Yes]</guibutton> is selected.</para>
 
       <para>If you are booting from floppies it will be necessary to remove
 	the <filename>mfsroot.flp</filename> floppy and replace it with
 	<filename>kern.flp</filename> before rebooting.</para>
     </sect2>
   </sect1>
 
   <sect1 id="using-sysinstall">
     <title>Introducing Sysinstall</title>
 
     <para>The <application>sysinstall</application> utility is the installation
       application provided by the FreeBSD Project.  It is console based and is
       divided into a number of menus and screens that you can use to
       configure and control the installation process.</para>
 
     <para>The <application>sysinstall</application> menu system is controlled
       by the arrow keys, <keycap>Enter</keycap>, <keycap>Space</keycap>, and
       other keys.  A detailed description of these keys, and what they do, is
       contained in <application>sysinstall's</application> usage 
       information.</para>
 
     <para>To review this information, ensure that the
       <guimenuitem>Usage</guimenuitem> entry is highlighted and that the
       <guibutton>[Select]</guibutton> button is selected, as shown in <xref
       linkend="sysinstall-main3">, then press <keycap>Enter</keycap>.</para>
 
     <para>The instructions for using the menu system will be displayed.  After
       reviewing them, press <keycap>Enter</keycap> to return to the Main
       Menu.</para>
 
     <figure id="sysinstall-main3">
       <title>Selecting Usage From Sysinstall Main Menu</title>
 
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="install/main1" format="PNG">
 	</imageobject>
       </mediaobject>
     </figure>
 
     <sect2 id="select-doc">
       <title>Selecting The Documentation Menu</title>
 
       <para>From the Main Menu, select <guimenuitem>Doc</guimenuitem> with
 	the arrow keys and
 	press <keycap>Enter</keycap>.</para>
 
       <figure id="main-doc">
 	<title>Selecting Documentation Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/main-doc" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>This will display the Documentation Menu.</para>
 
       <figure id="docmenu1">
 	<title>Sysinstall Documentation Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/docmenu1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>It is important to read the documents provided.</para>
 
       <para>To view a document, select it with the arrow keys and
 	press <keycap>Enter</keycap>.  When finished reading a document,
 	pressing <keycap>Enter</keycap> will return to the Documentation
 	Menu.</para>
 
       <para>To return to the Main Installation Menu, select
 	<guimenuitem>Exit</guimenuitem> with the 
 	arrow keys and press <keycap>Enter</keycap>.</para>
     </sect2>
 
     <sect2 id="keymap">
       <title>Selecting The Keymap Menu</title>
 
       <para>To change the keyboard mapping, use the arrow keys to select
 	<guimenuitem>Keymap</guimenuitem> from the menu and press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="sysinstall-keymap">
 	<title>Sysinstall Main Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/main-keymap" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>A different keyboard mapping may be chosen by selecting the
 	menu item using up/down arrow keys and pressing <keycap>Space</keycap>.
 	Pressing <keycap>Space</keycap> again will unselect the item.
 	When finished, choose the &gui.ok; using the arrow keys and press
 	<keycap>Enter</keycap>.</para>
 
       <para>Only a partial list is shown in this screen representation.
 	Selecting &gui.cancel; will use the default
 	keymap and return to the Main Install Menu.</para>
 
       <figure id="sysinstall-keymap-menu">
 	<title>Sysinstall Keymap Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/keymap" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
     </sect2>
 
     <sect2 id="viewsetoptions">
       <title>Installation Options Screen</title>
 
     <para>Select <guimenuitem>Options</guimenuitem> and press
 	<keycap>Enter</keycap>.</para>
 
     <figure id="sysinstall-options">
       <title>Sysinstall Main Menu</title>
 
       <mediaobject>
         <imageobject>
 	  <imagedata fileref="install/main-options" format="PNG">
 	</imageobject>
       </mediaobject>
     </figure>
 
       <figure id="options">
 	<title>Sysinstall Options</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/options" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The default values are usually fine for most users and do
 	not need to be changed.  The release name will vary according
 	to the version being installed.</para>
 
       <para>The description of the selected item will appear at the
 	bottom of the screen highlighted in blue.  Notice that one of the
 	options is <guimenuitem>Use Defaults</guimenuitem> to reset all
 	values to startup defaults.</para>
 
       <para>Press <keycap>F1</keycap> to read the help screen about the
 	various options.</para>
 
       <para>Pressing <keycap>Q</keycap> will return to the Main Install
 	menu.</para>
     </sect2>
 
     <sect2 id="start-install">
       <title>Begin A Standard Installation</title>
 
       <para>The <guimenuitem>Standard</guimenuitem> installation is the
 	option recommended for those new to Unix or FreeBSD.  Use the arrow
 	keys to select <guimenuitem>Standard</guimenuitem> and
 	then press <keycap>Enter</keycap> to start the installation.</para>
 
       <figure id="sysinstall-standard">
 	<title>Begin Standard Installation</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/main-std" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
     </sect2>
   </sect1>
 
   <sect1 id="install-steps">
     <title>Allocating Disk Space</title>
 
     <para>Your first task is to allocate disk space for FreeBSD, and label
       that space so that <application>sysinstall</application> can prepare
       it.  In order to do this you need to know how FreeBSD expects to find
       information on the disk.</para>
 
     <sect2 id="install-drive-bios-numbering">
       <title>BIOS Drive Numbering</title>
 
       <para>Before you install and configure FreeBSD on your system, there is an
 	important subject that you should be aware of, especially if you have
 	multiple hard drives.</para>
 
       <indexterm><primary>DOS</primary></indexterm>
       <indexterm><primary>Microsoft Windows</primary></indexterm>
       <para>In a PC running a BIOS-dependent operating system such as
 	MS-DOS or Microsoft Windows, the BIOS is able to abstract the
 	normal disk drive order, and
 	the operating system goes along with the change.  This allows the user
 	to boot from a disk drive other than the so-called <quote>primary
 	  master</quote>.  This is especially convenient for some users who have
 	found that the simplest and cheapest way to keep a system backup is to
 	buy an identical second hard drive, and perform routine copies of the
 	first drive to the second drive using 
 	<application>Ghost</application> or <application>XCOPY</application>
 	.  Then, if the
 	first drive fails, or is attacked by a virus, or is scribbled upon by an
 	operating system defect, he can easily recover by instructing the BIOS
 	to logically swap the drives.  It is like switching the cables on the
 	drives, but without having to open the case.</para>
 
       <indexterm><primary>SCSI</primary></indexterm>
       <indexterm><primary>BIOS</primary></indexterm>
       <para>More expensive systems with SCSI controllers often include BIOS
 	extensions which allow the SCSI drives to be re-ordered in a similar
 	fashion for up to seven drives.</para>
 
       <para>A user who is accustomed to taking advantage of these features may
 	become surprised when the results with FreeBSD are not as expected.
 	FreeBSD does not use the BIOS, and does not know the <quote>logical BIOS
 	  drive mapping</quote>.  This can lead to very perplexing situations,
 	especially when drives are physically identical in geometry, and have
 	also been made as data clones of one another.</para>
 
       <para>When using FreeBSD, always restore the BIOS to natural drive
 	numbering before installing FreeBSD, and then leave it that way.  If you
 	need to switch drives around, then do so, but do it the hard way, and
 	open the case and move the jumpers and cables.</para>
 
       <sidebar>
 	<title>An Illustration from the Files of Bill and Fred's Exceptional
 	  Adventures:</title>
       
 	<para>Bill breaks-down an older Wintel box to make another FreeBSD box
 	  for Fred.  Bill installs a single SCSI drive as SCSI unit zero and
 	  installs FreeBSD on it.</para>
 
 	<para>Fred begins using the system, but after several days notices that
 	  the older SCSI drive is reporting numerous soft errors and reports
 	  this fact to Bill.</para>
 
 	<para>After several more days, Bill decides it is time to address the
 	  situation, so he grabs an identical SCSI drive from the disk drive
 	  <quote>archive</quote> in the back room.  An initial surface scan
 	  indicates that
 	  this drive is functioning well, so Bill installs this drive as SCSI
 	  unit four and makes an image copy from drive zero to drive four.  Now
 	  that the new drive is installed and functioning nicely, Bill decides
 	  that it is a good idea to start using it, so he uses features in the
 	  SCSI BIOS to re-order the disk drives so that the system boots from
 	  SCSI unit four.  FreeBSD boots and runs just fine.</para>
 
 	<para>Fred continues his work for several days, and soon Bill and Fred
 	  decide that it is time for a new adventure -- time to upgrade to a
 	  newer version of FreeBSD.  Bill removes SCSI unit zero because it was
 	  a bit flaky and replaces it with another identical disk drive from
 	  the <quote>archive</quote>.  Bill then installs the new version of
 	  FreeBSD onto the new SCSI unit zero using Fred's magic Internet FTP
 	  floppies.  The installation goes well.</para>
 
 	<para>Fred uses the new version of FreeBSD for a few days, and certifies
 	  that it is good enough for use in the engineering department.  It is
 	  time to copy all of his work from the old version.  So Fred mounts
 	  SCSI unit four (the latest copy of the older FreeBSD version).  Fred
 	  is dismayed to find that none of his precious work is present on SCSI
 	  unit four.</para>
 
 	<para>Where did the data go?</para>
 
 	<para>When Bill made an image copy of the original SCSI unit zero onto
 	  SCSI unit four, unit four became the <quote>new clone</quote>.
 	  When Bill re-ordered the SCSI BIOS so that he could boot from
 	  SCSI unit four, he was only fooling himself.
 	  FreeBSD was still running on SCSI unit zero.
 	  Making this kind of BIOS change will cause some or all of the Boot and
 	  Loader code to be fetched from the selected BIOS drive, but when the
 	  FreeBSD kernel drivers take-over, the BIOS drive numbering will be
 	  ignored, and FreeBSD will transition back to normal drive numbering.
 	  In the illustration at hand, the system continued to operate on the
 	  original SCSI unit zero, and all of Fred's data was there, not on SCSI
 	  unit four.  The fact that the system appeared to be running on SCSI
 	  unit four was simply an artifact of human expectations.</para>
 
 	<para>We are delighted to mention that no data bytes were killed or
 	  harmed in any way by our discovery of this phenomenon.  The older SCSI
 	  unit zero was retrieved from the bone pile, and all of Fred's work was
 	  returned to him, (and now Bill knows that he can count as high as
 	  zero).</para>
 
 	<para>Although SCSI drives were used in this illustration, the concepts
 	  apply equally to IDE drives.</para>
       </sidebar>
     </sect2>
 
     <sect2>
       <title>Disk Organization</title>
 
       <para>The smallest unit of organization that FreeBSD uses to find files
 	is the filename.  Filenames are case-sensitive, which means that
 	<filename>readme.txt</filename> and <filename>README.TXT</filename>
 	are two separate files.  FreeBSD does not use the extension
 	(<filename>.txt</filename>) of a file to determine whether the file is
 	program, or a document, or some other form of data.</para>
 
       <para>Files are stored in directories.  A directory may contain no
 	files, or it may contain many hundreds of files.  A directory can also
 	contain other directories, allowing you to build up a hierarchy of
 	directories within one another.  This makes it much easier to organize
 	your data.</para>
 
       <para>Files and directories are referenced by giving the file or
 	directory name, followed by a forward slash, <literal>/</literal>,
 	followed by any other directory names that are necessary.  If you have
 	directory <filename>foo</filename>, which contains directory
 	<filename>bar</filename>, which contains the file
 	<filename>readme.txt</filename>, then the full name, or
 	<firstterm>path</firstterm> to the file is
 	<filename>foo/bar/readme.txt</filename>.</para>
 
       <para>Directories and files are stored in a filesystem.  Each filesystem
 	contains exactly one directory at the very top level, called the
 	<firstterm>root directory</firstterm> for that filesystem.  This root
 	directory can then contain other directories.</para>
 
       <para>So far this is probably similar to any other operating system you
 	may have used.  There are a few differences; for example, DOS uses
 	<literal>\</literal> to separate file and directory names, while MacOS
 	uses <literal>:</literal>.</para>
 
       <para>FreeBSD does not use drive letters, or other drive names in the
 	path.  You would not write <filename>c:/foo/bar/readme.txt</filename>
 	on FreeBSD.</para>
 
       <para>Instead, one filesystem is designated the <firstterm>root
 	  filesystem</firstterm>.  The root filesystem's root directory is
 	referred to as <literal>/</literal>.  Every other filesystem is then
 	<firstterm>mounted</firstterm> under the root filesystem.  No matter
 	how many disks you have on your FreeBSD system, every directory
 	appears to be part of the same disk.</para>
 
       <para>Suppose you have three filesystems, called <literal>A</literal>,
 	<literal>B</literal>, and <literal>C</literal>.  Each filesystem has
 	one root directory, which contains two other directories, called
 	<literal>A1</literal>, <literal>A2</literal> (and likewise
 	<literal>B1</literal>, <literal>B2</literal> and
 	<literal>C1</literal>, <literal>C2</literal>).</para>
 
       <para>Call <literal>A</literal> the root filesystem.  If you used the
 	<command>ls</command> command to view the contents of this directory
 	you would see two subdirectories, <literal>A1</literal> and
 	<literal>A2</literal>.  The directory tree looks like this:</para>
 
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="install/example-dir1" format="EPS">
 	</imageobject>
 
 	<textobject>
 	  <literallayout class="monospaced"> /
  |
  +--- A1
  |
  `--- A2</literallayout>
 	</textobject>
       </mediaobject>
 
       <para>A filesystem must be mounted on to a directory in another
 	filesystem.  So now suppose that you mount filesystem
 	<literal>B</literal> on to the directory <literal>A1</literal>.  The
 	root directory of <literal>B</literal> replaces <literal>A1</literal>,
 	and the directories in <literal>B</literal> appear accordingly:</para>
 
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="install/example-dir2" format="EPS">
 	</imageobject>
 
 	<textobject>
 	  <literallayout class="monospaced"> /
  | 
  +--- A1
  |     |
  |     +--- B1
  |     |
  |     `--- B2
  |
  `--- A2</literallayout>
 	</textobject>
       </mediaobject>
 
       <para>Any files that are in the <literal>B1</literal> or
 	<literal>B2</literal> directories can be reached with the path
 	<filename>/A1/B1</filename> or <filename>/A1/B2</filename> as
 	necessary.  Any files that were in <filename>/A1</filename> have been
 	temporarily hidden.  They will reappear if <literal>B</literal> is
 	<firstterm>unmounted</firstterm> from A.</para>
 
       <para>If <literal>B</literal> had been mounted on <literal>A2</literal>
 	then the diagram would look like this:</para>
 
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="install/example-dir3" format="EPS">
 	</imageobject>
 
 	<textobject>
 	  <literallayout class="monospaced"> /
  |
  +--- A1
  |
  `--- A2
        |
        +--- B1
        |
        `--- B2</literallayout>
 	</textobject>
       </mediaobject>
 
       <para>and the paths would be <filename>/A2/B1</filename> and
 	<filename>/A2/B2</filename> respectively.</para>
 
       <para>Filesystems can be mounted on top of one another.  Continuing the
 	last example, the <literal>C</literal> filesystem could be mounted on
 	top of the <literal>B1</literal> directory in the <literal>B</literal>
 	filesystem, leading to this arrangement:</para>
 
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="install/example-dir4" format="EPS">
 	</imageobject>
 	
 	<textobject>
 	  <literallayout class="monospaced"> /
  |
  +--- A1
  |
  `--- A2
        |
        +--- B1
        |     |
        |     +--- C1
        |     |
        |     `--- C2
        |
        `--- B2</literallayout>
 	</textobject>
       </mediaobject>
 
       <para>Or <literal>C</literal> could be mounted directly on to the
 	<literal>A</literal> filesystem, under the <literal>A1</literal>
 	directory:</para>
 
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="install/example-dir5" format="EPS">
 	</imageobject>
 
 	<textobject>
 	  <literallayout class="monospaced"> /
  |
  +--- A1
  |     |
  |     +--- C1
  |     |
  |     `--- C2
  |
  `--- A2
        |
        +--- B1
        |
        `--- B2</literallayout>
 	</textobject>
       </mediaobject>
 
       <para>If you are familiar with DOS, this is similar, although not
 	identical, to the <command>join</command> command.</para>
 
       <para>This is not normally something you need to concern yourself with.
 	Typically you create filesystems when installing FreeBSD and decide
 	where to mount them, and then never change them unless you add a new
 	disk.</para>
 
       <para>It is entirely possible to have one large root filesystem, and not
 	need to create any others.  There are some drawbacks to this approach,
 	and one advantage.</para>
 
       <itemizedlist>
 	<title>Benefits of multiple filesystems</title>
       
 	<listitem>
 	  <para>Different filesystems can have different <firstterm>mount
 	      options</firstterm>.  For example, with careful planning, the
 	    root filesystem can be mounted read-only, making it impossible for
 	    you to inadvertently delete or edit a critical file.</para>
 	</listitem>
 
 	<listitem>
 	  <para>FreeBSD automatically optimizes the layout of files on a
 	    filesystem, depending on how the filesystem is being used.  So a
 	    filesystem that contains many small files that are written
 	    frequently will have a different optimization to one that contains
 	    fewer, larger files.  By having one big filesystem this
 	    optimization breaks down.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>FreeBSD's filesystems are very robust should you lose power.
 	    However, a power loss at a critical point could still damage the
 	    structure of the filesystem.  By splitting your data over multiple
 	    filesystems it is more likely that the system will still come up,
 	    making it easier for you to restore from backup as
 	    necessary.</para>
 	</listitem>
       </itemizedlist>
 
       <itemizedlist>
 	<title>Benefit of a single filesystem</title>
 
 	<listitem>
 	  <para>Filesystems are a fixed size.  If you create a filesystem when
 	    you install FreeBSD and give it a specific size, you may later
 	    discover that you need to make the partition bigger.  This is not
 	    easily accomplished without backing up, recreating the filesystems
 	    with the size, and then restoring.</para>
 
 	  <important>
 	    <para>FreeBSD&nbsp;4.4 and up have a featured command, the
 	      &man.growfs.8;, which will makes it possible to
 	      increase the size of a filesystem on the fly, removing this
 	      limitation.</para>
 	  </important>
 	</listitem>
       </itemizedlist>
     
       <para>Filesystems are contained in partitions.  This does not have the
 	same meaning as the earlier usage of the term partition in this
 	chapter, because of FreeBSD's Unix heritage.  Each partition is
 	identified by a letter, <literal>a</literal> through to
 	<literal>h</literal>.  Each partition can only contain one filesystem,
 	which means that filesystems are often described by either their
 	typical mount point on the root filesystem, or the letter of the
 	partition they are contained in.</para>
 
       <para>FreeBSD also uses disk space for <firstterm>swap
 	  space</firstterm>.  Swap space provides FreeBSD with
 	<firstterm>virtual memory</firstterm>.  This allows your computer to
 	behave as though it has much more memory than it actually does.  When
 	FreeBSD runs out of memory it moves some of the data that is not
 	currently being used to the swap space, and moves it back in (moving
 	something else out) when it needs it.</para>
 
       <para>Some partitions have certain conventions associated with
 	them.</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Partition</entry>
 
 	      <entry>Convention</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><literal>a</literal></entry>
 
 	      <entry>Normally contains the root filesystem</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>b</literal></entry>
 
 	      <entry>Normally contains swap space</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>c</literal></entry>
 
 	      <entry>Normally the same size as the enclosing slice.  This
 		allows utilities that need to work on the entire slice (for
 		example, a bad block scanner) to work on the
 		<literal>c</literal> partition.  You would not normally create
 		a filesystem on this partition.</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>d</literal></entry>
 
 	      <entry>Partition <literal>d</literal> used to have a special
 		meaning associated with it, although that is now gone.  To
 		this day, some tools may operate oddly if told to work on
 		partition <literal>d</literal>, so
 		<application>sysinstall</application> will not normally create
 		partition <literal>d</literal>.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>Each partition-that-contains-a-filesystem is stored in what
 	FreeBSD calls a <firstterm>slice</firstterm>.  Slice is FreeBSD's term
 	for what were earlier called partitions, and again, this is because of
 	FreeBSD's Unix background.  Slices are numbered, starting at 1,
 	through to 4.</para>
 
 	<indexterm><primary>slices</primary></indexterm>
 	<indexterm><primary>partitions</primary></indexterm>
 	<indexterm><primary>dangerously dedicated</primary></indexterm>
 
       <para>Slice numbers follow
 	the device name, prefixed with an <literal>s</literal>,
 	starting at 1.  So <quote>da0<emphasis>s1</emphasis></quote>
 	is the first slice on the first SCSI drive.  There can only be
 	four physical slices on a disk, but you can have logical
 	slices inside physical slices of the appropriate type.  These
 	extended slices are numbered starting at 5, so
 	<quote>ad0<emphasis>s5</emphasis></quote> is the first
 	extended slice on the first IDE disk.  These devices are used by file
 	systems that expect to occupy a slice.</para> 
 
       <para>Slices, <quote>dangerously dedicated</quote> physical
 	drives, and other drives contain
 	<firstterm>partitions</firstterm>, which are represented as
 	letters from <literal>a</literal> to <literal>h</literal>.
 	This letter is appended to the device name, so
 	<quote>da0<emphasis>a</emphasis></quote> is the a partition on
 	the first da drive, which is <quote>dangerously dedicated</quote>.
 	<quote>ad1s3<emphasis>e</emphasis></quote> is the fifth partition
 	in the third slice of the second IDE disk drive.</para>
 	
       <para>Finally, each disk on the system is identified.  A disk name
 	starts with a code that indicates the type of disk, and then a number,
 	indicating which disk it is.  Unlike slices, disk numbering starts at
 	0.  Common codes that you will see are listed in 
 	<xref linkend="install-dev-codes">.</para>
 
       <para>When referring to a partition FreeBSD requires that you also name
 	the slice and disk that contains the partition, and when referring to
 	a slice you should also refer to the disk name.  Do this by listing
 	the disk name, <literal>s</literal>, the slice number, and then the
 	partition letter.  Examples are shown in 
 	<xref linkend="install-disk-slice-part">.</para>
 
       <para><xref linkend="install-concept-disk-model"> shows a conceptual
 	model of the disk layout that should help make things clearer.</para>
 
       <para>In order to install FreeBSD you must first configure the disk
 	slices, then create partitions within the slice you will use for
 	FreeBSD, and then create a filesystem (or swap space) in each
 	partition, and decide where that filesystem will be mounted.</para>
 
       <table frame="none" id="install-dev-codes">
 	<title>Disk Device Codes</title>
 
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Code</entry>
 	    
 	      <entry>Meaning</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><devicename>ad</devicename></entry>
 
 	      <entry>ATAPI (IDE) disk</entry>
 	    </row>
 
 	    <row>
 	      <entry><devicename>da</devicename></entry>
 	      
 	      <entry>SCSI direct access disk</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><devicename>acd</devicename></entry>
 	      
 	      <entry>ATAPI (IDE) CDROM</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><devicename>cd</devicename></entry>
 	      
 	      <entry>SCSI CDROM</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><devicename>fd</devicename></entry>
 	      
 	      <entry>Floppy disk</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
       
       <example id="install-disk-slice-part">
 	<title>Sample Disk, Slice, and Partition Names</title>
 	
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Name</entry>
 		
 		<entry>Meaning</entry>
 	      </row>
 	    </thead>
 	    
 	    <tbody>
 	      <row>
 		<entry><literal>ad0s1a</literal></entry>
 		
 		<entry>The first partition (<literal>a</literal>) on the first
 		  slice (<literal>s1</literal>) on the first IDE disk
 		  (<literal>ad0</literal>).</entry>
 	      </row>
 
 	      <row>
 		<entry><literal>da1s2e</literal></entry>
 		
 		<entry>The fifth partition (<literal>e</literal>) on the
 		  second slice (<literal>s2</literal>) on the second SCSI disk
 		  (<literal>da1</literal>).</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
       </example>
 
       <example id="install-concept-disk-model">
 	<title>Conceptual Model of a Disk</title>
 
 	<para>This diagram shows FreeBSD's view of the first IDE disk attached
 	  to the system.  Assume that the disk is 4&nbsp;GB in size, and contains
 	  two 2&nbsp;GB slices (DOS partitions).  The first slice contains a DOS
 	  disk, <devicename>C:</devicename>, and the second slice contains a
 	  FreeBSD installation.  This example FreeBSD installation has three
 	  partitions, and a swap partition.</para>
 
 	<para>The three partitions will each hold a filesystem.  Partition
 	  <literal>a</literal> will be used for the root filesystem,
 	  <literal>e</literal> for the <filename>/var</filename> directory
 	  hierarchy, and <literal>f</literal> for the
 	  <filename>/usr</filename> directory hierarchy.</para>
 
         <mediaobject>
           <imageobject>
             <imagedata fileref="install/disk-layout" format="EPS">
           </imageobject>
  
           <textobject>
 	    <literallayout class="monospaced">.-----------------.  --.
 |                 |    |
 |  DOS / Windows  |    |
 :                 :     >  First slice, ad0s1
 :                 :    |
 |                 |    |
 :=================:  ==:                               --.
 |                 |    |  Partition a, mounted as /      |
 |                 |     > referred to as ad0s2a          |
 |                 |    |                                 |
 :-----------------:  ==:                                 |
 |                 |    |  Partition b, used as swap      |
 |                 |     > referred to as ad0s2b          |
 |                 |    |                                 |
 :-----------------:  ==:                                 |  Partition c, no
 |                 |    |  Partition e, used as /var       > filesystem, all 
 |                 |     > referred to as ad0s2e          |  of FreeBSD slice,
 |                 |    |                                 |  ad0s2c
 :-----------------:  ==:                                 |
 |                 |    |                                 |
 :                 :    |  Partition f, used as /usr      |
 :                 :     > referred to as ad0s2f          |
 :                 :    |                                 |
 |                 |    |                                 |
 |                 |  --'                                 |
 `-----------------'                                    --'</literallayout>
           </textobject>
         </mediaobject>
       </example>
     </sect2>
 
 
     <sect2 id="main-fdisk">
       <title>Creating Slices using FDisk</title>
 
       <note>
 	<para>No changes you make at this point will be written to the disk.
 	  If you think you have made a mistake and want to start again you can
 	  use the menus to exit <application>sysinstall</application> and try
 	  again.  If you get confused and can not see how to exit you can
 	  always turn your computer off.</para>
       </note>
 
       <para>After choosing to begin a standard installation in
 	<application>sysinstall</application> you will be shown this
 	message:</para>
 
       <screen>                                 Message
  In the next menu, you will need to set up a DOS-style ("fdisk")
  partitioning scheme for your hard disk. If you simply wish to devote
  all disk space to FreeBSD (overwriting anything else that might be on
  the disk(s) selected) then use the (A)ll command to select the default
  partitioning scheme followed by a (Q)uit. If you wish to allocate only
  free space to FreeBSD, move to a partition marked "unused" and use the
  (C)reate command. 
                                 [  OK  ] 
 
                       [ Press enter or space ]</screen>
 
       <para>Press <keycap>Enter</keycap> as instructed.  You will then be
 	shown a list of all the hard drives that the kernel found when it
 	carried out the device probes.  
 	<xref linkend="sysinstall-fdisk-drive1"> shows an example from a
 	system with two IDE disks.  They have been called
 	<devicename>ad0</devicename> and <devicename>ad2</devicename>.</para>
 
       <figure id="sysinstall-fdisk-drive1">
 	<title>Select Drive for FDisk</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/fdisk-drive1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>You might be wondering why <devicename>ad1</devicename> is not
 	listed here.  Why has it been missed?</para>
 
       <para>Consider what would happen if you had two IDE hard disks, one
 	as the master on the first IDE controller, and one as the master on
 	the second IDE controller.  If FreeBSD numbered these as it found
 	them, as <devicename>ad0</devicename> and
 	<devicename>ad1</devicename> then everything would work.</para>
 
       <para>But if you then added a third disk, as the slave device on the
 	first IDE controller, it would now be <devicename>ad1</devicename>,
 	and the previous <devicename>ad1</devicename> would become
 	<devicename>ad2</devicename>.  Because device names (such as
 	<devicename>ad1s1a</devicename>) are used to find filesystems, you
 	may suddenly discover that some of your filesystems no longer
 	appear correctly, and you would need to change your FreeBSD
 	configuration.</para>
       
       <para>To work around this, the kernel can be configured to name IDE
 	disks based on where they are, and not the order in which they were
 	found.  With this scheme the master disk on the second IDE
 	controller will <emphasis>always</emphasis> be
 	<devicename>ad2</devicename>, even if there are no
 	<devicename>ad0</devicename> or <devicename>ad1</devicename>
 	devices.</para>
 
       <para>This configuration is the default for the FreeBSD kernel, which
 	is why this display shows <devicename>ad0</devicename> and
 	<devicename>ad2</devicename>.  The machine on which this screenshot
 	was taken had IDE disks on both master channels of the IDE
 	controllers, and no disks on the slave channels.</para>
 
       <para>You should select the disk on which you want to install FreeBSD,
 	and then press &gui.ok;.
 	<application>FDisk</application> will start, with a display similar to
 	that shown in <xref linkend="sysinstall-fdisk1">.</para>
 
       <para>The <application>FDisk</application> display is broken into three
 	sections.</para>
 
       <para>The first section, covering the first two lines of the display,
 	shows details about the currently selected disk, including its FreeBSD
 	name, the disk geometry, and the total size of the disk.</para>
 
       <para>The second section shows the slices that are currently on the
 	disk, where they start and end, how large they are, the name FreeBSD
 	gives them, and their description and sub-type.  This example shows two
 	small unused slices, which are artifacts of disk layout schemes on the
 	PC.  It also shows one large FAT slice, which almost certainly appears
 	as <devicename>C:</devicename> in DOS / Windows, and an extended
 	slice, which may contain other drive letters for DOS / Windows.</para>
 
       <para>The third section shows the commands that are available in
 	<application>FDisk</application>.</para>
 
       <figure id="sysinstall-fdisk1">
 	<title>Typical Fdisk Partitions Before Editing</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/fdisk-edit1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>What you do now will depend on how you want to slice up your
 	disk.</para>
 
       <para>If you want to use FreeBSD for the entire disk (which will delete
 	all the other data on this disk when you confirm that you want
 	<application>sysinstall</application> to continue later in the
 	installation process) then you can press <keycap>A</keycap>, which
 	corresponds to the <guimenuitem>Use Entire Disk</guimenuitem> option.
 	The existing slices will be removed, and replaced with a small area
 	flagged as <literal>unused</literal> (again, an artifact of PC disk
 	layout), and then one large slice for FreeBSD.  If you do this then
 	you should then select the newly created FreeBSD slice using the arrow
 	keys, and press <keycap>S</keycap> to mark the slice as being
 	bootable.  The screen will then look very similar to 
 	<xref linkend="sysinstall-fdisk2">.  Note the
 	<literal>A</literal> in the <literal>Flags</literal> column, which
 	indicates that this slice is <emphasis>active</emphasis>, and will be
 	booted from.</para>
 
       <para>If you will be deleting an existing slice to make space for
 	FreeBSD then you should select the slice using the arrow keys, and
 	then press <keycap>D</keycap>.  You can then press <keycap>C</keycap>,
 	and be prompted for size of slice you want to create.  Enter the
 	appropriate figure and press <keycap>Enter</keycap>.</para>
       
       <para>If you have already made space for FreeBSD (perhaps by using a
 	tool such as <application>Partition Magic</application>) then you can
 	press <keycap>C</keycap> to create a new slice.  Again, you will be
 	prompted for the size of slice you would like to create.</para>
 
       <figure id="sysinstall-fdisk2">
 	<title>Fdisk Partition Using Entire Disk</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/fdisk-edit2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>When finished, press <keycap>Q</keycap>.  Your changes will be
 	saved in <application>sysinstall</application>, but will not yet be
 	written to disk.</para>
     </sect2>
 
     <sect2 id="bootmgr">
       <title>Install a Boot Manager</title>
 
       <para>You now have the option to install a boot manager.  In general,
 	you should choose to install the FreeBSD boot manager if:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>You have more than one drive, and have installed FreeBSD onto
 	    a drive other than the first one.</para>
 	</listitem>
 
 	<listitem>
 	  <para>You have installed FreeBSD alongside another operating system
 	    on the same disk, and you want to choose whether to start FreeBSD
 	    or the other operating system when you start the computer.</para>
 	</listitem>
       </itemizedlist>
 
       <para>Make your choice and press <keycap>Enter</keycap>.</para>
 
       <figure id="sysinstall-bootmgr">
 	<title>Sysinstall Boot Manager Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/boot-mgr" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The help screen, reached by pressing <keycap>F1</keycap>,
 	discusses the problems that can be encountered when trying to share
 	the hard disk between operating systems.</para>
     </sect2>
 
     <sect2>
       <title>Creating Slices on Another Drive</title>
 
       <para>If there is more than one drive, it will return to the
 	Select Drives screen after the boot manager selection.  If you wish to
 	install FreeBSD on to more than one disk, then you can select another
 	disk here and repeat the slice process using
 	<application>FDisk</application>.</para>
 
       <figure id="sysinstall-fdisk-drive2">
 	<title>Exit Select Drive</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/fdisk-drive2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The <keycap>Tab</keycap> key toggles between the last drive
 	selected, &gui.ok;, and 
 	&gui.cancel;.</para>
 
       <para>Press the <keycap>Tab</keycap> once to toggle to the
 	&gui.ok;, then
 	press <keycap>Enter</keycap>
 	to continue with the installation.</para>
     </sect2>
 
     <sect2 id="disklabeleditor">
       <title>Creating Partitions using
 	<application>Disklabel</application></title>
       
       <para>You must now create some partitions inside each slice that you
 	have just created.  Remember that each partition is lettered, from
 	<literal>a</literal> through to <literal>h</literal>, and that
 	partitions <literal>b</literal>, <literal>c</literal>, and
 	<literal>d</literal> have conventional meanings that you should adhere
 	to.</para>
 
       <para>Certain applications can benefit from particular partition
 	schemes, especially if you are laying out partitions across more than
 	one disk.  However, for this, your first FreeBSD installation, you do
 	not need to give too much thought to how you partition the disk.  It
 	is more important that you install FreeBSD and start learning how to
 	use it.  You can always re-install FreeBSD to change your partition
 	scheme when you are more familiar with the operating system.</para>
 
       <para>This scheme features four partitions&mdash;one for swap space, and
 	three for filesystems.</para>
 
       <table frame="none">
 	<title>Partition Layout for First Disk</title>
 
 	<tgroup cols="4">
 	  <thead>
 	    <row>
 	      <entry>Partition</entry>
 	      
 	      <entry>Filesystem</entry>
 
 	      <entry>Size</entry>
 
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><literal>a</literal></entry>
 
 	      <entry><filename>/</filename></entry>
 
 	      <entry>100&nbsp;MB</entry>
 
 	      <entry>This is the root filesystem.  Every other filesystem
 		will be mounted somewhere under this one.  100&nbsp;MB is a
 		reasonable size for this filesystem.  You will not be storing
 		too much data on it, as a regular FreeBSD install will put
 		about 40&nbsp;MB of data here.  The remaining space is for temporary
 		data, and also leaves expansion space if future versions of
 		FreeBSD need more space in <filename>/</filename>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>b</literal></entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>2-3 x RAM</entry>
 
 	      <entry><para>The system's swap space is kept on this partition.
 		  Choosing the right amount of swap space can be a bit of an
 		  art.  A good rule of thumb is that your swap
 		  space should be two or three times as much as the
 		  available physical memory (RAM).
 		  You should also have at least 64&nbsp;MB of swap, so if you have
 		  less than 32&nbsp;MB of RAM in your computer then set the swap
 		  amount to 64&nbsp;MB.</para><para>
 
 		  If you have more than one disk then you can put swap
 		  space on each disk.  FreeBSD will then use each disk for 
 		  swap, which effectively speeds up the act of swapping.  In
 		  this case, calculate the total amount of swap you need
 		  (e.g., 128&nbsp;MB), and then divide this by the number of disks
 		  you have (e.g., two disks) to give the amount of swap you
 		  should put on each disk, in this example, 64&nbsp;MB of swap per
 		  disk.</para></entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>e</literal></entry>
 
 	      <entry><filename>/var</filename></entry>
 
 	      <entry>50&nbsp;MB</entry>
 
 	      <entry>The <filename>/var</filename> directory contains variable
 		length files; log files, and other administrative files.  Many
 		of these files are read-from or written-to extensively during
 		FreeBSD's day-to-day running.  Putting these files on another
 		filesystem allows FreeBSD to optimise the access of these
 		files without affecting other files in other directories that
 		do not have the same access pattern.</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>f</literal></entry>
 
 	      <entry><filename>/usr</filename></entry>
 
 	      <entry>Rest of disk</entry>
 
 	      <entry>All your other files will typically be stored in
 		<filename>/usr</filename>, and its subdirectories.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
       
       <para>If you will be installing FreeBSD on to more than one disk then
 	you must also create partitions in the other slices that you
 	configured.  The easiest way to do this is to create two partitions on
 	each disk, one for the swap space, and one for a filesystem.</para>
 
       <table frame="none">
 	<title>Partition Layout for Subsequent Disks</title>
 
 	<tgroup cols="4">
 	  <thead>
 	    <row>
 	      <entry>Partition</entry>
 	      
 	      <entry>Filesystem</entry>
 
 	      <entry>Size</entry>
 
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><literal>b</literal></entry>
 
 	      <entry>N/A</entry>
 
 	      <entry>See description</entry>
 
 	      <entry>As already discussed, you can split swap space across
 		each disk.  Even though the <literal>a</literal> partition is
 		free, convention dictates that swap space stays on the
 		<literal>b</literal> partition.</entry>
 	    </row>
 
 	    <row>
 	      <entry><literal>e</literal></entry>
 
 	      <entry>/disk<replaceable>n</replaceable></entry>
 
 	      <entry>Rest of disk</entry>
 
 	      <entry>The rest of the disk is taken up with one big partition.
 		This could easily be put on the <literal>a</literal>
 		partition, instead of the <literal>e</literal> partition.
 		However, convention says that the <literal>a</literal>
 		partition on a slice is reserved for the filesystem that will
 		be the root (<filename>/</filename>) filesystem.  You do not
 		have to follow this convention, but
 		<application>sysinstall</application> does, so following it
 		yourself makes the installation slightly cleaner.  You can
 		choose to mount this filesystem anywhere; this example
 		suggests that you mount them as directories
 		<filename>/disk<replaceable>n</replaceable></filename>, where
 		<replaceable>n</replaceable> is a number that changes for each
 		disk.  But you can use another scheme if you prefer.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
       <para>Having chosen your partition layout you can now create it using
 	<application>sysinstall</application>.  You will see this
 	message:</para>
 
       <screen>                                 Message
  Now, you need to create BSD partitions inside of the fdisk
  partition(s) just created. If you have a reasonable amount of disk
  space (200MB or more) and don't have any special requirements, simply
  use the (A)uto command to allocate space automatically. If you have
  more specific needs or just don't care for the layout chosen by
  (A)uto, press F1 for more information on manual layout.  
 
                                 [  OK  ]
                           [ Press enter or space ]</screen>
 
       <para>Press <keycap>Enter</keycap> to start the FreeBSD partition
 	editor, called <application>Disklabel</application>.</para>
 
       <para><xref linkend="sysinstall-label"> shows the display when you first
 	start <application>Disklabel</application>.  The display is divided in
 	to three sections.</para>
 
       <para>The first few lines show the name of the disk you are currently
 	working on, and the slice that contains the partitions you are
 	creating (at this point <application>Disklabel</application> calls
 	this the <literal>Partition name</literal> rather than slice name).
 	This display also shows the amount of free space within the slice;
 	that is, space that was set aside in the slice, but that has not yet
 	been assigned to a partition.</para>
 
       <para>The middle of the display shows the partitions that have been
 	created, the name of the filesystem that each partition contains,
 	their size, and some options pertaining to the creation of the
 	filesystem.</para>
 
       <para>The bottom third of the screen shows the keystrokes that are valid
 	in <application>Disklabel</application>.</para>
 
       <figure id="sysinstall-label">
 	<title>Sysinstall Disklabel Editor</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-ed1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para><application>Disklabel</application> can automatically create
 	partitions for you and assign them default sizes.  Try this now, by
 	Pressing <keycap>A</keycap>.  You will see a display similar to that
 	shown in <xref linkend="sysinstall-label2">.  Depending on the size of
 	the disk you are using the defaults may or may not be appropriate.
 	This does not matter, as you do not have to accept the
 	defaults.</para>
 
 	<note>
 	  <para>Beginning with FreeBSD&nbsp;4.5, the default partitioning assigns
 	    the <filename>/tmp</filename> directory its own partition instead
 	    of being part of the <filename>/</filename> partition.  This
 	    helps avoid filling the <filename>/</filename> partition with
 	    temporary files.</para>
 	</note>
 
       <figure id="sysinstall-label2">
 	<title>Sysinstall Disklabel Editor With Auto Defaults</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-auto" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>To delete the suggested partitions, and replace them with your
 	own, use the arrow keys to select the first partition, and press
 	<keycap>D</keycap> to delete it.  Repeat this to delete all the
 	suggested partitions.</para>
 
       <para>To create the first partition (<literal>a</literal>, mounted as
 	<filename>/</filename>), make sure the disk information at the top of
 	the screen is selected, and press <keycap>C</keycap>.  A dialog box
 	will appear prompting you for the size of the new partition (as shown
 	in <xref linkend="sysinstall-label-add">).  You can enter the size as
 	the number of disk blocks you want to use, or, more usefully, as a
 	number followed by either <literal>M</literal> for megabytes,
 	<literal>G</literal> for gigabytes, or <literal>C</literal> for
 	cylinders.</para>
 
       <note><para>Beginning with FreeBSD 5.x, users can select
 	<acronym>UFS2</acronym> using the Custom Newfs
 	(<keycap>Z</keycap>) option.  Either create labels with
 	Auto Defaults and modify them with the Custom Newfs option, or
 	add <option>-O 2</option> during the regurlar creation period.
 	Do not forget to add -U for softupdates if you use the Custom Newfs
 	option!</para></note>
 
       <figure id="sysinstall-label-add">
 	<title>Free Space For Root Partition</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-root1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The default size shown will create a partition that takes up the
 	rest of the slice.  If you are using the partition sizes described
 	earlier, then delete the existing figure using
 	<keycap>Backspace</keycap>, and then type in
 	<userinput>64M</userinput>, as shown in 
 	<xref linkend="sysinstall-label-add2">.  Then press
 	&gui.ok;.</para>
       
       <figure id="sysinstall-label-add2">
 	<title>Edit Root Partition Size</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-root2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Having chosen the partition's size you will then asked whether
 	this partition will contain a filesystem or swap space.  The dialog
 	box is shown in <xref linkend="sysinstall-label-type">.  This first
 	partition will contain a filesystem, so check that
 	<guimenuitem>FS</guimenuitem> is selected and then press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="sysinstall-label-type">
 	<title>Choose The Root Partition Type</title>
 	
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-fs" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
       
       <para>Finally, because you are creating a filesystem, you must tell
 	<application>Disklabel</application> where the filesystem is to be
 	mounted.  The dialog box is shown in 
 	<xref linkend="sysinstall-label-mount">.  The root filesystem's mount
 	point is <filename>/</filename>, so type <userinput>/</userinput>, and
 	then press <keycap>Enter</keycap>.</para>
 
       <figure id="sysinstall-label-mount">
 	<title>Choose The Root Mount Point</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-root3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The display will then update to show you the newly created
 	partition.  You should repeat this procedure for the other
 	partitions.  When you create the swap partition you will not be
 	prompted for the filesystem mount point, as swap partitions are never
 	mounted.  When you create the final partition,
 	<filename>/usr</filename>, you can leave the suggested size as is, to
 	use the rest of the slice.</para>
 
       <para>Your final FreeBSD DiskLabel Editor screen will appear similar to
 	<xref linkend="sysinstall-label4">, although your values chosen may
 	be different.  Press <keycap>Q</keycap> to finish.</para>
 
       <figure id="sysinstall-label4">
 	<title>Sysinstall Disklabel Editor</title>
 	
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/disklabel-ed2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="install-choosing">
     <title>Choosing What To Install</title>
 
     <sect2 id="distset">
       <title>Select The Distribution Set</title>
 
       <para>Deciding which distribution set to install will depend largely
 	on the intended use of the system and the amount of disk space
 	available.  The predefined options range from installing the
 	smallest possible configuration to everything.  Those who are
 	new to Unix and/or FreeBSD should almost certainly select one
 	of these canned options.  Customizing a distribution set is
 	typically for the more experienced user.</para>
 
       <para>Press <keycap>F1</keycap> for more information on the 
 	distribution set options and what they contain.  When finished
 	reviewing the help, pressing <keycap>Enter</keycap> will return
 	to the Select Distributions Menu.</para>
 
       <para>If a graphical user interface is desired then a distribution
 	set that is preceded by an <literal>X</literal> should be
 	chosen.  The configuration of <application>XFree86</application> and selection of a default
 	desktop is part of the post-installation steps.</para>
 
       <para>The default version of <application>XFree86</application> that is installed depends on the
 	version of the FreeBSD that you are installing.  For FreeBSD versions
 	prior to 4.6, <application>XFree86 3.X</application> is installed.  For FreeBSD&nbsp;4.6 and later,
 	<application>XFree86 4.X</application> is the default.</para>
 
       <para>You should check to see whether your video card is supported at the
 	<ulink url="http://www.xfree86.org/">XFree86</ulink> web site.  If it
 	is not supported under the default version that FreeBSD will install,
 	you should select a distribution without X for installation.  After
 	installation, install and configure the appropriate version of 
 	<application>XFree86</application> using the ports collection.</para>
 
       <para>If compiling a custom kernel is anticipated, select an option
 	which includes the source code.  For more information on why a
 	custom kernel should be built or how to build a custom kernel see
 	<xref linkend="kernelconfig">.</para>
 
       <para>Obviously, the most versatile system is one that includes
 	everything.  If there is adequate disk space, select 
 	<guimenuitem>All</guimenuitem> as shown in
 	<xref linkend="distribution-set1"> by using the arrow keys and
 	press <keycap>Enter</keycap>.  If there is a concern about disk
 	space consider using an option that is more suitable for the
 	situation.  Other distributions can be added after installation.</para>
 
       <figure id="distribution-set1">
 	<title>Choose Distributions</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/dist-set" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
     </sect2>
 
     <sect2 id="portscol">
       <title>Installing The Ports Collection</title>
 
       <para>After selecting the desired distribution, an opportunity to
 	install the FreeBSD Ports Collection is presented.  The ports
 	collection is an easy and convenient way to install software.
 	The ports collection does not contain the source code necessary
 	to compile the software.  It is a collection of files which
 	automates the downloading, compiling and installation.
 	<xref linkend="ports"> discusses how to use the ports
 	collection.</para>
 
       <para>The installation program does not check to see if you have
 	adequate space.  Select this option only if you have
 	adequate hard disk space.</para>
 
 <screen>                         User Confirmation Requested
  Would you like to install the FreeBSD ports collection? 
 
  This will give you ready access to over &os.numports; ported software packages,
  at a cost of around &ports.size; of disk space when "clean" and possibly much
  more than that if a lot of the distribution tarballs are loaded
  (unless you have the extra CDs from a FreeBSD CD/DVD distribution
  available and can mount it on /cdrom, in which case this is far less
  of a problem). 
 
  The ports collection is a very valuable resource and well worth having
  on your /usr partition, so it is advisable to say Yes to this option. 
 
  For more information on the ports collection & the latest ports,
  visit: 
      http://www.FreeBSD.org/ports  
 
                               [ Yes ]     No</screen>
 
       <para>Select <guibutton>[ Yes ]</guibutton> with the arrow keys to
 	install the ports collection or <guibutton>[ No ]</guibutton> to
 	skip this option.  Press <keycap>Enter</keycap> to continue.
 	The Choose Distributions menu will redisplay.</para>
 
       <figure id="distribution-set2">
 	<title>Confirm Distributions</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/dist-set2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>If satisfied with the options, select
 	<guimenuitem>Exit</guimenuitem> with the arrow keys, ensure that
 	&gui.ok; is highlighted, and press
 	<keycap>Enter</keycap> to continue.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="install-media">
     <title>Choosing Your Installation Media</title>
 
     <para>If Installing from a CDROM, use the arrow keys to highlight 
       <guimenuitem>Install from a FreeBSD CD/DVD</guimenuitem>.  Ensure
       that &gui.ok; is highlighted, then press
       <keycap>Enter</keycap> to proceed with the installation.</para>
     
     <para>For other methods of installation, select the appropriate
       option and follow the instructions.</para>
 
     <para>Press <keycap>F1</keycap> to display the Online Help for
       installation media.  Press <keycap>Enter</keycap> to return
       to the media selection menu.</para>
 
     <figure id="choose-media">
       <title>Choose Installation Media</title>
 
       <mediaobject>
 	<imageobject>
 	  <imagedata fileref="install/media" format="PNG">
 	</imageobject>
       </mediaobject>
     </figure>
 
     <note>
       <title>FTP Installation Modes</title>
 
       <indexterm>
 	<primary>installation</primary>
 	<secondary>network</secondary>
 	<tertiary>FTP</tertiary>
       </indexterm>
       
       <para>There are three FTP installation modes you can choose from:
 	active FTP, passive FTP, or via a HTTP proxy.</para>
 
       <variablelist>
 	<varlistentry>
 	  <term>FTP Active, <guimenuitem>Install from an FTP
 	      server</guimenuitem></term>
 	  
 	  <listitem>
 	    <para>This option will make all FTP transfers 
 	      use <quote>Active</quote>
 	      mode.  This will not work through firewalls, but will
 	      often work with older FTP servers that do not support
 	      passive mode.  If your connection hangs with passive
 	      mode (the default), try active!</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term>FTP Passive, <guimenuitem>Install from an FTP server through a
 	      firewall</guimenuitem></term>
 	  
 	  <listitem>
 	    <indexterm>
 	      <primary>FTP</primary>
 	      <secondary>Passive mode</secondary>
 	    </indexterm>
 
 	    <para>This option instructs FreeBSD to use 
 	      <quote>Passive</quote> mode for all FTP operations.  
 	      This allows the user to pass through firewalls
 	      that do not allow incoming connections on random port
 	      addresses.</para>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term>FTP via a HTTP proxy, <guimenuitem>Install from an FTP server
 	      through a http proxy</guimenuitem></term>
 	    
 	  <listitem>
 	    <indexterm>
 	      <primary>FTP</primary>
 	      <secondary>via a HTTP proxy</secondary>
 	    </indexterm>
 	    
 	    <para>This option instructs FreeBSD to use the HTTP
 	      protocol (like a web browser) to connect to a proxy
 	      for all FTP operations.  The proxy will translate
 	      the requests and send them to the FTP server.
 	      This allows the user to pass through firewalls
 	      that do not allow FTP at all, but offer a HTTP
 	      proxy.
 	      In this case, you have to specify the proxy in
 	      addition to the FTP server.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <para>For a proxy FTP server, you should usually give the name of the
 	server you really want as a part of the username, after an
 	<quote>@</quote> sign.  The proxy server then <quote>fakes</quote>
 	the real server.  For example, assuming you want to install from
 	<hostid role="fqdn">ftp.FreeBSD.org</hostid>, using the proxy FTP
 	server <hostid role="fqdn">foo.example.com</hostid>, listening on port
 	1024.</para>
       
       <para>In this case, you go to the options menu, set the FTP username
 	to <literal>ftp@ftp.FreeBSD.org</literal>, and the password to your
 	email address.  As your installation media, you specify FTP (or
 	passive FTP, if the proxy supports it), and the URL
 	<literal>ftp://foo.example.com:1234/pub/FreeBSD</literal>.</para>
 
       <para>Since <filename>/pub/FreeBSD</filename> from 
 	<hostid role="fqdn">ftp.FreeBSD.org</hostid> is proxied under 
 	<hostid role="fqdn">foo.example.com</hostid>, you are able to install
 	from <emphasis>that</emphasis> machine (which will fetch the files
 	from <hostid role="fqdn">ftp.FreeBSD.org</hostid> as your 
 	installation requests them).</para>
     </note>
   </sect1>
 
   <sect1 id="install-final-warning">
     <title>Committing to the Installation</title>
 
     <para>The installation can now proceed if desired.  This is also
       the last chance for aborting the installation to prevent changes
       to the hard drive.</para>
 
     <screen>                       User Confirmation Requested
  Last Chance! Are you SURE you want to continue the installation? 
 
  If you're running this on a disk with data you wish to save then WE
  STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! 
 
  We can take no responsibility for lost disk contents!  
 
                              [ Yes ]    No</screen>
 
     <para>Select <guibutton>[ Yes ]</guibutton> and press 
       <keycap>Enter</keycap> to proceed.</para>
 
     <para>The installation time will vary according to the distribution
       chosen, installation media used, and the speed of the computer.
       There will be a series of
       messages displayed indicating the status.</para>
     
     <para>The installation is complete when the following message is
       displayed:</para>
 
     <screen>                               Message 
 
 Congratulations! You now have FreeBSD installed on your system. 
 
 We will now move on to the final configuration questions. 
 For any option you do not wish to configure, simply select No. 
 
 If you wish to re-enter this utility after the system is up, you may
 do so by typing: /stand/sysinstall .  
 
                                  [ OK ] 
 
                       [  Press enter to continue  ]</screen>
 
     <para>Press <keycap>Enter</keycap> to proceed with post-installation
       configurations.</para>
 
     <para>Selecting <guibutton>[ No ]</guibutton> and pressing
       <keycap>Enter</keycap> will abort
       the installation so no changes will be made to your system.  The
       following message will appear:</para>
 
     <screen>                                Message
 Installation complete with some errors.  You may wish to scroll
 through the debugging messages on VTY1 with the scroll-lock feature. 
 You can also choose "No" at the next prompt and go back into the
 installation menus to try and retry whichever operations have failed. 
 
                                  [ OK ]</screen>
 
     <para>This message is generated because nothing was installed.
       Pressing <keycap>Enter</keycap> will return to the
       Main Installation Menu to exit the installation.</para>
   </sect1>
 
   <sect1 id="install-post">
     <title>Post-installation</title>
 
     <para>Configuration of various options follows the successful 
       installation.    An option can be configured by re-entering the
       configuration options before booting the new FreeBSD
       system or after installation using
       <command>/stand/sysinstall</command> and selecting
       <guimenuitem>Configure</guimenuitem>.</para>
 
     <sect2 id="inst-network-dev">
       <title>Network Device Configuration</title>
 
       <para>If you previously configured PPP for an FTP install, this screen
 	will not display and can be configured later as described
 	above.</para>
 
       <para>For detailed information on Local Area Networks and
 	configuring FreeBSD as a gateway/router refer to the
 	<link linkend="advanced-networking">Advanced Networking</link>
 	chapter.</para>
 
       <screen>                      User Confirmation Requested 
    Would you like to configure any Ethernet or SLIP/PPP network devices?
 
                              [ Yes ]   No</screen>
 
       <para>To configure a network device, select
 	<guibutton>[ Yes ]</guibutton> and press <keycap>Enter</keycap>.
       Otherwise, select <guibutton>[ No ]</guibutton> to continue.</para>
 
       <figure id="ed-config1">
 	<title>Selecting An Ethernet Device</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/ed0-conf" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select the interface to be configured with the arrow keys and press
 	<keycap>Enter</keycap>.</para>
 
       <screen>                      User Confirmation Requested 
        Do you want to try IPv6 configuration of the interface?
 
                               Yes   [ No ]</screen>
 
       <para>In this private local area network the current Internet
 	type protocol (IPv4) was sufficient and <guibutton>[ No ]</guibutton>
 	was selected with the arrow keys and <keycap>Enter</keycap>
 	pressed.</para>
 
       <para>If you want to try the new Internet protocol (IPv6), choose
 	<guibutton>[ Yes ]</guibutton> and press <keycap>Enter</keycap>.
 	It will take several seconds to scan for RA servers.</para>
 
       <screen>                             User Confirmation Requested 
         Do you want to try DHCP configuration of the interface?
 
                               Yes   [ No ]</screen>
 
       <para>If DHCP (Dynamic Host Configuration Protocol) is not required
 	select <guibutton>[ No ]</guibutton> with the arrow keys and press
 	<keycap>Enter</keycap>.</para>
 
       <para>Selecting <guibutton>[ Yes ]</guibutton> will execute
 	<application>dhclient</application>, and if successful, will fill
 	in the network configuration information automatically.  Refer to
 	<xref linkend="dhcp"> for more information.</para>
 
       <para>The following Network Configuration screen shows the
 	configuration of the Ethernet device for a system that will act
 	as the gateway for a Local Area Network.</para>
 
       <figure id="ed-config2">
 	<title>Set Network Configuration For ed0</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/ed0-conf2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use <keycap>Tab</keycap> to select the information fields and
 	fill in appropriate information:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term>Host</term>
 
 	  <listitem>
 	    <para>The fully-qualified hostname, e.g. k6-2.example.com in
 	      this case.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Domain</term>
 
 	  <listitem>
 	    <para>The name of the domain that your machine is
 	      in, e.g. example.com for this case.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>IPv4 Gateway</term>
 
 	  <listitem>
 	    <para>IP address of host forwarding packets to non-local
 	      destinations.  Fill this in only if the machine is a node
 	      on the network.  <emphasis>Leave this field blank</emphasis>
 	      if the machine is the gateway to the Internet for the
 	      network.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Name server</term>
 
 	  <listitem>
 	    <para>IP address of your local DNS server.  There is no local
 	      DNS server on this private local area network so the IP
 	      address of the provider's DNS server
 	      (<hostid role="ipaddr">208.163.10.2</hostid>) was used.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>IPv4 address</term>
 
 	  <listitem>
 	    <para>The IP address to be used for this interface was
 	      <hostid role="ipaddr">192.168.0.1</hostid></para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Netmask</term>
 
 	  <listitem>
 	    <para>The address block being used for this local area
 	      network is a Class C block
 	      (<hostid role="ipaddr">192.168.0.0</hostid> -
 	      <hostid role="ipaddr">192.168.255.255</hostid>).
 	      The default netmask is for a Class C network
 	      (<hostid role="netmask">255.255.255.0</hostid>).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Extra options to ifconfig</term>
 
 	  <listitem>
 	    <para>Any interface-specific options to <command>ifconfig</command>
 	      you would like to add.  There were none in this case.</para>
 	  </listitem>
 	</varlistentry>
 
       </variablelist>
 
       <para>Use <keycap>Tab</keycap> to select &gui.ok;
 	when finished and press <keycap>Enter</keycap>.</para>
 
 
       <screen>                      User Confirmation Requested 
         Would you like to Bring Up the ed0 interface right now?
 
                              [ Yes ]   No</screen>
 
       <para>Choosing <guibutton>[ Yes ]</guibutton> and pressing
 	<keycap>Enter</keycap> will bring
 	the machine up on the network and be ready for use after leaving
 	the installation.</para>
     </sect2>
 
     <sect2 id="gateway">
       <title>Configure Gateway</title>
 
       <screen>                       User Confirmation Requested 
        Do you want this machine to function as a network gateway?
 
                               [ Yes ]    No</screen>
 
       <para>If the machine will be acting as the gateway for a local area
 	network and forwarding packets between other machines then select
 	<guibutton>[ Yes ]</guibutton> and press <keycap>Enter</keycap>.
 	If the machine is a node on a network then 
 	select <guibutton>[ No ]</guibutton> and press
 	<keycap>Enter</keycap> to continue.</para>
     </sect2>
 
     <sect2 id="inetd-services">
       <title>Configure Internet Services</title>
 
       <screen>                      User Confirmation Requested
 Do you want to configure inetd and the network services that it provides?
 
                                Yes   [ No ]</screen>
 
       <para>If <guibutton>[ No ]</guibutton> is selected, various services
 	such <application>telnetd</application> will not be enabled.  This
 	means that remote users will not be able to
 	<application>telnet</application> into this machine.  Local users
 	will be still be able to access remote machines with
 	<application>telnet</application>.</para>
 
       <para>These services can be enabled after installation by editing
 	<filename>/etc/inetd.conf</filename> with your favorite text editor.
 	See <xref linkend="inetd-overview"> for more information.</para>
 
       <para>Select <guibutton>[ Yes ]</guibutton> if you wish to
 	configure these services during install.  An additional
 	confirmation will display:</para>
 
       <screen>                      User Confirmation Requested
 The Internet Super Server (inetd) allows a number of simple Internet
 services to be enabled, including finger, ftp and telnetd.  Enabling
 these services may increase risk of security problems by increasing
 the exposure of your system.
 
 With this in mind, do you wish to enable inetd?
 
                              [ Yes ]   No</screen>
 
       <para>Select <guibutton>[ Yes ]</guibutton> to continue.</para>
 
       <screen>                      User Confirmation Requested
 inetd(8) relies on its configuration file, /etc/inetd.conf, to determine
 which of its Internet services will be available.  The default FreeBSD
 inetd.conf(5) leaves all services disabled by default, so they must be
 specifically enabled in the configuration file before they will
 function, even once inetd(8) is enabled.  Note that services for
 IPv6 must be separately enabled from IPv4 services.
 
 Select [Yes] now to invoke an editor on /etc/inetd.conf, or [No] to
 use the current settings.
 
                              [ Yes ]   No</screen>
 
       <para>Selecting <guibutton>[ Yes ]</guibutton> will allow adding
 	services by deleting the <literal>#</literal> at the beginning
 	of a line.</para>
 
       <figure id="inetd-edit">
 	<title>Editing <filename>inetd.conf</filename></title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/edit-inetd-conf" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>After adding the desired services, pressing <keycap>Esc</keycap>
 	will display a menu which will allow exiting and saving 
 	the changes.</para>
 
     </sect2>
 
     <sect2 id="ftpanon">
       <title>Anonymous FTP</title>
 
       <screen>                      User Confirmation Requested
  Do you want to have anonymous FTP access to this machine? 
 
                               Yes    [ No ]</screen>
 
       <sect3 id="deny-anon">
 	<title>Deny Anonymous FTP</title>
       
 	<para>Selecting the default <guibutton>[ No ]</guibutton> and pressing
 	  <keycap>Enter</keycap> will still allow users who have accounts
 	  with passwords to use FTP to access the machine.</para>
       </sect3>
 
       <sect3 id="ftpallow">
 	<title>Allow Anonymous FTP</title>
 
 	<para>Anyone can access your machine if you elect to allow
 	  anonymous FTP connections.  The security implications should be
 	  considered before enabling this option.  For more information
 	  about security see <xref linkend="security">.</para>
 
 	<para>To allow anonymous FTP, use the arrow keys to select
 	  <guibutton>[ Yes ]</guibutton> and press <keycap>Enter</keycap>.
 	  The following screen (or similar) will display:</para>
 
 	<figure id="anon-ftp2">
 	  <title>Default Anonymous FTP Configuration</title>
 
 	  <mediaobject>
 	    <imageobject>
 	      <imagedata fileref="install/ftp-anon1" format="PNG">
 	    </imageobject>
 	  </mediaobject>
 	</figure>
 
 	<para>Pressing <keycap>F1</keycap> will display the help:</para>
 
 	<screen>This screen allows you to configure the anonymous FTP user.
 
 The following configuration values are editable:
 
 UID:     The user ID you wish to assign to the anonymous FTP user.
          All files uploaded will be owned by this ID.
 
 Group:   Which group you wish the anonymous FTP user to be in.
 
 Comment: String describing this user in /etc/passwd
 
 
 FTP Root Directory:
 
         Where files available for anonymous FTP will be kept.
 
 Upload subdirectory:
 
         Where files uploaded by anonymous FTP users will go.</screen>
 
 	<para>The ftp root directory will be put in <filename>/var</filename>
 	  by default.  If you do not have enough room there for the
 	  anticipated FTP needs, the <filename>/usr</filename> directory
 	  could be used by setting the FTP Root Directory to
 	  <filename>/usr/ftp</filename>.</para>
 
 	<para>When you are satisfied with the values, press 
 	  <keycap>Enter</keycap> to continue.</para>
 
 	<screen>                          User Confirmation Requested 
          Create a welcome message file for anonymous FTP users?
 
                               [ Yes ]    No</screen>
 
 	<para>If you select <guibutton>[ Yes ]</guibutton> and press
 	  <keycap>Enter</keycap>, an editor will automatically start
 	  allowing you to edit the message.</para>
 
 	<figure id="anon-ftp4">
 	  <title>Edit The FTP Welcome Message</title>
 
 	  <mediaobject>
 	    <imageobject>
 	      <imagedata fileref="install/ftp-anon2" format="PNG">
 	    </imageobject>
 	  </mediaobject>
 	</figure>
 
 	<para>This is a text editor called <command>ee</command>.  Use the
 	  instructions to change the message or change the message later
 	  using a text editor of your choice.  Note the file name/location
 	  at the bottom of the editor screen.</para>
 
 	<para>Press <keycap>Esc</keycap> and a pop-up menu will default
 	  to <guimenuitem>a) leave editor</guimenuitem>.  Press
 	  <keycap>Enter</keycap> to exit and continue.</para>
       </sect3>
     </sect2>
 
     <sect2 id="nfsconf">
       <title>Configure Network File Services</title>
 
       <para>Network File Services (NFS) allows sharing of files across a
 	network.  A machine can be configured as a server, a client, or
 	both.  Refer to <xref linkend="nfs"> for a more information.</para>
 
       <sect3 id="nsf-server-options">
 	<title>NFS Server</title>
 
 	<screen>                       User Confirmation Requested
  Do you want to configure this machine as an NFS server? 
 
                               Yes    [ No ]</screen>
 
 	<para>If there is no need for a Network File System server or
 	  client, select <guibutton>[ No ]</guibutton> and press
 	  <keycap>Enter</keycap>.</para>
 
 	<para>If <guibutton>[ Yes ]</guibutton> is chosen, a message will
 	  pop-up indicating that the <filename>exports</filename> file must be
 	  created.</para>
 
 	<screen>                               Message
 Operating as an NFS server means that you must first configure an
 /etc/exports file to indicate which hosts are allowed certain kinds of
 access to your local filesystems.
 Press [Enter] now to invoke an editor on /etc/exports
                                [ OK ]</screen>
 
 	<para>Press <keycap>Enter</keycap> to continue.  A text editor will
 	  start allowing the <filename>exports</filename> file to be created
 	  and edited.</para>
 
 	<figure id="nfs-server-edit">
 	  <title>Editing <filename>exports</filename></title>
 
 	  <mediaobject>
 	    <imageobject>
 	      <imagedata fileref="install/nfs-server-edit" format="PNG">
 	    </imageobject>
 	  </mediaobject>
 	</figure>
 
 	<para>Use the instructions to add the actual exported filesystems
 	  now or later using a text editor of your choice.  Note the
 	  file name/location at the bottom of the editor screen.</para>
 
 	<para>Press <keycap>Esc</keycap> and a pop-up menu will default to
 	  <guimenuitem>a) leave editor</guimenuitem>.  Press
 	  <keycap>Enter</keycap> to exit and continue.</para>
       </sect3>
 
       <sect3 id="nfs-client-options">
 	<title>NFS Client</title>
 
 	<screen>                       User Confirmation Requested
  Do you want to configure this machine as an NFS client? 
 
                               Yes   [ No ]</screen>
 
 	<para>With the arrow keys, select <guibutton>[ Yes ]</guibutton>
 	  or <guibutton>[ No ]</guibutton> as appropriate and
 	  press <keycap>Enter</keycap>.</para>
       </sect3>
     </sect2>
 
     <sect2 id="securityprofile">
       <title>Security Profile</title>
 
       <para>A <quote>security profile</quote> is a set of
 	configuration options that attempts to achieve the desired
 	ratio of security to convenience by enabling and disabling
 	certain programs and other settings.  The more severe the
 	security profile, the fewer programs will be enabled by
 	default.  This is one of the basic principles of security: do
 	not run anything except what you must.</para>
 
       <para>Please note that the security profile is just a default
 	setting.  All programs can be enabled and disabled after you
 	have installed FreeBSD by editing or adding the appropriate
 	line(s) to <filename>/etc/rc.conf</filename>.  For more
 	information, please see the &man.rc.conf.5; manual
 	page.</para>
 
       <para>The following table describes what each of the security
 	profiles does.  The columns are the choices you have for a
 	security profile, and the rows are the program or feature that
 	the profile enables or disables.</para>
 
       <table>
 	<title>Possible security profiles</title>
 
 	<tgroup cols=3>
 	  <thead>
 	    <row>
 	      <entry></entry>
 
 	      <entry>Extreme</entry>
 
 	      <entry>Moderate</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 
 	    <row>
 	      <entry>&man.sendmail.8;</entry>
 
 	      <entry>NO</entry>
 
 	      <entry>YES</entry>
 	    </row>
 
 	    <row>
 	      <entry>&man.sshd.8;</entry>
 
 	      <entry>NO</entry>
 
 	      <entry>YES</entry>
 	    </row>
 
 	    <row>
 	      <entry>&man.portmap.8;</entry>
 
 	      <entry>NO</entry>
 
 	      <entry>MAYBE
 		<footnote>
 		  <para>The portmapper is enabled if the machine has
 		    been configured as an NFS client or server earlier
 		    in the installation.</para>
 		</footnote>
 	      </entry>
 	    </row>
 
 	    <row>
 	      <entry>NFS server</entry>
 
 	      <entry>NO</entry>
 
 	      <entry>YES</entry>
 	    </row>
 
 	    <row>
 	      <entry>&man.securelevel.8;</entry>
 
 	      <entry>YES
 		<footnote>
 		  <para>If you choose a security profile that sets the
 		    securelevel to <quote>Extreme</quote> or
 		    <quote>High</quote>, you must be aware of the
 		    implications.  Please read the &man.init.8;
 		    manual page and pay particular attention to the
 		    meanings of the security levels, or you may have
 		    significant trouble later!</para>
 		</footnote>
 	      </entry>
 
 	      <entry>NO</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
       <screen>                       User Confirmation Requested
  Do you want to select a default security profile for this host (select
  No for "medium" security)? 
 
                             [ Yes ]    No</screen>
 
       <para>Selecting <guibutton>[ No ]</guibutton> and pressing
 	<keycap>Enter</keycap> will set the security profile to medium.</para>
 
       <para>Selecting <guibutton>[ Yes ]</guibutton> and pressing
 	<keycap>Enter</keycap> will allow selecting a different security
 	profile.</para>
 
       <figure id="security-profile">
 	<title>Security Profile Options</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/security" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Press <keycap>F1</keycap> to display the help.  Press
 	<keycap>Enter</keycap> to return to selection menu.</para>
 
       <para>Use the arrow keys to choose <guimenuitem>Medium</guimenuitem>
 	unless your are sure that another level is required for your needs.
 	With &gui.ok; highlighted, press
 	<keycap>Enter</keycap>.</para>
 
       <para>An appropriate confirmation message will display depending on
 	which security setting was chosen.</para>
 
       <screen>                                 Message
 
 Moderate security settings have been selected.
 
 Sendmail and SSHd have been enabled, securelevels are
 disabled, and NFS server setting have been left intact.
 PLEASE NOTE that this still does not save you from having
 to properly secure your system in other ways or exercise
 due diligence in your administration, this simply picks
 a standard set of out-of-box defaults to start with.
 
 To change any of these settings later, edit /etc/rc.conf
 
                                   [OK]</screen>
 
       <screen>                                 Message
 
 Extreme security settings have been selected.
 
 Sendmail, SSHd, and NFS services have been disabled, and
 securelevels have been enabled.
 PLEASE NOTE that this still does not save you from having
 to properly secure your system in other ways or exercise
 due diligence in your administration, this simply picks
 a more secure set of out-of-box defaults to start with.
 
 To change any of these settings later, edit /etc/rc.conf
 
                                   [OK]</screen>
 
       <para>Press <keycap>Enter</keycap> to continue with the
 	post-installation configuration.</para>
 
       <warning>
 	<para>The security profile is not a silver bullet!  Even if
 	  you use the extreme setting, you need to keep up with
 	  security issues by reading an appropriate <ulink
 	  url="../handbook/eresources.html#ERESOURCES-MAIL">mailing
 	  list</ulink>, using good passwords and passphrases, and
 	  generally adhering to good security practices.  It simply
 	  sets up the desired security to convenience ratio out of the
 	  box.</para>
       </warning>
 
     </sect2>
 
     <sect2 id="console">
       <title>System Console Settings</title>
 
       <para>There are several options available to customize the system
 	console.</para>
 
       <screen>                      User Confirmation Requested 
        Would you like to customize your system console settings?
 
                               [ Yes ]  No</screen>
 
       <para>To view and configure the options, select
 	<guibutton>[ Yes ]</guibutton> and press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="saver-options">
 	<title>System Console Configuration Options</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/console-saver1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>A commonly used option is the screen saver.  Use the arrow keys
 	to select <guimenuitem>Saver</guimenuitem> and then press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="saver-select">
 	<title>Screen Saver Options</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/console-saver2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select the desired screen saver using the arrow keys
 	and then press <keycap>Enter</keycap>.  The System Console
 	Configuration menu will redisplay.</para>
 
       <para>The default time interval is 300 seconds.  To change the time
 	interval, select <guimenuitem>Saver</guimenuitem> again.  At the
 	Screen Saver Options menu, select <guimenuitem>Timeout</guimenuitem>
 	using the arrow keys and press <keycap>Enter</keycap>.  A pop-up
 	menu will appear:</para>
 
       <figure id="saver-timeout">
 	<title>Screen Saver Timeout</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/console-saver3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The value can be changed, then select &gui.ok;
 	and press <keycap>Enter</keycap> to return to the System Console
 	Configuration menu.</para>
 
       <figure id="saver-exit">
 	<title>System Console Configuration Exit</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/console-saver4" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Selecting <guimenuitem>Exit</guimenuitem> and pressing
 	<keycap>Enter</keycap> will continue with the post-installation
 	configurations.</para>
     </sect2>
 
     <sect2 id="timezone">
       <title>Setting The Time Zone</title>
 
       <para>Setting the time zone for your machine will allow it to
 	automatically correct for any regional time changes and perform
 	other time zone related functions properly.</para>
 
       <para>The example shown is for a machine located in the Eastern
 	time zone of the United States.  Your selections will vary according
 	to your geographical location.</para>
 
       <screen>                      User Confirmation Requested 
           Would you like to set this machine's time zone now?
 
                             [ Yes ]   No</screen>
 
       <para>Select <guibutton>[ Yes ]</guibutton> and press
 	<keycap>Enter</keycap> to set the time zone.</para>
 
       <screen>                       User Confirmation Requested
  Is this machine's CMOS clock set to UTC? If it is set to local time
  or you don't know, please choose NO here! 
 
                               Yes   [ No ]</screen>
 
       <para>Select <guibutton>[ Yes ]</guibutton> 
 	or <guibutton>[ No ]</guibutton> according to how the machine's
 	clock is configured and press <keycap>Enter</keycap>.</para>
 
       <figure id="set-timezone-region">
 	<title>Select Your Region</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/timezone1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The appropriate region is selected using the arrow keys
 	and then press <keycap>Enter</keycap>.</para>
 
       <figure id="set-timezone-country">
 	<title>Select Your Country</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/timezone2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select the appropriate country using the arrow keys
 	and press <keycap>Enter</keycap>.</para>
 
       <figure id="set-timezone-locality">
 	<title>Select Your Time Zone</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/timezone3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The appropriate time zone is selected using the arrow
 	keys and pressing <keycap>Enter</keycap>.</para>
 
       <screen>                            Confirmation 
             Does the abbreviation 'EDT' look reasonable?
 
                             [ Yes ]   No</screen>
 
       <para>Confirm the abbreviation for the time zone is correct.
 	If it looks okay, press <keycap>Enter</keycap> to continue with
 	the post-installation configuration.</para>
     </sect2>
 
     <sect2 id="linuxcomp">
       <title>Linux Compatibility</title>
 
       <screen>                      User Confirmation Requested 
           Would you like to enable Linux binary compatibility?
 
                             [ Yes ]   No</screen>
 
       <para>Selecting <guibutton>[ Yes ]</guibutton> and pressing
 	<keycap>Enter</keycap> will allow
 	running Linux software on FreeBSD.  The install will proceed to add
 	the appropriate packages for Linux compatibility.</para>
 
       <para>If installing by FTP, the machine will need to be connected to
 	the Internet.  Sometimes a remote ftp site will not have all the
 	distributions like the Linux binary compatibility.  This can
 	be installed later if necessary.</para>
     </sect2>
 
     <sect2 id="mouse">
       <title>Mouse Settings</title>
 
       <para>This option will allow you to cut and paste text in the
 	console and user programs with a 3-button mouse.  If using a 2-button
 	mouse, refer to manual page, &man.moused.8;, after installation for
 	details on emulating the 3-button style.  This example depicts a
 	non-USB mouse configuration:</para>
 
       <screen>                      User Confirmation Requested 
          Does this system have a non-USB mouse attached to it?
 
                             [ Yes ]    No </screen>
 
       <para>Select <guibutton>[ Yes ]</guibutton> for a non-USB mouse or
 	<guibutton>[ No ]</guibutton> for a USB mouse and press
 	<keycap>Enter</keycap>.</para>
 
       <figure id="mouse-protocol">
 	<title>Select Mouse Protocol Type</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the arrow keys to select <guimenuitem>Type</guimenuitem> and
 	press <keycap>Enter</keycap>.</para>
 
       <figure id="set-mouse-protocol">
 	<title>Set Mouse Protocol</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The mouse used in this example is a PS/2 type, so the default
 	<guimenuitem>Auto</guimenuitem> was appropriate.  To change protocol,
 	use the arrow keys to select another option.  Ensure that &gui.ok; is
 	highlighted and press <keycap>Enter</keycap> to exit this menu.</para>
 
       <figure id="config-mouse-port">
 	<title>Configure Mouse Port</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the arrow keys to select <guimenuitem>Port</guimenuitem> and
 	press <keycap>Enter</keycap>.</para>
 
       <figure id="set-mouse-port">
 	<title>Setting The Mouse Port</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse4" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>This system had a PS/2 mouse, so the default
 	<guimenuitem>PS/2</guimenuitem> was appropriate.  To change the port,
 	use the arrow keys and then press <keycap>Enter</keycap>.</para>
 
       <figure id="test-daemon">
 	<title>Enable The Mouse Daemon</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse5" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Last, the mouse daemon is enabled and tested.</para>
 
       <figure id="test-mouse-daemon">
 	<title>Test The Mouse Daemon</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mouse6" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The cursor moved around the screen so the mouse daemon is
 	running.</para>
 
       <para>Select <guibutton>[ Yes ]</guibutton> to return to the previous
 	menu then select <guimenuitem>Exit</guimenuitem> with the arrow keys
 	and press <keycap>Enter</keycap> to return to continue with the
 	post-installation configuration.</para>
     </sect2>
 
     <sect2 id="x-server">
       <title>Configure X Server</title>
 
       <para>In order to use a graphical user interface such as 
 	<application>KDE</application>, <application>GNOME</application>,
 	or others, the X server will need to be configured.</para>
 
       <note>
 	<para>In order to run <application>XFree86</application> as a
 	  non <username>root</username> user you will need to
 	  have <filename role="package">x11/wrapper</filename> installed.
 	  This is installed by default beginning with FreeBSD 4.7.  For
 	  earlier versions this can be added
 	  from the Package Selection menu.</para>
       </note>
 
       <para>To see whether your video card is supported, check the
 	<ulink url="http://www.xfree86.org/">XFree86</ulink> web site.</para>
 
       <screen>                      User Confirmation Requested 
         Would you like to configure your X server at this time?
 
                             [ Yes ]   No</screen>
 
       <warning>
 	<para>It is necessary to know your monitor specifications and
 	  video card information.  Equipment damage can occur if settings
 	  are incorrect.  If you do not have this information, select
 	  <guibutton>[ No ]</guibutton> and perform the configuration
 	  after installation when you have the information using 
 	  <command>/stand/sysinstall</command>, selecting
 	  <guimenuitem>Configure</guimenuitem> and then 
 	  <guimenuitem>XFree86</guimenuitem>.
 	</para>
       </warning>
 
       <para>If you have graphics card and monitor information, select
 	<guibutton>[ Yes ]</guibutton> and press <keycap>Enter</keycap>
 	to proceed with configuring the X server.</para>
 
       <figure id="xserver2">
 	<title>Select Configuration Method Menu</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/xf86setup" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>There are several ways to configure the X server.
 	Use the arrow keys to select one of the methods  and press
 	<keycap>Enter</keycap>.  Be sure to read all instructions
 	carefully.</para>
 
       <para>The <application>xf86cfg</application> and 
 	<application>xf86cfg -textmode</application> may make the screen
 	go dark and take a few seconds to start.  Be patient.</para>
 
 
       <para>The following will illustrate the use of the
 	<application>xf86config</application> configuration tool.  The
 	configuration choices you make will depend on the hardware in the
 	system so your choices will probably be different than those
 	shown:</para>
 
       <screen>                                Message
  You have configured and been running the mouse daemon. 
  Choose "/dev/sysmouse" as the mouse port and "SysMouse" or
  "MouseSystems" as the mouse protocol in the X configuration utility. 
 
                                  [ OK ]
 
                       [ Press enter to continue ]</screen>
 
       <para>This indicates that the mouse daemon previously configured has been
 	detected.
 	Press <keycap>Enter</keycap> to continue.</para>
 
       <para>Starting <application>xf86config</application> will display
 	a brief introduction:</para>
 
       <screen>This program will create a basic XF86Config file, based on menu selections you
 make.
 
 The XF86Config file usually resides in /usr/X11R6/etc/X11 or /etc/X11. A sample
 XF86Config file is supplied with XFree86; it is configured for a standard
 VGA card and monitor with 640x480 resolution. This program will ask for a
 pathname when it is ready to write the file.
 
 You can either take the sample XF86Config as a base and edit it for your
 configuration, or let this program produce a base XF86Config file for your
 configuration and fine-tune it.
 
 Before continuing with this program, make sure you know what video card
 you have, and preferably also the chipset it uses and the amount of video
 memory on your video card. SuperProbe may be able to help with this.
 
 Press enter to continue, or ctrl-c to abort.</screen>
 
       <para>Pressing <keycap>Enter</keycap> will start the mouse
 	configuration.  Be sure to follow the instructions and use
 	<quote>Mouse Systems</quote> as the mouse protocol and
 	<devicename>/dev/sysmouse</devicename> as the mouse port even if
 	using a PS/2 mouse is shown as an illustration.</para>
 
       <screen>First specify a mouse protocol type. Choose one from the following list:
 
  1.  Microsoft compatible (2-button protocol)
  2.  Mouse Systems (3-button protocol) & FreeBSD moused protocol
  3.  Bus Mouse
  4.  PS/2 Mouse
  5.  Logitech Mouse (serial, old type, Logitech protocol)
  6.  Logitech MouseMan (Microsoft compatible)
  7.  MM Series
  8.  MM HitTablet
  9.  Microsoft IntelliMouse
 
 If you have a two-button mouse, it is most likely of type 1, and if you have
 a three-button mouse, it can probably support both protocol 1 and 2. There are
 two main varieties of the latter type: mice with a switch to select the
 protocol, and mice that default to 1 and require a button to be held at
 boot-time to select protocol 2. Some mice can be convinced to do 2 by sending
 a special sequence to the serial port (see the ClearDTR/ClearRTS options).
 
 Enter a protocol number: 2
 
 You have selected a Mouse Systems protocol mouse. If your mouse is normally
 in Microsoft-compatible mode, enabling the ClearDTR and ClearRTS options
 may cause it to switch to Mouse Systems mode when the server starts.
 
 Please answer the following question with either 'y' or 'n'.
 Do you want to enable ClearDTR and ClearRTS? n
 
 You have selected a three-button mouse protocol. It is recommended that you
 do not enable Emulate3Buttons, unless the third button doesn't work.
 
 Please answer the following question with either 'y' or 'n'.
 Do you want to enable Emulate3Buttons? y
 
 Now give the full device name that the mouse is connected to, for example
 /dev/tty00. Just pressing enter will use the default, /dev/mouse.
 On FreeBSD, the default is /dev/sysmouse.
 
 Mouse device: /dev/sysmouse</screen>
 
       <para>The keyboard is the next item to be configured. A generic
 	101-key model is shown for illustration.  Any name may be used
 	for the variant or simply press <keycap>Enter</keycap> to accept
 	the default value.</para>
 
       <screen>Please select one of the following keyboard types that is the better
 description of your keyboard. If nothing really matches,
 choose 1 (Generic 101-key PC)
 
   1  Generic 101-key PC                                
   2  Generic 102-key (Intl) PC                         
   3  Generic 104-key PC                                
   4  Generic 105-key (Intl) PC                         
   5  Dell 101-key PC                                   
   6  Everex STEPnote                                   
   7  Keytronic FlexPro                                 
   8  Microsoft Natural                                 
   9  Northgate OmniKey 101                             
  10  Winbook Model XP5                                 
  11  Japanese 106-key                                  
  12  PC-98xx Series                                    
  13  Brazilian ABNT2                                   
  14  HP Internet                                       
  15  Logitech iTouch                                   
  16  Logitech Cordless Desktop Pro                     
  17  Logitech Internet Keyboard                        
  18  Logitech Internet Navigator Keyboard              
  19  Compaq Internet                                   
  20  Microsoft Natural Pro                             
  21  Genius Comfy KB-16M                               
  22  IBM Rapid Access                                  
  23  IBM Rapid Access II                               
  24  Chicony Internet Keyboard                         
  25  Dell Internet Keyboard                            
 
 Enter a number to choose the keyboard.
 
 1
 
 
 Please select the layout corresponding to your keyboard
 
 
   1  U.S. English                                      
   2  U.S. English w/ ISO9995-3                         
   3  U.S. English w/ deadkeys                          
   4  Albanian                                          
   5  Arabic                                            
   6  Armenian                                          
   7  Azerbaidjani                                      
   8  Belarusian                                        
   9  Belgian                                           
  10  Bengali                                           
  11  Brazilian                                         
  12  Bulgarian                                         
  13  Burmese                                           
  14  Canadian                                          
  15  Croatian                                          
  16  Czech                                             
  17  Czech (qwerty)                                    
  18  Danish                                            
 
 Enter a number to choose the country.
 Press enter for the next page
 
 1
 
 
 Please enter a variant name for 'us' layout. Or just press enter
 for default variant
 
 us
 
 
 Please answer the following question with either 'y' or 'n'.
 Do you want to select additional XKB options (group switcher,
 group indicator, etc.)? n</screen>
 
       <para>Next, we proceed to the configuration for the monitor.  Do not
 	exceed the ratings of your monitor. Damage could occur.  If you
 	have any doubts, do the configuration after you have the
 	information.</para>
 
       <screen>Now we want to set the specifications of the monitor. The two critical
 parameters are the vertical refresh rate, which is the rate at which the
 whole screen is refreshed, and most importantly the horizontal sync rate,
 which is the rate at which scanlines are displayed.
 
 The valid range for horizontal sync and vertical sync should be documented
 in the manual of your monitor. If in doubt, check the monitor database
 /usr/X11R6/lib/X11/doc/Monitors to see if your monitor is there.
 
 Press enter to continue, or ctrl-c to abort.
 
 
 
 You must indicate the horizontal sync range of your monitor. You can either
 select one of the predefined ranges below that correspond to industry-
 standard monitor types, or give a specific range.
 
 It is VERY IMPORTANT that you do not specify a monitor type with a horizontal
 sync range that is beyond the capabilities of your monitor. If in doubt,
 choose a conservative setting.
 
     hsync in kHz; monitor type with characteristic modes
  1  31.5; Standard VGA, 640x480 @ 60 Hz
  2  31.5 - 35.1; Super VGA, 800x600 @ 56 Hz
  3  31.5, 35.5; 8514 Compatible, 1024x768 @ 87 Hz interlaced (no 800x600)
  4  31.5, 35.15, 35.5; Super VGA, 1024x768 @ 87 Hz interlaced, 800x600 @ 56 Hz
  5  31.5 - 37.9; Extended Super VGA, 800x600 @ 60 Hz, 640x480 @ 72 Hz
  6  31.5 - 48.5; Non-Interlaced SVGA, 1024x768 @ 60 Hz, 800x600 @ 72 Hz
  7  31.5 - 57.0; High Frequency SVGA, 1024x768 @ 70 Hz
  8  31.5 - 64.3; Monitor that can do 1280x1024 @ 60 Hz
  9  31.5 - 79.0; Monitor that can do 1280x1024 @ 74 Hz
 10  31.5 - 82.0; Monitor that can do 1280x1024 @ 76 Hz
 11  Enter your own horizontal sync range
 
 Enter your choice (1-11): 6
 
 You must indicate the vertical sync range of your monitor. You can either
 select one of the predefined ranges below that correspond to industry-
 standard monitor types, or give a specific range. For interlaced modes,
 the number that counts is the high one (e.g. 87 Hz rather than 43 Hz).
 
  1  50-70
  2  50-90
  3  50-100
  4  40-150
  5  Enter your own vertical sync range
 
 Enter your choice: 2
 
 You must now enter a few identification/description strings, namely an
 identifier, a vendor name, and a model name. Just pressing enter will fill
 in default names.
 
 The strings are free-form, spaces are allowed.
 Enter an identifier for your monitor definition: Hitachi</screen>
 
       <para>The selection of a video card driver from a list is
 	next.  If you pass your card on the list, continue to press
 	<keycap>Enter</keycap> and the list will repeat.  Only an
 	excerpt from the list is shown:</para>
 
       <screen>Now we must configure video card specific settings. At this point you can
 choose to make a selection out of a database of video card definitions.
 Because there can be variation in Ramdacs and clock generators even
 between cards of the same model, it is not sensible to blindly copy
 the settings (e.g. a Device section). For this reason, after you make a
 selection, you will still be asked about the components of the card, with
 the settings from the chosen database entry presented as a strong hint.
 
 The database entries include information about the chipset, what driver to
 run, the Ramdac and ClockChip, and comments that will be included in the
 Device section. However, a lot of definitions only hint about what driver
 to run (based on the chipset the card uses) and are untested.
 
 If you can't find your card in the database, there's nothing to worry about.
 You should only choose a database entry that is exactly the same model as
 your card; choosing one that looks similar is just a bad idea (e.g. a
 GemStone Snail 64 may be as different from a GemStone Snail 64+ in terms of
 hardware as can be).
 
 Do you want to look at the card database? y
 
 
 
 288  Matrox Millennium G200 8MB                        mgag200
 289  Matrox Millennium G200 SD 16MB                    mgag200
 290  Matrox Millennium G200 SD 4MB                     mgag200
 291  Matrox Millennium G200 SD 8MB                     mgag200
 292  Matrox Millennium G400                            mgag400
 293  Matrox Millennium II 16MB                         mga2164w
 294  Matrox Millennium II 4MB                          mga2164w
 295  Matrox Millennium II 8MB                          mga2164w
 296  Matrox Mystique                                   mga1064sg
 297  Matrox Mystique G200 16MB                         mgag200
 298  Matrox Mystique G200 4MB                          mgag200
 299  Matrox Mystique G200 8MB                          mgag200
 300  Matrox Productiva G100 4MB                        mgag100
 301  Matrox Productiva G100 8MB                        mgag100
 302  MediaGX                                           mediagx
 303  MediaVision Proaxcel 128                          ET6000
 304  Mirage Z-128                                      ET6000
 305  Miro CRYSTAL VRX                                  Verite 1000
 
 Enter a number to choose the corresponding card definition.
 Press enter for the next page, q to continue configuration.
 
 288
 
 Your selected card definition:
 
 Identifier: Matrox Millennium G200 8MB
 Chipset:    mgag200
 Driver:     mga
 Do NOT probe clocks or use any Clocks line.
 
 Press enter to continue, or ctrl-c to abort.
 
 
 
 Now you must give information about your video card. This will be used for
 the "Device" section of your video card in XF86Config.
 
 You must indicate how much video memory you have. It is probably a good
 idea to use the same approximate amount as that detected by the server you
 intend to use. If you encounter problems that are due to the used server
 not supporting the amount memory you have (e.g. ATI Mach64 is limited to
 1024K with the SVGA server), specify the maximum amount supported by the
 server.
 
 How much video memory do you have on your video card:
 
  1  256K
  2  512K
  3  1024K
  4  2048K
  5  4096K
  6  Other
 
 Enter your choice: 6
 
 Amount of video memory in Kbytes: 8192
 
 You must now enter a few identification/description strings, namely an
 identifier, a vendor name, and a model name. Just pressing enter will fill
 in default names (possibly from a card definition).
 
 Your card definition is Matrox Millennium G200 8MB.
 
 The strings are free-form, spaces are allowed.
 Enter an identifier for your video card definition:</screen>
 
       <para>Next, the video modes are set for the resolutions
 	desired.  Typically, useful ranges are 640x480, 800x600, and 1024x768
 	but those are a function of video card capability, monitor size,
 	and eye comfort.  When selecting a color depth, select the highest
 	mode that your card will support.</para>
 
       <screen>For each depth, a list of modes (resolutions) is defined. The default
 resolution that the server will start-up with will be the first listed
 mode that can be supported by the monitor and card.
 Currently it is set to:
 
 "640x480" "800x600" "1024x768" "1280x1024" for 8-bit
 "640x480" "800x600" "1024x768" "1280x1024" for 16-bit
 "640x480" "800x600" "1024x768" "1280x1024" for 24-bit
 
 Modes that cannot be supported due to monitor or clock constraints will
 be automatically skipped by the server.
 
  1  Change the modes for 8-bit (256 colors)
  2  Change the modes for 16-bit (32K/64K colors)
  3  Change the modes for 24-bit (24-bit color)
  4  The modes are OK, continue.
 
 Enter your choice: 2
 
 Select modes from the following list:
 
  1  "640x400"
  2  "640x480"
  3  "800x600"
  4  "1024x768"
  5  "1280x1024"
  6  "320x200"
  7  "320x240"
  8  "400x300"
  9  "1152x864"
  a  "1600x1200"
  b  "1800x1400"
  c  "512x384"
 
 Please type the digits corresponding to the modes that you want to select.
 For example, 432 selects "1024x768" "800x600" "640x480", with a
 default mode of 1024x768.
 
 Which modes? 432
 
 You can have a virtual screen (desktop), which is screen area that is larger
 than the physical screen and which is panned by moving the mouse to the edge
 of the screen. If you don't want virtual desktop at a certain resolution,
 you cannot have modes listed that are larger. Each color depth can have a
 differently-sized virtual screen
 
 Please answer the following question with either 'y' or 'n'.
 Do you want a virtual screen that is larger than the physical screen? n
 
 
 
 For each depth, a list of modes (resolutions) is defined. The default
 resolution that the server will start-up with will be the first listed
 mode that can be supported by the monitor and card.
 Currently it is set to:
 
 "640x480" "800x600" "1024x768" "1280x1024" for 8-bit
 "1024x768" "800x600" "640x480" for 16-bit
 "640x480" "800x600" "1024x768" "1280x1024" for 24-bit
 
 Modes that cannot be supported due to monitor or clock constraints will
 be automatically skipped by the server.
 
  1  Change the modes for 8-bit (256 colors)
  2  Change the modes for 16-bit (32K/64K colors)
  3  Change the modes for 24-bit (24-bit color)
  4  The modes are OK, continue.
 
 Enter your choice: 4
 
 
 
 Please specify which color depth you want to use by default:
 
   1  1 bit (monochrome)                                
   2  4 bits (16 colors)                                
   3  8 bits (256 colors)                               
   4  16 bits (65536 colors)                            
   5  24 bits (16 million colors)                       
 
 Enter a number to choose the default depth.
 
 4</screen>
 
       <para>Finally, the configuration needs to be saved.  Be sure
 	to enter <filename>/etc/XF86Config</filename> as the location
 	for saving the configuration.</para>
 
       <screen>I am going to write the XF86Config file now. Make sure you don't accidently
 overwrite a previously configured one.
 
 Shall I write it to /etc/X11/XF86Config? y</screen>
 
       <para>If the configuration fails, you can try the configuration again
 	by selecting <guimenuitem>[ Yes ]</guimenuitem> when the following
 	message appears:</para>
 
       <screen>          User Confirmation Requested
 The XFree86 configuration process seems to have
 failed.  Would you like to try again?
 
              [ Yes ]         No</screen>
 
       <para>If you have trouble configuring <application>XFree86</application>, select
 	<guimenuitem>[ No ]</guimenuitem> and press <keycap>Enter</keycap>
 	and continue with the installation process.  After installation
 	you can use <command>xf86cfg -textmode</command> or
 	<command>xf86config</command> to access the command line
 	configuration utilities as <username>root</username>.  There is
 	an additional method for configuring <application>XFree86</application> described in
 	<xref linkend="x11">.   If you choose not to configure
 	<application>XFree86</application> at this time the next menu will be for package
 	selection.</para>
 
       <para>The default setting which allows the server to be killed
 	is the hotkey sequence <keycombo action='simul'>
 	<keycap>Ctrl</keycap><keycap>Alt</keycap>
 	<keycap>Backspace</keycap></keycombo>.  This
 	can be executed if something is wrong with the server settings and
 	prevent hardware damage.</para>
 
       <para>The default setting that allows video mode switching will
 	permit changing of the mode while running X with the hotkey
 	sequence
 	<keycombo action='simul'>
 	  <keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>+</keycap>
 	</keycombo> or
 	<keycombo action='simul'>
 	  <keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>-</keycap>
 	</keycombo>.   
       </para>
 
       <para>After installation, the display can be adjusted for height,
 	width, or centering by using <application>xvidtune</application>
 	after you have <application>XFree86</application> running with
 	<application>xvidtune</application>.</para>
 
       <para>There are warnings that improper settings can
 	damage your equipment.  Heed them.  If in doubt, do not do
 	it.  Instead, use the monitor controls to adjust the display for
 	X Window.  There may be some display differences when switching
 	back to text mode, but it is better than damaging equipment.</para>
 
       <para>Read the &man.xvidtune.1; manual page before making
 	any adjustments.</para>
 
       <para>Following a successful <application>XFree86</application> configuration, it will proceed
 	to the selection of a default desktop.</para>
     </sect2>
 
     <sect2 id="default-desktop">
       <title>Select Default X Desktop</title>
 
       <para>There are a variety of window managers available.  They range
 	from very basic environments to full desktop environments with a
 	large suite of software.  Some require only minimal disk space and
 	low memory while others with more features require much more.  The
 	best way to determine which is most suitable for you is to try a few
 	different ones.  Those are available from the ports collection or as
 	packages and can be added after installation.</para>
 
       <para>You can select one of the popular desktops to be installed
 	and configured as the default desktop.  This will allow you
 	to start it right after installation.</para>
 
       <figure id="x-desktop">
 	<title>Select Default Desktop</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/desktop" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the arrow keys to select a desktop and press
 	<keycap>Enter</keycap>.  Installation of the selected desktop will
 	proceed.</para>
     </sect2>
 
     <sect2 id="packages">
     <title>Install Packages</title>
 
       <para>The packages are pre-compiled binaries and are a convenient
 	way to install software.</para>
 
       <para>Installation of one package is shown for purposes of
 	illustration.  Additional packages can also be added at this
 	time if desired.  After installation
 	<command>/stand/sysinstall</command> can be used to add additional
 	packages.</para>
 
       <screen>                     User Confirmation Requested
  The FreeBSD package collection is a collection of hundreds of
  ready-to-run applications, from text editors to games to WEB servers
  and more. Would you like to browse the collection now? 
 
                             [ Yes ]   No</screen>
 
       <para>Selecting <guimenuitem>[ Yes ]</guimenuitem> and pressing
 	<keycap>Enter</keycap> will be
 	followed by the Package Selection screens:</para>
 
       <figure id="package-category">
 	<title>Select Package Category</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/pkg-cat" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>All packages available will be displayed if 
 	<guimenuitem>All</guimenuitem> is selected or you can select a
 	particular category.  Highlight your selection with the arrow
 	keys and press <keycap>Enter</keycap>.</para>
 
       <para>A menu will display showing all the packages available for
 	the selection made:</para>
 
       <figure id="package-select">
 	<title>Select Packages</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/pkg-sel" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The <application>bash</application> shell is shown selected.
 	Select as many as desired by highlighting the package and pressing the
 	<keycap>Space</keycap> key.  A short description of each package will
 	appear in the lower left corner of the screen.</para>
 
       <para>Pressing the <keycap>Tab</keycap> key will toggle between the last
 	selected package, &gui.ok;, and &gui.cancel;.</para>
 
       <para>When you have finished marking the packages for installation,
 	press <keycap>Tab</keycap> once to toggle to the &gui.ok; and press
 	<keycap>Enter</keycap> to return to the Package Selection menu.</para>
 
       <para>The left and right arrow keys will also toggle between &gui.ok;
 	and &gui.cancel;.  This method can also be used to select &gui.ok; and
 	press <keycap>Enter</keycap> to return to the Package Selection
 	menu.</para>
 
       <figure id="package-install">
 	<title>Install Packages</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/pkg-install" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Use the arrow keys to select <guibutton>[ Install ]</guibutton>
 	and press <keycap>Enter</keycap>.  You will then need to confirm
 	that you want to install the packages:</para>
 
       <figure id="package-install-confirm">
 	<title>Confirm Package Installation</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/pkg-confirm" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Selecting &gui.ok; and pressing <keycap>Enter</keycap> will start
 	the package installation.  Installing messages will appear until
 	completed.  Make note if there are any error messages.</para>
 
       <para>The final configuration continues after packages are
 	installed.</para>
     </sect2>
 
     <sect2 id="addusers">
       <title>Add Users/Groups</title>
 
       <para>You should add at least one user during the installation so
 	that you can use the system without being logged in as
 	<username>root</username>.  The root partition is generally small
 	and running applications as <username>root</username> can quickly
 	fill it.  A bigger danger is noted below:</para>
 
       <screen>                     User Confirmation Requested
  Would you like to add any initial user accounts to the system? Adding
  at least one account for yourself at this stage is suggested since
  working as the "root" user is dangerous (it is easy to do things which
  adversely affect the entire system). 
 
                             [ Yes ]   No</screen>
 
       <para>Select <guibutton>[ Yes ]</guibutton> and press
 	<keycap>Enter</keycap> to continue with adding a user.</para>
 
       <figure id="add-user2">
 	<title>Select User</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/adduser1" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select <guimenuitem>User</guimenuitem> with the arrow keys
 	and press <keycap>Enter</keycap>.</para>
 
       <figure id="add-user3">
 	<title>Add User Information</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/adduser2" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>The following descriptions will appear in the lower part of
 	the screen as the items are selected with <keycap>Tab</keycap>
 	to assist with entering the required information:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term>Login ID</term>
 
 	  <listitem>
 	    <para>The login name of the new user (mandatory).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>UID</term>
 	
 	  <listitem>
 	    <para>The numerical ID for this user (leave blank for
 	      automatic choice).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Group</term>
 
 	  <listitem>
 	    <para>The login group name for this user (leave blank for
 	      automatic choice).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Password</term>
 
 	  <listitem>
 	    <para>The password for this user (enter this field with
 	      care!).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Full name</term>
 
 	  <listitem>
 	    <para>The user's full name (comment).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Member groups</term>
 
 	  <listitem>
 	    <para>The groups this user belongs to (i.e. gets access
 	      rights for).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Home directory</term>
 
 	  <listitem>
 	    <para>The user's home directory (leave blank for
 	      default).</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>Login shell</term>
 	  <listitem>
 	    <para>The user's login shell (leave blank for
 	      default, e.g. <filename>/bin/sh</filename>).</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
       <para>The login shell was changed from <filename>/bin/sh</filename> to
 	<filename>/usr/local/bin/bash</filename> to use the
 	<application>bash</application> shell that was previously installed as
 	a package.  Do not try to use a shell that does not exist or you will
 	not be able to login.</para>
 
       <para>The user was also added to the <groupname>wheel</groupname> group
 	to be able to become a superuser with <username>root</username>
 	privileges.</para>
 
       <para>When you are satisfied, press &gui.ok; and
 	the User and Group Management menu will redisplay:</para>
 
       <figure id="add-user4">
 	<title>Exit User and Group Management</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/adduser3" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Groups could also be added at this time if specific needs
 	are known.  Otherwise, this may be accessed through using
 	<filename>/stand/sysinstall</filename> after installation is
 	completed.</para>
 
       <para>When you are finished adding users, select 
 	<guimenuitem>Exit</guimenuitem> with the arrow keys and press
 	<keycap>Enter</keycap> to continue the installation.</para>
     </sect2>
 
     <sect2 id="rootpass">
       <title>Set <username>root</username> Password</title>
 
       <screen>                        Message
  Now you must set the system manager's password.  
  This is the password you'll use to log in as "root". 
 
                          [ OK ] 
 
                [ Press enter to continue ]</screen>
 
       <para>Press <keycap>Enter</keycap> to set the <username>root</username>
 	password.</para>
 
       <para>The password will need to be typed in twice correctly.  Needless to
 	say, make sure you have a way of finding the password if you
 	forget.</para>
 
       <screen>Changing local password for root. 
  New password : 
  Retype new password :</screen>
 
       <para>The installation will continue after the password is
 	successfully entered.</para>
     </sect2>
 
     <sect2 id="exit-inst">
       <title>Exiting Install</title>
 
       <para>If you need to configure additional network devices or to
 	do any other configurations, you can do it at this point or
 	after installation with <filename>/stand/sysinstall</filename>.</para>
 
       <screen>                     User Confirmation Requested
  Visit the general configuration menu for a chance to set any last
  options? 
 
                               Yes   [ No ]</screen>
 
       <para>Select <guibutton>[ No ]</guibutton> with the arrow keys
 	and press <keycap>Enter</keycap> to return to the Main
 	Installation Menu.</para>
 
       <figure id="final-main">
 	<title>Exit Install</title>
 
 	<mediaobject>
 	  <imageobject>
 	    <imagedata fileref="install/mainexit" format="PNG">
 	  </imageobject>
 	</mediaobject>
       </figure>
 
       <para>Select <guibutton>[X Exit Install]</guibutton> with the arrow
 	keys and press <keycap>Enter</keycap>.  You will be asked to
 	confirm exiting the installation:</para>
 
       <screen>                     User Confirmation Requested
  Are you sure you wish to exit? The system will reboot (be sure to  
  remove any floppies from the drives). 
 
                             [ Yes ]   No</screen>
 
       <para>Select <guibutton>[ Yes ]</guibutton> and remove the floppy if
 	booting from the floppy.  The CDROM drive is locked until the machine
 	starts to reboot.  The CDROM drive is then unlocked and the disk can
 	be removed from drive (quickly).</para>
 
       <para>The system will reboot so watch for any error messages that
 	may appear.</para>
     </sect2>
 
     <sect2 id="freebsdboot">
       <title>FreeBSD Bootup</title>
 
       <sect3 id="freebsdboot-i386">
         <title>FreeBSD Bootup on the i386</title>
 
       <para>If everything went well, you will see messages scroll
 	off the screen and you will arrive at a login prompt.  You can view
 	the content of the messages by pressing <keycap>Scroll-Lock</keycap>
 	and using <keycap>PgUp</keycap> and <keycap>PgDn</keycap>.
 	Pressing <keycap>Scroll-Lock</keycap> again will return
 	to the prompt.</para>
 
       <para>The entire message may not display (buffer limitation) but
 	it can be viewed from the command line after logging in by typing
 	<command>dmesg</command> at the prompt.</para>
 
       <para>Login using the username/password you set during installation
 	(<username>rpratt</username>, in this example).  Avoid logging in as
 	<username>root</username> except when necessary.</para>
 
       <para>Typical boot messages (version information omitted):</para>
 
 <screen>Copyright (c) 1992-2002 The FreeBSD Project. 
 Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
         The Regents of the University of California. All rights reserved. 
 
 Timecounter "i8254"  frequency 1193182 Hz
 CPU: AMD-K6(tm) 3D processor (300.68-MHz 586-class CPU)
   Origin = "AuthenticAMD"  Id = 0x580  Stepping = 0
   Features=0x8001bf&lt;FPU,VME,DE,PSE,TSC,MSR,MCE,CX8,MMX&gt; 
   AMD Features=0x80000800&lt;SYSCALL,3DNow!&gt; 
 real memory  = 268435456 (262144K bytes) 
 config&gt; di sn0 
 config&gt; di lnc0 
 config&gt; di le0 
 config&gt; di ie0 
 config&gt; di fe0 
 config&gt; di cs0 
 config&gt; di bt0  
 config&gt; di aic0 
 config&gt; di aha0 
 config&gt; di adv0 
 config&gt; q 
 avail memory = 256311296 (250304K bytes)
 Preloaded elf kernel "kernel" at 0xc0491000. 
 Preloaded userconfig_script "/boot/kernel.conf" at 0xc049109c. 
 md0: Malloc disk 
 Using $PIR table, 4 entries at 0xc00fde60
 npx0: &lt;math processor&gt; on motherboard 
 npx0: INT 16 interface 
 pcib0: &lt;Host to PCI bridge&gt; on motherboard 
 pci0: &lt;PCI bus&gt; on pcib0 
 pcib1: &lt;VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge&gt; at device 1.0 on pci0 
 pci1: &lt;PCI bus&gt; on pcib1 
 pci1: &lt;Matrox MGA G200 AGP graphics accelerator&gt; at 0.0 irq 11 
 isab0: &lt;VIA 82C586 PCI-ISA bridge&gt; at device 7.0 on pci0 
 isa0: &lt;ISA bus&gt; on isab0 
 atapci0: &lt;VIA 82C586 ATA33 controller&gt; port 0xe000-0xe00f at device 7.1 on pci0 
 ata0: at 0x1f0 irq 14 on atapci0 
 ata1: at 0x170 irq 15 on atapci0 
 uhci0: &lt;VIA 83C572 USB controller&gt; port 0xe400-0xe41f irq 10 at device 7.2 on pci0 
 usb0: &lt;VIA 83C572 USB controller&gt; on uhci0 
 usb0: USB revision 1.0 
 uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr 1 
 uhub0: 2 ports with 2 removable, self powered 
 chip1: &lt;VIA 82C586B ACPI interface&gt; at device 7.3 on pci0 
 ed0: &lt;NE2000 PCI Ethernet (RealTek 8029)&gt; port 0xe800-0xe81f irq 9 at
 device 10.0 on pci0 
 ed0: address 52:54:05:de:73:1b, type NE2000 (16 bit) 
 isa0: too many dependant configs (8) 
 isa0: unexpected small tag 14 
 fdc0: &lt;NEC 72065B or clone&gt; at port 0x3f0-0x3f5,0x3f7 irq 6 drq 2 on isa0
 fdc0: FIFO enabled, 8 bytes threshold 
 fd0: &lt;1440-KB 3.5" drive&gt; on fdc0 drive 0 
 atkbdc0: &lt;keyboard controller (i8042)&gt; at port 0x60-0x64 on isa0 
 atkbd0: &lt;AT Keyboard&gt; flags 0x1 irq 1 on atkbdc0 
 kbd0 at atkbd0 
 psm0: &lt;PS/2 Mouse&gt; irq 12 on atkbdc0 
 psm0: model Generic PS/2 mouse, device ID 0 
 vga0: &lt;Generic ISA VGA&gt; at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0
 sc0: &lt;System console&gt; at flags 0x1 on isa0 
 sc0: VGA &lt;16 virtual consoles, flags=0x300&gt; 
 sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0 
 sio0: type 16550A 
 sio1 at port 0x2f8-0x2ff irq 3 on isa0 
 sio1: type 16550A 
 ppc0: &lt;Parallel port&gt; at port 0x378-0x37f irq 7 on isa0 
 ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode 
 ppc0: FIFO with 16/16/15 bytes threshold 
 ppbus0: IEEE1284 device found /NIBBLE
 Probing for PnP devices on ppbus0: 
 plip0: &lt;PLIP network interface&gt; on ppbus0 
 lpt0: &lt;Printer&gt; on ppbus0 
 lpt0: Interrupt-driven port 
 ppi0: &lt;Parallel I/O&gt; on ppbus0
 ad0: 8063MB &lt;IBM-DHEA-38451&gt; [16383/16/63] at ata0-master using UDMA33 
 ad2: 8063MB &lt;IBM-DHEA-38451&gt; [16383/16/63] at ata1-master using UDMA33 
 acd0: CDROM &lt;DELTA OTC-H101/ST3 F/W by OIPD&gt; at ata0-slave using PIO4 
 Mounting root from ufs:/dev/ad0s1a 
 swapon: adding /dev/ad0s1b as swap device 
 Automatic boot in progress... 
 /dev/ad0s1a: FILESYSTEM CLEAN; SKIPPING CHECKS 
 /dev/ad0s1a: clean, 48752 free (552 frags, 6025 blocks, 0.9% fragmentation)
 /dev/ad0s1f: FILESYSTEM CLEAN; SKIPPING CHECKS 
 /dev/ad0s1f: clean, 128997 free (21 frags, 16122 blocks, 0.0% fragmentation)
 /dev/ad0s1g: FILESYSTEM CLEAN; SKIPPING CHECKS
 /dev/ad0s1g: clean, 3036299 free (43175 frags, 374073 blocks, 1.3% fragmentation)
 /dev/ad0s1e: filesystem CLEAN; SKIPPING CHECKS 
 /dev/ad0s1e: clean, 128193 free (17 frags, 16022 blocks, 0.0% fragmentation)
 Doing initial network setup: hostname. 
 ed0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
         inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
         inet6 fe80::5054::5ff::fede:731b%ed0 prefixlen 64 tentative scopeid 0x1
         ether 52:54:05:de:73:1b
 lo0: flags=8049&lt;UP,LOOPBACK,RUNNING,MULTICAST&gt; mtu 16384 
         inet6 fe80::1%lo0 prefixlen 64 scopeid 0x8 
         inet6 ::1 prefixlen 128 
         inet 127.0.0.1 netmask 0xff000000 
 Additional routing options: IP gateway=YES TCP keepalive=YES
 routing daemons:. 
 additional daemons: syslogd. 
 Doing additional network setup:. 
 Starting final network daemons: creating ssh RSA host key 
 Generating public/private rsa1 key pair.
 Your identification has been saved in /etc/ssh/ssh_host_key. 
 Your public key has been saved in /etc/ssh/ssh_host_key.pub. 
 The key fingerprint is: 
 cd:76:89:16:69:0e:d0:6e:f8:66:d0:07:26:3c:7e:2d root@k6-2.example.com
  creating ssh DSA host key 
 Generating public/private dsa key pair.
 Your identification has been saved in /etc/ssh/ssh_host_dsa_key. 
 Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub. 
 The key fingerprint is: 
 f9:a1:a9:47:c4:ad:f9:8d:52:b8:b8:ff:8c:ad:2d:e6 root@k6-2.example.com.
 setting ELF ldconfig path: /usr/lib /usr/lib/compat /usr/X11R6/lib
 /usr/local/lib 
 a.out ldconfig path: /usr/lib/aout /usr/lib/compat/aout /usr/X11R6/lib/aout 
 starting standard daemons: inetd cron sshd usbd sendmail.
 Initial rc.i386 initialization:. 
 rc.i386 configuring syscons: blank_time screensaver moused. 
 Additional ABI support: linux. 
 Local package initilization:. 
 Additional TCP options:. 
 
 FreeBSD/i386 (k6-2.example.com) (ttyv0)
 
 login: rpratt 
 Password:</screen>
 
       <para>Generating the RSA and DSA keys may take some time on slower
 	machines.  This happens only on the initial boot-up of a new
 	installation.  Subsequent boots will be faster.</para>
 
       <para>If the X server has been configured and a Default Desktop
 	chosen, it can be started by typing <command>startx</command> at
 	the command line.</para>
 
       </sect3>
 
       <sect3>
         <title>Bootup of FreeBSD on the Alpha</title>
 
 	<indexterm><primary>Alpha</primary></indexterm>
 
         <para>Once the install procedure has finished, you will be
           able to start FreeBSD by typing something like this to the
           SRM prompt:</para>
 
 	<screen>&gt;&gt;&gt;<userinput>BOOT DKC0</userinput></screen>
 
 	<para>This instructs the firmware to boot the specified
 	  disk.  To make FreeBSD boot automatically in the future, use
 	  these commands:</para>
 
 	<screen><prompt>&gt;&gt;&gt;</prompt> <userinput>SET BOOT_OSFLAGS A</userinput>
 <prompt>&gt;&gt;&gt;</prompt> <userinput>SET BOOT_FILE ''</userinput>
 <prompt>&gt;&gt;&gt;</prompt> <userinput>SET BOOTDEF_DEV DKC0</userinput>
 <prompt>&gt;&gt;&gt;</prompt> <userinput>SET AUTO_ACTION BOOT</userinput></screen>
 
 	<para>The boot messages will be similar (but not identical) to
 	those produced by FreeBSD booting on the i386.</para>
       </sect3>
     </sect2>
 
     <sect2 id="shutdown">
       <title>FreeBSD Shutdown</title>
 
       <para>It is important to properly shutdown the operating
 	system.  Do not just turn off power.  First, become a superuser by
 	typing <command>su</command> at the command line and entering the
 	<username>root</username> password.  This will work only if the user
 	is a member of the <groupname>wheel</groupname> group.
 	Otherwise, login as <username>root</username> and use
 	<command>shutdown -h now</command>.</para>
 
       <screen>The operating system has halted. 
 Please press any key to reboot.</screen>
 
       <para>It is safe to turn off the power after the shutdown command
 	has been issued and the message <quote>Please press any key to reboot</quote>
 	appears.  If any key is pressed instead of turning off the power
 	switch, the system will reboot.</para>
 
       <para>You could also use the
         <keycombo action="simul">
 	  <keycap>Ctrl</keycap>
 	  <keycap>Alt</keycap>
 	  <keycap>Del</keycap>
 	</keycombo>
 	key combination to reboot the system, however this is not recommended
 	during normal operation.</para>
 
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="install-supported-hardware">
     <title>Supported Hardware</title>
 
     <indexterm><primary>hardware</primary></indexterm>
     <para>FreeBSD currently runs on a wide variety of ISA, VLB, EISA, and PCI
       bus-based PCs with Intel, AMD, Cyrix, or NexGen <quote>x86</quote>
       processors, as well as a number of machines based on the Compaq Alpha
       processor.  Support for generic IDE or ESDI drive configurations,
       various SCSI controllers, PCMCIA cards, USB devices, and network and
       serial cards is also provided.  FreeBSD also supports IBM's microchannel
       (MCA) bus.</para>
 
     <para>A list of supported hardware is provided with each FreeBSD release
       in the FreeBSD Hardware Notes.  This document can usually be found in a
       file named <filename>HARDWARE.TXT</filename>, in the top-level directory
       of a CDROM or FTP distribution or in
       <application>sysinstall</application>'s documentation menu.  It lists,
       for a given architecture, what hardware devices are known to be
       supported by each release of FreeBSD.  Copies of the supported
       hardware list for various releases and architectures can also be
       found on the <ulink
       url="http://www.FreeBSD.org/releases/index.html">Release
       Information</ulink> page of the FreeBSD Web site.</para>
   </sect1>
 
   <sect1 id="install-trouble">
     <title>Troubleshooting</title>
 
     <indexterm>
       <primary>installation</primary>
       <secondary>troubleshooting</secondary>
     </indexterm>
     <para>The following section covers basic installation troubleshooting,
       such as common problems people have reported.  There are also a few
       questions and answers for people wishing to dual-boot FreeBSD with
       MS-DOS.</para>
 
     <sect2>
       <title>What to Do If Something Goes Wrong</title>
 
       <para>Due to various limitations of the PC architecture, it is
         impossible for probing to be 100% reliable, however, there are a
         few things you can do if it fails.</para>
 
       <para>Check the Hardware Notes document for your version of
         FreeBSD to make sure your hardware is
         supported.</para>
 
       <para>If your hardware is supported and you still experience
         lock-ups or other problems, reset your computer, and when the
         visual kernel configuration option is given, choose it.  This will
         allow you to go through your hardware and supply information to the
         system about it.  The kernel on the boot disks is configured
         assuming that most hardware devices are in their factory default
         configuration in terms of IRQs, IO addresses, and DMA channels.  If
         your hardware has been reconfigured, you will most likely need to
         use the configuration editor to tell FreeBSD where to find
         things.</para>
 
       <para>It is also possible that a probe for a device not present will
         cause a later probe for another device that is present to fail.  In
         that case, the probes for the conflicting driver(s) should be
         disabled.</para>
 
       <note>
         <para>Some installation problems can be avoided or alleviated
           by updating the firmware on various hardware components, most notably
           the motherboard.  The motherboard firmware may also be referred to
           as <acronym>BIOS</acronym> and most of the motherboard or computer
           manufactures have a website where the upgrades and upgrade information
           may be located.</para>
 
         <para>Most manufacturers strongly advise against upgrading the motherboard
           <acronym>BIOS</acronym> unless there is a good reason for doing so, which
           could possibly be a critical update of sorts.  The upgrade process
           <emphasis>can</emphasis> go wrong, causing permanent damage to the
           <acronym>BIOS</acronym> chip.</para>
         </note>
 
       <warning>
         <para>Do not disable any drivers you will need during the
           installation, such as your screen (<devicename>sc0</devicename>).
 	  If the installation wedges or fails mysteriously after leaving
 	  the configuration editor, you have probably removed or changed
 	  something you should not have.  Reboot and try again.</para>
       </warning>
 
       <para>In configuration mode, you can:</para>
 
       <itemizedlist>
         <listitem>
           <para>List the device drivers installed in the kernel.</para>
         </listitem>
 
         <listitem>
           <para>Disable device drivers for hardware that is not present in
 	    your system.</para>
         </listitem>
 
         <listitem>
           <para>Change IRQs, DRQs, and IO port addresses used by a device
 	    driver.</para>
         </listitem>
       </itemizedlist>
 
       <para>After adjusting the kernel to match your hardware
         configuration, type <command>Q</command> to boot with the new
         settings.  Once the installation has completed, any changes you
         made in the configuration mode will be permanent so you do not have
         to reconfigure every time you boot.  It is still highly likely that
         you will eventually want to build a <link
         linkend="kernelconfig">custom kernel</link>.</para>
     </sect2>
     
     <sect2>
       <title>MS-DOS User's Questions and Answers</title>
 
       <indexterm><primary>DOS</primary></indexterm>
       <para>Many users wish to install FreeBSD on PCs inhabited by MS-DOS.
         Here are some commonly asked questions about installing FreeBSD on
         such systems:</para>
 
       <qandaset>
         <qandaentry>
 	  <question>
 	    <para>Help, I have no space!  Do I need to delete everything 
 	      first?</para>
 	  </question>
 
 	  <answer>
 	    <para>If your machine is already running MS-DOS and has little
 	      or no free space available for the FreeBSD installation, all
 	      hope is not lost!  You may find the <application>FIPS</application>
 	      utility, provided
 	      in the <filename>tools</filename> directory on the FreeBSD
 	      CDROM or various FreeBSD FTP sites to be quite
 	      useful.</para>
 
 	    <indexterm>
 	      <primary><command>FIPS</command></primary>
 	    </indexterm>
 	    <para><application>FIPS</application> allows you to split an
 	      existing MS-DOS partition into two pieces, preserving the
 	      original partition and allowing you to install onto the second
 	      free piece.  You first defragment your MS-DOS partition using
 	      the Windows <application>DEFRAG</application> utility (go into
 	      Explorer, right-click on the hard drive, and choose to defrag
 	      your hard drive), or Norton Disk Tools.  You then must run
 	      <application>FIPS</application>.  It will prompt you for the
 	      rest of the information it needs.  Afterwards, you can reboot
 	      and install FreeBSD on the new free slice.  See the
 	      <emphasis>Distributions</emphasis> menu for an estimate of how
 	      much free space you will need for the kind of installation you
 	      want.</para>
 
 	    <indexterm>
 	      <primary><application>Partition Magic</application></primary>
 	    </indexterm>
 	    <para>There is also a <emphasis>very</emphasis> useful product
 	      from <ulink url="http://www.powerquest.com/">PowerQuest</ulink>
 	      called <application>Partition Magic</application>.  This
 	      application has far more functionality than
 	      <application>FIPS</application>, and is highly recommended if
 	      you plan to often add/remove operating systems (like me).
 	      However, it does cost money, and if you plan to install FreeBSD
 	      once and then leave it there, <application>FIPS</application>
 	      will probably be fine for you.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Can I use compressed MS-DOS filesystems from
 	      FreeBSD?</para>
 	  </question>
 
 	  <answer>
 	    <para>No.  If you are using a utility such as
 	      <trademark class="trade">Stacker</trademark> or
 	      <trademark class="trade">DoubleSpace</trademark>, FreeBSD
 	      will only be able to use whatever portion of the filesystem
 	      you leave uncompressed.  The rest of the filesystem will
 	      show up as one large file (the stacked/double spaced file!).
 	      <emphasis>Do not remove that file or you will probably regret
 	      it greatly!</emphasis></para>
 
 	    <para>It is probably better to create another uncompressed
 	      primary MS-DOS partition and use this for communications
 	      between MS-DOS and FreeBSD.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Can I mount my extended MS-DOS partition?</para>
 	  </question>
 
 	  <answer>
 	    <indexterm><primary>partitions</primary></indexterm>
 	    <indexterm><primary>slices</primary></indexterm>
 	    <para>Yes.  DOS extended partitions are mapped in at the end
 	      of the other <quote>slices</quote> in FreeBSD, e.g., your
 	      <devicename>D:</devicename> drive might be
 	      <filename>/dev/da0s5</filename>, your
 	      <devicename>E:</devicename> drive,
 	      <filename>/dev/da0s6</filename>, and so on.  This example
 	      assumes, of course, that your extended partition is on SCSI
 	      drive 0.  For IDE drives, substitute <filename>ad</filename>
 	      for <filename>da</filename> appropriately if installing
 	      4.0-RELEASE or later, and substitute
 	      <filename>wd</filename> for <filename>da</filename> if you
 	      are installing a version of FreeBSD prior to 4.0.  You otherwise
 	      mount extended partitions exactly like you would any other
 	      DOS drive, for example:</para>
 
 	    <screen>&prompt.root; <userinput>mount -t msdos /dev/ad0s5 /dos_d</userinput></screen>
 	  </answer>
 	</qandaentry>
       </qandaset>
     </sect2>
 
     <sect2>
       <title>Alpha User's Questions and Answers</title>
 
       <indexterm><primary>Alpha</primary></indexterm>
 
       <para>This section answers some commonly asked questions about
         installing FreeBSD on Alpha systems.</para>
 
       <qandaset>
 	<qandaentry>
 	  <question>
 	    <para>Can I boot from the ARC or Alpha BIOS Console?</para>
 	  </question>
 
 	  <indexterm><primary>ARC</primary></indexterm>
 	  <indexterm><primary>Alpha BIOS</primary></indexterm>
 	  <indexterm><primary>SRM</primary></indexterm>
 
 	  <answer>
 	    <para>No.  &os;, like Compaq Tru64 and VMS, will only boot
 	    from the SRM console.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Help, I have no space!  Do I need to delete
 	    everything first?</para>
 	  </question>
 
 	  <answer>
 	    <para>Unfortunately, yes.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	    <para>Can I mount my Compaq Tru64 or VMS filesystems?</para>
 	  </question>
 
 	  <answer>
 	    <para>No, not at this time.</para>
 	  </answer>
 	</qandaentry>
       </qandaset>
     </sect2>
   </sect1>
 
   <sect1 id="install-advanced">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Valentino</firstname>
 	  <surname>Vaschetto</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<!-- May 2001 -->
       </authorgroup>
     </sect1info>
 
     <title>Advanced Installation Guide</title>
 
     <para>This section describes how to install FreeBSD in exceptional
        cases.</para>
 
     <sect2 id="headless-install">
       <title>Installing FreeBSD on a System without a Monitor or
         Keyboard</title>
 
       <indexterm>
         <primary>installation</primary>
         <secondary>headless (serial console)</secondary>
       </indexterm>
       <indexterm><primary>serial console</primary></indexterm>
       <para>This type of installation is called a <quote>headless
 	install</quote>, because the machine that you are trying to install
 	FreeBSD on either does not have a monitor attached to it, or does not
 	even have a VGA output.  How is this possible you ask? Using a
         serial console.  A serial console is basically using another
         machine to act as the main display and keyboard for a
         system.  To do this, just follow these steps:</para>
 
       <procedure>
         <step>
           <title>Fetch the Right Boot Floppy Images</title>
 
           <para>First you will need to get the right disk images so
             that you can boot into the install program.  The secret
             with using a serial console is that you tell the boot
             loader to send I/O through a serial port instead of
             displaying console output to the VGA device and trying to
             read input from a local keyboard.  Enough of that now,
             let's get back to getting these disk images.</para>
 
 	  <para>You will need to get
 	    <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/kern.flp">kern.flp</ulink>
 	    and
             <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/mfsroot.flp">mfsroot.flp</ulink>
 	    from the
             <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/">
             floppies directory</ulink>.</para>
 
         </step>
         <step>
 	  <title>Write the Image Files to the Floppy Disks</title>
 
 	  <para>The image files, such as <filename>kern.flp</filename>, are
 	    <emphasis>not</emphasis> regular files that you copy to the disk.
 	    Instead, they are images of the complete contents of the
 	    disk.</para>
 
 	  <para>This means that you can <emphasis>not</emphasis> use
 	    commands like DOS' <command>copy</command> to write the
 	    files.  Instead, you must use specific tools to write the
 	    images directly to the disk.</para>
 	  
 	  <indexterm>
 	    <primary><command>fdimage</command></primary>
 	  </indexterm>
 	  <para>If you are creating the floppies on a computer running
 	    DOS then we provide a tool to do this called
 	    <command>fdimage</command>.</para>
 	  
 	  <para>If you are using the floppies from the CDROM, and
 	    your CDROM is the <devicename>E:</devicename> drive then
 	    you would run this:</para>
 
 	  <screen><prompt>E:\&gt;</prompt> <userinput>tools\fdimage floppies\kern.flp A:</userinput></screen> 
 
 	  <para>Repeat this command for each <filename>.flp</filename>
 	    file, replacing the floppy disk each time.  Adjust the
 	    command line as necessary, depending on where you have
 	    placed the <filename>.flp</filename> files.  If you do not
 	    have the CDROM then <command>fdimage</command> can be
 	    downloaded from the <ulink
 	    url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/"><filename>tools</filename>
 	    directory</ulink> on the FreeBSD FTP site.</para>
 
 	  <para>If you are writing the floppies on a Unix system (such
 	    as another FreeBSD system) you can use the &man.dd.1;
 	    command to write the image files directly to disk.  On
 	    FreeBSD you would run:</para>
 
 	  <screen>&prompt.root; <userinput>dd if=kern.flp of=/dev/fd0</userinput></screen>
 
 	  <para>On FreeBSD <filename>/dev/fd0</filename> refers to
 	    the first floppy disk (the <devicename>A:</devicename>
 	    drive).  <filename>/dev/fd1</filename> would be the
 	    <devicename>B:</devicename> drive, and so on.  Other Unix
 	    variants might have different names for the floppy disk
 	    devices, and you will need to check the documentation for
 	    the system as necessary.</para>
 
 	  </step>
 
 	  <step>
 	    <title>Enabling the Boot Floppies to Boot into a Serial
 	    Console</title>
 
             <warning>
               <para>Do not try to mount the floppy if it is write-protected.</para>
             </warning>
 
   	    <indexterm>
 	      <primary><command>mount</command></primary>
 	    </indexterm>
 	    <para>If you were to boot into the floppies that you just
 	      made, FreeBSD would boot into its normal install mode.  We
 	      want FreeBSD to boot into a serial console for our
 	      install.  To do this, you have to mount the
 	      <filename>kern.flp</filename> floppy onto your FreeBSD
 	      system using the &man.mount.8; command.</para>
 
             <screen>&prompt.root; <userinput>mount /dev/fd0 /mnt</userinput></screen>
 
 	    <para>Now that you have the floppy mounted, you must
 	      change into the floppy directory:</para>
 
 	    <screen>&prompt.root; <userinput>cd /mnt</userinput></screen>
 
 	    <para>Here is where you must set the floppy to boot into a
 	      serial console.  You have to make a file called
 	      <filename>boot.config</filename> containing 
 	      <literal>/boot/loader -h</literal>.  All this does is pass a flag to the bootloader to
 	      boot into a serial console.</para>
 
 	    <screen>&prompt.root; <userinput>echo "/boot/loader -h" > boot.config</userinput></screen>
 
 	    <para>Now that you have your floppy configured correctly,
 	      you must unmount the floppy using the &man.umount.8;
 	      command:</para>
 
             <screen>&prompt.root; <userinput>cd /</userinput>
 &prompt.root; <userinput>umount /mnt</userinput></screen>
 
 	    <para>Now you can remove the floppy from the floppy
 	      drive.</para>
 	  </step>
 
 	  <step>
 	    <title>Connecting Your Null Modem Cable</title>
 
   	    <indexterm><primary>null modem cable</primary></indexterm>
 	    <para>You now need to connect a null modem cable between
 	      the two machines.  Just connect the cable to the serial
 	      ports of the 2 machines.  <emphasis>A normal serial cable
 	      will not work here</emphasis>, you need a null modem
 	      cable because it has some of the wires inside crossed
 	      over.</para>
 	  </step>
 
 	  <step>
 	    <title>Booting Up for the Install</title>
 
 	    <para>It is now time to go ahead and start the install.  Put
 	      the <filename>kern.flp</filename> floppy in the floppy
 	      drive of the machine you are doing the headless install
 	      on, and power on the machine.</para>
 	  </step>
 
 	  <step>
 	    <title>Connecting to Your Headless Machine</title>
 	    <indexterm>
 	      <primary><command>cu</command></primary>
 	    </indexterm>
 	    <para>Now you have to connect to that machine with
 	      &man.cu.1;:</para> 
 
 	    <screen>&prompt.root; <userinput>cu -l /dev/cuaa0</userinput></screen>
 	  </step>
       </procedure>
 
       <para>That's it! You should be able to control the headless machine
 	through your <command>cu</command> session now.  It will ask you to
 	put in the <filename>mfsroot.flp</filename>, and then it will come up
 	with a selection of what kind of terminal to use.  Just select the
 	FreeBSD color console and proceed with your install!</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="install-diff-media">
     <title>Preparing Your Own Installation Media</title>
 
     <note>
       <para>To prevent repetition, <quote>FreeBSD disk</quote> in this context
 	means a FreeBSD CDROM or DVD that you have purchased, or produced
 	yourself.</para>
     </note>
 
     <para>There may be some situations in which you need to create your own
       FreeBSD installation media and/or source.  This might be physical media,
       such as a tape, or a source that <application>sysinstall</application>
       can use to retrieve the files, such as a local FTP site, or an MS-DOS
       partition.  For example:</para>
 
     <itemizedlist>
       <listitem>
 	<para>You have many machines connected to your local network, and one
 	  FreeBSD disk.  You want to create a local FTP site using the
 	  contents of the FreeBSD disk, and then have your machines use this
 	  local FTP site instead of needing to connect to the Internet.</para>
       </listitem>
 
       <listitem>
 	<para>You have a FreeBSD disk, FreeBSD does not recognize your CD/DVD
 	  drive, but DOS/Windows does.  You want to copy the FreeBSD
 	  installations files to a DOS partition on the same computer, and
 	  then install FreeBSD using those files.</para>
       </listitem>
 
       <listitem>
 	<para>The computer you want to install on does not have a CD/DVD
 	  drive, or a network card, but you can connect a
 	  <quote>Laplink-style</quote> serial or parallel cable to a computer
 	  that does.</para>
       </listitem>
 
       <listitem>
 	<para>You want to create a tape that can be used to install
 	  FreeBSD.</para>
       </listitem>
     </itemizedlist>
 
     <sect2 id="install-cdrom">
       <title>Creating an installation CDROM</title>
 
       <para>As part of each release, the FreeBSD project makes available five
 	CDROM images (<quote>ISO images</quote>).  These images can be written
 	(<quote>burned</quote>) to CDs if you have a CD writer, and then used
 	to install FreeBSD.  If you have a CD writer, and bandwidth is cheap,
 	then this is the easiest way to install FreeBSD.</para>
 
       <procedure>
 	<step>
 	  <title>Download the correct ISO images</title>
 
 	  <para>The ISO images for each release can be downloaded from <filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/ISO-IMAGES-<replaceable>arch</replaceable>/<replaceable>version</replaceable></filename> or the closest mirror.  
 	    Substitute <replaceable>arch</replaceable> and 
 	    <replaceable>version</replaceable> as appropriate.</para>
 
 	  <para>That directory will normally contain the following images:</para>
 
 	  <table frame="none">
 	    <title>FreeBSD ISO image names and meanings</title>
 
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>Filename</entry>
 
 		  <entry>Contains</entry>
 		</row>
 	      </thead>
 
 	      <tbody>
 		<row>
 		  <entry><filename><replaceable>version</replaceable>-mini.iso</filename></entry>
 		  
 		  <entry>Everything you need to install FreeBSD.</entry>
 		</row>
 
 		<row>
 		  <entry><filename><replaceable>version</replaceable>-disc1.iso</filename></entry>
 
 		  <entry>Everything you need to install FreeBSD, and as many
 		    additional third party packages as would fit on the
 		    disc.</entry>
 		</row>
 
 		<row>
 		  <entry><filename><replaceable>version</replaceable>-disc2.iso</filename></entry>
 
 		  <entry>A <quote>live filesystem</quote>, which is used in
 		    conjunction with the <quote>Repair</quote> facility in
 		    <application>sysinstall</application>.  A copy of the
 		    FreeBSD CVS tree.  As many additional third party packages
 		    as would fit on the disc.</entry>
 		</row>
 
 		<row>
 		  <entry><filename><replaceable>version</replaceable>-disc3.iso</filename></entry>
 
 		  <entry>As many additional third party packages as would fit
 		    on the disc.</entry>
 		</row>
 
 		<row>
 		  <entry><filename><replaceable>version</replaceable>-disc4.iso</filename></entry>
 
 		  <entry>As many additional third party packages as would fit
 		    on the disc.</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </table>
 
 	  <note>
 	    <para>The mini ISO was only produced for FreeBSD&nbsp;4.4 and
 	      subsequent releases.  The images for discs two, three, and four
 	      were only produced for FreeBSD&nbsp;4.5 and subsequent
 	      releases.</para>
 	  </note>
 
 	  <para>You <emphasis>must</emphasis> download one of either the mini
 	    ISO image, or the image of disc one.  Do not download both of them,
 	    since the disc one image contains everything that the mini ISO
 	    image contains.</para>
 
 	  <para>Use the mini ISO if Internet access is cheap for you.  It will
 	    let you install FreeBSD, and you can then install third party
 	    packages by downloading them using the ports/packages system (see
 	    <xref linkend="ports">) as
 	    necessary.</para>
 
 	  <para>Use the image of disc one if you want a reasonable selection
 	    of third party packages on the disc as well.</para>
 
 	  <para>The additional disc images are useful, but not essential,
 	    especially if you have high-speed access to the Internet.</para>
 	</step>
 
 	<step>
 	  <title>Write the CDs</title>
 
 	  <para>You must then write the CD images to disc.  If you will be
 	    doing this on another FreeBSD system then see 
 	    <xref linkend="creating-cds"> for more information (in 
 	    particular, <xref linkend="burncd"> and 
 	    <xref linkend="cdrecord">).</para>
 
 	  <para>If you will be doing this on another platform then you will
 	    need to use whatever utilities exist to control your CD writer on
 	    that platform.</para>
 	</step>
       </procedure>
     </sect2>
 
     <sect2 id="install-ftp">
       <title>Creating a Local FTP Site with a FreeBSD Disk</title>
 	
       <indexterm>
 	<primary>installation</primary>
 	<secondary>network</secondary>
 	<tertiary>FTP</tertiary>
       </indexterm>
 
       <para>FreeBSD disks are laid out in the same way as the FTP site.  This
 	makes it very easy for you to create a local FTP site that can be used
 	by other machines on your network when installing FreeBSD.</para>
 
       <procedure>
 	<step>
 	  <para>On the FreeBSD computer that will host the FTP site, ensure
 	    that the CDROM is in the drive, and mounted on
 	    <filename>/cdrom</filename>.</para>
 
 	  <screen>&prompt.root; <userinput>mount /cdrom</userinput></screen>
 	</step>
 
 	<step>
 	  <para>Create an account for anonymous FTP in
 	    <filename>/etc/passwd</filename>.  Do this by editing
 	    <filename>/etc/passwd</filename> using &man.vipw.8; and adding
 	    this line.</para>
 
 	  <programlisting>ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
 	</step>
 
 	<step>
 	  <para>Ensure that the FTP service is enabled in
 	    <filename>/etc/inetd.conf</filename>.</para>
 	</step>
       </procedure>
 
       <para>Anyone with network connectivity to your machine can now
 	chose a media type of FTP and type in
 	<userinput>ftp://<replaceable>your machine</replaceable></userinput>
 	after picking <quote>Other</quote> in the FTP sites menu during
 	the install.</para>
 
       <warning>
 	<para>This approach is OK for a machine that is on your local network,
 	  and that is protected by your firewall.  Offering up FTP services to
 	  other machines over the Internet (and not your local network)
 	  exposes your computer to the attention of crackers and other
 	  undesirables.  We strongly recommend that you follow good security
 	  practices if you do this.</para>
       </warning>
     </sect2>
 
       <sect2>
         <title>Creating Installation Floppies</title>
 
       <indexterm>
 	<primary>installation</primary>
 	<secondary>floppies</secondary>
       </indexterm>
 
       <para>If you must install from floppy disk (which we suggest you
 	do <emphasis>not</emphasis> do), either due to unsupported
 	hardware or simply because you insist on doing things the hard
 	way, you must first prepare some floppies for the installation.</para>
 
 	<para>At a minimum, you will need as many 1.44&nbsp;MB or 1.2&nbsp;MB floppies
 	  as it takes to hold all the files in the
 	  <filename>bin</filename> (binary distribution) directory.  If
 	  you are preparing the floppies from DOS, then they
 	  <emphasis>MUST</emphasis> be formatted using the MS-DOS
 	  <command>FORMAT</command> command.  If you are using Windows,
 	  use Explorer to format the disks (right-click on the
 	  <devicename>A:</devicename> drive, and select <quote>Format</quote>.</para>
 
 	<para>Do <emphasis>not</emphasis> trust factory pre-formatted
 	  floppies.  Format them again yourself, just to be sure.  Many
 	  problems reported by our users in the past have resulted from
 	  the use of improperly formatted media, which is why we are
 	  making a point of it now.</para>
 
 	<para>If you are creating the floppies on another FreeBSD machine,
 	  a format is still not a bad idea, though you do not need to put
 	  a DOS filesystem on each floppy.  You can use the
 	  <command>disklabel</command> and <command>newfs</command>
 	  commands to put a UFS filesystem on them instead, as the
 	  following sequence of commands (for a 3.5" 1.44&nbsp;MB floppy)
 	  illustrates:</para>
 
 	<screen>&prompt.root; <userinput>fdformat -f 1440 fd0.1440</userinput>
 &prompt.root; <userinput>disklabel -w -r fd0.1440 floppy3</userinput>
 &prompt.root; <userinput>newfs -t 2 -u 18 -l 1 -i 65536 /dev/fd0</userinput></screen>
 
 	<note>
 	  <para>Use <literal>fd0.1200</literal> and
 	    <literal>floppy5</literal> for 5.25" 1.2&nbsp;MB disks.</para>
 	</note>
 
 	<para>Then you can mount and write to them like any other
 	  filesystem.</para>
 
 	<para>After you have formatted the floppies, you will need to copy
 	  the files to them.  The distribution files are split into chunks
 	  conveniently sized so that 5 of them will fit on a conventional
 	  1.44&nbsp;MB floppy.  Go through all your floppies, packing as many
 	  files as will fit on each one, until you have all of the
 	  distributions you want packed up in this fashion.  Each
 	  distribution should go into a subdirectory on the floppy, e.g.:
 	  <filename>a:\bin\bin.aa</filename>,
 	  <filename>a:\bin\bin.ab</filename>, and so on.</para>
 
 	<para>Once you come to the Media screen during the install
 	  process, select <quote>Floppy</quote> and you will be prompted
 	  for the rest.</para>
       </sect2>
 
       <sect2 id="install-msdos">
         <title>Installing from an MS-DOS Partition</title>
 
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>from MS-DOS</secondary>
 	</indexterm>
 	<para>To prepare for an installation from an MS-DOS partition,
 	  copy the files from the distribution into a directory
           called <filename>freebsd</filename> in the root directory of the
 	  partition.  For example, <filename>c:\freebsd</filename>.  The
 	  directory structure of the CDROM or FTP site must be partially
 	  reproduced within this directory, so we suggest using the DOS
 	  <command>xcopy</command> command if you are copying it from a CD.
 	  For example, to prepare for a minimal installation of
 	  FreeBSD:</para>
 
 	<screen><prompt>C:\&gt;</prompt> <userinput>md c:\freebsd</userinput>
 <prompt>C:\&gt;</prompt> <userinput>xcopy e:\bin c:\freebsd\bin\ /s</userinput>
 <prompt>C:\&gt;</prompt> <userinput>xcopy e:\manpages c:\freebsd\manpages\ /s</userinput></screen>
 
 	<para>Assuming that <devicename>C:</devicename> is where you have
 	  free space and <devicename>E:</devicename> is where your CDROM
 	  is mounted.</para>
 	
 	<para>If you do not have a CDROM drive, you can download the
 	  distribution from <ulink
 	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">ftp.FreeBSD.org</ulink>.
 	  Each distribution is in its own directory; for example, the
 	  <emphasis>bin</emphasis> distribution can be found in the <ulink
 	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/bin/">&rel.current;/bin/</ulink>
 	  directory.</para>
     
 	<para>For as many distributions you wish to install from an MS-DOS
 	  partition (and you have the free space for), install each one
 	  under <filename>c:\freebsd</filename> &mdash; the
 	  <literal>BIN</literal> distribution is the only one required for
 	  a minimum installation.</para>
       </sect2>
 
       <sect2>
         <title>Creating an Installation Tape</title>
 
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>from QIC/SCSI Tape</secondary>
 	</indexterm>
 	<para>Installing from tape is probably the easiest method, short
 	  of an online FTP install or CDROM install.  The installation
 	  program expects the files to be simply tarred onto the tape.
 	  After getting all of the distribution files you are interested
 	  in, simply tar them onto the tape:</para>
 
 	<screen>&prompt.root; <userinput>cd /freebsd/distdir</userinput>
 &prompt.root; <userinput>tar cvf /dev/rwt0 dist1 ... dist2</userinput></screen>
 
 	<para>When you go to do the installation, you should also make
 	  sure that you leave enough room in some temporary directory
 	  (which you will be allowed to choose) to accommodate the
 	  <emphasis>full</emphasis> contents of the tape you have created.
 	  Due to the non-random access nature of tapes, this method of
 	  installation requires quite a bit of temporary storage.  You
 	  should expect to require as much temporary storage as you have
 	  stuff written on tape.</para>
 
 	<note>
 	  <para>When starting the installation, the tape must be in the
 	    drive <emphasis>before</emphasis> booting from the boot
 	    floppy.  The installation probe may otherwise fail to find
 	    it.</para>
 	</note>
       </sect2>
 
       <sect2>
         <title>Before Installing over a Network</title>
 
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>network</secondary>
 	  <tertiary>serial (SLIP or PPP)</tertiary>
 	</indexterm>
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>network</secondary>
 	  <tertiary>parallel (PLIP)</tertiary>
 	</indexterm>
 	<indexterm>
 	  <primary>installation</primary>
 	  <secondary>network</secondary>
 	  <tertiary>Ethernet</tertiary>
 	</indexterm>
 	<para>There are three types of network installations you can do.
 	  Serial port (SLIP or PPP), Parallel port (PLIP (laplink cable)),
 	  or Ethernet (a standard Ethernet controller (includes some
 	  PCMCIA)).</para>
 
 	<para>The SLIP support is rather primitive, and limited primarily
 	  to hard-wired links, such as a serial cable running between a
 	  laptop computer and another computer.  The link should be
 	  hard-wired as the SLIP installation does not currently offer a
 	  dialing capability; that facility is provided with the PPP
 	  utility, which should be used in preference to SLIP whenever
 	  possible.</para>
 
 	<para>If you are using a modem, then PPP is almost certainly
 	  your only choice.  Make sure that you have your service
 	  provider's information handy as you will need to know it fairly
 	  early in the installation process.</para>  
 
 	<para>If you use PAP or CHAP to connect your ISP (in other words, if
 	  you can connect to the ISP in Windows without using a script), then
 	  all you will need to do is type in <command>dial</command> at the
 	  <application>ppp</application> prompt.  Otherwise, you will need to
 	  know how to dial your ISP using the <quote>AT commands</quote>
 	  specific to your modem, as the PPP dialer provides only a very
 	  simple terminal emulator.  Please refer to the user-ppp <link
 	  linkend="userppp">handbook</link> and <ulink
 	  url="../faq/ppp.html">FAQ</ulink> entries for further information.
 	  If you have problems, logging can be directed to the screen using
 	  the command <command>set log local ...</command>.</para>
 
 	<para>If a hard-wired connection to another FreeBSD (2.0-R or
 	  later) machine is available, you might also consider installing
 	  over a <quote>laplink</quote> parallel port cable.  The data rate
 	  over the parallel port is much higher than what is typically
 	  possible over a serial line (up to 50&nbsp;kbytes/sec), thus resulting
 	  in a quicker installation.</para>
 
 	<para>Finally, for the fastest possible network installation, an
 	  Ethernet adapter is always a good choice!  FreeBSD supports most
 	  common PC Ethernet cards; a table of supported cards (and their
 	  required settings) is provided in the Hardware Notes for each
 	  release of FreeBSD.  If you are using one of the supported PCMCIA
 	  Ethernet cards, also be sure that it is plugged in
 	  <emphasis>before</emphasis> the laptop is powered on!  FreeBSD does
 	  not, unfortunately, currently support hot insertion of PCMCIA cards
 	  during installation.</para>
 
 	<para>You will also need to know your IP address on the network,
 	  the netmask value for your address class, and the name of your
 	  machine.  If you are installing over a PPP connection and do not
 	  have a static IP, fear not, the IP address can be dynamically
 	  assigned by your ISP.  Your system administrator can tell you
 	  which values to use for your particular network setup.  If you
 	  will be referring to other hosts by name rather than IP address,
 	  you will also need a name server and possibly the address of a
 	  gateway (if you are using PPP, it is your provider's IP address)
 	  to use in talking to it.  If you want to install by FTP via a
 	  HTTP proxy (see below), you will also need the proxy's address.
 	  If you do not know the answers to all or most of these questions,
 	  then you should really probably talk to your system administrator
 	  or ISP <emphasis>before</emphasis> trying this type of
 	  installation.</para>
 
 	<sect3>
 	  <title>Before Installing via NFS</title>
 
 	  <indexterm>
 	    <primary>installation</primary>
 	    <secondary>network</secondary>
 	    <tertiary>NFS</tertiary>
 	  </indexterm>
 	  <para>The NFS installation is fairly straight-forward.  Simply
 	    copy the FreeBSD distribution files you want onto a server
 	    somewhere and then point the NFS media selection at it.</para>
 
 	  <para>If this server supports only <quote>privileged port</quote>
 	    (as is generally the default for Sun workstations), you will
 	    need to set this option in the Options menu before
 	    installation can proceed.</para>
 
 	  <para>If you have a poor quality Ethernet card which suffers
 	    from very slow transfer rates, you may also wish to toggle the
 	    appropriate Options flag.</para>
 
 	  <para>In order for NFS installation to work, the server must
 	    support subdir mounts, e.g., if your FreeBSD&nbsp;3.4 distribution
 	    directory lives on:
 	    <filename>ziggy:/usr/archive/stuff/FreeBSD</filename>, then
 	    <hostid>ziggy</hostid> will have to allow the direct mounting
 	    of <filename>/usr/archive/stuff/FreeBSD</filename>, not just
 	    <filename>/usr</filename> or
 	    <filename>/usr/archive/stuff</filename>.</para>
 
 	  <para>In FreeBSD's <filename>/etc/exports</filename> file, this
 	    is controlled by the <option>-alldirs</option>.  Other NFS
 	    servers may have different conventions.  If you are getting
 	    <quote>permission denied</quote> messages from the server, then
 	    it is likely that you do not have this enabled
 	    properly.</para>
 	</sect3>
 
       </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
index ee4005773e..d592989473 100644
--- a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
@@ -1,921 +1,921 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="introduction">
   <chapterinfo>
     <authorgroup>
       <author>
         <firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured, reorganized, and parts
 	  rewritten by </contrib>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Introduction</title>
 
-  <sect1>
+  <sect1 id="introduction-synopsis">
     <title>Synopsis</title>
 
     <para>Thank you for your interest in FreeBSD!  The following chapter
       covers various aspects of the FreeBSD Project, such as its history,
       goals, development model, and so on.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How FreeBSD relates to other computer operating systems.</para>
       </listitem>
       <listitem>
 	<para>The history of the FreeBSD Project.</para>
       </listitem>
       <listitem>
 	<para>The goals of the FreeBSD Project.</para>
       </listitem>
       <listitem>
 	<para>The basics of the FreeBSD open-source development model.</para>
       </listitem>
       <listitem>
 	<para>And of course: where the name <quote>FreeBSD</quote> comes from.</para>
       </listitem>
     </itemizedlist>
 
   </sect1>
 
   <sect1 id="nutshell">
     <title>Welcome to FreeBSD!</title>
     <indexterm><primary>4.4BSD-Lite</primary></indexterm> 
 
     <para>FreeBSD is a 4.4BSD-Lite based operating system for the Intel
       architecture (x86) and DEC Alpha based systems.  Ports to other
       architectures are also underway.  For a brief overview of FreeBSD,
       see the <link linkend="nutshell">next section</link>.  You can also
       read about <link linkend="history">the history of FreeBSD</link>,
       or the <link linkend="relnotes">current release</link>.  If you
       are interested in contributing something to the Project (code,
       hardware, unmarked bills), see the <ulink
 	url="../../articles/contributing/index.html">Contributing to FreeBSD</ulink> article.</para>
 
     <sect2>
       <title>What Can FreeBSD Do?</title>
 
       <para>FreeBSD has many noteworthy features.  Some of these
         are:</para>
 
       <itemizedlist>
         <indexterm><primary>preemptive multitasking</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Preemptive multitasking</emphasis> with
 	    dynamic priority adjustment to ensure smooth and fair
 	    sharing of the computer between applications and users, even
 	    under the heaviest of loads.</para>
 	</listitem>
 
 	<indexterm><primary>multi-user facilities</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Multi-user facilities</emphasis> which allow many
 	    people to use a FreeBSD system simultaneously for a variety
 	    of things.  This means, for example, that system peripherals
 	    such as printers and tape drives are properly shared between
 	    all users on the system or the network and that individual
 	    resource limits can be placed on users or groups of users,
 	    protecting critical system resources from over-use.</para>
 	</listitem>
       
 	<indexterm><primary>TCP/IP networking</primary></indexterm>
 	<listitem>
 	  <para>Strong <emphasis>TCP/IP networking</emphasis> with
 	    support for industry standards such as SLIP, PPP, NFS, DHCP,
 	    and NIS.  This means that your FreeBSD machine can
 	    interoperate easily with other systems as well as act as an
 	    enterprise server, providing vital functions such as NFS
 	    (remote file access) and email services or putting your
 	    organization on the Internet with WWW, FTP, routing and
 	    firewall (security) services.</para>
 	</listitem>
 
 	<indexterm><primary>memory protection</primary></indexterm>      
 	<listitem>
 	  <para><emphasis>Memory protection</emphasis> ensures that
 	    applications (or users) cannot interfere with each other. One
 	    application crashing will not affect others in any way.</para>
 	</listitem>
       
 	<listitem>
 	  <para>FreeBSD is a <emphasis>32-bit</emphasis> operating
 	    system (<emphasis>64-bit</emphasis> on the Alpha) and was
 	    designed as such from the ground up.</para>
 	</listitem>
 
 	<indexterm>
     <primary>X Window System</primary>
     <seealso>XFree86</seealso>
   </indexterm>
 
 	<listitem>
 	  <para>The industry standard <emphasis>X Window System</emphasis>
 	    (X11R6) provides a graphical user interface (GUI) for the cost
 	    of a common VGA card and monitor and comes with full
 	    sources.</para>
 	</listitem>
 
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>Linux</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>SCO</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>SVR4</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>BSD/OS</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>binary compatibility</primary>
 	  <secondary>NetBSD</secondary>
 	</indexterm>
 	<listitem>
 	  <para><emphasis>Binary compatibility</emphasis> with many
 	    programs built for Linux, SCO, SVR4, BSDI and NetBSD.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>Thousands of <emphasis>ready-to-run</emphasis>
 	    applications are available from the FreeBSD
 	    <emphasis>ports</emphasis> and <emphasis>packages</emphasis>
 	    collection.  Why search the net when you can find it all right
 	    here?</para>
 	</listitem>
       
 	<listitem>
 	  <para>Thousands of additional and
 	    <emphasis>easy-to-port</emphasis> applications are available
 	    on the Internet.  FreeBSD is source code compatible with most
 	    popular commercial Unix systems and thus most applications
 	    require few, if any, changes to compile.</para>
 	</listitem>
       
 	<indexterm><primary>virtual memory</primary></indexterm>
 	<listitem>
 	  <para>Demand paged <emphasis>virtual memory</emphasis> and
 	    <quote>merged VM/buffer cache</quote> design efficiently
 	    satisfies applications with large appetites for memory while
 	    still maintaining interactive response to other users.</para>
 	</listitem>
       
         <indexterm>
 	  <primary>Symmetric Multi-Processing (SMP)</primary>
 	</indexterm>
 	<listitem>
 	  <para><emphasis>SMP</emphasis> support for machines with
 	    multiple CPUs.</para>
 	</listitem>
 
 	<indexterm>
 	  <primary>compilers</primary>
 	  <secondary>C</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>compilers</primary>
 	  <secondary>C++</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>compilers</primary>
 	  <secondary>Fortran</secondary>
 	</indexterm>
 	<listitem>
 	  <para>A full complement of <emphasis>C</emphasis>,
 	    <emphasis>C++</emphasis>, <emphasis>Fortran</emphasis>, and
 	    <emphasis>Perl</emphasis> development tools.
 	    Many additional languages for advanced research
 	    and development are also available in the ports and packages
 	    collection.</para>
 	</listitem>
 
 	<indexterm><primary>source code</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Source code</emphasis> for the entire system
 	    means you have the greatest degree of control over your
 	    environment.  Why be locked into a proprietary solution
 	    at the mercy of your vendor when you can have a truly open
 	    system?</para>
 	</listitem>
       
 	<listitem>
 	  <para>Extensive <emphasis>online
 	    documentation</emphasis>.</para>
 	</listitem>
       
 	<listitem>
 	  <para><emphasis>And many more!</emphasis></para>
 	</listitem>
       </itemizedlist>
     
       <indexterm><primary>4.4BSD-Lite</primary></indexterm>
       <indexterm>
         <primary>Computer Systems Research Group (CSRG)</primary>
       </indexterm>
       <indexterm><primary>U.C. Berkeley</primary></indexterm>
       <para>FreeBSD is based on the 4.4BSD-Lite release from Computer
         Systems Research Group (CSRG) at the University of California at
 	Berkeley, and carries on the distinguished tradition of BSD
 	systems development.  In addition to the fine work provided by
 	CSRG, the FreeBSD Project has put in many thousands of hours in
 	fine tuning the system for maximum performance and reliability in
 	real-life load situations.  As many of the commercial giants
 	struggle to field PC operating systems with such features,
 	performance and reliability, FreeBSD can offer them
 	<emphasis>now</emphasis>!</para>
 
       <para>The applications to which FreeBSD can be put are truly
         limited only by your own imagination.  From software development
 	to factory automation, inventory control to azimuth correction of
 	remote satellite antennae; if it can be done with a commercial
 	Unix product then it is more than likely that you can do it with
 	FreeBSD too!  FreeBSD also benefits significantly from
 	literally thousands of high quality applications developed by
 	research centers and universities around the world, often
 	available at little to no cost. Commercial applications are also
 	available and appearing in greater numbers every day.</para>
 
       <para>Because the source code for FreeBSD itself is generally
         available, the system can also be customized to an almost unheard
 	of degree for special applications or projects, and in ways not
 	generally possible with operating systems from most major
 	commercial vendors.  Here is just a sampling of some of the
 	applications in which people are currently using FreeBSD:</para>
     
       <itemizedlist>
 	<listitem>
 	  <para><emphasis>Internet Services:</emphasis> The robust TCP/IP
 	    networking built into FreeBSD makes it an ideal platform for a
 	    variety of Internet services such as:</para>
 
 	  <itemizedlist>
 	    <indexterm><primary>FTP servers</primary></indexterm>
 	    <listitem>
 	      <para>FTP servers</para>
 	    </listitem>
 	  
 	    <indexterm><primary>web servers</primary></indexterm>
 	    <listitem>
 	      <para>World Wide Web servers (standard or secure
 	        [SSL])</para>
 	    </listitem>
 
 	    <indexterm><primary>firewall</primary></indexterm>
 	    <indexterm><primary>IP masquerading</primary></indexterm>
 	    <listitem>
 	      <para>Firewalls and NAT (<quote>IP masquerading</quote>)
 	        gateways</para>
 	    </listitem>
 	  
 	    <indexterm><primary>electronic mail</primary></indexterm>
 	    <listitem>
 	      <para>Electronic Mail servers</para>
 	    </listitem>
 	  
 	    <indexterm><primary>USENET</primary></indexterm>
 	    <listitem>
 	      <para>USENET News or Bulletin Board Systems</para>
 	    </listitem>
 	  
 	    <listitem>
 	      <para>And more...</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>With FreeBSD, you can easily start out small with an
 	    inexpensive 386 class PC and upgrade all the way up to a
 	    quad-processor Xeon with RAID storage as your enterprise
 	    grows.</para>
 	</listitem>
       
 	<listitem>
 	  <para><emphasis>Education:</emphasis>  Are you a student of
 	    computer science or a related engineering field?  There is no
 	    better way of learning about operating systems, computer
 	    architecture and networking than the hands on, under the hood
 	    experience that FreeBSD can provide.  A number of freely
 	    available CAD, mathematical and graphic design packages also
 	    make it highly useful to those whose primary interest in a
 	    computer is to get <emphasis>other</emphasis> work
 	    done!</para>
 	</listitem>
       
 	<listitem>
 	  <para><emphasis>Research:</emphasis>  With source code for the
 	    entire system available, FreeBSD is an excellent platform for
 	    research in operating systems as well as other branches of
 	    computer science.  FreeBSD's freely available nature also makes
 	    it possible for remote groups to collaborate on ideas or
 	    shared development without having to worry about special
 	    licensing agreements or limitations on what may be discussed
 	    in open forums.</para>
 	</listitem>
       
 	<indexterm><primary>router</primary></indexterm>
 	<indexterm><primary>DNS Server</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Networking:</emphasis>  Need a new router?  A
 	    name server (DNS)? A firewall to keep people out of your
 	    internal network?  FreeBSD can easily turn that unused 386 or
 	    486 PC sitting in the corner into an advanced router with
 	    sophisticated packet-filtering capabilities.</para>
 	</listitem>
       
 	<indexterm>
 	  <primary>X Window System</primary>
 	  <secondary>XFree86</secondary>
 	</indexterm>
 	<indexterm>
 	  <primary>X Window System</primary>
 	  <secondary>Accelerated-X</secondary>
 	</indexterm>
 	<listitem>
 	  <para><emphasis>X Window workstation:</emphasis> FreeBSD is a
 	    fine choice for an inexpensive X terminal solution, either
 	    using the freely available XFree86 server or one of the
 	    excellent commercial servers provided by X Inside.  Unlike an
 	    X terminal, FreeBSD allows many applications to be run
 	    locally if desired, thus relieving the burden on a central
 	    server.  FreeBSD can even boot <quote>diskless</quote>, making
 	    individual workstations even cheaper and easier to
 	    administer.</para>
 	</listitem>
       
 	<indexterm><primary>GNU Compiler Collection</primary></indexterm>
 	<listitem>
 	  <para><emphasis>Software Development:</emphasis>  The basic
 	    FreeBSD system comes with a full complement of development
 	    tools including the renowned GNU C/C++ compiler and
 	    debugger.</para>
 	</listitem>
       </itemizedlist>
     
       <para>FreeBSD is available in both source and binary form on CDROM
         and via anonymous FTP.  Please see <xref linkend="mirrors">
         for more information about obtaining FreeBSD.</para>
     </sect2>
 
     <sect2>
       <title>Who uses FreeBSD?</title>
 
       <indexterm>
 	<primary>Users</primary>
 	<secondary>Large sites running FreeBSD</secondary>
       </indexterm>
 
       <para>FreeBSD is used to power some of the biggest sites on the
         Internet, including:</para>
 
       <itemizedlist>
         <indexterm><primary>Yahoo!</primary></indexterm>
         <listitem>
 	  <para><ulink url="http://www.yahoo.com/">Yahoo!</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Apache</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.apache.org/">Apache</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Blue Mountain Arts</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.bluemountain.com/">Blue Mountain
 	    Arts</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Pair Networks</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.pair.com/">Pair
 	    Networks</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Sony Japan</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.sony.co.jp/">Sony
 	    Japan</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Netcraft</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.netcraft.com/">Netcraft</ulink>
 	    </para>
 	</listitem>
 
 	<indexterm><primary>Weathernews</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.wni.com/">Weathernews</ulink>
 	</para></listitem>
 
 	<indexterm><primary>Supervalu</primary></indexterm>
 	<listitem>
 	  <para><ulink
 	    url="http://www.supervalu.com/">Supervalu</ulink></para>
 	</listitem>
 
 	<indexterm><primary>TELEHOUSE America</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.telehouse.com/">TELEHOUSE
 	    America</ulink></para>
 	</listitem>
 
 	<indexterm><primary>Sophos Anti-Virus</primary></indexterm>
 	<listitem>
 	  <para><ulink url="http://www.sophos.com/">Sophos
 	    Anti-Virus</ulink></para>
 	</listitem>
 
 	<indexterm><primary>JMA Wired</primary></indexterm>
 	<listitem>
 	  <para><ulink
 	    url="http://www.jmawired.com/">JMA Wired</ulink></para>
 	</listitem>
       </itemizedlist>
 
       <para>and many more.</para>
     </sect2>
 
   </sect1>
   
   <sect1 id="history">
     <title>About the FreeBSD Project</title>
 
     <para>The following section provides some background information on
       the project, including a brief history, project goals, and the
       development model of the project.</para>
 
     <sect2 id="intro-history">
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Jordan</firstname>
 	    <surname>Hubbard</surname>
 	    <contrib>Contributed by </contrib>
 	  </author>
 	</authorgroup>
       </sect2info>
 
       <title>A Brief History of FreeBSD</title>
 
       <indexterm><primary>386BSD Patchkit</primary></indexterm>
       <indexterm><primary>Hubbard, Jordan</primary></indexterm>
       <indexterm><primary>Williams, Nate</primary></indexterm>
       <indexterm><primary>Grimes, Rod</primary></indexterm>
       <indexterm>
         <primary>FreeBSD Project</primary>
         <secondary>History</secondary>
       </indexterm>
       <para>The FreeBSD project had its genesis in the early part of 1993,
 	partially as an outgrowth of the <quote>Unofficial 386BSD
         Patchkit</quote> by the patchkit's last 3 coordinators: Nate
 	Williams, Rod Grimes and myself.</para>
     
       <indexterm><primary>386BSD</primary></indexterm>
       <para>Our original goal was to produce an intermediate snapshot of
 	386BSD in order to fix a number of problems with it that the
 	patchkit mechanism just was not capable of solving.  Some of you
 	may remember the early working title for the project being
 	<quote>386BSD 0.5</quote> or <quote>386BSD Interim</quote> in
 	reference to that fact.</para>
     
       <indexterm><primary>Jolitz, Bill</primary></indexterm>
       <para>386BSD was Bill Jolitz's operating system, which had been up
 	to that point suffering rather severely from almost a year's worth
 	of neglect.  As the patchkit swelled ever more uncomfortably with
 	each passing day, we were in unanimous agreement that something
 	had to be done and decided to assist Bill by providing
 	this interim <quote>cleanup</quote> snapshot.  Those plans came to
 	a rude halt when Bill Jolitz suddenly decided to withdraw his
 	sanction from the project without any clear indication of what
 	would be done instead.</para>
 
       <indexterm><primary>Greenman, David</primary></indexterm>
       <indexterm><primary>Walnut Creek CDROM</primary></indexterm>
       <para>It did not take us long to decide that the goal remained
 	worthwhile, even without Bill's support, and so we adopted the
 	name <quote>FreeBSD</quote>, coined by David Greenman.  Our initial
 	objectives were set after consulting with the system's current
 	users and, once it became clear that the project was on the road
 	to perhaps even becoming a reality, I contacted Walnut Creek CDROM
 	with an eye toward improving FreeBSD's distribution channels for
 	those many unfortunates without easy access to the Internet.
 	Walnut Creek CDROM not only supported the idea of distributing
 	FreeBSD on CD but also went so far as to provide the project with a
 	machine to work on and a fast Internet connection.  Without Walnut
 	Creek CDROM's almost unprecedented degree of faith in what was, at
 	the time, a completely unknown project, it is quite unlikely that
         FreeBSD would have gotten as far, as fast, as it has today.</para>
 
       <indexterm><primary>4.3BSD-Lite</primary></indexterm>
       <indexterm><primary>Net/2</primary></indexterm>
       <indexterm><primary>U.C. Berkeley</primary></indexterm>
       <indexterm><primary>386BSD</primary></indexterm>
       <indexterm><primary>Free Software Foundation</primary></indexterm>
       <para>The first CDROM (and general net-wide) distribution was
 	FreeBSD&nbsp;1.0, released in December of 1993.  This was based on the
 	4.3BSD-Lite (<quote>Net/2</quote>) tape from U.C. Berkeley, with
 	many components also provided by 386BSD and the Free Software
 	Foundation.  It was a fairly reasonable success for a first
 	offering, and we followed it with the highly successful FreeBSD
 	1.1 release in May of 1994.</para>
 
       <indexterm><primary>Novell</primary></indexterm>
       <indexterm><primary>U.C. Berkeley</primary></indexterm>
       <indexterm><primary>Net/2</primary></indexterm>
       <indexterm><primary>AT&amp;amp;T</primary></indexterm>
       <para>Around this time, some rather unexpected storm clouds formed
 	on the horizon as Novell and U.C. Berkeley settled their
 	long-running lawsuit over the legal status of the Berkeley Net/2
 	tape.  A condition of that settlement was U.C. Berkeley's
 	concession that large parts of Net/2 were <quote>encumbered</quote>
 	code and the property of Novell, who had in turn acquired it from
 	AT&amp;T some time previously.  What Berkeley got in return was
 	Novell's <quote>blessing</quote> that the 4.4BSD-Lite release, when
 	it was finally released, would be declared unencumbered and all
 	existing Net/2 users would be strongly encouraged to switch.  This
 	included FreeBSD, and the project was given until the end of July
 	1994 to stop shipping its own Net/2 based product.  Under the
 	terms of that agreement, the project was allowed one last release
 	before the deadline, that release being FreeBSD&nbsp;1.1.5.1.</para>
 
       <para>FreeBSD then set about the arduous task of literally
 	re-inventing itself from a completely new and rather incomplete
 	set of 4.4BSD-Lite bits.  The <quote>Lite</quote> releases were
 	light in part because Berkeley's CSRG had removed large chunks of
 	code required for actually constructing a bootable running system
 	(due to various legal requirements) and the fact that the Intel
 	port of 4.4 was highly incomplete.  It took the project until
 	November of 1994 to make this transition, at which point it
 	released FreeBSD&nbsp;2.0 to the net and on CDROM (in late December).
 	Despite being still more than a little rough around the edges,
 	the release was a significant success and was followed by the
 	more robust and easier to install FreeBSD&nbsp;2.0.5 release in June of
 	1995.</para>
 
       <para>We released FreeBSD&nbsp;2.1.5 in August of 1996, and it appeared
 	to be popular enough among the ISP and commercial communities that
 	another release along the 2.1-STABLE branch was merited.  This was
 	FreeBSD&nbsp;2.1.7.1, released in February 1997 and capping the end of
 	mainstream development on 2.1-STABLE.  Now in maintenance mode,
 	only security enhancements and other critical bug fixes will be
 	done on this branch (RELENG_2_1_0).</para>
 
       <para>FreeBSD&nbsp;2.2 was branched from the development mainline
 	(<quote>-CURRENT</quote>) in November 1996 as the RELENG_2_2
 	branch, and the first full release (2.2.1) was released in April
 	1997.  Further releases along the 2.2 branch were done in the
 	summer and fall of '97, the last of which (2.2.8) appeared in
 	November 1998. The first official 3.0 release appeared in
 	October 1998 and spelled the beginning of the end for the 2.2
 	branch.</para>
 
       <para>The tree branched again on Jan 20, 1999, leading to the
 	4.0-CURRENT and 3.X-STABLE branches.  From 3.X-STABLE, 3.1 was
 	released on February 15, 1999, 3.2 on May 15, 1999, 3.3 on
 	September 16, 1999, 3.4 on December 20, 1999, and 3.5 on
 	June 24, 2000, which was followed a few days later by a minor
 	point release update to 3.5.1, to incorporate some last-minute
 	security fixes to Kerberos. This will be the final release in the
 	3.X branch.</para>
 
       <para>There was another branch on March 13, 2000, which saw the
 	emergence of the 4.X-STABLE branch, now considered to be the
 	"current -stable branch".  There have been several releases
 	from it so far: 4.0-RELEASE came out in March 2000, 4.1 was
 	released in July 2000, 4.2 in November 2000, 4.3 in April
 	2001, and 4.4 in September 2001.  There will be more releases
 	along the 4.X-stable (RELENG_4) branch well into 2002.</para>
 
       <para>Long-term development projects continue to take place in the
 	5.0-CURRENT (trunk) branch, and SNAPshot releases of 5.0 on
 	CDROM (and, of course, on the net) are continually made available
 	from <ulink url="ftp://current.FreeBSD.org/pub/FreeBSD/snapshots/">
 	the snapshot server</ulink> as work progresses.</para>
     </sect2>
       
     <sect2 id="goals">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Jordan</firstname>
 	    <surname>Hubbard</surname>
    	    <contrib>Contributed by </contrib>
 	  </author>
         </authorgroup>
       </sect2info>
 
       <title>FreeBSD Project Goals</title>
     
       <indexterm>
         <primary>FreeBSD Project</primary>
         <secondary>Goals</secondary>
       </indexterm>
       <para>The goals of the FreeBSD Project are to provide software that
 	may be used for any purpose and without strings attached.  Many of
 	us have a significant investment in the code (and project) and
 	would certainly not mind a little financial compensation now and
 	then, but we are definitely not prepared to insist on it.  We
 	believe that our first and foremost <quote>mission</quote> is to
 	provide code to any and all comers, and for whatever purpose, so
 	that the code gets the widest possible use and provides the widest
 	possible benefit.  This is, I believe, one of the most fundamental
 	goals of Free Software and one that we enthusiastically
 	support.</para>
 
       <indexterm>
         <primary>GNU General Public License (GPL)</primary>
       </indexterm>
       <indexterm>
         <primary>GNU Lesser General Public License (LGPL)</primary>
       </indexterm>
       <indexterm><primary>BSD Copyright</primary></indexterm>
       <para>That code in our source tree which falls under the GNU
         General Public License (GPL) or Library General Public License
         (LGPL) comes with slightly more strings attached, though at
         least on the side of enforced access rather than the usual
         opposite.  Due to the additional complexities that can evolve
         in the commercial use of GPL software we do, however, prefer
         software submitted under the more relaxed BSD copyright when
         it is a reasonable option to do so.</para>
     </sect2>
   
     <sect2 id="development">
       <sect2info>
         <authorgroup>
           <author>
             <firstname>Satoshi</firstname>
 	    <surname>Asami</surname>
    	    <contrib>Contributed by </contrib>
 	  </author>
         </authorgroup>
       </sect2info>
 
       <title>The FreeBSD Development Model</title>
     
       <indexterm>
         <primary>FreeBSD Project</primary>
         <secondary>Development Model</secondary>
       </indexterm>
       <para>The development of FreeBSD is a very open and flexible
 	process, FreeBSD being literally built from the contributions
 	of hundreds of people around the world, as can be seen from
 	our <ulink
 	url="../../articles/contributors/article.html">list of
 	contributors</ulink>.  We are constantly on the lookout for
 	new developers and ideas, and those interested in becoming
 	more closely involved with the project need simply contact us
 	at the &a.hackers;.  The &a.announce; is also available to
 	those wishing to make other FreeBSD users aware of major areas
 	of work.</para>
 
       <para>Useful things to know about the FreeBSD project and its
 	development process, whether working independently or in close
 	cooperation:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term>The CVS repository<anchor
 	    id="development-cvs-repository"></term>
 
 	  <indexterm>
       <primary>CVS</primary>
       <secondary>repository</secondary>
     </indexterm>
 	  <indexterm>
 	    <primary>Concurrent Versions System</primary>
       <see>CVS</see>
 	  </indexterm>
 	  <listitem>
 	    <para>The central source tree for FreeBSD is maintained by
 	      <ulink url="http://www.cvshome.org/">CVS</ulink>
 	      (Concurrent Versions System), a freely available source code
 	      control tool that comes bundled with FreeBSD.  The primary
 	      <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVS
 	      repository</ulink> resides on a machine in Santa Clara CA, USA
 	      from where it is replicated to numerous mirror machines
 	      throughout the world.  The CVS tree, as well as the <link
 	      linkend="current">-CURRENT</link> and <link
 	      linkend="stable">-STABLE</link> trees which are checked out
 	      of it, can be easily replicated to your own machine as well.
 	      Please refer to the <link linkend="synching">Synchronizing
 	      your source tree</link> section for more information on
 	      doing this.</para>
 	  </listitem>
 	</varlistentry>
       
 	<varlistentry>
 	  <term>The committers list<anchor
 	    id="development-committers"></term>
 	      
 	  <indexterm><primary>committers</primary></indexterm>
 	  <listitem>
 	    <para>The <firstterm>committers</firstterm>
 	      are the people who have <emphasis>write</emphasis> access to
 	      the CVS tree, and are thus authorized to make modifications
 	      to the FreeBSD source (the term <quote>committer</quote>
 	      comes from the &man.cvs.1; <command>commit</command>
 	      command, which is used to bring new changes into the CVS
 	      repository).  The best way of making submissions for review
 	      by the committers list is to use the &man.send-pr.1;
 	      command, though if something appears to be jammed in the
 	      system then you may also reach them by sending mail to
 	      the &a.committers;.</para>
 	  </listitem>
 	</varlistentry>
       
 	<varlistentry>
 	  <term>The FreeBSD core team<anchor id="development-core"></term>
 
 	  <indexterm><primary>core team</primary></indexterm>
 	  <listitem>
 	    <para>The <firstterm>FreeBSD core team</firstterm>
 	      would be equivalent to the board of directors if the FreeBSD
 	      Project were a company.  The primary task of the core team
 	      is to make sure the project, as a whole, is in good shape
 	      and is heading in the right directions.  Inviting dedicated
 	      and responsible developers to join our group of committers
 	      is one of the functions of the core team, as is the
 	      recruitment of new core team members as others move on.
 	      The current core team was elected from a pool of committer
 	      candidates in June 2002.  Elections are held every 2 years.
 	      </para>
 
 	    <para>Some core team members also have specific areas of
 	      responsibility, meaning that they are committed to
 	      ensuring that some large portion of the system works as
 	      advertised.  For a complete list of FreeBSD developers
 	      and their areas of responsibility, please see the <ulink
 	      url="../../articles/contributors/article.html">Contributors
 	      List</ulink></para>
 
 	    <note>
 	      <para>Most members of the core team are volunteers when it
 	        comes to FreeBSD development and do not benefit from the
 		project financially, so <quote>commitment</quote> should
 		also not be misconstrued as meaning <quote>guaranteed
 		support.</quote>  The <quote>board of directors</quote>
 		analogy above is not actually very accurate, and it may be
 		more suitable to say that these are the people who gave up
 		their lives in favor of FreeBSD against their better
 		judgment!</para>
 	    </note>
 	  </listitem>
 	</varlistentry>
       
 	<varlistentry>
 	  <term>Outside contributors</term>
 
 	  <indexterm><primary>contributors</primary></indexterm>
 	  <listitem>
 	    <para>Last, but definitely not least, the largest group of
 	      developers are the users themselves who provide feedback and
 	      bug fixes to us on an almost constant basis.  The primary
 	      way of keeping in touch with FreeBSD's more non-centralized
 	      development is to subscribe to the &a.hackers; (see <link
 	      linkend="eresources-mail">mailing list info</link>) where
 	      such things are discussed.</para>
 	  
 	    <para><citetitle><ulink
 	      url="../../articles/contributors/article.html">The
 	      FreeBSD Contributors List</ulink></citetitle> is a long
 	      and growing one, so why not join it by contributing
 	      something back to FreeBSD today?</para>
 
 	    <para>Providing code is not the only way of contributing to
 	      the project; for a more complete list of things that need
 	      doing, please refer to the <ulink
 	      url="../../../../index.html">FreeBSD Project web
 	      site</ulink>.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     
       <para>In summary, our development model is organized as a loose set
         of concentric circles.  The centralized model is designed for the
         convenience of the <emphasis>users</emphasis> of FreeBSD, who are
         thereby provided with an easy way of tracking one central code
 	base, not to keep potential contributors out! Our desire is to
 	present a stable operating system with a large set of coherent
 	<link linkend="ports">application programs</link> that the users
 	can easily install and use, and this model works very well in
 	accomplishing that.</para>
     
       <para>All we ask of those who would join us as FreeBSD developers is
         some of the same dedication its current people have to its
 	continued success!</para>
     </sect2>
 
     <sect2 id="relnotes">
       <title>The Current FreeBSD Release</title>
 
       <indexterm><primary>NetBSD</primary></indexterm>
       <indexterm><primary>OpenBSD</primary></indexterm>
       <indexterm><primary>386BSD</primary></indexterm>
       <indexterm><primary>Free Software Foundation</primary></indexterm>
       <indexterm><primary>U.C. Berkeley</primary></indexterm>
       <indexterm>
         <primary>Computer Systems Research Group (CSRG)</primary>
       </indexterm>
       <para>FreeBSD is a freely available, full source 4.4BSD-Lite based
         release for Intel i386, i486, Pentium, Pentium Pro, Celeron,
         Pentium&nbsp;II, Pentium&nbsp;III, Pentium&nbsp;IV (or compatible),
 	Xeon, DEC Alpha and SPARC64 based computer
         systems.  It is based primarily on software from U.C. Berkeley's
         CSRG group, with some enhancements from NetBSD, OpenBSD, 386BSD, and
         the Free Software Foundation.</para>
 
       <para>Since our release of FreeBSD&nbsp;2.0 in late 94, the performance,
         feature set, and stability of FreeBSD has improved dramatically.
 	<!-- XXX is the rest of this paragraph still true ? -->
         The largest change is a revamped virtual memory system with a merged
         VM/file buffer cache that not only increases performance, but also
         reduces FreeBSD's memory footprint, making a 5&nbsp;MB configuration a
         more acceptable minimum.  Other enhancements include full NIS client
         and server support, transaction TCP support, dial-on-demand PPP,
         integrated DHCP support, an improved SCSI subsystem, ISDN support,
         support for ATM, FDDI, Fast and Gigabit Ethernet (1000&nbsp;Mbit)
         adapters, improved support for the latest Adaptec controllers, and
         many hundreds of bug fixes.</para>
 
       <para>We have also taken the comments and suggestions of many of our
         users to heart and have attempted to provide what we hope is a more
         sane and easily understood installation process.  Your feedback on
         this (constantly evolving) process is especially welcome!</para>
 
       <para>In addition to the base distributions, FreeBSD offers a
         ported software collection with thousands of commonly
         sought-after programs.  At the time of this printing, there
         were over &os.numports; ports!  The list of ports ranges from
         http (WWW) servers, to games, languages, editors, and almost
         everything in between.  The entire ports collection requires
         approximately &ports.size; of storage, all ports being expressed as
         <quote>deltas</quote> to their original sources.  This makes
         it much easier for us to update ports, and greatly reduces the
         disk space demands made by the older 1.0 ports collection.  To
         compile a port, you simply change to the directory of the
         program you wish to install, type <command>make
         install</command>, and let the system do the rest.  The full
         original distribution for each port you build is retrieved
         dynamically off the CDROM or a local FTP site, so you need
         only enough disk space to build the ports you want.  Almost
         every port is also provided as a pre-compiled
         <quote>package</quote>, which can be installed with a simple
         command (<command>pkg_add</command>) by those who do not wish
         to compile their own ports from source.</para>
 
       <para>A number of additional documents which you may find very helpful
         in the process of installing and using FreeBSD may now also be found
         in the <filename>/usr/share/doc</filename> directory on any machine
         running FreeBSD&nbsp;2.1 or later.  You may view the locally installed
         manuals with any HTML capable browser using the following
         URLs:</para>
 
       <variablelist>
         <varlistentry>
 	  <term>The FreeBSD Handbook</term>
 
 	  <listitem>
 	    <para><ulink
 	      url="file://localhost/usr/share/doc/handbook/index.html">/usr/share/doc/handbook/index.html</ulink></para>
 	  </listitem>
         </varlistentry>
       
         <varlistentry>
 	  <term>The FreeBSD FAQ</term>
 
 	  <listitem>
 	    <para><ulink
 	      url="file://localhost/usr/share/doc/faq/index.html">/usr/share/doc/faq/index.html</ulink></para>
 	  </listitem>
         </varlistentry>
       </variablelist>
     
       <para>You can also view the master (and most frequently updated)
         copies at <ulink
 	url="../../../../index.html">http://www.FreeBSD.org/</ulink>.</para>
     </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
index fabbf37962..e979579503 100644
--- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
@@ -1,1484 +1,1484 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="kernelconfig">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Updated and restructured by </contrib>
 	<!-- Mar 2000 -->
       </author>
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Jake</firstname>
 	<surname>Hamby</surname>
 	<contrib>Originally contributed by </contrib>
 	<!-- 6 Oct 1995 -->
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Configuring the FreeBSD Kernel</title>
 
-  <sect1>
+  <sect1 id="kernelconfig-synopsis">
     <title>Synopsis</title>
 
     <indexterm>
       <primary>kernel</primary>
       <secondary>building a custom kernel</secondary>
     </indexterm>
 
     <para>The kernel is the core of the FreeBSD operating system.  It is
       responsible for managing memory, enforcing security controls,
       networking, disk access, and much more.  While more and more of FreeBSD
       becomes dynamically configurable it is still occasionally necessary to
       reconfigure and recompile your kernel.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Why you might need to build a custom kernel.</para>
       </listitem>
 
       <listitem>
 	<para>How to write a kernel configuration file, or alter an existing
 	  configuration file.</para>
       </listitem>
 
       <listitem>
 	<para>How to use the kernel configuration file to create and build a
 	  new kernel.</para>
       </listitem>
 
       <listitem>
 	<para>How to install the new kernel.</para>
       </listitem>
 
       <listitem>
 	<para>How to create any entries in <filename>/dev</filename> that may
 	  be required.</para>
       </listitem>
 
       <listitem>
 	<para>How to troubleshoot if things go wrong.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
-  <sect1>
+  <sect1 id="kernelconfig-custom-kernel">
     <title>Why Build a Custom Kernel?</title>
 
     <para>Traditionally, FreeBSD has had what is called a
       <quote>monolithic</quote> kernel.  This means that the kernel was one
       large program, supported a fixed list of devices, and if you wanted to
       change the kernel's behavior then you had to compile a new kernel, and
       then reboot your computer with the new kernel.</para>
 
     <para>Today, FreeBSD is rapidly moving to a model where much of the
       kernel's functionality is contained in modules which can be dynamically
       loaded and unloaded from the kernel as necessary.  This allows the
       kernel to adapt to new hardware suddenly becoming available (such as
       PCMCIA cards in a laptop), or for new functionality to be brought into
       the kernel that was not necessary when the kernel was originally
       compiled.  Colloquially these are called KLDs.</para>
 
     <para>Despite this, it is still necessary to carry out some static kernel
       configuration.  In some cases this is because the functionality is so
       tied to the kernel that it can not be made dynamically loadable.  In
       others it may simply be because no one has yet taken the time to write a
       dynamic loadable kernel module for that functionality yet.</para>
 
     <para>Building a custom kernel is one of the most important rites of
       passage nearly every Unix user must endure.  This process, while
       time consuming, will provide many benefits to your FreeBSD system.
       Unlike the <filename>GENERIC</filename> kernel, which must support a
       wide range of hardware, a custom kernel only contains support for
       <emphasis>your</emphasis> PC's hardware.  This has a number of
       benefits, such as:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Faster boot time.  Since the kernel will only probe the
 	hardware you have on your system, the time it takes your system to
 	boot will decrease dramatically.</para>
       </listitem>
 
       <listitem>
 	<para>Less memory usage.  A custom kernel often uses less memory
 	  than the <filename>GENERIC</filename> kernel, which is important
 	  because the kernel must always be present in real
 	  memory.  For this reason, a custom kernel is especially useful
 	  on a system with a small amount of RAM.</para>
       </listitem>
 
       <listitem>
 	<para>Additional hardware support.  A custom kernel allows you to
 	  add in support for devices such as sound cards, which are not
 	  present in the <filename>GENERIC</filename> kernel.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="kernelconfig-building">
     <title>Building and Installing a Custom Kernel</title>
     <indexterm>
       <primary>kernel</primary>
       <secondary>building / installing</secondary>
     </indexterm>
 
     <para>First, let us take a quick tour of the kernel build directory.
       All directories mentioned will be relative to the main
       <filename>/usr/src/sys</filename> directory, which is also
       accessible through <filename>/sys</filename>.  There are a number of
       subdirectories here representing different parts of the kernel, but
       the most important, for our purposes, are
       <filename><replaceable>arch</replaceable>/conf</filename>, where you
       will edit your custom kernel configuration, and
       <filename>compile</filename>, which is the staging area where your
       kernel will be built.  <replaceable>arch</replaceable> represents
       either <filename>i386</filename>, <filename>alpha</filename>, or
       <filename>pc98</filename> (an alternative development branch of PC
       hardware, popular in Japan).  Everything inside a particular
       architecture's directory deals with that architecture only; the rest
       of the code is common to all platforms to which FreeBSD could
       potentially be ported.  Notice the logical organization of the
       directory structure, with each supported device, filesystem, and
       option in its own subdirectory.</para>
 
     <note>
       <para>If there is <emphasis>not</emphasis> a
 	<filename>/usr/src/sys</filename> directory on your system, then
 	the kernel source has not been installed.  The easiest way to
 	do this is by running <command>/stand/sysinstall</command> as
 	<username>root</username>, choosing <guimenuitem>Configure</guimenuitem>,
 	then <guimenuitem>Distributions</guimenuitem>, then
 	<guimenuitem>src</guimenuitem>, then <guimenuitem>sys</guimenuitem>.  If you
 	have an aversion to <application>sysinstall</application> and
 	you have access to an <quote>official</quote> FreeBSD CDROM, then
 	you can also install the source from the command line:</para>
 
       <screen>&prompt.root; <userinput>mount /cdrom</userinput>
 &prompt.root; <userinput>mkdir -p /usr/src/sys</userinput>
 &prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput>
 &prompt.root; <userinput>cat /cdrom/src/ssys.[a-d]* | tar -xzvf -</userinput></screen>
     </note>
 
     <para>Next, move to the
       <filename><replaceable>arch</replaceable>/conf</filename> directory
       and copy the <filename>GENERIC</filename> configuration file to the
       name you want to give your kernel.  For example:</para>
 
     <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
 &prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
 
     <para>Traditionally, this name is in all capital letters and, if you
       are maintaining multiple FreeBSD machines with different hardware,
       it is a good idea to name it after your machine's hostname.  We will
       call it <filename>MYKERNEL</filename> for the purpose of this
       example.</para>
 
     <tip>
       <para>Storing your kernel config file directly under
 	<filename>/usr/src</filename> can be a bad idea.  If you are
 	experiencing problems it can be tempting to just delete
 	<filename>/usr/src</filename> and start again.  Five seconds after
 	you do that you realize that you have deleted your custom kernel
 	config file.</para>
 
       <para>You might want to keep your kernel config file elsewhere, and then
 	create a symbolic link to the file in the <filename>i386</filename>
 	directory.</para>
 
       <para>For example:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
 &prompt.root; <userinput>mkdir /root/kernels</userinput>
 &prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>	
 &prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
     </tip>
 
     <note>
       <para>You must execute these and all of the following commands under
 	the <username>root</username> account or you will get
         <errortype>permission denied</errortype> errors.</para>
     </note>
 
     <para>Now, edit <filename>MYKERNEL</filename> with your favorite text
       editor.  If you are just starting out, the only editor available
       will probably be <application>vi</application>, which is too complex to
       explain here, but is covered well in many books in the <link
       linkend="bibliography">bibliography</link>.  However, FreeBSD does
       offer an easier editor called <application>ee</application> which, if
       you are a beginner, should be your editor of choice.  Feel free to
       change the comment lines at the top to reflect your configuration or
       the changes you have made to differentiate it from
       <filename>GENERIC</filename>.</para>
     <indexterm><primary>SunOS</primary></indexterm>
 
     <para>If you have built a kernel under SunOS or some other BSD
       operating system, much of this file will be very familiar to you.
       If you are coming from some other operating system such as DOS, on
       the other hand, the <filename>GENERIC</filename> configuration file
       might seem overwhelming to you, so follow the descriptions in the
       <link linkend="kernelconfig-config">Configuration File</link>
       section slowly and carefully.</para>
 
     <note>
       <para>Be sure to always check the file
         <filename>/usr/src/UPDATING</filename>, before you perform any update
         steps, in the case you <link
         linkend="cutting-edge">sync your source tree</link> with the
         latest sources of the FreeBSD project.
         In this file all important issues with updating FreeBSD
         are written down.  <filename>/usr/src/UPDATING</filename> always fits
         to your version of the FreeBSD source, and is therefore more accurate
         for those information than the handbook.</para>
     </note>
 
     <para>You must now compile the source code for the kernel.  There are two
       procedures you can use to do this, and the one you will use depends on
       why you are rebuilding the kernel, and the version of FreeBSD you are
       running.</para>
 
     <itemizedlist>
       <listitem>
 	<para>If you have installed <emphasis>only</emphasis> the kernel
 	  source code, use procedure 1.</para>
       </listitem>
 
       <listitem>
 	<para>If you are running a FreeBSD version prior to 4.0, and you are
 	  <emphasis>not</emphasis> upgrading to FreeBSD&nbsp;4.0 or higher using
 	  the <maketarget>make world</maketarget> procedure, use procedure 1.
         </para>
       </listitem>
 
       <listitem>
 	<para>If you are building a new kernel without updating the source
 	  code (perhaps just to add a new option, such as
 	  <literal>IPFIREWALL</literal>) you can use either procedure.</para>
       </listitem>
 
       <listitem>
 	<para>If you are rebuilding the kernel as part of a
           <maketarget>make world</maketarget> process, use procedure 2.
         </para>
       </listitem>
     </itemizedlist>
     
     <procedure>
       <title>Procedure 1.  Building a kernel the <quote>traditional</quote> way</title>
       
       <step>
 	<para>Run &man.config.8; to generate the kernel source code.</para>
 	
 	<screen>&prompt.root; <userinput>/usr/sbin/config <replaceable>MYKERNEL</replaceable></userinput></screen>
       </step>
 
       <step>
 	<para>Change into the build directory.</para>
 
 	<screen>&prompt.root; <userinput>cd ../../compile/<replaceable>MYKERNEL</replaceable></userinput></screen>
       </step>
 
       <step>
 	<para>Compile the kernel.</para>
 	
 	<screen>&prompt.root; <userinput>make depend</userinput>
 &prompt.root; <userinput>make</userinput></screen>
       </step>
 
       <step>
 	<para>Install the new kernel.</para>
 	
 	<screen>&prompt.root; <userinput>make install</userinput></screen>
       </step>
     </procedure>
 
     <procedure>
       <title>Procedure 2.  Building a kernel the <quote>new</quote>
 	way</title>
       
       <step>
 	<para>Change to the <filename>/usr/src</filename> directory.</para>
 	
 	<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
       </step>
 
       <step>
 	<para>Compile the kernel.</para>
 	
 	<screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
       </step>
 
       <step>
 	<para>Install the new kernel.</para>
 
 	<screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
       </step>
     </procedure>
     
     <note>
       <para>In FreeBSD&nbsp;4.2 and older you must replace
         <literal>KERNCONF=</literal> with <literal>KERNEL=</literal>.
         4.2-STABLE that was fetched after Feb 2nd, 2001 does
         recognize <literal>KERNCONF=</literal>.</para>
     </note>
 
     <indexterm>
       <primary><command>cvsup</command></primary>
     </indexterm>
     <indexterm><primary>anonymous CVS</primary></indexterm>
     <indexterm><primary>CTM</primary></indexterm>
     <indexterm>
       <primary>CVS</primary>
       <secondary>anonymous</secondary>
     </indexterm>
 
     <para>If you have <emphasis>not</emphasis> upgraded your source
       tree in any way (you have not run <application>CVSup</application>, 
       <application>CTM</application>, or used 
       <application>anoncvs</application>), then you should use the 
       <command>config</command>, <maketarget>make depend</maketarget>,
       <command>make</command>, <maketarget>make install</maketarget> sequence.
     </para>
 
     <indexterm>
       <primary><filename>kernel.old</filename></primary>
     </indexterm> 
 
     <para>The new kernel will be copied to the root directory as
       <filename>/kernel</filename> and the old kernel will be moved to
       <filename>/kernel.old</filename>.  Now, shutdown the system and
       reboot to use your new kernel.  In case something goes wrong, there are
       some <link linkend="kernelconfig-trouble">troubleshooting</link>
       instructions at the end of this chapter.  Be sure to read the
       section which explains how to recover in case your new kernel <link
       linkend="kernelconfig-noboot">does not boot</link>.</para>
 
     <note>
       <para>As of FreeBSD 5.0, kernels are installed along with their
 	modules in <filename>/boot/kernel</filename>, and old kernels
 	will be backed up as <filename>/boot/kernel.old</filename>.
 	Other files relating to the boot process, such as the boot
 	&man.loader.8; and configuration are also stored in
 	<filename>/boot</filename>.  Third party or custom modules
         may be placed in <filename>/boot/modules</filename>, although
         users should be aware that keeping modules in sync with the
         compiled kernel is very important.  Modules not intended
         to run with the compiled kernel may result in instability
         or incorrectness.</para>
     </note>
 
     <note>
       <para>If you have added any new devices (such as sound cards) and you
 	are running FreeBSD&nbsp;4.X or previous versions, you
 	may have to add some device
 	nodes to your <filename>/dev</filename> directory before
 	you can use them. For more information, take a look at <link linkend="kernelconfig-nodes">Making
 	Device Nodes</link> section later on in this chapter.</para>
     </note>
   </sect1>
 
   <sect1 id="kernelconfig-config">
     <title>The Configuration File</title>
     <indexterm>
       <primary>kernel</primary>
       <secondary>LINT</secondary>
     </indexterm>
     <indexterm><primary>LINT</primary></indexterm>
     <indexterm>
       <primary>kernel</primary>
       <secondary>config file</secondary>
     </indexterm>
 
     <para>The general format of a configuration file is quite simple.
       Each line contains a keyword and one or more arguments.  For
       simplicity, most lines only contain one argument.  Anything
       following a <literal>#</literal> is considered a comment and
       ignored.  The following sections describe each keyword, generally in
       the order they are listed in <filename>GENERIC</filename>, although
       some related keywords have been grouped together in a single section
       (such as Networking) even though they are actually scattered
       throughout the <filename>GENERIC</filename> file.  <anchor
       id="kernelconfig-options"> An exhaustive list of options and more
       detailed explanations of the device lines is present in the
       <filename>LINT</filename> configuration file, located in the same
       directory as <filename>GENERIC</filename>.  If you are in doubt as
       to the purpose or necessity of a line, check first in
       <filename>LINT</filename>.</para>
 
     <important>
       <title>Quoting numbers</title>
 
       <para>In all versions of FreeBSD up to and including 3.X,
 	&man.config.8; required that any strings in the configuration file
 	that contained numbers used as text had to be enclosed in double
 	quotes.</para>
 
       <para>This requirement was removed in the 4.X branch, which this
 	book covers, so if you are on a pre-4.X system, see the
 	<filename>/usr/src/sys/i386/conf/LINT</filename> and
 	<filename>/usr/src/sys/i386/conf/GENERIC</filename>
 	files on your system for examples.</para>
     </important>
     <indexterm>
       <primary>kernel</primary>
       <secondary>example config file</secondary>
     </indexterm>
 
     <para>The following is an example <filename>GENERIC</filename> kernel
       configuration file with various additional comments where needed for
       clarity.  This example should match your copy in
       <filename>/usr/src/sys/i386/conf/GENERIC</filename> fairly
       closely.  For details of all the possible kernel options, see
       <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
 
     <programlisting>#
 # GENERIC -- Generic kernel configuration file for FreeBSD/i386
 #
 # For more information on this file, please read the handbook section on
 # Kernel Configuration Files:
 #
 #    http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig-config.html
 #
 # The handbook is also available locally in /usr/share/doc/handbook
 # if you've installed the doc distribution, otherwise always see the
 # FreeBSD World Wide Web server (http://www.FreeBSD.ORG/) for the
 # latest information.
 #
 # An exhaustive list of options and more detailed explanations of the
 # device lines is also present in the ./LINT configuration file. If you are
 # in doubt as to the purpose or necessity of a line, check first in LINT.
 #
 # &dollar;FreeBSD: src/sys/i386/conf/GENERIC,v 1.246 2000/03/09 16:32:55 jlemon Exp &dollar;</programlisting>
 
     <para>The following are the mandatory keywords required in
       <emphasis>every</emphasis> kernel you build:</para>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>machine</secondary>
     </indexterm>
 
     <programlisting>machine		i386</programlisting>
 
     <para>This is the machine architecture.  It must be either
       <literal>i386</literal>, <literal>alpha</literal>, or
       <literal>pc98</literal>.</para>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>cpu</secondary>
     </indexterm>
     <programlisting>cpu          I386_CPU
 cpu          I486_CPU
 cpu          I586_CPU
 cpu          I686_CPU</programlisting>
 
     <para>The above specifies the type of CPU you have in your system.
       You may have multiple instances of the CPU line (i.e., you are not
       sure whether you should use <literal>I586_CPU</literal> or
       <literal>I686_CPU</literal>), however, for a custom kernel, it is
       best to specify only the CPU you have.  If you are unsure of your
       CPU type, you can use the &man.dmesg.8; command to view your boot
       up messages.</para>
 
     <note><para>In FreeBSD 5.0, support for <literal>I386_CPU</literal>
       is disabled by default.</para></note>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>cpu type</secondary>
     </indexterm>
 
     <para>The Alpha architecture has different values for
       <literal>cpu</literal>.  They include:</para>
 
     <programlisting>cpu          EV4
 cpu          EV5</programlisting>
 
     <para>If you are using an Alpha machine, you should be using one of
       the above CPU types.</para>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>ident</secondary>
     </indexterm>
 
     <programlisting>ident          GENERIC</programlisting>
 
     <para>This is the identification of the kernel.  You should change
       this to whatever you named your kernel, as in our previous example,
       <literal>MYKERNEL</literal>.  The value you put in the
       <literal>ident</literal> string will print when you boot up the
       kernel, so it is useful to give the new kernel a different name if you
       want to keep it separate from your usual kernel (i.e., you want to
       build an experimental kernel).</para>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>maxusers</secondary>
     </indexterm>
 
     <programlisting>maxusers          <replaceable>n</replaceable></programlisting>
 
     <para>The <literal>maxusers</literal> option sets the size of a number
       of important system tables.  This number is supposed to be roughly
       equal to the number of simultaneous users you expect to have on your
       machine.</para>
 
     <para>Starting with FreeBSD&nbsp;4.5, the system will auto-tune this setting
       for you if you explicitly set it to <literal>0</literal><footnote>
 	<para>The auto-tuning algorithm sets <literal>maxuser</literal> equal
 	  to the amount of memory in the system, with a minimum of 32, and a
 	  maximum of 384.</para></footnote>.  If you are
       using an earlier version of FreeBSD, or you want to manage it
       yourself you will want to set
       <literal>maxusers</literal> to at least 4, especially if you are
       using the X Window System or compiling software.  The reason is that
       the most important table set by <literal>maxusers</literal> is the
       maximum number of processes,  which is set to <literal>20 + 16 *
       maxusers</literal>, so if you set <literal>maxusers</literal> to 1,
       then you can only have 36 simultaneous processes, including the 18
       or so that the system starts up at boot time, and the 15 or so you
       will probably create when you start the X Window System.  Even a
       simple task like reading a manual page will start up nine processes to
       filter, decompress, and view it.  Setting
       <literal>maxusers</literal> to 64 will allow you to have up to 1044
       simultaneous processes, which should be enough for nearly all uses.
       If, however, you see the dreaded <errortype>proc table
       full</errortype> error when trying to start another program, or are
       running a server with a large number of simultaneous users (like
       <hostid role="fqdn">ftp.FreeBSD.org</hostid>), you can always
       increase the number and rebuild.</para>
 
     <note>
       <para><literal>maxusers</literal> does <emphasis>not</emphasis>
 	limit the number of users which can log into your machine.  It
 	simply sets various table sizes to reasonable values considering
 	the maximum number of users you will likely have on your system
 	and how many processes each of them will be running.  One keyword
 	which <emphasis>does</emphasis> limit the number of simultaneous
 	<emphasis>remote logins</emphasis> is <link
 	linkend="kernelconfig-ptys"><literal>pseudo-device pty
 	16</literal></link>.</para>
     </note>
     
     <programlisting># Floating point support - do not disable.
 device          npx0     at nexus? port IO_NPX irq 13</programlisting>
     
     <para><literal>npx0</literal> is the interface to the floating point
       math unit in FreeBSD, which is either the hardware co-processor or
       the software math emulator.  This is <emphasis>not</emphasis>
       optional.</para>
 
     <programlisting># Pseudo devices - the number indicates how many units to allocate.
 pseudo-device   loop          # Network loopback</programlisting>
 
     <para>This is the generic loopback device for TCP/IP.  If you telnet
       or FTP to <hostid>localhost</hostid> (a.k.a., <hostid
       role="ipaddr">127.0.0.1</hostid>) it will come back at you through
       this pseudo-device.  This is <emphasis>mandatory</emphasis>.</para>
 
     <para>Everything that follows is more or less optional.  See the notes
       underneath or next to each option for more information.</para>
 
     <programlisting>#makeoptions     DEBUG=-g          #Build kernel with gdb(1) debug symbols
 options          MATH_EMULATE      #Support for x87 emulation</programlisting>
 
     <para>This line allows the kernel to simulate a math co-processor if
       your computer does not have one (386 or 486SX).  If you have a
       486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or
       higher (Pentium, Pentium&nbsp;II, etc.), you can comment this line
       out.</para>
 
     <note>
       <para>The normal math co-processor emulation routines that come with
 	FreeBSD are <emphasis>not</emphasis> very accurate.  If you do not
 	have a math co-processor, and you need the best accuracy, it is
 	recommended that you change this option to
 	<literal>GPL_MATH_EMULATE</literal> to use the GNU math support,
 	which is not included by default for licensing reasons.</para>
     </note>
 
     <note><para>In FreeBSD 5.0, math emulation is disabled by default,
       as older CPUs that do not have native floating point math support
       are far less common, and in many cases not supported by the native
       FreeBSD kernel without other additional options.</para></note>
 
     <programlisting>options          INET          #InterNETworking</programlisting>
 
     <para>Networking support.  Leave this in, even if you do not plan to
       be connected to a network.  Most programs require at least loopback
       networking (i.e., making network connections within your PC), so
       this is essentially mandatory.</para>
 
     <programlisting>options          INET6          #IPv6 communications protocols</programlisting>
 
     <para>This enables the IPv6 communication protocols.</para>
 
     <programlisting>options          FFS          #Berkeley Fast Filesystem
 options          FFS_ROOT     #FFS usable as root device [keep this!]</programlisting>
 
     <para>This is the basic hard drive filesystem.  Leave it in if you
       boot from the hard disk.</para>
 
     <note><para>In FreeBSD 5.0, <literal>FFS_ROOT</literal> is no longer
       required.</para></note>
 
     <programlisting>options          UFS_ACL      #Support for access control lists</programlisting>
 
     <para>This option, present only in FreeBSD&nbsp;5.0, enables kernel support
       for access control lists.  This relies on the use of extended
       attributes and UFS2, and the feature is described in detail
       in the <xref linkend="fs-acl">.  ACLs are enabled by default, and should not be
       disabled in the kernel if they have been used previously on a file
       system, as this will remove the access control lists changing the
       way files are protected in unpredictable ways.</para>
 
     <programlisting>options          UFS_DIRHASH  #Improve performance on big directories</programlisting>
 
     <para>This option includes some code to speed up disk operations on large
       directories, at the expense of using a some additional memory.  You
       would normally keep this for a large server, or interactive workstation,
       and remove it if you are using FreeBSD on a smaller system where memory
       is at a premium and disk access speed is less important, such as a
       firewall.</para>
 
     <programlisting>options          SOFTUPDATES  #Enable FFS Soft Updates support</programlisting>
 
     <para>This option enables Soft Updates in the kernel, this will help speed
       up write access on the disks.  They are enabled by default in the 4.X branch
       but may not be turned on.  Review the output from &man.mount.8; to see
       if you have them enabled.  If you do not see the <literal>soft-updates</literal> option then
       you will need to activate it using the &man.tunefs.8; or &man.newfs.8;
       for new filesystems.</para>      
 
     <programlisting>options          MFS          #Memory Filesystem
 options          MD_ROOT      #MD is a potential root device</programlisting>
 
     <para>This is the memory-mapped filesystem.  This is basically a RAM
       disk for fast storage of temporary files, useful if you have a lot
       of swap space that you want to take advantage of.  A perfect place
       to mount an MFS partition is on the <filename>/tmp</filename>
       directory, since many programs store temporary data here.  To mount
       an MFS RAM disk on <filename>/tmp</filename>, add the following line
       to <filename>/etc/fstab</filename>:</para>
 
     <informalexample>
       <programlisting>/dev/ad1s2b	/tmp mfs rw 0 0</programlisting>
     </informalexample>
 
     <para>Now you simply need to either reboot, or run the command
       <command>mount /tmp</command>.</para>
 
     <note><para>In FreeBSD 5.0, &man.md.4;-backed UFS file systems are
       used for memory file systems rather than MFS.  Information on
       configuring MD-backed file systems may be found in the man pages
       for &man.mdconfig.8; and &man.mdmfs.8;.  As a result, the
       <literal>MFS</literal> option is no longer supported.</para></note>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>NFS</secondary>
     </indexterm>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>NFS_ROOT</secondary>
     </indexterm>
     <programlisting>options          NFS          #Network Filesystem
 options          NFS_ROOT     #NFS usable as root device, NFS required</programlisting>
 
     <para>The network filesystem.  Unless you plan to mount partitions
       from a Unix file server over TCP/IP, you can comment these
       out.</para>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>MSDOSFS</secondary>
     </indexterm>
     <programlisting>options          MSDOSFS      #MSDOS Filesystem</programlisting>
 
     <para>The MS-DOS filesystem.  Unless you plan to mount a DOS formatted
       hard drive partition at boot time, you can safely comment this out.
       It will be automatically loaded the first time you mount a DOS
       partition, as described above.  Also, the excellent
       <application>mtools</application> software (in the ports collection)
       allows you to access DOS floppies without having to mount and
       unmount them (and does not require <literal>MSDOSFS</literal> at
       all).</para>
 
     <programlisting>options          CD9660       #ISO 9660 Filesystem
 options          CD9660_ROOT  #CD-ROM usable as root, CD9660 required</programlisting>
 
     <para>The ISO 9660 filesystem for CDROMs.  Comment it out if you do
       not have a CDROM drive or only mount data CDs occasionally (since it
       will be dynamically loaded the first time you mount a data CD).
       Audio CDs do not need this filesystem.</para>
 
     <programlisting>options          PROCFS       #Process filesystem</programlisting>
 
     <para>The process filesystem.  This is a <quote>pretend</quote>
       filesystem mounted on <filename>/proc</filename> which allows
       programs like &man.ps.1; to give you more information on what
       processes are running.  In FreeBSD 5.0, use of <literal>PROCFS
       </literal> is not required under most circumstances, as most
       debugging and monitoring tools have been adapted to run without
       <literal>PROCFS</literal>.  In addition, 5.0-CURRENT kernels
       making use of <literal>PROCFS</literal> must now also include
       support for <literal>PSEUDOFS</literal>:</para>
 
     <programlisting>options          PSEUDOFS     #Pseudo-filesystem framework</programlisting>
 
     <para><literal>PSEUDOFS</literal> is not available in FreeBSD 4.X.
       Unlike in FreeBSD 4.X, new installs of FreeBSD 5.0 will not mount
       the process file system by default.</para>
 
     <programlisting>options          COMPAT_43    #Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
 
     <para>Compatibility with 4.3BSD.  Leave this in; some programs will
       act strangely if you comment this out.</para>
 
     <programlisting>options          COMPAT_FREEBSD4     #Compatible with FreeBSD4</programlisting>
 
     <para>This option is required on FreeBSD 5.0 i386 and alpha systems
       to support applications compiled on older versions of FreeBSD
       that use older system call interfaces.  It is recommended that
       this option be used on all i386 and alpha systems that may
       run older applications; platforms that gained support only in
       5.0, such as ia64 and sparc64, do not require this option.</para>
 
     <programlisting>options          SCSI_DELAY=15000    #Delay (in ms) before probing SCSI</programlisting>
 
     <para>This causes the kernel to pause for 15 seconds before probing
       each SCSI device in your system.  If you only have IDE hard drives,
       you can ignore this, otherwise you will probably want to lower this
       number, perhaps to 5 seconds, to speed up booting.  Of course, if
       you do this, and FreeBSD has trouble recognizing your SCSI devices,
       you will have to raise it back up.</para>
 
     <programlisting>options          UCONSOLE            #Allow users to grab the console</programlisting>
 
     <para>Allow users to grab the console, which is useful for X users.
       For example, you can create a console <application>xterm</application>
       by typing <command>xterm
       -C</command>, which will display any &man.write.1;,
       &man.talk.1;, and any other messages you receive, as well
       as any console messages sent by the kernel.</para>
 
     <note><para>In FreeBSD 5.0, <literal>UCONSOLE</literal> is no
       longer required.</para></note>
 
     <programlisting>options          USERCONFIG          #boot -c editor</programlisting>
 
     <para>This option allows you to boot the configuration editor from the
       boot menu.</para>
 
     <programlisting>options          VISUAL_USERCONFIG   #visual boot -c editor</programlisting>
 
     <para>This option allows you to boot the visual configuration editor
       from the boot menu.</para>
 
       <note><para>From FreeBSD versions 5.0 and later, userconfig has been depreciated
 	in favor of the new &man.device.hints.5; method.  For more information
 	on &man.device.hints.5; please visit <xref linkend="device-hints"></para></note>
 
     <programlisting>options          KTRACE              #ktrace(1) support</programlisting>
 
     <para>This enables kernel process tracing, which is useful in
       debugging.</para>
 
     <programlisting>options          SYSVSHM             #SYSV-style shared memory</programlisting>
 
     <para>This option provides for System V shared memory.  The most
       common use of this is the XSHM extension in X, which many
       graphics-intensive programs will automatically take advantage of for
       extra speed.  If you use X, you will definitely want to include
       this.</para>
 
     <programlisting>options          SYSVSEM             #SYSV-style semaphores</programlisting>
 
     <para>Support for System V semaphores.  Less commonly used but only
       adds a few hundred bytes to the kernel.</para>
 
     <programlisting>options          SYSVMSG             #SYSV-style message queues</programlisting>
 
     <para>Support for System V messages.  Again, only adds a few hundred
       bytes to the kernel.</para>
 
     <note>
       <para>The &man.ipcs.1; command will list any processes using each of
 	these System V facilities.</para>
     </note>
 
     <programlisting>options 	P1003_1B		#Posix P1003_1B real-time extensions
 options 	_KPOSIX_PRIORITY_SCHEDULING</programlisting>
 
     <para>Real-time extensions added in the 1993 POSIX.  Certain
       applications in the ports collection use these
       (such as <application>StarOffice</application>).</para>
 
     <note><para>In FreeBSD 5.0, all of this functionality is now
       provided by the <literal>_KPOSIX_PRIORITY_SCHEDULING</literal>
       option, and <literal>P1003_1B</literal> is no longer
       required.</para></note>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>ICMP_BANDLIM</secondary>
     </indexterm>
     <indexterm>
       <primary>Denial of Service (DoS)</primary>
     </indexterm>
     <programlisting>options		ICMP_BANDLIM		#Rate limit bad replies</programlisting>
 
     <para>This option enables ICMP error response bandwidth limiting.  You
       typically want this option as it will help protect the machine from
       denial of service packet attacks.</para>
 
     <note><para>In FreeBSD 5.0, this feature is enabled by default and
       the <literal>ICMP_BANDLIM</literal> option is not required.
       </para></note>
 
     <indexterm>
       <primary>kernel options</primary>
       <secondary>SMP</secondary>
     </indexterm>
     <programlisting># To make an SMP kernel, the next two are needed
 #options        SMP                     # Symmetric MultiProcessor Kernel
 #options        APIC_IO                 # Symmetric (APIC) I/O</programlisting>
 
     <para>The above are both required for SMP support.</para>
 
     <programlisting>device          isa</programlisting>
 
     <para>All PCs supported by FreeBSD have one of these.  If you have an
       IBM PS/2 (Micro Channel Architecture), FreeBSD provides some limited support at
       this time.  For more information about the MCA support, see <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
 
     <programlisting>device          eisa</programlisting>
 
     <para>Include this if you have an EISA motherboard.  This enables
       auto-detection and configuration support for all devices on the EISA
       bus.</para>
 
     <programlisting>device          pci</programlisting>
 
     <para>Include this if you have a PCI motherboard.  This enables
       auto-detection of PCI cards and gatewaying from the PCI to ISA
       bus.</para>
 
     <programlisting># Floppy drives
 device          fdc0        at isa? port IO_FD1 irq 6 drq 2
 device          fd0         at fdc0 drive 0
 device          fd1         at fdc0 drive 1</programlisting>
 
     <para>This is the floppy drive controller.  <literal>fd0</literal> is
       the <devicename>A:</devicename> floppy drive, and
       <literal>fd1</literal> is the <devicename>B:</devicename>
       drive.</para>
 
     <programlisting>device          ata</programlisting>
 
     <para>This driver supports all ATA and ATAPI devices.  You only need
       one <literal>device ata</literal> line for the kernel to detect all
       PCI ATA/ATAPI devices on modern machines.</para>
 
     <programlisting>device          atadisk                 # ATA disk drives</programlisting>
 
     <para>This is needed along with <literal>device ata</literal> for
       ATA disk drives.</para>
 
     <programlisting><anchor id="kernelconfig-atapi">
 device          atapicd                 # ATAPI CDROM drives</programlisting>
 
     <para>This is needed along with <literal>device ata</literal> for
       ATAPI CDROM drives.</para>
 
     <programlisting>device          atapifd                 # ATAPI floppy drives</programlisting>
 
     <para>This is needed along with <literal>device ata</literal> for
       ATAPI floppy drives.</para>
 
     <programlisting>device          atapist                 # ATAPI tape drives</programlisting>
 
     <para>This is needed along with <literal>device ata</literal> for
       ATAPI tape drives.</para>
 
     <programlisting>options         ATA_STATIC_ID           #Static device numbering</programlisting>
 
     <para>This makes the controller number static (like the old driver) or
       else the device numbers are dynamically allocated.</para>
 
     <programlisting># ATA and ATAPI devices
 device          ata0        at isa? port IO_WD1 irq 14
 device          ata1        at isa? port IO_WD2 irq 15</programlisting>
 
     <para>Use the above for older, non-PCI systems.</para>
 
     <programlisting># SCSI Controllers
 device          ahb        # EISA AHA1742 family
 device          ahc        # AHA2940 and onboard AIC7xxx devices
 device          amd        # AMD 53C974 (Teckram DC-390(T))
 device          dpt        # DPT Smartcache - See LINT for options!
 device          isp        # Qlogic family
 device          ncr        # NCR/Symbios Logic
 device          sym        # NCR/Symbios Logic (newer chipsets)
 
 device          adv0       at isa?
 device          adw
 device          bt0        at isa?
 device          aha0       at isa?
 device          aic0       at isa?</programlisting>
 
     <para>SCSI controllers.  Comment out any you do not have in your
       system.  If you have an IDE only system, you can remove these
       altogether.</para>
 
     <programlisting># SCSI peripherals
 device          scbus      # SCSI bus (required)
 device          da         # Direct Access (disks)
 device          sa         # Sequential Access (tape etc)
 device          cd         # CD
 device          pass       # Passthrough device (direct SCSI
 access)</programlisting>
 
     <para>SCSI peripherals.  Again, comment out any you do not have, or if
       you have only IDE hardware, you can remove them completely.</para>
 
     <programlisting># RAID controllers
 device          ida        # Compaq Smart RAID
 device          amr        # AMI MegaRAID
 device          mlx        # Mylex DAC960 family</programlisting>
 
     <para>Supported RAID controllers.  If you do not have any of these,
       you can comment them out or remove them.</para>
 
     <programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse
 device          atkbdc0    at isa? port IO_KBD</programlisting>
 
     <para>The keyboard controller (<literal>atkbdc</literal>) provides I/O
       services for the AT keyboard and PS/2 style pointing devices.  This
       controller is required by the keyboard driver
       (<literal>atkbd</literal>) and the PS/2 pointing device driver
       (<literal>psm</literal>).</para>
 
     <programlisting>device          atkbd0     at atkbdc? irq 1</programlisting>
 
     <para>The <literal>atkbd</literal> driver, together with
       <literal>atkbdc</literal> controller, provides access to the AT 84
       keyboard or the AT enhanced keyboard which is connected to the AT
       keyboard controller.</para>
 
     <programlisting>device          psm0       at atkbdc? irq 12</programlisting>
 
     <para>Use this device if your mouse plugs into the PS/2 mouse
       port.</para>
 
     <programlisting>device          vga0        at isa?</programlisting>
 
     <para>The video card driver.</para>
 
     <programlisting># splash screen/screen saver
 pseudo-device          splash</programlisting>
 
     <para>Splash screen at start up!  Screen savers require this
       too.</para>
 
     <programlisting># syscons is the default console driver, resembling an SCO console
 device          sc0          at isa?</programlisting>
 
     <para><literal>sc0</literal> is the default console driver, which
       resembles a SCO console.  Since most full-screen programs access the
       console through a terminal database library like
       <filename>termcap</filename>, it should not matter whether you use
       this or <literal>vt0</literal>, the <literal>VT220</literal>
       compatible console driver.  When you log in, set your
       <envar>TERM</envar> variable to <literal>scoansi</literal> if
       full-screen programs have trouble running under this console.</para>
 
     <programlisting># Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
 #device          vt0     at isa?
 #options         XSERVER          # support for X server on a vt console
 #options         FAT_CURSOR       # start with block cursor
 # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
 #options         PCVT_SCANSET=2   # IBM keyboards are non-std</programlisting>
 
     <para>This is a VT220-compatible console driver, backward compatible to
       VT100/102.  It works well on some laptops which have hardware
       incompatibilities with <literal>sc0</literal>.  Also set your
       <envar>TERM</envar> variable to <literal>vt100</literal> or
       <literal>vt220</literal> when you log in.  This driver might also
       prove useful when connecting to a large number of different machines
       over the network, where <filename>termcap</filename> or
       <filename>terminfo</filename> entries for the <literal>sc0</literal>
       device are often not available &mdash; <literal>vt100</literal>
       should be available on virtually any platform.</para>
 
     <programlisting># Power management support (see LINT for more options)
 device          apm0     at nexus? disable flags 0x20  # Advanced Power Management</programlisting>
 
     <para>Advanced Power Management support.  Useful for laptops.</para>
 
     <programlisting># PCCARD (PCMCIA) support
 device          card
 device          pcic0    at isa? irq 10 port 0x3e0 iomem 0xd0000
 device          pcic1    at isa? irq 11 port 0x3e2 iomem 0xd4000 disable</programlisting>
 
     <para>PCMCIA support.  You want this if you are using a
       laptop.</para>
 
     <programlisting># Serial (COM) ports
 device          sio0     at isa? port IO_COM1 flags 0x10 irq 4
 device          sio1     at isa? port IO_COM2 irq 3
 device          sio2     at isa? disable port IO_COM3 irq 5
 device          sio3     at isa? disable port IO_COM4 irq 9</programlisting>
 
     <para>These are the four serial ports referred to as COM1 through COM4
       in the MS-DOS/Windows world.</para>
 
     <note>
       <para>If you have an internal modem on COM4 and a serial port at
 	COM2, you will have to change the IRQ of the modem to 2 (for
 	obscure technical reasons, IRQ2 = IRQ 9) in order to access it
 	from FreeBSD.  If you have a multiport serial card, check the
 	manual page for &man.sio.4; for more information on the proper
 	values for these lines.  Some video cards (notably those based on
 	S3 chips) use IO addresses in the form of
 	<literal>0x*2e8</literal>, and since many cheap serial cards do
 	not fully decode the 16-bit IO address space, they clash with
 	these cards making the COM4 port practically unavailable.</para>
 
       <para>Each serial port is required to have a unique IRQ (unless you
         are using one of the multiport cards where shared interrupts are
 	supported), so the default IRQs for COM3 and COM4 cannot be
 	used.</para>
     </note>
 
     <programlisting># Parallel port
 device          ppc0    at isa? irq 7</programlisting>
 
     <para>This is the ISA-bus parallel port interface.</para>
 
     <programlisting>device          ppbus      # Parallel port bus (required)</programlisting>
 
     <para>Provides support for the parallel port bus.</para>
 
     <programlisting>device          lpt        # Printer</programlisting>
 
     <para>Support for parallel port printers.</para>
 
     <note>
       <para>All three of the above are required to enable parallel printer
 	support.</para>
     </note>
 
     <programlisting>device          plip       # TCP/IP over parallel</programlisting>
 
     <para>This is the driver for the parallel network interface.</para>
 
     <programlisting>device          ppi        # Parallel port interface device</programlisting>
 
     <para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284
       I/O.</para>
 
     <programlisting>#device         vpo        # Requires scbus and da</programlisting>
 
     <indexterm><primary>zip drive</primary></indexterm>
     <para>This is for an Iomega Zip drive.  It requires
       <literal>scbus</literal> and <literal>da</literal> support.  Best
       performance is achieved with ports in EPP 1.9 mode.</para>
 
     <programlisting># PCI Ethernet NICs.
 device          de         # DEC/Intel DC21x4x (<quote>Tulip</quote>)
 device          fxp        # Intel EtherExpress PRO/100B (82557, 82558)
 device          tx         # SMC 9432TX (83c170 <quote>EPIC</quote>)
 device          vx         # 3Com 3c590, 3c595 (<quote>Vortex</quote>)
 device          wx         # Intel Gigabit Ethernet Card (<quote>Wiseman</quote>)</programlisting>
 
     <para>Various PCI network card drivers.  Comment out or remove any of
       these not present in your system.</para>
 
     <programlisting># PCI Ethernet NICs that use the common MII bus controller code.
 device          miibus     # MII bus support</programlisting>
 
     <para>MII bus support is required for some PCI 10/100 Ethernet NICs,
       namely those which use MII-compliant transceivers or implement
       transceiver control interfaces that operate like an MII.  Adding
       <literal>device miibus</literal> to the kernel config pulls in
       support for the generic miibus API and all of the PHY drivers,
       including a generic one for PHYs that are not specifically handled
       by an individual driver.</para>
 
     <programlisting>device          dc         # DEC/Intel 21143 and various workalikes
 device          rl         # RealTek 8129/8139
 device          sf         # Adaptec AIC-6915 (<quote>Starfire</quote>)
 device          sis        # Silicon Integrated Systems SiS 900/SiS 7016
 device          ste        # Sundance ST201 (D-Link DFE-550TX)
 device          tl         # Texas Instruments ThunderLAN
 device          vr         # VIA Rhine, Rhine II
 device          wb         # Winbond W89C840F
 device          xl         # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting>
 
     <para>Drivers that use the MII bus controller code.</para>
 
     <programlisting># ISA Ethernet NICs.
 device          ed0    at isa? port 0x280 irq 10 iomem 0xd8000
 device          ex
 device          ep
 # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
 # exists only as a PCMCIA device, so there is no ISA attachment needed
 # and resources will always be dynamically assigned by the pccard code.
 device          wi
 # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
 # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
 # mode (the factory default). If you set the switches on your ISA
 # card for a manually chosen I/O address and IRQ, you must specify
 # those parameters here.
 device          an
 # The probe order of these is presently determined by i386/isa/isa_compat.c.
 device          ie0    at isa? port 0x300 irq 10 iomem 0xd0000
 device          fe0    at isa? port 0x300
 device          le0    at isa? port 0x300 irq 5 iomem 0xd0000
 device          lnc0   at isa? port 0x280 irq 10 drq 0
 device          cs0    at isa? port 0x300
 device          sn0    at isa? port 0x300 irq 10
 # requires PCCARD (PCMCIA) support to be activated
 #device         xe0    at isa?</programlisting>
 
     <para>ISA Ethernet drivers.  See
       <filename>/usr/src/sys/i386/conf/LINT</filename> for which cards are
       supported by which driver.</para>
 
     <programlisting>pseudo-device   ether         # Ethernet support</programlisting>
 
     <para><literal>ether</literal> is only needed if you have an Ethernet
       card.  It includes generic Ethernet protocol code.</para>
 
     <programlisting>pseudo-device   sl      1     # Kernel SLIP</programlisting>
 
     <para><literal>sl</literal> is for SLIP support.  This has been almost
       entirely supplanted by PPP, which is easier to set up, better suited
       for modem-to-modem connection, and more powerful.  The
       <replaceable>number</replaceable> after <literal>sl</literal>
       specifies how many simultaneous SLIP sessions to support.</para>
 
     <programlisting>pseudo-device   ppp     1     # Kernel PPP</programlisting>
 
     <para>This is for kernel PPP support for dial-up connections.  There
       is also a version of PPP implemented as a userland application that
       uses <literal>tun</literal> and offers more flexibility and features
       such as demand dialing.  The <replaceable>number</replaceable> after
       <literal>ppp</literal> specifies how many simultaneous PPP
       connections to support.</para>
 
     <programlisting>pseudo-device   tun           # Packet tunnel.</programlisting>
 
     <para>This is used by the userland PPP software.  A
       <replaceable>number</replaceable> after <literal>tun</literal>
       specifies the number of simultaneous PPP sessions to support.  See
       the <link linkend="userppp">PPP</link> section of this book for more
       information.</para>
 
     <programlisting><anchor id="kernelconfig-ptys">
 pseudo-device   pty           # Pseudo-ttys (telnet etc)</programlisting>
 
     <para>This is a <quote>pseudo-terminal</quote> or simulated login port.
       It is used by incoming <command>telnet</command> and
       <command>rlogin</command> sessions,
       <application>xterm</application>, and some other applications such
       as <application>Emacs</application>.  A
       <replaceable>number</replaceable> after <literal>pty</literal> indicates the number of
       <literal>pty</literal>s to create.  If you need more than the
       default of 16 simultaneous <application>xterm</application> windows
       and/or remote logins, be sure to increase this number accordingly,
       up to a maximum of 256.</para>
 
     <programlisting>pseudo-device   md            # Memory <quote>disks</quote></programlisting>
 
     <para>Memory disk pseudo-devices.</para>
 
     <programlisting>pseudo-device   gif</programlisting>
 
     <para>or</para>
 
     <programlisting>pseudo-device   gif     4     # IPv6 and IPv4 tunneling</programlisting>
 
     <para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling,
       IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.  Beginning with
       FreeBSD&nbsp;4.4 the <literal>gif</literal> device is
       <quote>auto-cloning</quote>, and you should use the first example
       (without the number after <literal>gif</literal>).  Earlier versions of
       FreeBSD require the number.</para>
 
     <programlisting>pseudo-device   faith   1     # IPv6-to-IPv4 relaying (translation)</programlisting>
 
     <para>This pseudo-device captures packets that are sent to it and
       diverts them to the IPv4/IPv6 translation daemon.</para>
 
     <programlisting># The `bpf' pseudo-device enables the Berkeley Packet Filter.
 # Be aware of the administrative consequences of enabling this!
 pseudo-device   bpf           # Berkeley packet filter</programlisting>
 
     <para>This is the Berkeley Packet Filter.  This pseudo-device allows
       network interfaces to be placed in promiscuous mode, capturing every
       packet on a broadcast network (e.g., an Ethernet).  These packets
       can be captured to disk and or examined with the &man.tcpdump.1;
       program.</para>
 
     <note>
       <para>The <literal>bpf pseudo-device</literal> is also used by
 	&man.dhclient.8; to obtain the IP address of the default router
 	(gateway) and so on.  If you use DHCP, leave this
 	uncommented.</para>
     </note>
 
     <programlisting># USB support
 #device         uhci          # UHCI PCI-&gt;USB interface
 #device         ohci          # OHCI PCI-&gt;USB interface
 #device         usb           # USB Bus (required)
 #device         ugen          # Generic
 #device         uhid          # <quote>Human Interface Devices</quote>
 #device         ukbd          # Keyboard
 #device         ulpt          # Printer
 #device         umass         # Disks/Mass storage - Requires scbus and da
 #device         ums           # Mouse
 # USB Ethernet, requires mii
 #device         aue           # ADMtek USB ethernet
 #device         cue           # CATC USB ethernet
 #device         kue           # Kawasaki LSI USB ethernet</programlisting>
 
     <para>Support for various USB devices.</para>
 
     <para>For more information and additional devices supported by
       FreeBSD, see
       <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
   </sect1>
 
   <sect1 id="kernelconfig-nodes">
     <title>Making Device Nodes</title>
 
     <indexterm><primary>device nodes</primary></indexterm>
     <indexterm>
       <primary><command>MAKEDEV</command></primary>
     </indexterm>
 
     <note><para>If you are running FreeBSD&nbsp;5.0 or later
       you can safely skip this section.  These versions use
       &man.devfs.5; to allocate device nodes transparently for the user.</para></note>
 
     <para>Almost every device in the kernel has a corresponding
       <quote>node</quote> entry in the <filename>/dev</filename> directory.
       These nodes look like regular files, but are actually special
       entries into the kernel which programs use to access the device.
       The shell script <filename>/dev/MAKEDEV</filename>, which is
       executed when you first install the operating system, creates
       nearly all of the device nodes supported.  However, it does not
       create <emphasis>all</emphasis> of them, so when you add support for
       a new device, it pays to make sure that the appropriate entries are
       in this directory, and if not, add them.  Here is a simple
       example:</para>
 
     <para>Suppose you add the IDE CD-ROM support to the kernel.  The line
       to add is:</para>
 
     <programlisting>device acd0</programlisting>
 
     <para>This means that you should look for some entries that start with
       <filename>acd0</filename> in the <filename>/dev</filename>
       directory, possibly followed by a letter, such as
       <literal>c</literal>, or preceded by the letter
       <literal>r</literal>, which means a <quote>raw</quote> device.  It
       turns out that those files are not there, so you must change to the
       <filename>/dev</filename> directory and type:</para>
 
     <indexterm>
       <primary><command>MAKEDEV</command></primary></indexterm>
     <screen>&prompt.root; <userinput>sh MAKEDEV acd0</userinput></screen>
 
     <para>When this script finishes, you will find that there are now
       <filename>acd0c</filename> and <filename>racd0c</filename> entries
       in <filename>/dev</filename> so you know that it executed
       correctly.</para>
 
     <para>For sound cards, the following command creates the appropriate
       entries:</para>
 
     <screen>&prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen>
 
     <note>
       <para>When creating device nodes for devices such as sound cards, if
 	other people have access to your machine, it may be desirable to
 	protect the devices from outside access by adding them to the
 	<filename>/etc/fbtab</filename> file.  See &man.fbtab.5; for more
 	information.</para>
     </note>
 
     <para>Follow this simple procedure for any other
       non-<filename>GENERIC</filename>  devices which do not have
       entries.</para>
 
     <note>
       <para>All SCSI controllers use the same set of
 	<filename>/dev</filename> entries, so you do not need to create
 	these.  Also, network cards and SLIP/PPP pseudo-devices do not
 	have entries in <filename>/dev</filename> at all, so you do not
 	have to worry about these either.</para>
     </note>
   </sect1>
 
   <sect1 id="kernelconfig-trouble">
     <title>If Something Goes Wrong</title>
 
     <para>There are five categories of trouble that can occur when
       building a custom kernel.  They are:</para>
 
     <variablelist>
       <varlistentry>
 	<term><command>config</command> fails:</term>
 
 	<listitem>
 	  <para>If the &man.config.8; command fails when you
 	    give it your kernel description, you have probably made a
 	    simple error somewhere.  Fortunately,
 	    &man.config.8; will print the line number that it
 	    had trouble with, so you can quickly skip to it with
 	    <application>vi</application>.  For example, if you see:</para>
 
 	  <screen>config: line 17: syntax error</screen>
 
 	  <para>You can skip to the problem in <application>vi</application> by
 	    typing <command>17G</command> in command mode.  Make sure the
 	    keyword is typed correctly, by comparing it to the
 	    <filename>GENERIC</filename> kernel or another
 	    reference.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><command>make</command> fails:</term>
 
 	<listitem>
 	  <para>If the <command>make</command> command fails, it usually
 	    signals an error in your kernel description, but not severe
 	    enough for &man.config.8; to catch it.  Again, look
 	    over your configuration, and if you still cannot resolve the
 	    problem, send mail to the &a.questions; with your kernel
 	    configuration, and it should be diagnosed very quickly.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Installing the new kernel fails:</term>
 	
 	<listitem>
 	  <para>If the kernel compiled fine, but failed to install
 	    (the <command>make install</command> or
 	    <command>make installkernel</command> command failed),
 	    the first thing to check is if your system is running at
 	    securelevel 1 or higher (see &man.init.8;).  The kernel
 	    installation tries to remove the immutable flag from
 	    your kernel and set the immutable flag on the new one.
 	    Since securelevel 1 or higher prevents unsetting the immutable
 	    flag for any files on the system, the kernel installation needs
 	    to be performed at securelevel 0 or lower.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>The kernel does not boot:<anchor
 	  id="kernelconfig-noboot"></term>
 
 	<listitem>
 	  <para>If your new kernel does not boot, or fails to
 	    recognize your devices, do not panic!  Fortunately, FreeBSD has
 	    an excellent mechanism for recovering from incompatible
 	    kernels.  Simply choose the kernel you want to boot from at
 	    the FreeBSD boot loader. You can access this when the system
 	    counts down from 10.  Hit any key except for the
             <keycap>Enter</keycap> key, type <command>unload</command>
             and then type
 	    <command>boot <replaceable>kernel.old</replaceable></command>,
             or the filename of any other kernel that will boot properly.
             When reconfiguring a kernel, it is always a good idea to keep
             a kernel that is known to work on hand.</para>
 
 	  <para>After booting with a good kernel you can check over your
 	    configuration file and try to build it again.  One helpful
 	    resource is the <filename>/var/log/messages</filename> file
 	    which records, among other things, all of the kernel messages
 	    from every successful boot.  Also, the &man.dmesg.8; command
 	    will print the kernel messages from the current boot.</para>
 
 	  <note>
 	    <para>If you are having trouble building a kernel, make sure
 	      to keep a <filename>GENERIC</filename>, or some other kernel
 	      that is known to work on hand as a different name that will
 	      not get erased on the next build.  You cannot rely on
 	      <filename>kernel.old</filename> because when installing a
 	      new kernel, <filename>kernel.old</filename> is overwritten
 	      with the last installed kernel which may be non-functional.
 	      Also, as soon as possible, move the working kernel to the
 	      proper <filename>kernel</filename> location or commands such
 	      as &man.ps.1; will not work properly.  The proper command to
 	      <quote>unlock</quote> the kernel file that
 	      <command>make</command> installs (in order to move another
 	      kernel back permanently) is:</para>
 
 	    <screen>&prompt.root; <userinput>chflags noschg /kernel</userinput></screen>
 
 	    <para>If you find you cannot do this, you are probably running
 	      at a &man.securelevel.8; greater than zero.  Edit
 	      <literal>kern_securelevel</literal> in
 	      <filename>/etc/rc.conf</filename> and set it to
 	      <literal>-1</literal>, then reboot.  You can change it back
 	      to its previous setting when you are happy with your new
 	      kernel.</para>
 
 	    <para>And, if you want to <quote>lock</quote> your new kernel
 	      into place, or any file for that matter, so that it cannot
 	      be moved or tampered with:</para>
 
 	    <screen>&prompt.root; <userinput>chflags schg /kernel</userinput></screen>
 	  </note>
 
 	  <note><para>In FreeBSD 5.0, kernels are not installed with the
 	    system immutable flag, so this is unlikely to be the source
 	    of the problem you're experiencing.</para></note>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>The kernel works, but &man.ps.1; does not work
 	  any more:</term>
 
 	<listitem>
 	  <para>If you have installed a different version of the kernel
 	    from the one that the system utilities have been built with,
 	    for example, a 4.X kernel on a 3.X system, many system-status
 	    commands like &man.ps.1; and &man.vmstat.8; will not work any
 	    more.  You must recompile the <filename>libkvm</filename>
 	    library as well as these utilities.  This is one reason it is
 	    not normally a good idea to use a different version of the
 	    kernel from the rest of the operating system.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
index 755e2a4341..b6af76df58 100644
--- a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
@@ -1,973 +1,973 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="l10n">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Andrey A.</firstname>
 	<surname>Chernov</surname>
 	<contrib>Contributed by </contrib>
       </author>
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Michael C.</firstname>
 	<surname>Wu</surname>
 	<contrib>Rewritten by </contrib>
       </author>
       <!-- 30 Nv 2000 -->
     </authorgroup>
   </chapterinfo>
 
   <title>Localization - I18N/L10N Usage and Setup</title>
 
-  <sect1>
+  <sect1 id="l10n-synopsis">
     <title>Synopsis</title>
 
     <para>FreeBSD is a very distributed project with users and
       contributors located all over the world.  This chapter discusses
       the internationalization and localization features of FreeBSD
       that allow non-English speaking users to get real work done.
       There are many aspects of the i18n implementation in both the system
       and application levels, so where applicable we refer the reader
       to more specific sources of documentation.</para>
 
     <para>After reading this chapter, you will know:</para>
     <itemizedlist>
       <listitem><para>How different languages and locales are encoded
       on modern operating systems.</para></listitem>
       <listitem><para>How to set the locale for your login
       shell.</para></listitem>
       <listitem><para>How to configure your console for non-English
       languages.</para></listitem>
       <listitem><para>How to use X Windows effectively with different
       languages.</para></listitem>
       <listitem><para>Where to find more information about writing
       i18n-compliant applications.</para></listitem>
    </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem><para>Know how to install additional third-party
         applications (<xref linkend="ports">).</para></listitem>
     </itemizedlist>
   </sect1>
 
-  <sect1>
+  <sect1 id="l10n-basics">
     <title>The Basics</title>
 
     <sect2>
       <title>What is I18N/L10N?</title>
     <indexterm><primary>internationalization</primary></indexterm> 
     <indexterm><primary>localization</primary></indexterm> 
 
       <para>Developers shortened internationalization into the term I18N,
 	counting the number of letters between the first and the last
 	letters of internationalization.  L10N uses the same naming
 	scheme, coming from <quote>localization</quote>.  Combined
 	together, I18N/L10N methods, protocols, and applications allow
 	users to use languages of their choice.</para>
 
       <para>I18N applications are programmed using I18N kits under
 	libraries.  It allows for developers to write a simple file and
 	translate displayed menus and texts to each language.  We strongly
 	encourage programmers to follow this convention.</para>
     </sect2>
 
     <sect2>
       <title>Why Should I Use I18N/L10N?</title>
 
       <para>I18N/L10N is used whenever you wish to either view, input, or
 	process data in non-English languages.</para>
     </sect2>
 
     <sect2>
       <title>What Languages Are Supported in the I18N Effort?</title>
 
       <para>I18N and L10N are not FreeBSD specific.  Currently, one can
 	choose from most of the major languages of the World, including
 	but not limited to:  Chinese, German, Japanese, Korean, French,
 	Russian, Vietnamese and others.</para>
     </sect2>
   </sect1>
 
   <sect1 id="using-localization">
     <title>Using Localization</title>
 
     <para>In all its splendor, I18N is not FreeBSD-specific and is a
       convention.  We encourage you to help FreeBSD in following this
       convention.</para>
     <indexterm><primary>locale</primary></indexterm>
 
     <para>Localization settings are based on three main terms:
       Language Code, Country Code, and Encoding.  Locale names are
       constructed from these parts as follows:</para>
 
     <programlisting><replaceable>LanguageCode</replaceable>_<replaceable>CountryCode</replaceable>.<replaceable>Encoding</replaceable></programlisting>
 
     <sect2>
       <title>Language and Country Codes</title>
       <indexterm><primary>language codes</primary></indexterm>
       <indexterm><primary>country codes</primary></indexterm>
 
       <para>In order to localize a FreeBSD system to a specific language
 	(or any other I18N-supporting Unixes), the user needs to find out
 	the codes for the specify country and language (country
 	codes tell applications what variation of given
 	language to use).  In addition, web
 	browsers, SMTP/POP servers, web servers, etc. make decisions based on
 	them.  The following are examples of language/country codes:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Language/Country Code</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>en_US</entry>
 	      <entry>English - United States</entry>
 	    </row>
 
 	    <row>
 	      <entry>ru_RU</entry>
 	      <entry>Russian for Russia</entry>
 	    </row>
 
 	    <row>
 	      <entry>zh_TW</entry>
 	      <entry>Traditional Chinese for Taiwan</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
     </sect2>
 
     <sect2>
       <title>Encodings</title>
       <indexterm><primary>encodings</primary></indexterm>
       <indexterm><primary>ASCII</primary></indexterm>
 
       <para>Some languages use non-ASCII encodings that are 8-bit, wide
 	or multibyte characters, see &man.multibyte.3; for more
 	details. Older applications do not recognize them
 	and mistake them for control characters.  Newer applications
 	usually do recognize 8-bit characters.  Depending on the
 	implementation, users may be required to compile an application
 	with wide or multibyte characters support, or configure it correctly.
 	To be able to input and process wide or multibyte characters, the <ulink 
 	url="../../../../ports/index.html">FreeBSD Ports collection</ulink> has provided
 	each language with different programs.  Refer to the I18N
 	documentation in the respective FreeBSD Port.</para>
 
       <para>Specifically, the user needs to look at the application
 	documentation to decide on how to configure it correctly or to
 	pass correct values into the configure/Makefile/compiler.</para>
 
       <para>Some things to keep in mind are:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Language specific single C chars character sets
 	  (see &man.multibyte.3;), i.e.,
 	    ISO-8859-1, ISO-8859-15, KOI8-R, CP437.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Wide or multibyte encodings, i.e. EUC, Big5.</para>
 	</listitem>
       </itemizedlist>
 
       <para>You can check the active list of character sets at the
 	<ulink
 	url="http://www.iana.org/assignments/character-sets">IANA Registry</ulink>.</para>
 
       <note>
       <para>FreeBSD versions 4.5 and up use X11-compatible locale
 	encodings instead.</para>
       </note>
 
     </sect2>
 
     <sect2>
       <title>I18N Applications</title>
 
       <para>In the FreeBSD Ports and Package system, I18N applications
 	have been named with <literal>I18N</literal> in their names for
 	easy identification.  However, they do not always support the
 	language needed.</para>
     </sect2>
 
     <sect2 id="setting-locale">
       <title>Setting Locale</title>
 
       <para>Usually it is sufficient to export the value of the locale name
         as <envar>LANG</envar> in the login shell.  This could be done in
 	the user's <filename>~/.login_conf</filename> file or in the
 	startup file of the user's shell (<filename>~/.profile</filename>,
 	<filename>~/.bashrc</filename>, <filename>~/.cshrc</filename>).
 	There is no need to set the locale subsets such as
 	<envar>LC_CTYPE</envar>, <envar>LC_CTIME</envar>.  Please
 	refer to language-specific FreeBSD documentation for more
 	information.</para>
 
       <para>You should set the following two environment variables in your configuration
 	files:</para>
 
       <itemizedlist>
         <indexterm><primary>POSIX</primary></indexterm>
         <listitem>
 	  <para><envar>LANG</envar> for POSIX &man.setlocale.3; family
 	    functions</para>
 	</listitem>
 
         <indexterm><primary>MIME</primary></indexterm>
 	<listitem>
 	  <para><envar>MM_CHARSET</envar> for applications' MIME character
 	    set</para>
 	</listitem>
       </itemizedlist>
 
       <para>This includes the user shell configuration, the specific application
         configuration, and the X11 configuration.</para>
 
       <sect3>
 	<title>Setting Locale Methods</title>
         <indexterm><primary>locale</primary></indexterm>
         <indexterm><primary>login class</primary></indexterm>
 
 	<para>There are two methods for setting locale, and both are
 	  described below.  The first (recommended one) is by assigning
 	  the environment variables in <link linkend="login-class">login
 	  class</link>, and the second is by adding the environment
 	  variable assignments to the system's shell <link
 	  linkend="startup-file">startup file</link>.</para>
 
 	<sect4 id="login-class">
 	  <title>Login Classes Method</title>
 
 	  <para>This method allows environment variables needed for locale
 	    name and MIME character sets to be assigned once for every
 	    possible shell instead of adding specific shell assignments to
 	    each shell's startup file.  <link linkend="usr-setup">User
 	    Level Setup</link> can be done by an user himself and <link
 	    linkend="adm-setup">Administrator Level Setup</link> require
 	    superuser privileges.</para>
 
 	  <sect5 id="usr-setup">
 	    <title>User Level Setup</title>
 
 	    <para>Here is a minimal example of a
 	      <filename>.login_conf</filename> file in user's home
 	      directory which has both variables set for Latin-1
 	      encoding:</para>
 
 	    <programlisting>me:\
 	:charset=ISO-8859-1:\
 	:lang=de_DE.ISO8859-1:</programlisting>
 
 	    <indexterm><primary>Traditional Chinese / BIG-5 encoding</primary></indexterm>
 	    <para>Here is an example of a 
 	       <filename>.login_conf</filename> that sets the variables
 	       for Traditional Chinese in BIG-5 encoding.  Notice the many
 	       more variables set because some software does not respect
 	       locale variables correctly for Chinese, Japanese, and Korean.</para>
 
 	    <programlisting>#Users who do not wish to use monetary units or time formats
 #of Taiwan can manually change each variable
 me:\
 	lang=zh_TW.Big5:\
 	lc_all=zh_TW.Big:\
 	lc_collate=zh_TW.Big5:\ 
 	lc_ctype=zh_TW.Big5:\
 	lc_messages=zh_TW.Big5:\
 	lc_monetary=zh_TW.Big5:\
 	lc_numeric=zh_TW.Big5:\
 	lc_time=zh_TW.Big5:\
 	charset=big5:\
 	xmodifiers="@im=xcin": #Setting the XIM Input Server</programlisting> 
 
 	    <para>See <link linkend="adm-setup">Administrator Level
 	      Setup</link> and &man.login.conf.5; for more details.</para>
 	  </sect5>
 
 	  <sect5 id="adm-setup">
 	    <title>Administrator Level Setup</title>
 
 	    <para>Verify that the user's login class in
 	      <filename>/etc/login.conf</filename> sets the correct
 	      language.  Make sure these settings
 	      appear in <filename>/etc/login.conf</filename>:</para>
 
 	    <programlisting><replaceable>language_name</replaceable>:<replaceable>accounts_title</replaceable>:\
 	:charset=<replaceable>MIME_charset</replaceable>:\
 	:lang=<replaceable>locale_name</replaceable>:\
 	:tc=default:</programlisting>
 
 	    <para>So sticking with our previous example using Latin-1, it
 	      would look like this:</para>
 
 	    <programlisting>german:German Users Accounts:\
 	:charset=ISO-8859-1:\
 	:lang=de_DE.ISO8859-1:\
 	:tc=default:</programlisting>
 
 	    <bridgehead renderas=sect4>Changing Login Classes with &man.vipw.8;</bridgehead>
 
 	    <indexterm>
         <primary><command>vipw</command></primary>
       </indexterm>
 	    <para>Use <command>vipw</command> to add new users, and make
 	      the entry look like this:</para>
 
 	    <programlisting>user:password:1111:11:<replaceable>language</replaceable>:0:0:User Name:/home/user:/bin/sh</programlisting>
 
 	    <bridgehead renderas=sect4>Changing Login Classes with &man.adduser.8;</bridgehead>
 
 	    <indexterm>
         <primary><command>adduser</command></primary>
       </indexterm>
 	    <indexterm><primary>login class</primary></indexterm>
 	    <para>Use <command>adduser</command> to add new users, and do
 	      the following:</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para>Set <literal>defaultclass =
 		  <replaceable>language</replaceable></literal> in
 		  <filename>/etc/adduser.conf</filename>.  Keep in mind
 		  you must enter a <literal>default</literal> class for
 		  all users of other languages in this case.</para>
 	      </listitem>
 
 	      <listitem>
 		<para>An alternative variant is answering the specified
 		  language each time that 
 <screen><prompt>Enter login class: default []: </prompt></screen>
 		  appears from &man.adduser.8;.</para>
 	      </listitem>
 
 	      <listitem>
 		<para>Another alternative is to use the following for each
 		  user of a different language that you wish to
 		  add:</para>
 
 		<screen>&prompt.root; <userinput>adduser -class <replaceable>language</replaceable></userinput></screen>
 	      </listitem>
 	    </itemizedlist>
 
 	    <bridgehead renderas=sect4>Changing Login Classes with &man.pw.8;</bridgehead>
 	    <indexterm>
         <primary><command>pw</command></primary>
       </indexterm>
 	    <para>If you use &man.pw.8; for adding new users, call it in
 	      this form:</para>
 
 	    <screen>&prompt.root; <userinput>pw useradd <replaceable>user_name</replaceable> -L <replaceable>language</replaceable></userinput></screen>
 	  </sect5>
 	</sect4>
 
 	<sect4 id="startup-file">
 	  <title>Shell Startup File Method</title>
 
 	  <note>
 	    <para>This method is not recommended because it requires a
 	      different setup for each possible login program chosen.  Use
 	      the <link linkend="login-class">Login Class Method</link>
 	      instead.</para>
 	  </note>
 
 	  <indexterm><primary>MIME</primary></indexterm>
 	  <indexterm><primary>locale</primary></indexterm>
 	  <para>To add the locale name and MIME character set, just set
 	    the two environment variables shown below in the
 	    <filename>/etc/profile</filename> and/or
 	    <filename>/etc/csh.login</filename> shell startup files.  We
 	    will use the German language as an example below:</para>
 
 	  <para>In <filename>/etc/profile</filename>:</para>
 
 	  <programlisting><envar>LANG=de_DE.ISO8859-1; export LANG</envar>
 <envar>MM_CHARSET=ISO-8859-1; export MM_CHARSET</envar></programlisting>
 
 	  <para>Or in <filename>/etc/csh.login</filename>:</para>
 
 	  <programlisting><envar>setenv LANG de_DE.ISO8859-1</envar>
 <envar>setenv MM_CHARSET ISO-8859-1</envar></programlisting>
 
 	  <para>Alternatively, you can add the above instructions to
 	    <filename>/usr/share/skel/dot.profile</filename> (similar to
 	    what was used in <filename>/etc/profile</filename> above), or
 	    <filename>/usr/share/skel/dot.login</filename> (similar to
 	    what was used in <filename>/etc/csh.login</filename>
 	    above).</para>
 
 	  <para>For X11:</para>
 
 	  <para>In <filename>$HOME/.xinitrc</filename>:</para>
 
 	  <programlisting><envar>LANG=de_DE.ISO8859-1; export LANG</envar></programlisting>
 
 	  <para>Or:</para>
 
 	  <programlisting><envar>setenv LANG de_DE.ISO8859-1</envar></programlisting>
 
 	  <para>Depending on your shell (see above).</para>
 
 	</sect4>
       </sect3>
     </sect2>
 
     <sect2 id="setting-console">
       <title>Console Setup</title>
 
       <para>For all single C chars character sets, set the correct
 	console fonts in <filename>/etc/rc.conf</filename> for the
 	language in question with:</para>
 
       <programlisting>font8x16=<replaceable>font_name</replaceable>
 font8x14=<replaceable>font_name</replaceable>
 font8x8=<replaceable>font_name</replaceable></programlisting>
 
       <para>The <replaceable>font_name</replaceable> here is taken from
         the <filename>/usr/share/syscons/fonts</filename> directory,
 	without the <filename>.fnt</filename> suffix.</para>
 
       <indexterm>
         <primary><application>sysinstall</application></primary>
       </indexterm>
       <indexterm><primary>keymap</primary></indexterm>
       <indexterm><primary>screenmap</primary></indexterm>
       <para>Also be sure to set the correct keymap and screenmap for your
 	single C chars character set through
 	<filename>/stand/sysinstall</filename>.
 	Once inside <application>sysinstall</application>, choose <guimenuitem>Configure</guimenuitem>, then
 	<guimenuitem>Console</guimenuitem>.  Alternatively, you can add the
 	following to <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>scrnmap=<replaceable>screenmap_name</replaceable>
 keymap=<replaceable>keymap_name</replaceable>
 keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting>
 	
       <para>The <replaceable>screenmap_name</replaceable> here is taken
         from the <filename>/usr/share/syscons/scrnmaps</filename>
 	directory, without the <filename>.scm</filename> suffix.  A
 	screenmap with a corresponding mapped font is usually needed as a
 	workaround for expanding bit 8 to bit 9 on a VGA adapter's font
 	character matrix in pseudographics area, i.e., to move letters out
 	of that area if screen font uses a bit 8 column.</para>
 
       <para>If you have the <application>moused</application> daemon
 	enabled by setting the following
 	in your <filename>/etc/rc.conf</filename>:</para>
 
 <programlisting>moused_enable="YES"</programlisting>
 
       <para>then examine the mouse cursor information in the next
 	paragraph.</para>
 
       <indexterm>
         <primary><application>moused</application></primary>
       </indexterm>
       <para>By default the mouse cursor of the &man.syscons.4; driver occupies the
 	0xd0-0xd3 range in the character set.  If your language uses this
 	range, you need to move the cursor's range outside of it.  To enable
 	the workaround for FreeBSD versions before 5.0, insert the following
 	line into your kernel configuration:</para>
 
       <programlisting>options		SC_MOUSE_CHAR=0x03</programlisting>
 
       <para>For the FreeBSD versions 4.4 and up insert the following line
 	into <filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>mousechar_start=3</programlisting>
 
       <para>The <replaceable>keymap_name</replaceable> here is taken from
         the <filename>/usr/share/syscons/keymaps</filename> directory,
 	without the <filename>.kbd</filename> suffix.  If you're
 	uncertain which keymap to use, you use can &man.kbdmap.1; to test
 	keymaps without rebooting.</para>
 
       <para>The <literal>keychange</literal> is usually needed to program
         function keys to match the selected terminal type because
 	function key sequences cannot be defined in the key map.</para>
 
       <para>Also be sure to set the correct console terminal type in
         <filename>/etc/ttys</filename> for all <literal>ttyv*</literal>
 	entries.  Current pre-defined correspondences are:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Character Set</entry>
 	      <entry>Terminal Type</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>ISO-8859-1 or ISO-8859-15</entry>
 	      <entry><literal>cons25l1</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>ISO-8859-2</entry>
 	      <entry><literal>cons25l2</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>ISO-8859-7</entry>
 	      <entry><literal>cons25l7</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>KOI8-R</entry>
 	      <entry><literal>cons25r</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>KOI8-U</entry>
 	      <entry><literal>cons25u</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>CP437 (VGA default)</entry>
 	      <entry><literal>cons25</literal></entry>
 	    </row>
 
 	    <row>
 	      <entry>US-ASCII</entry>
 	      <entry><literal>cons25w</literal></entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>For wide or multibyte characters languages, use the correct
 	FreeBSD port in your
 	<filename>/usr/ports/<replaceable>language</replaceable></filename>
 	directory.  Some ports appear as console while the system sees it
 	as serial vtty's, hence you must reserve enough vtty's for both
 	X11 and the pseudo-serial console.  Here is a partial list of
 	applications for using other languages in console:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Language</entry>
 	      <entry>Location</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>Traditional Chinese (BIG-5)</entry>
 	      <entry><filename role="package">chinese/big5con</filename></entry>
 	    </row>
 
 	    <row>
 	      <entry>Japanese</entry>
 	      <entry><filename role="package">japanese/ja-kon2-*</filename> or
 	        <filename role="package">japanese/Mule_Wnn</filename></entry>
 	    </row>
 
 	    <row>
 	      <entry>Korean</entry>
 	      <entry><filename role="package">korean/ko-han</filename></entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
     </sect2>
 
     <sect2>
       <title>X11 Setup</title>
 
       <para>Although X11 is not part of the FreeBSD Project, we have
 	included some information here for FreeBSD users.  For more
 	details, refer to the <ulink url="http://www.xfree86.org/">XFree86
 	web site</ulink> or whichever X11 Server you use.</para>
 
       <para>In <filename>~/.Xresources</filename>, you can additionally
 	tune application specific I18N settings (e.g., fonts, menus,
 	etc.).</para>
 
       <sect3>
 	<title>Displaying Fonts</title>
 	<indexterm><primary>X11 True Type font server</primary></indexterm>
 	<para>Install the X11 True Type-Common server (<filename role="package">x11-servers/XttXF86srv-common</filename>) and
 	  install the language truetype fonts.  Setting the correct
 	  locale should allow you to view your selected language in menus
 	  and such.</para>
       </sect3>
 
       <sect3>
 	<title>Inputting Non-English Characters</title>
 	<indexterm><primary>X11 Input Method (XIM)</primary></indexterm>
 	<para>The X11 Input Method (XIM) Protocol is a new standard for
 	  all X11 clients.  All X11 applications should be written as XIM
 	  clients that take input from XIM Input servers.  There are
 	  several XIM servers available for different languages.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Printer Setup</title>
 
       <para>Some single C chars character sets are usually hardware
 	coded into printers. Wide or multibyte
 	character sets require special setup and we recommend using
 	<application>apsfilter</application>.  You may also convert the
 	document to PostScript or PDF formats using language specific
 	converters.</para>
     </sect2>
 
     <sect2>
       <title>Kernel and File Systems</title>
 
       <para>The FreeBSD fast filesystem (FFS) is 8-bit clean, so it can be used
 	with any single C chars character set (see &man.multibyte.3;),
 	but there is no character set
 	name stored in the filesystem; i.e., it is raw 8-bit and does not
 	know anything about encoding order.  Officially, FFS does not
 	support any form of wide or multibyte character sets yet.  However, some
 	wide or multibyte character sets have independent patches for FFS
 	enabling such support.  They are only temporary unportable
 	solutions or hacks and we have decided to not include them in the
 	source tree.  Refer to respective languages' web sites for more
 	informations and the patch files.</para>
 
       <indexterm><primary>DOS</primary></indexterm>
       <indexterm><primary>Unicode</primary></indexterm>
       <para>The FreeBSD MS-DOS filesystem has the configurable ability to
 	convert between MS-DOS, Unicode character sets and chosen
 	FreeBSD filesystem character sets.  See &man.mount.msdos.8; for
 	details.</para>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="l10n-compiling">
     <title>Compiling I18N Programs</title>
 
     <para>Many FreeBSD Ports have been ported with I18N support.  Some
       of them are marked with -I18N in the port name.  These and many
       other programs have built in support for I18N and need no special
       consideration.</para>
 
     <indexterm>
       <primary><application>MySQL</application></primary>
     </indexterm>
     <para>However, some applications such as 
       <application>MySQL</application> need to be have the
       <filename>Makefile</filename> configured with the specific
       charset.  This is usually done in the
       <filename>Makefile</filename> or done by passing a value to
       <application>configure</application> in the source.</para>
   </sect1>
 
   <sect1 id="lang-setup">	
     <title>Localizing FreeBSD to Specific Languages</title>
 
     <sect2 id="ru-localize">
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Andrey A.</firstname>
 	    <surname>Chernov</surname>
 	    <contrib>Originally contributed by </contrib>
 	  </author>
 	</authorgroup>
       </sect2info>
       <title>Russian Language (KOI8-R encoding)</title>
       <indexterm>
 	<primary>localization</primary>
 	<secondary>Russian</secondary>
       </indexterm>
 
       <para>For more information about KOI8-R encoding, see the <ulink
 	url="http://koi8.pp.ru/">KOI8-R References
 	(Russian Net Character Set)</ulink>.</para>
 
       <sect3>
 	<title>Locale Setup</title>
 
 	<para>Put the following lines into your
 	  <filename>~/.login_conf</filename> file:</para>
 
 	<programlisting>me:My Account:\
 	:charset=KOI8-R:\
 	:lang=ru_RU.KOI8-R:</programlisting>
 
 	<para>See earlier in this chapter for examples of setting up the
 	  <link linkend="setting-locale">locale</link>.</para>
       </sect3>
 
       <sect3>
 	<title>Console Setup</title>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>For the FreeBSD versions before 5.0 add the following line
 	      to your kernel configuration file:</para>
 
 	    <programlisting>options		SC_MOUSE_CHAR=0x03</programlisting>
 
 	    <para>For the FreeBSD versions 4.4 and up insert the following
 	      line into <filename>/etc/rc.conf</filename>:</para>
 
 	    <programlisting>mousechar_start=3</programlisting>
 	  </listitem>
 
 	  <listitem>
 	    <para>Use following settings in
 	      <filename>/etc/rc.conf</filename>:</para>
 
 	    <programlisting>keymap="ru.koi8-r"
 scrnmap="koi8-r2cp866"
 font8x16="cp866b-8x16"
 font8x14="cp866-8x14"
 font8x8="cp866-8x8"</programlisting>
 
 	  </listitem>
 
 	  <listitem>
 	    <para>For each <literal>ttyv*</literal> entry in
 	      <filename>/etc/ttys</filename>, use
 	      <literal>cons25r</literal> as the terminal type.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>See earlier in this chapter for examples of setting up the
 	  <link linkend="setting-console">console</link>.</para>
       </sect3>
 
       <sect3>
 	<title>Printer Setup</title>
 	<indexterm><primary>printers</primary></indexterm>
 	<para>Since most printers with Russian characters come with
 	  hardware code page CP866, a special output filter is needed
 	  to convert from KOI8-R to CP866.  Such a filter is installed by
 	  default as <filename>/usr/libexec/lpr/ru/koi2alt</filename>.
 	  A Russian printer <filename>/etc/printcap</filename> entry
 	  should look like:</para>
 
 	<programlisting>lp|Russian local line printer:\
 	:sh:of=/usr/libexec/lpr/ru/koi2alt:\
 	:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:</programlisting>
 
 	<para>See &man.printcap.5; for a detailed description.</para>
       </sect3>
 
       <sect3>
 	<title>MS-DOS FS and Russian Filenames</title>
 
 	<para>The following example &man.fstab.5; entry enables support
 	  for Russian filenames in mounted MS-DOS filesystems:</para>
 
 	<programlisting>/dev/ad0s2      /dos/c  msdos   rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0</programlisting>
 
 	<para>See &man.mount.msdos.8; for a detailed description of the
 	  <option>-W</option> and <option>-L</option> options.</para>
       </sect3>
 
       <sect3>
 	<title>X11 Setup</title>
 
 	<orderedlist>
 	  <listitem>
 	    <para>Do <link linkend="setting-locale">non-X locale
 	      setup</link> first as described.</para>
 
 	    <note>
 	      <para><anchor id="russian-note">The Russian KOI8-R locale
 		may not work with old <application>XFree86</application> releases (lower than 3.3).
 		<application>XFree86 4.X</application> is now the default
 		version of the X Window System on FreeBSD.
 		This should not be an
 		issue unless you are using an old version of
 		FreeBSD.</para>
 	    </note>
 	  </listitem>
 
 	  <listitem>
 	    <para>Go to the
 	      <filename role="package">russian/X.language</filename> directory
 	      and issue the following command:</para>
 
 	    <screen>&prompt.root; <userinput>make install</userinput></screen>
       
 	    <para>The above port installs the latest version of the KOI8-R
 	      fonts.  <application>XFree86 3.3</application> already has some KOI8-R fonts, but these
 	      are scaled better.</para>
 
 	    <para>Check the <literal>"Files"</literal> section
 	      in your <filename>/etc/XF86Config</filename> file.
 	      The following
 	      lines must be added <emphasis>before</emphasis> any other
 	      <literal>FontPath</literal> entries:</para>
 
 	    <programlisting>FontPath   "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
 FontPath   "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
 FontPath   "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"</programlisting>
 
 	    <para>If you use a high resolution video mode, swap the 75 dpi
 	      and 100 dpi lines.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>To activate a Russian keyboard, add the following to the
 	      <literal>"Keyboard"</literal> section of your
 	      <filename>XF86Config</filename> file.</para>
 
 	    <para>For <application>XFree86 3.X</application>:</para>
 
 	    <programlisting>XkbLayout  "ru"
 XkbOptions "grp:caps_toggle"</programlisting>
 
 	    <para>For <application>XFree86 4.X</application>:</para>
 
 	    <programlisting>Option "XkbLayout"   "ru"
 Option "XkbOptions"  "grp:caps_toggle"</programlisting>
 
 	    <para>Also make sure that <literal>XkbDisable</literal> is
 	      turned off (commented out) there.</para>
 
 	    <para>The RUS/LAT switch will be <keycap>CapsLock</keycap>.
 	    The old <keycap>CapsLock</keycap> function is still
 	    available via <keycombo action="simul"><keycap>Shift</keycap><keycap>CapsLock</keycap></keycombo> (in LAT mode
 	      only).</para>
 
 	    <para>If you have <quote>Windows</quote> keys on your keyboard,
 	      and notice that some non-alphabetical keys are mapped
 	      incorrectly in RUS mode, add the following line in your
 	      <filename>XF86Config</filename> file.</para>
 
 	    <para>For <application>XFree86 3.X</application>:</para>
 
 	<programlisting>XkbVariant "winkeys"</programlisting>
 
 	    <para>For <application>XFree86 4.X</application>:</para>
 
 	<programlisting>Option "XkbVariant" "winkeys"</programlisting>
 
 	    <note>
 	      <para>The Russian XKB keyboard may not work with old <application>XFree86</application>
 		versions, see the <link linkend="russian-note">above
 		note</link> for more information.  The Russian XKB
 		keyboard may also not work with non-localized
 		applications as well.  Minimally localized applications
 		should call a <function>XtSetLanguageProc (NULL, NULL,
 		NULL);</function> function early in the program.
 		See <ulink
 		url="http://koi8.pp.ru/xwin.html">
 		KOI8-R for X Window</ulink> for more instructions on
 		localizing X11 applications.</para>
 	    </note>
 	  </listitem>
 	</orderedlist>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Traditional Chinese Localization for Taiwan</title>
       <indexterm>
 	<primary>localization</primary>
 	<secondary>Traditional Chinese</secondary>
       </indexterm>
       <para>The FreeBSD-Taiwan Project has an I18N/L10N tutorial for
 	FreeBSD at <ulink url="http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/">http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/</ulink>
 	using many Chinese ports.
 	The editor for the <literal>zh-L10N-tut</literal> is Clive Lin
 	<email>Clive@CirX.org</email>.  You can also cvsup the following
 	collections at <hostid
 	role="fqdn">freebsd.sinica.edu.tw</hostid>:</para>
 
       <informaltable frame="none">
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Collection</entry>
 	      <entry>Description</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>outta-port tag=.</entry>
 	      <entry>Beta-quality ports collection for Chinese</entry>
 	    </row>
 
 	    <row>
 	      <entry>zh-L10N-tut tag=.</entry>
 	      <entry>Localizing FreeBSD Tutorial in BIG-5 Traditional
 		Chinese</entry>
 	    </row>
 
 	    <row>
 	      <entry>zh-doc tag=.</entry>
 	      <entry>FreeBSD Documentation Translation to BIG-5 Traditional
 		Chinese</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>Chuan-Hsing Shen <email>s874070@mail.yzu.edu.tw</email> has
 	created the <ulink url="http://cnpa.yzu.edu.tw/~cfc/">Chinese
 	FreeBSD Collection (CFC)</ulink> using FreeBSD-Taiwan's
 	<literal>zh-L10N-tut</literal>.  The packages and the script files
 	are available at <ulink url="ftp://ftp.csie.ncu.edu.tw/OS/FreeBSD/taiwan/CFC/">ftp://ftp.csie.ncu.edu.tw/OS/FreeBSD/taiwan/CFC/</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>German Language Localization (For All ISO 8859-1
 	Languages)</title>
       <indexterm>
 	<primary>localization</primary>
 	<secondary>German</secondary>
       </indexterm>
 
       <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a
 	tutorial how to use umlauts on a FreeBSD machine.  The tutorial
 	is written in German and available at <ulink
 	url="http://www.de.FreeBSD.org/de/umlaute/">http://www.de.FreeBSD.org/de/umlaute/</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>Japanese and Korean Language Localization</title>
       <indexterm>
 	<primary>localization</primary>
 	<secondary>Japanese</secondary>
       </indexterm>
       <indexterm>
 	<primary>localization</primary>
 	<secondary>Korean</secondary>
       </indexterm>
       <para>For Japanese, refer to <ulink
 	url="http://www.jp.FreeBSD.org/">http://www.jp.FreeBSD.org/</ulink>,
 	and for Korean, refer to <ulink
 	url="http://www.kr.FreeBSD.org/">http://www.kr.FreeBSD.org/</ulink>.</para>
     </sect2>
 
     <sect2>
       <title>Non-English FreeBSD Documentation</title>
 
       <para>Some FreeBSD contributors have translated parts of FreeBSD to
 	other languages.  They are available through links on the <ulink
 	url="../../../../index.html">main site</ulink> or in
 	<filename>/usr/share/doc</filename>.</para>
     </sect2>
   </sect1>
 </chapter>
diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
index db30c88783..6e05b5aa4e 100644
--- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
@@ -1,3097 +1,3097 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="linuxemu">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured and parts updated by </contrib>
       </author>
       <!-- 22 Mar 2000 -->
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Brian N.</firstname>
 	<surname>Handy</surname>
 	<contrib>Originally contributed by </contrib>
       </author>
       <author>
 	<firstname>Rich</firstname>
 	<surname>Murphey</surname>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Linux Binary Compatibility</title>
 
-  <sect1>
+  <sect1 id="linuxemu-synopsis">
     <title>Synopsis</title>
     <indexterm><primary>Linux binary compatibility</primary></indexterm>
     <indexterm>
       <primary>binary compatibility</primary>
       <secondary>Linux</secondary>
     </indexterm>
 
     <para>FreeBSD provides binary compatibility with several other
       Unix-like operating systems, including Linux.  At this point,
       you may be asking yourself why exactly, does
       FreeBSD need to be able to run Linux binaries?  The answer to that
       question is quite simple.  Many companies and developers develop
       only for Linux, since it is the latest <quote>hot thing</quote> in
       the computing world.  That leaves the rest of us FreeBSD users
       bugging these same companies and developers to put out native
       FreeBSD versions of their applications.  The problem is, that most
       of these companies do not really realize how many people would use
       their product if there were FreeBSD versions too, and most continue
       to only develop for Linux.  So what is a FreeBSD user to do?  This
       is where the Linux binary compatibility of FreeBSD comes into
       play.</para>
 
     <para>In a nutshell, the compatibility allows FreeBSD users to run
       about 90% of all Linux applications without modification.  This
       includes applications such as <application>Star Office</application>,
       the Linux version of <application>Netscape</application>,
       <application>Adobe Acrobat</application>,
       <application>RealPlayer</application>
       5 and 7, <application>VMWare</application>,
       <application>Oracle</application>,
       <application>WordPerfect</application>, <application>Doom</application>,
       <application>Quake</application>, and more.  It is also reported
       that in some situations, Linux binaries perform better on FreeBSD
       than they do under Linux.</para>
     <indexterm>
       <primary>Linux</primary>
       <secondary><filename>/proc</filename> filesystem</secondary>
     </indexterm>
 
     <para>There are, however, some Linux-specific operating system
       features that are not supported under FreeBSD.  Linux binaries will
       not work on FreeBSD if they overly use the Linux
       <filename>/proc</filename> filesystem (which is different from
       FreeBSD's <filename>/proc</filename> filesystem), or i386-specific
       calls, such as enabling virtual 8086 mode.</para>
 
     <para>After reading this chapter, you will know:</para>
     <itemizedlist>
       <listitem>
 	<para>How to enable Linux binary compatibility on your system.</para>
       </listitem>
 
       <listitem>
 	<para>How to install additional Linux shared
 	  libraries.</para>
 	</listitem>
 
       <listitem>
 	<para>How to install Linux applications on your FreeBSD system.</para>
       </listitem>
 
       <listitem>
 	<para>The implementation details of Linux compatibility in FreeBSD.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Know how to install additional third-party
         software (<xref linkend="ports">).</para>
       </listitem>
     </itemizedlist>
 
   </sect1>
 
   <sect1 id="linuxemu-lbc-install">
     <title>Installation</title>
 
     <indexterm><primary>KLD (kernel loadable object)</primary></indexterm>
 
     <para>Linux binary compatibility is not turned on by default.  The
       easiest way to enable this functionality is to load the
       <literal>linux</literal> KLD object (<quote>Kernel LoaDable
       object</quote>).  You can load this module by simply typing
       <command>linux</command> at the command prompt.</para>
 
     <para>If you would like Linux compatibility to always be enabled,
       then you should add the following line to
       <filename>/etc/rc.conf</filename>:</para>
 
     <programlisting>linux_enable="YES"</programlisting>
 
     <para>The &man.kldstat.8; command can be used to verify that the
       KLD is loaded:</para>
 
     <screen>&prompt.user; <userinput>kldstat</userinput>
 Id Refs Address    Size     Name
  1    2 0xc0100000 16bdb8   kernel
  7    1 0xc24db000 d000     linux.ko</screen>
     <indexterm>
       <primary>kernel options</primary>
       <secondary>LINUX</secondary>
     </indexterm>
 
     <para>If for some reason you do not want to or cannot load the KLD,
       then you may statically link Linux binary compatibility into the kernel
       by adding <literal>options LINUX</literal> to your kernel
       configuration file.  Then install your new kernel as described in
       <xref linkend="kernelconfig">.</para>
 
     <sect2>
       <title>Installing Linux Runtime Libraries</title>
       <indexterm>
 	<primary>Linux</primary>
 	<secondary>installing Linux libraries</secondary>
       </indexterm>
 
       <para>This can be done one of two ways, either by using the
 	<link linkend="linuxemu-libs-port">linux_base</link> port, or
 	by installing them <link
 	linkend="linuxemu-libs-manually">manually</link>.</para>
 
       <sect3 id="linuxemu-libs-port">
 	<title>Installing Using the linux_base Port</title>
 	<indexterm><primary>ports collection</primary></indexterm>
 
 	<para>This is by far the easiest method to use when installing the
 	  runtime libraries.  It is just like installing any other port
 	  from the <ulink url="file://localhost/usr/ports/">ports collection</ulink>.
 	  Simply do the following:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput>
 &prompt.root; <userinput>make install distclean</userinput></screen>
 
 	<para>You should now have working Linux binary compatibility.
 	  Some programs may complain about incorrect minor versions of the
 	  system libraries.  In general, however, this does not seem to be
 	  a problem.</para>
       </sect3>
 
       <sect3 id="linuxemu-libs-manually">
 	<title>Installing Libraries Manually</title>
 
 	<para>If you do not have the <quote>ports</quote> collection
 	  installed, you can install the libraries by hand instead.  You
 	  will need the Linux shared libraries that the program depends on
 	  and the runtime linker.  Also, you will need to create a
 	  <quote>shadow root</quote> directory,
 	  <filename>/compat/linux</filename>, for Linux libraries on your
 	  FreeBSD system.  Any shared libraries opened by Linux programs
 	  run under FreeBSD will look in this tree first.  So, if a Linux
 	  program loads, for example, <filename>/lib/libc.so</filename>,
 	  FreeBSD will first try to open
 	  <filename>/compat/linux/lib/libc.so</filename>, and if that does
 	  not exist, it will then try <filename>/lib/libc.so</filename>.
 	  Shared libraries should be installed in the shadow tree
 	  <filename>/compat/linux/lib</filename> rather than the paths
 	  that the Linux <command>ld.so</command> reports.</para>
 
 	<para>Generally, you will need to look for the shared libraries
 	  that Linux binaries depend on only the first few times that you
 	  install a Linux program on your FreeBSD system.  After a while,
 	  you will have a sufficient set of Linux shared libraries on your
 	  system to be able to run newly imported Linux binaries without
 	  any extra work.</para>
       </sect3>
 
       <sect3>
 	<title>How to Install Additional Shared Libraries</title>
 	<indexterm><primary>shared libraries</primary></indexterm>
 
 	<para>What if you install the <filename>linux_base</filename> port
 	  and your application still complains about missing shared
 	  libraries?  How do you know which shared libraries Linux
 	  binaries need, and where to get them?  Basically, there are 2
 	  possibilities (when following these instructions you will need
 	  to be <username>root</username> on your FreeBSD system).</para>
 
 	<para>If you have access to a Linux system, see what shared
 	  libraries the application needs, and copy them to your FreeBSD
 	  system.  Look at the following example:</para>
 
 	<informalexample>
 	  <para>Let us assume you used FTP to get the Linux binary of
 	    <application>Doom</application>, and put it on a Linux system you have access to.  You
 	    then can check which shared libraries it needs by running
 	    <command>ldd linuxdoom</command>, like so:</para>
 
 	  <screen>&prompt.user; <userinput>ldd linuxdoom</userinput>
 libXt.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libXt.so.3.1.0
 libX11.so.3 (DLL Jump 3.1) =&gt; /usr/X11/lib/libX11.so.3.1.0
 libc.so.4 (DLL Jump 4.5pl26) =&gt; /lib/libc.so.4.6.29</screen>
 
 	  <indexterm><primary>symbolic links</primary></indexterm>
 	  <para>You would need to get all the files from the last column,
 	    and put them under <filename>/compat/linux</filename>, with
 	    the names in the first column as symbolic links pointing to
 	    them.  This means you eventually have these files on your
 	    FreeBSD system:</para>
 
 	  <screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0
 /compat/linux/usr/X11/lib/libXt.so.3 -&gt; libXt.so.3.1.0
 /compat/linux/usr/X11/lib/libX11.so.3.1.0
 /compat/linux/usr/X11/lib/libX11.so.3 -&gt; libX11.so.3.1.0
 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
 
 	  <blockquote>
 	    <note>
 	      <para>Note that if you already have a Linux shared library
 		with a matching major revision number to the first column
 		of the <command>ldd</command> output, you will not need to
 		copy the file named in the last column to your system, the
 		one you already have should work.  It is advisable to copy
 		the shared library anyway if it is a newer version,
 		though.  You can remove the old one, as long as you make
 		the symbolic link point to the new one.  So, if you have
 		these libraries on your system:</para>
 
 	      <screen>/compat/linux/lib/libc.so.4.6.27
 /compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.27</screen>
 
 	      <para>and you find a new binary that claims to require a
 		later version according to the output of
 		<command>ldd</command>:</para>
 
 	      <screen>libc.so.4 (DLL Jump 4.5pl26) -&gt; libc.so.4.6.29</screen>
 
 	      <para>If it is only one or two versions out of date in the
 		in the trailing digit then do not worry about copying
 		<filename>/lib/libc.so.4.6.29</filename> too, because the
 		program should work fine with the slightly older version.
 		However, if you like, you can decide to replace the
 		<filename>libc.so</filename> anyway, and that should leave
 		you with:</para>
 
 	      <screen>/compat/linux/lib/libc.so.4.6.29
 /compat/linux/lib/libc.so.4 -&gt; libc.so.4.6.29</screen>
 	    </note>
 	  </blockquote>
 
 	  <blockquote>
 	    <note>
 	      <para>The symbolic link mechanism is
 		<emphasis>only</emphasis> needed for Linux binaries.  The
 		FreeBSD runtime linker takes care of looking for matching
 		major revision numbers itself and you do not need to worry
 		about it.</para>
 	    </note>
 	  </blockquote>
 	</informalexample>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Installing Linux ELF Binaries</title>
       <indexterm>
 	<primary>Linux</primary>
 	<secondary>ELF binaries</secondary>
       </indexterm>
 
       <para>ELF binaries sometimes require an extra step of
 	<quote>branding</quote>.  If you attempt to run an unbranded ELF
 	binary, you will get an error message like the following:</para>
 
       <screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput>
 ELF binary type not known
 Abort</screen>
 
       <para>To help the FreeBSD kernel distinguish between a FreeBSD ELF
 	binary from a Linux binary, use the &man.brandelf.1;
 	utility.</para>
 
       <screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen>
 
       <indexterm><primary>GNU toolchain</primary></indexterm>
       <para>The GNU toolchain now places the appropriate branding
 	information into ELF binaries automatically, so this step
 	should become increasingly more rare in the future.</para>
     </sect2>
 
     <sect2>
       <title>Configuring the Hostname Resolver</title>
 
       <para>If DNS does not work or you get this message:</para>
 
       <screen>resolv+: "bind" is an invalid keyword resolv+:
 "hosts" is an invalid keyword</screen>
 
       <para>You will need to configure a
 	<filename>/compat/linux/etc/host.conf</filename> file
 	containing:</para>
 
       <programlisting>order hosts, bind
 multi on</programlisting>
 
       <para>The order here specifies that <filename>/etc/hosts</filename>
 	is searched first and DNS is searched second.  When
 	<filename>/compat/linux/etc/host.conf</filename> is not
 	installed, Linux applications find FreeBSD's
 	<filename>/etc/host.conf</filename> and complain about the
 	incompatible FreeBSD syntax.  You should remove
 	<literal>bind</literal> if you have not configured a name server
 	using the <filename>/etc/resolv.conf</filename> file.</para>
     </sect2>
   </sect1>
 
   <sect1 id="linuxemu-mathematica">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Murray</firstname>
 	  <surname>Stokely</surname>
 	  <contrib>Updated for Mathematica 4.X by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Bojan</firstname>
 	  <surname>Bistrovic</surname>
 	  <contrib>Merged with work by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Installing Mathematica</title>
 
     <indexterm>
       <primary>applications</primary>
       <secondary><application>Mathematica</application></secondary>
     </indexterm>
 
     <para>This document describes the process of installing the Linux
       version of <application>Mathematica 4.X</application> onto
       a FreeBSD system.</para>
 
     <para>The Linux version of <application>Mathematica</application>
       runs perfectly under FreeBSD
       however the binaries shipped by Wolfram need to be branded so that
       FreeBSD knows to use the Linux ABI to execute them.</para>
 
     <para>The Linux version of <application>Mathematica</application>
       or <application>Mathematica for Students</application> can
       be ordered directly from Wolfram at <ulink
       url="http://www.wolfram.com/">http://www.wolfram.com/</ulink>.</para>
 
     <sect2>
       <title>Branding the Linux Binaries</title>
 
       <para>The Linux binaries are located in the <filename>Unix</filename>
 	directory of the <application>Mathematica</application> CDROM
 	distributed by Wolfram.  You
 	need to copy this directory tree to your local hard drive so that
 	you can brand the Linux binaries with &man.brandelf.1; before
 	running the installer:</para>
 
       <screen>&prompt.root; <userinput>mount /cdrom</userinput>
 &prompt.root; <userinput>cp -rp /cdrom/Unix/ /localdir/</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/*</userinput>
 &prompt.root; <userinput>brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm</userinput>
 &prompt.root; <userinput>cd /localdir/Installers/Linux/</userinput>
 &prompt.root; <userinput>./MathInstaller</userinput></screen>
 
       <para>Alternatively, you can simply set the default ELF brand
 	to Linux for all unbranded binaries with the command:</para>
       <screen>&prompt.root; <userinput>sysctl kern.fallback_elf_brand=3</userinput></screen>
       <para>This will make FreeBSD assume that unbranded ELF binaries
 	use the Linux ABI and so you should be able to run the
 	installer straight from the CDROM.</para>
     </sect2>
 
     <sect2>
       <title>Obtaining Your Mathematica Password</title>
 
       <para>Before you can run <application>Mathematica</application>
 	you will have to obtain a
 	password from Wolfram that corresponds to your <quote>machine
 	ID</quote>.</para>
       <indexterm>
 	<primary>Ethernet</primary>
 	<secondary>MAC address</secondary>
       </indexterm>
 
       <para>Once you have installed the Linux compatibility runtime
 	libraries and unpacked <application>Mathematica</application>
 	you can obtain the
 	<quote>machine ID</quote> by running the program
 	<command>mathinfo</command> in the Install directory.  This
 	machine ID is based solely on the MAC address of your first
 	Ethernet card.</para>
 
       <screen>&prompt.root; <userinput>cd /localdir/Files/SystemFiles/Installation/Binaries/Linux</userinput>
 &prompt.root; <userinput>mathinfo</userinput>
 disco.example.com 7115-70839-20412</screen>
 
       <para>When you register with Wolfram, either by email, phone or fax,
 	you will give them the <quote>machine ID</quote> and they will
 	respond with a corresponding password consisting of groups of
 	numbers.  You can then enter this information when you attempt to
 	run <application>Mathematica</application> for the first time
 	exactly as you would for any other
 	<application>Mathematica</application> platform.</para>
     </sect2>
 
     <sect2>
       <title>Running the Mathematica Frontend over a Network</title>
 
       <para><application>Mathematica</application> uses some special
 	fonts to display characters not
 	present in any of the standard font sets (integrals, sums, Greek
 	letters, etc.).  The X protocol requires these fonts to be install
 	<emphasis>locally</emphasis>.  This means you will have to copy
 	these fonts from the CDROM or from a host with
 	<application>Mathematica</application>
 	installed to your local machine.  These fonts are normally stored
 	in <filename>/cdrom/Unix/Files/SystemFiles/Fonts</filename> on the
 	CDROM, or
 	<filename>/usr/local/mathematica/SystemFiles/Fonts</filename> on
 	your hard drive.  The actual fonts are in the subdirectories
 	<filename>Type1</filename> and <filename>X</filename>.  There are
 	several ways to use them, as described below.</para>
 
       <para>The first way is to copy them into one of the existing font
 	directories in <filename>/usr/X11R6/lib/X11/fonts</filename>.
 	This will require editing the <filename>fonts.dir</filename> file,
 	adding the font names to it, and changing the number of fonts on
 	the first line.  Alternatively, you should also just be able to
 	run <command>mkfontdir</command> in the directory you have copied
 	them to.</para>
 
       <para>The second way to do this is to copy the directories to
 	<filename>/usr/X11R6/lib/X11/fonts</filename>:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts</userinput>
 &prompt.root; <userinput>mkdir X</userinput>
 &prompt.root; <userinput>mkdir MathType1</userinput>
 &prompt.root; <userinput>cd /cdrom/Unix/Files/SystemFiles/Fonts</userinput>
 &prompt.root; <userinput>cp X/* /usr/X11R6/lib/X11/fonts/X</userinput>
 &prompt.root; <userinput>cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1</userinput>
 &prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/X</userinput>
 &prompt.root; <userinput>mkfontdir</userinput>
 &prompt.root; <userinput>cd ../MathType1</userinput>
 &prompt.root; <userinput>mkfontdir</userinput></screen>
 
       <para>Now add the new font directories to your font path:</para>
 
       <screen>&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/X</userinput>
 &prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/MathType1</userinput>
 &prompt.root; <userinput>xset fp rehash</userinput></screen>
 
       <para>If you are using the XFree86 server, you can have these font
 	directories loaded automatically by adding them to your
 	<filename>XF86Config</filename> file.</para>
       <indexterm><primary>fonts</primary></indexterm>
 
       <para>If you <emphasis>do not</emphasis> already have a directory
 	called <filename>/usr/X11R6/lib/X11/fonts/Type1</filename>, you
 	can change the name of the <filename>MathType1</filename>
 	directory in the example above to
 	<filename>Type1</filename>.</para>
     </sect2>
   </sect1>
 
   <sect1 id="linuxemu-maple">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Aaron</firstname>
 	  <surname>Kaplan</surname>
 <!--	  <address><email>aaron@lo-res.org</email></address>-->
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Robert</firstname>
 	  <surname>Getschmann</surname>
 <!--	  <address><email>rob@getschmann.org</email></address>-->
 	  <contrib>Thanks to </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <title>Installing Maple</title>
 
     <indexterm>
       <primary>applications</primary>
       <secondary><application>Maple</application></secondary>
     </indexterm>
 
     <para>Maple is a commercial mathematics program similar to
       Mathematica.  You must purchase this software from <ulink
       url="http://www.maplesoft.com/"></ulink> and then register there
       for a license file.  To install this software on FreeBSD, please
       follow these simple steps.</para>
 
       <procedure>
 	<step><para>Execute the <filename>INSTALL</filename> shell
 	  script from the product distribution.  Choose the
 	  <quote>RedHat</quote> option when prompted by the
 	  installation program.  A typical installation directory
 	  might be <filename
 	  class="directory">/usr/local/maple</filename>.</para></step>
 
         <step><para>If you have not done so, order a license for Maple
 	  from Maple Waterloo Software (http://register.maplesoft.com)
 	  and copy it to
 	  <filename>/usr/local/maple/license/license.dat</filename>.</para></step>
 
         <step><para>Install the <application>FLEXlm</application>
 	  license manager by running the
 	  <filename>INSTALL_LIC</filename> install shell script that
 	  comes with <application>Maple</application>.  Specify the
 	  primary hostname for your machine for the license
 	  server.</para></step>
 
         <step><para>Patch the
           <filename>usr/local/maple/bin/maple.system.type</filename>
           file with the following:</para>
 <programlisting>   ----- snip ------------------
 *** maple.system.type.orig      Sun Jul  8 16:35:33 2001
 --- maple.system.type   Sun Jul  8 16:35:51 2001
 ***************
 *** 72,77 ****
 --- 72,78 ----
           # the IBM RS/6000 AIX case
           MAPLE_BIN="bin.IBM_RISC_UNIX"
           ;;
 +     "FreeBSD"|\
       "Linux")
           # the Linux/x86 case
         # We have two Linux implementations, one for Red Hat and
    ----- snip end of patch -----</programlisting>
 
 	<para>Please note that after the <literal>"FreeBSD"|\</literal> no other
 	  whitespace should be present.</para>
 
 	<para>This patch instructs <application>Maple</application> to
 	  recognize <quote>FreeBSD</quote> as a type of Linux system.
 	  The <filename>bin/maple</filename> shell script calls the
 	  <filename>bin/maple.system.type</filename> shell script
 	  which in turn calls uname -a to find out the operating
 	  system name. Depending on the OS name it will find out which
 	  binaries to use.</para></step>
 
       <step><para>Start the license server.</para>
 
 	<para>The following script, installed as
 	  <filename>/usr/local/etc/rc.d/lmgrd.sh</filename> is a
 	  convenient way to start up <command>lmgrd</command>:</para>
 
 	<programlisting>   ----- snip ------------
 
 #! /bin/sh
 PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin
 PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX
 export PATH
 
 LICENSE_FILE=/usr/local/maple/license/license.dat
 LOG=/var/log/lmgrd.log
 
 case "$1" in
 start)
 	lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2
 	echo -n " lmgrd"
 	;;
 stop)
 	lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2
 	;;
 *)
 	echo "Usage: `basename $0` {start|stop}" 1>&2
 	exit 64
 	;;
 esac
 
 exit 0
    ----- snip ------------</programlisting></step>
 
 
       <step><para>Test-start maple:</para>
 	<screen>&prompt.user; <userinput>cd /usr/local/maple/bin</userinput>
 &prompt.user; <userinput>./xmaple</userinput></screen>
 
 	<para>You should be up and running. Make sure to write
 	  Maplesoft to let them know you would like a native FreeBSD
 	  version!</para></step>
     </procedure>
 
     <sect2>
       <title>Common Pitfalls</title>
 
       <itemizedlist>
 	<listitem><para>The FLEXlm license manager can be a difficult
 	  tool to work with.  Additional documentation on the subject
 	  can be found at <ulink
 	  url="http://www.globetrotter.com/"></ulink>.</para></listitem>
 
 	<listitem><para><command>lmgrd</command> is known to be very picky
 	  about the license file and to core dump if there are any
 	  problems.  A correct license file should look like this:</para>
 
 <programlisting># =======================================================
 # License File for UNIX Installations ("Pointer File")
 # =======================================================
 SERVER chillig ANY
 #USE_SERVER
 VENDOR maplelmg
 
 FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \
          PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \
          ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \
          SN=XXXXXXXXX</programlisting>
 
 	  <note><para>Serial number and key 'X''ed out. <hostid>chillig</hostid> is a
 	    hostname.</para></note>
 
   	  <para>Editing the license file works as long as you do not
  	    touch the <quote>FEATURE</quote> line (which is protected by the
  	    license key).</para></listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="linuxemu-oracle">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Marcel</firstname>
 	  <surname>Moolenaar</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<!-- marcel@cup.hp.com -->
       </authorgroup>
     </sect1info>
     <title>Installing Oracle</title>
 
     <indexterm>
       <primary>applications</primary>
       <secondary><application>Oracle</application></secondary>
     </indexterm>
 
     <sect2>
       <title>Preface</title>
       <para>This document describes the process of installing Oracle 8.0.5 and
 	Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD
 	machine.</para>
     </sect2>
 
     <sect2>
       <title>Installing the Linux Environment</title>
 
       <para>Make sure you have both <filename>linux_base</filename> and
 	<filename>linux_devtools</filename> from the ports collection
 	installed.  These ports are added to the collection after the release
 	of FreeBSD&nbsp;3.2.  If you are using FreeBSD&nbsp;3.2 or an older version for
 	that matter, update your ports collection.  You may want to consider
 	updating your FreeBSD version too.  If you run into difficulties with
 	<filename>linux_base-6.1</filename> or
 	<filename>linux_devtools-6.1</filename> you may have to use version
 	5.2 of these packages.</para>
 
       <para>If you want to run the intelligent agent, you will
 	also need to install the Red Hat Tcl package:
 	<filename>tcl-8.0.3-20.i386.rpm</filename>.  The general command
 	for installing packages with the official RPM port is:</para>
 
       <screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen>
 
       <para>Installation of the package should not generate any errors.</para>
     </sect2>
 
     <sect2>
       <title>Creating the Oracle Environment</title>
 
       <para>Before you can install Oracle, you need to set up a proper
 	environment.  This document only describes what to do
 	<emphasis>specially</emphasis> to run Oracle for Linux on FreeBSD, not
 	what has been described in the Oracle installation guide.</para>
 
       <sect3 id="linuxemu-kernel-tuning">
         <title>Kernel Tuning</title>
 	<indexterm><primary>kernel tuning</primary></indexterm>
 
 	<para>As described in the Oracle installation guide, you need to set
 	  the maximum size of shared memory.  Do not use
 	  <literal>SHMMAX</literal> under FreeBSD. <literal>SHMMAX</literal>
 	  is merely calculated out of <literal>SHMMAXPGS</literal> and
 	  <literal>PGSIZE</literal>.  Therefore define
 	  <literal>SHMMAXPGS</literal>.  All other options can be used as
 	  described in the guide.  For example:</para>
 
 	<programlisting>options SHMMAXPGS=10000
 options SHMMNI=100
 options SHMSEG=10
 options SEMMNS=200
 options SEMMNI=70
 options SEMMSL=61</programlisting>
 
 	<para>Set these options to suit your intended use of Oracle.</para>
 
 	<para>Also, make sure you have the following options in your kernel
 	  config-file:</para>
 
 <programlisting>options SYSVSHM #SysV shared memory
 options SYSVSEM #SysV semaphores
 options SYSVMSG #SysV interprocess communication</programlisting>
       </sect3>
 
       <sect3 id="linuxemu-oracle-account">
 
         <title>Oracle Account</title>
 
 	<para>Create an Oracle account just as you would create any other
 	  account. The  Oracle account is special only that you need to give
 	  it a Linux shell.  Add <literal>/compat/linux/bin/bash</literal> to
 	  <filename>/etc/shells</filename> and set the shell for the Oracle
 	  account to <filename>/compat/linux/bin/bash</filename>.</para>
       </sect3>
 
       <sect3 id="linuxemu-environment">
         <title>Environment</title>
 
 	<para>Besides the normal Oracle variables, such as
 	  <envar>ORACLE_HOME</envar> and <envar>ORACLE_SID</envar> you must
 	  set the following environment variables:</para>
 
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Variable</entry>
 
 		<entry>Value</entry>
 	      </row>
 	    </thead>
 	    <tbody>
 	      <row>
 		<entry><envar>LD_LIBRARY_PATH</envar></entry>
 
 		<entry><literal>$ORACLE_HOME/lib</literal></entry>
 	      </row>
 
 	      <row>
 		<entry><envar>CLASSPATH</envar></entry>
 
 		<entry><literal>$ORACLE_HOME/jdbc/lib/classes111.zip</literal></entry>
 	      </row>
 
 	      <row>
 		<entry><envar>PATH</envar></entry>
 
 		<entry><literal>/compat/linux/bin
 /compat/linux/sbin
 /compat/linux/usr/bin
 /compat/linux/usr/sbin
 /bin
 /sbin
 /usr/bin
 /usr/sbin
 /usr/local/bin
 $ORACLE_HOME/bin</literal></entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
         <para>It is advised to set all the environment variables in
 	  <filename>.profile</filename>.  A complete example is:</para>
 
 <programlisting>ORACLE_BASE=/oracle; export ORACLE_BASE
 ORACLE_HOME=/oracle; export ORACLE_HOME
 LD_LIBRARY_PATH=$ORACLE_HOME/lib
 export LD_LIBRARY_PATH
 ORACLE_SID=ORCL; export ORACLE_SID
 ORACLE_TERM=386x; export ORACLE_TERM
 CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
 export CLASSPATH
 PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin
 PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
 PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
 export PATH</programlisting>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Installing Oracle</title>
 
       <para>Due to a slight inconsistency in the Linux emulator, you need to
 	create a directory named <filename>.oracle</filename> in
 	<filename>/var/tmp</filename> before you start the installer.  Either
 	make it world writable or let it be owner by the oracle user.  You
 	should be able to install Oracle without any problems.  If you have
 	problems, check your Oracle distribution and/or configuration first!
 	After you have installed Oracle, apply the patches described in the
 	next two subsections.</para>
 
       <para>A frequent problem is that the TCP protocol adapter is not
 	installed right. As a consequence, you cannot start any TCP listeners.
 	The following actions help solve this problem:</para>
 
       <screen>&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
 &prompt.root; <userinput>make -f ins_network.mk ntcontab.o</userinput>
 &prompt.root; <userinput>cd $ORACLE_HOME/lib</userinput>
 &prompt.root; <userinput>ar r libnetwork.a ntcontab.o</userinput>
 &prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput>
 &prompt.root; <userinput>make -f ins_network.mk install</userinput></screen>
 
       <para>Do not forget to run <filename>root.sh</filename> again!</para>
 
     <sect3 id="linuxemu-patch-root">
       <title>Patching root.sh</title>
 
 	<para>When installing Oracle, some actions, which need to be performed
 	  as <username>root</username>, are recorded in a shell script called
 	  <filename>root.sh</filename>.  <filename>root.sh</filename> is
 	  written in the <filename>orainst</filename> directory.  Apply the
 	  following patch to root.sh, to have it use to proper location of
 	  <command>chown</command> or alternatively run the script under a
 	  Linux native shell.</para>
 
 	<programlisting>*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
 --- orainst/root.sh Mon Dec 28 15:58:53 1998
 ***************
 *** 31,37 ****
 # This is the default value for CHOWN
 # It will redefined later in this script for those ports
 # which have it conditionally defined in ss_install.h
 ! CHOWN=/bin/chown
 #
 # Define variables to be used in this script
 --- 31,37 ----
 # This is the default value for CHOWN
 # It will redefined later in this script for those ports
 # which have it conditionally defined in ss_install.h
 ! CHOWN=/usr/sbin/chown
 #
 # Define variables to be used in this script</programlisting>
 
 	<para>When you do not install Oracle from CD, you can patch the source
 	  for <filename>root.sh</filename>.  It is called
 	  <filename>rthd.sh</filename> and is located in the
 	  <filename>orainst</filename> directory in the source tree.</para>
       </sect3>
 
       <sect3 id="linuxemu-patch-tcl">
 	<title>Patching genclntsh</title>
 
 	<para>The script <command>genclntsh</command> is used to create
 	  a single shared client
 	  library.  It is used when building the demos.  Apply the following
 	  patch to comment out the definition of PATH:</para>
 
 	<programlisting>*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
 --- bin/genclntsh Tue Dec 22 15:36:49 1998
 ***************
 *** 32,38 ****
 #
 # Explicit path to ensure that we're using the correct commands
 #PATH=/usr/bin:/usr/ccs/bin export PATH
 ! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
 #
 # each product MUST provide a $PRODUCT/admin/shrept.lst
 --- 32,38 ----
 #
 # Explicit path to ensure that we're using the correct commands
 #PATH=/usr/bin:/usr/ccs/bin export PATH
 ! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
 #
 # each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Running Oracle</title>
 
       <para>When you have followed the instructions, you should be able to run
 	<application>Oracle</application> as if it was run on Linux
 	itself.</para>
     </sect2>
   </sect1>
 
   <sect1 id="sapr3">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Holger</firstname>
 	  <surname>Kipp</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
       <!-- holger.kipp@alogis.com -->
       <authorgroup>
 	<author>
 	  <firstname>Valentino</firstname>
 	  <surname>Vaschetto</surname>
 	  <contrib>Original version converted to SGML by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title>Installing SAP R/3</title>
 
     <indexterm>
       <primary>applications</primary>
       <secondary><application>SAP R/3</application></secondary>
     </indexterm>
 
     <para>Installations of SAP Systems using FreeBSD will not be
       supported by the SAP support team &mdash; they only offer support
       for certified platforms.</para>
 
     <sect2 id="preface">
       <title>Preface</title>
 
       <para>This document describes a possible way of installing a
 	<application>SAP R/3-System</application>
 	with <application>Oracle Database</application>
 	for Linux onto a FreeBSD machine, including the installation
 	of FreeBSD and <application>Oracle</application>. Two different
 	configurations will be described:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><application>SAP R/3 4.6B (IDES)</application> with
 	  <application>Oracle 8.0.5</application> on FreeBSD 4.3-STABLE</para>
 	</listitem>
 
 	<listitem>
 	  <para><application>SAP R/3 4.6C</application> with
 	  <application>Oracle 8.1.7</application> on FreeBSD 4.5-STABLE</para>
 	</listitem>
       </itemizedlist>
 
       <para>Even though this document tries to describe all important
         steps in a greater detail, it is not intended as a replacement
         for the <application>Oracle</application> and
 	<application>SAP R/3</application> installation guides.</para>
 
       <para>Please see the documentation that comes with the
 	<application>SAP R/3</application>
 	Linux edition for <application>SAP</application>- and
 	<application>Oracle</application>-specific questions, as well
 	as resources from <application>Oracle</application> and
 	<application>SAP OSS</application>.</para>
     </sect2>
 
     <sect2 id="software">
       <title>Software</title>
 
       <para>The following CD-ROMs have been used for SAP-installations:</para>
 
       <sect3 id="software-46b">
 	<title>SAP R/3 4.6B, Oracle 8.0.5</title>
 
       <informaltable>
 	<tgroup cols=3>
 	  <thead>
 	    <row>
 	      <entry>Name</entry> <entry>Number</entry> <entry>Description</entry>
 	    </row>
 	  </thead>
 	  <tbody>
 	    <row>
 	      <entry>KERNEL</entry> <entry>51009113</entry> <entry>SAP Kernel Oracle /
 		Installation / AIX, Linux, Solaris</entry>
 	    </row>
 
 	    <row>
 	      <entry>RDBMS</entry> <entry>51007558</entry> <entry>Oracle / RDBMS 8.0.5.X /
 		Linux</entry>
 	    </row>
 
 	    <row>
 	      <entry>EXPORT1</entry> <entry>51010208</entry> <entry>IDES / DB-Export /
 		Disc 1 of 6</entry>
 	    </row>
 
 	    <row>
 	      <entry>EXPORT2</entry> <entry>51010209</entry> <entry>IDES / DB-Export /
 		Disc 2 of 6</entry>
 	    </row>
 
 	    <row>
 	      <entry>EXPORT3</entry> <entry>51010210</entry> <entry>IDES / DB-Export /
 		Disc 3 of 6</entry>
 	    </row>
    
 	    <row>
 	      <entry>EXPORT4</entry> <entry>51010211</entry> <entry>IDES / DB-Export /
 		Disc 4 of 6</entry>
 	    </row>
 
 	    <row>
 	      <entry>EXPORT5</entry> <entry>51010212</entry> <entry>IDES / DB-Export /
 		Disc 5 of 6</entry>
 	    </row>
 
 	    <row>
 	      <entry>EXPORT6</entry> <entry>51010213</entry> <entry>IDES / DB-Export /
 		Disc 6 of 6</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>Additionally, I used the <application>Oracle 8
 	Server</application> (Pre-production version 8.0.5 for Linux,
 	Kernel Version 2.0.33) CD which is not really necessary, and
 	of course FreeBSD 4.3-STABLE (it was only a few days past 4.3
 	RELEASE).</para>
 
       </sect3>
       <sect3 id="software-46c">
 	<title>SAP R/3 4.6C SR2, Oracle 8.1.7</title>
 
 	<informaltable>
 	  <tgroup cols=3>
 	    <thead>
 	      <row>
 		<entry>Name</entry> <entry>Number</entry> <entry>Description</entry>
 	      </row>
 	    </thead>
 
 	    <tbody>
 	      <row>
 		<entry>KERNEL</entry> <entry>51014004</entry> <entry>SAP Kernel Oracle /
 		  SAP Kernel Version 4.6D / DEC, Linux</entry>
 	      </row>
 
 	      <row>
 		<entry>RDBMS</entry> <entry>51012930</entry> <entry>Oracle 8.1.7/ RDBMS /
 		  Linux</entry>
 	      </row>
 
 	      <row>
 		<entry>EXPORT1</entry> <entry>51013953</entry> <entry>Release 4.6C SR2 / Export
 		  / Disc 1 of 4</entry>
 	      </row>
 
 	      <row>
 		<entry>EXPORT1</entry> <entry>51013953</entry> <entry>Release 4.6C SR2 / Export
 		  / Disc 2 of 4</entry>
 	      </row>
 
 	      <row>
 		<entry>EXPORT1</entry> <entry>51013953</entry> <entry>Release 4.6C SR2 / Export
 		  / Disc 3 of 4</entry>
 	      </row>
 
 	      <row>
 		<entry>EXPORT1</entry> <entry>51013953</entry> <entry>Release 4.6C SR2 / Export
 		  / Disc 4 of 4</entry>
 	      </row>
 
 	      <row>
 		<entry>LANG1</entry> <entry>51013954</entry> <entry>Release 4.6C SR2 /
 		  Language / DE, EN, FR / Disc 1 of 3</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
         <para>Depending on the languages you would like to install, additional
 	  language CDs might be necessary. Here we're just using DE and EN, so
 	  the first Language-CD is the only one needed. As a little note, the
 	  numbers for all four export CDs are identical. All three language CDs
 	  also have the same number (this is different from the 4.6B IDES
 	  release CD numbering). At the time of writing this installation is
 	  running on FreeBSD 4.5-STABLE (20.03.2002).</para>
       </sect3>
     </sect2>
 
     <sect2 id="sap-notes">
       <title>SAP-Notes</title>
 
       <para>The following notes should be read before installing
 	<application>SAP R/3</application> or proved to be useful
 	during installation:</para>
 
       <sect3 id="sap-notes-46b">
 	<title>SAP R/3 4.6B, Oracle 8.0.5</title>
 
 	<informaltable>
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Number</entry>
 		<entry>Title</entry>
 	      </row>
 	    </thead>
 	    <tbody>
 
 	      <row>
 		<entry>0171356</entry> <entry>SAP Software on Linux: Essential
 		  Comments</entry>
 	      </row>
 
 	      <row>
 		<entry>0201147</entry> <entry>INST: 4.6C R/3 Inst. on UNIX -
 		  Oracle</entry>
 	      </row>
 
 	      <row>
 		<entry>0373203</entry> <entry>Update / Migration Oracle 8.0.5 --&gt;
 		  8.0.6/8.1.6 LINUX</entry>
 	      </row>
 
 	      <row>
 		<entry>0072984</entry> <entry>Release of Digital UNIX 4.0B for
 		  Oracle</entry>
 	      </row>
 
 	      <row>
 		<entry>0130581</entry> <entry>R3SETUP step DIPGNTAB terminates</entry>
 	      </row>
 
 	      <row>
 		<entry>0144978</entry> <entry>Your system has not been installed
 		  correctly</entry>
 	      </row>
 
 	      <row>
 		<entry>0162266</entry> <entry>Questions and tips for R3SETUP on Windows
 		  NT / W2K</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
       </sect3>
 
       <sect3 id="sap-notes-46c">
 	<title>SAP R/3 4.6C, Oracle 8.1.7</title>
 
 	<informaltable>
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Number</entry>
 		<entry>Title</entry>
 	      </row>
 	    </thead>
 	    <tbody>
 	      <row>
 		<entry>0015023</entry> <entry>Initializing table TCPDB (RSXP0004)
 		  (EBCDIC)</entry>
 	      </row>
 
 	      <row>
 		<entry>0045619</entry> <entry>R/3 with several languages or
 		  typefaces</entry>
 	      </row>
 
 	      <row>
 		<entry>0171356</entry> <entry>SAP Software on Linux: Essential
 		  Comments</entry>
 	      </row>
 
 	      <row>
 		<entry>0195603</entry> <entry>RedHat 6.1 Enterprise version:
 		  Known problems</entry>
 	      </row>
 
 	      <row>
 		<entry>0212876</entry> <entry>The new archiving tool SAPCAR</entry>
 	      </row>
 
 	      <row>
 		<entry>0300900</entry> <entry>Linux: Released DELL Hardware</entry>
 	      </row>
 
 	      <row>
 		<entry>0377187</entry> <entry>RedHat 6.2: important remarks</entry>
 	      </row>
 
 	      <row>
 		<entry>0387074</entry> <entry>INST: R/3 4.6C SR2 Installation on
 		  UNIX</entry>
 	      </row>
 
 	      <row>
 		<entry>0387077</entry> <entry>INST: R/3 4.6C SR2 Inst. on UNIX -
 		  Oracle</entry>
 	      </row>
 
 	      <row>
 		<entry>0387078</entry> <entry>SAP Software on UNIX: OS Dependencies
 		  4.6C SR2</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
       </sect3>
     </sect2>
 
     <sect2 id="hardware-requirements">
       <title>Hardware-Requirements</title>
 
       <para>The following equipment is sufficient for the installation
 	of a <application>SAP R/3 System</application>. For production
 	use, a more exact sizing is of course needed:</para>
 
       <informaltable>
 	<tgroup cols="3">
 	  <thead>
 	    <row>
 	      <entry>Component</entry>
 	      <entry>4.6B</entry>
 	      <entry>4.6C</entry>
 	    </row>
 	  </thead>
 	  <tbody>
 	    <row>
 	      <entry>Processor</entry>
 	      <entry>2 x 800MHz Pentium III</entry>
 	      <entry>2 x 800MHz Pentium III</entry>
 	    </row>
 
 	    <row>
 	      <entry>Memory</entry>
 	      <entry>1GB ECC</entry>
 	      <entry>2GB ECC</entry>
 	    </row>
 
 	    <row>
 	      <entry>Hard Disk Space</entry>
 	      <entry>50-60GB (IDES)</entry>
 	      <entry>50-60GB (IDES)</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </informaltable>
 
       <para>For use in production, Xeon-Processors with large cache,
 	high-speed disk access (SCSI, RAID hardware controller), USV
 	and ECC-RAM is recommended.  The large amount of hard disk
 	space is due to the preconfigured IDES System, which creates
 	27&nbsp;GB of database files during installation. This space is
 	also sufficient for initial production systems and application
 	data.</para>
 
       <sect3 id="hardware-46b">
 	<title>SAP R/3 4.6B, Oracle 8.0.5</title>
 
       <para>The following off-the-shelf hardware was used: a dual processor
 	board with 2 800&nbsp;MHz Pentium&nbsp;III processors, Adaptec 29160 Ultra160
 	SCSI adapter (for accessing a 40/80&nbsp;GB DLT tape drive and CDROM),
 	Mylex AcceleRAID (2 channels, firmware 6.00-1-00 with 32&nbsp;MB RAM).
 	To the Mylex Raid-controller are attached two 17&nbsp;GB hard disks
 	(mirrored) and four 36&nbsp;GB hard disks (RAID level 5).</para>
       </sect3>
 
       <sect3 id="hardware-46c">
 	<title>SAP R/3 4.6C, Oracle 8.1.7</title>
 
       <para>For this installation a DELL PowerEdge 2500 was used: a
 	dual processor board with two 1000&nbsp;MHz Pentium&nbsp;III processors
 	(256&nbsp;kB Cache), 2&nbsp;GB PC133 ECC SDRAM, PERC/3 DC PCI Raid Controller
 	with 128&nbsp;MB, and an EIDE DVD-ROM drive. To the RAID-controller are
 	attached two 18&nbsp;GB hard disks (mirrored) and four 36&nbsp;GB hard disks
 	(RAID level 5).</para>
       </sect3>
     </sect2>
 
     <sect2 id="installation">
       <title>Installation of FreeBSD</title>
 
       <para>First you have to install FreeBSD. There are several ways to do
 	this (FreeBSD&nbsp;4.3 was installed via FTP, FreeBSD&nbsp;4.5 directly from
 	release-CD).</para>
 
       <sect3 id="disk-layout">
 	<title>Disk Layout</title>
 
 	<para>To keep it simple, the same disk layout both for the
 	  <application>SAP R/3 46B</application>- and <application>SAP R/3 46C
 	  SR2</application>-installation was used. Only the device names
 	  changed, as the installations were on different hardware (<devicename>/dev/da</devicename>
 	  and <devicename>/dev/amr</devicename> respectively, so if using an AMI MegaRAID, one will see
 	  <devicename>/dev/amr0s1a</devicename> instead of <devicename>/dev/da0s1a</devicename>):</para>
 
 	<informaltable>
 	  <tgroup cols="4">
 	    <thead>
 	      <row>
 		<entry>Filesystem</entry>
 		<entry>Size (1k-blocks)</entry>
 		<entry>Size (GB)</entry>
 		<entry>Mounted on</entry>
 	      </row>
 	    </thead>
 	    <tbody>
 	      <row>
 		<entry><devicename>/dev/da0s1a</devicename></entry>
 		<entry>1.016.303</entry>
 		<entry>1</entry>
 		<entry><filename>/</filename></entry>
 	      </row>
 
 	      <row>
 		<entry><devicename>/dev/da0s1b</devicename></entry>
 		<entry> </entry>
 		<entry>6</entry>
 		<entry>swap</entry>
 	      </row>
 
 	      <row>
 		<entry><devicename>/dev/da0s1e</devicename></entry>
 		<entry>2.032.623</entry>
 		<entry>2</entry>
 		<entry><filename>/var</filename></entry>
 	      </row>
 
 	      <row>
 		<entry><devicename>/dev/da0s1f</devicename></entry>
 		<entry>8.205.339</entry>
 		<entry>8</entry>
 		<entry><filename>/usr</filename></entry>
 	      </row>
 
 	      <row>
 		<entry><devicename>/dev/da1s1e</devicename></entry>
 		<entry>45.734.361</entry>
 		<entry>45</entry>
 		<entry><filename>/compat/linux/oracle</filename></entry>
 	      </row>
 
 	      <row>
 		<entry><devicename>/dev/da1s1f</devicename></entry>
 		<entry>2.032.623</entry>
 		<entry>2</entry>
 		<entry><filename>/compat/linux/sapmnt</filename></entry>
 	      </row>
 
 	      <row>
 		<entry><devicename>/dev/da1s1g</devicename></entry>
 		<entry>2.032.623</entry>
 		<entry>2</entry>
 		<entry><filename>/compat/linux/usr/sap</filename></entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
 	<para>Configure and initialize the two logical drives
 	  with the Mylex- or PERC/3 RAID software beforehand.
 	  The software can be started during the
 	  bios boot phase.</para>
 
 	<para> Please note that this disk layout differs slightly from
 	  the SAP recommendations, as SAP suggests mounting the
 	  oracle-subdirectories (and some others) separately - I
 	  decided to just create them as real subdirectories for
 	  simplicity.</para>
       </sect3>
 
       <sect3 id="makeworldandnewkernel">
 	<title><command>make world</command> and a New Kernel</title>
 
 	<para>Download the latest stable-sources. Rebuild world and your
 	  custom kernel after configuring your kernel configuration file.
 	  Here you should also include the
 	  <link linkend="kerneltuning">kernel parameters</link>
 	  which are required for both <application>SAP R/3</application>
 	  and <application>Oracle</application>.</para>
       </sect3>
     </sect2>
 
     <sect2 id="installingthelinuxenviornment">
       <title>Installing the Linux Environment</title>
 
       <para>During the first installation with FreeBSD 4.3-STABLE I had some
 	trouble downloading the required RPM-files (for 4.3 stable, 2nd May
 	2001), but with FreeBSD 4.5-STABLE, everything went very smooth.
 	Should you encounter some problems, try to download those files by
 	hand. For a list of RPM-Mirrors and required files, see the
 	corresponding makefile.</para>
 
       <sect3 id="installinglinuxbase-system">
 	<title>Installing Linux Base-system</title>
 
 	<para>First the <link linkend="linuxemu-libs-port">linux_base</link>
 	  port needs to be installed (as <username>root</username>). This is
 	  currently <filename>linux_base-6</filename>.</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput>
 &prompt.root; <userinput>make package</userinput></screen>
 
       </sect3>
 
 
       <sect3 id="installinglinuxdevelopment">
 	<title>Installing Linux Development</title>
 
 	<para>The Linux development is needed, if you want to install
 	  <application>Oracle</application> on FreeBSD according to the
 	  corresponding description in the handbook:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/ports/devel/linux_devtools</userinput>
 &prompt.root; <userinput>make package</userinput></screen>
 
 	<para>Linux Development has only been installed for the <application>SAP
 	  R/3 46B IDES</application>-installation. It is not needed, if
 	  the <application>Oracle DB</application> is not relinked on the
 	  FreeBSD system. This is the case if you are using the
 	  <application>Oracle</application> tarball from a linux system.</para>
 
       </sect3>
 
 
       <sect3 id="installingnecessaryrpms">
 	<title>Installing Necessary RPMs</title>
 	<indexterm><primary>RPMs</primary></indexterm>
 
 	<para>To start the R3SETUP-Program, PAM support is needed.
 	  During the first SAP-Installation on FreeBSD 4.3-STABLE I
 	  tried to install PAM with all the required packages and
 	  finally forced the installation of the PAM package, which
 	  worked. For <application>SAP R/3 4.6C SR2</application> I
 	  directly forced the installation of the PAM-RPM, which also
 	  works, so it seems the dependend packages are not needed:</para>
 
 
 <screen>&prompt.root; <userinput>rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm \
 pam-0.68-7.i386.rpm</userinput></screen>
 
 	<para>For <application>Oracle 8.0.5</application> to run the
 	  intelligent agent, I also had to install the RedHat Tcl package
 	  <filename>tcl-8.0.5-30.i386.rpm</filename> (otherwise the
 	  relinking during <application>Oracle</application> install
 	  will not work).  There are some other issues regarding
 	  relinking of <application>Oracle</application>, but that is
 	  a Oracle-Linux issue, not FreeBSD specific.</para>
 
       </sect3>
 
       <sect3 id="linuxprocandfallbackelfbrand">
 	<title>Some additional hints</title>
 
 	<para>It might also be a good idea to add <filename>linprocfs</filename>
 	  to <filename>/etc/fstab</filename>. See <command>man linprocfs</command>.
 	  Another parameter to set is <emphasis>kern.fallback_elf_brand=3</emphasis>
 	  which is done in file <filename>/etc/sysctl.conf</filename>.
       </sect3>
     </sect2>
 
     <sect2 id="creatingsapr3env">
       <title>Creating the SAP/R3 Environment</title>
 
       <sect3 id="filesystemsandmountpoints">
 	<title>Creating the Necessary Filesystems and Mountpoints</title>
 
 	<para>For a simple installation, it is sufficient to create the
           following filesystems:</para>
 
 	<informaltable>
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>mountpoint</entry>
 		<entry>size in GB</entry>
 	      </row>
 	    </thead>
 	    <tbody>
 	      <row>
 		<entry><filename>/compat/linux/oracle</filename></entry>
 		<entry>45 GB</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>/compat/linux/sapmnt</filename></entry>
 		<entry>2 GB</entry>
 	      </row>
 
 	      <row>
 		<entry><filename>/compat/linux/usr/sap</filename></entry>
 		<entry>2 GB</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
 	<para>It is also necessary to created some links. Otherwise
 	  the SAP-Installer will complain, as it is checking the
 	  created links:</para>
 
 	<screen>&prompt.root; <userinput>ln -s /compat/linux/oracle /oracle</userinput>
 &prompt.root; <userinput>ln -s /compat/linux/sapmnt /sapmnt</userinput>
 &prompt.root; <userinput>ln -s /compat/linux/usr/sap /usr/sap</userinput></screen>
 
 	<para>Possible error message during installation (here with
 	  System <emphasis>PRD</emphasis> and the
 	  <application>SAP R/3 4.6C SR2</application>
 	  installation):</para>
 
 	<screen>INFO 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:200
     Checking existence of symbolic link /usr/sap/PRD/SYS/exe/dbg to
     /sapmnt/PRD/exe. Creating if it does not exist...
 
 WARNING 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:400
     Link /usr/sap/PRD/SYS/exe/dbg exists but it points to file
     /compat/linux/sapmnt/PRD/exe instead of /sapmnt/PRD/exe. The
     program cannot go on as long as this link exists at this
     location. Move the link to another location.
 
 ERROR 2002-03-19 16:45:36 R3LINKS_IND_IND Ins_SetupLinks:0
     can not setup link '/usr/sap/PRD/SYS/exe/dbg' with content
     '/sapmnt/PRD/exe'</screen>
       </sect3>
 
       <sect3 id="creatingusersanddirectories">
 	<title>Creating Users and Directories</title>
 
 	<para><application>SAP R/3</application> needs two users and
 	  three groups. The usernames depend on the
 	  <application>SAP</application> system id (SID) which consists
 	  of three letters. Some of these SIDs are reserved
 	  by <application>SAP</application> (for example
 	  <emphasis>SAP</emphasis> and <emphasis>NIX</emphasis>. For a
 	  complete list please see the SAP documentation).  For the IDES
 	  installation I used <emphasis>IDS</emphasis>, for the
 	  4.6C SR2 installation <emphasis>PRD</emphasis>, as that system
 	  is intended for production use.  We have
 	  therefore the following groups (group ids might differ, these
 	  are just the values I used with my installation):</para>
 
         <informaltable>
           <tgroup cols="3">
           <thead>
           <row>
             <entry>group id</entry>
             <entry>group name</entry>
             <entry>description</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>100</entry>
             <entry>dba</entry>
             <entry>Data Base Administrator</entry>
           </row>
           <row>
             <entry>101</entry>
             <entry>sapsys</entry>
             <entry>SAP System</entry>
           </row>
           <row>
             <entry>102</entry>
             <entry>oper</entry>
             <entry>Data Base Operator</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>For a default Oracle-Installation, only group
           <groupname>dba</groupname> is used. As
           <groupname>oper</groupname>-group, one also uses group
           <groupname>dba</groupname> (see Oracle- and
           SAP-documentation for further information).</para>
 
         <para>We also need the following users:</para>
 
         <informaltable>
           <tgroup cols="6">
           <thead>
           <row>
             <entry>user id</entry>
             <entry>username</entry>
             <entry>generic name</entry>
             <entry>group</entry>
             <entry>additional groups</entry>
             <entry>description</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>1000</entry>
             <entry>idsadm/prdadm</entry>
             <entry><replaceable>sid</replaceable>adm</entry>
             <entry>sapsys</entry>
             <entry>oper</entry>
             <entry>SAP Administrator</entry>
           </row>
           <row>
             <entry>1002</entry>
             <entry>oraids/oraprd</entry>
             <entry>ora<replaceable>sid</replaceable></entry>
             <entry>dba</entry>
             <entry>oper</entry>
             <entry>DB Administrator</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>Adding the users with <command>adduser</command>
           requires the following (please note shell and home
           directory) entries for SAP-Administrator:</para>
 
         <programlisting>Name: <replaceable>sid</replaceable>adm
 Password: ******
 Fullname: SAP Administrator <replaceable>SID</replaceable>
 Uid: 1000
 Gid: 101 (sapsys)
 Class:
 Groups: sapsys dba
 HOME: /home/<replaceable>sid</replaceable>adm
 Shell: bash  (/compat/linux/bin/bash)</programlisting>
 
         <para>and for Database-Administrator:</para>
 
         <programlisting>Name: ora<replaceable>sid</replaceable> 
 Password: ****** 
 Fullname: Oracle Administrator <replaceable>SID</replaceable>
 Uid: 1002 
 Gid: 100 (dba) 
 Class: 
 Groups: dba 
 HOME: /oracle/<replaceable>sid</replaceable> 
 Shell: bash  (/compat/linux/bin/bash)</programlisting>
 
         <para>This should also include group
           <groupname>oper</groupname> in case you are using both
           groups <groupname>dba</groupname> and
           <groupname>oper</groupname>.</para>
 
       </sect3>
 
       <sect3 id="creatingdirectories">
         <title>Creating Directories</title>
 
         <para>These directories are usually created as separate
           filesystems.  This depends entirely on your requirements.  I
           choose to create them as simple directories, as they are all
           located on the same RAID 5 anyway:</para>
 
         <para>First we will set owners and rights of some directories (as
           user <username>root</username>):</para>
 
         <screen>&prompt.root; <userinput>chmod 775 /oracle</userinput>
 &prompt.root; <userinput>chmod 777 /sapmnt</userinput>
 &prompt.root; <userinput>chown root:dba /oracle</userinput>
 &prompt.root; <userinput>chown <replaceable>sid</replaceable>adm:sapsys /compat/linux/usr/sap</userinput>
 &prompt.root; <userinput>chmod 775 /compat/linux/usr/sap</userinput></screen>
 
         <para>Second we will create directories as user 
 	  <username>ora<replaceable>sid</replaceable></username>. These
           will all be subdirectories of 
 	  <filename>/oracle/<replaceable>SID</replaceable></filename>:</para>
 
         <screen>&prompt.root; <userinput>su - ora<replaceable>sid</replaceable></userinput>
 &prompt.root; <userinput>cd /oracle/<replaceable>SID</replaceable></userinput>
 &prompt.root; <userinput>mkdir mirrlogA mirrlogB origlogA origlogB</userinput>
 &prompt.root; <userinput>mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6</userinput>
 &prompt.root; <userinput>mkdir saparch sapreorg</userinput>
 &prompt.root; <userinput>exit</userinput></screen>
 
 	<para>For the <application>Oracle 8.1.7</application>-installation
 	  some additional directories are needed:</para>
 
 	<screen>&prompt.root; <userinput>su - ora<replaceable>sid</replaceable></userinput>
 &prompt.root; <userinput>cd /oracle</userinput>
 &prompt.root; <userinput>mkdir 805_32</userinput>
 &prompt.root; <userinput>mkdir client stage</userinput>
 &prompt.root; <userinput>mkdir client/80x_32</userinput>
 &prompt.root; <userinput>mkdir stage/817_32</userinput>
 &prompt.root; <userinput>cd /oracle/<replaceable>SID</replaceable></userinput>
 &prompt.root; <userinput>mkdir 817_32</userinput></screen>
 
 	<note><para>The directory <filename>client/80x_32</filename> is used
 	  with exactly this name. Don't replace the <emphasis>x</emphasis>
 	  with some number or anything.</para></note>
 
         <para>In the third step we create directories as user 
 	  <username><replaceable>sid</replaceable>adm</username>:</para>
 
         <screen>&prompt.root; <userinput>su - <replaceable>sid</replaceable>adm</userinput>
 &prompt.root; <userinput>cd /usr/sap</userinput>
 &prompt.root; <userinput>mkdir <replaceable>SID</replaceable></userinput>
 &prompt.root; <userinput>mkdir trans</userinput>
 &prompt.root; <userinput>exit</userinput></screen>
       </sect3>
 
       <sect3 id="entriesinslashetcslashservices">
         <title>Entries in /etc/services</title>
 
         <para>SAP R/3 requires some entries in file
           <filename>/etc/services</filename>, which will not be set
           correctly during installation under FreeBSD.  Please add the
           following entries (you need at least those entries
           corresponding to the instance number - in this case,
           <emphasis>00</emphasis>.  It will do no harm adding all
           entries from <emphasis>00</emphasis> to
           <emphasis>99</emphasis> for <emphasis>dp</emphasis>,
           <emphasis>gw</emphasis>, <emphasis>sp</emphasis> and
           <emphasis>ms</emphasis>). If you are going to use a saprouter
 	  or need to access SAP OSS, you also need <emphasis>99</emphasis>,
 	  as port 3299 is usually used for the saprouter process on the
 	  target system:</para>
 
         <programlisting>
 sapdp00    3200/tcp # SAP Dispatcher.      3200 + Instance-Number
 sapgw00  3300/tcp # SAP Gateway.         3300 + Instance-Number
 sapsp00  3400/tcp #                      3400 + Instance-Number
 sapms00  3500/tcp #                      3500 + Instance-Number
 sapms<replaceable>SID</replaceable> 3600/tcp # SAP Message Server.  3600 + Instance-Number
 sapgw00s   4800/tcp # SAP Secure Gateway   4800 + Instance-Number</programlisting>
       </sect3>
 
       <sect3 id="necessarylocales">
         <title>Necessary Locales</title>
 	<indexterm><primary>locale</primary></indexterm>
 
         <para>SAP requires at least two locales that are not part of
           the default RedHat installation. SAP offers the required
           RPMs as download from their FTP-server (which is only
           accessible if you are a customer with OSS-access).  See note
           0171356 for a list of RPMs you need.</para>
 
         <para>It is also possible to just create appropriate links
           (for example from <emphasis>de_DE</emphasis> and
           <emphasis>en_US</emphasis> ), but I would not recommend this
           for a production system (so far it worked with the IDES
           system without any problems, though).  The following locales
           are needed:</para>
 
         <programlisting>de_DE.ISO-8859-1
 en_US.ISO-8859-1</programlisting>
 
 	<para>Create the links like this:</para>
 
 	<screen>&prompt.root; <userinput>cd /compat/linux/usr/share/locale</userinput>
 &prompt.root; <userinput>ln -s de_DE de_DE.ISO-8859-1</userinput>
 &prompt.root; <userinput>ln -s en_US en_US.ISO-8859-1</userinput></screen>
 
         <para>If they are not present, there will be some problems
           during the installation.  If these are then subsequently
           ignored (by setting the status of the offending steps to
           OK in file CENTRDB.R3S), it will be impossible to log onto
           the SAP-system without some additional effort.</para>
       </sect3>
 
       <sect3 id="kerneltuning">
         <title>Kernel Tuning</title>
 	<indexterm><primary>kernel tuning</primary></indexterm>
 
         <para>SAP R/3 Systems need a lot of resources.  I therefore
         added the following parameters to my kernel config-file:</para>
 
         <programlisting># Set these for memory pigs (SAP and Oracle):
 options MAXDSIZ="(1024*1024*1024)"
 options DFLDSIZ="(1024*1024*1024)"
 # System V options needed.
 options SYSVSHM #SYSV-style shared memory
 options SHMMAXPGS=262144 #max amount of shared mem. pages
 #options SHMMAXPGS=393216 #use this for the 46C inst.parameters
 options SHMMNI=256 #max number of shared memory ident if.
 options SHMSEG=100 #max shared mem.segs per process
 options SYSVMSG #SYSV-style message queues 
 options MSGSEG=32767 #max num. of mes.segments in system 
 options MSGSSZ=32 #size of msg-seg. MUST be power of 2
 options MSGMNB=65535 #max char. per message queue
 options MSGTQL=2046 #max amount of msgs in system
 options SYSVSEM #SYSV-style semaphores 
 options SEMMNU=256 #number of semaphore UNDO structures
 options SEMMNS=1024 #number of semaphores in system
 options SEMMNI=520 #number of semaphore indentifiers
 options SEMUME=100       #number of UNDO keys</programlisting>
 
         <para>The minimum values are specified in the documentation that
           comes from SAP.  As there is no description for Linux, see the
           HP-UX-section (32-bit) for further information. As the system
 	  for the 4.6C SR2 installation has more main memory, the shared
 	  segments can be larger both for <application>SAP</application>
 	  and <application>Oracle</application>, therefore choose a larger
 	  number of shared memory pages.</para>
 
 	<note><para>With the default installation of FreeBSD&nbsp;4.5 on x386,
 	  leave MAXDSIZ and DFLDSIZ at 1&nbsp;GB maximum. Otherwise, strange 
 	  errors like <errorname>ORA-27102: out of memory</errorname> and 
           <errorname>Linux Error: 12: Cannot allocate memory</errorname>
           might happen.</para></note>
       </sect3>
     </sect2>
 
     <sect2 id="installingsapr3">
       <title>Installing SAP R/3</title>
 
       <sect3 id="preparingsapcdroms">
         <title>Preparing SAP CDROMs</title>
 
         <para>There are many CDROMs to mount and unmount during the
           installation.  Assuming you have enough CDROM-drives, you
           can just mount them all.  I decided to copy the CDROM
           contents to corresponding directories:</para>
 
 	<programlisting>/oracle/<replaceable>SID</replaceable>/sapreorg/<replaceable>cd-name</replaceable></programlisting>
 
         <para>where <replaceable>cd-name</replaceable> was one of <filename>KERNEL</filename>, 
 	  <filename>RDBMS</filename>, <filename>EXPORT1</filename>,
 	  <filename>EXPORT2</filename>, <filename>EXPORT3</filename>,
 	  <filename>EXPORT4</filename>, <filename>EXPORT5</filename> and 
 	  <filename>EXPORT6</filename> for the 4.6B/IDES-installation, and
 	  <filename>KERNEL</filename>, <filename>RDBMS</filename>,
 	  <filename>DISK1</filename>, <filename>DISK2</filename>,
 	  <filename>DISK3</filename>, <filename>DISK4</filename> and
 	  <filename>LANG</filename> for the 4.6C SR2-installation. All the
 	  filenames on the mounted CDs should be in capital letters,
 	  otherwise use the <option>-g</option> option for mounting. So use the following
 	  commands:</para>
 
         <screen>&prompt.root; <userinput>mount_cd9660 -g /dev/cd0a /mnt</userinput>
 &prompt.root; <userinput>cp -R /mnt/* /oracle/<replaceable>SID</replaceable>/sapreorg/<replaceable>cd-name</replaceable></userinput>
 &prompt.root; <userinput>umount /mnt</userinput></screen>
       </sect3>
 
       <sect3 id="runningtheinstall-script">
         <title>Running the install-script</title>
 
 	<para>First you have to prepare an install-directory:</para>
 
 	<screen>&prompt.root; <userinput>cd /oracle/<replaceable>SID</replaceable>/sapreorg</userinput>
 &prompt.root; <userinput>mkdir install</userinput>
 &prompt.root; <userinput>cd install</userinput></screen>
 
         <para>Then the install-script is started, which will copy nearly
           all the relevant files into the install-directory:</para>
 
 	<screen>&prompt.root; <userinput>/oracle/<replaceable>SID</replaceable>/sapreorg/KERNEL/UNIX/INSTTOOL.SH</userinput></screen>
 
 	<para>The IDES-Installation (4.6B) comes with a fully customized
 	  SAP R/3 Demo-System, so there are six instead of just three
           EXPORT-CDs.  At this point the installation template
 	  <filename>CENTRDB.R3S</filename> is for installing a standard
 	  central instance (R/3 and Database), not the IDES central
 	  instance, so one needs to copy the corresponding CENTRDB.R3S
 	  from the EXPORT1 directory, otherwise R3SETUP will only ask
 	  for three EXPORT-CDs.</para>
 
 	<para>The newer <application>SAP 4.6C SR2</application>-release
 	  comes with four EXPORT-CDs. The parameter-file that controls
 	  the installation-steps is <filename>CENTRAL.R3S</filename>.
 	  Contrary to earlier releases there are no separate installation
 	  templates for a central instance with or without database.
 	  SAP is using a separate template for DB-installation. To restart
 	  the installation later it is however sufficient to restart with
 	  the original file.</para>
 
 	<para>During and after installation, SAP requires
 	  <command>hostname</command> to return the computer name
 	  only, not the fully qualified domain name. So either
 	  set the hostname accordingly, or set an alias with
 	  <command>alias hostname='hostname -s'</command> for
 	  both <username>ora<replaceable>sid</replaceable></username> and 
 	  <username><replaceable>sid</replaceable>adm</username> (and for
 	  <username>root</username> at least during installation
 	  steps performed as <username>root</username>). It is also 
 	  possible to adjust the installed profile- and login-scripts of
 	  both users that are installed during 
 	  <application>SAP</application>-installation.</para>
       </sect3>
 
       <sect3 id="startr3setup-46B">
         <title>Start R3SETUP 4.6B</title>
 
         <para>Make sure <envar>LD_LIBRARY_PATH</envar> is set correctly:</para>
 
         <screen>&prompt.root; <userinput>export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib</userinput></screen>
 
         <para>Start R3SETUP as <username>root</username> from 
 	  installation directory:</para>
 
         <screen>&prompt.root; <userinput>cd /oracle/IDS/sapreorg/install</userinput>
 &prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput></screen>
 
         <para>The script then asks some questions (defaults in brackets,
         followed by actual input):</para>
 
         <informaltable>
           <tgroup cols="3">
           <thead>
           <row>
             <entry>Question</entry>
             <entry>Default</entry>
             <entry>Input</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>Enter SAP System ID</entry>
             <entry>[C11]</entry>
             <entry>IDS<keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter SAP Instance Number</entry>
             <entry>[00]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter SAPMOUNT Directory</entry>
             <entry>[/sapmnt]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter name of SAP central host</entry>
             <entry>[troubadix.domain.de]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter name of SAP db host</entry>
             <entry>[troubadix]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Select character set</entry>
             <entry>[1] (WE8DEC)</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.6</entry>
             <entry> </entry>
             <entry>1<keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Extract Oracle Client archive</entry>
             <entry>[1] (Yes, extract)</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter path to KERNEL CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/KERNEL</entry>
           </row>
           <row>
             <entry>Enter path to RDBMS CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/RDBMS</entry>
           </row>
           <row>
             <entry>Enter path to EXPORT1 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT1</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT1 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD4_DIR]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter path to EXPORT2 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT2</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT2 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD5_DIR]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter path to EXPORT3 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT3</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT3 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD6_DIR]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter path to EXPORT4 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT4</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT4 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD7_DIR]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter path to EXPORT5 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT5</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT5 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD8_DIR]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter path to EXPORT6 CD</entry>
             <entry>[/sapcd]</entry>
             <entry>/oracle/IDS/sapreorg/EXPORT6</entry>
           </row>
           <row>
             <entry>Directory to copy EXPORT6 CD</entry>
             <entry>[/oracle/IDS/sapreorg/CD9_DIR]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter amount of RAM for SAP + DB</entry>
             <entry> </entry>
             <entry>850<keycap>Enter</keycap> (in Megabytes)</entry>
           </row>
           <row>
             <entry>Service Entry Message Server</entry>
             <entry>[3600]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter Group-ID of sapsys</entry>
             <entry>[101]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter Group-ID of oper</entry>
             <entry>[102]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter Group-ID of dba</entry>
             <entry>[100]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter User-ID of <replaceable>sid</replaceable>adm</entry>
             <entry>[1000]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter User-ID of ora<replaceable>sid</replaceable></entry>
             <entry>[1002]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Number of parallel procs</entry>
             <entry>[2]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
       
         <para>If you had not copied the CDs to the different locations,
           then the SAP-Installer cannot find the CD needed (identified
           by the <filename>LABEL.ASC</filename>-File on CD) and would
           then ask you to insert and mount the CD and confirm or enter
           the mount path.</para>
    
         <para>The <filename>CENTRDB.R3S</filename> might not be
           error-free. In my case, it requested EXPORT4 again (but
           indicated the correct key (6_LOCATION, then 7_LOCATION
           etc.), so one can just continue with entering the correct
           values. Do not get irritated.</para>
 
         <para>Apart from some problems mentioned below, everything
           should go straight through up to the point where the Oracle
           database software needs to be installed.</para>
       </sect3>
 
       <sect3 id="startr3setup-46C">
 	<title>Start R3SETUP 4.6C SR2</title>
 
 	<para>Make sure <envar>LD_LIBRARY_PATH</envar> is set correctly. This is a
 	  different value from the 4.6B installation with
 	  <application>Oracle 8.0.5</application>:</para>
 
 	<screen>&prompt.root; <userinput>export LD_LIBRARY_PATH=/sapmnt/PRD/exe:/oracle/PRD/817_32/lib</userinput></screen>
 
 	<para>Start R3SETUP as user root from installation directory:</para>
 
 	<screen>&prompt.root; <userinput>cd /oracle/PRD/sapreorg/install</userinput>
 &prompt.root; <userinput>./R3SETUP -f CENTRAL.R3S</userinput></screen>
 
 	<para>The script then asks some questions (defaults in brackets,
 	  followed by actual input):</para>
 
 	<informaltable>
 	  <tgroup cols="3">
 	  <thead>
 	  <row>
 	    <entry>Question</entry>
 	    <entry>Default</entry>
 	    <entry>Input</entry>
 	  </row>
 	  </thead>
 	  <tbody>
 	  <row>
 	    <entry>Enter SAP System ID</entry>
 	    <entry>[C11]</entry>
 	    <entry>PRD<keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Enter SAP Instance Number</entry>
 	    <entry>[00]</entry>
 	    <entry><keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Enter SAPMOUNT Directory</entry>
 	    <entry>[/sapmnt]</entry>
 	    <entry><keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Enter name of SAP central host</entry>
 	    <entry>[majestix]</entry>
 	    <entry><keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Enter Database System ID</entry>
 	    <entry>[PRD]</entry>
 	    <entry>PRD<keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Enter name of SAP db host</entry>
 	    <entry>[majestix]</entry>
 	    <entry><keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Select character set</entry>
 	    <entry>[1] (WE8DEC)</entry>
 	    <entry><keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Enter Oracle server version (2) Oracle 8.1.7</entry>
 	    <entry> </entry>
 	    <entry>2<keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Extract Oracle Client archive</entry>
 	    <entry>[1] (Yes, extract)</entry>
 	    <entry><keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Enter path to KERNEL CD</entry>
 	    <entry>[/sapcd]</entry>
 	    <entry>/oracle/PRD/sapreorg/KERNEL</entry>
 	  </row>
 	  <row>
 	    <entry>Enter amount of RAM for SAP + DB</entry>
 	    <entry>2044</entry>
 	    <entry>1800<keycap>Enter</keycap> (in Megabytes)</entry>
 	  </row>
 	  <row>
 	    <entry>Service Entry Message Server</entry>
 	    <entry>[3600]</entry>
 	    <entry><keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
 	    <entry>Enter Group-ID of sapsys</entry>
 	    <entry>[100]</entry>
 	    <entry><keycap>Enter</keycap></entry>
 	  </row>
 	  <row>
             <entry>Enter Group-ID of oper</entry>
             <entry>[101]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter Group-ID of dba</entry>
             <entry>[102]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter User-ID of <username>oraprd</username></entry>
             <entry>[1002]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter User-ID of <username>prdadm</username></entry>
             <entry>[1000]</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>LDAP support</entry>
             <entry> </entry>
             <entry>3<keycap>Enter</keycap> (no support)</entry>
           </row>
           <row>
             <entry>Installation step completed</entry>
             <entry>[1] (continue)</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Choose installation service</entry>
             <entry>[1] (DB inst,file)</entry>
             <entry><keycap>Enter</keycap></entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
       
         <para>So far, creation of users gives an error during
 	  installation in phases OSUSERDBSID_IND_ORA (for creating
 	  user <username>ora<replaceable>sid</replaceable></username>) and 
 	  OSUSERSIDADM_IND_ORA (creating user 
 	  <username><replaceable>sid</replaceable>adm</username>).</para>
    
         <para>Apart from some problems mentioned below, everything
           should go straight through up to the point where the Oracle
           database software needs to be installed.</para>
       </sect3>
     </sect2>
 
     <sect2 id="installingoracle805">
       <title>Installing Oracle 8.0.5</title>
 
       <para>Please see the corresponding SAP-Notes and Oracle Readmes
         regarding Linux and Oracle DB for possible problems. Most if
         not all problems stem from incompatible libraries.</para>
 
       <para>For more information on installing Oracle, refer to <link
 	  linkend="linuxemu-oracle">the Installing Oracle
 	  chapter.</link></para>
 
 
       <sect3 id="installingtheoracle805withorainst">
         <title>Installing the Oracle 8.0.5 with orainst</title>
 
         <para>If <application>Oracle 8.0.5</application> is to be
           used, some additional libraries are needed for successfully
           relinking, as Oracle 8.0.5 was linked with an old glibc
           (RedHat 6.0), but RedHat 6.1 already uses a new glibc. So
           you have to install the following additional packages to
           ensure that linking will work:</para>
 
         <para><filename>compat-libs-5.2-2.i386.rpm</filename></para>
         <para><filename>compat-glibc-5.2-2.0.7.2.i386.rpm</filename></para>
         <para><filename>compat-egcs-5.2-1.0.3a.1.i386.rpm</filename></para>
         <para><filename>compat-egcs-c++-5.2-1.0.3a.1.i386.rpm</filename></para>
         <para><filename>compat-binutils-5.2-2.9.1.0.23.1.i386.rpm</filename></para>
 
         <para>See the corresponding SAP-Notes or Oracle Readmes for
           further information.  If this is no option (at the time of
           installation I did not have enough time to check this), one
           could use the original binaries, or use the relinked
           binaries from an original RedHat System.</para>
 
         <para>For compiling the intelligent agent, the RedHat Tcl
           package must be installed.  If you cannot get
           <filename>tcl-8.0.3-20.i386.rpm</filename>, a newer one like
           <filename>tcl-8.0.5-30.i386.rpm</filename> for RedHat 6.1
           should also do.</para>
 
         <para>Apart from relinking, the installation is
           straightforward:</para>
 
         <screen>&prompt.root; <userinput>su - oraids</userinput>
 &prompt.root; <userinput>export TERM=xterm</userinput>
 &prompt.root; <userinput>export ORACLE_TERM=xterm</userinput>
 &prompt.root; <userinput>export ORACLE_HOME=/oracle/IDS</userinput>
 &prompt.root; <userinput>cd /ORACLE_HOME/orainst_sap</userinput>
 &prompt.root; <userinput>./orainst</userinput></screen>
 
         <para>Confirm all Screens with <keycap>Enter</keycap> until the software is
           installed, except that one has to deselect the
           <emphasis>Oracle On-Line Text Viewer</emphasis>, as this is
           not currently available for Linux. Oracle then wants to
           relink with <command>i386-glibc20-linux-gcc</command>
           instead of the available <command>gcc</command>,
           <command>egcs</command> or <command>i386-redhat-linux-gcc
           </command>.</para>
 
         <para>Due to time constrains I decided to use the binaries
           from an <application>Oracle 8.0.5 PreProduction</application>
 	  release, after the first
           attempt at getting the version from the RDBMS-CD working,
           failed, and finding and accessing the correct RPMs was a
           nightmare at that time.</para>
 
       </sect3>
 
       <sect3 id="installingtheoracle805preproduction">
         <title>Installing the Oracle 8.0.5 Pre-Production release for
           Linux (Kernel 2.0.33)</title>
 
         <para>This installation is quite easy. Mount the CD, start the
           installer.  It will then ask for the location of the Oracle
           home directory, and copy all binaries there. I did not
           delete the remains of my previous RDBMS-installation tries,
           though.</para>
 
         <para>Afterwards, Oracle Database could be started with no
           problems.</para>
       </sect3>
     </sect2>
 
     <sect2 id="installingoracle817">
       <title>Installing the Oracle 8.1.7 linux tarball</title>
       <para>Take the tarball <filename>oracle81732.tgz</filename> you
 	produced from the installation directory on a linux system
 	and untar it to <filename>/oracle/<replaceable>SID</replaceable>/817_32/</filename>.</para>
     </sect2>
 
     <sect2 id="continuewithsapr4installation">
       <title>Continue with SAP R/3 Installation</title>
 
       <para>First check the environment settings of users 
 	<username>idsamd</username>
         (<replaceable>sid</replaceable>adm) and 
 	<username>oraids</username> (ora<replaceable>sid</replaceable>). They should now
         both have the files <filename>.profile</filename>,
         <filename>.login</filename> and <filename>.cshrc</filename>
         which are all using <command>hostname</command>. In case the
         system's hostname is the fully qualified name, you need to
         change <command>hostname</command> to <command>hostname
         -s</command> within all three files.</para>
 
       <sect3 id="databaseload">
         <title>Database Load</title>
 
         <para>Afterwards, R3SETUP can either be restarted or continued
           (depending on whether exit was chosen or not). R3SETUP then
 	  creates the tablespaces and loads the data (for 46B IDES, from 
 	  EXPORT1 to EXPORT6, for 46C from DISK1 to DISK4) with R3load 
 	  into the database.</para>
 
         <para>When the database load is finished (might take a few
           hours), some passwords are requested. For test
           installations, one can use the well known default passwords
           (use different ones if security is an issue!):</para>
 
         <informaltable>
           <tgroup cols="2">
           <thead>
           <row>
             <entry>Question</entry>
             <entry>Input</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>Enter Password for sapr3</entry>
             <entry>sap<keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Confirum Password for sapr3</entry>
             <entry>sap<keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter Password for sys</entry>
             <entry>change_on_install<keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Confirm Password for sys</entry>
             <entry>change_on_install<keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Enter Password for system</entry>
             <entry>manager<keycap>Enter</keycap></entry>
           </row>
           <row>
             <entry>Confirm Password for system</entry>
             <entry>manager<keycap>Enter</keycap></entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>At this point I had a few problems with 
 	  <literal>dipgntab</literal> during the 4.6B
 	  installation.</para>
       </sect3>
 
       <sect3 id="listener">
         <title>Listener</title>
 
         <para>Start the Oracle-Listener as user 
 	  <username>ora<replaceable>sid</replaceable></username> as follows:</para>
 
         <screen>&prompt.user; <userinput>umask 0; lsnrctl start</userinput></screen>
 
         <para>Otherwise you might get <errorcode>ORA-12546</errorcode> as the sockets will not
         have the correct permissions. See SAP note 072984.</para>
       </sect3>
 
       <sect3 id="mnlstables">
 	<title>Updating MNLS Tables</title>
 	<para>If you plan to import non-Latin-1 languages into the SAP-System,
 	  you have to update the Multi National Language Support tables.
 	  This is described in the SAP OSS-Notes 15023 and 45619. Otherwise,
 	  you can skip this question during SAP installation.</para>
 	<note><para>If you don't need MNLS, it is still necessary to check
 	  table TCPDB and initializing it if this hasn't been done. See
 	  SAP note 0015023 and 0045619 for further information.</para></note>
       </sect3>
     </sect2>
 
     <sect2 id="postinstallationsteps">
       <title>Post-installation Steps</title>
 
       <sect3 id="requestsapr3licensekey">
         <title>Request SAP R/3 License Key</title>
 
         <para>You have to request your SAP R/3 License Key. This is needed,
 	  as the temporary license that was installed during installation
 	  is only valid for four weeks. First get the hardware key.  Log 
 	  on as user <username>idsadm</username> and call 
 	  <command>saplicense</command>:</para>
 
         <screen>&prompt.root; <userinput>/sapmnt/IDS/exe/saplicense -get</userinput></screen>
 
 	<para>Calling <command>saplicense</command> without options gives 
 	  a list of options.  Upon receiving the license key, it can be 
 	  installed using:</para>
 
         <screen>&prompt.root; <userinput>/sapmnt/IDS/exe/saplicense -install</userinput></screen>
 
         <para>You are then required to enter the following values:</para>
 
         <programlisting>SAP SYSTEM ID   = <replaceable>SID, 3 chars</replaceable>
 CUSTOMER KEY    = <replaceable>hardware key, 11 chars</replaceable>
 INSTALLATION NO = <replaceable>installation, 10 digits</replaceable>
 EXPIRATION DATE = <replaceable>yyyymmdd, usually "99991231"</replaceable>
 LICENSE KEY     = <replaceable>license key, 24 chars</replaceable></programlisting>
       </sect3>
 
       <sect3 id="creatingusers">
         <title>Creating Users</title>
 
         <para>Create a user within client 000 (for some tasks required
         to be done within client 000, but with a user different from
         users <username>sap*</username> and
         <username>ddic</username>). As a username, I usually choose
         <replaceable>wartung</replaceable> (or
         <replaceable>service</replaceable> in English).  Profiles
         required are <emphasis>sap_new</emphasis> and
         <emphasis>sap_all</emphasis>. For additional safety the
         passwords of default users within all clients should be
         changed (this includes users <username>sap*</username> and
         <username>ddic</username>).</para>
       </sect3>
 
       <sect3 id="configtranssysprofileopermodesetc">
         <title>Configure Transport System, Profile, Operation Modes, Etc.</title>
 
         <para>Within client 000, user different from <username>ddic</username>
 	  and sap*, do at least the following:</para>
 
         <informaltable>
           <tgroup cols="2">
           <thead>
           <row>
             <entry>Task</entry>
             <entry>Transaction</entry>
           </row>
           </thead>
           <tbody>
           <row>
             <entry>Configure Transport System, eg as <emphasis>Stand-Alone
             Transport Domain Entity</emphasis></entry>
 	    <entry>STMS</entry>
           </row>
           <row>
             <entry>Create / Edit Profile for System</entry>
             <entry>RZ10</entry>
           </row>
           <row>
             <entry>Maintain Operation Modes and Instances</entry>
             <entry>RZ04</entry>
           </row>
           </tbody>
           </tgroup>
         </informaltable>
 
         <para>These and all the other post-installation steps are
           thoroughly described in SAP installation guides.</para>
       </sect3>
 
       <sect3 id="editintsidsap">
         <title>Edit init<replaceable>sid</replaceable>.sap (initIDS.sap)</title>
 
 	<para>The file <filename>/oracle/IDS/dbs/initIDS.sap</filename>
 	  contains the SAP backup profile.  Here the size of the tape to 
 	  be used, type of compression and so on need to be defined. To 
           get this running with <command>sapdba</command> /
 	  <command>brbackup</command>, I changed the following values:</para>
 
         <programlisting>compress = hardware
 archive_function = copy_delete_save
 cpio_flags = "-ov --format=newc --block-size=128 --quiet"
 cpio_in_flags = "-iuv --block-size=128 --quiet"
 tape_size = 38000M
 tape_address = /dev/nsa0
 tape_address_rew = /dev/sa0</programlisting>
 
         <para>Explanations:</para>
 
         <para><varname>compress</varname> The tape I use is a HP DLT1
         which does hardware compression.</para>
 
         <para><varname>archive_function</varname> This defines the
         default behavior for saving Oracle archive logs: New logfiles
         are saved to tape, already saved logfiles are saved again and
         are then deleted.  This prevents lots of trouble if you need to
         recover the database, and one of the archive-tapes has gone
         bad.</para>
 
         <para><varname>cpio_flags</varname> Default is to use -B which
         sets blocksize to 5120&nbsp;Bytes. For DLT-Tapes, HP recommends at
         least 32&nbsp;K blocksize, so I used --block-size=128 for
         64&nbsp;K. --format=newc is needed I have inode numbers greater than
         65535. The last option --quiet is needed as otherwise 
 	<command>brbackup</command>
         complains as soon as <command>cpio</command> outputs the 
 	numbers of blocks saved.</para>
 
         <para><varname>cpio_in_flags</varname> Flags needed for
         loading data back from tape. Format is recognized
         automagically.</para>
 
         <para><varname>tape_size</varname> This usually gives the raw
         storage capability of the tape. For security reason (we use
         hardware compression), the value is slightly lower than the
         actual value.</para>
 
         <para><varname>tape_address</varname> The non-rewindable
         device to be used with <command>cpio</command>.</para>
 
         <para><varname>tape_address_rew</varname> The rewindable device to be
         used with cpio.</para>
       </sect3>
 
       <sect3>
 	<title>Configuration Issues after Installation</title>
 
 	<para>The following SAP-parameters should be tuned after
 	  installation (examples for IDES 46B, 1&nbsp;GB memory):</para>
 
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Name</entry>
 		<entry>Value</entry>
 	      </row>
 	    </thead>
 	    <tbody>
 	      <row>
 		<entry>ztta/roll_extension</entry>
 		<entry>250000000</entry>
 	      </row>
 	      <row>
 		<entry>abap/heap_area_dia</entry>
                 <entry>300000000</entry>
 	      </row>
 	      <row>
 		<entry>abap/heap_area_nondia</entry>
 		<entry>400000000</entry>
 	      </row>
 	      <row>
 		<entry>em/initial_size_MB</entry>
 		<entry>256</entry>
 	      </row>
 	      <row>
 		<entry>em/blocksize_kB</entry>
 		<entry>1024</entry>
 	      </row>
 	      <row>
 		<entry>ipc/shm_psize_40</entry>
 		<entry>70000000</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
 	<para>SAP-Note 0013026:</para>
 
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Name</entry>
 		<entry>Value</entry>
 	      </row>
 	    <tbody>
 	      <row>
 		<entry>ztta/dynpro_area</entry>
 		<entry>2500000</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
 	<para>SAP-Note 0157246:</para>
 
 	<informaltable frame="none">
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Name</entry>
 		<entry>Value</entry>
 	      </row>
 	    <tbody>
 	      <row>
 		<entry>rdisp/ROLL_MAXFS</entry>
 		<entry>16000</entry>
 	      </row>
 	      <row>
 		<entry>rdisp/PG_MAXFS</entry>
 		<entry>30000</entry>
 	      </row>
 	    </tbody>
 	  </tgroup>
 	</informaltable>
 
 	<note>
 	  <para>With the above parameters, on a system with 1&nbsp;gigabyte
 	    of memory, one may find memory consumption similar to:</para>
 
 	  <programlisting>Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K Free</programlisting>
 	</note>
       </sect3>
     </sect2>
 
     <sect2 id="problemsduringinstallation">
       <title>Problems During Installation</title>
 
       <sect3 id="restartr3setup">
 	<title>Restart R3SETUP after fixing a problem</title>
 
 	<para>R3SETUP stops if it encounters an error. If you have
 	  looked at the corresponding logfiles and fixed the error,
 	  you have to start R3SETUP again, usually selecting REPEAT
 	  as option for the last step R3SETUP complained about.</para>
 
 	<para>To restart R3SETUP, just start it with the corresponding
 	  <filename>R3S</filename>-file:
 	  <screen>&prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput></screen>
 	  for 4.6B, or with
 	  <screen>&prompt.root; <userinput>./R3SETUP -f CENTRAL.R3S</userinput></screen>
 	  for 4.6C, no matter whether the error occured
 	  with <filename>CENTRAL.R3S</filename> or
 	  <filename>DATABASE.R3S</filename>.</para>
 
 	<note><para>At some stages, R3SETUP assumes that both database-
 	    and SAP-processes are up and running (as those were steps it
 	    already completed). Should errors occur and for example the 
 	    database could not be started, you have to start both database 
 	    and SAP by hand after you fixed the errors and before starting 
 	    R3SETUP again.</para>
 	  <para>Don't forget to also start the oracle listener again (as 
 	    <username>ora<replaceable>sid</replaceable></username> with
 	    <command>umask 0; lsnrctl start</command>) if it was also
 	    stopped (for example due to a necessary reboot of the 
 	    system).</para>
 	</note>
       </sect3>
 
       <sect3 id="indoraduringduringr3setup">
         <title>OSUSERSIDADM_IND_ORA During R3SETUP</title>
 
         <para>If R3SETUP complains at this stage, edit the
 	  template file R3SETUP used at that time
           (<filename>CENTRDB.R3S</filename> (4.6B) or either
 	  <filename>CENTRAL.R3S</filename> or
 	  <filename>DATABASE.R3S</filename> (4.6C)).
 	  Locate [OSUSERSIDADM_IND_ORA] or search for the
 	  only <emphasis>STATUS=ERROR</emphasis>-entry
 	  and edit the following values:</para>
 
         <programlisting>HOME=/home/<replaceable>sid</replaceable>adm (was empty)
 STATUS=OK (had status ERROR)
         </programlisting>
 
         <para>Then you can restart R3SETUP again.</para>
       </sect3>
 
       <sect3 id="indoraduringr3setup">
         <title>OSUSERDBSID_IND_ORA During R3SETUP</title>
 
         <para>Possibly R3SETUP also complains at this stage. The error
 	  here is similar to the one in phase OSUSERSIDADM_IND_ORA. 
 	  Just edit
 	  the template file R3SETUP used at that time
           (<filename>CENTRDB.R3S</filename> (4.6B) or either
 	  <filename>CENTRAL.R3S</filename> or
 	  <filename>DATABASE.R3S</filename> (4.6C)).
 	  Locate [OSUSERDBSID_IND_ORA] or search for the
 	  only <emphasis>STATUS=ERROR</emphasis>-entry
 	  and edit the following value in that section:</para>
 
         <programlisting>STATUS=OK</programlisting>
 
         <para>Then restart R3SETUP.</para>
       </sect3>
 
       <sect3 id="oraviewvrffilenotfound">
         <title><errorname>oraview.vrf FILE NOT FOUND</errorname> During Oracle Installation</title>
 
         <para>You have not deselected <emphasis>Oracle On-Line Text Viewer</emphasis>
           before starting the installation. This is marked for installation even
           though this option is currently not available for Linux. Deselect this
           product inside the Oracle installation menu and restart installation.</para>
       </sect3>
 
       <sect3 id="textenvincalid">
         <title><errorname>TEXTENV_INVALID</errorname> During R3SETUP, RFC or SAPGUI Start</title>
 
         <para>If this error is encountered, the correct locale is
 	  missing.  SAP note 0171356 lists the necessary RPMs that need
 	  be installed (eg <emphasis>saplocales-1.0-3</emphasis>,
 	  <emphasis>saposcheck-1.0-1</emphasis> for RedHat 6.1). In case
 	  you ignored all the related errors and set the corresponding
 	  status from ERROR to OK (in CENTRDB.R3S) every time R3SETUP
 	  complained and just restarted R3SETUP, the SAP-System will not
 	  be properly configured and you will then not be able to
 	  connect to the system with a
 	  <literal>sapgui</literal>, even though the system
 	  can be started. Trying to connect with the old Linux
 	  <literal>sapgui</literal> gave the following
 	  messages:</para>
 
         <programlisting>Sat May 5 14:23:14 2001
 *** ERROR => no valid userarea given [trgmsgo. 0401]
 Sat May 5 14:23:22 2001
 *** ERROR => ERROR NR 24 occured [trgmsgi. 0410]
 *** ERROR => Error when generating text environment. [trgmsgi. 0435]
 *** ERROR => function failed [trgmsgi. 0447]
 *** ERROR => no socket operation allowed [trxio.c 3363]
 Speicherzugriffsfehler</programlisting>
 
         <para>This behavior is due to SAP R/3 being unable to correctly
 	  assign a locale and also not being properly configured itself
 	  (missing entries in some database tables). To be able to connect
 	  to SAP, add the following entries to file 
 	  <filename>DEFAULT.PFL</filename> (see note 0043288):</para>
 
 	<programlisting>abap/set_etct_env_at_new_mode = 0
 install/collate/active = 0
 rscp/TCP0B = TCP0B</programlisting>
 
         <para>Restart the SAP system. Now you can connect to the
           system, even though country-specific language settings might
           not work as expected.  After correcting country-settings
           (and providing the correct locales), these entries can be
           removed from <filename>DEFAULT.PFL</filename> and the SAP
 	  system can be restarted.</para>
 
       </sect3>
 
       <sect3 id="ora-00001">
 	<title><errorcode>ORA-00001</errorcode></title>
 	<para>This error only happened with 
 	  <application>Oracle 8.1.7</application> on FreeBSD&nbsp;4.5.
 	  The reason was that the Oracle database could not initialize itself
 	  properly and crashed, leaving semaphores and shared memory on the
 	  system. The next try to start the database then returned
 	  <errorcode>ORA-00001</errorcode>.</para>
 
 	<para>Find them with <command>ipcs -a</command> and remove them
 	  with <command>ipcrm</command>.</para>
       </sect3>
 
       <sect3 id="ora-00445pmon">
 	<title><errorcode>ORA-00445</errorcode> (background process PMON did not start)</title>
 	<para>This error happened with <application>Oracle 8.1.7</application>.
 	  This error is reported if the Database is started with
 	  the usual startsap-script (for example
 	  <filename>startsap_majestix_00</filename>) as user 
 	  <username>prdadm</username>.</para>
 
 	<para>A possible workaround is to start the database as user 
 	  <username>oraprd</username> instead
 	  with <command>svrmgrl</command>:</para>
 
 	<screen>&prompt.user; <userinput>svrmgrl</userinput>
 SVRMGR&gt; <userinput>connect internal;</userinput>
 SVRMGR&gt; <userinput>startup</userinput>;
 SVRMGR&gt; <userinput>exit</userinput></screen>
 
       </sect3>
 
       <sect3 id="ora-12546">
         <title><errorcode>ORA-12546</errorcode> (start Listener with Correct Permissions)</title>
 
         <para>Start the Oracle Listener as user
           <username>oraids</username> with the following commands:</para>
 
         <screen>&prompt.root; <userinput>umask 0; lsnrctl start</userinput></screen>
 
         <para>Otherwise you might get <errorcode>ORA-12546</errorcode> as the sockets will not
           have the correct permissions. See SAP note 0072984.</para>
       </sect3>
 
       <sect3 id="ora-27102">
 	<title><errorcode>ORA-27102</errorcode> (out of memory)</title>
 
 	<para>This error happend whilst trying to use values for
 	  <emphasis>MAXDSIZ</emphasis> and <emphasis>DFLDSIZ</emphasis>
 	  greater than 1&nbsp;GB (1024x1024x1024). Additionally, I got 
 	  <errorname>Linux Error 12: Cannot allocate memory</errorname>.</para>
       </sect3>
 
       <sect3 id="dipgntabindind">
         <title>[DIPGNTAB_IND_IND] During R3SETUP</title>
 
         <para>In general, see SAP note 0130581 (R3SETUP step 
 	  <literal>DIPGNTAB</literal> terminates).  During the
 	  IDES-specific installation, for some reasons the installation
 	  process was not using the proper SAP system name <quote>IDS</quote>, but
 	  the empty string "" instead. This lead to some minor problems
 	  with accessing directories, as the paths are generated
 	  dynamically using <replaceable>SID</replaceable> (in this case IDS).  So instead
 	  of accessing:</para>
 
         <programlisting>/usr/sap/IDS/SYS/...
 /usr/sap/IDS/DVMGS00</programlisting>
 
         <para>the following paths were used:</para>
 
         <programlisting>/usr/sap//SYS/...
 /usr/sap/D00</programlisting>
 
         <para>To continue with the installation, I created a link and an
           additional directory:</para>
 
         <screen>&prompt.root; <userinput>pwd</userinput>
 /compat/linux/usr/sap
 &prompt.root; <userinput>ls -l</userinput>
 total 4
 drwxr-xr-x 3  idsadm sapsys 512 May 5 11:20 D00
 drwxr-x--x 5  idsadm sapsys 512 May 5 11:35 IDS
 lrwxr-xr-x 1  root   sapsys 7 May 5 11:35 SYS -> IDS/SYS
 drwxrwxr-x 2  idsadm sapsys 512 May 5 13:00 tmp
 drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans</screen>
    
         <para>I also found SAP notes (0029227 and 0008401) describing
         this behavior. I did not encounter any of these problems with
 	the <application>SAP 4.6C</application>-installation.</para>
       </sect3>
 
       <sect3 id="rfcrswboiniindind">
         <title>[RFCRSWBOINI_IND_IND] During R3SETUP</title>
 
 	<para>During installation of <application>SAP 4.6C</application>,
           this error was just the result of another error happening
 	  earlier during installation. In this case, you have to look
 	  through the corresponding logfiles and correct the real
 	  problem.</para>
 
         <para>If after looking through the logfiles this error is
 	  indeed the correct one (check the SAP-notes), you can set 
 	  STATUS of the offending step from ERROR to OK (file
 	  <filename>CENTRDB.R3S</filename>) and restart R3SETUP. After
 	  installation, you have to execute the report
 	  <literal>RSWBOINS</literal> from transaction SE38. See SAP
 	  note 0162266 for additional information about phase
 	  <literal>RFCRSWBOINI</literal> and
 	  <literal>RFCRADDBDIF</literal>.</para>
       </sect3>
 
       <sect3 id="rfcraddbdifindind">
         <title>[RFCRADDBDIF_IND_IND] During R3SETUP</title>
 	<para>Here the same restrictions apply: Make sure by looking
 	  through the logfiles, that this error is not caused by some
 	  previous problems.</para>
 
         <para>If you can confirm that SAP-Note 0162266 applies, just 
 	  set STATUS of the offending step from ERROR to OK (file
 	  <filename>CENTRDB.R3S</filename>) and restart R3SETUP. After
 	  installation, you have to execute the report
 	  <literal>RADDBDIF</literal> from transaction SE38.</para>
       </sect3>
 
       <sect3 id="sigactionsig31">
         <title>sigaction sig31: File size limit exceeded</title>
 
 	<para>This error occured during start of SAP-processes
 	  <emphasis>disp+work</emphasis>. If starting SAP with the
 	  startsap-script, subprocesses are then started which
 	  detach and do the dirty work of starting all other SAP 
           processes. As a result, the script itself won't notice
 	  if something goes wrong.</para>
 
 	<para>To check whether the SAP processes did start properly,
 	  have a look at the process status with 
 	  <command>ps ax | grep <replaceable>SID</replaceable></command>, which will give
 	  you a list of all Oracle- and SAP-processes. If it looks like
 	  some processes are missing or if you can't connect to the SAP-System,
 	  look at the corresponding logfiles which can be found
 	  at <filename>/usr/sap/<replaceable>SID</replaceable>/DVEBMGS<replaceable>nr</replaceable>/work/</filename>.
 	  The files to look at are <filename>dev_ms</filename> and 
 	  <filename>dev_disp</filename>.</para>
 
 	<para>Signal 31 happens here if the amount of shared memory used by
 	  Oracle and SAP exceed the one defined within the kernel configuration
 	  file and could be resolved by using a larger value:</para>
 
         <programlisting># larger value for 46C production systems:
 options SHMMAXPGS=393216
 # smaller value sufficient for 46B:
 #options SHMMAXPGS=262144</programlisting>
 	  
       </sect3>
 
       <sect3 id="saposcolfails">
         <title>Start of saposcol failed</title>
 	<para>There are some problems with Program saposcol (version 4.6D).
 	  The SAP-System is using saposcol to collect data about the 
 	  system performance. This program is not needed to use the SAP-System,
 	  so this problem can be considered a minor one. The older versions
 	  (4.6B) does work, but doesn't collect all the data (many calls will
 	  just return 0, for example for CPU usage).</para>
       </sect3>
     </sect2>
   </sect1>
 
-  <sect1>
+  <sect1 id="linuxemu-advanced">
     <title>Advanced Topics</title>
 
     <para>If you are curious as to how the Linux binary compatibility
       works, this is the section you want to read.  Most of what follows
       is based heavily on an email written to &a.chat; by Terry Lambert
       <email>tlambert@primenet.com</email> (Message ID:
       <literal>&lt;199906020108.SAA07001@usr09.primenet.com&gt;</literal>).</para>
 
     <sect2>
       <title>How Does It Work?</title>
       <indexterm><primary>execution class loader</primary></indexterm>
 
       <para>FreeBSD has an abstraction called an <quote>execution class
 	loader</quote>.  This is a wedge into the &man.execve.2; system
 	call.</para>
 
       <para>What happens is that FreeBSD has a list of loaders, instead of
 	a single loader with a fallback to the <literal>#!</literal>
 	loader for running any shell interpreters or shell scripts.</para>
 
       <para>Historically, the only loader on the Unix platform examined
 	the magic number (generally the first 4 or 8 bytes of the file) to
 	see if it was a binary known to the system, and if so, invoked the
 	binary loader.</para>
 
       <para>If it was not the binary type for the system, the
 	&man.execve.2; call returned a failure, and the shell attempted to
 	start executing it as shell commands.</para>
 
       <para>The assumption was a default of <quote>whatever the current
 	shell is</quote>.</para>
 
       <para>Later, a hack was made for &man.sh.1; to examine the first two
 	characters, and if they were <literal>:\n</literal>, then it
 	invoked the &man.csh.1; shell instead (we believe SCO first made
 	this hack).</para>
 
       <para>What FreeBSD does now is go through a list of loaders, with a
 	generic <literal>#!</literal> loader that knows about interpreters
 	as the characters which follow to the next whitespace next to
 	last, followed by a fallback to
 	<filename>/bin/sh</filename>.</para>
       <indexterm><primary>ELF</primary></indexterm>
 
       <para>For the Linux ABI support, FreeBSD sees the magic number as an
 	ELF binary (it makes no distinction between FreeBSD, Solaris,
 	Linux, or any other OS which has an ELF image type, at this
 	point).</para>
       <indexterm><primary>Solaris</primary></indexterm>
 
       <para>The ELF loader looks for a specialized
 	<emphasis>brand</emphasis>, which is a comment section in the ELF
 	image, and which is not present on SVR4/Solaris ELF
 	binaries.</para>
 
       <para>For Linux binaries to function, they must be
 	<emphasis>branded</emphasis> as type <literal>Linux</literal>;
 	from &man.brandelf.1;:</para>
 
       <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen>
 
       <para>When this is done, the ELF loader will see the
 	<literal>Linux</literal> brand on the file.</para>
       <indexterm>
         <primary>ELF</primary>
 	<secondary>branding</secondary>
       </indexterm>
 
       <para>When the ELF loader sees the <literal>Linux</literal> brand,
 	the loader replaces a pointer in the <literal>proc</literal>
 	structure.  All system calls are indexed through this pointer (in
 	a traditional Unix system, this would be the
 	<literal>sysent[]</literal> structure array, containing the system
 	calls).  In addition, the process is flagged for special handling of
 	the trap vector for the signal trampoline code, and several other
 	(minor) fix-ups that are handled by the Linux kernel
 	module.</para>
 
       <para>The Linux system call vector contains, among other things, a
 	list of <literal>sysent[]</literal> entries whose addresses reside
 	in the kernel module.</para>
 
       <para>When a system call is called by the Linux binary, the trap
 	code dereferences the system call function pointer off the
 	<literal>proc</literal> structure, and gets the Linux, not the
 	FreeBSD, system call entry points.</para>
 
       <para>In addition, the Linux mode dynamically
 	<emphasis>reroots</emphasis> lookups; this is, in effect, what the
 	<literal>union</literal> option to FS mounts
 	(<emphasis>not</emphasis> the unionfs!) does.  First, an attempt
 	is made to lookup the file in the
 	<filename>/compat/linux/<replaceable>original-path</replaceable></filename>
 	directory, <emphasis>then</emphasis> only if that fails, the
 	lookup is done in the
 	<filename>/<replaceable>original-path</replaceable></filename>
 	directory.  This makes sure that binaries that require other
 	binaries can run (e.g., the Linux toolchain can all run under
 	Linux ABI support).  It also means that the Linux binaries can
 	load and exec FreeBSD binaries, if there are no corresponding
 	Linux binaries present, and that you could place a &man.uname.1;
 	command in the <filename>/compat/linux</filename> directory tree
 	to ensure that the Linux binaries could not tell they were not
 	running on Linux.</para>
 
       <para>In effect, there is a Linux kernel in the FreeBSD kernel; the
 	various underlying functions that implement all of the services
 	provided by the kernel are identical to both the FreeBSD system
 	call table entries, and the Linux system call table entries: file
 	system operations, virtual memory operations, signal delivery,
 	System V IPC, etc&hellip;  The only difference is that FreeBSD
 	binaries get the FreeBSD <emphasis>glue</emphasis> functions, and
 	Linux binaries get the Linux <emphasis>glue</emphasis> functions
 	(most older OS's only had their own <emphasis>glue</emphasis>
 	functions: addresses of functions in a static global
 	<literal>sysent[]</literal> structure array, instead of addresses
 	of functions dereferenced off a dynamically initialized pointer in
 	the <literal>proc</literal> structure of the process making the
 	call).</para>
 
       <para>Which one is the native FreeBSD ABI?  It does not matter.
 	Basically the only difference is that (currently; this could
 	easily be changed in a future release, and probably will be after
 	this) the FreeBSD <emphasis>glue</emphasis> functions are
 	statically linked into the kernel, and the Linux glue functions
 	can be statically linked, or they can be accessed via a kernel
 	module.</para>
 
       <para>Yeah, but is this really emulation?  No.  It is an ABI
 	implementation, not an emulation.  There is no emulator (or
 	simulator, to cut off the next question) involved.</para>
 
       <para>So why is it sometimes called <quote>Linux emulation</quote>?
 	To make it hard to sell FreeBSD!  Really, it
 	is because the historical implementation was done at a time when
 	there was really no word other than that to describe what was
 	going on; saying that FreeBSD ran Linux binaries was not true, if
 	you did not compile the code in or load a module, and there needed
 	to be a word to describe what was being loaded&mdash;hence
 	<quote>the Linux emulator</quote>.</para>
     </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml
index c7b48ea0d7..ce34c8abd8 100644
--- a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml
@@ -1,1254 +1,1254 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="mail">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Bill</firstname>
 	<surname>Lloyd</surname>
 	<contrib>Original work by </contrib>
       </author>
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Rewritten by </contrib>
 	<!-- 2 Dec 1999 -->
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Electronic Mail</title>
 
-  <sect1>
+  <sect1 id="mail-synopsis">
     <title>Synopsis</title>
     <indexterm><primary>email</primary></indexterm>
     <indexterm><primary>electronic mail</primary></indexterm>
 
     <para><quote>Electronic Mail</quote>, better known as email, is one of the
       most widely used forms of communication today.  This chapter provides
       a basic introduction to running a mail server on FreeBSD.
       However, it is not a complete reference and in fact many
       important considerations are omitted.  For more complete
       coverage of the subject, the reader is referred to the many
       excellent books listed in <xref linkend="bibliography">.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>What software components are involved in sending and receiving
 	  electronic mail.</para>
       </listitem>
 
       <listitem>
 	<para>Where basic <application>sendmail</application> configuration
 	  files are located in FreeBSD.</para>
       </listitem>
 
       <listitem>
 	<para>How to block spammers from illegally using your mail server as a
 	  relay.</para>
       </listitem>
 
       <listitem>
 	<para>How to install and configure an alternate mail transfer agent on
 	  your system, replacing <application>sendmail</application>.</para>
       </listitem>
 
       <listitem>
 	<para>How to troubleshoot common mail server problems.</para>
       </listitem>
       
       <listitem>
         <para>How to configure SMTP Authentication for added security.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Properly setup your network connection
 	  (<xref linkend="advanced-networking">).</para>
       </listitem>
 
       <listitem>
 	<para>Properly setup the DNS information for your mail host
 	  (<xref linkend="advanced-networking">).</para>
       </listitem>
 
       <listitem>
 	<para>Know how to install additional third-party software
 	  (<xref linkend="ports">).</para></listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="mail-using">
     <title>Using Electronic Mail</title>
     <indexterm><primary>POP</primary></indexterm>
     <indexterm><primary>IMAP</primary></indexterm>
     <indexterm><primary>DNS</primary></indexterm>
 
     <para>There are five major parts involved in an email exchange.  They
       are: <link linkend="mail-mua">the user program</link>, <link
       linkend="mail-mta">the server daemon</link>, <link
       linkend="mail-dns">DNS</link>, <link linkend="mail-receive">a POP or
       IMAP daemon</link>, and of course, <link linkend="mail-host">the
       mailhost itself</link>.</para>
 
     <sect2 id="mail-mua">
       <title>The User Program</title>
 
       <para>This includes command line programs such as
         <application>mutt</application>, <application>pine</application>,
 	<application>elm</application>, and
 	<application>mail</application>, and GUI programs such as
 	<application>balsa</application>,
 	<application>xfmail</application> to name a few, and something
 	more <quote>sophisticated</quote> like a WWW browser.  These
 	programs simply pass off the email transactions to the local <link
 	linkend="mail-host"><quote>mailhost</quote></link>, either by
 	calling one of the <link linkend="mail-mta">server daemons</link>
 	available or delivering it over TCP.</para>
     </sect2>
 
     <sect2 id="mail-mta">
       <title>Mailhost Server Daemon</title>
       <indexterm>
         <primary>mail server daemons</primary>
         <secondary><application>sendmail</application></secondary>
       </indexterm>
       <indexterm>
         <primary>mail server daemons</primary>
         <secondary><application>postfix</application></secondary>
       </indexterm>
       <indexterm>
         <primary>mail server daemons</primary>
         <secondary><application>qmail</application></secondary>
       </indexterm>
       <indexterm>
         <primary>mail server daemons</primary>
         <secondary><application>exim</application></secondary>
       </indexterm>
 
       <para>This is usually <application>sendmail</application> (by
         default with FreeBSD) or one of the other mail server daemons such
 	as <application>qmail</application>,
 	<application>postfix</application>, or
 	<application>exim</application>.  There are others, but those are
 	the most widely used.</para>
 
       <para>The server daemon usually has two functions&mdash;it looks
         after receiving incoming mail and delivers outgoing mail.  It does
 	not allow you to connect to it via POP or IMAP to read your mail.
 	You need an additional <link linkend="mail-receive">daemon</link>
 	for that.</para>
 
       <para>Be aware that some older versions of
         <application>sendmail</application> have some serious security
 	problems, however as long as you run a current version of it you
 	should not have any problems.  As always, it is a good idea to
 	stay up-to-date with any software you run.</para>
     </sect2>
 
     <sect2 id="mail-dns">
       <title>Email and DNS</title>
 
       <para>The Domain Name System (DNS) and its daemon
         <command>named</command> play a large role in the delivery of
 	email.  In order to deliver mail from your site to another, the
 	server daemon will look up the site in the DNS to determine the
 	host that will receive mail for the destination.</para>
 
       <para>It works the same way when you have mail sent to you.  The DNS
         contains the database mapping hostname to an IP address, and a
 	hostname to mailhost.  The IP address is specified in an A record.
 	The MX (Mail eXchanger) record specifies the mailhost that will
 	receive mail for you.  If you do not have an MX record for your
 	hostname, the mail will be delivered directly to your host.</para>
     </sect2>
 
     <sect2 id="mail-receive">
       <title>Receiving Mail</title>
       <indexterm>
         <primary>email</primary>
         <secondary>receiving</secondary>
       </indexterm>
 
       <para>Receiving mail for your domain is done by the mail host.  It
         will collect mail sent to you and store it for reading or pickup.
 	In order to pick the stored mail up, you will need to connect to
 	the mail host.  This is done by either using POP or IMAP.  If you
 	want to read mail directly on the mail host, then a POP or IMAP
 	server is not needed.</para>
 
       <indexterm><primary>POP</primary></indexterm>
       <indexterm><primary>IMAP</primary></indexterm>
       <para>If you want to run a POP or IMAP server, there are two things
         you need to do:</para>
 
       <procedure>
         <step>
 	  <para>Get a POP or IMAP daemon from the <ulink
 	    url="../../../../ports/mail.html">ports collection</ulink> and install
 	    it on your system.</para>
 	</step>
 
 	<step>
 	  <para>Modify <filename>/etc/inetd.conf</filename> to load the
 	    POP or IMAP server.</para>
 	</step>
       </procedure>
     </sect2>
 
     <sect2 id="mail-host">
       <title>The Mail Host</title>
       <indexterm><primary>mail host</primary></indexterm>
 
       <para>The mail host is the name given to a server that is
         responsible for delivering and receiving mail for your host, and
 	possibly your network.</para>
     </sect2>
   </sect1>
 
   <sect1 id="sendmail">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Christopher</firstname>
           <surname>Shumway</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title><application>sendmail</application> Configuration</title>
 
     <indexterm>
       <primary><application>sendmail</application></primary>
     </indexterm>
 
     <para>&man.sendmail.8; is the default Mail Transfer Agent (MTA) in
       FreeBSD.  <application>sendmail</application>'s job is to accept
       mail from Mail User Agents (MUA) and deliver it to the
       appropriate mailer as defined by its configuration file.
       <application>sendmail</application> can also accept network
       connections and deliver mail to local mailboxes or deliver it to
       another program.</para>
 
     <para><application>sendmail</application> uses the following
       configuration files:</para>
 
     <indexterm>
       <primary><filename>/etc/mail/access</filename></primary>
     </indexterm>
     <indexterm>
       <primary><filename>/etc/mail/aliases</filename></primary>
     </indexterm>
     <indexterm>
       <primary><filename>/etc/mail/local-host-names</filename></primary>
     </indexterm>
     <indexterm>
       <primary><filename>/etc/mail/mailer.conf</filename></primary>
     </indexterm>
     <indexterm>
       <primary><filename>/etc/mail/mailertable</filename></primary>
     </indexterm>
     <indexterm>
       <primary><filename>/etc/mail/sendmail.cf</filename></primary>
     </indexterm>
     <indexterm>
       <primary><filename>/etc/mail/virtusertable</filename></primary>
     </indexterm>
     <informaltable>
       <tgroup cols="2">
 	<thead>
 	  <row>
 	    <entry>Filename</entry>
 	    <entry>Function</entry>
 	  </row>
 	</thead>
 	<tbody>
 	  <row>
 	    <entry>
 	      <filename>/etc/mail/access</filename>
 	    </entry>
 	    <entry><application>sendmail</application> access database
  	      file</entry>
 	  </row>
 	  <row>
 	    <entry>
 	      <filename>/etc/mail/aliases</filename>
 	    </entry>
 	    <entry>Mailbox aliases</entry>
 	  </row>
 	  <row>
 	    <entry>
 	      <filename>/etc/mail/local-host-names</filename>
 	    </entry>
 	    <entry>Lists of hosts <application>sendmail</application>
 	    accepts mail for</entry>
     </row>
 	  <row>
 	    <entry>
 	      <filename>/etc/mail/mailer.conf</filename>
 	    </entry>
 	    <entry>Mailer program configuration</entry>
 	  </row>
 	  <row>
 	    <entry>
 	      <filename>/etc/mail/mailertable</filename>
 	    </entry>
 	    <entry>Mailer delivery table</entry>
 	  </row>
 	  <row>
 	    <entry>
 	      <filename>/etc/mail/sendmail.cf</filename>
 	    </entry>
 	    <entry><application>sendmail</application> master
 	    configuration file</entry>
 	  </row>
 	  <row>
 	    <entry>
 	      <filename>/etc/mail/virtusertable</filename>
 	    </entry>
 	    <entry>Virtual users and domain tables</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
 
   <sect2>
     <title><filename>/etc/mail/access</filename></title>
 
     <para>The access database defines what host(s) or IP addresses
       have access to the local mail server and what kind of access
       they have.  Hosts can be listed as <option>OK</option>,
       <option>REJECT</option>, <option>RELAY</option> or simply passed
       to <application>sendmail</application>'s error handling routine with a given mailer error.
       Hosts that are listed as <option>OK</option>, which is the
       default, are allowed to send mail to this host as long as the
       mail's final destination is the local machine.  Hosts that are
       listed as <option>REJECT</option> are rejected for all mail
       connections.  Hosts that have the <option>RELAY</option> option
       for their hostname are allowed to send mail for any destination
       through this mail server.</para>
 
       <example>
 	<title>Configuring the <application>sendmail</application>
   	  Access Database</title>
 
     <programlisting>cyberspammer.com                550 We don't accept mail from spammers
 FREE.STEALTH.MAILER@            550 We don't accept mail from spammers
 another.source.of.spam          REJECT
 okay.cyberspammer.com           OK
 128.32                          RELAY</programlisting>
       </example>
 
    <para>In this example we have five entries.  Mail senders that
      match the left hand side of the table are affected by the action
      on the right side of the table.  The first two examples give an
      error code to <application>sendmail</application>'s error
      handling routine.  The message is printed to the remote host when
      a mail matches the left hand side of the table.  The next entry
      rejects mail from a specific host on the Internet,
      <hostid>another.source.of.spam</hostid>.  The next entry accepts
      mail connections from a host
      <hostid role="fqdn">okay.cyberspammer.com</hostid>, which is more exact than
      the <hostid role="domainname">cyberspammer.com</hostid> line above.  More specific
      matches override less exact matches.  The last entry allows
      relaying of electronic mail from hosts with an IP address that
      begins with <hostid>128.32</hostid>.  These hosts would be able
      to send mail through this mail server that are destined for other
      mail servers.</para>
 
    <para>When this file is updated, you need to run
      <command>make</command> in <filename>/etc/mail/</filename> to
      update the database.</para>
 
    </sect2>
    <sect2>
     <title><filename>/etc/mail/aliases</filename></title>
 
     <para>The aliases database contains a list of virtual mailboxes
       that are expanded to other user(s), files, programs or other
       aliases.  Here are a few examples that can be used in
       <filename>/etc/mail/aliases</filename>:</para>
 
       <example>
 	<title>Mail Aliases</title>
     <programlisting>root: localuser
 ftp-bugs: joe,eric,paul
 bit.bucket:  /dev/null
 procmail: "|/usr/local/bin/procmail"</programlisting>
       </example>
 
       <para>The file format is simple; the mailbox name on the left
 	side of	the colon is expanded to the target(s) on the right.
 	The
 	first example simply expands the mailbox <username>root</username>
 	to the mailbox <username>localuser</username>, which is then
 	looked up again in the aliases database.  If no match is found,
 	then the message is delivered to the local user
 	<username>localuser</username>.  The next example shows a mail
 	list.  Mail to the mailbox <username>ftp-bugs</username> is
 	expanded to the three local mailboxes <username>joe</username>,
 	<username>eric</username>, and <username>paul</username>.  Note
 	that a remote mailbox could be specified as <literal>user@example.com</literal>.  The
 	next example shows writing mail to a file, in this case
 	<filename>/dev/null</filename>.  The last example shows sending
 	mail to a program, in this case the mail message is written to the
 	standard input of <filename>/usr/local/bin/procmail</filename>
 	through a Unix pipe.</para>
 
    <para>When this file is updated, you need to run
    <command>make</command> in <filename>/etc/mail/</filename> to
    update the database.</para>
   </sect2>
   <sect2>
     <title><filename>/etc/mail/local-host-names</filename></title>
 
     <para>This is a list of hostnames &man.sendmail.8; is to accept as
       the local host name.  Place any domains or hosts that
       <application>sendmail</application> is to be receiving mail for.
       For example, if this mail server was to accept mail for the
       domain <hostid role="domainname">example.com</hostid> and the host
       <hostid role="fqdn">mail.example.com</hostid>, its
       <filename>local-host-names</filename> might look something like
       this:</para>
 
     <programlisting>example.com
 mail.example.com</programlisting>
 
     <para>When this file is updated, &man.sendmail.8; needs to be
     restarted to read the changes.</para>
 
   </sect2>
 
   <sect2>
     <title><filename>/etc/mail/sendmail.cf</filename></title>
 
     <para><application>sendmail</application>'s master configuration
       file, <filename>sendmail.cf</filename> controls the overall
       behavior of <application>sendmail</application>, including everything
       from rewriting e-mail addresses to printing rejection messages to
       remote mail servers.  Naturally, with such a diverse role, this
       configuration file is quite complex and its details are a bit
       out of the scope of this section.  Fortunately, this file rarely
       needs to be changed for standard mail servers.</para>
 
     <para>The master <application>sendmail</application> configuration
       file can be built from &man.m4.1; macros that define the features
       and behavior of <application>sendmail</application>.  Please see
       <filename>/usr/src/contrib/sendmail/cf/README</filename> for
       some of the details.</para>
 
     <para>When changes to this file are made,
       <application>sendmail</application> needs to be restarted for
       the changes to take effect.</para>
 
   </sect2>
   <sect2>
     <title><filename>/etc/mail/virtusertable</filename></title>
 
     <para>The <filename>virtusertable</filename> maps mail addresses for
       virtual domains and
       mailboxes to real mailboxes.  These mailboxes can be local,
       remote, aliases defined in
       <filename>/etc/mail/aliases</filename> or files.</para>
 
     <example>
 	<title>Example Virtual Domain Mail Map</title>
 
     <programlisting>root@example.com                root
 postmaster@example.com          postmaster@noc.example.net
 @example.com                    joe</programlisting>
       </example>
 
     <para>In the above example, we have a mapping for a domain
       <hostid role="domainname">example.com</hostid>.  This file is processed in a
       first match order down the file.  The first item maps
       <literal>root@example.com</literal> to the local mailbox <username>root</username>.  The next entry maps
       <literal>postmaster@example.com</literal> to the mailbox <username>postmaster</username> on the host
       <hostid role="fqdn">noc.example.net</hostid>.  Finally, if nothing from <hostid role="domainname">example.com</hostid> has
       matched so far, it will match the last mapping, which matches
       every other mail message addressed to someone at
       <hostid role="domainname">example.com</hostid>.
       This will be mapped to the local mailbox <username>joe</username>.</para>
 
   </sect2>
   </sect1>
 
   <sect1 id="mail-changingmta">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Andrew</firstname>
           <surname>Boothman</surname>
           <contrib>Written by </contrib>
         </author>
       </authorgroup>
       <authorgroup>
         <author>
           <firstname>Gregory</firstname>
           <surname>Neil Shapiro</surname>
           <contrib>Information taken from e-mails written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Changing your Mail Transfer Agent</title>
     <indexterm>
       <primary>email</primary>
       <secondary>change mta</secondary>
     </indexterm>
 
     <para>As already mentioned, FreeBSD comes with
       <application>sendmail</application> already installed as your
       MTA (Mail Transfer Agent).  Therefore by default it is
       in charge of your outgoing and incoming mail.</para>
 
     <para>However, for a variety of reasons, some system
       administrators want to change their system's MTA.  These
       reasons range from simply wanting to try out another MTA to
       needing a specific feature or package which relies on another
       mailer.  Fortunately, whatever the reason, FreeBSD makes it
       easy to make the change.</para>
 
     <sect2>
       <title>Install a new MTA</title>
 
       <para>You have a wide choice of MTAs available.  A good
 	starting point is the
 	<link linkend="ports">FreeBSD Ports Collection</link> where
 	you will be able to find many.  Of course you are free to use
 	any MTA you want from any location, as long as you can make
 	it run under FreeBSD.</para>
 
       <para>Start by installing your new MTA.  Once it is installed
 	it gives you a chance to decide if it really fulfills your
 	needs, and also gives you the opportunity to configure your
 	new software before getting it to take over from
 	<application>sendmail</application>.  When doing this, you
 	should be sure that installing the new software won't attempt
 	to overwrite system binaries such as
 	<filename>/usr/bin/sendmail</filename>.  Otherwise, your new
 	mail software has essentially been put into service before
 	you have configured it.</para>
 
       <para>Please refer to your chosen MTA's documentation for
 	information on how to configure the software you have
 	chosen.</para>
     </sect2>
 
     <sect2>
       <title>Disable <application>sendmail</application></title>
 
       <para>The procedure used to start
 	<application>sendmail</application> changed significantly
 	between 4.5-RELEASE and 4.6-RELEASE.  Therefore, the procedure
 	used to disable it is subtly different.</para>
 
       <sect3>
 	<title>FreeBSD 4.5-STABLE before 2002/4/4 and earlier
 	  (including 4.5-RELEASE and earlier)</title>
 
 	<para>Enter:</para>
 
 	  <programlisting>sendmail_enable="NO"</programlisting>
 
 	  <para>into <filename>/etc/rc.conf</filename>.  This will disable
 	  <application>sendmail</application>'s incoming mail service,
 	  but if <filename>/etc/mail/mailer.conf</filename> (see below)
 	  is not changed, <application>sendmail</application> will
 	  still be used to send e-mail.</para>
       </sect3>
 
       <sect3>
 	<title>FreeBSD 4.5-STABLE after 2002/4/4
 	  (including 4.6-RELEASE and later)</title>
 
 	<para>In order to completely disable
 	  <application>sendmail</application> you must use</para>
 
 	  <programlisting>sendmail_enable="NONE"</programlisting>
 
 	  <para>in <filename>/etc/rc.conf.</filename></para>
 
 	<warning>
 	  <para>If you disable <application>sendmail</application>'s
 	    outgoing mail service in this way, it is important that you
 	    replace it with a fully working alternative mail delivery
 	    system.  If you choose not to, system functions such as
 	    &man.periodic.8; will be unable to deliver their results by
 	    e-mail as they would normally expect to.  Many parts of your
 	    system may expect to have a functional
 	    <application>sendmail</application>-compatible system.  If
 	    applications continue to use
 	    <application>sendmail</application>'s binaries to try and send
 	    e-mail after you have disabled them, mail could go into an
 	    inactive <application>sendmail</application> queue, and never be delivered.</para>
 	</warning>
 
 	<para>If you only want to disable
 	  <application>sendmail</application>'s incoming mail service,
 	  you should set</para>
 
 	  <programlisting>sendmail_enable="NO"</programlisting>
 
 	<para>in <filename>/etc/rc.conf</filename>.  More information on
 	  <application>sendmail</application>'s startup options is
 	  available from the &man.rc.sendmail.8; manual page.</para>
       </sect3>
 
     <sect2>
       <title>Running your new MTA on boot</title>
 
       <para>You may have a choice of two methods for running your
 	new MTA on boot, again depending on what version of FreeBSD
 	you are running.</para>
 
       <sect3>
 	<title>FreeBSD 4.5-STABLE before 2002/4/11
 	  (including 4.5-RELEASE and earlier)</title>
 
 	<para>Add a script to
 	  <filename>/usr/local/etc/rc.d/</filename> that
 	  ends in <filename>.sh</filename> and is executable by
 	  <username>root</username>.  The script should accept <literal>start</literal> and
 	  <literal>stop</literal> parameters.  At startup time the
 	  system scripts will execute the command</para>
 
 	<programlisting>/usr/local/etc/rc.d/supermailer.sh start</programlisting>
 
 	<para>which you can also use to manually start the server.  At
 	  shutdown time, the system scripts will use the
 	  <literal>stop</literal> option, running the command</para>
 
 	<programlisting>/usr/local/etc/rc.d/supermailer.sh stop</programlisting>
 
 	<para>which you can also use to manually stop the server
 	  while the system is running.</para>
 
       </sect3>
 
       <sect3>
 	<title>FreeBSD 4.5-STABLE after 2002/4/11
 	  (including 4.6-RELEASE and later)</title>
 
 	<para>With later versions of FreeBSD, you can use the
 	  above method or you can set</para>
 
 	<programlisting>mta_start_script="filename"</programlisting>
 
 	<para>in <filename>/etc/rc.conf</filename>, where
 	  <replaceable>filename</replaceable> is the name of some
 	  script that you want executed at boot to start your
 	  MTA.</para>
       </sect3>
 
     </sect2>
 
     <sect2>
       <title>Replacing <application>sendmail</application> as
        the system's default mailer</title>
 
       <para>The program <application>sendmail</application> is so ubiquitous
 	as standard software on Unix systems that some software
 	just assumes it is already installed and configured.
 	For this reason, many alternative MTA's provide their own compatible
 	implementations of the <application>sendmail</application>
 	command-line interface; this facilitates using them as
 	<quote>drop-in</quote> replacements for <application>sendmail</application>.</para>
 
       <para>Therefore, if you are using an alternative mailer,
 	you will need to make sure that software trying to execute
 	standard <application>sendmail</application> binaries such as
 	<filename>/usr/bin/sendmail</filename> actually executes
 	your chosen mailer instead.  Fortunately, FreeBSD provides
 	a system called &man.mailwrapper.8; that does this job for
 	you.</para>
 
       <para>When <application>sendmail</application> is operating as installed, you will
 	find something like the following
 	in <filename>/etc/mail/mailer.conf</filename>:</para>
 
 <programlisting>sendmail	 /usr/libexec/sendmail/sendmail
 send-mail	/usr/libexec/sendmail/sendmail
 mailq		/usr/libexec/sendmail/sendmail
 newaliases	/usr/libexec/sendmail/sendmail
 hoststat	/usr/libexec/sendmail/sendmail
 purgestat	/usr/libexec/sendmail/sendmail</programlisting>
 
       <para>This means that when any of these common commands
 	(such as <filename>sendmail</filename> itself) are run,
 	the system actually invokes a copy of mailwrapper named <filename>sendmail</filename>, which
 	checks <filename>mailer.conf</filename> and
 	executes <filename>/usr/libexec/sendmail/sendmail</filename>
 	instead.  This system makes it easy to change what binaries
 	are actually executed when these default <filename>sendmail</filename> functions
 	are invoked.</para>
 
       <para>Therefore if you wanted
 	<filename>/usr/local/supermailer/bin/sendmail-compat</filename>
 	to be run instead of <application>sendmail</application>, you could change
 	<filename>/etc/mail/mailer.conf</filename> to read:</para>
 
 <programlisting>sendmail	 /usr/local/supermailer/bin/sendmail-compat
 send-mail	/usr/local/supermailer/bin/sendmail-compat
 mailq		/usr/local/supermailer/bin/mailq-compat
 newaliases	/usr/local/supermailer/bin/newaliases-compat
 hoststat	/usr/local/supermailer/bin/hoststat-compat
 purgestat	/usr/local/supermailer/bin/purgestat-compat</programlisting>
 
 	</sect2>
 
 	<sect2>
 	  <title>Finishing</title>
 
 	<para>Once you have everything configured the way you want it, you should
 	  either kill the <application>sendmail</application> processes that
 	  you no longer need and start the processes belonging to your new
 	  software, or simply reboot.  Rebooting will also
 	  give you the opportunity to ensure that you have correctly
 	  configured your system to start your new MTA automatically on boot.</para>
 
       </sect2>
     </sect1>
 
   <sect1 id="mail-trouble">
     <title>Troubleshooting</title>
     <indexterm>
       <primary>email</primary>
       <secondary>troubleshooting</secondary>
     </indexterm>
 
     <qandaset>
       <qandaentry>
         <question>
 	<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
 	  <hostid role="fqdn">foo.bar.edu</hostid> 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>
 
 	<indexterm><primary>BIND</primary></indexterm>
 	<para>Traditionally, this was allowed by BSD BIND resolvers.
 	  However the current version of <application>BIND</application>
 	  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:
 
           <programlisting>search foo.bar.edu bar.edu</programlisting>
 
           instead of the previous:
 
           <programlisting>domain foo.bar.edu</programlisting>
 
           into your <filename>/etc/resolv.conf</filename>.  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>
 	<para><application>sendmail</application> says <errorname>mail
 	  loops back to myself</errorname></para>
 	</question>
 
 	<answer>
 	<para>This is answered in the
 	<application>sendmail</application> FAQ as follows:</para>
 
         <programlisting>* I am getting <quote>Local configuration error</quote> messages, such as:
 
 553 relay.domain.net config error: mail loops back to myself
 554 &lt;user@domain.net&gt;... Local configuration error
 
 How can I solve this problem?
 
 You have asked mail to the domain (e.g., domain.net) to be
 forwarded to a specific host (in this case, relay.domain.net)
 by using an MX record, but the relay machine does not recognize
 itself as domain.net. Add domain.net to /etc/mail/local-host-names
 (if you are using FEATURE(use_cw_file)) or add <quote>Cw domain.net</quote>
 to /etc/mail/sendmail.cf.</programlisting>
 
         <para>The <application>sendmail</application> FAQ can be found at
 	  <ulink URL="http://www.sendmail.org/faq/"></ulink> and is
 	  recommended reading if you want to do any
 	  <quote>tweaking</quote> of your mail setup.</para>
 	</answer>
       </qandaentry>
 
       <indexterm><primary>PPP</primary></indexterm>
       <qandaentry>
         <question>
 	<para>How can I run a mail server on a dial-up PPP host?</para>
 	</question>
 
 	<answer>
 	<para>You want to connect a FreeBSD box on a LAN to the
 	  Internet.  The FreeBSD box will be a mail gateway for the LAN.
 	  The PPP connection is non-dedicated.</para>
 
 	<indexterm><primary>UUCP</primary></indexterm>
 
 	<para>There are at least two ways to do this.  One way is to use
 	  UUCP.</para>
 
 	<para>Another way is to get a full-time Internet server to provide secondary MX
 	  services for your domain.  For example, if your company's domain is
 	  <hostid role="domainname">example.com</hostid> and your Internet service provider has
 	  set <hostid role="domainname">example.net</hostid> up to provide secondary MX services
 	  to your domain:</para>
 
 	<programlisting>example.com.          MX        10      example.com.
                       MX        20      example.net.</programlisting>
 
 	<para>Only one host should be specified as the final recipient
 	  (add <literal>Cw example.com</literal> in
 	  <filename>/etc/mail/sendmail.cf</filename> on <hostid role="domainname">example.com</hostid>).</para>
 
 	<para>When the sending <command>sendmail</command> is trying to
 	  deliver the mail it will try to connect to you (<hostid role="domainname">example.com</hostid>) over the modem
 	  link.  It will most likely time out because you are not online.
 	  The program <application>sendmail</application> will automatically deliver it to the
 	  secondary MX site, i.e. your Internet provider (<hostid role="domainname">example.net</hostid>).  The secondary MX
 	  site will then periodically try to connect to
 	  your host and deliver the mail to the primary MX host (<hostid role="domainname">example.com</hostid>).</para>
 
 	<para>You might want to use something like this as a login
 	  script:</para>
 
 	<programlisting>#!/bin/sh
 # Put me in /usr/local/bin/pppmyisp
 ( sleep 60 ; /usr/sbin/sendmail -q ) &amp;
 /usr/sbin/ppp -direct pppmyisp</programlisting>
 
 	<para>If you are going to create a separate login script for a
 	  user you could use <command>sendmail -qRexample.com</command>
 	  instead in the script above. This will force all mail in your
 	  queue for <hostid role="domainname">example.com</hostid> to be processed immediately.</para>
 
 	<para>A further refinement of the situation is as follows:</para>
 
 	<para>Message stolen from the &a.isp;.</para>
 
 	<programlisting>&gt; we provide the secondary MX for a customer. The customer connects to
 &gt; our services several times a day automatically to get the mails to
 &gt; his primary MX (We do not call his site when a mail for his domains
 &gt; arrived). Our sendmail sends the mailqueue every 30 minutes. At the
 &gt; moment he has to stay 30 minutes online to be sure that all mail is
 &gt; gone to the primary MX.
 &gt;
 &gt; Is there a command that would initiate sendmail to send all the mails
 &gt; now? The user has not root-privileges on our machine of course.
 
 In the <quote>privacy flags</quote> section of sendmail.cf, there is a
 definition Opgoaway,restrictqrun
 
 Remove restrictqrun to allow non-root users to start the queue processing.
 You might also like to rearrange the MXs. We are the 1st MX for our
 customers like this, and we have defined:
 
 # If we are the best MX for a host, try directly instead of generating
 # local config error.
 OwTrue
 
 That way a remote site will deliver straight to you, without trying
 the customer connection.  You then send to your customer.  Only works for
 <quote>hosts</quote>, so you need to get your customer to name their mail
 machine <quote>customer.com</quote> as well as
 <quote>hostname.customer.com</quote> in the DNS.  Just put an A record in
 the DNS for <quote>customer.com</quote>.</programlisting>
         </answer>
       </qandaentry>
 
       <qandaentry>
         <question>
 	  <para>Why do I keep getting <errorname>Relaying
 	    Denied</errorname> errors when sending mail from other
 	    hosts?</para>
 	</question>
 
 	<answer>
 	  <para>In default FreeBSD installations,
  	    <application>sendmail</application> is configured to only
  	    send mail from the host it is running on.  For example, if
  	    a POP3 server is installed, then users will be able to
  	    check mail from school, work, or other remote locations
  	    but they still will not be able to send outgoing emails
  	    from outside locations.  Typically, a few moments after
  	    the attempt, an email will be sent from
  	    <application>MAILER-DAEMON</application> with a
  	    <errorname>5.7 Relaying Denied</errorname> error
  	    message.</para>
 
 	  <para>There are several ways to get around this.  The most
  	    straightforward solution is to put your ISP's address in
  	    a relay-domains file at
  	    <filename>/etc/mail/relay-domains</filename>.  A quick way
  	    to do this would be:</para>
 
 	  <screen>&prompt.root; <userinput>echo "your.isp.example.com" &gt; /etc/mail/relay-domains</userinput></screen>
 
 	  <para>After creating or editing this file you must restart
   	    <application>sendmail</application>.  This works great if
   	    you are a server administrator and do not wish to send mail
   	    locally, or would like to use a point and click
   	    client/system on another machine or even another ISP.  It
   	    is also very useful if you only have one or two email
   	    accounts set up.  If there is a large number of addresses
   	    to add, you can simply open this file in your favorite
   	    text editor and then add the domains, one per line:</para>
 
 	  <programlisting>your.isp.example.com
 other.isp.example.net
 users-isp.example.org
 www.example.org</programlisting>
 
 	  <para>Now any mail sent through your system, by any host in
 	    this list (provided the user has an account on your
 	    system), will succeed.  This is a very nice way to allow
 	    users to send mail from your system remotely without
 	    allowing people to send SPAM through your system.</para>
 
 	</answer>
       </qandaentry>
     </qandaset>
   </sect1>
 
   <sect1 id="mail-advanced">
     <title>Advanced Topics</title>
 
     <para>The following section covers more involved topics such as mail
       configuration and setting up mail for your entire domain.</para>
 
     <sect2 id="mail-config">
       <title>Basic Configuration</title>
       <indexterm>
         <primary>email</primary>
         <secondary>configuration</secondary>
       </indexterm>
 
       <para>Out of the box, you should be able to send email to external
         hosts as long as you have set up
 	<filename>/etc/resolv.conf</filename> or are running your own
 	name server.  If you would like to have mail for your host
 	delivered to the MTA (e.g., <application>sendmail</application>) on your own FreeBSD host, there are two methods:</para>
 
       <itemizedlist>
         <listitem>
           <para>Run your own name server and have your own domain.  For
 	    example, <hostid
 	    role="domainname">FreeBSD.org</hostid></para>
         </listitem>
 
         <listitem>
           <para>Get mail delivered directly to your host.  This is done by
 	    delivering mail directly to the current DNS name for your
 	    machine.  For example, <hostid
 	    role="fqdn">example.FreeBSD.org</hostid>.</para>
         </listitem>
       </itemizedlist>
 
       <indexterm><primary>SMTP</primary></indexterm>
       <para>Regardless of which of the above you choose, in order to have
         mail delivered directly to your host, it must have a permanent
         static IP address (not a dynamic address, as with most PPP dial-up configurations).  If you are behind a
         firewall, it must pass SMTP traffic on to you.  If you want to
         receive mail directly at your host, you need to be sure of either of two
         things:</para>
 
       <itemizedlist>
         <indexterm><primary>MX record</primary></indexterm>
         <listitem>
           <para>Make sure that the (lowest-numbered) MX record in your DNS points to your
 	    host's IP address.</para>
         </listitem>
 
         <listitem>
           <para>Make sure there is no MX entry in your DNS for your
 	    host.</para>
         </listitem>
       </itemizedlist>
 
       <para>Either of the above will allow you to receive mail directly at
         your host.</para>
 
       <para>Try this:</para>
 
       <screen>&prompt.root; <userinput>hostname</userinput>
 example.FreeBSD.org
 &prompt.root; <userinput>host example.FreeBSD.org</userinput>
 example.FreeBSD.org has address 204.216.27.XX</screen>
 
       <para>If that is what you see, mail directly to
         <email>yourlogin@example.FreeBSD.org</email> should work without
         problems (assuming <application>sendmail</application> is
         running correctly on <hostid role="fqdn">example.FreeBSD.org</hostid>).</para>
 
       <para>If instead you see something like this:</para>
 
       <screen>&prompt.root; <userinput>host example.FreeBSD.org</userinput>
 example.FreeBSD.org has address 204.216.27.XX
 example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.org</screen>
 
       <para>All mail sent to your host (<hostid
         role="fqdn">example.FreeBSD.org</hostid>) will end up being
 	collected on <hostid>hub</hostid> under the same username instead
 	of being sent directly to your host.</para>
 
       <para>The above information is handled by your DNS server.  The DNS
         record that carries mail routing information is the
         <emphasis>M</emphasis>ail e<emphasis>X</emphasis>change entry.  If
         no MX record exists, mail will be delivered directly to the host by
         way of its IP address.</para>
 
       <para>The MX entry for <hostid
         role="fqdn">freefall.FreeBSD.org</hostid> at one time looked like
         this:</para>
 
       <programlisting>freefall		MX	30	mail.crl.net
 freefall		MX	40	agora.rdrop.com
 freefall		MX	10	freefall.FreeBSD.org
 freefall		MX	20	who.cdrom.com</programlisting>
 
       <para>As you can see, <hostid>freefall</hostid> had many MX entries.
         The lowest MX number is the host that receives mail directly if
         available; if it's not accessible for some reason, the others
         (sometimes called <quote>backup MXes</quote>) accept messages
         temporarily, and pass it along when a lower-numbered host becomes
         available, eventually to the lowest-numbered host.</para>
 
       <para>Alternate MX sites should have separate Internet connections
         from your own in order to be most useful.  Your ISP or another
         friendly site should have no problem providing this service for
         you.</para>
     </sect2>
 
     <sect2 id="mail-domain">
       <title>Mail for Your Domain</title>
 
       <para>In order to set up a <quote>mailhost</quote> (a.k.a. mail
         server) you need to have any mail sent to various workstations
 	directed to it.  Basically, you want to <quote>claim</quote> any
 	mail for any hostname in your domain (in this case <hostid
 	role="fqdn">*.FreeBSD.org</hostid>) and divert it to your mail
 	server so your users can receive their mail on
 	the master mail server.</para>
 
       <indexterm><primary>DNS</primary></indexterm>
       <para>To make life easiest, a user account with the same
         <emphasis>username</emphasis> should exist on both machines.  Use
 	&man.adduser.8; to do this.</para>
 
       <para>The mailhost you will be using must be the designated mail
         exchanger for each workstation on the network.  This is done in
 	your DNS configuration like so:</para>
 
       <programlisting>example.FreeBSD.org	A	204.216.27.XX		; Workstation
 			MX	10 hub.FreeBSD.org	; Mailhost</programlisting>
 
       <para>This will redirect mail for the workstation to the mailhost no
         matter where the A record points.  The mail is sent to the MX
 	host.</para>
 
       <para>You cannot do this yourself unless you are running a DNS
         server.  If you are not, or cannot run your own DNS server, talk
 	to your ISP or whoever provides your DNS.</para>
 
       <para>If you are doing virtual email hosting, the following
         information will come in handy.  For this example, we
 	will assume you have a customer with his own domain, in this
 	case <hostid role="domainname">customer1.org</hostid>, and you want
 	all the mail for <hostid role="domainname">customer1.org</hostid>
 	sent to your mailhost, <hostid
 	role="fqdn">mail.myhost.com</hostid>.  The entry in your DNS
 	should look like this:</para>
 
       <programlisting>customer1.org		MX	10	mail.myhost.com</programlisting>
 
       <para>You do <emphasis>not</emphasis> need an A record for <hostid role="domainname">customer1.org</hostid> if you only
         want to handle email for that domain.</para>
 
       <note>
 	<para>Be aware that pinging <hostid
 	  role="domainname">customer1.org</hostid> will not work unless
 	  an A record exists for it.</para>
       </note>
 
       <para>The last thing that you must do is tell
         <application>sendmail</application> on your mailhost what domains
 	and/or hostnames it should be accepting mail for.  There are a few
 	different ways this can be done.  Either of the following will
 	work:</para>
 
       <itemizedlist>
         <listitem>
 	  <para>Add the hosts to your
 	  <filename>/etc/mail/local-host-names</filename> file if you are using the
 	  <literal>FEATURE(use_cw_file)</literal>.  If you are using
 	  a version of <application>sendmail</application> earlier than 8.10, the file is
 	  <filename>/etc/sendmail.cw</filename>.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Add a <literal>Cwyour.host.com</literal> line to your
 	    <filename>/etc/sendmail.cf</filename> or
 	    <filename>/etc/mail/sendmail.cf</filename> if you are using
 	    <application>sendmail</application> 8.10 or higher.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
   
   <sect1 id="SMTP-Auth">
     <title>SMTP Authentication</title>
     
     <para>Having <acronym>SMTP</acronym> Authentication in place on
       your mail server has a number of benefits.
       <acronym>SMTP</acronym> Authentication can add another layer
       of security to <application>sendmail</application>, and has the benefit of giving mobile
       users who switch hosts the ability to use the same mail server
       without the need to reconfigure their mail client settings
       each time.</para>
 
     <procedure>
       <step>
 	<para>Install <filename role="package">security/cyrus-sasl</filename>
 	  from the ports. You can find this port in
 	  <filename role="package">security/cyrus-sasl</filename>.
 	  <filename role="package">security/cyrus-sasl</filename> has
 	  a number of compile time options to choose from and, for
 	  the method we will be using here, make sure to select the
 	  <option>pwcheck</option> option.</para>
       </step>
 
 
       <step>
 	<para>After installing <filename role="package">security/cyrus-sasl</filename>,
 	  edit <filename>/usr/local/lib/sasl/Sendmail.conf</filename>
 	  (or create it if it does not exist) and add the following
 	  line:</para>
 
 	<programlisting>pwcheck_method: passwd</programlisting>
 
 	<para>This method will enable <application>sendmail</application>
 	  to authenticate against your FreeBSD <filename>passwd</filename>
 	  database.  This saves the trouble of creating a new set of usernames
 	  and passwords for each user that needs to use
 	  <acronym>SMTP</acronym> authentication, and keeps the login
 	  and mail password the same.</para>
       </step>
 
       <step>
 	<para>Now edit <filename>/etc/make.conf</filename> and add the
 	  following lines:</para>
 
 	<programlisting>SENDMAIL_CFLAGS=-I/usr/local/include/sasl1 -DSASL
 SENDMAIL_LDFLAGS=-L/usr/local/lib
 SENDMAIL_LDADD=-lsasl</programlisting>
 
 	<para>These lines will give <application>sendmail</application>
 	the proper configuration options for linking
 	to <filename role="package">cyrus-sasl</filename> at compile time.
 	Make sure that <filename role="package">cyrus-sasl</filename>
 	has been installed before recompiling
 	<application>sendmail</application>.</para>
       </step>
 
       <step>
 	<para>Recompile <application>sendmail</application> by executing the following commands:</para>
 
 	<screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail</userinput>
 &prompt.root; <userinput>make cleandir</userinput>
 &prompt.root; <userinput>make obj</userinput>
 &prompt.root; <userinput>make</userinput>
 &prompt.root; <userinput>make install</userinput></screen>
 
 	<para>The compile of <application>sendmail</application> should not have any problems
 	  if <filename>/usr/src</filename> has not been changed extensively
 	  and the shared libraries it needs are available.</para>
       </step>
 
       <step>
 	<para>After <application>sendmail</application> has been compiled
 	  and reinstalled, edit your <filename>/etc/mail/freebsd.mc</filename>
 	  file (or whichever file you use as your <filename>.mc</filename> file. Many administrators
 	  choose to use the output from &man.hostname.1; as the <filename>.mc</filename> file for
 	  uniqueness).  Add these lines to it:</para>
 
 	<programlisting>dnl set SASL options
 TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl
 define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl
 define(`confDEF_AUTH_INFO', `/etc/mail/auth-info')dnl</programlisting>
 
 	<para>These options configure the different methods available to
 	<application>sendmail</application> for authenticating users.
 	If you would like to use a method other than
 	<application>pwcheck</application>, please see the
 	included documentation.</para>
       </step>
 
       <step>
 	<para>Finally, run &man.make.1; while in <filename>/etc/mail</filename>.
 	  That will run your new <filename>.mc</filename> file and create a <filename>.cf</filename> file named
 	  <filename>freebsd.cf</filename> (or whatever name you've used
 	  for your <filename>.mc</filename> file). Copy that to <filename>sendmail.cf</filename>,
 	  and send a <command>kill -HUP</command> signal to
 	  <application>sendmail</application>.</para>
       </step>
     </procedure>
 
     <para>If all has gone correctly, you should be able to enter your login
       information into the mail client and send a test message.
       For further investigation, set the LogLevel of
       <application>sendmail</application> to 13 and watch
       <filename>/var/log/maillog</filename> for any errors.</para>
 
     <para>For more information, please see the <application>sendmail</application>
       page regarding
       <ulink url="http://www.sendmail.org/~ca/email/auth.html">
       <acronym>SMTP</acronym> authentication</ulink>.</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/mirrors/chapter.sgml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
index be9056a4a4..f0d0aa5dfd 100644
--- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
@@ -1,4687 +1,4687 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <appendix id="mirrors">
   <title>Obtaining FreeBSD</title>
 
-  <sect1>
+  <sect1 id="mirrors-cdrom">
     <title>CDROM Publishers</title>
 
     <sect2>
       <title>Retail Boxed Products</title>
 
       <para>FreeBSD is available as a boxed product (FreeBSD CDs,
 	additional software, and printed documentation) from several
 	retailers:</para>
 
       <itemizedlist>
 	<listitem>
 	  <address>
 	    <otheraddr>CompUSA</otheraddr>
 	    WWW: <otheraddr><ulink url="http://www.compusa.com/">http://www.compusa.com/</ulink></otheraddr>
 	  </address>
 	</listitem>
 
 	<listitem>
 	  <address>
 	    <otheraddr>Frys Electronics</otheraddr>
 	    WWW: <otheraddr><ulink url="http://www.frys.com/">http://www.frys.com/</ulink></otheraddr>
 	  </address>
 	</listitem>
 
 	<listitem>
 	  <address>
 	    <otheraddr>Staples</otheraddr>
 	    WWW: <otheraddr><ulink url="http://www.staples.com/">http://www.staples.com/</ulink></otheraddr>
 	  </address>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>CD Sets</title>
 
       <para>FreeBSD CD sets are available from many online
 	retailers:</para>
 
     <itemizedlist>
       <listitem>
         <address>
           <otheraddr>Daemon News Mall</otheraddr>
           <street>560 South State Street, Suite A2</street>
           <city>Orem</city>, <state>UT</state> <postcode>84058</postcode>
           <country>USA</country>
           Phone: <phone>+1 800 407-5170</phone>
           Fax: <fax>+1 1 801 765-0877</fax>
           Email: <email>sales@bsdmall.com</email>
           WWW: <otheraddr><ulink url="http://www.bsdmall.com/freebsd1.html">http://www.bsdmall.com/</ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>FreeBSD Mall, Inc.</otheraddr>
 	  <street>3623 Sanford Street</street>
 	  <city>Concord</city>, <state>CA</state>  <postcode>94520-1405</postcode>
 	  <country>USA</country>
 	  Phone: <phone>+1 925 674-0783</phone>
 	  Fax: <fax>+1 925 674-0821</fax>
 	  Email: <email>info@freebsdmall.com</email>
 	  WWW: <otheraddr><ulink url="http://www.freebsdmall.com/">http://www.freebsdmall.com/</ulink></otheraddr>
 	</address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>Hinner EDV</otheraddr>
 	  <street>St. Augustinus-Str. 10</street>
 	  <postcode>D-81825</postcode> <city>M&uuml;nchen</city>
 	  <country>Germany</country>
 	  Phone: <phone>(089) 428 419</phone>
 	  WWW: <otheraddr><ulink url="http://www.hinner.de/linux/freebsd.html">http://www.hinner.de/linux/freebsd.html</ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>Ingram Micro</otheraddr>
 	  <street>1600 E. St. Andrew Place</street>
 	  <city>Santa Ana</city>, <state>CA</state>  <postcode>92705-4926</postcode>
 	  <country>USA</country>
 	  Phone: <phone>1 (800) 456-8000</phone>
 	  WWW: <otheraddr><ulink url="http://www.ingrammicro.com/">http://www.ingrammicro.com/</ulink></otheraddr>
         </address>
       </listitem>
 
       <listitem>
 	<address>
 	  <otheraddr>The Linux Emporium</otheraddr>
 	  <street>Hilliard House, Lester Way</street>
 	  <city>Wallingford</city>
 	  <postcode>OX10 9TA</postcode>
 	  <country>United Kingdom</country>
 	  Phone: <phone>+44 1491 837010</phone>
 	  Fax: <fax>+44 1491 837016</fax>
 	  WWW: <otheraddr><ulink url="http://www.linuxemporium.co.uk/bsd.html#FreeBSD">http://www.linuxemporium.co.uk/bsd.html</ulink></otheraddr>
         </address>
       </listitem>
 
     </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Distributors</title>
 
       <para>If you are a reseller and want to carry FreeBSD CDROM products,
 	please contact a distributor:</para>
 
       <itemizedlist>
 	<listitem>
 	  <address>
 	    <otheraddr>Cylogistics</otheraddr>
 	    <street>2672 Bayshore Parkway, Suite 610</street>
 	    <city>Mountain View</city>, <state>CA</state> <postcode>94043</postcode>
 	    <country>USA</country>
 	    Phone: <phone>+1 650 694-4949</phone>
 	    Fax: <fax>+1 650 694-4953</fax>
 	    Email: <email>sales@cylogistics.com</email>
 	    WWW: <otheraddr><ulink url="http://www.cylogistics.com/">http://www.cylogistics.com/</ulink></otheraddr>
 	  </address>
 	</listitem>
 
 	<listitem>
 	  <address>
 	    <otheraddr>Kudzu, LLC</otheraddr>
 	    <street>7375 Washington Ave. S.</street>
 	    <city>Edina</city>, <state>MN</state> <postcode>55439</postcode>
 	    <country>USA</country>
 	    Phone: <phone>+1 952 947-0822</phone>
 	    Fax: <fax>+1 952 947-0876</fax>
 	    Email: <email>sales@kudzuenterprises.com</email>
 	  </address>
 	</listitem>
 
 	<listitem>
 	  <address>
 	    <otheraddr>Navarre Corp</otheraddr>
 	    <street>7400 49th Ave South</street>
 	    <city>New Hope</city>, <state>MN</state> <postcode>55428</postcode>
 	    <country>USA</country>
 	    Phone: <phone>+1 763 535-8333</phone>
 	    Fax: <fax>+1 763 535-0341</fax>
 	    WWW: <otheraddr><ulink url="http://www.navarre.com/">http://www.navarre.com/</ulink></otheraddr>
 	  </address>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="mirrors-dvd">
     <title>DVD Publishers</title>
 
     <para>FreeBSD is available on DVD from:</para>
 
     <itemizedlist>
       <listitem>
 	<address>
           <otheraddr>FreeBSD Mall, Inc.</otheraddr>
           <street>3623 Sanford Street</street>
           <city>Concord</city>, <state>CA</state>  <postcode>94520-1405</postcode>
           <country>USA</country>
           Phone: <phone>+1 925 674-0783</phone>
           Fax: <fax>+1 925 674-0821</fax>
           Email: <email>info@freebsdmall.com</email>
           WWW: <otheraddr><ulink url="http://www.freebsdmall.com/">http://www.freebsdmall.com/</ulink></otheraddr>
 	</address>
       </listitem>
 
       <listitem>
         <address>
           <otheraddr>FreeBSD Services Ltd</otheraddr>
           <street>11 Lapwing Close</street>
           <city>Bicester</city>
           <postcode>OX26 6XR</postcode>
           <country>United Kingdom</country>
           WWW: <otheraddr><ulink url="http://www.freebsd-services.com/">http://www.freebsd-services.com/</ulink></otheraddr>
         </address>
       </listitem>
     </itemizedlist>
   </sect1>
   
   <sect1 id="mirrors-ftp">
     <title>FTP Sites</title>
 
     <para>The official sources for FreeBSD are available via anonymous FTP
       from:
 
       <blockquote>
 	<para><ulink
 	    url="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp://ftp.FreeBSD.org/pub/FreeBSD/</ulink>.</para>
       </blockquote></para>
 
     <para>The <ulink
 	url="http://www.freebsdmirrors.org/">FreeBSD mirror
 	sites database</ulink> is more accurate than the mirror listing in the
       Handbook, as it gets its information from the DNS rather than relying on
       static lists of hosts.</para>
 
     <para>Additionally, FreeBSD is available via anonymous FTP from the
       following mirror sites.  If you choose to obtain FreeBSD via anonymous
       FTP, please try to use a site near you.</para>
 
     <para><link linkend="mirrors-ar">Argentina</link>,
       <link linkend="mirrors-au">Australia</link>,
       <link linkend="mirrors-at">Austria</link>,
       <link linkend="mirrors-br">Brazil</link>,
       <link linkend="mirrors-bg">Bulgaria</link>,
       <link linkend="mirrors-ca">Canada</link>,
       <link linkend="mirrors-cn">China</link>,
       <link linkend="mirrors-cz">Czech Republic</link>,
       <link linkend="mirrors-dk">Denmark</link>,
       <link linkend="mirrors-ee">Estonia</link>,
       <link linkend="mirrors-fi">Finland</link>,
       <link linkend="mirrors-fr">France</link>,
       <link linkend="mirrors-de">Germany</link>,
       <link linkend="mirrors-gr">Greece</link>,
       <link linkend="mirrors-hk">Hong Kong</link>,
       <link linkend="mirrors-hu">Hungary</link>,
       <link linkend="mirrors-is">Iceland</link>,
       <link linkend="mirrors-ie">Ireland</link>,
       <link linkend="mirrors-it">Italy</link>,
       <link linkend="mirrors-jp">Japan</link>,
       <link linkend="mirrors-kr">Korea</link>,
       <link linkend="mirrors-lt">Lithuania</link>,
       <link linkend="mirrors-nl">Netherlands</link>,
       <link linkend="mirrors-nz">New Zealand</link>,
       <link linkend="mirrors-no">Norway</link>,
       <link linkend="mirrors-pl">Poland</link>,
       <link linkend="mirrors-pt">Portugal</link>,
       <link linkend="mirrors-ro">Romania</link>,
       <link linkend="mirrors-ru">Russia</link>,
       <link linkend="mirrors-sa">Saudi Arabia</link>,
       <link linkend="mirrors-sg">Singapore</link>,
       <link linkend="mirrors-sk">Slovak Republic</link>,
       <link linkend="mirrors-si">Slovenia</link>,
       <link linkend="mirrors-za">South Africa</link>,
       <link linkend="mirrors-es">Spain</link>,
       <link linkend="mirrors-se">Sweden</link>,
       <link linkend="mirrors-ch">Switzerland</link>,
       <link linkend="mirrors-tw">Taiwan</link>,
       <link linkend="mirrors-th">Thailand</link>,
       <link linkend="mirrors-uk">UK</link>,
       <link linkend="mirrors-ua">Ukraine</link>,
       <link linkend="mirrors-us">USA</link>.</para>
 
     <variablelist>
       <varlistentry>
 	<term><anchor id="mirrors-ar">Argentina</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@ar.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.ar.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ar.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-au">Australia</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@au.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp.au.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.au.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.au.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp4.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.au.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.au.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp6.au.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.au.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-at">Austria</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@at.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.at.FreeBSD.org/pub/FreeBSD/">ftp://ftp.at.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	    
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.at.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.at.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-br">Brazil</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@br.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp.br.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.br.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.br.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp4.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.br.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.br.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp6.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.br.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp7.br.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.br.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-bg">Bulgaria</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@bg.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.bg.FreeBSD.org/pub/FreeBSD/">ftp://ftp.bg.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-ca">Canada</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@ca.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.ca.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ca.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	    
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.ca.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.ca.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-cn">China</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>phj@cn.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.cn.FreeBSD.org/pub/FreeBSD/">ftp://ftp.cn.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.cn.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.cn.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.cn.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.cn.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-cz">Czech Republic</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@cz.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.cz.FreeBSD.org/pub/FreeBSD/">ftp://ftp.cz.FreeBSD.org/pub/FreeBSD/</ulink> Contact: <email>calda@dzungle.ms.mff.cuni.cz</email></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-dk">Denmark</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@dk.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.dk.FreeBSD.org/pub/FreeBSD/">ftp://ftp.dk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.dk.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.dk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.dk.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.dk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-ee">Estonia</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@ee.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.ee.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ee.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-fi">Finland</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@fi.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.fi.FreeBSD.org/pub/FreeBSD/">ftp://ftp.fi.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.fi.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.fi.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-fr">France</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@fr.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp.fr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.fr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.fr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <!--
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp4.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.fr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	    -->
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.fr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp6.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.fr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <!--
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp7.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.fr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	    -->
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp8.fr.FreeBSD.org/pub/FreeBSD/">ftp://ftp8.fr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-de">Germany</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the mirror admins
 	    <email>de-bsd-hubs@de.FreeBSD.org </email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp.de.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.de.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.de.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp4.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.de.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.de.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp6.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.de.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp7.de.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.de.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-gr">Greece</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@gr.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.gr.FreeBSD.org/pub/FreeBSD/">ftp://ftp.gr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.gr.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.gr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-hk">Hong Kong</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.hk.FreeBSD.org/pub/FreeBSD/">ftp://ftp.hk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-hu">Hungary</term>
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>mohacsi@ik.bme.hu</email> for this domain.</para>
 	  
 	 <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.hu.FreeBSD.org/pub/FreeBSD/">ftp://ftp.hu.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <!--
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.hu.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.hu.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	    -->
 	 </itemizedlist>
        </listitem>
       </varlistentry>
 
 	  
       <varlistentry>
 	<term><anchor id="mirrors-is">Iceland</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@is.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.is.FreeBSD.org/pub/FreeBSD/">ftp://ftp.is.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-ie">Ireland</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@ie.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.ie.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ie.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.ie.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.ie.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.ie.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.ie.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-it">Italy</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@it.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.it.FreeBSD.org/pub/FreeBSD/">ftp://ftp.it.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.it.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.it.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-jp">Japan</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@jp.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp.jp.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.jp.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.jp.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp4.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.jp.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.jp.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp6.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.jp.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp7.jp.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.jp.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-kr">Korea</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@kr.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp.kr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.kr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink url="ftp://ftp3.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.kr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink url="ftp://ftp4.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.kr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink url="ftp://ftp5.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.kr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp6.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.kr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp7.kr.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.kr.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-lt">Lithuania</term>
 	  <listitem>
 	    <para>In case of problems, please contact the hostmaster
 	      <email>hostmaster@lt.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 	     	url="ftp://ftp.lt.FreeBSD.org/pub/FreeBSD/">ftp://ftp.lt.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 		
       <varlistentry>
 	<term><anchor id="mirrors-nl">Netherlands</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@nl.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.nl.FreeBSD.org/pub/FreeBSD/">ftp://ftp.nl.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.nl.freebsd.org/pub/FreeBSD/">ftp://ftp2.nl.freebsd.org/pub/FreeBSD/</ulink></para>
 	      </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-nz">New Zealand</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@nz.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink url="ftp://ftp.nz.FreeBSD.org/pub/FreeBSD/">ftp://ftp.nz.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-no">Norway</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@no.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.no.FreeBSD.org/pub/FreeBSD/">ftp://ftp.no.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.no.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.no.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-pl">Poland</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@pl.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.pl.FreeBSD.org/pub/FreeBSD/">ftp://ftp.pl.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.pl.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.pl.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.pl.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.pl.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-pt">Portugal</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@pt.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <!--
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.pt.FreeBSD.org/pub/FreeBSD/">ftp://ftp.pt.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	    -->
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.pt.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.pt.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.pt.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.pt.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-ro">Romania</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@ro.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.ro.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ro.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-ru">Russia</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@ru.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.ru.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ru.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.ru.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.ru.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.ru.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.ru.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink url="ftp://ftp4.ru.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.ru.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-sa">Saudi Arabia</term>
 	<listitem>
 	  <para>In case of problems, please contact
 	   <email>ftpadmin@isu.net.sa</email></para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		url="ftp://ftp.isu.net.sa/pub/mirrors/ftp.freebsd.org/">ftp://ftp.isu.net.sa/pub/mirrors/ftp.freebsd.org/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-sg">Singapore</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@sg.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.sg.FreeBSD.org/pub/FreeBSD/">ftp://ftp.sg.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-za">South Africa</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@za.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/">ftp://ftp.za.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.za.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.za.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.za.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.za.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp4.za.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.za.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-sk">Slovak Republic</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@sk.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink url="ftp://ftp.sk.FreeBSD.org/pub/FreeBSD/">ftp://ftp.sk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink url="ftp://ftp2.sk.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.sk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry><term><anchor id="mirrors-si">Slovenia</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@si.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <!--
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.si.FreeBSD.org/pub/FreeBSD/">ftp://ftp.si.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	    -->
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.si.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.si.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-es">Spain</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@es.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink url="ftp://ftp.es.FreeBSD.org/pub/FreeBSD/">ftp://ftp.es.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	    
 	    <listitem>
 	      <para><ulink url="ftp://ftp2.es.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.es.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	    
 	    <listitem>
 	      <para><ulink url="ftp://ftp3.es.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.es.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-se">Sweden</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@se.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.se.FreeBSD.org/pub/FreeBSD/">ftp://ftp.se.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.se.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.se.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.se.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.se.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.se.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.se.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-ch">Switzerland</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@ch.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.ch.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ch.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-tw">Taiwan</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@tw.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp.tw.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.tw.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.tw.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp4.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.tw.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.tw.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp6.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.tw.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp7.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.tw.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp8.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp8.tw.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp9.tw.FreeBSD.org/pub/FreeBSD/">ftp://ftp9.tw.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-th">Thailand</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.nectec.or.th/pub/FreeBSD/">ftp://ftp.nectec.or.th/pub/FreeBSD/</ulink> Contact: <email>ftpadmin@ftp.nectec.or.th</email>.</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-ua">Ukraine</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.ua.FreeBSD.org/pub/FreeBSD/">ftp://ftp.ua.FreeBSD.org/pub/FreeBSD/</ulink> Contact: <email>freebsd-mnt@lucky.net</email>.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.ua.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.ua.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.ua.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.ua.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.ua.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.ua.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-uk">UK</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@uk.FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp.uk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.uk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.uk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp4.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.uk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.uk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp6.uk.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.uk.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term><anchor id="mirrors-us">USA</term>
 
 	<listitem>
 	  <para>In case of problems, please contact the hostmaster
 	    <email>hostmaster@FreeBSD.org</email> for this domain.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		url="ftp://ftp1.FreeBSD.org/pub/FreeBSD/">ftp://ftp1.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp2.FreeBSD.org/pub/FreeBSD/">ftp://ftp2.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp3.FreeBSD.org/pub/FreeBSD/">ftp://ftp3.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp4.FreeBSD.org/pub/FreeBSD/">ftp://ftp4.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp5.FreeBSD.org/pub/FreeBSD/">ftp://ftp5.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp6.FreeBSD.org/pub/FreeBSD/">ftp://ftp6.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp7.FreeBSD.org/pub/FreeBSD/">ftp://ftp7.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp8.FreeBSD.org/pub/FreeBSD/">ftp://ftp8.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp9.FreeBSD.org/pub/os/FreeBSD/">ftp://ftp9.FreeBSD.org/pub/os/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp10.FreeBSD.org/pub/FreeBSD/">ftp://ftp10.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp11.FreeBSD.org/pub/FreeBSD/">ftp://ftp11.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp12.FreeBSD.org/pub/FreeBSD/">ftp://ftp12.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp13.FreeBSD.org/pub/FreeBSD/">ftp://ftp13.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp14.FreeBSD.org/pub/FreeBSD/">ftp://ftp14.FreeBSD.org/pub/FreeBSD/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
     <sect1 id="anoncvs">
       <title>Anonymous CVS</title>
 
       <sect2>
 	<title><anchor id="anoncvs-intro">Introduction</title>
 
 	<para>Anonymous CVS (or, as it is otherwise known,
 	  <emphasis>anoncvs</emphasis>) is a feature provided by the CVS
 	  utilities bundled with FreeBSD for synchronizing with a remote
 	  CVS repository.  Among other things, it allows users of FreeBSD
 	  to perform, with no special privileges, read-only CVS operations
 	  against one of the FreeBSD project's official anoncvs servers.
 	  To use it, one simply sets the <envar>CVSROOT</envar>
 	  environment variable to point at the appropriate anoncvs server,
 	  provides the well-known password <quote>anoncvs</quote> with the
 	  <command>cvs login</command> command, and then uses the
 	  &man.cvs.1; command to access it like any local
 	  repository.</para>
 
 	<note>
 	  <para>The <command>cvs login</command> command, stores the passwords
 	    that are used for authenticating to the CVS server in a file
 	    called <filename>.cvspass</filename> in your
 	    <envar>HOME</envar> directory.  If this file doesn't exist,
 	    you might get an error when trying to use <command>cvs
 	    login</command> for the first time.  Just make an empty
 	    <filename>.cvspass</filename> file, and retry to login.</para>
 	</note>
 
 	<para>While it can also be said that the <link
 	  linkend="cvsup">CVSup</link> and <emphasis>anoncvs</emphasis>
 	  services both perform essentially the same function, there are
 	  various trade-offs which can influence the user's choice of
 	  synchronization methods.  In a nutshell,
 	  <application>CVSup</application> is much more efficient in its
 	  usage of network resources and is by far the most technically
 	  sophisticated of the two, but at a price.  To use
 	  <application>CVSup</application>, a special client must first be
 	  installed and configured before any bits can be grabbed, and
 	  then only in the fairly large chunks which
 	  <application>CVSup</application> calls
 	  <emphasis>collections</emphasis>.</para>
 
 	<para><application>Anoncvs</application>, by contrast, can be used
 	  to examine anything from an individual file to a specific
 	  program (like <command>ls</command> or <command>grep</command>)
 	  by referencing the CVS module name.  Of course,
 	  <application>anoncvs</application> is also only good for
 	  read-only operations on the CVS repository, so if it is your
 	  intention to support local development in one repository shared
 	  with the FreeBSD project bits then
 	  <application>CVSup</application> is really your only
 	  option.</para>
       </sect2>
 
       <sect2>
 	<title><anchor id="anoncvs-usage">Using Anonymous CVS</title>
 
 	<para>Configuring &man.cvs.1; to use an Anonymous CVS repository
 	  is a simple matter of setting the <envar>CVSROOT</envar>
 	  environment variable to point to one of the FreeBSD project's
 	  <emphasis>anoncvs</emphasis> servers.  At the time of this
 	  writing, the following servers are available:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><emphasis>USA</emphasis>:
 	      :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
 	      (Use <command>cvs login</command> and enter the password
 	      <quote>anoncvs</quote> when prompted.)</para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>Germany</emphasis>:
 	      :pserver:anoncvs@anoncvs.de.FreeBSD.org:/home/ncvs
 	      (Use <command>cvs login</command> and enter the password
 	      <quote>anoncvs</quote> when prompted.)</para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>Germany</emphasis>:
 	      :pserver:anoncvs@anoncvs2.de.FreeBSD.org:/home/ncvs
 	      (rsh, pserver, ssh, ssh/2022)
 	      </para>
 	  </listitem>
 	  <listitem>
 	    <para><emphasis>Japan</emphasis>:
 	      :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs
 	      (Use <command>cvs login</command> and enter the password
 	      <quote>anoncvs</quote> when prompted.)</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>Since CVS allows one to <quote>check out</quote> virtually
 	  any version of the FreeBSD sources that ever existed (or, in
 	  some cases, will exist), you need to be
 	  familiar with the revision (<option>-r</option>) flag to
 	  &man.cvs.1; and what some of the permissible values for it in
 	  the FreeBSD Project repository are.</para>
 
 	<para>There are two kinds of tags, revision tags and branch tags.
 	  A revision tag refers to a specific revision.  Its meaning stays
 	  the same from day to day.  A branch tag, on the other hand,
 	  refers to the latest revision on a given line of development, at
 	  any given time.  Because a branch tag does not refer to a
 	  specific revision, it may mean something different tomorrow than
 	  it means today.</para>
 
 	<para><xref linkend="cvs-tags"> contains revision tags that users
  	  might be interested
 	  in.  Again, none of these are valid for the ports collection
 	  since the ports collection does not have multiple
 	  revisions.</para>
 
 	<para>When you specify a branch tag, you normally receive the
 	  latest versions of the files on that line of development.  If
 	  you wish to receive some past version, you can do so by
 	  specifying a date with the <option>-D date</option> flag.
 	  See the &man.cvs.1; manual page for more details.</para>
       </sect2>
 
       <sect2>
 	<title>Examples</title>
 
 	<para>While it really is recommended that you read the manual page
 	  for &man.cvs.1; thoroughly before doing anything, here are some
 	  quick examples which essentially show how to use Anonymous
 	  CVS:</para>
 
 	<example>
 	  <title>Checking Out Something from -CURRENT (&man.ls.1;) and
 	    Deleting It Again:</title>
 
 	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
 &prompt.user; <userinput>cvs login</userinput>
 <emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
 &prompt.user; <userinput>cvs co ls</userinput>
 &prompt.user; <userinput>cvs release -d ls</userinput>
 &prompt.user; <userinput>cvs logout</userinput>
 	  </screen>
 	</example>
 
 	<example>
 	  <title>Checking Out the Version of &man.ls.1; in the 3.X-STABLE
 	    Branch:</title>
 	    
 	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
 &prompt.user; <userinput>cvs login</userinput>
 <emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
 &prompt.user; <userinput>cvs co -rRELENG_3 ls</userinput>
 &prompt.user; <userinput>cvs release -d ls</userinput>
 &prompt.user; <userinput>cvs logout</userinput>
 	  </screen>
 	</example>
 
 	<example>
 	  <title>Creating a List of Changes (as unified diffs) to &man.ls.1;</title>
 
 	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
 &prompt.user; <userinput>cvs login</userinput>
 <emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
 &prompt.user; <userinput>cvs rdiff -u -rRELENG_3_0_0_RELEASE -rRELENG_3_4_0_RELEASE ls</userinput>
 &prompt.user; <userinput>cvs logout</userinput>
 	  </screen>
 	</example>
 
 	<example>
 	  <title>Finding Out What Other Module Names Can Be Used:</title>
 
 	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
 &prompt.user; <userinput>cvs login</userinput>
 <emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
 &prompt.user; <userinput>cvs co modules</userinput>
 &prompt.user; <userinput>more modules/modules</userinput>
 &prompt.user; <userinput>cvs release -d modules</userinput>
 &prompt.user; <userinput>cvs logout</userinput>
 	  </screen>
 	</example>
       </sect2>
 
       <sect2>
 	<title>Other Resources</title>
 
 	<para>The following additional resources may be helpful in learning
 	  CVS:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><ulink
 		url="http://www.csc.calpoly.edu/~dbutler/tutorials/winter96/cvs/">CVS Tutorial</ulink> from Cal Poly.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink url="http://www.cvshome.org/">CVS Home</ulink>,
 	      the CVS development and support community.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><ulink
 		url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVSWeb</ulink> is
 	      the FreeBSD Project web interface for CVS.</para>
 	  </listitem>
 	</itemizedlist>
       </sect2>
     </sect1>
     
     
   <sect1 id="ctm">
     <title>Using CTM</title>
 
       <para><application>CTM</application> is a method for keeping a
 	remote directory tree in sync with a central one.  It has been
 	developed for usage with FreeBSD's source trees, though other
 	people may find it useful for other purposes as time goes by.
 	Little, if any, documentation currently exists at this time on the
 	process of creating deltas, so talk to &a.phk; for more
 	information should you wish to use <application>CTM</application>
 	for other things.</para>
 
       <sect2>
 	<title>Why Should I Use <application>CTM</application>?</title>
 
 	<para><application>CTM</application> will give you a local copy of
 	  the FreeBSD source trees.  There are a number of
 	  <quote>flavors</quote> of the tree available.  Whether you wish
 	  to track the entire CVS tree or just one of the branches,
 	  <application>CTM</application> can provide you the information.
 	  If you are an active developer on FreeBSD, but have lousy or
 	  non-existent TCP/IP connectivity, or simply wish to have the
 	  changes automatically sent to you,
 	  <application>CTM</application> was made for you.  You will need
 	  to obtain up to three deltas per day for the most  active
 	  branches.  However, you should consider having them sent by
 	  automatic email.  The sizes of the updates are always kept as
 	  small as possible.  This is typically less than 5K, with an
 	  occasional (one in ten) being 10-50K and every now and then a
 	  large 100K+ or more coming around.</para>
 
 	<para>You will also need to make yourself aware of the various
 	  caveats related to working directly from the development sources
 	  rather than a pre-packaged release.  This is particularly true
 	  if you choose the <quote>current</quote> sources.  It is
 	  recommended that you read <link linkend="current">Staying
 	  current with FreeBSD</link>.</para>
       </sect2>
 
       <sect2>
 	<title>What Do I Need to Use
 	  <application>CTM</application>?</title>
 
 	<para>You will need two things: The <application>CTM</application>
 	  program, and the initial deltas to feed it (to get up to
 	  <quote>current</quote> levels).</para>
 	    
 	<para>The <application>CTM</application> program has been part of
 	  FreeBSD ever since version 2.0 was released, and lives in
 	  <filename>/usr/src/usr.sbin/ctm</filename> if you have a copy
 	  of the source available.</para>
 
 	<para>If you are running a pre-2.0 version of FreeBSD, you can
 	  fetch the current <application>CTM</application> sources
 	  directly from:</para>
 	    
 	<para><ulink
 	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm/</ulink></para>
 
 	<para>The <quote>deltas</quote> you feed
 	  <application>CTM</application> can be had two ways, FTP or
 	  email.  If you have general FTP access to the Internet then the
 	  following FTP sites support access to
 	  <application>CTM</application>:</para>
 
 	<para><ulink
 	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/</ulink></para>
 
 	<para>or see section <link
 	  linkend="mirrors-ctm">mirrors</link>.</para>
 
 	<para>FTP the relevant directory and fetch the
 	  <filename>README</filename> file, starting from there.</para>
 
 	<para>If you wish to get your deltas via email:</para>
 
 	<para>Send email to &a.majordomo; to subscribe to one of the
 	  <application>CTM</application> distribution lists.
 	  <quote>ctm-cvs-cur</quote> supports the entire CVS tree.
 	  <quote>ctm-src-cur</quote> supports the head of the development
 	  branch.  <quote>ctm-src-2_2</quote> supports the 2.2 release
 	  branch, etc..  (If you do not know how to subscribe yourself
 	  using majordomo, send a message first containing the word
 	  <literal>help</literal> &mdash; it will send you back usage
 	  instructions.)</para>
 
 	<para>When you begin receiving your <application>CTM</application>
 	  updates in the mail, you may use the
 	  <command>ctm_rmail</command> program to unpack and apply them.
 	  You can actually use the <command>ctm_rmail</command> program
 	  directly from a entry in <filename>/etc/aliases</filename> if
 	  you want to have the process run in a fully automated fashion.
 	  Check the <command>ctm_rmail</command> manual page for more
 	  details.</para>
 
 	<note>
 	  <para>No matter what method you use to get the
 	    <application>CTM</application> deltas, you should subscribe to
 	    the <email>ctm-announce@FreeBSD.org</email> mailing list.  In
 	    the future, this will be the only place where announcements
 	    concerning the operations of the
 	    <application>CTM</application> system will be posted.  Send an
 	    email to &a.majordomo; with a single line of
 	    <literal>subscribe ctm-announce</literal> to get added to the
 	    list.</para>
 	</note>
       </sect2>
 
       <sect2>
 	<title>Using <application>CTM</application> for the First
 	  Time</title>
 
 	<para>Before you can start using <application>CTM</application>
 	  deltas, you will need to get to a starting point for the deltas
 	  produced subsequently to it.</para>
 
 	<para>First you should determine what you already have.  Everyone
 	  can start from an <quote>empty</quote> directory.  You must use
 	  an initial <quote>Empty</quote> delta to start off your
 	  <application>CTM</application> supported tree.  At some point it
 	  is intended that one of these <quote>started</quote> deltas be
 	  distributed on the CD for your convenience, however, this does
 	  not currently happen.</para>
 
 	<para>Since the trees are many tens of megabytes, you should
 	  prefer to start from something already at hand.  If you have a
 	  -RELEASE CD, you can copy or extract an initial source from it.
 	  This will save a significant transfer of data.</para>
 
 	<para>You can recognize these <quote>starter</quote> deltas by the
 	  <literal>X</literal> appended to the number
 	  (<filename>src-cur.3210XEmpty.gz</filename> for instance).  The
 	  designation following the <literal>X</literal> corresponds to
 	  the origin of your initial <quote>seed</quote>.
 	  <filename>Empty</filename> is an empty directory.  As a rule a
 	  base transition from <literal>Empty</literal> is produced
 	  every 100 deltas.  By the way, they are large! 70 to 80
 	  Megabytes of <command>gzip</command>'d data is common for the
 	  <filename>XEmpty</filename> deltas.</para>
 
 	<para>Once you have picked a base delta to start from, you will also
 	  need all deltas with higher numbers following it.</para>
       </sect2>
 
       <sect2>
 	<title>Using <application>CTM</application> in Your Daily
 	  Life</title>
 
 	<para>To apply the deltas, simply say:</para>
 
 	<screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput>
 &prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen>
 
 	<para><application>CTM</application> understands deltas which have
 	  been put through <command>gzip</command>, so you do not need to
 	  <command>gunzip</command> them first, this saves disk space.</para>
 
 	<para>Unless it feels very secure about the entire process,
 	  <application>CTM</application> will not touch your tree.  To
 	  verify a delta you can also use the <option>-c</option> flag and
 	  <application>CTM</application> will not actually touch your
 	  tree; it will merely verify the integrity of the delta and see
 	  if it would apply cleanly to your current tree.</para>
 
 	<para>There are other options to <application>CTM</application>
 	  as well, see the manual pages or look in the sources for more
 	  information.</para>
 
 	<para>That is really all there is to it.  Every time you get a new
 	  delta, just run it through <application>CTM</application> to
 	  keep your sources up to date.</para>
 
 	<para>Do not remove the deltas if they are hard to download again.
 	  You just might want to keep them around in case something bad
 	  happens.  Even if you only have floppy disks, consider using
 	  <command>fdwrite</command> to make a copy.</para>
       </sect2>
 
       <sect2>
 	<title>Keeping Your Local Changes</title>
 
 	<para>As a developer one would like to experiment with and change
 	  files in the source tree.  <application>CTM</application>
 	  supports local modifications in a limited way: before checking
 	  for the presence of a file <filename>foo</filename>, it first
 	  looks for <filename>foo.ctm</filename>.  If this file exists,
 	  CTM will operate on it instead of
 	  <filename>foo</filename>.</para>
 
 	<para>This behavior gives us a simple way to maintain local
 	  changes:  simply copy the files you plan to modify to the
 	  corresponding file names with a <filename>.ctm</filename>
 	  suffix.  Then you can freely hack  the code, while CTM keeps the
 	  <filename>.ctm</filename> file up-to-date.</para>
       </sect2>
 
       <sect2>
 	<title>Other Interesting <application>CTM</application> Options</title>
 
 	<sect3>
 	  <title>Finding Out Exactly What Would Be Touched by an
 	    Update</title>
 
 	  <para>You can determine the list of changes that
 	    <application>CTM</application> will make on your source
 	    repository using the <option>-l</option> option to
 	    <application>CTM</application>.</para>
 
 	  <para>This is useful if you would like to keep logs of the
 	    changes, pre- or post- process the modified files in any
 	    manner, or just are feeling a tad paranoid.</para>
 	</sect3>
 
 	<sect3>
 	  <title>Making Backups Before Updating</title>
 
 	  <para>Sometimes you may want to backup all the files that would
 	    be changed by a <application>CTM</application> update.</para>
 
 	  <para>Specifying the <option>-B backup-file</option> option
 	    causes <application>CTM</application> to backup all files that
 	    would be touched by a given <application>CTM</application>
 	    delta to <filename>backup-file</filename>.</para>
 	</sect3>
 
 	<sect3>
 	  <title>Restricting the Files Touched by an Update</title>
 
 	  <para>Sometimes you would be interested in restricting the scope
 	    of a given <application>CTM</application> update, or may be
 	    interested in extracting just a few files from a sequence of
 	    deltas.</para>
 
 	  <para>You can control the list of files that
 	    <application>CTM</application> would operate on by specifying
 	    filtering regular expressions using the <option>-e</option>
 	    and <option>-x</option> options.</para>
 
 	  <para>For example, to extract an up-to-date copy of
 	    <filename>lib/libc/Makefile</filename> from your collection of
 	    saved CTM deltas, run the commands:</para>
 
 	  <screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput>
 &prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen>
 
 	  <para>For every file specified in a
 	    <application>CTM</application> delta, the <option>-e</option>
 	    and <option>-x</option> options are applied in the order given
 	    on the command line.  The file is processed by
 	    <application>CTM</application> only if it is marked as
 	    eligible after all the <option>-e</option> and
 	    <option>-x</option> options are applied to it.</para>
 	</sect3>
       </sect2>
 
       <sect2>
 	<title>Future Plans for <application>CTM</application></title>
 
 	<para>Tons of them:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>Use some kind of authentication into the CTM system, so
 	      as to allow detection of spoofed CTM updates.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Clean up the options to <application>CTM</application>,
 	      they became confusing and counter intuitive.</para>
 	  </listitem>
 	</itemizedlist>
       </sect2>
 
       <sect2>
 	<title>Miscellaneous Stuff</title>
 
 	<para>There is a sequence of deltas for the
 	  <literal>ports</literal> collection too, but interest has not
 	  been all that high yet.</para>
       </sect2>
 
     <sect2 id="mirrors-ctm">
       <title>CTM Mirrors</title>
       
     <para><link linkend="ctm">CTM</link>/FreeBSD is available via anonymous
       FTP from the following mirror sites.  If you choose to obtain CTM via
       anonymous FTP, please try to use a site near you.</para>
 
     <para>In case of problems, please contact &a.phk;.</para>
 
     <variablelist>
       <varlistentry>
 	<term>California, Bay Area, official source</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>South Africa, backup server for old deltas</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Taiwan/R.O.C.</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/</ulink></para>
 	    </listitem>
 
 	    <listitem>
 	      <para><ulink
 		  url="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/</ulink></para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
     </variablelist>
 
     <para>If you did not find a mirror near to you or the mirror is
       incomplete, try to use a search engine such as
       <ulink url="http://www.alltheweb.com/">alltheweb</ulink>.</para>
   </sect2></sect1>
 
   <sect1 id="cvsup">
     <title>Using CVSup</title>
     
     <sect2 id="cvsup-intro">
       <title>Introduction</title>
       
       <para><application>CVSup</application> is a software package for
 	distributing and updating source trees from a master CVS
 	repository on a remote server host.  The FreeBSD sources are
 	maintained in a CVS repository on a central development machine
 	in California.  With <application>CVSup</application>, FreeBSD
 	users can easily keep their own source trees up to date.</para>
       
       <para><application>CVSup</application> uses the so-called
 	<emphasis>pull</emphasis> model of updating.  Under the pull
 	model, each client asks the server for updates, if and when they
 	are wanted.  The server waits passively for update requests from
 	its clients.  Thus all updates are instigated by the client.
 	The server never sends unsolicited updates.  Users must either
 	run the <application>CVSup</application> client manually to get
 	an update, or they must set up a <command>cron</command> job to
 	run it automatically on a regular basis.</para>
       
       <para>The term <application>CVSup</application>, capitalized just
 	so, refers to the entire software package.  Its main components
 	are the client <command>cvsup</command> which runs on each
 	user's machine, and the server <command>cvsupd</command> which
 	runs at each of the FreeBSD mirror sites.</para>
 
       <para>As you read the FreeBSD documentation and mailing lists, you
 	may see references to <application>sup</application>.
 	<application>Sup</application> was the predecessor of
 	<application>CVSup</application>, and it served a similar
 	purpose.  <application>CVSup</application> is used much in the
 	same way as sup and, in fact, uses configuration files which are
 	backward-compatible with <command>sup</command>'s.
 	<application>Sup</application> is no longer used in the FreeBSD
 	project, because <application>CVSup</application> is both faster
 	and more flexible.</para>
     </sect2>
 
     <sect2 id="cvsup-install">
       <title>Installation</title>
       
       <para>The easiest way to install <application>CVSup</application>
 	is to use the precompiled <filename role="package">net/cvsup</filename> package
 	from the FreeBSD <link linkend="ports">packages collection</link>.
 	If you prefer to build <application>CVSup</application> from
 	source, you can use the <filename role="package">net/cvsup</filename>
 	port instead.  But be forewarned: the
 	<filename role="package">net/cvsup</filename> port depends on the Modula-3
 	system, which takes a substantial amount of time and
 	disk space to download and build.</para>
 
 	<note>
 	  <para>If you are going to be using
 	  <application>CVSup</application> on a machine which will not have
 	  <application>XFree86</application> installed, such as a server, be
 	  sure to use the port which does not include the
 	  <application>CVSup</application> <acronym>GUI</acronym>,
 	  <ulink url="http://www.FreeBSD.org/cgi/url.cgi?ports/net/cvsup/pkg-descr.nogui/">cvsup-without-gui</ulink>.</para>
 	</note>
       
       <para>If you do not know anything about 
 	<application>CVSup</application> at all and want a
 	single package which will install it, set up the configuration
 	file and start the transfer via a pointy-clicky type of
 	interface, then get the <filename
 	role="package">net/cvsupit</filename>
 	package.  Just hand it to &man.pkg.add.1; and it will lead you
 	through the configuration process in a menu-oriented
 	fashion.</para>
     </sect2>
 
     <sect2 id="cvsup-config">
       <title>CVSup Configuration</title>
       
       <para><application>CVSup</application>'s operation is controlled
 	by a configuration file called the <filename>supfile</filename>.
 	There are some sample <filename>supfiles</filename> in the
 	directory <ulink
 	  url="file://localhost/usr/share/examples/cvsup/">/usr/share/examples/cvsup/</ulink>.</para>
       
       <para>The information in a <filename>supfile</filename> answers
 	the following questions for cvsup:</para>
       
       <itemizedlist>
 	<listitem>
 	  <para><link linkend="cvsup-config-files">Which files do you
 	      want to receive?</link></para>
 	</listitem>
 	
 	<listitem>
 	  <para><link linkend="cvsup-config-vers">Which versions of them
 	      do you want?</link></para>
 	</listitem>
 	
 	<listitem>
 	  <para><link linkend="cvsup-config-where">Where do you want to
 	      get them from?</link></para>
 	</listitem>
 	
 	<listitem>
 	  <para><link linkend="cvsup-config-dest">Where do you want to
 	      put them on your own machine?</link></para>
 	</listitem>
 	
 	<listitem>
 	  <para><link linkend="cvsup-config-status">Where do you want to
 	      put your status files?</link></para>
 	</listitem>
       </itemizedlist>
 
       <para>In the following sections, we will construct a typical
 	<filename>supfile</filename> by answering each of these
 	questions in turn.  First, we describe the overall structure of
 	a <filename>supfile</filename>.</para>
 
       <para>A <filename>supfile</filename> is a text file.  Comments
 	begin with <literal>#</literal> and extend to the end of the
 	line.  Lines that are blank and lines that contain only
 	comments are ignored.</para>
       
       <para>Each remaining line describes a set of files that the user
 	wishes to receive.  The line begins with the name of a
 	<quote>collection</quote>, a logical grouping of files defined by
 	the server. The name of the collection tells the server which
 	files you want.  After the collection name come zero or more
 	fields, separated by white space.  These fields answer the
 	questions listed above.  There are two types of fields: flag
 	fields and value fields.  A flag field consists of a keyword
 	standing alone, e.g., <literal>delete</literal> or
 	<literal>compress</literal>.  A value field also begins with a
 	keyword, but the keyword is followed without intervening white
 	space by <literal>=</literal> and a second word.  For example,
 	<literal>release=cvs</literal> is a value field.</para>
       
       <para>A <filename>supfile</filename> typically specifies more than
 	one collection to receive.  One way to structure a
 	<filename>supfile</filename> is to specify all of the relevant
 	fields explicitly for each collection.  However, that tends to
 	make the <filename>supfile</filename> lines quite long, and it
 	is inconvenient because most fields are the same for all of the
 	collections in a <filename>supfile</filename>.
 	<application>CVSup</application> provides a defaulting mechanism
 	to avoid these problems.  Lines beginning with the special
 	pseudo-collection name <literal>*default</literal> can be used
 	to set flags and values which will be used as defaults for the
 	subsequent collections in the <filename>supfile</filename>.  A
 	default value can be overridden for an individual collection, by
 	specifying a different value with the collection itself.
 	Defaults can also be changed or augmented in mid-supfile by
 	additional <literal>*default</literal> lines.</para>
 
       <para>With this background, we will now proceed to construct a
 	<filename>supfile</filename> for receiving and updating the main
 	source tree of <link
 	  linkend="current">FreeBSD-CURRENT</link>.</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><anchor id="cvsup-config-files">Which files do you want
 	    to receive?</para>
 	  
 	  <para>The files available via <application>CVSup</application>
 	    are organized into named groups called
 	    <quote>collections</quote>.  The collections that are
 	    available are described in the <link
 	      linkend="cvsup-collec">following section</link>.  In this
 	    example, we
 	    wish to receive the entire main source tree for the FreeBSD
 	    system.  There is a single large collection
 	    <literal>src-all</literal> which will give us all of that.
 	    As a first step toward constructing our
 	    <filename>supfile</filename>, we
 	    simply list the collections, one per line (in this case,
 	    only one line):</para>
 
 	  <programlisting>src-all</programlisting>
 	</listitem>
 
 	<listitem>
 	  <para><anchor id="cvsup-config-vers">Which version(s) of them
 	    do you want?</para>
 
 	  <para>With <application>CVSup</application>, you can receive
 	    virtually any version of the sources that ever existed.
 	    That is possible because the
 	    <application>cvsupd</application> server works directly from
 	    the CVS repository, which contains all of the versions.  You
 	    specify which one of them you want using the
 	    <literal>tag=</literal> and <option>date=</option> value
 	    fields.</para>
 	  
 	  <warning>
 	    <para>Be very careful to specify any <literal>tag=</literal>
 	      fields correctly.  Some tags are valid only for certain
 	      collections of files.  If you specify an incorrect or
 	      misspelled tag, <application>CVSup</application>
 	      will delete files which you probably
 	      do not want deleted.  In particular, use <emphasis>only
 	      </emphasis> <literal>tag=.</literal> for the
 	      <literal>ports-*</literal> collections.</para>
 	  </warning>
 
 	  <para>The <literal>tag=</literal> field names a symbolic tag
 	    in the repository.  There are two kinds of tags, revision
 	    tags and branch tags.  A revision tag refers to a specific
 	    revision.  Its meaning stays the same from day to day.  A
 	    branch tag, on the other hand, refers to the latest revision
 	    on a given line of development, at any given time.  Because
 	    a branch tag does not refer to a specific revision, it may
 	    mean something different tomorrow than it means
 	    today.</para>
 	  
 	  <para><xref linkend="cvs-tags"> contains branch tags that
 	    users might be interested in.  When specifying a tag in
 	    <application>CVSup</application>'s configuration file, it
 	    must be preceded with <literal>tag=</literal>
 	    (<literal>RELENG_4</literal> will become
 	    <literal>tag=RELENG_4</literal>).
 	    Keep in mind that only the <literal>tag=.</literal> is
 	    relevant for the ports collection.</para>
 
 	  <warning>
 	    <para>Be very careful to type the tag name exactly as shown.
 	      <application>CVSup</application> cannot distinguish
 	      between valid and invalid tags.  If you misspell the tag,
 	      <application>CVSup</application> will behave as though you
 	      had specified a valid tag which happens to refer to no
 	      files at all.  It will delete your existing sources in
 	      that case.</para>
 	  </warning>
 
 	  <para>When you specify a branch tag, you normally receive the
 	    latest versions of the files on that line of development.
 	    If you wish to receive some past version, you can do so by
 	    specifying a date with the <option>date=</option> value
 	    field. The &man.cvsup.1; manual page explains how to do
 	    that.</para>
 
 	  <para>For our example, we wish to receive FreeBSD-CURRENT.  We
 	    add this line at the beginning of our
 	    <filename>supfile</filename>:</para>
 	  
 	  <programlisting>*default tag=.</programlisting>
 
 	  <para>There is an important special case that comes into play
 	    if you specify neither a <literal>tag=</literal> field nor a
 	    <literal>date=</literal> field.  In that case, you receive
 	    the actual RCS files directly from the server's CVS
 	    repository, rather than receiving a particular version.
 	    Developers generally prefer this mode of operation.  By
 	    maintaining a copy of the repository itself on their
 	    systems, they gain the ability to browse the revision
 	    histories and examine past versions of files.  This gain is
 	    achieved at a large cost in terms of disk space,
 	    however.</para>
 	</listitem>
 
 	<listitem>
 	  <para><anchor id="cvsup-config-where">Where do you want to get
 	    them from?</para>
 	  
 	  <para>We use the <literal>host=</literal> field to tell
 	    <command>cvsup</command> where to obtain its updates.  Any
 	    of the <link linkend="cvsup-mirrors">CVSup mirror
 	      sites</link> will do, though you should try to select one
 	    that is close to you in cyberspace.  In this example we will
 	    use a fictional FreeBSD distribution site,
 	    <hostid role="fqdn">cvsup666.FreeBSD.org</hostid>:</para>
 
 	  <programlisting>*default host=cvsup666.FreeBSD.org</programlisting>
 	  
 	  <para>You will need to change the host to one that actually
 	    exists before running <application>CVSup</application>.
 	    On any particular run of
 	    <command>cvsup</command>, you can override the host  setting
 	    on the command line, with <option>-h
 	      <replaceable>hostname</replaceable></option>.</para>
 	</listitem>
 	
 	<listitem>
 	  <para><anchor id="cvsup-config-dest">Where do you want to put
 	    them on your own machine?</para>
 	  
 	  <para>The <literal>prefix=</literal> field tells
 	    <command>cvsup</command> where to put the files it receives.
 	    In this example, we will put the source files directly into
 	    our main source tree, <filename>/usr/src</filename>.  The
 	    <filename>src</filename> directory is already implicit in
 	    the collections we have chosen to receive, so this is the
 	    correct specification:</para>
 	  
 	  <programlisting>*default prefix=/usr</programlisting>
 	</listitem>
 
 	<listitem>
 	  <para><anchor id="cvsup-config-status">Where should
 	    <command>cvsup</command> maintain its status files?</para>
 
 	  <para>The <application>CVSup</application> client maintains
 	    certain status files in what
 	    is called the <quote>base</quote> directory.  These files
 	    help <application>CVSup</application> to work more
 	    efficiently, by keeping track of which updates you have
 	    already received.  We will use the standard base directory,
 	    <filename>/usr/local/etc/cvsup</filename>:</para>
 
 	  <programlisting>*default base=/usr/local/etc/cvsup</programlisting>
 
 	  <para>This setting is used by default if it is not specified
 	    in the <filename>supfile</filename>, so we actually do not
 	    need the above line.</para>
 	  
 	  <para>If your base directory does not already exist, now would
 	    be a good time to create it.  The <command>cvsup</command>
 	    client will refuse to run if the base directory does not
 	    exist.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Miscellaneous <filename>supfile</filename>
 	    settings:</para>
 	  
 	  <para>There is one more line of boiler plate that normally
 	    needs to be present in the
 	    <filename>supfile</filename>:</para>
 
 	  <programlisting>*default release=cvs delete use-rel-suffix compress</programlisting>
 
 	  <para><literal>release=cvs</literal> indicates that the server
 	    should get its information out of the main FreeBSD CVS
 	    repository.  This is virtually always the case, but there
 	    are other possibilities which are beyond the scope of this
 	    discussion.</para>
 	  
 	  <para><literal>delete</literal> gives
 	    <application>CVSup</application> permission to delete files.
 	    You should always specify this, so that
 	    <application>CVSup</application> can keep your source tree
 	    fully up-to-date.  <application>CVSup</application> is
 	    careful to delete only those files for which it is
 	    responsible.  Any extra files you happen to have will be
 	    left strictly alone.</para>
 	  
 	  <para><literal>use-rel-suffix</literal> is ... arcane.  If you
 	    really want to know about it, see the &man.cvsup.1; manual
 	    page.  Otherwise, just specify it and do not worry about
 	    it.</para>
 
 	  <para><literal>compress</literal> enables the use of
 	    gzip-style compression on the communication channel.  If
 	    your network link is T1 speed or faster, you probably should
 	    not use compression.  Otherwise, it helps
 	    substantially.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Putting it all together:</para>
 
 	  <para>Here is the entire <filename>supfile</filename> for our
 	    example:</para>
 
 	  <programlisting>*default tag=.
 *default host=cvsup666.FreeBSD.org
 *default prefix=/usr
 *default base=/usr/local/etc/cvsup
 *default release=cvs delete use-rel-suffix compress
 
 src-all</programlisting>
 	</listitem>
       </itemizedlist>
       <sect3>
        <title>The <filename>refuse</filename> File</title>
 
        <para>As mentioned above, <application>CVSup</application> uses
        a <emphasis>pull method</emphasis>. Basically, this means that
        you connect to the <application>CVSup</application> server, and
        it says, <quote>Here is what you can download from
        me...</quote>, and your client responds <quote>OK, I will take
        this, this, this, and this.</quote> In the default
        configuration, the <application>CVSup</application> client will
        take every file associated with the collection and tag you
        chose in the configuration file. However, this is not always
        what you want, especially if you are synching the doc, ports, or
        www trees &mdash; most people cannot read four or five
        languages, and therefore they do not need to download the
        language-specific files. If you are
        <application>CVSup</application>ing the ports collection, you
        can get around this by specifying each collection individually
        (e.g., <emphasis>ports-astrology</emphasis>,
        <emphasis>ports-biology</emphasis>, etc instead of simply
        saying <emphasis>ports-all</emphasis>). However, since the doc
        and www trees do not have language-specific collections, you
        must use one of <application>CVSup</application>'s many nifty
        features; the <filename>refuse</filename> file.</para>
 
        <para>The <filename>refuse</filename> file essentially tells
        <application>CVSup</application> that it should not take every
        single file from a collection; in other words, it tells the
        client to <emphasis>refuse</emphasis> certain files from the
        server. The <filename>refuse</filename> file can be found (or, if you do not yet
        have one, should be placed) in
        <filename><replaceable>base</replaceable>/sup/refuse</filename>.
        <replaceable>base</replaceable> is defined in your supfile; by
        default, <replaceable>base</replaceable> is
        <filename>/usr/local/etc/cvsup</filename>, 
        which means that by default the <filename>refuse</filename> file is in 
        <filename>/usr/local/etc/cvsup/sup/refuse</filename>.</para>
 
        <para>The <filename>refuse</filename> file has a very simple format; it simply
        contains the names of files or directories that you do not wish
        to download.  For example, if you cannot speak any languages other
        than English and some German, and you do not feel the need to use
        the German applications (or applications for any other
        languages, except for English), you can put the following in your
        <filename>refuse</filename> file:</para>
 
        <screen>ports/chinese
 ports/french
 ports/german
 ports/hebrew
 ports/japanese
 ports/hungarian
 ports/korean
 ports/portuguese
 ports/russian
 ports/ukrainian
 ports/vietnamese
 doc/de_DE.ISO8859-1
 doc/el_GR.ISO8859-7
 doc/es_ES.ISO8859-1
 doc/fr_FR.ISO8859-1
 doc/it_IT.ISO8859-15
 doc/ja_JP.eucJP
 doc/nl_NL.ISO8859-1
 doc/pt_BR.ISO8859-1
 doc/ru_RU.KOI8-R
 doc/sr_YU.ISO8859-2
 doc/zh_TW.Big5</screen>
 
        <para>and so forth for the other languages (you can find the
        full list by browsing the <ulink
        URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/">FreeBSD
        FTP server</ulink>).  Note that the name
        of the repository is the first <quote>directory</quote> in the
        <filename>refuse</filename> file.</para>
 
        <para>With this very useful feature, those users who are on
        slow links or pay by the minute for their Internet connection
        will be able to save valuable time as they will no longer need
        to download files that they will never use. For more
        information on <filename>refuse</filename> files and other neat
        features of <application>CVSup</application>, please view its
        manual page.</para> 
       </sect3>
     </sect2>
     
     <sect2>
       <title>Running <application>CVSup</application></title>
       
       <para>You are now ready to try an update.  The command line for
 	doing this is quite simple:</para>
 
       <screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen>
 
       <para>where <filename><replaceable>supfile</replaceable></filename>
 	is of course the name of the supfile you have just created. 
 	Assuming you are running under X11, <command>cvsup</command>
 	will display a GUI window with some buttons to do the usual
 	things.  Press the <quote>go</quote> button, and watch it
 	run.</para>
       
       <para>Since you are updating your actual
 	<filename>/usr/src</filename> tree in this example, you will
 	need to run the program as <username>root</username> so that
 	<command>cvsup</command> has the permissions it needs to update
 	your files.  Having just created your configuration file, and
 	having never used this program before, that might
 	understandably make you nervous. There is an easy way to do a
 	trial run without touching your precious files.  Just create an
 	empty directory somewhere convenient, and name it as an extra
 	argument on the command line:</para>
 
       <screen>&prompt.root; <userinput>mkdir /var/tmp/dest</userinput>
 &prompt.root; <userinput>cvsup supfile /var/tmp/dest</userinput></screen>
       
       <para>The directory you specify will be used as the destination
 	directory for all file updates.
 	<application>CVSup</application> will examine your usual files
 	in <filename>/usr/src</filename>, but it will not modify or
 	delete any of them.  Any file updates will instead land in
 	<filename>/var/tmp/dest/usr/src</filename>.
 	<application>CVSup</application> will also leave its base
 	directory status files untouched when run this way.  The new
 	versions of those files will be written into the specified
 	directory.  As long as you have read access to
 	<filename>/usr/src</filename>, you do not even need to be
 	<username>root</username> to perform this kind of trial run.</para>
       
       <para>If you are not running X11 or if you just do not like GUIs,
 	you should add a couple of options to the command line when you
 	run cvsup:</para>
       
       <screen>&prompt.root; <userinput>cvsup -g -L 2 supfile</userinput></screen>
 	    
       <para>The <option>-g</option> tells
 	<application>CVSup</application> not to use its GUI.  This is
 	automatic if you are not running X11, but otherwise you have to
 	specify it.</para>
       
       <para>The <option>-L 2</option> tells 
 	<application>CVSup</application> to print out the
 	details of all the file updates it is doing.  There are three
 	levels of verbosity, from <option>-L 0</option> to
 	<option>-L 2</option>.  The default is 0, which means total
 	silence except for error messages.</para>
       
       <para>There are plenty of other options available.  For a brief
 	list of them, type <command>cvsup -H</command>.  For more
 	detailed descriptions, see the manual page.</para>
 
       <para>Once you are satisfied with the way updates are working, you
 	can arrange for regular runs of <application>CVSup</application>
 	using &man.cron.8;.
 	Obviously, you should not let <application>CVSup</application>
 	use its GUI when running it from &man.cron.8;.</para>
     </sect2>
 
     <sect2 id="cvsup-collec">
       <title><application>CVSup</application> File Collections</title>
 	    
       <para>The file collections available via
 	<application>CVSup</application> are organized hierarchically.
 	There are a few large collections, and they are divided into
 	smaller sub-collections.  Receiving a large collection is
 	equivalent to receiving each of its sub-collections.  The
 	hierarchical relationships among collections are reflected by
 	the use of indentation in the list below.</para>
       
       <para>The most commonly used collections are
 	<literal>src-all</literal>, and
 	<literal>ports-all</literal>.  The other collections are used
 	only by small groups of people for specialized purposes, and
 	some mirror sites may not carry all of them.</para>
       
       <variablelist>
 	<varlistentry>
 	  <term><literal>cvs-all release=cvs</literal></term>
 	  
 	  <listitem>
 	    <para>The main FreeBSD CVS repository, including the
 	      cryptography code.</para>
 	    
 	    <variablelist>
 	      <varlistentry>
 		<term><literal>distrib release=cvs</literal></term>
 		
 		<listitem>
 		  <para>Files related to the distribution and mirroring
 		    of FreeBSD.</para>
 		</listitem>
 	      </varlistentry>
 	      
 	      <varlistentry>
 		<term><literal>doc-all release=cvs</literal></term>
 
 		<listitem>
 		  <para>Sources for the FreeBSD Handbook and other
 		    documentation.  This does not include files for
 		    the FreeBSD web site.</para>
 		</listitem>
 	      </varlistentry>
 
 	      <varlistentry>
 		<term><literal>ports-all release=cvs</literal></term>
 
 		<listitem>
 		  <para>The FreeBSD Ports Collection.</para>
 
 		  <variablelist>
 		    <varlistentry>
 		      <term><literal>ports-archivers
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Archiving tools.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-astro
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Astronomical ports.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-audio
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Sound support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-base
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Miscellaneous files at the top of
 			  /usr/ports.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-benchmarks
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Benchmarks.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-biology
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Biology.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-cad
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Computer aided design tools.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-chinese
 			  release=cvs</literal></term>
 			
 		      <listitem>
 			<para>Chinese language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-comms
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Communication software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-converters
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>character code converters.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-databases
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Databases.</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>ports-deskutils
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Things that used to be on the desktop
 			  before computers were invented.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-devel
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Development utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-editors
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Editors.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-emulators
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Emulators for other operating
 			  systems.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-finance
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Monetary, financial and related applications.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-ftp
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>FTP client and server utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-games
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Games.</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>ports-german
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>German language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-graphics
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Graphics utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-hungarian
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Hungarian language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-irc
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Internet Relay Chat utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-japanese
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Japanese language support.</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>ports-java
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Java utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-korean
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Korean language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-lang
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Programming languages.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-mail
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Mail software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-math
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Numerical computation software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-mbone
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>MBone applications.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-misc
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Miscellaneous utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-multimedia
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Multimedia software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-net
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Networking software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-news
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>USENET news software.</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>ports-palm
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Software support for <trademark class="trade">Palm</trademark>
 			  series.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-portuguese
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Portuguese language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-print
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Printing software.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-russian
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Russian language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-security
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Security utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-shells
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Command line shells.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-sysutils
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>System utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-textproc
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>text processing utilities (does not
 			  include desktop publishing).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-vietnamese
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Vietnamese language support.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-www
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Software related to the World Wide
 			  Web.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Ports to support the X window
 			  system.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-clocks
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>X11 clocks.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-fm
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>X11 file managers.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-fonts
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>X11 fonts and font utilities.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-toolkits
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>X11 toolkits.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-servers</literal></term>
 		      
 		      <listitem>
 			<para>X11 servers.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>ports-x11-wm</literal></term>
 		      
 		      <listitem>
 			<para>X11 window managers.</para>
 		      </listitem>
 		    </varlistentry>
 		  </variablelist>
 		</listitem>
 	      </varlistentry>
 
 	      <varlistentry>
 		<term><literal>src-all release=cvs</literal></term>
 		
 		<listitem>
 		  <para>The main FreeBSD sources, including the
 		    cryptography code.</para>
 
 		  <variablelist>
 		    <varlistentry>
 		      <term><literal>src-base
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Miscellaneous files at the top of
 			  <filename>/usr/src</filename>.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-bin
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>User utilities that may be needed in
 			  single-user mode
 			  (<filename>/usr/src/bin</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-contrib
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Utilities and libraries from outside the
 			  FreeBSD project, used relatively unmodified
 			  (<filename>/usr/src/contrib</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-crypto release=cvs</literal></term>
 
 		      <listitem>
 			<para>Cryptography utilities and libraries from
 			  outside the FreeBSD project, used relatively
 			  unmodified
 			  (<filename>/usr/src/crypto</filename>).</para>
 			  </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-eBones release=cvs</literal></term>
 		
 		      <listitem>
 			<para>Kerberos and DES
 			  (<filename>/usr/src/eBones</filename>).  Not
 			  used in current releases of FreeBSD.</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-etc
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>System configuration files
 			  (<filename>/usr/src/etc</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-games
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Games
 			  (<filename>/usr/src/games</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-gnu
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Utilities covered by the GNU Public
 			  License (<filename>/usr/src/gnu</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-include
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Header files
 			  (<filename>/usr/src/include</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-kerberos5
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Kerberos5 security package
 			  (<filename>/usr/src/kerberos5</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-kerberosIV
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>KerberosIV security package
 			  (<filename>/usr/src/kerberosIV</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-lib
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Libraries
 			  (<filename>/usr/src/lib</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-libexec
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>System programs normally executed by other
 			  programs
 			  (<filename>/usr/src/libexec</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>src-release
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>Files required to produce a FreeBSD
 			  release
 			  (<filename>/usr/src/release</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-sbin release=cvs</literal></term>
 
 		      <listitem>
 			<para>System utilities for single-user mode
 			  (<filename>/usr/src/sbin</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 		    
 		    <varlistentry>
 		      <term><literal>src-secure
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Cryptographic libraries and commands
 			  (<filename>/usr/src/secure</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-share
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Files that can be shared across multiple
 			  systems
 			  (<filename>/usr/src/share</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-sys
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>The kernel
 			  (<filename>/usr/src/sys</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-sys-crypto
 			release=cvs</literal></term>
 		
 		      <listitem>
 			<para>Kernel cryptography code
 			  (<filename>/usr/src/sys/crypto</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-tools
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>Various tools for the maintenance of
 			  FreeBSD
 			  (<filename>/usr/src/tools</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-usrbin
 			  release=cvs</literal></term>
 
 		      <listitem>
 			<para>User utilities
 			  (<filename>/usr/src/usr.bin</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 
 		    <varlistentry>
 		      <term><literal>src-usrsbin
 			  release=cvs</literal></term>
 		      
 		      <listitem>
 			<para>System utilities
 			  (<filename>/usr/src/usr.sbin</filename>).</para>
 		      </listitem>
 		    </varlistentry>
 		  </variablelist>
 		</listitem>
 	      </varlistentry>
 	      
 	      <varlistentry>
 		<term><literal>www release=cvs</literal></term>
 		
 		<listitem>
 		  <para>The sources for the FreeBSD WWW site.</para>
 		</listitem>
 	      </varlistentry>
 	    </variablelist>
 	  </listitem>
 	</varlistentry>
 	
 	<varlistentry>
 	  <term><literal>distrib release=self</literal></term>
 
 	  <listitem>
 	    <para>The <application>CVSup</application> server's own 
 	      configuration files.  Used by <application>CVSup</application>
 	      mirror sites.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>gnats release=current</literal></term>
 
 	  <listitem>
 	    <para>The GNATS bug-tracking database.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>mail-archive release=current</literal></term>
 	  
 	  <listitem>
 	    <para>FreeBSD mailing list archive.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>www release=current</literal></term>
 
 	  <listitem>
 	    <para>The pre-processed FreeBSD WWW site files (not the
 	      source files).  Used by WWW mirror sites.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
     </sect2>
 
     <sect2>
       <title>For More Information</title>
 
       <para>For the <application>CVSup</application> FAQ and other 
 	information about <application>CVSup</application>, see
 	<ulink url="http://www.polstra.com/projects/freeware/CVSup/">The
 	  CVSup Home Page</ulink>.</para>
 
       <para>Most FreeBSD-related discussion of
 	<application>CVSup</application> takes place on the
 	&a.hackers;.  New versions of the software are announced there,
 	as well as on the &a.announce;.</para>
       
       <para>Questions and bug reports should be addressed to the author
 	of the program at <email>cvsup-bugs@polstra.com</email>.</para>
     </sect2>
 
     <sect2 id="cvsup-mirrors">
     <title>CVSup Sites</title>
 
     <para><link linkend="cvsup">CVSup</link> servers for FreeBSD are running
       at the following sites:</para>
 
     <variablelist>
       <varlistentry>
 	<term>Argentina</term>
 
 	<listitem>
 	  <itemizedlist>
 
 	    <listitem>
 	      <para>cvsup.ar.FreeBSD.org (maintainer
 		<email>msagre@cactus.fi.uba.ar</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Australia</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.au.FreeBSD.org (maintainer
 		<email>cvsup@ntt.net.au</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.au.FreeBSD.org (maintainer
 		<email>cvsup@isp.net.au</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.au.FreeBSD.org (maintainer
 		<email>cvsup@speednet.com.au</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.au.FreeBSD.org (maintainer
 		<email>cvsup@ideal.net.au</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.au.FreeBSD.org (maintainer
 		<email>cvsup@cvsup5.au.FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <!-- cvsup6.au is currently an alias for cvsup5.au
 	    <listitem>
 	      <para>cvsup6.au.FreeBSD.org (maintainer
 		<email>cvsup@cvsup5.au.FreeBSD.org</email>)</para>
 	    </listitem>
 	    -->
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Austria</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.at.FreeBSD.org (maintainer
 		<email>postmaster@wu-wien.ac.at</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.at.FreeBSD.org (maintainer
 		<email>ftp-admin.zid@univie.ac.at</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Brazil</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.br.FreeBSD.org (maintainer
 		<email>cvsup@cvsup.br.FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.br.FreeBSD.org (maintainer
 		<email>tps@ti.sk</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.br.FreeBSD.org (maintainer
 		<email>camposr@matrix.com.br</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.br.FreeBSD.org (maintainer
 		<email>cvsup@tcoip.com.br</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.br.FreeBSD.org (maintainer
 		<email>hostmaster@br.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Bulgaria</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.bg.FreeBSD.org (maintainer
 		<email>hostmaster@bg.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Canada</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.ca.FreeBSD.org (maintainer
 		<email>cvsup@ca.FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <!--
 	    <listitem>
 	      <para>cvsup2.ca.FreeBSD.org (maintainer
 		<email>hostmaster@ca.FreeBSD.org</email>)</para>
 	    </listitem>
 	    -->
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>China</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.cn.FreeBSD.org (maintainer
 		<email>phj@cn.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Czech Republic</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.cz.FreeBSD.org (maintainer
 	      <email>cejkar@fit.vutbr.cz</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Denmark</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.dk.FreeBSD.org (maintainer
 	      <email>jesper@skriver.dk</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.dk.FreeBSD.org (maintainer
 	      <email>morten@skriver.dk</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Estonia</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.ee.FreeBSD.org (maintainer
 		<email>taavi@uninet.ee</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Finland</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.fi.FreeBSD.org (maintainer
 		<email>count@key.sms.fi</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.fi.FreeBSD.org (maintainer
 		<email>count@key.sms.fi</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>France</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.fr.FreeBSD.org (maintainer
 		<email>hostmaster@fr.FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.fr.FreeBSD.org (maintainer
 		<email>ftpmaint@uvsq.fr</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.fr.FreeBSD.org (maintainer
 		<email>ftpmaint@enst.fr</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.fr.FreeBSD.org (maintainer
 		<email>ftpmaster@t-online.fr</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.fr.FreeBSD.org (maintainer
 		<email>freebsdcvsup@teaser.net</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup8.fr.FreeBSD.org (maintainer
 		<email>ftpmaint@crc.u-strasbg.fr</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Germany</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.de.FreeBSD.org (maintainer
 		<email>cvsup@cosmo-project.de</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.de.FreeBSD.org (maintainer
 		<email>cvsup@apfel.de</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.de.FreeBSD.org (maintainer
 		<email>ag@leo.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.de.FreeBSD.org (maintainer
 		<email>cvsup@cosmo-project.de</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.de.FreeBSD.org (maintainer
 		&a.rse;)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup6.de.FreeBSD.org (maintainer
 		<email>adminmail@heitec.net</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup7.de.FreeBSD.org (maintainer
 		<email>karsten@rohrbach.de</email>)</para>
 	    </listitem>
 
 
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Greece</term>
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.gr.FreeBSD.org (maintainer
 	      <email>ftpadm@duth.gr</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.gr.FreeBSD.org (maintainer
 	      <email>paschos@cs.uoi.gr</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Hungary</term>
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.hu.FreeBSD.org (maintainer
 	      <email>janos.mohacsi@bsd.hu</email>)</para>
 	    </listitem>
 
 	    <!--
 	    <listitem>
 	      <para>cvsup2.hu.FreeBSD.org (maintainer
 	      <email>hostmaster@cvsup2.hu.FreeBSD.org</email>)</para>
 	    </listitem>
 	    -->
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Iceland</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.is.FreeBSD.org (maintainer
 	      <email>hostmaster@is.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Ireland</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.ie.FreeBSD.org (maintainer
 	      <email>dwmalone@maths.tcd.ie</email>),
 	      Trinity College, Dublin.</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Japan</term>
 
 	<listitem>
 	  <itemizedlist>
 
 	    <listitem>
 	      <para>cvsup.jp.FreeBSD.org (maintainer
 		<email>cvsupadm@jp.FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.jp.FreeBSD.org (maintainer
 		&a.max;)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.jp.FreeBSD.org (maintainer
 		<email>shige@cin.nihon-u.ac.jp</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.jp.FreeBSD.org (maintainer
 		<email>cvsup-admin@ftp.media.kyoto-u.ac.jp</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.jp.FreeBSD.org (maintainer
 		<email>cvsup@imasy.or.jp</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup6.jp.FreeBSD.org (maintainer
 		<email>cvsupadm@jp.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Korea</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.kr.FreeBSD.org (maintainer
 		<email>cjh@kr.FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.kr.FreeBSD.org (maintainer
 		<email>holywar@mail.holywar.net</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.kr.FreeBSD.org (maintainer
 		<email>hostmaster@cvsup3.kr.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Latvia</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.lv.FreeBSD.org (maintainer
 		<email>system@soft.lv</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Lithuania</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.lt.FreeBSD.org (maintainer
 		<email>domas.mituzas@delfi.lt</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.lt.FreeBSD.org (maintainer
 		<email>vaidas.damosevicius@sampo.lt</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
 
       <varlistentry>
 	<term>New Zealand</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.nz.FreeBSD.org (maintainer
 		<email>cvsup@langille.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Netherlands</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.nl.FreeBSD.org (maintainer
 		<email>xaa@xaa.iae.nl</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.nl.FreeBSD.org (maintainer
 		<email>cvsup@nl.uu.net</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.nl.FreeBSD.org (maintainer
 		<email>cvsup@vuurwerk.nl</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.nl.FreeBSD.org (maintainer
 		<email>hostmaster@cvsup4.nl.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Norway</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.no.FreeBSD.org (maintainer
 		<email>Per.Hove@math.ntnu.no</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Poland</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.pl.FreeBSD.org (maintainer
 		<email>Mariusz@kam.pl</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.pl.FreeBSD.org (maintainer
 		<email>hostmaster@cvsup2.pl.FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.pl.FreeBSD.org (maintainer
 		<email>hostmaster@cvsup3.pl.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Portugal</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.pt.FreeBSD.org (maintainer
 		<email>jpedras@webvolution.net</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
         <term>Romania</term>
 
         <listitem>
           <itemizedlist>
             <listitem>
               <para>cvsup.ro.FreeBSD.org (maintainer
                 <email>razor@ldc.ro</email>)</para>
             </listitem>
 
 	    <listitem>
 	      <para>cvsup2.ro.FreeBSD.org (maintainer
 	        <email>hostmaster@rofug.ro</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.ro.FreeBSD.org (maintainer
 	        <email>veedee@c7.campus.utcluj.ro</email>)</para>
 	    </listitem>
           </itemizedlist>
         </listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Russia</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.ru.FreeBSD.org (maintainer
 		<email>ache@nagual.pp.ru</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.ru.FreeBSD.org (maintainer
 		<email>dv@dv.ru</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.ru.FreeBSD.org (maintainer
 		<email>fjoe@iclub.nsu.ru</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.ru.FreeBSD.org (maintainer
 		<email>zhecka@klondike.ru</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.ru.FreeBSD.org (maintainer
 		<email>maxim@macomnet.ru</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup6.ru.FreeBSD.org (maintainer
 		<email>pvr@corbina.net</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>San Marino</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.sm.FreeBSD.org (maintainer
 		<email>sysadmin@alexdupre.com</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Singapore</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.sg.FreeBSD.org (maintainer
 		<email>mirror-maintainer@mirror.averse.net</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Slovak Republic</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.sk.FreeBSD.org (maintainer
 		<email>tps@tps.sk</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.sk.FreeBSD.org (maintainer
 		<email>tps@tps.sk</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Slovenia</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.si.FreeBSD.org (maintainer
 	      <email>blaz@si.FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.si.FreeBSD.org (maintainer
 	      <email>cuk@cuk.nu</email>)</para>
 	    </listitem>
 	   </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>South Africa</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.za.FreeBSD.org (maintainer
 		&a.markm;)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.za.FreeBSD.org (maintainer
 		&a.markm;)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Spain</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.es.FreeBSD.org (maintainer
 	      &a.jesusr;)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.es.FreeBSD.org (maintainer
 	      &a.jesusr;)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.es.FreeBSD.org (maintainer
 	      <email>jose@we.lc.ehu.es</email>)</para>
 	    </listitem>
 	   </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Sweden</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.se.FreeBSD.org (maintainer
 	      <email>pantzer@ludd.luth.se</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.se.FreeBSD.org (maintainer
 	      <email>cvsup@dataphone.net</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Taiwan</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.tw.FreeBSD.org (maintainer
 		<email>ijliao@FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <!--
 	    <listitem>
 	      <para>cvsup2.tw.FreeBSD.org (maintainer
 		<email>ycheng@sinica.edu.tw</email>)</para>
 	    </listitem>
 	    -->
 
 	    <listitem>
 	      <para>cvsup3.tw.FreeBSD.org (maintainer
 		<email>foxfair@FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.tw.FreeBSD.org (maintainer
 		<email>einstein@NHCTC.edu.tw</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.tw.FreeBSD.org (maintainer
 		<email>einstein@NHCTC.edu.tw</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup6.tw.FreeBSD.org (maintainer
 		<email>jason@tw.FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup7.tw.FreeBSD.org (maintainer
 		<email>cvsup@abpe.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup8.tw.FreeBSD.org (maintainer
 		<email>heboy@FreeBSD.tku.edu.tw</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup9.tw.FreeBSD.org (maintainer
 		<email>cs871256@csie.ncu.edu.tw</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup10.tw.FreeBSD.org (maintainer
 		<email>rafan@infor.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup11.tw.FreeBSD.org (maintainer
 		<email>vanilla@FreeBSD.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup12.tw.FreeBSD.org (maintainer
 		<email>GEO.bbs@birdnest.twbbs.org</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup13.tw.FreeBSD.org (maintainer
 		<email>cdsheen@tw.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Turkey</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.tr.FreeBSD.org (maintainer
 		<email>roots@enderunix.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Ukraine</term>
 
 	<listitem>
 	  <itemizedlist>
 
 	    <listitem>
 	      <para>cvsup2.ua.FreeBSD.org (maintainer
 		<email>freebsd-mnt@lucky.net</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.ua.FreeBSD.org (maintainer
 		<email>ftpmaster@ukr.net</email>), Kiev</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.ua.FreeBSD.org (maintainer
 		<email>phantom@cris.net</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.ua.FreeBSD.org (maintainer
 		<email>never@nevermind.kiev.ua</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>United Kingdom</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup.uk.FreeBSD.org (maintainer
 		<email>ftp-admin@plig.net</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.uk.FreeBSD.org (maintainer
 		&a.brian;)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.uk.FreeBSD.org (maintainer
 		<email>ben.hughes@uk.easynet.net</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup4.uk.FreeBSD.org (maintainer
 		<email>ejb@leguin.org.uk</email>)</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.uk.FreeBSD.org (maintainer
 		<email>mirror@teleglobe.net</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>USA</term>
 
 	<listitem>
 	  <itemizedlist>
 	    <listitem>
 	      <para>cvsup1.FreeBSD.org (maintainer
 		<email>cwt@networks.cwu.edu</email>), Washington
 		state</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup2.FreeBSD.org (maintainers
 		<email>djs@secure.net</email> and &a.nectar;), Virginia</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup3.FreeBSD.org (maintainer
 		&a.wollman;), Massachusetts</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup5.FreeBSD.org (maintainer
 		<email>mjr@blackened.com</email>), Arizona</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup6.FreeBSD.org (maintainer
 		<email>cvsup@cvsup.adelphiacom.net</email>), Illinois</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup7.FreeBSD.org (maintainer
 		&a.jdp;), Washington state</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup8.FreeBSD.org (maintainer
 		<email>hostmaster@bigmirror.com</email>), Washington
 		state</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup9.FreeBSD.org (maintainer
 		&a.jdp;), Minnesota</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup10.FreeBSD.org (maintainer
 		&a.jdp;), California</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup11.FreeBSD.org (maintainer
 		<email>cvsup@research.uu.net</email>), Virginia</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup12.FreeBSD.org (maintainer
 		&a.will;), Indiana</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup13.FreeBSD.org (maintainer
 		<email>dima@valueclick.com</email>), California</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup14.FreeBSD.org (maintainer
 		<email>freebsd-cvsup@mfnx.net</email>), California</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup15.FreeBSD.org (maintainer
 		<email>cvsup@math.uic.edu</email>), Illinois</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup16.FreeBSD.org (maintainer
 		<email>pth3k@virginia.edu</email>), Virginia</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup17.FreeBSD.org (maintainer
 		<email>cvsup@mirrortree.com</email>), Washington state</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>cvsup18.FreeBSD.org (maintainer
 		<email>hostmaster@cvsup18.FreeBSD.org</email>)</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect2>
   </sect1>
   
   <sect1 id="cvs-tags">
     <title>CVS Tags</title>
 
     <para>When obtaining or updating sources from
       <application>cvs</application> and
       <application>CVSup</application> a revision tag (reference to a
       date in time) must be specified.  The following tags are
       available, each specifying different branches of FreeBSD at
       different points of time:</para>
 
     <note>
       <para>The ports tree does not have any tag associated with it,
 	it is always CURRENT.</para>
     </note>
 
     <para>The most common tags are:</para>
 
     <variablelist>
       <varlistentry>
 	<term>HEAD</term>
 
 	<listitem>
 	  <para>Symbolic name for the main line, or FreeBSD-CURRENT.
 	    Also the default when no revision is specified.</para>
 
 	  <para>In <application>CVSup</application>, this tag is represented
 	    by a <literal>.</literal> (not punctuation, but a literal
 	    <literal>.</literal> character).</para>
 
 	  <note>
 	    <para>In CVS, this is the default when no revision tag is
 	      specified.  It is usually <emphasis>not</emphasis>
 	      a good idea to checkout or update to CURRENT sources
 	      on a STABLE machine, unless that is your intent.</para>
 	  </note>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4</term>
 
 	<listitem>
 	  <para>The line of development for FreeBSD-4.X, also known
 	    as FreeBSD-STABLE.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_7</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.7, used only 
 	    for security advisories and other seriously critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_6</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.6 and FreeBSD-4.6.2,
             used only for security advisories and other seriously
             critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_5</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.5, used only
 	    for security advisories and other seriously critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_4</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.4, used only
 	    for security advisories and other seriously critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_3</term>
 
 	<listitem>
 	  <para>The release branch for FreeBSD-4.3, used only
 	    for security advisories and other seriously critical fixes.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3</term>
 
 	<listitem>
 	  <para>The line of development for FreeBSD-3.X, also known
 	    as 3.X-STABLE.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2</term>
 
 	<listitem>
 	  <para>The line of development for FreeBSD-2.2.X, also known
 	    as 2.2-STABLE.  This branch is mostly obsolete.</para>
 	</listitem>
     </variablelist>
 
     <para>Other revision tags that are available include:</para>
 
     <variablelist>
       <varlistentry>
 	<term>RELENG_4_7_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.7</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_6_2_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.6.2</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_6_1_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.6.1</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_6_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.6</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_5_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.5.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_4_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.4.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_3_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.3.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_2_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.2.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_1_1_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.1.1.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_1_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.1.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_4_0_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD 4.0.</para>
 	</listitem>
       </varlistentry>
 	  
       <varlistentry>
 	<term>RELENG_3_5_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.5.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_4_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.4.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_3_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.3.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_2_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.2.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_1_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.1.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_3_0_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-3.0.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_8_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.8.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_7_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.7.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_6_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.6.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_5_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.5.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_2_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.2.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_1_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.1.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>RELENG_2_2_0_RELEASE</term>
 
 	<listitem>
 	  <para>FreeBSD-2.2.0.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
   <sect1 id="mirrors-afs">
     <title>AFS Sites</title>
 
     <para>AFS servers for FreeBSD are running at the following sites:</para>
 
     <variablelist>
       <varlistentry>
 	<term>Sweden</term>
 
 	<listitem>
 	  <para>The path to the files are:
   	    <filename>/afs/stacken.kth.se/ftp/pub/FreeBSD/</filename></para>
 
 	  <programlisting>stacken.kth.se         # Stacken Computer Club, KTH, Sweden
 130.237.234.43         #hot.stacken.kth.se
 130.237.237.230        #fishburger.stacken.kth.se
 130.237.234.3          #milko.stacken.kth.se</programlisting>
 
 	  <para>Maintainer <email>ftp@stacken.kth.se</email></para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
   <sect1 id="mirrors-rsync">
     <title>rsync sites</title>
 
     <para>The following sites make FreeBSD available through the rsync
       protocol.  The <application>rsync</application> utility works in
       much the same way as the <application>rcp</application> command,
       but has more options and uses the rsync remote-update protocol
       which transfers only the differences between two sets of files,
       thus greatly speeding up the synchronization over the network.  
       This is most useful if you are a mirror site for the
       FreeBSD FTP server, or the CVS repository.  The
       <application>rsync</application> suite is available for many
       operating systems, on FreeBSD, see the
       <filename>net/rsync</filename>
       port or use the package.</para>
 
     <variablelist>
       <varlistentry>
 	<term>Czech Republic</term>
 
 	<listitem>
 	  <para>rsync://ftp.cz.freebsd.org/</para>
 
 	  <para>Available collections:</para>
 	  <itemizedlist>
 	    <listitem><para>ftp: A partial mirror of the FreeBSD FTP
 	      server.</para></listitem>
 	    <listitem><para>FreeBSD: A full mirror of the FreeBSD FTP
 	      server.</para></listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Germany</term>
 
 	<listitem>
 	  <para>rsync://grappa.unix-ag.uni-kl.de/</para>
 
 	  <para>Available collections:</para>
 	  <itemizedlist>
 	    <listitem><para>freebsd-cvs: The full FreeBSD CVS
 	      repository.</para></listitem>
 	  </itemizedlist>
 	  <para>This machine also mirrors the CVS repositories of the
 	    NetBSD and the OpenBSD projects, among others.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>United States of America</term>
 
 	<listitem>
 	  <para>rsync://ftp-master.freebsd.org/<para>
 
 	  <para>This server may only be used by FreeBSD primary mirror
 	    sites.</para>
 	  <para>Available collections:</para>
 	  <itemizedlist>
 	    <listitem><para>FreeBSD: The master archive of the FreeBSD
 	      FTP server.</para></listitem>
 	    <listitem><para>acl: The FreeBSD master ACL
 	      list.</para></listitem>  
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>  
 </appendix>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../appendix.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "appendix")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
index 360a8da316..12497d9762 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
@@ -1,1584 +1,1584 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="ports">
   <title>Installing Applications: Packages and Ports</title>
 
-  <sect1>
+  <sect1 id="ports-synopsis">
     <title>Synopsis</title>
 
     <indexterm><primary>ports</primary></indexterm>
     <indexterm><primary>packages</primary></indexterm>
     <para>FreeBSD is bundled with a rich collection of system tools as
       part of the base system.  However, there is only so much one can
       do before needing to install an additional third-party
       application to get real work done.  FreeBSD provides two
       complementary technologies for installing third party software
       on your system: the FreeBSD Ports Collection, and binary
       software packages.  Either system may be used to install the
       newest version of your favorite applications from local media or
       straight off the network.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How to install third-party binary software packages.</para>
       </listitem>
       <listitem>
 	<para>How to build third-party software from the ports
 	collection.</para>
       </listitem>
       <listitem>
 	<para>How to remove previously installed packages or ports.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
-  <sect1>
+  <sect1 id="ports-overview">
     <title>Overview of Software Installation</title>
 
     <para>If you have used a Unix system before you will know that the typical
       procedure for installing third party software goes something like
       this:</para>
 
     <procedure>
       <step>
 	<para>Download the software, which might be distributed in source code
 	  format, or as a binary.</para>
       </step>
 
       <step>
 	<para>Unpack the software from its distribution format (typically a
 	  tarball compressed with either &man.compress.1; or &man.gzip.1;).</para>
       </step>
 
       <step>
 	<para>Locate the documentation (perhaps an <filename>INSTALL</filename> or <filename>README</filename>
 	  file, or some files in a <filename>doc/</filename> subdirectory) and
 	  read up on how to install the software.</para>
       </step>
 
       <step>
 	<para>If the software was distributed in source format, compile it.
 	  This may involve editing a <filename>Makefile</filename>, or
 	  running a <command>configure</command> script, and other work.</para>
       </step>
 
       <step>
 	<para>Test and install the software.</para>
       </step>
     </procedure>
 
     <para>And that is only if everything goes well.  If you are installing a
       software package that was not deliberately ported to FreeBSD you may
       even have to go in and edit the code to make it work properly.</para>
 
     <para>Should you want to, you can continue to install software the
       <quote>traditional</quote> way with FreeBSD.  However, FreeBSD
       provides two technologies which can save you a lot of effort:
       packages and ports.  At the time of writing, over &os.numports;
       third party applications have been made available in this
       way.</para>
 
     <para>For any given application, the FreeBSD package for that application
       is a single file which you must download.  The package contains
       pre-compiled copies of all the commands for the application, as well as
       any configuration files or documentation.  A downloaded package file can
       be manipulated with FreeBSD package management commands, such as
       &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so on.</para>
 
     <para>Installing a new application can be carried out with a single
       command.</para>
 
     <para>A FreeBSD port for an application is a collection of files designed
       to automate the process of compiling an application from source
       code.</para>
 
     <para>Remember that there are a number of steps you would normally carry
       out if you compiled a program yourself (downloading, unpacking, patching, compiling,
       installing).  The files that make up a port contain all the necessary
       information to allow the system to do this for you.  You run a handful
       of simple commands and the source code for the application is
       automatically downloaded, extracted, patched, compiled, and installed
       for you.</para>
 
     <para>In fact, the ports system can also be used to generate packages
       which can later be manipulated with <command>pkg_add</command>
       and the other package management commands that will be introduced
       shortly.</para>
 
     <para>Both packages and ports understand
       <emphasis>dependencies</emphasis>.  Suppose you want to install an
       application that depends on a specific library being installed.  Both
       the application and the library have been made available as FreeBSD
       ports and packages.  If you use the <command>pkg_add</command> command
       or the ports system to add the application, both will notice that the
       library has not been installed, and automatically install the
       library first.</para>
 
     <para>Given that the two technologies are quite similar, you might be
       wondering why FreeBSD bothers with both.  Packages and ports both have
       their own strengths, and which one you use will depend on your own
       preference.</para>
 
     <itemizedlist>
       <title>Package Benefits</title>
       
       <listitem>
 	<para>A compressed package tarball is typically smaller than the
 	  compressed tarball containing the source code for the application.</para>
       </listitem>
 
       <listitem>
 	<para>Packages do not require any additional compilation.  For large
 	  applications, such as <application>Mozilla</application>,
 	  <application>KDE</application>, or <application>GNOME</application>
 	  this can be important, particularly if you are on a slow system.</para>
       </listitem>
 
       <listitem>
 	<para>Packages do not require you to understand the process
 	  involved in compiling software on FreeBSD.</para>
       </listitem>
     </itemizedlist>
 
     <itemizedlist>
       <title>Ports Benefits</title>
       
       <listitem>
 	<para>Packages are normally compiled with conservative options,
 	  because they have to run on the maximum number of systems.  By
 	  installing from the port, you can tweak the compilation options to
 	  (for example) generate code that is specific to a Pentium
 	  III or Athlon processor.</para>
       </listitem>
 
       <listitem>
 	<para>Some applications have compile time options relating to what they
 	  can and cannot do.  For example, <application>Apache</application>
 	  can be configured with a wide variety of different built-in options.
 	  By building from the port you do not have to accept the default
 	  options, and can set them yourself.</para>
 
 	<para>In some cases, multiple packages will exist for the same
 	  application to specify certain settings.  For example,
 	  <application>Ghostscript</application> is available as a
 	  <filename>ghostscript</filename> package and a
 	  <filename>ghostscript-nox11</filename> package, depending on whether
 	  or not you have installed an X11 server.  This sort of rough
 	  tweaking is possible with packages, but rapidly becomes impossible
 	  if an application has more than one or two different compile time
 	  options.</para>
       </listitem>
 
       <listitem>
 	<para>The licensing conditions of some software distributions forbid
 	  binary distribution.  They must be distributed as source
 	  code.</para>
       </listitem>
 
       <listitem>
 	<para>Some people do not trust binary distributions.  At least with
 	  source code, you can (in theory) read through it and look for
 	  potential problems yourself.</para>
       </listitem>
 
       <listitem>
 	<para>If you have local patches, you will need the source in order to
 	  apply them.</para>
       </listitem>
 
       <listitem>
 	<para>Some people like having code around, so they can read it if they
 	  get bored, hack it, borrow from it (license permitting, of course),
 	  and so on.</para>
       </listitem>
     </itemizedlist>
 
     <para>To keep track of updated ports, subscribe to the
       &a.ports;.</para>
 
     <para>The remainder of this chapter will explain how to use packages and
       ports to install and manage third party software on FreeBSD.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="ports-finding-applications">
     <title>Finding Your Application</title>
 
     <para>Before you can install any applications you need to know what you
       want, and what the application is called.</para>
 
     <para>FreeBSD's list of available applications is growing all the
       time.  Fortunately, there are a number of ways to
       find what you want:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The FreeBSD web site maintains an up-to-date searchable list of
 	  all the available applications, at
 	  <ulink url="../../../../ports/index.html">http://www.FreeBSD.org/ports/</ulink>.
 	  The ports are divided into categories, and you may either
 	  search for an application by name (if you know it), or see
 	  all the applications available in a category.</para>
       </listitem>
 
       <indexterm><primary>FreshPorts</primary></indexterm>
 
       <listitem>
 	<para>Dan Langille maintains FreshPorts, at
 	  <ulink url="http://www.FreshPorts.org/">http://www.FreshPorts.org/</ulink>.
 	  FreshPorts tracks changes to the applications in the ports tree as
 	  they happen, allows you to <quote>watch</quote> one or more
 	  ports, and can send you email when they are updated.</para>
       </listitem>
 
       <indexterm><primary>FreshMeat</primary></indexterm>
 
       <listitem>
 	<para>If you do not know the name of the application you want, try
 	  using a site like FreshMeat
 	  (<ulink url="http://www.freshmeat.net/">http://www.freshmeat.net/</ulink>)
 	  to find an application, then check back at the FreeBSD site to see
 	  if the application has been ported yet.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="packages-using">
     <sect1info>    
       <authorgroup>
         <author>
           <firstname>Chern</firstname>
 	  <surname>Lee</surname>
 	  <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     <!-- 30 Mar 2001 -->
     </sect1info>
 
     <title>Using the Packages System</title>
 
     <sect2>
       <title>Installing a Package</title>
       <indexterm>
         <primary>packages</primary>
         <secondary>installing</secondary>
       </indexterm>
     
       <indexterm>
         <primary><command>pkg_add</command></primary>
       </indexterm>
       <para>You can use the &man.pkg.add.1; utility to install a
 	FreeBSD software package from a local file or from a server on
 	the network.</para>
 
       <example>
         <title>Downloading a Package Manually and then Installing It Locally</title>
 
         <screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput>
 Connected to ftp2.FreeBSD.org.
 220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
 331 Guest login ok, send your email address as password.
 230-
 230-     This machine is in Vienna, VA, USA, hosted by Verio.
 230-         Questions? E-mail freebsd@vienna.verio.net.
 230-
 230-
 230 Guest login ok, access restrictions apply.
 Remote system type is UNIX.
 Using binary mode to transfer files.
 <prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/packages/sysutils/</userinput>
 250 CWD command successful.
 <prompt>ftp></prompt> <userinput>get lsof-4.56.4.tgz</userinput>
 local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
 200 PORT command successful.
 150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
 100% |**************************************************| 92375       00:00 ETA
 226 Transfer complete.
 92375 bytes received in 5.60 seconds (16.11 KB/s)
 <prompt>ftp></prompt> <userinput>exit</userinput>
 &prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen>
       </example>
 
       <para>If you do not have a source of local packages (such as a
         FreeBSD CD-ROM set) then it will probably be easier to use the
         <option>-r</option> option to &man.pkg.add.1;.  This will cause the utility to
         automatically determine the correct object format and release
         and then fetch and install the package from an FTP site.
       </para>
 
       <indexterm>
         <primary><command>pkg_add</command></primary></indexterm>
       <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen>
 
       <para>The example above would download the correct package and add 
 	it without any further user intervention.  &man.pkg.add.1; uses 
 	  &man.fetch.3; to download the files, which honours various 
 	environment variables, including <envar>FTP_PASSIVE_MODE</envar>, 
 	<envar>FTP_PROXY</envar>, and <envar>FTP_PASSWORD</envar>.  You 
 	may need to set one or more of these if you are behind a firewall, 
 	or need to use an FTP/HTTP proxy.  See &man.fetch.3; for the 
 	complete list.  You can also note that in the example above
 	<literal>lsof</literal> is used instead of
 	<literal>lsof-4.56.4</literal>.  When the remote fetching
 	feature is used, the version number of the package must be
 	removed.  &man.pkg.add.1; will automatically fetch the latest
 	version of the application.</para>
 
       <para>Package files are distributed in <filename>.tgz</filename> format.  You can
           find them at <ulink
           url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">
           ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/</ulink>,
           or on the FreeBSD CD-ROM distribution.  Every CD on the
           FreeBSD 4-CD set (and the PowerPak, etc.) contains packages in
           the <filename>/packages</filename> directory.  The layout of
           the packages is similar to that of the
           <filename>/usr/ports</filename> tree.  Each category has its
           own directory, and every package can be found within the
           <filename>All</filename> directory.
       </para>
 
       <para>The directory structure of the package system matches
         the ports layout; they work with each other to form the entire
         package/port system.
       </para>
 
     </sect2>
 
     <sect2>
       <title>Managing Packages</title>
 
       <indexterm>
         <primary>packages</primary>
         <secondary>managing</secondary>
       </indexterm>
       <para>&man.pkg.info.1; is a utility that lists and describes 
         the various packages installed.
       </para>
 
       <indexterm>
         <primary><command>pkg_info</command></primary>
       </indexterm>
       <screen>&prompt.root; <userinput>pkg_info</userinput>
 cvsup-16.1          A general network file distribution system optimized for CV
 docbook-1.2         Meta-port for the different versions of the DocBook DTD
 ...</screen>
       <para>&man.pkg.version.1; is a utility that summarizes the
         versions of all installed packages.  It compares the package 
         version to the current version found in the ports tree.
       </para> 
       <indexterm>
         <primary><command>pkg_version</command></primary>
       </indexterm>
         <screen>&prompt.root; <userinput>pkg_version</userinput>
 cvsup                       =
 docbook                     =
 ...</screen>
 
       <para>The symbols in the second column indicate the relative age
       of the installed version and the version available in the local
       ports tree.</para>
 
       <informaltable frame="none">
         <tgroup cols="2">
 	  <thead>
             <row>
               <entry>Symbol</entry>
               <entry>Meaning</entry>
             </row>
           </thead>
 
  	  <tbody>
   	    <row>
 	    <entry>=</entry> <entry>The version of the
 	    installed package matches that of the one found in the
 	    local ports tree.</entry>
   	    </row>
  
         <row><entry>&lt;</entry>
 	<entry>The installed version is older than the one available
 	in the ports tree.</entry>
 	</row>
 
         <row><entry>&gt;</entry><entry>The installed version is newer
           than the one found in the local ports tree. (local ports
           tree is probably out of date)</entry></row>
 
         <row><entry>?</entry><entry>The installed package cannot be
         found in the ports index.</entry></row>
 
         <row><entry>*</entry><entry>There are multiple versions of the
         package.</entry></row>
 
 	</tbody>
 	</tgroup>
     </informaltable>
     </sect2>
 
     <sect2>
       <title>Deleting a Package</title>
       <indexterm>
         <primary><command>pkg_delete</command></primary>
       </indexterm>
       <indexterm>
         <primary>packages</primary>
         <secondary>deleting</secondary>
       </indexterm>
       <para>To remove a previously installed software package, use the
 	&man.pkg.delete.1; utility.
       </para>
 
       <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>
     </sect2>
 
     <sect2>
       <title>Miscellaneous</title>
       <para>All package information is stored within the 
         <filename>/var/db/pkg</filename> directory.  The installed
 	file list and descriptions of each package can be found within 
         files in this directory.
       </para>
     </sect2>
   </sect1>
   
   <sect1 id="ports-using">
     <title>Using the Ports Collection</title>
 
     <para>The following sections provide basic instructions on using the
       ports collection to install or remove programs from your
       system.</para>
 
     <sect2 id="ports-tree">
       <title>Obtaining the Ports Collection</title>
 
       <para>Before you can install ports, you must first obtain the
 	ports collection&mdash;which is essentially a set of <filename>Makefiles</filename>,
 	patches, and description files placed in
 	<filename>/usr/ports</filename>.
       </para>
 
       <para>When installing your FreeBSD system,
 	<application>Sysinstall</application> asked if you would like to
 	install the ports collection.  If you chose no, you can follow
 	these instructions to obtain the ports collection:</para>
 
       <procedure>
 	<title>Sysinstall Method</title>
 
 	<para>This method involves using
 	  <application>sysinstall</application> again to manually
 	  install the ports collection.</para>
 
 	<step>
 	  <para>As <username>root</username>, run <command>/stand/sysinstall</command> as
 	    shown below:</para>
 
 	  <screen>&prompt.root; <userinput>/stand/sysinstall</userinput></screen>
 	</step>
 
 	<step>
 	  <para>Scroll down and select <guimenuitem>Configure</guimenuitem>,
 	    press <keycap>Enter</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>Scroll down and select
 	    <guimenuitem>Distributions</guimenuitem>, press <keycap>Enter</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>Scroll down to <guimenuitem>ports</guimenuitem>, press
 	    <keycap>Space</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>Scroll up to <guimenuitem>Exit</guimenuitem>, press
 	    <keycap>Enter</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>Select your desired installation media, such as CDROM,
 	    FTP, and so on.</para>
 	</step>
 
 	<step>
 	  <para>Scroll up to <guimenuitem>Exit</guimenuitem> and press
 	    <keycap>Enter</keycap>.</para>
 	</step>
 
 	<step>
 	  <para>Press <keycap>X</keycap> to exit
 	    <application>sysinstall</application>.</para>
 	</step>
       </procedure>
 
       <para>The alternative method to obtain and keep your ports
 	collection up to date is by using
 	<application>CVSup</application>.  Look at the ports
 	<application>CVSup</application> file,
 	<filename>/usr/share/examples/cvsup/ports-supfile</filename>.
 	See <link linkend="cvsup">Using CVSup</link> (<xref
 	  linkend="cvsup">) for more information on using
 	<application>CVSup</application> and this file.</para>
 
       <procedure>
 	<title>CVSup Method</title>
 
 	<para>This is a quick method for getting the ports collection
 	  using <application>CVSup</application>.  If you want to keep
 	  your ports tree up to date, or learn more about
 	  <application>CVSup</application>, read the previously
 	  mentioned sections.</para>
 
 	<step>
 	  <para>Install the <filename role="package">net/cvsup</filename> port.  See <link
 	      linkend="cvsup-install">CVSup Installation</link> (<xref
 	      linkend="cvsup-install">) for more details.</para>
 	</step>
 
 	<step>
 	  <para>As <username>root</username>, copy
 	    <filename>/usr/share/examples/cvsup/ports-supfile</filename>
 	    to a new location, such as <filename>/root</filename> or your
 	      home directory.</para>
 	</step>
 
 	<step>
 	  <para>Edit <filename>ports-supfile</filename>.</para>
 	</step>
 
 	<step>
 	  <para>Change <replaceable>CHANGE_THIS.FreeBSD.org</replaceable> to a
 	    <application>CVSup</application> server near you.  See <link
 	      linkend="cvsup-mirrors">CVSup Mirrors</link> (<xref
 	      linkend="cvsup-mirrors">) for a complete listing of mirror
 	    sites.</para>
 	</step>
 
 	<step>
 	  <para>Run <command>cvsup</command>:</para>
 
 	  <screen>&prompt.root; <userinput>cvsup -g -L 2 <replaceable>/root/ports-supfile</replaceable></userinput></screen>
 	</step>
 
 	<step>
 	  <para>Running this command later will
 	    download and apply all the recent changes to your ports
 	    collection, except actually rebuilding the ports for your own system.</para>
 	</step>
       </procedure>
     </sect2>
 
     <sect2 id="ports-skeleton">
       <title>Installing Ports</title>
 
       <indexterm>
         <primary>ports</primary>
         <secondary>installing</secondary>
       </indexterm>
       <para>The first thing that should be explained
         when it comes to the ports collection is what is actually meant
 	by a <quote>skeleton</quote>.  In a nutshell, a port skeleton is a
 	minimal set of files that tell your FreeBSD system how to
         cleanly compile and install a program.  Each port skeleton includes:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>A <filename>Makefile</filename>.  The
 	    <filename>Makefile</filename> contains various statements that
 	    specify how the application should be compiled and where it
 	    should be installed on your system.</para>
 	</listitem>
 
 	<listitem>
 	  <para>A <filename>distinfo</filename> file.  This file contains
 	    information about the files that must be downloaded to build the
 	    port and their checksums, to verify that files have not been
 	    corrupted during the download.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>A <filename>files</filename> directory.  This directory
 	    contains patches to make the program compile and install on
 	    your FreeBSD system.  Patches are basically small files that
 	    specify changes to particular files.  They are in plain text
 	    format, and basically say <quote>Remove line 10</quote> or
 	    <quote>Change line 26 to this ...</quote>.  Patches are also
 	    known as <quote>diffs</quote> because they are generated by the
 	    &man.diff.1; program.</para>
 
 	  <para>This directory may also contain other files used to build
 	    the port.</para>
 	</listitem>
 
 	<listitem>
 	  <para>A <filename>pkg-comment</filename> file.  This is a one-line
 	    description of the program.</para>
 	</listitem>
 
 	<listitem>
 	  <para>A <filename>pkg-descr</filename> file.  This is a more
 	    detailed, often multiple-line, description of the program.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>A <filename>pkg-plist</filename> file.  This is a list of all
 	    the files that will be installed by the port.  It also tells the
 	    ports system what files to remove upon deinstallation.</para>
 	</listitem>
       </itemizedlist>
 
       <para>Some ports have other files, such as
         <filename>pkg-message</filename>.  The ports system uses these
         files to handle special situations.  If you want more details
         on these files, and on ports in general, check out the <ulink
         url="../porters-handbook/index.html">FreeBSD Porter's
         Handbook</ulink>.</para>
 
       <para>Now that you have enough background information to know what
         the ports collection is used for, you are ready to install your
 	first port.  There are two ways this can be done, and each is
 	explained below.</para>
 
       <para>Before we get into that, however, you will need to choose a
         port to install.  There are a few ways to do this, with the
 	easiest method being the <ulink
 	url="../../../../ports/index.html">ports listing on the FreeBSD
 	web site</ulink>.  You can browse through the ports listed there
 	or use the search function on the site.  Each port also includes
 	a description so you can read a bit about each port before
 	deciding to install it.</para>
 
       <para>Another method is to use the &man.whereis.1;
         command.  Simply type <command>whereis <replaceable>file</replaceable></command>,
 	where <replaceable>file</replaceable> is the program you want to
 	install.  If it is found on
         your system, you will be told where it is, as follows:</para>
 
       <screen>&prompt.root; <userinput>whereis lsof</userinput>
 lsof: /usr/ports/sysutils/lsof</screen>
 
       <para>This tells us that <command>lsof</command> (a system utility)
 	can be found in the
         <filename>/usr/ports/sysutils/lsof</filename> directory.</para>
 
       <para>Yet another way to find a particular port is by using the
         ports collection's built-in search mechanism.  To use the search
         feature, you will need to be in the
 	<filename>/usr/ports</filename> directory.  Once in that
 	directory, run <command>make search name=<replaceable>program-name</replaceable></command>
 	where <replaceable>program-name</replaceable> is the name of the program you
 	want to find.  For example, if you were looking for 
 	<command>lsof</command>:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make search name=lsof</userinput>
 Port:   lsof-4.56.4
 Path:   /usr/ports/sysutils/lsof
 Info:   Lists information about open files (similar to fstat(1))
 Maint:  obrien@FreeBSD.org
 Index:  sysutils
 B-deps: 
 R-deps: </screen>
 
       <para>The part of the output you want to pay particular attention
         to is the <quote>Path:</quote> line, since that tells you where to
 	find the port.  The other information provided is not needed in order
 	to install the port, so it will not be covered
 	here.</para>
 
       <para>For more in-depth searching you can also use
        <command>make search key=<replaceable>string</replaceable></command> where 
        <replaceable>string</replaceable> is some text to search for.  This searches 
        port names, comments, descriptions and dependencies and can be used 
        to find ports which relate to a particular subject if you don't 
        know the name of the program you are looking for.</para>
 
       <para>In both of these cases, the search string is case-insensitive.
        Searching for <quote>LSOF</quote> will yield the same results as 
        searching for <quote>lsof</quote>.</para>
 
       <note>
         <para>You must be logged in as <username>root</username> to install
           ports.</para>
       </note>
 
       <para>Now that you have found a port you would like to install,
         you are ready to do the actual installation.  The port
         includes instructions on how to build source code, but not the
         actual source code.  You can get the source code from a CD-ROM
         or from the Internet.  Source code is distributed in whatever
         manner the software author desires.  Frequently this is a
         tarred and gzipped file, but it might be compressed with some
         other tool or even uncompressed.  The program source code,
         whatever form it comes in, is called a
         <quote>distfile</quote>.  You can get the distfile from a
         CD-ROM or from the Internet.</para>
 
       <sect3 id="ports-cd">
         <title>Installing Ports from a CD-ROM</title>
 
         <indexterm>
           <primary>ports</primary>
           <secondary>installing from CD-ROM</secondary>
         </indexterm>
         <para>The FreeBSD Project's official CD-ROM images no longer
 	  include distfiles.  They take up a lot of room that is
 	  better used for precompiled packages.  CD-ROM products such as
 	  the FreeBSD PowerPak do include distfiles, and you can
 	  order these sets from a vendor such as the <ulink
 	  url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>.
 	  This section assumes you have such a FreeBSD CD-ROM
 	  set.</para>
 
         <para>Place your FreeBSD CD-ROM in the drive.  Mount it on
 	  <filename>/cdrom</filename>.  (If you use a different mount
 	  point, the install will not work.)  To begin, change to the
 	  directory for the port you want to install:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen>
 
         <para>Once inside the <filename>lsof</filename> directory,
 	  you will see the port
 	  skeleton.  The next step is to compile, or <quote>build</quote>, the
 	  port.  This is done by simply typing <command>make</command> at
 	  the prompt.  Once you have done so, you should see something
 	  like this:</para>
 
         <screen>&prompt.root; <userinput>make</userinput>
 &gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
 &gt;&gt; Attempting to fetch from file:/cdrom/ports/distfiles/.
 ===&gt;  Extracting for lsof-4.57
 ...
 [extraction output snipped]
 ...
 &gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
 ===&gt;  Patching for lsof-4.57
 ===&gt;  Applying FreeBSD patches for lsof-4.57
 ===&gt;  Configuring for lsof-4.57
 ...
 [configure output snipped]
 ...
 ===&gt;  Building for lsof-4.57
 ...
 [compilation output snipped]
 ...
 &prompt.root;</screen>
 
         <para>Notice that once the compile is complete you are
 	  returned to your prompt.  The next step is to install the
 	  port.  In order to install it, you simply need to tack one word
 	  onto the <command>make</command> command, and that word is
 	  <command>install</command>:</para>
 
         <screen>&prompt.root; <userinput>make install</userinput>
 ===&gt;  Installing for lsof-4.57
 ...
 [installation output snipped]
 ...
 ===&gt;   Generating temporary packing list
 ===&gt;   Compressing manual pages for lsof-4.57
 ===&gt;   Registering installation for lsof-4.57
 ===&gt;  SECURITY NOTE: 
       This port has installed the following binaries which execute with
       increased privileges.
 &prompt.root;</screen>
 
         <para>Once you are returned to your prompt, you should be able to
           run the application you just installed.  Since 
 	  <command>lsof</command> is a
 	  program that runs with increased privileges, a security
 	  warning is shown.  During the building and installation of
 	  ports, you should take heed of any other warnings that
 	  may appear.</para>
 
         <note>
           <para>You can save an extra step by just running <command>make
             install</command> instead of <command>make</command> and
 	    <command>make install</command> as two separate steps.</para>
 	</note>
 
 	<note>
 	  <para>Some shells keep a cache of the commands that are available in
 	    the directories listed in the <envar>PATH</envar> environment
 	    variable, to speed up lookup operations for the executable file of
 	    these commands.  If you are using one of these shells, you might
 	    have to use the <command>rehash</command> command after installing
 	    a port, before the newly installed commands can be used.  This is
 	    true for both shells that are part of the base-system (such as
 	    <command>tcsh</command>) and shells that are available as ports
 	    (for instance,
 	    <filename role="package">shells/zsh</filename>).</para>
 	</note>
 
         <note>
           <para>Please be aware that the licenses of a few ports do not
             allow for inclusion on the CD-ROM.  This could be because a
             registration form needs
 	    to be filled out before downloading or redistribution is not
 	    allowed, or for another reason.  If you wish to install a port not
 	    included on the CD-ROM, you will need to be online in order to
 	    do so (see the <link linkend="ports-inet">next
 	    section</link>).</para>
 	</note>
       </sect3>
 
       <sect3 id="ports-inet">
       <title>Installing Ports from the Internet</title>
 
         <para>As with the last section, this section makes an assumption
           that you have a working Internet connection.  If you do not,
 	  you will need to perform the <link linkend="ports-cd">CD-ROM
 	  installation</link>, or put a copy of the distfile into <filename>/usr/ports/distfiles</filename> manually.</para>
 
         <para>Installing a port from the Internet is done exactly the same
 	  way as it would be if you were installing from a CD-ROM.  The
 	  only difference between the two is that the distfile
 	  is downloaded from the Internet instead of read from the
 	  CD-ROM.</para>
 
         <para>The steps involved are identical:</para>
 
         <screen>&prompt.root; <userinput>make install</userinput>
 &gt;&gt; lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
 &gt;&gt; Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.
 Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
 439860 bytes transferred in 18.0 seconds (23.90 kBps)
 ===&gt;  Extracting for lsof-4.57
 ...
 [extraction output snipped]
 ...
 &gt;&gt; Checksum OK for lsof_4.57D.freebsd.tar.gz.
 ===&gt;  Patching for lsof-4.57
 ===&gt;  Applying FreeBSD patches for lsof-4.57
 ===&gt;  Configuring for lsof-4.57
 ...
 [configure output snipped]
 ...
 ===&gt;  Building for lsof-4.57
 ...
 [compilation output snipped]
 ...
 ===&gt;  Installing for lsof-4.57
 ...
 [installation output snipped]
 ...
 ===&gt;   Generating temporary packing list
 ===&gt;   Compressing manual pages for lsof-4.57
 ===&gt;   Registering installation for lsof-4.57
 ===&gt;  SECURITY NOTE: 
       This port has installed the following binaries which execute with
       increased privileges.
 &prompt.root;</screen>
 
         <para>As you can see, the only difference is the line that tells
 	  you where the system is fetching the port distfile from.</para>
 
 	<para>The ports system uses &man.fetch.1; to download the files, 
 	  which honours various environment variables, including 
 	  <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, 
 	  and <envar>FTP_PASSWORD</envar>.  You may need to set one or more 
 	  of these if you are behind a firewall, or need to use an FTP/HTTP
 	  proxy.  See &man.fetch.3; for the complete list.</para>
       </sect3>
     </sect2>
 
     <sect2 id="ports-removing">
       <title>Removing Installed Ports</title>
 
       <indexterm>
         <primary>ports</primary>
         <secondary>removing</secondary>
       </indexterm>
       <para>Now that you know how to install ports, you are probably
         wondering how to remove them, just in case you install one and
 	later on decide that you installed the wrong port.  
         We will remove our previous example (which was 
 	<command>lsof</command> for
         those of you not paying attention).  As with installing ports,
 	the first thing you must do is change to the port directory,
 	<filename>/usr/ports/sysutils/lsof</filename>.  After you change
 	directories, you are ready to uninstall <command>lsof</command>.
 	This is done with
 	the <command>make deinstall</command> command:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
 &prompt.root; <userinput>make deinstall</userinput>
 ===&gt;  Deinstalling for lsof-4.57</screen>
 
       <para>That was easy enough.  You have removed
 	<command>lsof</command>
         from your system.  If you would like to reinstall it, you can do
 	so by running <command>make reinstall</command> from the
         <filename>/usr/ports/sysutils/lsof</filename> directory.</para>
 
       <para>The <command>make deinstall</command> and <command>make
         reinstall</command> sequence does not work once you have run
         <command>make clean</command>.  If you want to deinstall a
         port after cleaning, use &man.pkg.delete.1; as
         discussed in the <link linkend="packages-using">Packages
         section of the Handbook</link>.</para>
     </sect2>
   </sect1>
 
   <sect1 id="ports-nextsteps">
     <title>Post-installation activities</title>
 
     <para>After installing a new application you will normally want to read
       any documentation it may have included, edit any configuration files
       that are required, ensure that the application starts at boot time (if
       it is a daemon), and so on.</para>
 
     <para>The exact steps you need to take to configure each application will
       obviously be different.  However, if you have just installed a new
       application and are wondering <quote>What now?</quote> these tips might
       help:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Use &man.pkg.info.1; to find out which files were installed,
 	  and where.  For example, if you have just
 	  installed FooPackage version 1.0.0, then this command</para>
 
 	<screen>&prompt.root; <userinput>pkg_info -L foopackage-1.0.0 | less</userinput></screen>
 
 	<para>will show all the files installed by the package.  Pay special
 	  attention to files in <filename>man/</filename> directories, which
 	  will be manual pages, <filename>etc/</filename> directories, which
 	  will be configuration files, and <filename>doc/</filename>, which will be
 	  more comprehensive documentation.</para>
 
 	<para>If you are not sure which version of the application was just
 	  installed, a command like this</para>
 
 	<screen>&prompt.root; <userinput>pkg_info | grep <replaceable>foopackage</replaceable></userinput></screen>
 
 	<para>will find all the installed packages that have
 	  <replaceable>foopackage</replaceable> in the package name.  Replace
 	  <replaceable>foopackage</replaceable> in your command line as
 	  necessary.</para>
       </listitem>
 
       <listitem>
 	<para>Once you have identified where the application's manual pages
 	  have been installed, review them using &man.man.1;.  Similarly, 
 	  look over the sample configuration files, and any additional 
 	  documentation that may have been provided.</para>
       </listitem>
 
       <listitem>
 	<para>If the application has a web site, check it for additional
 	  documentation, frequently asked questions, and so forth.  If
 	  you are not sure of the web site address it may be listed in the
 	  output from</para>
 
 	<screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>
 	
 	<para>A <literal>WWW:</literal> line, if present, should provide a URL
 	  for the application's web site.</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="ports-trouble">
     <title>Troubleshooting</title>
 
     <para>The following sections cover some of the more frequently asked
       questions about the ports collection and some basic troubleshooting
       techniques, and what do to if a <link
       linkend="ports-broken">port is broken</link>.</para>
 
     <sect2 id="ports-questions">
       <title>Some Questions and Answers</title>
 
       <qandaset>
         <qandaentry>
 	  <question>
 	  <para>I thought this was going to be a discussion about
 	    modems??!</para>
 	  </question>
 
 	  <answer>
 	  <para>Ah, you must be thinking of the serial ports on the back
 	    of your computer.  We are using <quote>port</quote> here to
 	    mean the result of <quote>porting</quote> a program from one
 	    operating system to another.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para id="ports-patch">What is a patch?</para>
 	  </question>
 
 	  <answer>
 	  <para>A patch is a small file that specifies how to go from
 	    one version of a file to another.  It contains plain text,
 	    and basically says things like <quote>delete line 23</quote>,
 	    <quote>add these two lines after line 468</quote>, and
 	    <quote>change line 197 to this</quote>.  They are also known
 	    as diffs because they are generated by the
 	    &man.diff.1; program.</para>
 	  </answer>
 	</qandaentry>
 
   <indexterm><primary>tarball</primary></indexterm>
 	<qandaentry>
 	  <question>
 	  <para id="ports-tarball">What is all this about
 	    tarballs?</para>
 	  </question>
 
 	  <answer>
 	  <para>It is a file ending in <filename>.tar</filename>, or
 	    with variations such as <filename>.tar.gz</filename>,
 	    <filename>.tar.Z</filename>, <filename>.tar.bz2</filename>,
 	    and even <filename>.tgz</filename>.</para>
 
 	  <para>Basically, it is a directory tree that has been archived
 	    into a single file (<filename>.tar</filename>) and
 	    optionally compressed (<filename>.gz</filename>).  This
 	    technique was originally used for <emphasis>T</emphasis>ape
 	    <emphasis>AR</emphasis>chives (hence the name
 	    <command>tar</command>), but it is a widely used way of
 	    distributing program source code around the Internet.</para>
 
 	  <para>You can see what files are in them, or even extract
             them yourself by using the standard Unix
 	    &man.tar.1; program, which comes with the base
 	    FreeBSD system, like this:</para>
 
 	  <screen>&prompt.user; <userinput>tar tvzf foobar.tar.gz</userinput>
 &prompt.user; <userinput>tar xzvf foobar.tar.gz</userinput>
 &prompt.user; <userinput>tar tvf foobar.tar</userinput>
 &prompt.user; <userinput>tar xvf foobar.tar</userinput></screen>
 	  </answer>
 	</qandaentry>
 
   <indexterm><primary>checksum</primary></indexterm>
 	<qandaentry>
 	  <question>
 	  <para id="ports-checksum">And checksums?</para>
 	  </question>
 
 	  <answer>
 	  <para>It is a number generated by adding up all the data in
 	    the file you want to check.  If any of the characters
 	    change, the checksum will no longer be equal to the total,
 	    so a simple comparison will allow you to spot the
 	    difference.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I did what you said for compiling ports from a CDROM and
 	    it worked great until I tried to install the <application>Kermit</application>
 	    port.</para>
 
 	  <screen>&prompt.root; <userinput>make install</userinput>
 &gt;&gt; cku190.tar.gz doesn't seem to exist on this system.
 &gt;&gt; Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.</screen>
 
 	  <para>Why can it not be found?  Have I got a dud CDROM?</para>
 	  </question>
 
 	  <answer>
 	  <para>As explained in the <link
 	    linkend="ports-cd">installing ports from CDROM</link>
 	    section, some ports cannot be put on the CDROM set
 	    due to licensing restrictions.  <application>Kermit</application> is an example of
 	    that.  The licensing terms for <application>Kermit</application> do not allow us to put
 	    the tarball for it on the CDROM, so you will have to fetch
 	    it by hand&mdash;sorry!</para>
 
 	  <para>The reason why you got all those error messages was
 	    because you were not connected to the Internet at the time.
 	    Once you have downloaded it from any of the <makevar>MASTER_SITES</makevar>
 	    (listed in the <filename>Makefile</filename>), you can restart the install
 	    process.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I did that, but when I tried to put it into
 	    <filename>/usr/ports/distfiles</filename> I got some error
 	    about not having permission.</para>
 	  </question>
 
 	  <answer>
 	  <para>The ports mechanism will download distribution
 	    tarballs into <filename>/usr/ports/distfiles</filename>,
 	    but many system administrators will symlink this directory
 	    to a remote file server or local read-only CD-ROM media.
 	    If this is the case, then you should specify a different
 	    directory to be used for storing distfiles with the
 	    following command:</para>
 
 	  <screen>&prompt.root; <userinput>make DISTDIR=<replaceable>/local/dir/with/write/permission</replaceable> install</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>Does the ports scheme only work if you have everything
 	    in <filename>/usr/ports</filename>?  My system administrator
 	    says I must put everything under
 	    <filename>/u/people/guests/wurzburger</filename>, but it
 	    does not seem to work.</para>
 	  </question>
 
 	  <answer>
 	  <para>You can use the <makevar>PORTSDIR</makevar> and
 	    <makevar>PREFIX</makevar> variables to tell the ports
 	    mechanism to use different directories.  For
 	    instance,</para>
 
 	  <screen>&prompt.root; <userinput>make PORTSDIR=/u/people/guests/wurzburger/ports install</userinput></screen>
 
 	  <para>will compile the port in
 	    <filename>/u/people/guests/wurzburger/ports</filename> and
 	    install everything under
 	    <filename>/usr/local</filename>.</para>
 
 	  <screen>&prompt.root; <userinput>make PREFIX=/u/people/guests/wurzburger/local install</userinput></screen>
 
 	  <para>will compile it in <filename>/usr/ports</filename> and
 	    install it in
 	    <filename>/u/people/guests/wurzburger/local</filename>.</para>
 
 	  <para>And of course,</para>
 
 	  <screen>&prompt.root; <userinput>make PORTSDIR=../ports PREFIX=../local install</userinput></screen>
 
 	  <para>will combine the two (it is too long to write fully on
 	    the page, but it should give you the general idea).</para>
 
 	  <indexterm><primary>imake</primary></indexterm>
 
 	  <para>Some ports that use &man.imake.1; (a part of the X Windows
 	  System) do not work well with <makevar>PREFIX</makevar>, and will insist on
 	  installing under <filename>/usr/X11R6</filename>.  Similarly, some Perl ports
 	  ignore <makevar>PREFIX</makevar> and install in the Perl tree.  Making these
 	  ports respect <makevar>PREFIX</makevar> is a difficult or impossible
 	  job.</para>
 
 	  <para>If you do not fancy typing all that in every time you
 	    install a port, you can put these variables
 	    into your environment.  Read the manual page for your shell for
 	    instructions on doing so.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I do not have a FreeBSD CD-ROM, but I would like to have
 	    all the tarballs handy on my system so I do not have to wait
 	    for a download every time I install a port.  Is there any
 	    way to get them all at once?</para>
 	  </question>
 
 	  <answer>
 	  <para>To get every single tarball for the ports collection,
 	    do:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make fetch</userinput></screen>
 
 	  <para>For all the tarballs for a single ports directory,
 	    do:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
 &prompt.root; <userinput>make fetch</userinput></screen>
 
 	  <para>and for just one port&mdash;well, you have probably
 	    guessed already.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I know it is probably faster to fetch the tarballs from
 	    one of the FreeBSD mirror sites close by.  Is there any way
 	    to tell the port to fetch them from servers other than the
 	    ones listed in the <makevar>MASTER_SITES</makevar>?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes.  If you know, for example, that <hostid
 	    role="fqdn">ftp.FreeBSD.org</hostid> is much closer to you
 	    than the sites listed in <makevar>MASTER_SITES</makevar>,
 	    do as follows:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
 &prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I want to know what files <command>make</command> is
 	    going to need before it tries to pull them down.</para>
 	  </question>
 
 	  <answer>
 	  <para><command>make fetch-list</command> will display a list
 	    of the files needed for a port.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>Is there any way to stop the port from compiling?  I
 	    want to do some hacking on the source before I install it,
 	    but it is a bit tiresome to watch it and hit
 	    <keycombo action="simul">
 	      <keycap>Ctrl</keycap>
 	      <keycap>C</keycap>
 	    </keycombo>
 	    every time.</para>
 	  </question>
 
 	  <answer>
             <para>Doing <command>make extract</command> will stop it
 	      after it has fetched and extracted the source code.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I am trying to make my own port and I want to be able
 	    to stop it compiling until I have had a chance to see if my
 	    patches worked properly.  Is there something like
 	    <command>make extract</command>, but for patches?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes, <command>make patch</command> is what you want.
 	    You will probably find the <makevar>PATCH_DEBUG</makevar>
 	    option useful as well.  And by the way, thank you for your
 	    efforts!</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I have heard that some compiler options can cause bugs.
 	    Is this true?  How can I make sure that I compile ports
 	    with the right settings?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes, with version 2.6.3 of <command>gcc</command> (the
 	    version shipped with FreeBSD&nbsp;2.1.0 and 2.1.5), the
 	    <option>-O2</option> option could result in buggy code
 	    unless you used the <option>-fno-strength-reduce</option>
 	    option as well.  (Most of the ports do not use
 	    <option>-O2</option>).  You <emphasis>should</emphasis> be
 	    able to specify compiler options with something
 	    like:</para>
 
 	  <screen>&prompt.root; <userinput>make CFLAGS='-O2 -fno-strength-reduce' install</userinput></screen>
 
 	  <para>or by editing <filename>/etc/make.conf</filename>, but
 	    unfortunately not all ports respect this.  The surest way
 	    is to do <command>make configure</command>, then go into
 	    the source directory and inspect the <filename>Makefile</filename>s by hand, but
 	    this can get tedious if the source has lots of
 	    sub-directories, each with their own <filename>Makefile</filename>s.</para>
 
 	    <para>The default FreeBSD compiler options are quite conservative, 
 	      so if you have not changed them you should not have any
 	      problems.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>There are so many ports it is hard to find the one I
 	    want.  Is there a list anywhere of what ports are
 	    available?</para>
 	  </question>
 
 	  <answer>
 	  <para>Look in the <filename>INDEX</filename> file in
 	    <filename>/usr/ports</filename>.  If you would like to
 	    search the ports collection for a keyword, you can do that
 	    too.  For example, you can find ports relevant to the LISP
 	    programming language using:</para>
 
 	  <screen>&prompt.user; <userinput>cd /usr/ports</userinput>
 &prompt.user; <userinput>make search key=lisp</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I tried to install the <literal>foo</literal> port but
 	    the system suddenly stopped compiling it and starting
 	    compiling the <literal>bar</literal> port.  What is going
 	    on?</para>
 	  </question>
 
 	  <answer>
 	  <para>The <literal>foo</literal> port needs something that is
 	    supplied with <literal>bar</literal> &mdash; for instance,
 	    if <literal>foo</literal> uses graphics,
 	    <literal>bar</literal> might have a library with useful
 	    graphics processing routines.  Or <literal>bar</literal>
 	    might be a tool that is needed to compile the
 	    <literal>foo</literal> port. Once <literal>bar</literal> is finished, your system should automatically resume building <literal>foo</literal>.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para id="ports-remove">  I installed the
 	    <literal>grizzle</literal> program from the ports and
 	    frankly it is a complete waste of disk space.  I want to
 	    delete it but I do not know where it put all the files.
 	    Any clues?</para>
 	  </question>
 
 	  <answer>
 	  <para>No problem, just type:</para>
 
 	  <screen>&prompt.root; <userinput>pkg_delete grizzle-6.5</userinput></screen>
 
 	  <para>Alternatively, you can type:</para>
 
 	  <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/grizzle</replaceable></userinput>
 &prompt.root; <userinput>make deinstall</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>Hang on a minute, you have to know the version number
 	    to use that command.  You do not seriously expect me to
 	    remember that, do you?</para>
 	  </question>
 
 	  <answer>
 	  <para>Not at all, you can find it out by doing:</para>
 
 	  <screen>&prompt.root; <userinput>pkg_info -I 'grizzle*'</userinput>
 Information for grizzle-6.5:
 grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
 arcade game.</screen>
 
 	  <para>The version number can be found either by using the 
 	    <command>pkg_info</command> or by typing:
 	    <command>ls /var/db/pkg</command></para>
 
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>Speaking of disk space, the ports directory seems to be
 	    taking up an awful lot of room.  Is it safe to go in there
 	    and delete things?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes, if you have installed a program and are fairly
 	    certain you will not need the source again, there is no
 	    point in keeping it hanging around.  The surest way to do
 	    this is:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make clean</userinput></screen>
 
 	  <para>which will go through all the ports subdirectories and
 	    delete everything except the skeletons for each
 	    port.</para>
 
 	  <tip><para>It is possible to achieve the same effect without
 		recursively calling each <filename>Makefile</filename>.  For example, you
 		can delete all of the <filename>work/</filename> subdirectories directly
 		with the following command:
 	    <screen>&prompt.root; <userinput>find /usr/ports -depth -name work -exec rm -rf {} \;</userinput></screen></para>
 	    </tip>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I tried that and it still left all those tarballs or
 	    whatever you called them in the
 	    <filename>distfiles</filename> directory.  Can I delete
 	    those as well?</para>
 	  </question>
 
 	  <answer>
 	  <para>Yes, if you are sure you have finished with them,
 	     those can go as well.  They can be removed manually, or by
 	     using <command>make distclean</command>.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I like having lots and lots of programs to play with.
 	    Is there any way of installing all the ports in one
 	    go?</para>
 	  </question>
 
 	  <answer>
 	  <para>Just do:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make install</userinput></screen>
 
 	    <para>Be careful, as some ports may install files with the same
 	      name.  If you install two graphics ports and they both install
 	      <filename>/usr/local/bin/plot</filename> then you will obviously 
 	      have problems.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>OK, I tried that, but I thought it would take a very
 	    long time so I went to bed and left it to get on with it.
 	    When I looked at the computer this morning, it had only
 	    done three and a half ports.  Did something go
 	    wrong?</para>
 	  </question>
 
 	  <answer>
 	  <para>No, the problem is that some of the ports need to ask
 	    you questions that we cannot answer for you (e.g., <quote>Do
 	    you want to print on A4 or US letter sized paper?</quote>)
 	    and they need to have someone on hand to answer
 	    them.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>I really do not want to spend all day staring at the
 	    monitor.  Any better ideas?</para>
 	  </question>
 
 	  <answer>
 	  <para>OK, do this before you go to bed/work/the local
 	    park:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make -DBATCH install</userinput></screen>
 
 	  <para>This will install every port that does
 	    <emphasis>not</emphasis> require user input.  Then, when
 	    you come back, do:</para>
 
 	  <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 &prompt.root; <userinput>make -DINTERACTIVE install</userinput></screen>
 
 	  <para>to finish the job.</para>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>At work, we are using <literal>frobble</literal>, which
 	    is in your ports collection, but we have altered it quite a
 	    bit to get it to do what we need.  Is there any way of making
 	    our own package, so we can distribute it more easily around
 	    our sites?</para>
 	  </question>
 
 	  <answer>
 	  <para>No problem, assuming you know how to make patches for
 	    your changes:</para>
 
 	  <screen>&prompt.root; <userinput>cd <replaceable>/usr/ports/somewhere/frobble</replaceable></userinput>
 &prompt.root; <userinput>make extract</userinput>
 &prompt.root; <userinput>cd work/frobble-2.8</userinput>
 [Apply your patches]
 &prompt.root; <userinput>cd ../..</userinput>
 &prompt.root; <userinput>make package</userinput></screen>
 	  </answer>
 	</qandaentry>
 
 	<qandaentry>
 	  <question>
 	  <para>This ports stuff is really clever.  I am desperate to
 	    find out how you did it.  What is the secret?</para>
 	  </question>
 
 	  <answer>
 	  <para>Nothing secret about it at all, just look at the
 	    <filename>bsd.port.mk</filename> and
 	    <filename>bsd.port.subdir.mk</filename> files in
 	    <filename>/usr/ports/Mk/</filename>.</para>
 
 	  <para>(Readers with an aversion to intricate shell-scripts are
 	    advised not to look at the files in this directory.)</para>
 	  </answer>
 	</qandaentry>
       </qandaset>
     </sect2>
 
     <sect2 id="ports-broken">
       <title>Help!  This Port Is Broken!</title>
 
       <para>If you come across a port that does not work for you, there are
         a few things you can do, including:</para>
 
       <orderedlist>
         <listitem>
 	  <para>Fix it!  The <ulink
 	    url="../porters-handbook/index.html">Porter's
 	    Handbook</ulink> includes detailed information on the
 	    "Ports" infrastructure so that you can fix the occasional
 	    broken port or even submit your own!</para>
 	</listitem>
 
 	<listitem>
 	  <para>Gripe&mdash;<emphasis>by email only</emphasis>!  Send
 	    email to the maintainer of the port first.  Type <command>make
 	    maintainer</command> or read the <filename>Makefile</filename>
 	    to find the maintainer's email address.  Remember to include
 	    the name and version of the port (send the
 	    <literal>&dollar;FreeBSD:</literal> line from the
 	    <filename>Makefile</filename>) and the output leading up to the
 	    error when you email the maintainer.  If you do not get a
 	    response from the maintainer, you can use
 	    &man.send-pr.1; to submit a bug report.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Grab the package from an FTP site near you.  The
 	    <quote>master</quote> package collection is on <hostid
 	    role="fqdn">ftp.FreeBSD.org</hostid> in the <ulink
 	    URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages
 	    directory</ulink>, but be sure to check your local mirror
 	    <emphasis>first</emphasis>!  These are more likely to work
 	    than trying to compile from source and are a lot faster as
 	    well.  Use the &man.pkg.add.1; program to install the package
 	    on your system.</para>
 	</listitem>
       </orderedlist>
     </sect2>
   </sect1>
 
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
index a814298370..533a1d5f07 100644
--- a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
@@ -1,3161 +1,3161 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="ppp-and-slip">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured, reorganized, and updated by </contrib>
 	<!-- 1 Mar 2000 -->
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>PPP and SLIP</title>
 
-  <sect1>
+  <sect1 id="ppp-and-slip-synopsis">
     <title>Synopsis</title>
     <indexterm id="ppp-ppp">
       <primary>PPP</primary>
     </indexterm>
     <indexterm id="ppp-slip">
       <primary>SLIP</primary>
     </indexterm>
 
     <para>FreeBSD has a number of ways to link one computer to
       another.  To establish a network or Internet connection through a
       dial-up modem, or to allow others to do so through you, requires
       the use of PPP or SLIP.  This chapter describes setting up
       these modem-based communication services in detail.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How to setup User PPP.</para>
       </listitem>
       <listitem>
 	<para>How to setup Kernel PPP.</para>
       </listitem>
       <listitem>
 	<para>How to setup <acronym>PPPoE</acronym> (PPP over
 	  Ethernet).</para>
       </listitem>
       <listitem>
 	<para>How to setup <acronym>PPPoA</acronym> (PPP over
 	  ATM).</para>
 	</listitem>
       <listitem>
 	<para>How to configure and setup a SLIP client and
 	  server.</para>
       </listitem>
     </itemizedlist>
 
     <indexterm id="ppp-ppp-user">
       <primary>PPP</primary>
       <secondary>user PPP</secondary>
     </indexterm>      
     <indexterm id="ppp-ppp-kernel">
       <primary>PPP</primary>
       <secondary>kernel PPP</secondary>
     </indexterm>      
     <indexterm id="ppp-ppp-ethernet">
       <primary>PPP</primary>
       <secondary>over Ethernet</secondary>
     </indexterm>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Be familiar with basic network terminology.</para>
       </listitem>
       <listitem>
 	<para>Understand the basics and purpose of a dialup connection
 	  and PPP and/or SLIP.</para>
       </listitem>
     </itemizedlist>
 
     <para>You may be wondering what the main difference is between User
       PPP and kernel PPP.  The answer is simple; user PPP processes the
       inbound and outbound data in userland rather than in the kernel.
       This is expensive in terms of copying the data between the kernel
       and userland, but allows a far more feature-rich ppp implementation.
       User PPP uses the <devicename>tun</devicename> device to communicate
       with the outside world whereas kernel-ppp uses the
       <devicename>ppp</devicename> device.</para>
 
     <note>
       <para>Throughout in this chapter, user ppp will simply be
 	referred to as ppp unless a distinction needs to be made between it
 	and any other PPP software such as <command>pppd</command>.
 	Unless otherwise stated, all of the commands explained in this
 	section should be executed as <username>root</username>.</para>
     </note>
   </sect1>
 
   <sect1 id="userppp">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Tom</firstname>
           <surname>Rhodes</surname>
           <contrib>Updated and enhanced by </contrib>
         </author>
       </authorgroup>
       <authorgroup>
         <author>
           <firstname>Brian</firstname>
           <surname>Somers</surname>
 	  <contrib>Originally contributed by </contrib>
         </author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Nik</firstname>
 	  <surname>Clayton</surname>
 	  <contrib>With input from </contrib>
         </author>
         <author>
 	  <firstname>Dirk</firstname>
           <surname>Fr&ouml;mberg</surname>
         </author>
         <author>
           <firstname>Peter</firstname>
           <surname>Childs</surname>
         </author>
       </authorgroup>
     </sect1info>
 
     <title>Using User PPP</title>
 
     <sect2>
       <title>User PPP</title>
 
       <sect3>
 	<title>Assumptions</title>
 
 	<para>This document assumes you have the following:</para>
 
 	<itemizedlist>
 	  <indexterm id="ppp-isp">
 	    <primary>ISP</primary>
 	  </indexterm>
 	  <indexterm id="ppp-ppp2">
 	    <primary>PPP</primary>
 	  </indexterm>
 	  <listitem>
 	    <para>An account with an Internet Service Provider (ISP) which
 	      you connect to using PPP.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>You have a modem or
 	      other device connected to your system and configured
 	      correctly which allows you to connect to your ISP.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The dial-up number(s) of your ISP.</para>
 	  </listitem>
 
 	  <indexterm id="ppp-pap">
 	    <primary>PAP</primary>
 	  </indexterm>
 	  <indexterm id="ppp-chap">
 	    <primary>CHAP</primary>
 	  </indexterm>
 	  <indexterm id="ppp-unix">
 	    <primary>Unix</primary>
 	  </indexterm>
 	  <indexterm id="ppp-login">
 	    <primary>login name</primary>
 	  </indexterm>
 	  <indexterm id="ppp-password">
 	    <primary>password</primary>
 	  </indexterm>
 	  <listitem>
 	    <para>Your login name and password. (Either a
 	      regular Unix-style login and password pair, or a PAP or CHAP
 	      login and password pair.)</para>
 	  </listitem>
 
 	  <indexterm id="ppp-nameserver">
 	    <primary>nameserver</primary>
 	  </indexterm>
 	  <listitem>
 	    <para>The IP address of one or more name servers.
 	      Normally, you will be given two IP addresses by your ISP to
 	      use for this.  If they have not given you at least one, then
 	      you can use the <command>enable dns</command> command in
 	      <filename>ppp.conf</filename> and
 	      <application>ppp</application> will set the name servers for
 	      you.  This feature depends on your ISPs PPP implementation
               supporting DNS negotiation.</para>
 	  </listitem>
 	</itemizedlist>
 
 	<para>The following information may be supplied by your ISP, but
 	  is not completely necessary:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>The IP address of your ISP's gateway.  The gateway is
 	      the machine to which you will connect and will be set up as
 	      your <emphasis>default route</emphasis>.  If you do not have
 	      this information, we can make one up and your ISP's PPP
 	      server will tell us the correct value when we connect.</para>
 
 	    <para>This IP number is referred to as
 	      <literal>HISADDR</literal> by
 	      <application>ppp</application>.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The netmask you should use.  If your ISP has not
 	      provided you with one, you can safely use <hostid
 	      role="netmask">255.255.255.255</hostid>.</para>
 	  </listitem>
 
 	  <indexterm id="ppp-static-ip">
 	    <primary>static IP address</primary>
 	  </indexterm>
 	  <listitem>
 	    <para>If your ISP provides you with a static IP address and
 	      hostname, you can enter it.  Otherwise, we simply let the
 	      peer assign whatever IP address it sees fit.</para>
 	  </listitem>
 	</itemizedlist>
  
 	<para>If you do not have any of the required information, contact
 	  your ISP.</para>
 
 	<note>
 	  <para>Throughout this section, many of the examples showing
 	    the contents of configuration files are numbered by line.
 	    These numbers serve to aid in the presentation and
 	    discussion only and are not meant to be placed in the actual
 	    file.  Proper indentation with tab and space characters is
 	    also important.</para>
 	</note>
 
       </sect3>
 
       <sect3>
 	<title>Manual <command>ppp</command> Initialization</title>
 
 	<para>Under normal circumstances, most users will only use one
 	  <devicename>tun</devicename> device
 	  (<devicename>/dev/tun0</devicename>).  References to
 	  <devicename>tun0</devicename> below may be changed to
 	  <devicename>tunN</devicename> where <literal>N</literal>
 	    is any unit number corresponding to your system.</para>
 
         <para>For FreeBSD installations that do not have &man.devfs.5; enabled (FreeBSD&nbsp;4.X and earlier),
           the existence of the <devicename>tun0</devicename> device should
           be verified (this is not necessary if &man.devfs.5; is enabled as device
           nodes will be created on demand).</para>
 
 	<para>The easiest way to make sure that the
 	  <devicename>tun0</devicename> device is configured correctly
 	  is to remake the device.  To remake the device, do the
           following:</para>
 
 	<screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV tun0</userinput></screen>
 
 	<para>If you need 16 tunnel devices in your kernel, you will need
 	  to create them.  This can be done by executing the following
 	  commands:</para>
 
 	<screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV tun15</userinput></screen>
 
         <sect4>
           <title>Check the Modem</title>
             <para>If you reconfigured your <filename>kernel</filename>
               then you recall the <devicename>sio</devicename>
               device.  If your modem acts like a standard serial port
               then you most likely only need to make the serial device.
               You can do this by changing your directory to
               <filename>/dev</filename> and running the <filename>MAKEDEV</filename>
               script like above.  Now make the serial devices with
 <screen>&prompt.root; <userinput>sh MAKEDEV cuaa0 cuaa1 cuaa2 cuaa3</userinput></screen>
               which will create the serial devices for your system.
               If your modem is on <devicename>sio1</devicename> or
               <acronym>COM2</acronym> if you are in DOS, then your
               modem device would be <devicename>/dev/cuaa1</devicename>.
             </para>
           </sect4>
         </sect3>
 
       <sect3>
         <title>Manual Connections</title>
           <para>Connecting to the internet by manually controlling
             <command>ppp</command> is quick, easy, and a great way
             to debug a connection or just get information on how your
             <acronym>ISP</acronym> handles connections.  Lets start
             <application>PPP</application> from the command line,
             note that, in all of our examples we will use <emphasis>localhost</emphasis>
             as the hostname of the machine running <application>PPP</application>.
             You start <command>ppp</command> by just typing <command>ppp</command>:
 
 <screen>&prompt.root; <userinput>ppp</userinput></screen>
 
         <para>We have now started <command>ppp</command>.</para>
 
 <screen>ppp ON example&gt; <userinput>set device <devicename>/dev/cuaa1</devicename></userinput></screen>
 
         <para>We set our modem device, in this case it is
           <devicename>cuaa1</devicename>.</para>
 
 <screen>ppp ON example&gt; <userinput>set speed 115200</userinput></screen>
 
         <para>Set the connection speed, in this case we
           are using 115,200 <acronym>kbps</acronym>.</para>
 
 <screen>ppp ON example&gt; <userinput>enable dns</userinput></screen>
 
         <para>Tell <command>ppp</command> to configure our
           resolver and add the nameserver lines to
           <filename>/etc/resolv.conf</filename>.  If <command>ppp</command>
           cannot determine our hostname, we can set one manually later.
         </para>
 
 <screen>ppp ON example&gt; <userinput>term</userinput></screen>
 
         <para>Switch to <quote>terminal</quote> mode so that we can manually
           control the modem.</para>
 
 <programlisting>
 deflink: Entering terminal mode on <devicename>/dev/cuaa1</devicename>
 type '~h' for help</programlisting>
 
 <screen><userinput>at</userinput>
 OK
 <userinput>atdt<replaceable>123456789</replaceable></userinput></screen>
 
         <para>Use <command>at</command> to initialize the modem,
           then use <command>atdt</command> and the number for your
           <acronym>ISP</acronym> to begin the dial in process.</para>
 
 <screen>CONNECT</screen>
 
         <para>Confirmation of the connection, if we are going to have
           any connection problems, unrelated to hardware, here is where
           we will attempt to resolve them.</para>
 
 <screen>ISP Login:<userinput>myusername</userinput></screen>
 
         <para>Here you are prompted for a username, return the
           prompt with the username that was provided by the
           <acronym>ISP</acronym>.</para>
 
 <screen>ISP Pass:<userinput>mypassword</userinput></screen>
 
         <para>This time we are prompted for a password, just
           reply with the password that was provided by the
           <acronym>ISP</acronym>.  Just like when logging into
           FreeBSD, the password will not echo.</para>
 
 <screen>Shell or PPP:<userinput>ppp</userinput></screen>
 
         <para>Depending on your <acronym>ISP</acronym> this prompt
           may never appear.  Here we are being asked if we wish to
           use a shell on the provider, or to start
           <command>ppp</command>.  In this example, we have chosen
           to use <command>ppp</command> as we want an internet
           connection.</para>
 
 <screen>Ppp ON example&gt;</screen>
 
         <para>Notice that in this example the first <option>p</option>
           has been capitalized.  This shows that we have successfully
           connected to the <acronym>ISP</acronym>.</para>
 
 <screen>PPp ON example&gt;</screen>
 
         <para>We have successfully authenticated with our
           <acronym>ISP</acronym> and are waiting for the
           assigned <acronym>IP</acronym> address.</para>
 
 <screen>PPP ON example&gt;</screen>
 
         <para>We have made an agreement on an <acronym>IP</acronym>
           address and successfully completed our connection.</para>
 
 <screen>PPP ON example&gt;<userinput>add default HISADDR</userinput></screen>
 
         <para>Here we add our default route, we need to do this
           before we can talk to the outside world as currently the
           only established connection is with the peer.  If this
           fails due to existing routes you can put a bang character
           <literal>!</literal> in front of the <option>add</option>.
           Alternatively, you can set this before making the actual connection
           and it will negotiate a new route accordingly.</para>
 
           <para>If everything went good we should now have an active
             connection to the internet, which could be thrown into
             the background using
             <keycombo action="simul"><keycap>CTRL</keycap> <keycap>z</keycap></keycombo>
             If you notice the <command>PPP</command> return to
             <command>ppp</command> then we have lost our connection.
             This is good to know because it shows our connection status.
             Capital P's show that we have a connection to the
             <acronym>ISP</acronym> and lowercase p's show that the
             connection has been lost for whatever reason.
             <command>ppp</command> only has these 2 states.
           </para>
 
           <sect4>
             <title>Troubleshooting Manual Connections</title>
               <para>Like everything else, once in awhile a problem or
                 may occur.  <application>PPP</application> is no
                 exemption to this theory.  If <command>ppp</command>
                 would happen to stop responding there are some things
                 we can try.</para>
 
               <para>If you have a direct line and cannot seem to make a
                 connection, then turn hardware flow <acronym>CTS/RTS</acronym>
                 to off with the <option>set ctsrts off</option>.  This is
                 mainly the case if you are connected to some
                 <application>PPP</application> capable terminal servers,
                 where <application>PPP</application> hangs when it tries
                 to write data to your communication link, so it
                 would be waiting for a <acronym>CTS</acronym>, or Clear
                 To Send signal which may never come.  If you use this
                 option however, you should also use the <option>set accmap</option>
                 option, which may be required to defeat hardware dependent on
                 passing certain characters from end to end, most of the time
                 XON/XOFF.  See the &man.ppp.8; manual page for more information
                 on this option, and how it is used.</para>
 
               <para>If you have an older modem, you may need to use the
                 <option>set parity even</option>.  Parity is set at none
                 be default, but is used for error checking (with a large
                 increase in traffic) on older modems and some
                 <acronym>ISP</acronym>s.  You may need this option for
                 the Compuserve ISP.</para>
 
               <para><application>PPP</application> may not return to the
                 command mode, which is usually a negotiation error where
                 the <acronym>ISP</acronym> is waiting for your side to start
                 negotiating.  At this point, using the <command>~p</command>
                 command will force ppp to start sending the configuration
                 information.</para>
 
               <para>If you never obtain a login prompt, then most likely you
                 need to use <acronym>PAP</acronym> or <acronym>CHAP</acronym>
                 authentication instead of the Unix-style in the example above.  To
                 use <acronym>PAP</acronym> or <acronym>CHAP</acronym> just add the
                 following options to <application>PPP</application> before going
                 into terminal mode:</para>
 
 <screen>ppp ON localhost&gt; <userinput>set authname <replaceable>myusername</replaceable></userinput></screen>
 
         <para>Where <replaceable>myusername</replaceable> should be replaced with
           the username that was assigned by the <acronym>ISP</acronym>.</para>
 
 <screen>ppp ON localhost&gt; <userinput>set authkey <replaceable>mypassword</replaceable></userinput></screen>
 
         <para>Where <replaceable>mypassword</replaceable> should be replaced with
           the password that was assigned by the <acronym>ISP</acronym>.</para>
 
         <para>If you connect fine, but cannot seem to find any domain name, try to
           use &man.ping.8; with an <acronym>IP</acronym> address and see if you
           can get any return information.  If you experience 100 percent (100%)
           packet loss, then its most likely that you were not assigned a default
           route.  Double check that the option <option>add default HISADDR</option>
           was set during the connection.  If you can connect to a remote
           <acronym>IP</acronym> address then it is possible that a resolver address
           has not been added to the <filename>/etc/resolv.conf</filename>.  This
           file should look like:</para>
 
 	  <programlisting>domain <replaceable>example.com</replaceable>
 nameserver <replaceable>x.x.x.x</replaceable>
 nameserver <replaceable>y.y.y.y</replaceable></programlisting>
 
         <para>Where <replaceable>x.x.x.x</replaceable> and
           <replaceable>y.y.y.y</replaceable> should be replaced with the
           <acronym>IP</acronym> address of your <acronym>ISP</acronym>'s DNS servers.
           This information may or may not have been provided when you signed up, but
           a quick call to your <acronym>ISP</acronym> should remedy that.</para>
 
               <para>You could also have &man.syslog.3; provide a logging function
                 for your <application>PPP</application> connection.  Just add:</para>
 
         <programlisting>
         !ppp
         *.*     /var/log/ppp.log</programlisting>
 
               <para>to <filename>/etc/syslog.conf</filename>.  In most cases, this
                 functionality already exists.</para>
 
         </sect4>
       </sect3>
 
       <sect3>
         <title>Automatic <application>PPP</application> Configuration</title>
 
 	<indexterm><primary>PPP</primary><secondary>configuration</secondary></indexterm>
 	<para>Both <command>ppp</command> and <command>pppd</command>
 	  (the kernel level implementation of PPP) use the configuration
 	  files located in the <filename>/etc/ppp</filename> directory.
           Examples for user ppp can be found in
           <filename>/usr/share/examples/ppp/</filename>.</para>
 
 	<para>Configuring <command>ppp</command> requires that you edit a
 	  number of files, depending on your requirements.  What you put
 	  in them depends to some extent on whether your ISP allocates IP
 	  addresses statically (i.e., you get given one IP address, and
 	  always use that one) or dynamically (i.e., your IP address
 	  changes each time you connect to your ISP).</para>
 
 	<sect4 id="userppp-staticIP">
 	  <title>PPP and Static IP Addresses</title>
 
 	  <indexterm><primary>PPP</primary><secondary>with static IP addresses</secondary></indexterm>
 	  <para>You will need to edit the
 	    <filename>/etc/ppp/ppp.conf</filename> configuration file.  It
             should look similar to the example below.</para>
 
 	  <note>
 	    <para>Lines that end in a <literal>:</literal> start in
 	      the first column (beginning of the line)&mdash; all other
 	      lines should be indented as shown using spaces or
 	      tabs.  Most of the information you need to provide here
               was shown to us by doing the manual dial above.</para>
 	  </note>
 
 	  <programlisting>1     default:
 2       set log Phase Chat LCP IPCP CCP tun command
 3       ident user-ppp VERSION (built COMPILATIONDATE)
 4       set device /dev/cuaa0
 5       set speed 115200
 6       set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
 7                 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT"
 8       set timeout 180
 9       enable dns
 10
 11    provider:
 12      set phone "(123) 456 7890"
 13      set authname foo
 14      set authkey bar
 15      set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp"
 16      set timeout 300
 17      set ifaddr <replaceable>x.x.x.x</replaceable> <replaceable>y.y.y.y</replaceable> 255.255.255.255 0.0.0.0
 18      add default HISADDR</programlisting>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term>Line 1:</term>
 
 	      <listitem>
 		<para>Identifies the default entry.  Commands in this
 		  entry are executed automatically when ppp is run.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 2:</term>
 
 	      <listitem>
 		<para>Enables logging parameters.  When the configuration
 		  is working satisfactorily, this line should be reduced
                   to saying
 
 	          <programlisting>set log phase tun</programlisting>
 
                   in order to avoid excessive log file sizes.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 3:</term>
 
 	      <listitem>
 		<para>Tells PPP how to identify itself to the peer.
                   PPP identifies itself to the peer if it has any trouble
                   negotiating and setting up the link, providing information
                   that the peers administrator may find useful when
                   investigating such problems.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 4:</term>
 
 	      <listitem>
 		<para>Identifies the device to which the modem is
 		  connected.  <devicename>COM1</devicename> is
 		  <devicename>/dev/cuaa0</devicename> and
 		  <devicename>COM2</devicename> is
 		  <devicename>/dev/cuaa1</devicename>.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 5:</term>
 
 	      <listitem>
 		<para>Sets the speed you want to connect at.  If 115200
 		  does not work (it should with any reasonably new modem),
 		  try 38400 instead.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 6 & 7:</term>
 
 	      <indexterm><primary>PPP</primary><secondary>user PPP</secondary></indexterm>
 	      <listitem>
 		<para>The dial string.  User PPP uses an expect-send
 		  syntax similar to the &man.chat.8; program.  Refer to
 		  the manual page for information on the features of this
 		  language.</para>
 
 		<para>Note that this command continues onto the next line
                    for readability.  Any command in
                    <filename>ppp.conf</filename> may do this if the last
                    character on the line is a ``\'' character.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 8:</term>
 
 	      <listitem>
 		<para>Sets the idle timeout for the link.  180 seconds
 		  is the default, so this line is purely cosmetic.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 9:</term>
 
 	      <listitem>
 		<para>Tells PPP to ask the peer to confirm the local
 		  resolver settings.  If you run a local name server, this
                   line should be commented out or removed.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 10:</term>
 
 	      <listitem>
 		<para>A blank line for readability.  Blank lines are ignored
 		by PPP.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 11:</term>
 
 	      <listitem>
 		<para>Identifies an entry for a provider called
 		  <quote>provider</quote>.  This could be changed
                     to the name of your <acronym>ISP</acronym> so
                     that later you can use the <option>load ISP</option>
                     to start the connection.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 12:</term>
 
 	      <listitem>
 		<para>Sets the phone number for this provider.  Multiple
 		  phone numbers may be specified using the colon
 		  (<literal>:</literal>) or pipe character
 		  (<literal>|</literal>)as a separator.  The difference
 		  between the two separators is described in &man.ppp.8;.
 		  To summarize, if you want to rotate through the numbers,
 		  use a colon.  If you want to always attempt to dial the
 		  first number first and only use the other numbers if the
 		  first number fails, use the pipe character.  Always
 		  quote the entire set of phone numbers as shown.</para>
 	    
 	      <para>You must enclose the phone number in quotation marks
 		(<literal>"</literal>) if there is any intention on using
 		spaces in the phone number.  This can cause a simple, yet
 		subtle error.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 13 & 14:</term>
 
 	      <listitem>
 		<para>Identifies the user name and password.  When connecting
                   using a Unix-style login prompt, these values are referred
                   to by the <command>set login</command> command using the \U
                   and \P variables.  When connecting using PAP or CHAP, these
                   values are used at authentication time.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 15:</term>
 
 	      <listitem>
 		<indexterm><primary>PAP</primary></indexterm>
 		<indexterm><primary>CHAP</primary></indexterm>
 		<para>If you are using PAP or CHAP, there will be no login
 		  at this point, and this line should be commented out or
 		  removed.  See <link linkend="userppp-PAPnCHAP">PAP and CHAP
 		  authentication</link> for further details.</para>
 
                 <para>The login string is of the same chat-like syntax as
 		  the dial string.  In this example, the string works for
 		  a service whose login session looks like this:</para>
 
 		<screen>J. Random Provider
 login: <replaceable>foo</replaceable>
 password: <replaceable>bar</replaceable>
 protocol: ppp</screen>
 
 		<para>You will need to alter this script to suit your own
 		  needs.  When you write this script for the first time,
 		  you should ensure that you have enabled <quote>chat</quote>
                   logging so you can determine if the conversation is going
                   as expected.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 16:</term>
 
 	      <indexterm><primary>timeout</primary></indexterm>
 	      <listitem>
 		<para>Sets the default idle timeout (in seconds) for the
 		  connection.  Here, the connection will be closed
 		  automatically after 300 seconds of inactivity.  If you
 		  never want to timeout, set this value to zero or use
                   the <option>-ddial</option> command line switch.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 17:</term>
 	      <indexterm><primary>ISP</primary></indexterm>
 	      <listitem>
 		<para>Sets the interface addresses.  The string
 		  <replaceable>x.x.x.x</replaceable> should be replaced by
 		  the IP address that your provider has allocated to you.
 		  The string <replaceable>y.y.y.y</replaceable> should be
 		  replaced by the IP address that your ISP indicated for
 		  their gateway (the machine to which you connect).  If
 		  your ISP has not given you a gateway address, use <hostid
 		  role="netmask">10.0.0.2/0</hostid>.  If you need to use
 		  a <quote>guessed</quote> address, make sure that you
 		  create an entry in
 		  <filename>/etc/ppp/ppp.linkup</filename> as per the
 		  instructions for <link linkend="userppp-dynamicIP">PPP
 		  and Dynamic IP addresses</link>.  If this line is
 		  omitted, <command>ppp</command> cannot run in
 		  <option>-auto</option> mode.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 18:</term>
 
 	      <listitem>
 		<para>Adds a default route to your ISP's gateway.  The
 		  special word <literal>HISADDR</literal> is replaced with
 		  the gateway address specified on line 9.  It is
 		  important that this line appears after line 9,
 		  otherwise <literal>HISADDR</literal> will not yet be
 		  initialized.</para>
 
 		<para>If you do not wish to run ppp in <option>-auto</option>,
 		  this line should be moved to the
                   <filename>ppp.linkup</filename> file.</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
 
 	  <para>It is not necessary to add an entry to
 	    <filename>ppp.linkup</filename> when you have a static IP
 	    address and are running ppp in <option>-auto</option> mode as your
             routing table entries are already correct before you connect.
             You may however wish to create an entry to invoke programs after
             connection.  This is explained later with the sendmail
             example.</para>
 
 	  <para>Example configuration files can be found in the
 	    <filename>/usr/share/examples/ppp/</filename> directory.</para>
 	</sect4>
 
 	<sect4 id="userppp-dynamicIP">
 	  <title>PPP and Dynamic IP Addresses</title>
 	  <indexterm><primary>PPP</primary><secondary>with dynamic IP addresses</secondary></indexterm>
 	  <indexterm><primary>IPCP</primary></indexterm>
 	  <para>If your service provider does not assign static IP
 	    addresses, <command>ppp</command> can be configured to
 	    negotiate the local and remote addresses.  This is done by
 	    <quote>guessing</quote> an IP address and allowing
 	    <command>ppp</command> to set it up correctly using the IP
 	    Configuration Protocol (IPCP) after connecting.  The
 	    <filename>ppp.conf</filename> configuration is the same as
 	    <link linkend="userppp-staticIP">PPP and Static IP
 	    Addresses</link>, with the following change:</para>
 
 	  <programlisting>17      set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255</programlisting>
 
 	  <para>Again, do not include the line number, it is just for
 	    reference.  Indentation of at least one space is
 	    required.</para>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term>Line 17:</term>
 
 	      <listitem>
 		<para>The number after the <literal>/</literal> character
 		  is the number of bits of the address that ppp will
 		  insist on.  You may wish to use IP numbers more
 		  appropriate to your circumstances, but the above example
 		  will always work.</para>
 
 		<para>The last argument (<literal>0.0.0.0</literal>) tells
 		  PPP to start negotiations using address <hostid
 		  role="ipaddr">0.0.0.0</hostid> rather than <hostid
 		  role="ipaddr">10.0.0.1</hostid> and is necessary for some
                   ISPs.  Do not use <literal>0.0.0.0</literal> as the first
                   argument to <command>set ifaddr</command> as it prevents
                   PPP from setting up an initial route in
                   <option>-auto</option> mode.</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
 
 	  <para>If you are not running in <option>-auto</option> mode, you
 	    will need to create an entry in
             <filename>/etc/ppp/ppp.linkup</filename>.
 	    <filename>ppp.linkup</filename> is used after a connection has
 	    been established.  At this point, <command>ppp</command> will
 	    have assigned the interface addresses and it will now be
 	    possible to add the routing table entries:</para>
 
 	  <programlisting>1     provider:
 2      add default HISADDR</programlisting>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term>Line 1:</term>
 
 	      <listitem>
 		<para>On establishing a connection, <command>ppp</command>
 		  will look for an entry in <filename>ppp.linkup</filename>
 		  according to the following rules: First, try to match
 		  the same label as we used in
 		  <filename>ppp.conf</filename>.  If that fails, look for
 		  an entry for the IP address of our gateway.  This entry
 		  is a four-octet IP style label.  If we still have not
 		  found an entry, look for the <literal>MYADDR</literal>
 		  entry.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 2:</term>
 
 	      <listitem>
 		<para>This line tells <command>ppp</command> to add a
 		  default route that points to <literal>HISADDR</literal>.
 		  <literal>HISADDR</literal> will be replaced with the IP
 		  number of the gateway as negotiated by the IPCP.</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
 
 	  <para>See the <literal>pmdemand</literal> entry in the files
 	    <filename>/usr/share/examples/ppp/ppp.conf.sample</filename> and
 	    <filename>/usr/share/examples/ppp/ppp.linkup.sample</filename> for a
 	    detailed example.</para>
 	</sect4>
 
 	<sect4>
 	  <title>Receiving Incoming Calls</title>
 	  <indexterm><primary>PPP</primary><secondary>receiving
 	  incoming calls</secondary></indexterm>
 	  <para>When you configure <application>ppp</application> to
 	    receive incoming calls on a machine connected to a LAN, you
 	    must decide if you wish to forward packets to the LAN.  If you
 	    do, you should allocate the peer an IP number from your LAN's
 	    subnet, and use the command <command>enable proxy</command> in
 	    your <filename>/etc/ppp/ppp.conf</filename> file.  You should
 	    also confirm that the <filename>/etc/rc.conf</filename> file
 	    contains the following:</para>
 
 	  <programlisting>gateway_enable="YES"</programlisting>
 
 	  <sect5>
 	    <title>Which getty?</title>
 
 	    <para><link linkend="dialup">Configuring FreeBSD for Dial-up
 	      Services</link> provides a good description on enabling
 	      dial-up services using &man.getty.8;.</para>
 
 	    <para>An alternative to <command>getty</command> is <ulink
 	      url="http://www.leo.org/~doering/mgetty/index.html">mgetty</ulink>,
 	      a smarter version of <command>getty</command> designed with
 	      dial-up lines in mind.</para>
 
 	    <para>The advantages of using <command>mgetty</command> is
 	      that it actively <emphasis>talks</emphasis> to modems,
 	      meaning if port is turned off in
 	      <filename>/etc/ttys</filename> then your modem will not answer
 	      the phone.</para>
 
 	    <para>Later versions of <command>mgetty</command> (from
 	      0.99beta onwards) also support the automatic detection of
 	      PPP streams, allowing your clients script-less access to
 	      your server.</para>
 
 	    <para>Refer to <link linkend="userppp-mgetty">Mgetty and
 	      AutoPPP</link> for more information on
 	      <command>mgetty</command>.</para>
 	  </sect5>
 
 	  <sect5>
 	    <title><application>PPP</application> Permissions</title>
 
 	    <para>The <command>ppp</command> command must normally be run
 	      as the <username>root</username> user.  If however, you wish
 	      to allow
 	      <command>ppp</command> to run in server mode as a normal
 	      user by executing <command>ppp</command> as described below,
 	      that user must be given permission to run
 	      <command>ppp</command> by adding them to the
 	      <username>network</username> group in
 	      <filename>/etc/group</filename>.</para>
 
 	    <para>You will also need to give them access to one or more
 	      sections of the configuration file using the
 	      <command>allow</command> command:</para>
 
 	    <programlisting>allow users fred mary</programlisting>
 
 	    <para>If this command is used in the <literal>default</literal>
 	      section, it gives the specified users access to
 	      everything.</para>
 	  </sect5>
 
 	  <sect5>
 	    <title>PPP Shells for Dynamic-IP Users</title>
 	    <indexterm><primary>PPP shells</primary></indexterm>
 
 	    <para>Create a file called
 	      <filename>/etc/ppp/ppp-shell</filename> containing the
 	      following:</para>
 
 	    <programlisting>#!/bin/sh
 IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'`
 CALLEDAS="$IDENT"
 TTY=`tty`
 
 if [ x$IDENT = xdialup ]; then
         IDENT=`basename $TTY`
 fi
 
 echo "PPP for $CALLEDAS on $TTY"
 echo "Starting PPP for $IDENT"
 
 exec /usr/sbin/ppp -direct $IDENT</programlisting>
 
 	    <para>This script should be executable.  Now make a symbolic
 	      link called <filename>ppp-dialup</filename> to this script
 	      using the following commands:</para>
 
 	    <screen>&prompt.root; <userinput>ln -s ppp-shell /etc/ppp/ppp-dialup</userinput></screen>
 
 	    <para>You should use this script as the
 	      <emphasis>shell</emphasis> for all of your dialup users.
 	      This is an example from <filename>/etc/password</filename>
 	      for a dialup PPP user with username
 	      <username>pchilds</username> (remember do not directly edit
 	      the password file, use <command>vipw</command>).</para>
 
 	    <programlisting>pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup</programlisting>
 
 	    <para>Create a <filename>/home/ppp</filename> directory that
 	      is world readable containing the following 0 byte
 	      files:</para>
 
 	    <screen>-r--r--r--   1 root     wheel           0 May 27 02:23 .hushlogin
 -r--r--r--   1 root     wheel           0 May 27 02:22 .rhosts</screen>
 
 	    <para>which prevents <filename>/etc/motd</filename> from being
 	      displayed.</para>
 	  </sect5>
 
 	  <sect5>
 	    <title>PPP Shells for Static-IP Users</title>
 	    <indexterm><primary>PPP shells</primary></indexterm>
 
 	    <para>Create the <filename>ppp-shell</filename> file as above,
 	      and for each account with statically assigned IPs create a
 	      symbolic link to <filename>ppp-shell</filename>.</para>
 
 	    <para>For example, if you have three dialup customers,
 	      <username>fred</username>, <username>sam</username>, and
 	      <username>mary</username>, that you route class C networks
 	      for, you would type the following:</para>
 
 	    <screen>&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred</userinput>
 &prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam</userinput>
 &prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary</userinput></screen>
 
 	    <para>Each of these users dialup accounts should have their
 	      shell set to the symbolic link created above (for example,
 	      <username>mary</username>'s shell should be
 	      <filename>/etc/ppp/ppp-mary</filename>).</para>
 	  </sect5>
 
 	  <sect5>
 	    <title>Setting up <filename>ppp.conf</filename> for Dynamic-IP Users</title>
 	  
 	    <para>The <filename>/etc/ppp/ppp.conf</filename> file should
 	      contain something along the lines of:</para>
 	  
 	    <programlisting>default:
   set debug phase lcp chat
   set timeout 0
 
 ttyd0:
   set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
   enable proxy
 
 ttyd1:
   set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
   enable proxy</programlisting>
 
 	    <note>
 	      <para>The indenting is important.</para>
 	    </note>
 
 	    <para>The <literal>default:</literal> section is loaded for
 	      each session.  For each dialup line enabled in
 	      <filename>/etc/ttys</filename> create an entry similar to
 	      the one for <literal>ttyd0:</literal> above.  Each line
 	      should get a unique IP address from your pool of IP
 	      addresses for dynamic users.</para>
 	  </sect5>
 
 	  <sect5>
 	    <title>Setting up <filename>ppp.conf</filename> for Static-IP
 	      Users</title>
 
 	    <para>Along with the contents of the sample
 	      <filename>/usr/share/examples/ppp/ppp.conf</filename> above you should add
 	      a section for each of the statically assigned dialup users.
 	      We will continue with our <username>fred</username>,
 	      <username>sam</username>, and <username>mary</username>
 	      example.</para>
 
 	    <programlisting>fred:
   set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255
 
 sam:
   set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255
 
 mary:
   set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255</programlisting>
 
 	    <para>The file <filename>/etc/ppp/ppp.linkup</filename> should
 	      also contain routing information for each static IP user if
 	      required.  The line below  would add a route for the <hostid
 	      role="ipaddr">203.14.101.0</hostid> class C via  the
 	      client's ppp link.</para>
 
 	    <programlisting>fred:
   add 203.14.101.0 netmask 255.255.255.0 HISADDR
 
 sam:
   add 203.14.102.0 netmask 255.255.255.0 HISADDR
 
 mary:
   add 203.14.103.0 netmask 255.255.255.0 HISADDR</programlisting>
 	  </sect5>
 	</sect4>
 
 	<sect4>
 	  <title>More on <command>mgetty</command>, AutoPPP, and MS
 	    Extensions</title>
 
 	  <sect5 id="userppp-mgetty">
 	    <title><command>mgetty</command> and AutoPPP</title>
 	    <indexterm>
         <primary><command>mgetty</command></primary>
       </indexterm>
 	    <indexterm><primary>AutoPPP</primary></indexterm>
 	    <indexterm><primary>LCP</primary></indexterm>
 
 	    <para>Configuring and compiling <command>mgetty</command> with
 	      the <literal>AUTO_PPP</literal> option enabled allows
 	      <command>mgetty</command> to detect the LCP phase of PPP
 	      connections and automatically spawn off a ppp shell.
 	      However, since the default login/password sequence does not
 	      occur it is necessary to authenticate users using either PAP
 	      or CHAP.</para>
 
 	    <para>This section assumes the user has successfully
 	      configured, compiled, and installed a version of
 	      <command>mgetty</command> with the
 	      <literal>AUTO_PPP</literal> option (v0.99beta or
 	      later).</para>
 
 	    <para>Make sure your
 	      <filename>/usr/local/etc/mgetty+sendfax/login.config</filename>
 	      file has the following in it:</para>
 
 	    <programlisting>/AutoPPP/ -     -		      /etc/ppp/ppp-pap-dialup</programlisting>
 
 	    <para>This will tell <command>mgetty</command> to run the
 	      <filename>ppp-pap-dialup</filename> script for detected PPP
 	      connections.</para>
 
 	    <para>Create a file called
 	      <filename>/etc/ppp/ppp-pap-dialup</filename> containing the
 	      following (the file should be executable):</para>
 
 	    <programlisting>#!/bin/sh
 exec /usr/sbin/ppp -direct pap$IDENT</programlisting>
 
 	    <para>For each dialup line enabled in
 	      <filename>/etc/ttys</filename>, create a corresponding entry
 	      in <filename>/etc/ppp/ppp.conf</filename>.  This will
 	      happily co-exist with the definitions we created
 	      above.</para>
 
 	    <programlisting>pap:
   enable pap	      
   set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
   enable proxy</programlisting>
 
 	    <para>Each user logging in with this method will need to have
 	      a username/password in
 	      <filename>/etc/ppp/ppp.secret</filename> file, or
 	      alternatively add the following option to authenticate users
 	      via PAP from <filename>/etc/password</filename> file.</para>
 
 	    <programlisting>enable passwdauth</programlisting>
 
 	    <para>If you wish to assign some users a static IP number, you
 	      can specify the number as the third argument in
 	      <filename>/etc/ppp/ppp.secret</filename>.  See
 	      <filename>/usr/share/examples/ppp/ppp.secret.sample</filename> for
 	      examples.</para>
 	  </sect5>
 
 	  <sect5>
 	    <title>MS Extensions</title>
 	    <indexterm><primary>DNS</primary></indexterm>    
 	    <indexterm><primary>NetBIOS</primary></indexterm>
 	    <indexterm><primary>PPP</primary><secondary>Microsoft extensions</secondary></indexterm>
 	    <para>It is possible to configure PPP to supply DNS and
 	      NetBIOS nameserver addresses on demand.</para>
 
 	    <para>To enable these extensions with PPP version 1.x, the
 	      following lines might be added to the relevant section of
 	      <filename>/etc/ppp/ppp.conf</filename>.</para>
 
 	    <programlisting>enable msext
 set ns 203.14.100.1 203.14.100.2
 set nbns 203.14.100.5</programlisting>
 
 	    <para>And for PPP version 2 and above:</para>
 
 	    <programlisting>accept dns
 set dns 203.14.100.1 203.14.100.2
 set nbns 203.14.100.5</programlisting>
 
 	    <para>This will tell the clients the primary and secondary
 	      name server addresses, and a NetBIOS nameserver host.</para>
 
 	    <para>In version 2 and above, if the
 	      <literal>set dns</literal> line is omitted, PPP will use the
 	      values found in <filename>/etc/resolv.conf</filename>.</para>
 	  </sect5>
 	</sect4>
 
         <sect4 id="userppp-PAPnCHAP">
 	  <title>PAP and CHAP Authentication</title>
 	  <indexterm><primary>PAP</primary></indexterm>	    
 	  <indexterm><primary>CHAP</primary></indexterm>	    
 	  <para>Some ISPs set their system up so that the authentication
 	    part of your connection is done using either of the PAP or
 	    CHAP authentication mechanisms.  If this is the case, your ISP
 	    will not give a <prompt>login:</prompt> prompt when you
 	    connect, but will start talking PPP immediately.</para>
 
 	  <para>PAP is less secure than CHAP, but security is not normally
 	    an issue here as passwords, although being sent as plain text
 	    with PAP, are being transmitted down a serial line only.
 	    There is not much room for crackers to
 	    <quote>eavesdrop</quote>.</para>
 
 	  <para>Referring back to the <link linkend="userppp-staticIP">PPP
 	    and Static IP addresses</link> or <link
 	    linkend="userppp-dynamicIP">PPP and Dynamic IP addresses</link>
 	    sections, the following alterations must be made:</para>
 
 	  <programlisting>7       set login
 &hellip;
 12      set authname <replaceable>MyUserName</replaceable>
 13      set authkey <replaceable>MyPassword</replaceable></programlisting>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term>Line 7:</term>
 
 	      <listitem>
 		<para>Your ISP will not normally require that you log into
 		  the server if you are using PAP or CHAP.  You must
 		  therefore disable your <quote>set login</quote>
 		  string.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 12:</term>
 
 	      <listitem>
 		<para>This line specifies your PAP/CHAP user name.  You
 		  will need to insert the correct value for
 		  <replaceable>MyUserName</replaceable>.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term>Line 13:</term>
 	      <indexterm><primary>password</primary></indexterm>
 	      <listitem>
 		<para>This line specifies your PAP/CHAP password.  You
 		  will need to insert the correct value for
 		  <replaceable>MyPassword</replaceable>.  You may want to
 		  add an additional line, such as:</para>
 		    
 		<programlisting>15      accept PAP</programlisting>
 
 		<para>or</para>
 
 		<programlisting>15      accept CHAP</programlisting>
 
 		<para>to make it obvious that this is the intention, but
 		  PAP and CHAP are both accepted by default.</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
 	</sect4>
 
 	<sect4>
 	  <title>Changing Your <command>ppp</command> Configuration on the
 	    Fly</title>
 
 	  <para>It is possible to talk to the <command>ppp</command>
 	    program while it is running in the background, but only if a
 	    suitable diagnostic port has been set up.  To do this, add the
 	    following line to your configuration:</para>
 
 	  <programlisting>set server /var/run/ppp-tun<replaceable>%d</replaceable> DiagnosticPassword 0177</programlisting>
 
 	  <para>This will tell PPP to listen to the specified Unix-domain
 	    socket, asking clients for the specified password before
 	    allowing access.  The <literal>%d</literal> in the name is
 	    replaced with the <devicename>tun</devicename> device number
 	    that is in use.</para>
 
 	  <para>Once a socket has been set up, the &man.pppctl.8; program
 	    may be used in scripts that wish to manipulate the running
 	    program.</para>
 	</sect4>
       </sect3>
 
       <sect3 id="userppp-nat">
        <title>Using PPP Network Address Translation Capability</title>
        <indexterm><primary>PPP</primary><secondary>NAT</secondary></indexterm>
 
        <para>PPP has ability to use internal NAT without kernel diverting
          capabilities. This functionality may be enabled by the following 
          line in <filename>/etc/ppp/ppp.conf</filename>:</para>
 
        <programlisting>nat enable yes</programlisting>
 
        <para>Alternatively, PPP NAT may be enabled by command-line
          option <literal>-nat</literal>. There is also 
          <filename>/etc/rc.conf</filename> knob named 
          <literal>ppp_nat</literal>, which is enabled by default.</para>
 
        <para>If you use this feature, you may also find useful
          the following <filename>/etc/ppp/ppp.conf</filename> options
          to enable incoming connections forwarding:</para>
 
        <programlisting>nat port tcp 10.0.0.2:ftp ftp
 nat port tcp 10.0.0.2:http http</programlisting>
 
        <para>or don't trust the outside at all</para>
 
        <programlisting>nat deny_incoming yes</programlisting>
       </sect3>
 
       <sect3 id="userppp-final">
 	<title>Final System Configuration</title>
 	<indexterm><primary>PPP</primary><secondary>configuration</secondary></indexterm>
 
 	<para>You now have <command>ppp</command> configured, but there
 	  are a few more things to do before it is ready to work.  They
 	  all involve editing the <filename>/etc/rc.conf</filename>
 	  file.</para>
 
 	<para>Working from the top down in this file, make sure the
 	  <literal>hostname=</literal> line is set, e.g.:</para>
 
 	<programlisting>hostname="foo.example.com"</programlisting>
 
 	<para>If your ISP has supplied you with a static IP address and
 	  name, it is probably best that you use this name as your host
 	  name.</para>
 
 	<para>Look for the <literal>network_interfaces</literal> variable.
 	  If you want to configure your system to dial your ISP on demand,
 	  make sure the <devicename>tun0</devicename> device is added to
 	  the list, otherwise remove it.</para>
 
 	<programlisting>network_interfaces="lo0 tun0"
 ifconfig_tun0=</programlisting>
 
 	<note>
 	  <para>The <literal>ifconfig_tun0</literal> variable should be
 	    empty, and a file called
 	    <filename>/etc/start_if.tun0</filename> should be created.
 	    This file should contain the line:</para>
 
 	  <programlisting>ppp -auto mysystem</programlisting>
 
 	  <para>This script is executed at network configuration time,
 	    starting your ppp daemon in automatic mode.  If you have a LAN
 	    for which this machine is a gateway, you may also wish to use
 	    the <option>-alias</option> switch.  Refer to the manual page
 	    for further details.</para>
 	</note>
 
 	<para>Set the router program to <literal>NO</literal> with
 	  following line in your
 	  <filename>/etc/rc.conf</filename>:</para>
 
 	<programlisting>router_enable="NO"</programlisting>
 
 	<indexterm>
     <primary><application>routed</application></primary>
   </indexterm>
 	<para>It is important that the <command>routed</command> daemon is
 	  not started (it is started by default), as
 	  <command>routed</command> tends to delete the default routing
 	  table entries created by <command>ppp</command>.</para>
 
 	<para>It is probably worth your while ensuring that the
 	  <literal>sendmail_flags</literal> line does not include the
 	  <option>-q</option> option, otherwise
 	  <command>sendmail</command> will attempt to do a network lookup
 	  every now and then, possibly causing your machine to dial out.
 	  You may try:</para>
 
 	<programlisting>sendmail_flags="-bd"</programlisting>
 
 	<indexterm>
     <primary><application>sendmail</application></primary>
   </indexterm>
 	<para>The downside of this is that you must force
 	  <command>sendmail</command> to re-examine the mail queue
 	  whenever the ppp link is up by typing:</para>
 
 	<screen>&prompt.root; <userinput>/usr/sbin/sendmail -q</userinput></screen>
 
 	<para>You may wish to use the <command>!bg</command> command in
 	  <filename>ppp.linkup</filename> to do this automatically:</para>
 
 	<programlisting>1     provider:
 2       delete ALL
 3       add 0 0 HISADDR
 4       !bg sendmail -bd -q30m</programlisting>
 
         <indexterm><primary>SMTP</primary></indexterm>
 	<para>If you do not like this, it is possible to set up a
 	  <quote>dfilter</quote> to block SMTP traffic.  Refer to the
 	  sample files for further details.</para>
 
 	<para>Now the only thing left to do is reboot the machine.</para>
 
 	<para>All that is left is to reboot the machine.  After rebooting,
 	  you can now either type:</para>
 
 	<screen>&prompt.root; <userinput>ppp</userinput></screen>
 
 	<para>and then <command>dial provider</command> to start the PPP
 	  session, or, if you want <command>ppp</command> to establish
 	  sessions automatically when there is outbound traffic (and
 	  you have not created the <filename>start_if.tun0</filename>
 	  script), type:</para>
 
 	<screen>&prompt.root; <userinput>ppp -auto provider</userinput></screen>
       </sect3>
 
       <sect3>
 	<title>Summary</title>
 
 	<para>To recap, the following steps are necessary when setting up
 	  ppp for the first time:</para>
 
 	<para>Client side:</para>
 
 	<procedure>
 	  <step>
 	    <para>Ensure that the <devicename>tun</devicename> device is
 	      built into your kernel.</para>
 	  </step>
 
 	  <step>
 	    <para>Ensure that the
 	      <filename>tun<replaceable>X</replaceable></filename> device
 	      file is available in the <filename>/dev</filename>
 	      directory.</para>
 	  </step>
 
 	  <step>
 	    <para>Create an entry in
 	      <filename>/etc/ppp/ppp.conf</filename>.  The
 	      <filename>pmdemand</filename> example should suffice for
 	      most ISPs.</para>
 	  </step>
 
 	  <step>
 	    <para>If you have a dynamic IP address, create an entry in
 	      <filename>/etc/ppp/ppp.linkup</filename>.</para>
 	  </step>
 
 	  <step>
 	    <para>Update your <filename>/etc/rc.conf</filename>
 	      file.</para>
 	  </step>
 
 	  <step>
 	    <para>Create a <filename>start_if.tun0</filename> script if
 	      you require demand dialing.</para>
 	  </step>
 	</procedure>
 
 	<para>Server side:</para>
 
 	<procedure>
 	  <step>
 	    <para>Ensure that the <devicename>tun</devicename> device is
 	      built into your kernel.</para>
 	  </step>
 
 	  <step>
 	    <para>Ensure that the
 	      <filename>tun<replaceable>X</replaceable></filename> device
 	      file is available in the <filename>/dev</filename>
 	      directory.</para>
 	  </step>
 
 	  <step>
 	    <para>Create an entry in <filename>/etc/passwd</filename>
 	      (using the &man.vipw.8; program).</para>
 	  </step>
 
 	  <step>
 	    <para>Create a profile in this users home directory that runs
 	      <command>ppp -direct direct-server</command> or
 	      similar.</para>
 	  </step>
 
 	  <step>
 	    <para>Create an entry in
 	      <filename>/etc/ppp/ppp.conf</filename>.  The
 	      <filename>direct-server</filename> example should
 	      suffice.</para>
 	  </step>
 
 	  <step>
 	    <para>Create an entry in
 	      <filename>/etc/ppp/ppp.linkup</filename>.</para>
 	  </step>
 
 	  <step>
 	    <para>Update your <filename>/etc/rc.conf</filename>
 	      file.</para>
 	  </step>
 	</procedure>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="ppp">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Gennady B.</firstname>
           <surname>Sorokopud</surname>
           <contrib>Parts originally contributed by </contrib>
         </author>
         <author>
           <firstname>Robert</firstname>
           <surname>Huff</surname>
         </author>
       </authorgroup>
     </sect1info>
 
     <title>Using Kernel PPP</title>
 
     <sect2>
       <title>Setting up Kernel PPP</title>
       <indexterm><primary>PPP</primary><secondary>kernel PPP</secondary></indexterm>
 
       <para>Before you start setting up PPP on your machine make sure
 	that <command>pppd</command> is located in
 	<filename>/usr/sbin</filename> and the directory
 	<filename>/etc/ppp</filename> exists.</para>
 
       <para><command>pppd</command> can work in two modes:</para>
 
       <orderedlist>
 	<listitem>
 	  <para>As a <quote>client</quote> &mdash; you want to connect your
 	    machine to the outside world via a PPP serial connection or
 	    modem line.</para>
 	</listitem>
 
         <indexterm><primary>PPP</primary><secondary>server</secondary></indexterm>
 	<listitem>
 	  <para>as a <quote>server</quote> &mdash; your machine is located on
 	    the network and used to connect other computers using
 	    PPP.</para>
 	</listitem>
       </orderedlist>
 
       <para>In both cases you will need to set up an options file
         (<filename>/etc/ppp/options</filename> or
 	<filename>~/.ppprc</filename> if you have more than one user on
 	your machine that uses PPP).</para>
 
       <para>You also will need some modem/serial software (preferably
         kermit) so you can dial and establish a connection with the
 	remote host.</para>
     </sect2>
 
     <sect2>
       <sect2info>
 	<authorgroup>
 	  <author>
 	    <firstname>Trev</firstname>
 	    <surname>Roydhouse</surname>
 	    <contrib>Based on information provided by </contrib>
 	    <!-- Trev.Roydhouse@f401.n711.z3.fidonet.org -->
 	  </author>
 	</authorgroup>
       </sect2info>
 	    
       <title>Using <command>pppd</command> as a Client</title>
       <indexterm><primary>PPP</primary><secondary>client</secondary></indexterm>
       <indexterm><primary>Cisco</primary></indexterm>
       <para>The following <filename>/etc/ppp/options</filename> might be
         used to connect to a Cisco terminal server PPP line.</para>
 
       <programlisting>crtscts         # enable hardware flow control
 modem           # modem control line
 noipdefault     # remote PPP server must supply your IP address.
                 # if the remote host doesn't send your IP during IPCP
                 # negotiation , remove this option
 passive         # wait for LCP packets
 domain ppp.foo.com      # put your domain name here
 
 :&lt;remote_ip&gt;    # put the IP of remote PPP host here
                 # it will be used to route packets via PPP link
                 # if you didn't specified the noipdefault option
                 # change this line to &lt;local_ip&gt;:&lt;remote_ip&gt;
 
 defaultroute    # put this if you want that PPP server will be your
                 # default router</programlisting>
 
       <para>To connect:</para>
 
       <indexterm><primary>kermit</primary></indexterm>
       <indexterm><primary>modem</primary></indexterm>
       <procedure>
 	<step>
 	  <para>Dial to the remote host using kermit (or some other modem
 	    program), and enter your user name and password (or whatever
 	    is needed to enable PPP on the remote host).</para>
 	</step>
 
 	<step>
 	  <para>Exit kermit (without hanging up the line).</para>
 	</step>
 
 	<step>
 	  <para>Enter the following:</para>
 
 	  <screen>&prompt.root; <userinput>/usr/src/usr.sbin/pppd.new/pppd <replaceable>/dev/tty01</replaceable> <replaceable>19200</replaceable></userinput></screen>
 
 	  <para>Be sure to use the appropriate speed and device name.</para>
 	</step>
       </procedure>
 
       <para>Now your computer is connected with PPP.  If the connection
 	fails, you can add the <option>debug</option> option to the
 	<filename>/etc/ppp/options</filename> file and check messages on
 	the console to track the problem.</para>
 	  
       <para>Following <filename>/etc/ppp/pppup</filename> script will make
 	all 3 stages automatically:</para>
 
       <programlisting>#!/bin/sh
 ps ax |grep pppd |grep -v grep
 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
 if [ "X${pid}" != "X" ] ; then
         echo 'killing pppd, PID=' ${pid}
         kill ${pid}
 fi
 ps ax |grep kermit |grep -v grep
 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
 if [ "X${pid}" != "X" ] ; then
         echo 'killing kermit, PID=' ${pid}
         kill -9 ${pid}
 fi
 
 ifconfig ppp0 down
 ifconfig ppp0 delete
 
 kermit -y /etc/ppp/kermit.dial
 pppd /dev/tty01 19200</programlisting>
 
       <indexterm><primary>kermit</primary></indexterm>
       <para><filename>/etc/ppp/kermit.dial</filename> is a kermit script
 	that dials and makes all necessary authorization on the remote
 	host (an example of such a script is attached to the end of this
 	document).</para>
 
       <para>Use the following <filename>/etc/ppp/pppdown</filename> script
         to disconnect the PPP line:</para>
 
       <programlisting>#!/bin/sh
 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
 if [ X${pid} != "X" ] ; then
         echo 'killing pppd, PID=' ${pid}
         kill -TERM ${pid}
 fi
 
 ps ax |grep kermit |grep -v grep
 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
 if [ "X${pid}" != "X" ] ; then
         echo 'killing kermit, PID=' ${pid}
         kill -9 ${pid}
 fi
 
 /sbin/ifconfig ppp0 down
 /sbin/ifconfig ppp0 delete
 kermit -y /etc/ppp/kermit.hup
 /etc/ppp/ppptest</programlisting>
 
       <para>Check to see if PPP is still running by executing
 	<filename>/usr/etc/ppp/ppptest</filename>, which should look like
 	this:</para>
 
       <programlisting>#!/bin/sh
 pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'`
 if [ X${pid} != "X" ] ; then
         echo 'pppd running: PID=' ${pid-NONE}
 else
         echo 'No pppd running.'
 fi
 set -x
 netstat -n -I ppp0
 ifconfig ppp0</programlisting>
 
       <para>To hang up the modem, execute
 	<filename>/etc/ppp/kermit.hup</filename>, which should
 	contain:</para>
 
       <programlisting>set line /dev/tty01	; put your modem device here
 set speed 19200
 set file type binary
 set file names literal
 set win 8
 set rec pack 1024
 set send pack 1024
 set block 3
 set term bytesize 8
 set command bytesize 8
 set flow none
 
 pau 1
 out +++
 inp 5 OK
 out ATH0\13
 echo \13
 exit</programlisting>
 
       <para>Here is an alternate method using <command>chat</command>
 	instead of <command>kermit</command>.</para>
 
       <para>The following two files are sufficient to accomplish a 
 	<command>pppd</command>	connection.</para>
 
       <para><filename>/etc/ppp/options</filename>:</para>
 
       <programlisting>/dev/cuaa1 115200
 
 crtscts		# enable hardware flow control
 modem		# modem control line
 connect "/usr/bin/chat -f /etc/ppp/login.chat.script"
 noipdefault	# remote PPP serve must supply your IP address.
 	        # if the remote host doesn't send your IP during
                 # IPCP negotiation, remove this option
 passive         # wait for LCP packets
 domain &lt;your.domain&gt;	# put your domain name here
 
 :		# put the IP of remote PPP host here
 	        # it will be used to route packets via PPP link
                 # if you didn't specified the noipdefault option
                 # change this line to &lt;local_ip&gt;:&lt;remote_ip&gt;
 
 defaultroute	# put this if you want that PPP server will be
 	        # your default router</programlisting>
 
       <para><filename>/etc/ppp/login.chat.script</filename>:</para>
 
       <note>
 	<para>The following should go on a single line.</para>
       </note>
 
       <programlisting>ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT&lt;phone.number&gt;
   CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: &lt;login-id&gt;
   TIMEOUT 5 sword: &lt;password&gt;</programlisting>
 
       <para>Once these are installed and modified correctly, all you need
 	to do is run <command>pppd</command>, like so:</para>
 
       <screen>&prompt.root; <userinput>pppd</userinput></screen>
     </sect2>
 
     <sect2>
       <title>Using <command>pppd</command> as a Server</title>
 
       <para><filename>/etc/ppp/options</filename> should contain something
 	similar to the following:</para>
 
       <programlisting>crtscts                         # Hardware flow control
 netmask 255.255.255.0           # netmask ( not required )
 192.114.208.20:192.114.208.165  # ip's of local and remote hosts
                                 # local ip must be different from one
                                 # you assigned to the ethernet ( or other )
                                 # interface on your machine.
                                 # remote IP is ip address that will be 
                                 # assigned to the remote machine
 domain ppp.foo.com              # your domain
 passive                         # wait for LCP
 modem                           # modem line</programlisting>
 
       <para>The following <filename>/etc/ppp/pppserv</filename> script
 	will enable tell <application>pppd</application> to behave as a
 	server:</para>
 
       <programlisting>#!/bin/sh 
 ps ax |grep pppd |grep -v grep
 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
 if [ "X${pid}" != "X" ] ; then
         echo 'killing pppd, PID=' ${pid}
         kill ${pid}
 fi
 ps ax |grep kermit |grep -v grep
 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
 if [ "X${pid}" != "X" ] ; then
         echo 'killing kermit, PID=' ${pid}
         kill -9 ${pid}
 fi
 
 # reset ppp interface
 ifconfig ppp0 down
 ifconfig ppp0 delete
 
 # enable autoanswer mode
 kermit -y /etc/ppp/kermit.ans
 
 # run ppp
 pppd /dev/tty01 19200</programlisting>
 
       <para>Use this <filename>/etc/ppp/pppservdown</filename> script to
 	stop the server:</para>
 
       <programlisting>#!/bin/sh 
 ps ax |grep pppd |grep -v grep
 pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
 if [ "X${pid}" != "X" ] ; then
         echo 'killing pppd, PID=' ${pid}
         kill ${pid}
 fi
 ps ax |grep kermit |grep -v grep
 pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
 if [ "X${pid}" != "X" ] ; then
         echo 'killing kermit, PID=' ${pid}
         kill -9 ${pid}
 fi
 ifconfig ppp0 down
 ifconfig ppp0 delete
 
 kermit -y /etc/ppp/kermit.noans</programlisting>
 
       <para>The following kermit script
 	(<filename>/etc/ppp/kermit.ans</filename>) will enable/disable
 	autoanswer mode on your modem.  It should look like this:</para>
 
       <programlisting>set line /dev/tty01
 set speed 19200
 set file type binary
 set file names literal
 set win 8
 set rec pack 1024
 set send pack 1024
 set block 3
 set term bytesize 8
 set command bytesize 8
 set flow none
 
 pau 1
 out +++
 inp 5 OK
 out ATH0\13
 inp 5 OK
 echo \13
 out ATS0=1\13   ; change this to out ATS0=0\13 if you want to disable
                 ; autoanswer mod
 inp 5 OK
 echo \13
 exit</programlisting>
 
       <para>A script named <filename>/etc/ppp/kermit.dial</filename> is
 	used for dialing and authenticating on the remote host.  You will
 	need to customize it for your needs.  Put your login and password
 	in this script; you will also need to change the input statement
 	depending on responses from your modem and remote host.</para>
 
       <programlisting>;
 ; put the com line attached to the modem here:
 ;
 set line /dev/tty01
 ;
 ; put the modem speed here:
 ;
 set speed 19200
 set file type binary            ; full 8 bit file xfer
 set file names literal
 set win 8
 set rec pack 1024
 set send pack 1024
 set block 3
 set term bytesize 8
 set command bytesize 8
 set flow none
 set modem hayes
 set dial hangup off
 set carrier auto                ; Then SET CARRIER if necessary,
 set dial display on             ; Then SET DIAL if necessary,
 set input echo on
 set input timeout proceed
 set input case ignore
 def \%x 0                       ; login prompt counter
 goto slhup
 
 :slcmd                          ; put the modem in command mode
 echo Put the modem in command mode.
 clear                           ; Clear unread characters from input buffer
 pause 1
 output +++                      ; hayes escape sequence
 input 1 OK\13\10                ; wait for OK
 if success goto slhup
 output \13
 pause 1
 output at\13
 input 1 OK\13\10
 if fail goto slcmd              ; if modem doesn't answer OK, try again
 
 :slhup                          ; hang up the phone
 clear                           ; Clear unread characters from input buffer
 pause 1
 echo Hanging up the phone.
 output ath0\13                  ; hayes command for on hook
 input 2 OK\13\10
 if fail goto slcmd              ; if no OK answer, put modem in command mode
 
 :sldial                         ; dial the number
 pause 1
 echo Dialing.
 output atdt9,550311\13\10               ; put phone number here
 assign \%x 0                    ; zero the time counter
 
 :look
 clear                           ; Clear unread characters from input buffer
 increment \%x                   ; Count the seconds
 input 1 {CONNECT }
 if success goto sllogin
 reinput 1 {NO CARRIER\13\10}
 if success goto sldial
 reinput 1 {NO DIALTONE\13\10}
 if success goto slnodial
 reinput 1 {\255}
 if success goto slhup
 reinput 1 {\127}
 if success goto slhup
 if < \%x 60 goto look
 else goto slhup
 
 :sllogin                        ; login
 assign \%x 0                    ; zero the time counter
 pause 1
 echo Looking for login prompt.
 
 :slloop
 increment \%x                   ; Count the seconds
 clear                           ; Clear unread characters from input buffer
 output \13
 ;
 ; put your expected login prompt here:
 ;
 input 1 {Username: }
 if success goto sluid
 reinput 1 {\255}
 if success goto slhup
 reinput 1 {\127}
 if success goto slhup
 if < \%x 10 goto slloop         ; try 10 times to get a login prompt
 else goto slhup                 ; hang up and start again if 10 failures
 
 :sluid
 ;
 ; put your userid here:
 ;
 output ppp-login\13
 input 1 {Password: }
 ;
 ; put your password here:
 ;
 output ppp-password\13
 input 1 {Entering SLIP mode.}
 echo
 quit
 
 :slnodial
 echo \7No dialtone.  Check the telephone line!\7
 exit 1
 
 ; local variables:
 ; mode: csh
 ; comment-start: "; "
 ; comment-start-skip: "; "
 ; end:</programlisting>
     </sect2>
   </sect1>
 
   <sect1 id="pppoe">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Jim</firstname>
           <surname>Mock</surname>
           <contrib>Contributed (from http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html) by </contrib>
 	</author>
       </authorgroup>
       <!-- 10 Jan 2000 -->
     </sect1info>
 
     <title>Using <application>PPP</application> over Ethernet (PPPoE)</title>
     <indexterm><primary>PPP</primary><secondary>over Ethernet</secondary></indexterm>
     <indexterm>
       <primary>PPPoE</primary>
       <see>PPP, over Ethernet</see>
     </indexterm>
 
     <para>This section describes how to set up PPP over Ethernet
       (<acronym>PPPoE</acronym>).</para>
 
     <sect2>
       <title>Configuring the kernel</title>
 
       <para>No kernel configuration is necessary for PPPoE any longer.  If
 	the necessary netgraph support is not built into the kernel, it will
         be dynamically loaded by <application>ppp</application>.</para>
     </sect2>
 
     <sect2>
       <title>Setting up <filename>ppp.conf</filename></title>
 
       <para>Here is an example of a working
         <filename>ppp.conf</filename>:</para>
 
       <programlisting>default:
   set log Phase tun command # you can add more detailed logging if you wish
   set ifaddr 10.0.0.1/0 10.0.0.2/0
 
 name_of_service_provider:
   set device PPPoE:<replaceable>xl1</replaceable> # replace xl1 with your ethernet device
   set authname YOURLOGINNAME
   set authkey YOURPASSWORD
   set dial
   set login
   add default HISADDR</programlisting>
 
     </sect2>
 
     <sect2>
       <title>Running <application>PPP</application></title>
 
       <para>As <username>root</username>, you can run:</para>
 
       <screen>&prompt.root; <userinput>ppp -ddial name_of_service_provider</userinput></screen>
 
     </sect2>
 
     <sect2>
       <title>Starting <application>PPP</application> at Boot</title>
 
       <para>Add the following to your <filename>/etc/rc.conf</filename>
         file:</para>
 
       <programlisting>ppp_enable="YES"
 ppp_mode="ddial"
 ppp_nat="YES"	# if you want to enable nat for your local network, otherwise NO
 ppp_profile="name_of_service_provider"</programlisting>
     </sect2>
 
     <sect2>
       <title>Using a PPPoE Service tag</title>
 
       <para>Sometimes it will be necessary to use a service tag to establish
 	your connection.  Service tags are used to distinguish between
 	different PPPoE servers attached to a given network.</para>
 
       <para>You should have been given any required service tag information
 	in the documentation provided by your ISP.  If you cannot locate
 	it there, ask your ISP's tech support personnel.</para>
 
       <para>As a last resort, you could try the method suggested by the
 	<ulink url="http://www.roaringpenguin.com/pppoe/">Roaring Penguin
 	PPPoE</ulink> program which can be found in the <link
 	linkend="ports">ports collection</link>.  Bear in mind however,
 	this may de-program your modem and render it useless, so
 	think twice before doing it.  Simply install the program shipped
 	with the modem by your provider.  Then, access the
 	<literal>System</literal> menu from the program.  The name of your
 	profile should be listed there.  It is usually
 	<emphasis>ISP</emphasis>.</para>
 
       <para>The profile name (service tag) will be used in the PPPoE
 	configuration entry in <filename>ppp.conf</filename> as the provider
 	part of the <command>set device</command> command (see the &man.ppp.8;
 	manual page for full details).  It should look like this:</para>
 
       <programlisting>set device PPPoE:<replaceable>xl1</replaceable>:<replaceable>ISP</replaceable></programlisting>
 
       <para>Do not forget to change <replaceable>xl1</replaceable>
 	to the proper device for your Ethernet card.</para>
       <para>Do not forget to change <replaceable>ISP</replaceable>
 	to the profile you have just found above.</para>
 
       <para>For additional information, see:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><ulink url="http://renaud.waldura.com/doc/freebsd/pppoe/">Cheaper Broadband with FreeBSD on
 	    DSL</ulink> by Renaud Waldura.</para>
 	</listitem>
 
 	<listitem>
 	  <para><ulink
 	      url="http://www.ruhr.de/home/nathan/FreeBSD/tdsl-freebsd.html">
 	      Nutzung von T-DSL und T-Online mit FreeBSD</ulink>
 	    by Udo Erdelhoff (in German).</para>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2 id="ppp-3com">
 
       <title>PPPoE with a 3Com HomeConnect ADSL Modem Dual Link</title>
 
       <para>This modem does not follow <ulink
 	url="http://www.faqs.org/rfcs/rfc2516.html">RFC 2516</ulink>
 	(<emphasis>A Method for transmitting PPP over Ethernet
 	(PPPoE)</emphasis>, written by L. Mamakos, K. Lidl, J. Evarts,
 	D. Carrel, D. Simone, and R. Wheeler).  Instead, different packet
 	type codes have been used for the Ethernet frames.  Please complain
 	to <ulink url="http://www.3com.com/">3Com</ulink> if you think it
 	should comply with the PPPoE specification.</para>
 
       <para>In order to make FreeBSD capable of communicating with this
 	device, a sysctl must be set.  This can be done automatically at
 	boot time by updating <filename>/etc/sysctl.conf</filename>:</para>
 
 	<programlisting>net.graph.nonstandard_pppoe=1</programlisting>
 
       <para>or can be done for immediate effect with the command
 	<command>sysctl net.graph.nonstandard_pppoe=1</command>.</para>
 
       <para>Unfortunately, because this is a system-wide setting, it is
 	not possible to talk to a normal PPPoE client or server and a
 	3Com HomeConnect ADSL Modem at the same time.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="pppoa">
     <title>Using <application>PPP</application> over ATM (PPPoA)</title>
     <indexterm><primary>PPP</primary><secondary>over ATM</secondary></indexterm>
     <indexterm>
       <primary>PPPoA</primary>
       <see>PPP, over ATM</see>
     </indexterm>
 
     <para>The following describes how to set up PPP over ATM (PPPoA).
       PPPoA is a popular choice among European DSL providers.</para>
 
     <sect2>
       <title>Using PPPoA with the Alcatel Speedtouch USB</title>
 
       <para>PPPoA support for this device is supplied as a port in FreeBSD
 	because the firmware is distributed under <ulink
 	  URL="http://www.alcatel.com/consumer/dsl/disclaimer_lx.htm">Alcatel's
 	license agreement</ulink> and can not be redistributed freely with the
 	base system of FreeBSD.</para>
 
       <para>To install the software, simply use the <link
 	  linkend="ports">ports collection</link>. Install the
 	<filename role="package">net/pppoa</filename> port and follow the
 	instructions provided with it.</para>
     </sect2>
 
     <sect2>
       <title>Using mpd</title>
 
       <para>You can use <application>mpd</application> to connect to a variety
         of services, in particular pptp services. You can find
         <application>mpd</application> in the ports collection,
         <filename role="package">net/mpd</filename>.</para>
 
       <para>First you must install the port, and then you can configure
         <application>mpd</application> to suit your requirements and provider
         settings. The port places a set of sample configuration files which
         are well documented in
         <filename><replaceable>PREFIX</replaceable>/etc/mpd/</filename>.  Note
         here that <emphasis>PREFIX</emphasis> means the directory into which
         your ports are installed, this defaults to
         <filename>/usr/local/</filename>. A complete guide to configuring
         <application>mpd</application> is available in HTML format once the
         port has been installed. It is placed in
         <filename><replaceable>PREFIX</replaceable>/share/mpd/</filename>.
         Here is a sample configuration for connecting to an ADSL service with
         <application>mpd</application>. The configuration is spread over two
         files, first the <filename>mpd.conf</filename>.</para>
 
       <programlisting>default:
     load adsl
 
 adsl:
     new -i ng0 adsl adsl
     set bundle authname <replaceable>username</replaceable> <co
     id="co-mpd-ex-user">
     set bundle password <replaceable>password</replaceable> <co
     id="co-mpd-ex-pass">
     set bundle disable multilink
     
     set link no pap actcomp protocomp
     set link disable chap
     set link accept chap
     set link keep-alive 30 10
     
     set ipcp no vjcomp
     set ipcp ranges 0.0.0.0/0 0.0.0.0/0
     
     set iface route default
     set iface disable on-demand
     set iface enable proxy-arp
     set iface idle 0
 
     open</programlisting>
 
     <calloutlist>
       <callout arearefs="co-mpd-ex-user">
         <para>The username used to authenticate with your ISP.</para>
       </callout>
       <callout arearefs="co-mpd-ex-pass">
         <para>The password used to authenticate with your ISP.</para>
       </callout>
     </calloutlist>
 
     <para>The <filename>mpd.links</filename> file contains information about
       the link, or links, you wish to establish. An example
       <filename>mpd.links</filename> to accompany the above example is given
       beneath.</para>
 
     <programlisting>adsl:
     set link type pptp
     set pptp mode active
     set pptp enable originate incoming outcall
     set pptp self 10.0.0.140
     set pptp peer 10.0.0.138</programlisting>
 
     <para>It is possible to initialise the connection easily by issuing the
       following command as <username>root</username>.</para>
 
     <screen>&prompt.root; <userinput>mpd -b</userinput> <replaceable>adsl</replaceable></screen>
 
     <para>You can see the status of the connection with the following
       command.</para>
 
     <screen>&prompt.user; <userinput>ifconfig <replaceable>ng0</replaceable></userinput>
 : flags=88d1&lt;UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST&gt; mtu 1500
      inet 216.136.204.117 --> 204.152.186.171 netmask 0xffffffff</screen>
     
     <para>Using <application>mpd</application> is the recommended way to
       connect to an ADSL service with &os;.</para>
     
     </sect2>
 
     <sect2>
       <title>Using pptpclient</title>
 	  
       <para>It is also possible to use FreeBSD to connect to other PPPoA
 	services using
 	<filename role="package">net/pptpclient</filename>.</para>
 	  
       <para>To use <filename role="package">net/pptpclient</filename> to
 	connect to a DSL service, install the port or package and edit your
 	<filename>/etc/ppp/ppp.conf</filename>. You will need to be
 	<username>root</username> to perform both of these operations. An
 	example section of <filename>ppp.conf</filename> is given
 	below. For further information on <filename>ppp.conf</filename>
 	options consult the <application>ppp</application> manual page,
 	&man.ppp.8;.</para>
 
       <programlisting>adsl:
  set log phase chat lcp ipcp ccp tun command
  set timeout 0
  enable dns
  set authname <replaceable>username</replaceable> <co id="co-pptp-ex-user">
  set authkey <replaceable>password</replaceable> <co id="co-pptp-ex-pass">
  set ifaddr 0 0
  add default HISADDR</programlisting>
 
    <calloutlist>
      <callout arearefs="co-pptp-ex-user">
 	   <para>The username of your account with the DSL provider.</para>
 	 </callout>
 	 <callout arearefs="co-pptp-ex-pass">
 	   <para>The password for your account.</para>
 	 </callout>
    </calloutlist>
 
    <warning>
      <para>Because you must put your account's password in the
 	 <filename>ppp.conf</filename> file in plain text form you should
 	 make sure than nobody can read the contents of this file. The
 	 following series of commands will make sure the file is only
 	 readable by the <username>root</username> account. Refer to the
 	 manuals pages for &man.chmod.1; and &man.chown.8; for further
 	 information.</para>
 	 <screen>&prompt.root; <userinput>chown root:wheel /etc/ppp/ppp.conf</userinput>
 &prompt.root; <userinput>chmod 600 /etc/ppp/ppp.conf</userinput></screen>
    </warning>
 
       <para>This will open a tunnel for a PPP session to your DSL router.
 	Ethernet DSL modems have a preconfigured LAN IP address which you
 	connect to. In the case of the Alcatel Speedtouch Home this address is
 	<hostid role="ipaddr">10.0.0.138</hostid>. Your routers documentation
 	should tell you which address your device uses. To open the tunnel and
 	start a <application>ppp</application> session execute the following
 	command.</para>
 
       <screen>&prompt.root; <userinput>pptp <replaceable>address</replaceable> <replaceable>isp</replaceable></userinput></screen>
 
       <tip>
 	<para>You may wish to add an ampersand (<quote>&amp;</quote>) to the
 	  end of the previous command because <application>pptp</application>
 	  will not return your prompt to you otherwise.</para>
       </tip>
 	  
       <para>A <devicename>tun</devicename> virtual tunnel device will be
 	created for interaction between the <application>pptp</application>
 	and <application>ppp</application> processes. Once you have been
 	returned to your prompt, or the <application>pptp</application>
 	process has confirmed a connection you can examine the tunnel like
 	so.</para>
 
       <screen>&prompt.user; <userinput>ifconfig <replaceable>tun0</replaceable></userinput>
 tun0: flags=8051&lt;UP,POINTOPOINT,RUNNING,MULTICAST&gt; mtu 1500
         inet 216.136.204.21 --> 204.152.186.171 netmask 0xffffff00 
         Opened by PID 918</screen>
 
       <para>If you are unable to connect, check the configuration of
 	your router, which is usually accessible via
 	<application>telnet</application> or with a web browser. If you still
 	cannot connect you should examine the output of the
 	<application>pptp</application> command and the contents of the
 	<application>ppp</application> log file,
 	<filename>/var/log/ppp.log</filename> for clues.</para>
     </sect2>
   </sect1>
 
   <sect1 id="slip">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Satoshi</firstname>
 	  <surname>Asami</surname>
 	  <contrib>Originally contributed by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Guy</firstname>
 	  <surname>Helmer</surname>
 	  <contrib>With input from </contrib>
 	</author>
 	<author>
 	  <firstname>Piero</firstname>
           <surname>Serini</surname>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title>Using SLIP</title>
     <indexterm><primary>SLIP</primary></indexterm>
 
     <sect2 id="slipc">
       <title>Setting up a SLIP Client</title>
       <indexterm><primary>SLIP</primary><secondary>client</secondary></indexterm>
       <para>The following is one way to set up a FreeBSD machine for SLIP
 	on a static host network.  For dynamic hostname assignments (your
 	address changes each time you dial up), you probably need to
 	have a more complex setup.</para>
 
       <para>First, determine which serial port your modem is connected to.
 	Many people setup a symbolic link, such as
 	<devicename>/dev/modem</devicename>, to point to the real device name,
 	<devicename>/dev/cuaaN</devicename>.  This allows you to
 	abstract the actual device name should you ever need to move
 	the modem to a different port.  It can become quite cumbersome when you
 	need to fix a bunch of files in <filename>/etc</filename> and
 	<filename>.kermrc</filename> files all over the system!</para>
 
       <note>
 	<para><filename>/dev/cuaa0</filename> is
 	  <devicename>COM1</devicename>, <filename>cuaa1</filename> is
 	  <devicename>COM2</devicename>, etc.</para>
       </note>
 
       <para>Make sure you have the following in your kernel configuration
 	file:</para>
       
       <programlisting>pseudo-device   sl      1</programlisting>
 
       <para>It is included in the <filename>GENERIC</filename> kernel, so
 	this should not be a problem unless you have deleted it.</para>
 
       <sect3>
 	<title>Things You Have to Do Only Once</title>
 
 	<procedure>
 	  <step>
 	    <para>Add your home machine, the gateway and nameservers to
 	      your <filename>/etc/hosts</filename> file.  Mine looks like
 	      this:</para>
 
 	    <programlisting>127.0.0.1               localhost loghost
 136.152.64.181          water.CS.Example.EDU water.CS water
 136.152.64.1            inr-3.CS.Example.EDU inr-3 slip-gateway
 128.32.136.9            ns1.Example.EDU ns1
 128.32.136.12           ns2.Example.EDU ns2</programlisting>
 	  </step>
 
 	  <step>
 	    <para>Make sure you have <option>hosts</option> before
 	      <option>bind</option> in your
 	      <filename>/etc/host.conf</filename> on FreeBSD versions
 	      prior to 5.0.  Since FreeBSD&nbsp;5.0, the system uses
 	      the file <filename>/etc/nsswitch.conf</filename> instead,
 	      make sure you have <option>files</option> before
 	      <option>dns</option> in the <option>hosts</option> line
 	      of this file.  Without these parameters funny
 	      things may happen.</para>
 	  </step>
 
 	  <step>
 	    <para>Edit the <filename>/etc/rc.conf</filename> file.</para>
 
 	    <orderedlist>
 	      <listitem>
 		<para>Set your hostname by editing the line that
 		  says:</para>
 	      
 		<programlisting>hostname="myname.my.domain"</programlisting>
 
 		<para>Your machine's full Internet hostname should be
 		  placed here.</para>
 	      </listitem>
 
 	      <listitem>
 		<para>Add <devicename>sl0</devicename> to the list of
 		  network interfaces by changing the line that
 		  says:</para>
 
 		<programlisting>network_interfaces="lo0"</programlisting>
 
 		<para>to:</para>
 
 		<programlisting>network_interfaces="lo0 sl0"</programlisting>
 	      </listitem>
 
 	      <listitem>
 		<para>Set the startup flags of <devicename>sl0</devicename> by adding a
 		  line:</para>
 
 		<programlisting>ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up"</programlisting>
 	      </listitem>
 
 	      <indexterm><primary>default route</primary></indexterm>
 	      <listitem>
 		<para>Designate the default router by changing the
 		  line:</para>
 
 		<programlisting>defaultrouter="NO"</programlisting>
 
 		<para>to:</para>
 
 		<programlisting>defaultrouter="slip-gateway"</programlisting>
 	      </listitem>
 	    </orderedlist>
 	  </step>
 
 	  <step>
 	    <para>Make a file <filename>/etc/resolv.conf</filename> which
 	      contains:</para>
 
 	    <programlisting>domain CS.Example.EDU
 nameserver 128.32.136.9
 nameserver 128.32.136.12</programlisting>
 
 	    <indexterm><primary>nameserver</primary></indexterm>
 	    <indexterm><primary>domain name</primary></indexterm>
 	    <para>As you can see, these set up the nameserver hosts.  Of
 	      course, the actual domain names and addresses depend on your
 	      environment.</para>
 	  </step>
 
 	  <step>
 	    <para>Set the password for <username>root</username> and 
 	      <username>toor</username> (and any other
 	      accounts that do not have a password).</para>
 	  </step>
 
 	  <step>
 	    <para>Reboot your machine and make sure it comes up with the
 	      correct hostname.</para>
 	  </step>
 	</procedure>
       </sect3>
 
       <sect3>
 	<title>Making a SLIP Connection</title>
 	<indexterm><primary>SLIP</primary><secondary>connecting with</secondary></indexterm>
 	<procedure>
 	  <step>
 	    <para>Dial up, type <command>slip</command> at the prompt,
 	      enter your machine name and password.  What is required to
 	      be entered depends on your environment.  If you use
 	      kermit, you can try a script like this:</para>
 
 	    <programlisting># kermit setup
 set modem hayes
 set line /dev/modem
 set speed 115200
 set parity none
 set flow rts/cts
 set terminal bytesize 8
 set file type binary
 # The next macro will dial up and login
 define slip dial 643-9600, input 10 =&gt;, if failure stop, -
 output slip\x0d, input 10 Username:, if failure stop, -
 output silvia\x0d, input 10 Password:, if failure stop, -
 output ***\x0d, echo \x0aCONNECTED\x0a</programlisting>
 
 	    <para>Of course, you have to change the hostname and password
 	      to fit yours.  After doing so, you can just type
 	      <command>slip</command> from the kermit prompt to
 	      connect.</para>
 
 	    <note>
 	      <para>Leaving your password in plain text anywhere in the
 	        filesystem is generally a <emphasis>bad</emphasis> idea.
 		Do it at your own risk.</para>
 	    </note>
 	  </step>
 
 	  <step>
 	    <para>Leave the kermit there (you can suspend it by
 	      <keycombo>
 		<keycap>Ctrl</keycap>
 		<keycap>z</keycap>
 	      </keycombo>) and as <username>root</username>, type:</para>
 
 	    <screen>&prompt.root; <userinput>slattach -h -c -s 115200 /dev/modem</userinput></screen>
 
 	    <para>If you are able to <command>ping</command> hosts on the
 	      other side of the router, you are connected!  If it does not
 	      work, you might want to try <option>-a</option> instead of
 	      <option>-c</option> as an argument to 
               <command>slattach</command>.</para>
 	  </step>
 	</procedure>
       </sect3>
 
       <sect3>
 	<title>How to Shutdown the Connection</title>
 
 	<para>Do the following:</para>
 
 	<screen>&prompt.root; <userinput>kill -INT `cat /var/run/slattach.modem.pid`</userinput></screen>
 
 	<para>to kill <command>slattach</command>.  Keep in mind you must be
 	  <username>root</username> to do the above.  Then go back to
 	  kermit (by running <command>fg</command> if you suspended it) and
 	  exit from
 	  it (<command>q</command>).</para>
 
 	<para>The <command>slattach</command> manual page says you have 
 	  to use <command>ifconfig sl0 down</command> 
           to mark the interface down, but this does not
 	  seem to make any difference for me.
 	  (<command>ifconfig sl0</command> reports the same thing.)</para>
 
 	<para>Some times, your modem might refuse to drop the carrier
 	  (mine often does).  In that case, simply start kermit and quit
 	  it again. It usually goes out on the second try.</para>
       </sect3>
 
       <sect3>
 	<title>Troubleshooting</title>
 
 	<para>If it does not work, feel free to ask me.  The things that
 	  people tripped over so far:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>Not using <option>-c</option> or <option>-a</option> in
 	      <command>slattach</command> (This should not be fatal,
 	      but some users have reported that this solves their
 	      problems.)</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Using <option>s10</option> instead of
 	      <option>sl0</option> (might be hard to see the difference on
 	      some fonts).</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>Try <command>ifconfig sl0</command> to see your
 	      interface status.  For example, you might get:</para>
 
 	    <screen>&prompt.root; <userinput>ifconfig sl0</userinput>
 sl0: flags=10&lt;POINTOPOINT&gt;
         inet 136.152.64.181 --&gt; 136.152.64.1 netmask ffffff00</screen>
 	  </listitem>
 
 	  <listitem>
 	    <para>If you get <errorname>no route to host</errorname>
             messages from ping, there may be a problem with your
             routing table.  You can use the <command>netstat -r</command>
             command to display the current routes :</para>
 
 	    <screen>&prompt.root; <userinput>netstat -r</userinput>
 Routing tables
 Destination      Gateway            Flags     Refs     Use  IfaceMTU    Rtt    Netmasks:
 
 (root node)
 (root node)
 
 Route Tree for Protocol Family inet:
 (root node) =&gt;
 default          inr-3.Example.EDU  UG          8   224515  sl0 -      -
 localhost.Exampl localhost.Example. UH          5    42127  lo0 -       0.438
 inr-3.Example.ED water.CS.Example.E UH          1        0  sl0 -      -
 water.CS.Example localhost.Example. UGH        34 47641234  lo0 -       0.438
 (root node)</screen>
 
 	    <para>The preceding examples are from a relatively busy system.
               The numbers on your system will vary depending on
               network activity.</para>
 
 	  </listitem>
 	</itemizedlist>
       </sect3>
     </sect2>
 
     <sect2 id="slips">
       <title>Setting up a SLIP Server</title>
       <indexterm><primary>SLIP</primary><secondary>server</secondary></indexterm>
 
       <para>This document provides suggestions for setting up SLIP Server
 	services on a FreeBSD system, which typically means configuring
 	your system to automatically startup connections upon login for
 	remote SLIP clients.</para>
 
       <!-- Disclaimer is not necessarily relevant
       <para> The author has written this document based
 	on his experience; however, as your system and needs may be
 	different, this document may not answer all of your questions, and
 	the author cannot be responsible if you damage your system or lose
 	data due to attempting to follow the suggestions here.</para>
       -->
 
       <sect3 id="slips-prereqs">
 	<title>Prerequisites</title>
 	<indexterm><primary>TCP/IP networking</primary></indexterm>
 	<para>This section is very technical in nature, so background
 	  knowledge is required.  It is assumed that you are familiar with
 	  the TCP/IP network protocol, and in particular, network and node
 	  addressing, network address masks, subnetting, routing, and
 	  routing protocols, such as RIP.  Configuring SLIP services on a
 	  dial-up server requires a knowledge of these concepts, and if
 	  you are not familiar with them, please read a copy of either
 	  Craig Hunt's <emphasis>TCP/IP Network Administration</emphasis>
 	  published by O'Reilly &amp; Associates, Inc. (ISBN Number
 	  0-937175-82-X), or Douglas Comer's books on the TCP/IP
 	  protocol.</para>
 
 	<indexterm><primary>modem</primary></indexterm>
 	<para>It is further assumed that you have already setup your
 	  modem(s) and configured the appropriate system files to allow
 	  logins through your modems.  If you have not prepared your
 	  system for this yet, please see the tutorial for configuring
 	  dialup services; if you have a World-Wide Web browser available,
 	  browse the list of tutorials at <ulink
 	  url="../../../../index.html">http://www.FreeBSD.org/</ulink>.
 	  You may also want to check the manual pages for &man.sio.4; for
 	  information on the serial port device driver and &man.ttys.5;,
 	  &man.gettytab.5;, &man.getty.8;, &amp; &man.init.8; for
 	  information relevant to configuring the system to accept logins
 	  on modems, and perhaps &man.stty.1; for information on setting
 	  serial port parameters (such as <literal>clocal</literal> for
 	  directly-connected serial interfaces).</para>
       </sect3>
 
       <sect3>
 	<title>Quick Overview</title>
 
 	<para>In its typical configuration, using FreeBSD as a SLIP server
 	  works as follows:  a SLIP user dials up your FreeBSD SLIP Server
 	  system and logs in with a special SLIP login ID that uses
 	  <filename>/usr/sbin/sliplogin</filename> as the special user's
 	  shell.  The <command>sliplogin</command> program browses the
 	  file <filename>/etc/sliphome/slip.hosts</filename> to find a
 	  matching line for the special user, and if it finds a match,
 	  connects the serial line to an available SLIP interface and then
 	  runs the shell script
 	  <filename>/etc/sliphome/slip.login</filename> to configure the
 	  SLIP interface.</para>
 
         <sect4>
 	  <title>An Example of a SLIP Server Login</title>
 
 	  <para>For example, if a SLIP user ID were
 	    <username>Shelmerg</username>, <username>Shelmerg</username>'s
 	    entry in <filename>/etc/master.passwd</filename> would look
 	    something like this:</para>
 
 	  <programlisting>Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin</programlisting>
 
 	  <para>When <username>Shelmerg</username> logs in,
 	    <command>sliplogin</command> will search
 	    <filename>/etc/sliphome/slip.hosts</filename> for a line that
 	    had a matching user ID; for example, there may be a line in
 	    <filename>/etc/sliphome/slip.hosts</filename> that
 	    reads:</para>
 
 	  <programlisting>Shelmerg        dc-slip sl-helmer       0xfffffc00		  autocomp</programlisting>
 
 	  <para><command>sliplogin</command> will find that matching line,
 	    hook the serial line into the next available SLIP interface,
 	    and then execute <filename>/etc/sliphome/slip.login</filename>
 	    like this:</para>
 
 	  <programlisting>/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting>
 
 	  <para>If all goes well,
 	    <filename>/etc/sliphome/slip.login</filename> will issue an
 	    <command>ifconfig</command> for the SLIP interface to which
 	    <command>sliplogin</command> attached itself (slip interface
 	    0, in the above example, which was the first parameter in the
 	    list given to <filename>slip.login</filename>) to set the
 	    local IP address (<hostid>dc-slip</hostid>), remote IP address
 	    (<hostid>sl-helmer</hostid>), network mask for the SLIP
 	    interface (<hostid role="netmask">0xfffffc00</hostid>), and
 	    any additional flags (<literal>autocomp</literal>).  If
 	    something goes wrong, <command>sliplogin</command> usually
 	    logs good informational messages via the
 	    <literal>daemon</literal> syslog facility, which usually logs
 	    to <filename>/var/log/messages</filename> (see the manual
 	    pages for &man.syslogd.8; and &man.syslog.conf.5; and perhaps
 	    check <filename>/etc/syslog.conf</filename> to see to what
 	    <command>syslogd</command> is logging and where it is
 	    logging to.</para>
 
 	  <para>OK, enough of the examples &mdash; let us dive into
 	    setting up the system.</para>
 	</sect4>
       </sect3>
 
       <sect3>
 	<title>Kernel Configuration</title>
 	<indexterm><primary>kernel</primary><secondary>configuration</secondary></indexterm>
 	<para>FreeBSD's default kernels usually come with two SLIP
 	  interfaces defined (<devicename>sl0</devicename> and
 	  <devicename>sl1</devicename>); you can use <command>netstat
 	  -i</command> to see whether these interfaces are defined in your
 	  kernel.</para>
 
 	<para>Sample output from <command>netstat -i</command>:</para>
 
 	<screen>Name  Mtu   Network     Address            Ipkts Ierrs    Opkts Oerrs  Coll
 ed0   1500  &lt;Link&gt;0.0.c0.2c.5f.4a         291311     0   174209     0   133
 ed0   1500  138.247.224 ivory             291311     0   174209     0   133
 lo0   65535 &lt;Link&gt;                            79     0       79     0     0
 lo0   65535 loop        localhost             79     0       79     0     0
 sl0*  296   &lt;Link&gt;                             0     0        0     0     0
 sl1*  296   &lt;Link&gt;                             0     0        0     0     0</screen>
 
 	<para>The <devicename>sl0</devicename> and
 	  <devicename>sl1</devicename> interfaces shown from
 	  <command>netstat -i</command> indicate that there are
 	  two SLIP interfaces built into the kernel.  (The asterisks after
 	  the <literal>sl0</literal> and <literal>sl1</literal> indicate
 	  that the interfaces are <quote>down</quote>.)</para>
 
 	<para>However, FreeBSD's default kernel does not come configured
 	  to forward packets (by default, your FreeBSD machine will not act
 	  as a
 	  router) due to Internet RFC requirements for Internet hosts (see
 	  RFCs 1009 [Requirements for Internet Gateways], 1122
 	  [Requirements for Internet Hosts &mdash; Communication Layers],
 	  and perhaps 1127 [A Perspective on the Host Requirements RFCs]).
 	  If you want your FreeBSD SLIP Server to act as a router, you
 	  will have to edit the <filename>/etc/rc.conf</filename> file and
 	  change the setting of the <literal>gateway_enable</literal> variable to
 	  <option>YES</option>.</para>
  
 	<para>You will then need to reboot for the new settings to take
 	  effect.</para>
 
 	<para>You will notice that near the end of the default kernel
 	  configuration file (<filename>/sys/i386/conf/GENERIC</filename>)
 	  is a line that reads:</para>
 
 	<programlisting>pseudo-device sl 2</programlisting>
 
 	<indexterm><primary>SLIP</primary></indexterm>
 	<para>This is the line that defines the number of SLIP devices
 	  available in the kernel; the number at the end of the line is
 	  the maximum number of SLIP connections that may be operating
 	  simultaneously.</para>
 
 	<para>Please refer to <xref linkend="kernelconfig"> on
 	  Configuring the FreeBSD Kernel for help in
 	  reconfiguring your kernel.</para>
       </sect3>
 
       <sect3>
 	<title>Sliplogin Configuration</title>
 
 	<para>As mentioned earlier, there are three files in the
 	  <filename>/etc/sliphome</filename> directory that are part of
 	  the configuration for <filename>/usr/sbin/sliplogin</filename>
 	  (see &man.sliplogin.8; for the actual manual page for
 	  <command>sliplogin</command>): <filename>slip.hosts</filename>,
 	  which defines the SLIP users and their associated IP
 	  addresses; <filename>slip.login</filename>, which usually just
 	  configures the SLIP interface; and (optionally)
 	  <filename>slip.logout</filename>, which undoes
 	  <filename>slip.login</filename>'s effects when the serial
 	  connection is terminated.</para>
 
         <sect4>
 	  <title><filename>slip.hosts</filename> Configuration</title>
 
 	  <para><filename>/etc/sliphome/slip.hosts</filename> contains
 	    lines which have at least four items separated by
 	    whitespace:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>SLIP user's login ID</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Local address (local to the SLIP server) of the SLIP
 		link</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Remote address of the SLIP link</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Network mask</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>The local and remote addresses may be host names (resolved
 	    to IP addresses by <filename>/etc/hosts</filename> or by the
 	    domain name service, depending on your specifications in the file
 	    <filename>/etc/nsswitch.conf</filename> on FreeBSD&nbsp;5.X, in
 	    <filename>/etc/host.conf</filename> if you use FreeBSD&nbsp;4.X), and the
 	    network mask may be a name that can be resolved by a lookup
 	    into <filename>/etc/networks</filename>.  On a sample system,
 	    <filename>/etc/sliphome/slip.hosts</filename> looks like
 	    this:</para>
 
 	  <programlisting>#
 # login local-addr      remote-addr     mask            opt1    opt2 
 #                                               (normal,compress,noicmp)
 #
 Shelmerg  dc-slip       sl-helmerg      0xfffffc00      autocomp</programlisting>
 
 	  <para>At the end of the line is one or more of the
 	    options.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para><option>normal</option> &mdash; no header
 		compression</para>
 	    </listitem>
 
 	    <listitem>
 	      <para><option>compress</option> &mdash; compress
 		headers</para>
 	    </listitem>
 
 	    <listitem>
 	      <para><option>autocomp</option> &mdash; compress headers if
 		the remote end allows it</para>
 	    </listitem>
 
 	    <listitem>
 	      <para><option>noicmp</option> &mdash; disable ICMP packets
 		(so any <quote>ping</quote> packets will be dropped instead
 		of using up your bandwidth)</para>
 	    </listitem>
 	  </itemizedlist>
 
   	  <indexterm><primary>SLIP</primary></indexterm>
   	  <indexterm><primary>TCP/IP networking</primary></indexterm>
 	  <para>Your choice of local and remote addresses for your SLIP
 	    links depends on whether you are going to dedicate a TCP/IP
 	    subnet or if you are going to use <quote>proxy ARP</quote> on
 	    your SLIP server (it is not <quote>true</quote> proxy ARP, but
 	    that is the terminology used in this section to describe it).
 	    If you are not sure which method to select or how to assign IP
 	    addresses, please refer to the TCP/IP books referenced in
 	    the SLIP Prerequisites (<xref linkend="slips-prereqs">)
 	    and/or consult your IP network manager.</para>
 
 	  <para>If you are going to use a separate subnet for your SLIP
 	    clients, you will need to allocate the subnet number out of
 	    your assigned IP network number and assign each of your SLIP
 	    client's IP numbers out of that subnet.  Then, you will
 	    probably need to configure a static route to the SLIP
 	    subnet via your SLIP server on your nearest IP router.</para>
 
   	  <indexterm><primary>Ethernet</primary></indexterm>
 	  <para>Otherwise, if you will use the <quote>proxy ARP</quote>
 	    method, you will need to assign your SLIP client's IP
 	    addresses out of your SLIP server's Ethernet subnet, and you
 	    will also need to adjust your
 	    <filename>/etc/sliphome/slip.login</filename> and
 	    <filename>/etc/sliphome/slip.logout</filename> scripts to use
 	    &man.arp.8; to manage the proxy-ARP entries in the SLIP
 	    server's ARP table.</para>
 	</sect4>
 
 	<sect4>
 	  <title><filename>slip.login</filename> Configuration</title>
 
 	  <para>The typical <filename>/etc/sliphome/slip.login</filename>
 	    file looks like this:</para>
 
 	  <programlisting>#!/bin/sh -
 #
 #       @(#)slip.login  5.1 (Berkeley) 7/1/90
 
 #
 # generic login file for a slip line.  sliplogin invokes this with
 # the parameters:
 #      1        2         3        4          5         6     7-n
 #   slipunit ttyspeed loginname local-addr remote-addr mask opt-args
 #
 /sbin/ifconfig sl$1 inet $4 $5 netmask $6</programlisting>
 
 	  <para>This <filename>slip.login</filename> file merely runs
 	    <command>ifconfig</command> for the appropriate SLIP interface
 	    with the local and remote addresses and network mask of the
 	    SLIP interface.</para>
 
 	  <para>If you have decided to use the <quote>proxy ARP</quote>
 	    method (instead of using a separate subnet for your SLIP
 	    clients), your <filename>/etc/sliphome/slip.login</filename>
 	    file will need to look something like this:</para>
 
 	  <programlisting>#!/bin/sh -
 #
 #       @(#)slip.login  5.1 (Berkeley) 7/1/90
 
 #
 # generic login file for a slip line.  sliplogin invokes this with
 # the parameters:
 #      1        2         3        4          5         6     7-n
 #   slipunit ttyspeed loginname local-addr remote-addr mask opt-args
 #
 /sbin/ifconfig sl$1 inet $4 $5 netmask $6 
 # Answer ARP requests for the SLIP client with our Ethernet addr
 /usr/sbin/arp -s $5 00:11:22:33:44:55 pub</programlisting>
 
 	  <para>The additional line in this
 	    <filename>slip.login</filename>, <command>arp -s
 	    &#36;5 00:11:22:33:44:55 pub</command>, creates an ARP entry
 	    in the SLIP server's ARP table.  This ARP entry causes the
 	    SLIP server to respond with the SLIP server's Ethernet MAC
 	    address whenever another IP node on the Ethernet asks to
 	    speak to the SLIP client's IP address.</para>
 
   	  <indexterm><primary>Ethernet</primary><secondary>MAC address</secondary></indexterm>
 	  <para>When using the example above, be sure to replace the
 	    Ethernet MAC address (<hostid
 	    role="mac">00:11:22:33:44:55</hostid>) with the MAC address of
 	    your system's Ethernet card, or your <quote>proxy ARP</quote>
 	    will definitely not work!  You can discover your SLIP server's
 	    Ethernet MAC address by looking at the results of running
 	    <command>netstat -i</command>; the second line of the output
 	    should look something like:</para>
 
 	  <screen>ed0   1500  &lt;Link&gt;0.2.c1.28.5f.4a         191923	0   129457     0   116</screen>
 
 	  <para>This indicates that this particular system's Ethernet MAC
 	    address is <hostid role="mac">00:02:c1:28:5f:4a</hostid>
 	    &mdash; the periods in the Ethernet MAC address given by
 	    <command>netstat -i</command> must be changed to colons and
 	    leading zeros should be added to each single-digit hexadecimal
 	    number to convert the address into the form that &man.arp.8;
 	    desires; see the manual page on &man.arp.8; for complete
 	    information on usage.</para>
 
 	  <note>
 	    <para>When you create
 	      <filename>/etc/sliphome/slip.login</filename> and
 	      <filename>/etc/sliphome/slip.logout</filename>, the
 	      <quote>execute</quote> bit (<command>chmod 755
 	      /etc/sliphome/slip.login /etc/sliphome/slip.logout</command>)
 	      must be set, or <command>sliplogin</command> will be unable
 	      to execute it.</para>
 	  </note>
 	</sect4>
 
 	<sect4>
 	  <title><filename>slip.logout</filename> Configuration</title>
 
 	  <para><filename>/etc/sliphome/slip.logout</filename> is not
 	    strictly needed (unless you are implementing <quote>proxy
 	    ARP</quote>), but if you decide to create it, this is an
 	    example of a basic
 	    <filename>slip.logout</filename> script:</para>
 
 	  <programlisting>#!/bin/sh -
 #
 #       slip.logout
 
 #
 # logout file for a slip line.  sliplogin invokes this with
 # the parameters:
 #      1        2         3        4          5         6     7-n
 #   slipunit ttyspeed loginname local-addr remote-addr mask opt-args
 #
 /sbin/ifconfig sl$1 down</programlisting>
 
 	  <para>If you are using <quote>proxy ARP</quote>, you will want to
 	    have <filename>/etc/sliphome/slip.logout</filename> remove the
 	    ARP entry for the SLIP client:</para>
 
 	  <programlisting>#!/bin/sh -
 #
 #       @(#)slip.logout
 
 #
 # logout file for a slip line.  sliplogin invokes this with
 # the parameters:
 #      1        2         3        4          5         6     7-n
 #   slipunit ttyspeed loginname local-addr remote-addr mask opt-args
 #
 /sbin/ifconfig sl$1 down
 # Quit answering ARP requests for the SLIP client
 /usr/sbin/arp -d $5</programlisting>
 
 	  <para>The <command>arp -d &#36;5</command> removes the ARP entry
 	    that the <quote>proxy ARP</quote>
 	    <filename>slip.login</filename> added when the SLIP client
 	    logged in.</para>
 
 	  <para>It bears repeating: make sure
 	    <filename>/etc/sliphome/slip.logout</filename> has the execute
 	    bit set after you create it (ie, <command>chmod 755
 	    /etc/sliphome/slip.logout</command>).</para>
 	</sect4>
       </sect3>
 
       <sect3>
 	<title>Routing Considerations</title>
 	<indexterm>
     <primary>SLIP</primary>
     <secondary>routing</secondary>
   </indexterm>
 	<para>If you are not using the <quote>proxy ARP</quote> method for
 	  routing packets between your SLIP clients and the rest of your
 	  network (and perhaps the Internet), you will probably 
 	  have to add static routes to your closest default router(s) to
 	  route your SLIP client subnet via your SLIP server.</para>
 
 	<sect4>
 	  <title>Static Routes</title>
 	  <indexterm><primary>static routes</primary></indexterm>
 	  <para>Adding static routes to your nearest default routers can
 	    be troublesome (or impossible if you do not have authority to
 	    do so...).  If you have a multiple-router network in your
 	    organization, some routers, such as those made by Cisco and Proteon, may
 	    not only need to be configured with the static route to the
 	    SLIP subnet, but also need to be told which static routes to
 	    tell other routers about, so some expertise and
 	    troubleshooting/tweaking may be necessary to get
 	    static-route-based routing to work.</para>
 	</sect4>
 
 	<sect4>
 	  <title>Running <command>gated</command></title>
 	  <indexterm>
       <primary><application>gated</application></primary>
     </indexterm>
 
 	<note>
 	  <para><command>gated</command> is proprietary software now and 
 	    will not be available as source code to the public anymore 
 	    (more info on the <ulink
 	    url="http://www.gated.org/">gated</ulink> website). This 
 	    section only exists to ensure backwards compatability for
 	    those that are still using an older version.</para>
 	</note>
 
 	  <para>An alternative to the headaches of static routes is to
 	    install <command>gated</command> on your FreeBSD SLIP server
 	    and configure it to use the appropriate routing protocols
 	    (RIP/OSPF/BGP/EGP) to tell other routers about your SLIP
 	    subnet.  
 	    You'll need to write a <filename>/etc/gated.conf</filename> 
 	    file to configure your gated; here is a sample, similar to
 	    what the author used on a FreeBSD SLIP server:</para>
 
 	  <programlisting>#
 # gated configuration file for dc.dsu.edu; for gated version 3.5alpha5
 # Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface
 #
 #
 # tracing options
 #
 traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ;
 
 rip yes {
   interface sl noripout noripin ;
   interface ed ripin ripout version 1 ;
   traceoptions route ;
 } ;
 
 #
 # Turn on a bunch of tracing info for the interface to the kernel:
 kernel {
   traceoptions remnants request routes info interface ;
 } ;
 
 #
 # Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP
 #
 
 export proto rip interface ed {
   proto direct {
       <replaceable>xxx.xxx.yy</replaceable> mask 255.255.252.0 metric 1; # SLIP connections
   } ;
 } ;
 
 #
 # Accept routes from RIP via ed Ethernet interfaces
 	      
 import proto rip interface ed {
   all ;
 } ;</programlisting>
 
           <indexterm><primary>RIP</primary></indexterm>
 	  <para>The above sample <filename>gated.conf</filename> file
 	    broadcasts routing information regarding the SLIP subnet
 	    <replaceable>xxx.xxx.yy</replaceable> via RIP onto the
 	    Ethernet; if you are using a different Ethernet driver than
 	    the <devicename>ed</devicename> driver, you will need to
 	    change the references to the <devicename>ed</devicename>
 	    interface appropriately.  This sample file also sets up
 	    tracing to <filename>/var/tmp/gated.output</filename> for
 	    debugging <command>gated</command>'s activity; you can
 	    certainly turn off the tracing options if
 	    <command>gated</command> works OK for you.  You will need to
 	    change the <replaceable>xxx.xxx.yy</replaceable>'s into the
 	    network address of your own SLIP subnet (be sure to change the
 	    net mask in the <literal>proto direct</literal> clause as
 	    well).</para>
 
 	  <para>Once you have installed and configured
 	    <command>gated</command> on your system, you will need to
 	    tell the FreeBSD startup scripts to run
 	    <command>gated</command> in place of
 	    <command>routed</command>.  The easiest way to accomplish
 	    this is to set the <varname>router</varname> and
 	    <varname>router_flags</varname> variables in
 	    <filename>/etc/rc.conf</filename>.  Please see the manual
 	    page for <command>gated</command> for information on
 	    command-line parameters.</para>
         </sect4>
       </sect3>
     </sect2>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
index 8463ea879d..eb0b8e9f67 100644
--- a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
@@ -1,4936 +1,4936 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="printing">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Sean</firstname>
 	<surname>Kelly</surname>
 	<contrib>Contributed by </contrib>
       </author>
       <!-- 30 Sept 1995 -->
     </authorgroup>
     <authorgroup>
       <author>
 	<firstname>Jim</firstname>
 	<surname>Mock</surname>
 	<contrib>Restructured and updated by </contrib>
 	<!-- Mar 2000 -->
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Printing</title>
 
-  <sect1>
+  <sect1 id="printing-synopsis">
     <title>Synopsis</title>
     <indexterm><primary>LPD spooling system</primary></indexterm>
     <indexterm><primary>printing</primary></indexterm>
 
     <para>FreeBSD can be used to print to a wide variety of printers, from the
       oldest impact printer to the latest laser printers, and everything in
       between, allowing you to produce high quality printed output from the
       applications you run.</para>
 
     <para>FreeBSD can also be configured to act as a print server on a
       network; in this capacity FreeBSD can receive print jobs from a variety
       of other computers, including other FreeBSD computers, Windows and MacOS
       hosts.  FreeBSD will ensure that one job at a time is printed, and can
       keep statistics on which users and machines are doing the most printing,
       produce <quote>banner</quote> pages showing who's printout is who's, and
       more.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>How to configure the FreeBSD print spooler.</para>
       </listitem>
 
       <listitem>
 	<para>How to install print filters, to handle special print jobs
 	  differently, including converting incoming documents to print
 	  formats that your printers understand.</para>
       </listitem>
 
       <listitem>
 	<para>How to enable header, or banner pages on your printout.</para>
       </listitem>
 
       <listitem>
 	<para>How to print to printers connected to other computers.</para>
       </listitem>
 
       <listitem>
 	<para>How to print to printers connected directly to the
 	  network.</para>
       </listitem>
 
       <listitem>
 	<para>How to control printer restrictions, including limiting the size
 	  of print jobs, and preventing certain users from printing.</para>
       </listitem>
 
       <listitem>
 	<para>How to keep printer statistics, and account for printer
 	  usage.</para>
       </listitem>
 
       <listitem>
 	<para>How to troubleshoot printing problems.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Know how to configure and install a new kernel 
 	  (<xref linkend="kernelconfig">).</para>
       </listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="printing-intro-spooler">
     <title>Introduction</title>
 
     <para>In order to use printers with FreeBSD, you will need to set
       them up to work with the Berkeley line printer spooling system,
       also known as the <application>LPD</application> spooling system.
       It is the standard printer control system in FreeBSD.  This
       chapter introduces the <application>LPD</application> spooling
       system, often simply called <application>LPD</application>, and
       will guide you through its configuration.</para>
 
     <para>If you are already familiar with 
       <application>LPD</application> or another printer spooling
       system, you may wish to skip to section <link
       linkend="printing-intro-setup">Setting up the spooling
       system</link>.</para>
 
     <para><application>LPD</application> controls everything about a 
       host's printers.  It is responsible for a number of things:</para>
 
     <itemizedlist>
       <listitem>
 	<para>It controls access to attached printers and printers
 	  attached to other hosts on the network.</para>
       </listitem>
 
       <indexterm><primary>print jobs</primary></indexterm>
       <listitem>
 	<para>It enables users to submit files to be printed; these
 	  submissions are known as <emphasis>jobs</emphasis>.</para>
       </listitem>
 
       <listitem>
 	<para>It prevents multiple users from accessing a printer at the
 	  same time by maintaining a <emphasis>queue</emphasis> for each
 	  printer.</para>
       </listitem>
 
       <listitem>
 	<para>It can print <emphasis>header pages</emphasis> (also known
 	  as <emphasis>banner</emphasis> or <emphasis>burst</emphasis>
 	  pages) so users can easily find jobs they have printed in a
 	  stack of printouts.</para>
       </listitem>
 
       <listitem>
 	<para>It takes care of communications parameters for printers
 	  connected on serial ports.</para>
       </listitem>
 
       <listitem>
 	<para>It can send jobs over the network to a 
 	  <application>LPD</application> spooler on another host.</para>
       </listitem>
 
       <listitem>
 	<para>It can run special filters to format jobs to be printed for
 	  various printer languages or printer capabilities.</para>
       </listitem>
 
       <listitem>
 	<para>It can account for printer usage.</para>
       </listitem>
     </itemizedlist>
 
     <para>Through a configuration file
       (<filename>/etc/printcap</filename>), and by providing the special
       filter programs, you can enable the <application>LPD</application>
       system to do all or some
       subset of the above for a great variety of printer hardware.</para>
 
     <sect2 id="printing-intro-why">
       <title>Why You Should Use the Spooler</title>
 
       <para>If you are the sole user of your system, you may be wondering
         why you should bother with the spooler when you do not need access
 	control, header pages, or printer accounting.  While it is
 	possible to enable direct access to a printer, you should use the
 	spooler anyway since:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><application>LPD</application> prints jobs in the background;
 	    you do not have to wait
 	    for data to be copied to the printer.</para>
 	</listitem>
 
 	<indexterm><primary>TeX</primary></indexterm>
 	<listitem>
 	  <para><application>LPD</application> can conveniently run a job 
 	    to be printed through
 	    filters to add date/time headers or convert a special file
 	    format (such as a TeX DVI file) into a format the printer will
 	    understand.  You will not have to do these steps
 	    manually.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Many free and commercial programs that provide a print
 	    feature usually expect to talk to the spooler on your system.
 	    By setting up the spooling system, you will more easily
 	    support other software you may later add or already
 	    have.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="printing-intro-setup">
     <title>Basic Setup</title>
 
     <para>To use printers with the <application>LPD</application> spooling
       system, you will need to
       set up both your printer hardware and the 
       <application>LPD</application> software.  This
       document describes two levels of setup:</para>
 
     <itemizedlist>
       <listitem>
 	<para>See section <link linkend="printing-simple">Simple Printer
 	  Setup</link> to learn how to connect a printer, tell 
 	  <application>LPD</application> how to
 	  communicate with it, and print plain text files to the
 	  printer.</para>
       </listitem>
 
       <listitem>
 	<para>See section <link linkend="printing-advanced">Advanced
 	  Printer Setup</link> to find out how to print a variety of
 	  special file formats, to print header pages, to print across a
 	  network, to control access to printers, and to do printer
 	  accounting.</para>
       </listitem>
     </itemizedlist>
 
     <sect2 id="printing-simple">
       <title>Simple Printer Setup</title>
 
       <para>This section tells how to configure printer hardware and the
 	<application>LPD</application> software to use the printer.  
 	It teaches the basics:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Section <link linkend="printing-hardware">Hardware
 	    Setup</link> gives some hints on connecting the printer to a
 	    port on your computer.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Section <link linkend="printing-software">Software
 	    Setup</link> shows how to setup the 
 	    <application>LPD</application> spooler configuration
 	    file (<filename>/etc/printcap</filename>).</para>
 	</listitem>
       </itemizedlist>
 
       <para>If you are setting up a printer that uses a network protocol
 	to accept data to print instead of a serial or parallel interface,
 	see <link linkend="printing-advanced-network-net-if">Printers With
 	Networked Data Stream Interfaces</link>.</para>
 
       <para>Although this section is called <quote>Simple Printer
 	Setup</quote>, it is actually fairly complex.  Getting the printer
 	to work with your computer and the <application>LPD</application>
 	spooler is the hardest
 	part.  The advanced options like header pages and accounting are
 	fairly easy once you get the printer working.</para>
 
       <sect3 id="printing-hardware">
 	<title>Hardware Setup</title>
 
 	<para>This section tells about the various ways you can connect a
 	  printer to your PC.  It talks about the kinds of ports and
 	  cables, and also the kernel configuration you may need to enable
 	  FreeBSD to speak to the printer.</para>
 
 	<para>If you have already connected your printer and have
 	  successfully printed with it under another operating system, you
 	  can probably skip to section <link
 	  linkend="printing-software">Software Setup</link>.</para>
 
 	<sect4 id="printing-ports">
 	  <title>Ports and Cables</title>
 
 	  <para>Nearly all printers you can get for a PC today support one
 	    or both of the following interfaces:</para>
 
 	  <itemizedlist>
 	    <indexterm>
         <primary>printer</primary>
         <secondary>serial</secondary>
       </indexterm>
 	    <listitem>
 	      <para><emphasis>Serial</emphasis> interfaces use a serial
 		port on your computer to send data to the printer.  Serial
 		interfaces are common in the computer industry and cables
 		are readily available and also easy to construct.  Serial
 		interfaces sometimes need special cables and might require
 		you to configure somewhat complex communications
 		options.</para>
 	    </listitem>
 
 	    <indexterm>
         <primary>printer</primary>
         <secondary>parallel</secondary>
       </indexterm>
 	    <listitem>
 	      <para><emphasis>Parallel</emphasis> interfaces use a
 		parallel port on your computer to send data to the
 		printer.  Parallel interfaces are common in the PC market.
 		Cables are readily available but more difficult to
 		construct by hand.  There are usually no communications
 		options with parallel interfaces, making their
 		configuration exceedingly simple.</para>
 
 	      <indexterm>
 	        <primary>centronics</primary>
 		<see>parallel printers</see>
 	      </indexterm>
 	      <para>Parallel interfaces are sometimes known as
 		<quote>Centronics</quote> interfaces, named after the
 		connector type on the printer.</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>In general, serial interfaces are slower than parallel
 	    interfaces.  Parallel interfaces usually offer just
 	    one-way communication (computer to printer) while serial
 	    gives you two-way.  Many newer parallel ports and printers
 	    can communicate in both directions under FreeBSD when a
 	    IEEE1284 compliant cable is used.</para>
 
 	  <indexterm><primary>PostScript</primary></indexterm>
 	  <para>Usually, the only time you need two-way communication with
 	    the printer is if the printer speaks PostScript.  PostScript
 	    printers can be very verbose.  In fact, PostScript jobs are
 	    actually programs sent to the printer; they need not produce
 	    paper at all and may return results directly to the computer.
 	    PostScript also uses two-way communication to tell the
 	    computer about problems, such as errors in the PostScript
 	    program or paper jams.  Your users may be appreciative of such
 	    information.  Furthermore, the best way to do effective
 	    accounting with a PostScript printer requires two-way
 	    communication: you ask the printer for its page count (how
 	    many pages it has printed in its lifetime), then send the
 	    user's job, then ask again for its page count.  Subtract the
 	    two values and you know how much paper to charge the
 	    user.</para>
 	</sect4>
 	  
 	<sect4 id="printing-parallel">
 	  <title>Parallel Ports</title>
 
 	  <para>To hook up a printer using a parallel interface, connect
 	    the Centronics cable between the printer and the computer.
 	    The instructions that came with the printer, the computer, or
 	    both should give you complete guidance.</para>
 
 	  <para>Remember which parallel port you used on the computer.
 	    The first parallel port is <filename>/dev/ppc0</filename> to
 	    FreeBSD; the second is <filename>/dev/ppc1</filename>, and so
 	    on.  The printer device name uses the same scheme:
 	    <filename>/dev/lpt0</filename> for the printer on the first
 	    parallel ports etc.</para>
 	</sect4>
 
 	<sect4 id="printing-serial">
 	  <title>Serial Ports</title>
 
 	  <para>To hook up a printer using a serial interface, connect the
 	    proper serial cable between the printer and the computer.  The
 	    instructions that came with the printer, the computer, or both
 	    should give you complete guidance.</para>
 
 	  <para>If you are unsure what the <quote>proper serial
 	    cable</quote> is, you may wish to try one of the following
 	    alternatives:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>A <emphasis>modem</emphasis> cable connects each pin
 		of the connector on one end of the cable straight through
 		to its corresponding pin of the connector on the other
 		end.  This type of cable is also known as a
 		<quote>DTE-to-DCE</quote> cable.</para>
 	    </listitem>
 
 	    <indexterm><primary>null-modem cable</primary></indexterm>
 	    <listitem>
 	      <para>A <emphasis>null-modem</emphasis> cable connects some
 		pins straight through, swaps others (send data to receive
 		data, for example), and shorts some internally in each
 		connector hood.  This type of cable is also known as a
 		<quote>DTE-to-DTE</quote> cable.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>A <emphasis>serial printer</emphasis> cable, required
 		for some unusual printers, is like the null-modem cable,
 		but sends some signals to their counterparts instead of
 		being internally shorted.</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <indexterm><primary>baud rate</primary></indexterm>
 	  <indexterm><primary>parity</primary></indexterm>
 	  <indexterm><primary>flow control protocol</primary></indexterm>
 	  <para>You should also set up the communications parameters for
 	    the printer, usually through front-panel controls or DIP
 	    switches on the printer.  Choose the highest
 	    <literal>bps</literal> (bits per second, sometimes
 	    <emphasis>baud rate</emphasis>) rate that both your computer
 	    and the printer can support.  Choose 7 or 8 data bits; none,
 	    even, or odd parity; and 1 or 2 stop bits.  Also choose a flow
 	    control protocol:  either none, or XON/XOFF (also known as
 	    <quote>in-band</quote> or <quote>software</quote>) flow control.
 	    Remember these settings for the software configuration that
 	    follows.</para>
 	</sect4>
       </sect3>
 
       <sect3 id="printing-software">
 	<title>Software Setup</title>
 
 	<para>This section describes the software setup necessary to print
 	  with the <application>LPD</application> spooling system in FreeBSD.
 	</para>
 
 	<para>Here is an outline of the steps involved:</para>
 
 	<procedure>
 	  <step>
 	    <para>Configure your kernel, if necessary, for the port you
 	      are using for the printer; section <link
 	      linkend="printing-kernel">Kernel Configuration</link> tells
 	      you what you need to do.</para>
 	  </step>
 
 	  <step>
 	    <para>Set the communications mode for the parallel port, if
 	      you are using a parallel port; section <link
 	      linkend="printing-parallel-port-mode">Setting the
 	      Communication Mode for the Parallel Port</link> gives
 	      details.</para>
 	  </step>
 
 	  <step>
 	    <para>Test if the operating system can send data to the printer.
 	      Section <link linkend="printing-testing">Checking Printer
 	      Communications</link> gives some suggestions on how to do
 	      this.</para>
 	  </step>
 
 	  <step>
 	    <para>Set up <application>LPD</application> for the printer by 
 	      modifying the file
 	      <filename>/etc/printcap</filename>.  You will find out how
 	      to do this later in this chapter.</para>
 	  </step>
 	</procedure>
 
 	<sect4 id="printing-kernel">
 	  <title>Kernel Configuration</title>
 
 	  <para>The operating system kernel is compiled to work with a
 	    specific set of devices.  The serial or parallel interface for
 	    your printer is a part of that set.  Therefore, it might be
 	    necessary to add support for an additional serial or parallel
 	    port if your kernel is not already configured for one.</para>
 
 	  <para>To find out if the kernel you are currently using supports
 	    a serial interface, type:</para>
 
 	  <screen>&prompt.root; <userinput>dmesg | grep sio<replaceable>N</replaceable></userinput></screen>
 
 	  <para>Where <replaceable>N</replaceable> is the number of the
 	    serial port, starting from zero.  If you see output similar to
 	    the following:</para>
 
 	  <screen>sio2 at port 0x3e8-0x3ef irq 5 on isa
 sio2: type 16550A</screen>
 
 	  <para>then the kernel supports the port.</para>
 
 	  <para>To find out if the kernel supports a parallel interface,
 	    type:</para>
 
 	  <screen>&prompt.root; <userinput>dmesg | grep ppc<replaceable>N</replaceable></userinput></screen>
 
 	  <para>Where <replaceable>N</replaceable> is the number of the
 	    parallel port, starting from zero.  If you see output similar
 	    to the following:</para>
 	    
 	    <screen>ppc0: &lt;Parallel port&gt; at port 0x378-0x37f irq 7 on isa0
 ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode
 ppc0: FIFO with 16/16/8 bytes threshold</screen>
 	    
 	    <para>then the kernel supports the port.</para>
 
 	  <para>You might have to reconfigure your kernel in order for the
 	    operating system to recognize and use the parallel or serial
 	    port you are using for the printer.</para>
 
 	  <para>To add support for a serial port, see the section on
 	    kernel configuration.  To add support for a parallel port, see
 	    that section <emphasis>and</emphasis> the section that
 	    follows.</para>
 	</sect4>
       </sect3>
 
       <sect3 id="printing-dev-ports">
 	<title>Adding <filename>/dev</filename> Entries for the
 	  Ports</title>
 
 	<note><para>FreeBSD&nbsp;5.0 includes the <literal>devfs</literal>
 	  filesystem which automatically creates device nodes as
 	  needed.  If you are running a version of FreeBSD with
 	  <literal>devfs</literal> enabled then you can safely skip
 	  this section.</para></note>
 
 	<para>Even though the kernel may support communication along a
 	  serial or parallel port, you will still need a software
 	  interface through which programs running on the system can
 	  send and receive data.  That is what entries in the
 	  <filename>/dev</filename> directory are for.</para>
 
 	<para><emphasis>To add a <filename>/dev</filename> entry for a
 	  port:</emphasis></para>
 
 	<procedure>
 	  <step>
 	    <para>Become <username>root</username> with the &man.su.1; command.
 	       Enter the <username>root</username> password when prompted.</para>
 	  </step>
 
 	  <step>
 	    <para>Change to the <filename>/dev</filename>
 	      directory:</para>
 
 	    <screen>&prompt.root; <userinput>cd /dev</userinput></screen>
 	  </step>
 
 	  <step>
 	    <para>Type:</para>
 
 	    <screen>&prompt.root; <userinput>./MAKEDEV <replaceable>port</replaceable></userinput></screen>
 
 	    <para>Where <replaceable>port</replaceable> is the device
 	      entry for the port you want to make.  Use
 	      <literal>lpt0</literal> for the printer on the first parallel port,
 	      <literal>lpt1</literal> for the printer on the second port, and so on; use
 	      <literal>ttyd0</literal> for the first serial port,
 	      <literal>ttyd1</literal> for the second, and so on.</para>
 	  </step>
 
 	  <step>
 	    <para>Type:</para>
 
 	    <screen>&prompt.root; <userinput>ls -l <replaceable>port</replaceable></userinput></screen>
 
 	    <para>to make sure the device entry got created.</para>
 	  </step>
 	</procedure>
 
 	<sect4 id="printing-parallel-port-mode">
 	  <title>Setting the Communication Mode for the Parallel
 	    Port</title>
 
 	  <para>When you are using the parallel interface, you can choose
 	    whether FreeBSD should use interrupt-driven or polled
 	    communication with the printer.  The generic printer
 	    device driver (&man.lpt.4;) on FreeBSD&nbsp;4.X and 5.X
 	    uses the &man.ppbus.4; system, which controls the port
 	    chipset with the &man.ppc.4; driver.</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>The <emphasis>interrupt-driven</emphasis> method is
 		the default with the GENERIC kernel.  With this method,
 		the operating system uses an IRQ line to determine when
 		the printer is ready for data.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>The <emphasis>polled</emphasis> method directs the
 		operating system to repeatedly ask the printer if it is
 		ready for more data.  When it responds ready, the kernel
 		sends more data.</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>The interrupt-driven method is usually somewhat faster
 	    but uses up a precious IRQ line.  Some newer HP printers
 	    are claimed not to work correctly in interrupt mode,
 	    apparently due to some (not yet exactly understood) timing
 	    problem.  These printers need polled mode.  You should use
 	    whichever one works.  Some printers will work in both
 	    modes, but are painfully slow in interrupt mode.</para>
 
 	  <para>You can set the communications mode in two ways: by
 	    configuring the kernel or by using the &man.lptcontrol.8;
 	    program.</para>
 
 	  <para><emphasis>To set the communications mode by configuring
 	    the kernel:</emphasis></para>
 
 	  <procedure>
 	    <step>
 	      <para>Edit your kernel configuration file.  Look for
 		an <literal>ppc0</literal> entry.  If you are setting up
 		the second parallel port, use <literal>ppc1</literal>
 		instead.  Use <literal>ppc2</literal> for the third port,
 		and so on.</para>
 
 	      <itemizedlist>
 		<listitem>
 		  <para>If you want interrupt-driven mode, for FreeBSD&nbsp;4.X add the
 		    <literal>irq</literal> specifier:</para>
 
 		  <programlisting>device ppc0 at isa? irq <replaceable>N</replaceable></programlisting>
 
 		  <para>Where <replaceable>N</replaceable> is the IRQ
 		    number for your computer's parallel port.</para>
 
 		  <para>For FreeBSD&nbsp;5.X, edit the following line:</para>
 
 		  <programlisting>hint.ppc.0.irq="<replaceable>N</replaceable>"</programlisting>
 
 		  <para>in the <filename>/boot/device.hints</filename> file
 		    and replace <replaceable>N</replaceable> with the right
 		    IRQ number.  The kernel configuration file must
 		    also contain the &man.ppc.4; driver:</para>
 
 		  <screen>device ppc</screen>
 
 		</listitem>
 
 		<listitem>
 		  <para>If you want polled mode, do not add the
 		    <literal>irq</literal> specifier:</para>
 
 		  <para>For FreeBSD&nbsp;4.X, use the following line in
 		    your kernel configuration file:</para>
 
 		  <programlisting>device ppc0 at isa?</programlisting>
 
 		  <para>For FreeBSD&nbsp;5.X, simply remove in your
 		    <filename>/boot/device.hints</filename> file, the
 		    following line:</para>
 
 		  <programlisting>hint.ppc.0.irq="<replaceable>N</replaceable>"</programlisting>
 
 		  <para>In some cases, this is not enough to put the
 		    port in polled mode under FreeBSD&nbsp;5.X.  Most of
 		    time it comes from &man.acpi.4; driver, this latter
 		    is able to probe and attach devices, and therefore,
 		    control the access mode to the printer port.  You
 		    should check your &man.acpi.4; configuration to
 		    correct this problem.</para>
 		</listitem>
 	      </itemizedlist>
 	    </step>
 
 	    <step>
 	      <para>Save the file.  Then configure, build, and install the
 		kernel, then reboot.  See <link
 		linkend="kernelconfig">kernel configuration</link> for
 		more details.</para>
 	    </step>
 	  </procedure>
 
 	  <para><emphasis>To set the communications mode with</emphasis>
 	    &man.lptcontrol.8;:</para>
 
 	  <procedure>
 	    <step>
 	      <para>Type:</para>
 
 	      <screen>&prompt.root; <userinput>lptcontrol -i -d /dev/lpt<replaceable>N</replaceable></userinput></screen>
 
 	      <para>to set interrupt-driven mode for
 		<literal>lpt<replaceable>N</replaceable></literal>.</para>
 	    </step>
 
 	    <step>
 	      <para>Type:</para>
 
 	      <screen>&prompt.root; <userinput>lptcontrol -p -d /dev/lpt<replaceable>N</replaceable></userinput></screen>
 
 	      <para>to set polled-mode for
 		<literal>lpt<replaceable>N</replaceable></literal>.</para>
 	    </step>
 	  </procedure>
 
 	  <para>You could put these commands in your
 	    <filename>/etc/rc.local</filename> file to set the mode each
 	    time your system boots.  See &man.lptcontrol.8; for more
 	    information.</para>
 	</sect4>
 
 	<sect4 id="printing-testing">
 	  <title>Checking Printer Communications</title>
 
 	  <para>Before proceeding to configure the spooling system, you
 	    should make sure the operating system can successfully send
 	    data to your printer.  It is a lot easier to debug printer
 	    communication and the spooling system separately.</para>
 
 	  <para>To test the printer, we will send some text to it.  For
 	    printers that can immediately print characters sent to them,
 	    the program  &man.lptest.1; is perfect: it generates all 96
 	    printable ASCII characters in 96 lines.</para>
 
 	  <indexterm><primary>PostScript</primary></indexterm>
 	  <para>For a PostScript (or other language-based) printer, we
 	    will need a more sophisticated test.  A small PostScript
 	    program, such as the following, will suffice:</para>
 
 	  <programlisting>%!PS
 100 100 moveto 300 300 lineto stroke
 310 310 moveto /Helvetica findfont 12 scalefont setfont
 (Is this thing working?) show
 showpage</programlisting>
 
 	  <para>The above PostScript code can be placed into a file and
 	    used as shown in the examples appearing in the following
 	    sections.</para>
 
 	  <indexterm><primary>PCL</primary></indexterm>
 	  <note>
 	    <para>When this document refers to a printer language, it is
 	      assuming a language like PostScript, and not Hewlett
 	      Packard's PCL.  Although PCL has great functionality, you
 	      can intermingle plain text with its escape sequences.
 	      PostScript cannot directly print plain text, and that is the
 	      kind of printer language for which we must make special
 	      accommodations.</para>
 	  </note>
 
 	  <sect5 id="printing-checking-parallel">
 	    <title>Checking a Parallel Printer</title>
 
 	    <indexterm>
         <primary>printer</primary>
         <secondary>parallel</secondary>
       </indexterm>
 	    <para>This section tells you how to check if FreeBSD can
 	      communicate with a printer connected to a parallel
 	      port.</para>
 
 	    <para><emphasis>To test a printer on a parallel
 	      port:</emphasis></para>
 
 	    <procedure>
 	      <step>
 		<para>Become <username>root</username> with  &man.su.1;.</para>
 	      </step>
 
 	      <step>
 		<para>Send data to the printer.</para>
 
 		<itemizedlist>
 		  <listitem>
 		    <para>If the printer can print plain text, then use
 		      &man.lptest.1;.  Type:</para>
 
 		    <screen>&prompt.root; <userinput>lptest &gt; /dev/lpt<replaceable>N</replaceable></userinput></screen>
 
 		    <para>Where <replaceable>N</replaceable> is the number
 		      of the parallel port, starting from zero.</para>
 		  </listitem>
 
 		  <listitem>
 		    <para>If the printer understands PostScript or other
 		      printer language, then send a small program to the
 		      printer.  Type:</para>
 
 		    <screen>&prompt.root; <userinput>cat &gt; /dev/lpt<replaceable>N</replaceable></userinput></screen>
 
 		    <para>Then, line by line, type the program
 		      <emphasis>carefully</emphasis> as you cannot edit a
 		      line once you have pressed <literal>RETURN</literal>
 		      or <literal>ENTER</literal>.  When you have finished
 		      entering the program, press
 		      <literal>CONTROL+D</literal>, or whatever your end
 		      of file key is.</para>
 
 		    <para>Alternatively, you can put the program in a file
 		      and type:</para>
 
 		    <screen>&prompt.root; <userinput>cat <replaceable>file</replaceable> &gt; /dev/lpt<replaceable>N</replaceable></userinput></screen>
 
 		    <para>Where <replaceable>file</replaceable> is the
 		      name of the file containing the program you want to
 		      send to the printer.</para>
 		  </listitem>
 		</itemizedlist>
 	      </step>
 	    </procedure>
 
 	    <para>You should see something print.  Do not worry if the
 	      text does not look right; we will fix such things
 	      later.</para>
 	  </sect5>
 
 	  <sect5 id="printing-checking-serial">
 	    <title>Checking a Serial Printer</title>
 
 	    <indexterm>
         <primary>printer</primary>
         <secondary>serial</secondary>
       </indexterm>
 	    <para>This section tells you how to check if FreeBSD can
 	      communicate with a printer on a serial port.</para>
 
 	    <para><emphasis>To test a printer on a serial
 	      port:</emphasis></para>
 
 	    <procedure>
 	      <step>
 		<para>Become <username>root</username> with &man.su.1;.</para>
 	      </step>
 
 	      <step>
 		<para>Edit the file <filename>/etc/remote</filename>.  Add
 		  the following entry:</para>
 
 		<programlisting>printer:dv=/dev/<replaceable>port</replaceable>:br#<replaceable>bps-rate</replaceable>:pa=<replaceable>parity</replaceable></programlisting>
 
 		<indexterm><primary>bits-per-second</primary></indexterm>
 		<indexterm><primary>serial port</primary></indexterm>
 		<indexterm><primary>parity</primary></indexterm>
 		<para>Where <replaceable>port</replaceable> is the device
 		  entry for the serial port (<literal>ttyd0</literal>,
 		  <literal>ttyd1</literal>, etc.),
 		  <replaceable>bps-rate</replaceable> is the
 		  bits-per-second rate at which the printer communicates,
 		  and <replaceable>parity</replaceable> is the parity
 		  required by the printer (either <literal>even</literal>,
 		  <literal>odd</literal>, <literal>none</literal>, or
 		  <literal>zero</literal>).</para>
 
 		<para>Here is a sample entry for a printer connected via
 		  a serial line to the third serial port at 19200&nbsp;bps with
 		  no parity:</para>
 
 		<programlisting>printer:dv=/dev/ttyd2:br#19200:pa=none</programlisting>
 	      </step>
 
 	      <step>
 		<para>Connect to the printer with &man.tip.1;.
 		  Type:</para>
 
 		<screen>&prompt.root; <userinput>tip printer</userinput></screen>
 
 		<para>If this step does not work, edit the file
 		  <filename>/etc/remote</filename> again and try using
 		  <filename>/dev/cuaa<replaceable>N</replaceable></filename>
 		  instead of
 		  <filename>/dev/ttyd<replaceable>N</replaceable></filename>.</para>
 	      </step>
 
 	      <step>
 		<para>Send data to the printer.</para>
 
 		<itemizedlist>
 		  <listitem>
 		    <para>If the printer can print plain text, then use
 		      &man.lptest.1;.  Type:</para>
 
 		    <screen>&prompt.user; <userinput>$lptest</userinput></screen>
 		  </listitem>
 
 		  <listitem>
 		    <para>If the printer understands PostScript or other
 		      printer language, then send a small program to the
 		      printer.  Type the program, line by line,
 		      <emphasis>very carefully</emphasis> as backspacing
 		      or other editing keys may be significant to the
 		      printer.  You may also need to type a special
 		      end-of-file key for the printer so it knows it
 		      received the whole program.  For PostScript
 		      printers, press <literal>CONTROL+D</literal>.</para>
 
 		    <para>Alternatively, you can put the program in a file
 		      and type:</para>
 
 		    <screen>&prompt.user; <userinput>&gt;<replaceable>file</replaceable></userinput></screen>
 
 		    <para>Where <replaceable>file</replaceable> is the
 		      name of the file containing the program.  After
 		      &man.tip.1; sends the file, press any required
 		      end-of-file key.</para>
 		  </listitem>
 		</itemizedlist>
 	      </step>
 	    </procedure>
 
 	    <para>You should see something print.  Do not worry if the
 	      text does not look right; we will fix that later.</para>
 	  </sect5>
 	</sect4>
       </sect3>
 
       <sect3 id="printing-printcap">
 	<title>Enabling the Spooler: The <filename>/etc/printcap</filename>
 	  File</title>
 
 	<para>At this point, your printer should be hooked up, your kernel
 	  configured to communicate with it (if necessary), and you have
 	  been able to send some simple data to the printer.  Now, we are
 	  ready to configure <application>LPD</application> to control access
 	  to your printer.</para>
 
 	<para>You configure <application>LPD</application> by editing the file
 	  <filename>/etc/printcap</filename>.  The 
 	  <application>LPD</application> spooling system
 	  reads this file each time the spooler is used, so updates to the
 	  file take immediate effect.</para>
 
 	<indexterm>
     <primary>printer</primary>
     <secondary>capabilities</secondary>
   </indexterm>
 	<para>The format of the &man.printcap.5; file is straightforward.
 	  Use your favorite text editor to make changes to
 	  <filename>/etc/printcap</filename>.  The format is identical to
 	  other capability files like
 	  <filename>/usr/share/misc/termcap</filename> and
 	  <filename>/etc/remote</filename>.  For complete information
 	  about the format, see the &man.cgetent.3;.</para>
 
 	<para>The simple spooler configuration consists of the following
 	  steps:</para>
 
 	<procedure>
 	  <step>
 	    <para>Pick a name (and a few convenient aliases) for the
 	      printer, and put them in the
 	      <filename>/etc/printcap</filename> file; see the 
 	      <link linkend="printing-naming">Naming the Printer</link>
 	      section for more information on naming.</para>
 	  </step>
 
 	  <indexterm><primary>header pages</primary></indexterm>
 	  <step>
 	    <para>Turn off header pages (which are on by default) by
 	      inserting the <literal>sh</literal> capability; see the
 	      <link linkend="printing-no-header-pages">Suppressing Header
 	      Pages</link> section for more information.</para>
 	  </step>
 
 	  <step>
 	    <para>Make a spooling directory, and specify its location with
 	      the <literal>sd</literal> capability; see the <link
 	      linkend="printing-spooldir">Making the Spooling
 	      Directory</link> section for more information.</para>
 	  </step>
 
 	  <step>
 	    <para>Set the <filename>/dev</filename> entry to use for the
 	      printer, and note it in <filename>/etc/printcap</filename>
 	      with the <literal>lp</literal> capability; see the <link
 	      linkend="printing-device">Identifying the Printer
 	      Device</link> for more information.  Also, if the printer is
 	      on a serial port, set up the communication parameters with
 	      the <literal>fs</literal>, <literal>fc</literal>,
 	      <literal>xs</literal>, and <literal>xc</literal>
 	      capabilities; which is discussed in the <link
 	      linkend="printing-commparam">Configuring Spooler
 	      Communications Parameters</link> section.</para>
 	  </step>
 
 	  <step>
 	    <para>Install a plain text input filter; see the <link
 	    linkend="printing-textfilter">Installing the Text
 	    Filter</link> section for details.</para>
 	  </step>
 
 	  <step>
 	    <para>Test the setup by printing something with the
 	      &man.lpr.1; command.  More details are available in the
 	      <link linkend="printing-trying">Trying It Out</link> and
 	      <link
 	      linkend="printing-troubleshooting">Troubleshooting</link>
 	      sections.</para>
 	  </step>
 	</procedure>
 
 	<note>
 	  <para>Language-based printers, such as PostScript printers,
 	    cannot directly print plain text.  The simple setup outlined
 	    above and described in the following sections assumes that if
 	    you are installing such a printer you will print only files
 	    that the printer can understand.</para>
 	</note>
 
 	<para>Users often expect that they can print plain text to any of
 	  the printers installed on your system.  Programs that interface
 	  to <application>LPD</application> to do their printing usually
 	  make the same assumption.
 	  If you are installing such a printer and want to be able to
 	  print jobs in the printer language <emphasis>and</emphasis>
 	  print plain text jobs, you are strongly urged to add an
 	  additional step to the simple setup outlined above: install an
 	  automatic plain-text-to-PostScript (or other printer language)
 	  conversion program.  The section entitled <link
 	  linkend="printing-advanced-if-conversion">Accommodating Plain
 	  Text Jobs on PostScript Printers</link> tells how to do
 	  this.</para>
 
 	<sect4 id="printing-naming">
 	  <title>Naming the Printer</title>
 
 	  <para>The first (easy) step is to pick a name for your printer
 	    It really does not matter whether you choose functional or
 	    whimsical names since you can also provide a number of aliases
 	    for the printer.</para>
 
 	  <para>At least one of the printers specified in the
 	    <filename>/etc/printcap</filename> should have the alias
 	    <literal>lp</literal>.  This is the default printer's name.
 	    If users do not have the <envar>PRINTER</envar> environment
 	    variable nor specify a printer name on the command line of any
 	    of the <application>LPD</application> commands, 
 	    then <literal>lp</literal> will be the
 	    default printer they get to use.</para>
 
 	  <para>Also, it is common practice to make the last alias for a
 	    printer be a full description of the printer, including make
 	    and model.</para>
 
 	  <para>Once you have picked a name and some common aliases, put
 	    them in the <filename>/etc/printcap</filename> file.  The name
 	    of the printer should start in the leftmost column.  Separate
 	    each alias with a vertical bar and put a colon after the last
 	    alias.</para>
 
 	  <para>In the following example, we start with a skeletal
 	    <filename>/etc/printcap</filename> that defines two printers
 	    (a Diablo 630 line printer and a Panasonic KX-P4455 PostScript
 	    laser printer):</para>
 
 	  <programlisting>#
 #  /etc/printcap for host rose
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:
 
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:</programlisting>
 
 	  <para>In this example, the first printer is named
 	    <literal>rattan</literal> and has as aliases
 	    <literal>line</literal>, <literal>diablo</literal>,
 	    <literal>lp</literal>, and <literal>Diablo 630 Line
 	    Printer</literal>.  Since it has the alias
 	    <literal>lp</literal>, it is also the default printer.  The
 	    second is named <literal>bamboo</literal>, and has as aliases
 	    <literal>ps</literal>, <literal>PS</literal>,
 	    <literal>S</literal>, <literal>panasonic</literal>, and
 	    <literal>Panasonic KX-P4455 PostScript v51.4</literal>.</para>
 	</sect4>
 
 	<sect4 id="printing-no-header-pages">
 	  <title>Suppressing Header Pages</title>
 	  <indexterm>
       <primary>printing</primary>
       <secondary>header pages</secondary>
     </indexterm>
 
 	  <para>The <application>LPD</application> spooling system will 
 	    by default print a
 	    <emphasis>header page</emphasis> for each job.  The header
 	    page contains the user name who requested the job, the host
 	    from which the job came, and the name of the job, in nice
 	    large letters.  Unfortunately, all this extra text gets in the
 	    way of debugging the simple printer setup, so we will suppress
 	    header pages.</para>
 
 	  <para>To suppress header pages, add the <literal>sh</literal>
 	    capability to the entry for the printer in
 	    <filename>/etc/printcap</filename>.  Here is an example
 	    <filename>/etc/printcap</filename> with <literal>sh</literal>
 	    added:</para>
 
 	  <programlisting>#
 #  /etc/printcap for host rose - no header pages anywhere
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :sh:
 
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:</programlisting>
 
 	  <para>Note how we used the correct format: the first line starts
 	    in the leftmost column, and subsequent lines are indented with
 	    a single TAB.  Every line in an entry except the last ends in
 	    a backslash character.</para>
 	</sect4>
 
 	<sect4 id="printing-spooldir">
 	  <title>Making the Spooling Directory</title>
 	  <indexterm><primary>printer spool</primary></indexterm>
 	  <indexterm><primary>print jobs</primary></indexterm>
 
 	  <para>The next step in the simple spooler setup is to make a
 	    <emphasis>spooling directory</emphasis>, a directory where
 	    print jobs reside until they are printed, and where a number
 	    of other spooler support files live.</para>
 
 	  <para>Because of the variable nature of spooling directories, it
 	    is customary to put these directories under
 	    <filename>/var/spool</filename>.  It is not necessary to
 	    backup the contents of spooling directories, either.
 	    Recreating them is as simple as running &man.mkdir.1;.</para>
 
 	  <para>It is also customary to make the directory with a name
 	    that is identical to the name of the printer, as shown
 	    below:</para>
 
 	  <screen>&prompt.root; <userinput>mkdir /var/spool/<replaceable>printer-name</replaceable></userinput></screen>
 
 	  <para>However, if you have a lot of printers on your network,
 	    you might want to put the spooling directories under a single
 	    directory that you reserve just for printing with 
 	    <application>LPD</application>.  We
 	    will do this for our two example printers
 	    <literal>rattan</literal> and
 	    <literal>bamboo</literal>:</para>
 
 	  <screen>&prompt.root; <userinput>mkdir /var/spool/lpd</userinput>
 &prompt.root; <userinput>mkdir /var/spool/lpd/rattan</userinput>
 &prompt.root; <userinput>mkdir /var/spool/lpd/bamboo</userinput></screen>
 
 	  <note>
 	    <para>If you are concerned about the privacy of jobs that
 	      users print, you might want to protect the spooling
 	      directory so it is not publicly accessible.  Spooling
 	      directories should be owned and be readable, writable, and
 	      searchable by user daemon and group daemon, and no one else.
 	      We will do this for our example printers:</para>
 
 	    <screen>&prompt.root; <userinput>chown daemon:daemon /var/spool/lpd/rattan</userinput>
 &prompt.root; <userinput>chown daemon:daemon /var/spool/lpd/bamboo</userinput>
 &prompt.root; <userinput>chmod 770 /var/spool/lpd/rattan</userinput>
 &prompt.root; <userinput>chmod 770 /var/spool/lpd/bamboo</userinput></screen>
 	  </note>
 
 	  <para>Finally, you need to tell <application>LPD</application>
 	    about these directories
 	    using the <filename>/etc/printcap</filename> file.  You
 	    specify the pathname of the spooling directory with the
 	    <literal>sd</literal> capability:</para>
 
 	  <programlisting>#
 #  /etc/printcap for host rose - added spooling directories
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :sh:sd=/var/spool/lpd/rattan:
 
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:sd=/var/spool/lpd/bamboo:</programlisting>
 
 	  <para>Note that the name of the printer starts in the first
 	    column but all other entries describing the printer should be
 	    indented with a tab and each line escaped with a
 	    backslash.</para>
 
 	  <para>If you do not specify a spooling directory with
 	    <literal>sd</literal>, the spooling system will use
 	    <filename>/var/spool/lpd</filename> as a default.</para>
 	</sect4>
 
 	<sect4 id="printing-device">
 	  <title>Identifying the Printer Device</title>
 
 	  <para>In the <link linkend="printing-dev-ports">Adding
 	    <filename>/dev</filename> Entries for the Ports</link>
 	    section, we identified which entry in the
 	    <filename>/dev</filename> directory FreeBSD will use to
 	    communicate with the printer.  Now, we tell 
 	    <application>LPD</application> that
 	    information.  When the spooling system has a job to print, it
 	    will open the specified device on behalf of the filter program
 	    (which is responsible for passing data to the printer).</para>
 
 	  <para>List the <filename>/dev</filename> entry pathname in the
 	    <filename>/etc/printcap</filename> file using the
 	    <literal>lp</literal> capability.</para>
 
 	  <para>In our running example, let us assume that
 	    <literal>rattan</literal> is on the first parallel port, and
 	    <literal>bamboo</literal> is on a sixth serial port; here are
 	    the additions to <filename>/etc/printcap</filename>:</para>
 
 	  <programlisting>#
 #  /etc/printcap for host rose - identified what devices to use
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :sh:sd=/var/spool/lpd/rattan:\
         :lp=/dev/lpt0:
 
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:sd=/var/spool/lpd/bamboo:\
         :lp=/dev/ttyd5:</programlisting>
 
 	  <para>If you do not specify the <literal>lp</literal> capability
 	    for a printer in your <filename>/etc/printcap</filename> file,
 	    <application>LPD</application> uses <filename>/dev/lp</filename>
 	    as a default.
 	    <filename>/dev/lp</filename> currently does not exist in
 	    FreeBSD.</para>
 
 	  <para>If the printer you are installing is connected to a
 	    parallel port, skip to the section entitled, <link
 	    linkend="printing-textfilter">Installing the Text
 	    Filter</link>.  Otherwise, be sure to follow the instructions
 	    in the next section.</para>
 	</sect4>
 
 	<sect4 id="printing-commparam">
 	  <title>Configuring Spooler Communication Parameters</title>
 	  <indexterm>
       <primary>printer</primary>
       <secondary>serial</secondary>
     </indexterm>
 
 	  <para>For printers on serial ports, <application>LPD</application>
 	    can set up the bps rate,
 	    parity, and other serial communication parameters on behalf of
 	    the filter program that sends data to the printer.  This is
 	    advantageous since:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>It lets you try different communication parameters by
 		simply editing the <filename>/etc/printcap</filename>
 		file; you do not have to recompile the filter
 		program.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>It enables the spooling system to use the same filter
 		program for multiple printers which may have different
 		serial communication settings.</para>
 	    </listitem>
 	  </itemizedlist>
 
 	  <para>The following <filename>/etc/printcap</filename>
 	    capabilities control serial communication parameters of the
 	    device listed in the <literal>lp</literal> capability:</para>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term><literal>br#<replaceable>bps-rate</replaceable></literal></term>
 
 	      <listitem>
 		<para>Sets the communications speed of the device to
 		  <replaceable>bps-rate</replaceable>, where
 		  <replaceable>bps-rate</replaceable> can be 50, 75, 110,
 		  134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600,
 		  19200, or 38400 bits-per-second.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><literal>fc#<replaceable>clear-bits</replaceable></literal></term>
 
 	      <listitem>
 		<para>Clears the flag bits
 		  <replaceable>clear-bits</replaceable> in the
 		  <replaceable>sgttyb</replaceable> structure after
 		  opening the device.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><literal>fs#<replaceable>set-bits</replaceable></literal></term>
 
 	      <listitem>
 		<para>Sets the flag bits
 		  <replaceable>set-bits</replaceable> in the
 		  <replaceable>sgttyb</replaceable> structure.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><literal>xc#<replaceable>clear-bits</replaceable></literal></term>
 
 	      <listitem>
 		<para>Clears local mode bits
 		  <replaceable>clear-bits</replaceable> after opening the
 		  device.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
 	      <term><literal>xs#<replaceable>set-bits</replaceable></literal></term>
 
 	      <listitem>
 		<para>Sets local mode bits
 		  <replaceable>set-bits</replaceable>.</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
 
 	  <para>For more information on the bits for the
 	    <literal>fc</literal>, <literal>fs</literal>,
 	    <literal>xc</literal>, and <literal>xs</literal> capabilities,
 	    see the file
 	    <filename>/usr/include/sys/ioctl_compat.h</filename>.</para>
 
 	  <para>When <application>LPD</application> opens the device
 	    specified by the
 	    <literal>lp</literal> capability, it reads the flag bits in
 	    the <literal>sgttyb</literal> structure; it clears any bits in
 	    the <literal>fc</literal> capability, then sets bits in the
 	    <literal>fs</literal> capability, then applies the resultant
 	    setting.  It does the same for the local mode bits as
 	    well.</para>
 
 	  <para>Let us add to our example printer on the sixth serial
 	    port.  We will set the bps rate to 38400.  For the flag bits,
 	    we will set the <literal>TANDEM</literal>,
 	    <literal>ANYP</literal>, <literal>LITOUT</literal>,
 	    <literal>FLUSHO</literal>, and <literal>PASS8</literal> flags.
 	    For the local mode bits, we will set the
 	    <literal>LITOUT</literal> and <literal>PASS8</literal>
 	    flags:</para>
 
 	  <programlisting>bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:sd=/var/spool/lpd/bamboo:\
         :lp=/dev/ttyd5:fs#0x82000c1:xs#0x820:</programlisting>
 	</sect4>
 
 	<sect4 id="printing-textfilter">
 	  <title>Installing the Text Filter</title>
 	  <indexterm><primary>print filters</primary></indexterm>
 
 	  <para>We are now ready to tell <application>LPD</application>
 	    what text filter to use to
 	    send jobs to the printer.  A <emphasis>text filter</emphasis>,
 	    also known as an <emphasis>input filter</emphasis>, is a
 	    program that <application>LPD</application> runs when it 
 	    has a job to print.  When <application>LPD</application>
 	    runs the text filter for a printer, it sets the filter's
 	    standard input to the job to print, and its standard output to
 	    the printer device specified with the <literal>lp</literal>
 	    capability.  The filter is expected to read the job from
 	    standard input, perform any necessary translation for the
 	    printer, and write the results to standard output, which will
 	    get printed.  For more information on the text filter, see
 	    the <link linkend="printing-advanced-filters">Filters</link>
 	    section.</para>
 
 	  <para>For our simple printer setup, the text filter can be a
 	    small shell script that just executes
 	    <command>/bin/cat</command> to send the job to the printer.
 	    FreeBSD comes with another filter called
 	    <filename>lpf</filename> that handles backspacing and
 	    underlining for printers that might not deal with such
 	    character streams well.  And, of course, you can use any other
 	    filter program you want.  The filter <command>lpf</command> is
 	    described in detail in section entitled <link
 	    linkend="printing-advanced-lpf">lpf: a Text
 	    Filter</link>.</para>
 
 	  <para>First, let us make the shell script
 	    <filename>/usr/local/libexec/if-simple</filename> be a simple
 	    text filter.  Put the following text into that file with your
 	    favorite text editor:</para>
 
 	  <programlisting>#!/bin/sh
 #
 # if-simple - Simple text input filter for lpd
 # Installed in /usr/local/libexec/if-simple
 #
 # Simply copies stdin to stdout.  Ignores all filter arguments.
 
 /bin/cat &amp;&amp; exit 0
 exit 2</programlisting>
 
 	  <para>Make the file executable:</para>
 
 	  <screen>&prompt.root; <userinput>chmod 555 /usr/local/libexec/if-simple</userinput></screen>
 
 	  <para>And then tell LPD to use it by specifying it with the
 	    <literal>if</literal> capability in
 	    <filename>/etc/printcap</filename>.  We will add it to the two
 	    printers we have so far in the example
 	    <filename>/etc/printcap</filename>:</para>
 
 	  <programlisting>#
 #  /etc/printcap for host rose - added text filter
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\
         :if=/usr/local/libexec/if-simple:
 
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:sd=/var/spool/lpd/bamboo:\
         :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:\
         :if=/usr/local/libexec/if-simple:</programlisting>
 	</sect4>
 
 	<sect4>
 	  <title>Turn on <application>LPD</application></title>
 
 	  <para>&man.lpd.8; is run from <filename>/etc/rc</filename>,
 	    controlled by the <literal>lpd_enable</literal> variable.  This
 	    variable defaults to <literal>NO</literal>.  If you have not done
 	    so already, add the line:</para>
 
 	  <programlisting>lpd_enable="YES"</programlisting>
 
 	  <para>to <filename>/etc/rc.conf</filename>, and then either restart
 	    your machine, or just run &man.lpd.8;.</para>
 
 	  <screen>&prompt.root; <userinput>lpd</userinput></screen>
 	</sect4>
 	
 	<sect4 id="printing-trying">
 	  <title>Trying It Out</title>
 
 	  <para>You have reached the end of the simple 
 	    <application>LPD</application> setup.
 	    Unfortunately, congratulations are not quite yet in order,
 	    since we still have to test the setup and correct any
 	    problems.  To test the setup, try printing something.  To
 	    print with the <application>LPD</application> system, you 
 	    use the command &man.lpr.1;,
 	    which submits a job for printing.</para>
 
 	  <para>You can combine &man.lpr.1; with the &man.lptest.1;
 	    program, introduced in section <link
 	    linkend="printing-testing">Checking Printer
 	    Communications</link> to generate some test text.</para>
 
 	  <para><emphasis>To test the simple <application>LPD</application>
 	      setup:</emphasis></para>
 
 	  <para>Type:</para>
 
 	  <screen>&prompt.root; <userinput>lptest 20 5 | lpr -P<replaceable>printer-name</replaceable></userinput></screen>
 	  
 	  <para>Where <replaceable>printer-name</replaceable> is a the
 	    name of a printer (or an alias) specified in
 	    <filename>/etc/printcap</filename>.  To test the default
 	    printer, type &man.lpr.1; without any <option>-P</option>
 	    argument.  Again, if you are testing a printer that expects
 	    PostScript, send a PostScript program in that language instead
 	    of using &man.lptest.1;.  You can do so by putting the program
 	    in a file and typing <command>lpr 
 	    <replaceable>file</replaceable></command>.</para>
 
 	  <para>For a PostScript printer, you should get the results of
 	    the program.  If you are using &man.lptest.1;, then your
 	    results should look like the following:</para>
 
 	  <programlisting>!"#$%&amp;'()*+,-./01234
 "#$%&amp;'()*+,-./012345
 #$%&amp;'()*+,-./0123456
 $%&amp;'()*+,-./01234567
 %&amp;'()*+,-./012345678</programlisting>
 
 	  <para>To further test the printer, try downloading larger
 	    programs (for language-based printers) or running
 	    &man.lptest.1; with different arguments.  For example,
 	    <command>lptest 80 60</command> will produce 60 lines of 80
 	    characters each.</para>
 
 	  <para>If the printer did not work, see the <link
 	    linkend="printing-troubleshooting">Troubleshooting</link>
 	    section.</para>
 	</sect4>
       </sect3>
     </sect2>
   </sect1>
   
   <sect1 id="printing-advanced">
     <title>Advanced Printer Setup</title>
     
     <para>This section describes filters for printing specially formatted
       files, header pages, printing across networks, and restricting and
       accounting for printer usage.</para>
 
     <sect2 id="printing-advanced-filter-intro">
       <title>Filters</title>
       <indexterm><primary>print filters</primary></indexterm>
       
       <para>Although <application>LPD</application> handles network protocols,
 	queuing, access control,
         and other aspects of printing, most of the <emphasis>real</emphasis>
         work happens in the <emphasis>filters</emphasis>.  Filters are
         programs that communicate with the printer and handle its device
         dependencies and special requirements.  In the simple printer setup,
         we installed a plain text filter&mdash;an extremely simple one that
         should work with most printers (section <link
           linkend="printing-textfilter">Installing the Text
           Filter</link>).</para>
           
       <para>However, in order to take advantage of format conversion, printer
         accounting, specific printer quirks, and so on, you should understand
         how filters work.  It will ultimately be the filter's responsibility
         to handle these aspects.  And the bad news is that most of the time
         <emphasis>you</emphasis> have to provide filters yourself.  The good
         news is that many are generally available; when they are not, they are
         usually easy to write.</para>
           
       <para>Also, FreeBSD comes with one,
         <filename>/usr/libexec/lpr/lpf</filename>, that works with many
         printers that can print plain text.  (It handles backspacing and tabs
         in the file, and does accounting, but that is about all it does.)
         There are also several filters and filter components in the FreeBSD
         Ports Collection.</para>
           
       <para>Here is what you will find in this section:</para>
       
       <itemizedlist>
         <listitem>
           <para>Section <link linkend="printing-advanced-filters">How Filters
               Work</link>, tries to give an overview of a filter's role in the
             printing process.  You should read this section to get an
             understanding of what is happening <quote>under the hood</quote>
             when <application>LPD</application> uses filters.  This knowledge
 	    could help you anticipate
             and debug problems you might encounter as you install more and
             more filters on each of your printers.</para>
         </listitem>
               
         <listitem>
           <para><application>LPD</application> expects every printer to be 
 	    able to print plain text by
             default.  This presents a problem for PostScript (or other
             language-based printers) which cannot directly print plain text.
             Section <link
               linkend="printing-advanced-if-conversion">Accommodating
               Plain Text Jobs on PostScript Printers</link> tells you what you
             should do to overcome this problem.  You should read this
             section if you have a PostScript printer.</para>
         </listitem>
 
         <listitem>
           <para>PostScript is a popular output format for many programs. Even
             some people (myself included) write PostScript code directly.  But
             PostScript printers are expensive.  Section <link
               linkend="printing-advanced-ps">Simulating PostScript on
               Non-PostScript Printers</link> tells how you can further modify
             a printer's text filter to accept and print PostScript data on a
             <emphasis>non-PostScript</emphasis> printer.  You should read
             this section if you do not have a PostScript printer.</para>
         </listitem>
               
         <listitem>
           <para>Section <link
               linkend="printing-advanced-convfilters">Conversion
               Filters</link> tells about a way you can automate the conversion
             of specific file formats, such as graphic or typesetting data,
             into formats your printer can understand.  After reading this
             section, you should be able to set up your printers such that
             users can type <command>lpr -t</command> to print troff data, or
             <command>lpr -d</command> to print TeX DVI data, or <command>lpr
               -v</command> to print raster image data, and so forth.  I
             recommend reading this section.</para>
         </listitem>
               
         <listitem>
           <para>Section <link linkend="printing-advanced-of">Output
               Filters</link> tells all about a not often used feature of 
 	    <application>LPD</application>:
             output filters.  Unless you are printing header pages (see <link
               linkend="printing-advanced-header-pages">Header Pages</link>),
             you can probably skip that section altogether.</para>
         </listitem>
 
         <listitem>
           <para>Section <link linkend="printing-advanced-lpf">lpf: a Text
               Filter</link> describes <command>lpf</command>, a fairly
             complete if simple text filter for line printers (and laser
             printers that act like line printers) that comes with FreeBSD.  If
             you need a quick way to get printer accounting working for plain
             text, or if you have a printer which emits smoke when it sees
             backspace characters, you should definitely consider
             <command>lpf</command>.</para>
         </listitem>
       </itemizedlist>
       
       <sect3 id="printing-advanced-filters">
         <title>How Filters Work</title>
 
         <para>As mentioned before, a filter is an executable program started
           by <application>LPD</application> to handle the device-dependent part of
 	  communicating with the printer.</para>
             
         <para>When <application>LPD</application> wants to print a file in a 
 	  job, it starts a filter
           program.  It sets the filter's standard input to the file to print,
           its standard output to the printer, and its standard error to the
           error logging file (specified in the <literal>lf</literal>
           capability in <filename>/etc/printcap</filename>, or
           <filename>/dev/console</filename> by default).</para>
             
         <indexterm>
           <primary><command>troff</command></primary>
         </indexterm>
         <para>Which filter <application>LPD</application> starts and the 
 	  filter's arguments depend on
           what is listed in the <filename>/etc/printcap</filename> file and
           what arguments the user specified for the job on the      
             &man.lpr.1; command line.  For example, if the user typed
           <command>lpr -t</command>, <application>LPD</application> would
 	  start the troff filter, listed
           in the <literal>tf</literal> capability for the destination printer.
           If the user wanted to print plain text, it would start the
           <literal>if</literal> filter (this is mostly true: see <link
             linkend="printing-advanced-of">Output Filters</link> for
           details).</para>
 
         <para>There are three kinds of filters you can specify in
           <filename>/etc/printcap</filename>:</para>
 
         <itemizedlist>
           <listitem>
             <para>The <emphasis>text filter</emphasis>, confusingly called the
               <emphasis>input filter</emphasis> in 
 	      <application>LPD</application> documentation, handles
               regular text printing.  Think of it as the default filter.  
 	      <application>LPD</application>
               expects every printer to be able to print plain text by default,
               and it is the text filter's job to make sure backspaces, tabs,
               or other special characters do not confuse the printer.  If you
               are in an environment where you have to account for printer
               usage, the text filter must also account for pages printed,
               usually by counting the number of lines printed and comparing
               that to the number of lines per page the printer supports.  The
               text filter is started with the following argument list:
 
               <cmdsynopsis>
                 <command>filter-name</command>
                 <arg>-c</arg>
                 <arg choice="plain">-w<replaceable>width</replaceable></arg>
                 <arg choice="plain">-l<replaceable>length</replaceable></arg>
                 <arg choice="plain">-i<replaceable>indent</replaceable></arg>
                 <arg choice="plain">-n <replaceable>login</replaceable></arg>
                 <arg choice="plain">-h <replaceable>host</replaceable></arg>
                 <arg choice="plain"><replaceable>acct-file</replaceable></arg>
               </cmdsynopsis>
 
               where
               
               <variablelist>
                 <varlistentry>
                   <term><option>-c</option></term>
 
                   <listitem>
                     <para>appears if the job is submitted with <command>lpr
                         -l</command></para>
                   </listitem>
                 </varlistentry>
                 
                 <varlistentry>
                   <term><replaceable>width</replaceable></term>
                   
                   <listitem>
                     <para>is the value from the <literal>pw</literal> (page
                       width) capability specified in
                       <filename>/etc/printcap</filename>, default 132</para>
                   </listitem>
                 </varlistentry>
                 
                 <varlistentry>
                   <term><replaceable>length</replaceable></term>
                   
                   <listitem>
                     <para>is the value from the <literal>pl</literal> (page
                       length) capability, default 66</para>
                   </listitem>
                 </varlistentry>
                 
                 <varlistentry>
                   <term><replaceable>indent</replaceable></term>
                   
                   <listitem>
                     <para>is the amount of the indentation from <command>lpr
                         -i</command>, default 0</para>
                   </listitem>
                 </varlistentry>
                 
                 <varlistentry>
                   <term><replaceable>login</replaceable></term>
                   
                   <listitem>
                     <para>is the account name of the user printing the
                       file</para>
                   </listitem>
                 </varlistentry>
                 
                 <varlistentry>
                   <term><replaceable>host</replaceable></term>
                   
                   <listitem>
                     <para>is the host name from which the job was
                       submitted</para>
                   </listitem>
                 </varlistentry>
                 
                 <varlistentry>
                   <term><replaceable>acct-file</replaceable></term>
                   
                   <listitem>
                     <para>is the name of the accounting file from the
                       <literal>af</literal> capability.</para>
                   </listitem>
                 </varlistentry>
               </variablelist>
             </para>
           </listitem>
 
 	  <indexterm>
       <primary>printer</primary>
       <secondary>filters</secondary>
     </indexterm>          
           <listitem>
             <para>A <emphasis>conversion filter</emphasis> converts a specific
               file format into one the printer can render onto paper.  For
               example, ditroff typesetting data cannot be directly printed,
               but you can install a conversion filter for ditroff files to
               convert the ditroff data into a form the printer can digest and
               print.  Section <link
                 linkend="printing-advanced-convfilters">Conversion
                 Filters</link> tells all about them. Conversion filters also
               need to do accounting, if you need printer accounting.
               Conversion filters are started with the following arguments:
 
               <cmdsynopsis>
                 <command>filter-name</command>
                 <arg
                   choice="plain">-x<replaceable>pixel-width</replaceable></arg>
                 <arg choice="plain">-y<replaceable>pixel-height</replaceable></arg>
                 <arg choice="plain">-n <replaceable>login</replaceable></arg>
                 <arg choice="plain">-h <replaceable>host</replaceable></arg>
                 <arg choice="plain"><replaceable>acct-file</replaceable></arg>
               </cmdsynopsis>
 
               where <replaceable>pixel-width</replaceable> is the value
               from the <literal>px</literal> capability (default 0) and
               <replaceable>pixel-height</replaceable> is the value from the
               <literal>py</literal> capability (default 0).</para>
           </listitem>
           
           <listitem>
             <para>The <emphasis>output filter</emphasis> is used only if there
               is no text filter, or if header pages are enabled. In my
               experience, output filters are rarely used.  Section <link
                 linkend="printing-advanced-of">Output Filters</link> describe
               them.  There are only two arguments to an output filter:
 
               <cmdsynopsis>
                 <command>filter-name</command>
                 <arg choice="plain">-w<replaceable>width</replaceable></arg>
                 <arg choice="plain">-l<replaceable>length</replaceable></arg>
               </cmdsynopsis>
 
               which are identical to the text filters <option>-w</option> and
               <option>-l</option> arguments.</para>
           </listitem>
         </itemizedlist>
 
         <para>Filters should also <emphasis>exit</emphasis> with the
           following exit status:</para>
             
         <variablelist>
           <varlistentry>
             <term>exit 0</term>
 
             <listitem>
               <para>If the filter printed the file successfully.</para>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term>exit 1</term>
             
             <listitem>
               <para>If the filter failed to print the file but wants 
 		<application>LPD</application> to
                 try to print the file again.  <application>LPD</application>
 		will restart a filter if it exits with this status.</para>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term>exit 2</term>
             
             <listitem>
               <para>If the filter failed to print the file and does not want
                 <application>LPD</application> to try again.  
 		<application>LPD</application> will throw out the file.</para>
             </listitem>
           </varlistentry>
         </variablelist>
 
         <para>The text filter that comes with the FreeBSD release,
           <filename>/usr/libexec/lpr/lpf</filename>, takes advantage of the
           page width and length arguments to determine when to send a form
           feed and how to account for printer usage.  It uses the login, host,
           and accounting file arguments to make the accounting entries.</para>
 
         <para>If you are shopping for filters, see if they are LPD-compatible.
           If they are, they must support the argument lists described above.
           If you plan on writing filters for general use, then have them
           support the same argument lists and exit codes.</para>
       </sect3>
       
       <sect3 id="printing-advanced-if-conversion">
         <title>Accommodating Plain Text Jobs on PostScript Printers</title>
         <indexterm><primary>print jobs</primary></indexterm>
 
         <para>If you are the only user of your computer and PostScript (or
           other language-based) printer, and you promise to never send plain
           text to your printer and to never use features of various programs
           that will want to send plain text to your printer, then you do not
           need to worry about this section at all.</para>
             
         <para>But, if you would like to send both PostScript and plain text
           jobs to the printer, then you are urged to augment your printer
           setup.  To do so, we have the text filter detect if the arriving job
           is plain text or PostScript.  All PostScript jobs must start with
           <literal>%!</literal> (for other printer languages, see your printer
           documentation).  If those are the first two characters in the job,
           we have PostScript, and can pass the rest of the job directly.  If
           those are not the first two characters in the file, then the filter
           will convert the text into PostScript and print the result.</para>
             
         <para>How do we do this?</para>
 
         <indexterm>
           <primary>printer</primary>
           <secondary>serial</secondary>
         </indexterm>
         <para>If you have got a serial printer, a great way to do it is to
           install <command>lprps</command>.  <command>lprps</command> is a
           PostScript printer filter which performs two-way communication with
           the printer.  It updates the printer's status file with verbose
           information from the printer, so users and administrators can see
           exactly what the state of the printer is (such as <errorname>toner
             low</errorname> or <errorname>paper jam</errorname>).  But more
           importantly, it includes a program called <command>psif</command>
           which detects whether the incoming job is plain text and calls
           <command>textps</command> (another program that comes with
           <command>lprps</command>) to convert it to PostScript.  It then uses
           <command>lprps</command> to send the job to the printer.</para>
             
         <para><command>lprps</command> is part of the FreeBSD Ports Collection
           (see <link linkend="ports">The Ports Collection</link>).  You can
           fetch, build and install it yourself, of course.  After installing
           <command>lprps</command>, just specify the pathname to the
           <command>psif</command> program that is part of
           <command>lprps</command>.  If you installed <command>lprps</command>
           from the ports collection, use the following in the serial
           PostScript printer's entry in
           <filename>/etc/printcap</filename>:</para>
               
         <programlisting>:if=/usr/local/libexec/psif:</programlisting>
 
         <para>You should also specify the <literal>rw</literal> capability;
           that tells <application>LPD</application> to open the printer in 
 	  read-write mode.</para>
             
         <para>If you have a parallel PostScript printer (and therefore cannot
           use two-way communication with the printer, which
           <command>lprps</command> needs), you can use the following shell
           script as the text filter:</para>
 
         <programlisting>#!/bin/sh
 #
 #  psif - Print PostScript or plain text on a PostScript printer
 #  Script version; NOT the version that comes with lprps
 #  Installed in /usr/local/libexec/psif
 #
 
 IFS="" read -r first_line
 first_two_chars=`expr "$first_line" : '\(..\)'`
 
 if [ "$first_two_chars" = "%!" ]; then
     #
     #  PostScript job, print it.
     #
     echo "$first_line" &amp;&amp; cat &amp;&amp; printf "\004" &amp;&amp; exit 0
     exit 2
 else
     #
     #  Plain text, convert it, then print it.
     #
     ( echo "$first_line"; cat ) | /usr/local/bin/textps &amp;&amp; printf "\004" &amp;&amp; exit 0
     exit 2
 fi</programlisting>
             
         <para>In the above script, <command>textps</command> is a program we
           installed separately to convert plain text to PostScript.  You can
           use any text-to-PostScript program you wish.  The FreeBSD Ports
           Collection (see <link linkend="ports">The Ports Collection</link>)
           includes a full featured text-to-PostScript program called
           <literal>a2ps</literal> that you might want to investigate.</para>
       </sect3>
           
       <sect3 id="printing-advanced-ps">
         <title>Simulating PostScript on Non-PostScript Printers</title>
         <indexterm>
           <primary>PostScript</primary>
           <secondary>emulating</secondary>
         </indexterm>
         <indexterm>
           <primary>Ghostscript</primary></indexterm>
         <para>PostScript is the <emphasis>de facto</emphasis> standard for
           high quality typesetting and printing.  PostScript is, however, an
           <emphasis>expensive</emphasis> standard. Thankfully, Alladin
           Enterprises has a free PostScript work-alike called
           <application>Ghostscript</application> that runs with FreeBSD.
           Ghostscript can read most PostScript files and can render their
           pages onto a variety of devices, including many brands of
           non-PostScript printers.  By installing Ghostscript and using a
           special text filter for your printer, you can make your
           non-PostScript printer act like a real PostScript printer.</para>
             
         <para>Ghostscript is in the FreeBSD Ports Collection, if you
           would like to install it from there.  You can fetch, build, and
           install it quite easily yourself, as well.</para>
             
         <para>To simulate PostScript, we have the text filter detect if it is
           printing a PostScript file.  If it is not, then the filter will pass
           the file directly to the printer; otherwise, it will use Ghostscript
           to first convert the file into a format the printer will
           understand.</para>
             
         <para>Here is an example: the following script is a text filter
           for Hewlett Packard DeskJet 500 printers.  For other printers,
           substitute the <option>-sDEVICE</option> argument to the
           <command>gs</command> (Ghostscript) command.  (Type <command>gs
             -h</command> to get a list of devices the current installation of
           Ghostscript supports.)</para>
 
         <programlisting>#!/bin/sh
 #
 #  ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500
 #  Installed in /usr/local/libexec/hpif
 
 #
 #  Treat LF as CR+LF:
 #
 printf "\033&amp;k2G" || exit 2
 
 #
 #  Read first two characters of the file
 #
 IFS="" read -r first_line
 first_two_chars=`expr "$first_line" : '\(..\)'`
 
 if [ "$first_two_chars" = "%!" ]; then
     #
     #  It is PostScript; use Ghostscript to scan-convert and print it.
     #
     #  Note that PostScript files are actually interpreted programs,
     #  and those programs are allowed to write to stdout, which will
     #  mess up the printed output.  So, we redirect stdout to stderr
     #  and then make descriptor 3 go to stdout, and have Ghostscript
     #  write its output there.  Exercise for the clever reader:
     #  capture the stderr output from Ghostscript and mail it back to
     #  the user originating the print job.
     #
     exec 3&gt;&amp;1 1&gt;&amp;2
     /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \
         -sOutputFile=/dev/fd/3 - &amp;&amp; exit 0
 
     #
     /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 -sOutputFile=- - \
         &amp;&amp; exit 0
 else
     #
     #  Plain text or HP/PCL, so just print it directly; print a form feed
     #  at the end to eject the last page.
     #
     echo "$first_line" &amp;&amp; cat &amp;&amp; printf "\033&amp;l0H" &amp;&amp; 
 exit 0
 fi
 
 exit 2</programlisting>
 
         <para>Finally, you need to notify <application>LPD</application> of 
 	  the filter via the <literal>if</literal> capability:</para>
             
         <programlisting>:if=/usr/local/libexec/ifhp:</programlisting>
 
         <para>That is it.  You can type <command>lpr plain.text</command> and
           <filename>lpr whatever.ps</filename> and both should print
           successfully.</para>
       </sect3>
       
       <sect3 id="printing-advanced-convfilters">
         <title>Conversion Filters</title>
 
         <para>After completing the simple setup described in <link
             linkend="printing-simple">Simple Printer Setup</link>, the first
           thing you will probably want to do is install conversion filters for
           your favorite file formats (besides plain ASCII text).</para>
             
         <sect4>
           <title>Why Install Conversion Filters?</title>
           <indexterm>
             <primary>TeX</primary>
             <secondary>printing dvi files</secondary>
           </indexterm>
           
           <para>Conversion filters make printing various kinds of files easy.
             As an example, suppose we do a lot of work with the TeX
             typesetting system, and we have a PostScript printer.  Every time
             we generate a DVI file from TeX, we cannot print it directly until
             we convert the DVI file into PostScript.  The command sequence
             goes like this:</para>
                 
           <screen>&prompt.user; <userinput>dvips seaweed-analysis.dvi</userinput>
 &prompt.user; <userinput>lpr seaweed-analysis.ps</userinput></screen>
                 
           <para>By installing a conversion filter for DVI files, we can skip
             the hand conversion step each time by having 
 	    <application>LPD</application> do it for us.
             Now, each time we get a DVI file, we are just one step away from
             printing it:</para>
               
           <screen>&prompt.user; <userinput>lpr -d seaweed-analysis.dvi</userinput></screen>
                 
           <para>We got <application>LPD</application> to do the DVI file 
 	    conversion for us by specifying
             the <option>-d</option> option.  Section <link
               linkend="printing-lpr-options-format">Formatting and Conversion
               Options</link> lists the conversion options.</para>
               
           <para>For each of the conversion options you want a printer to
             support, install a <emphasis>conversion filter</emphasis> and
             specify its pathname in <filename>/etc/printcap</filename>.  A
             conversion filter is like the text filter for the simple printer
             setup (see section <link linkend="printing-textfilter">Installing
               the Text Filter</link>) except that instead of printing plain
             text, the filter converts the file into a format the printer can
             understand.</para>
         </sect4>
 
         <sect4>
           <title>Which Conversions Filters Should I Install?</title>
           
           <para>You should install the conversion filters you expect to use.
             If you print a lot of DVI data, then a DVI conversion filter is in
             order.  If you have got plenty of troff to print out, then you
             probably want a troff filter.</para>
               
           <para>The following table summarizes the filters that 
 	    <application>LPD</application> works
             with, their capability entries for the
             <filename>/etc/printcap</filename> file, and how to invoke them
             with the <command>lpr</command> command:</para>
 
           <informaltable frame="none">
             <tgroup cols="3">
               <thead>
                 <row>
                   <entry>File type</entry>
                   <entry><filename>/etc/printcap</filename> capability</entry>
                   <entry><command>lpr</command> option</entry>
                 </row>
               </thead>
               
               <tbody>
                 <row>
                   <entry>cifplot</entry>
                   <entry><literal>cf</literal></entry>
                   <entry><option>-c</option></entry>
                 </row>
                 
                 <row>
                   <entry>DVI</entry>
                   <entry><literal>df</literal></entry>
                   <entry><option>-d</option></entry>
                 </row>
                 
                 <row>
                   <entry>plot</entry>
                   <entry><literal>gf</literal></entry>
                   <entry><option>-g</option></entry>
                 </row>
                 
                 <row>
                   <entry>ditroff</entry>
                   <entry><literal>nf</literal></entry>
                   <entry><option>-n</option></entry>
                 </row>
                 
                 <row>
                   <entry>FORTRAN text</entry>
                   <entry><literal>rf</literal></entry>
                   <entry><option>-f</option></entry>
                 </row>
                 
                 <row>
                   <entry>troff</entry>
                   <entry><literal>rf</literal></entry>
                   <entry><option>-f</option></entry>
                 </row>
                 
                 <row>
                   <entry>raster</entry>
                   <entry><literal>vf</literal></entry>
                   <entry><option>-v</option></entry>
                 </row>
                 
                 <row>
                   <entry>plain text</entry>
                   <entry><literal>if</literal></entry>
                   <entry>none, <option>-p</option>, or
                     <option>-l</option></entry>
                 </row>
               </tbody>
             </tgroup>
           </informaltable>
           
           <para>In our example, using <command>lpr -d</command> means the
             printer needs a <literal>df</literal> capability in its entry in
             <filename>/etc/printcap</filename>.</para>
               
           <indexterm><primary>fortran</primary></indexterm>
           <para>Despite what others might contend, formats like FORTRAN text
             and plot are probably obsolete.  At your site, you can give new
             meanings to these or any of the formatting options just by
             installing custom filters.  For example, suppose you would like to
             directly print Printerleaf files (files from the Interleaf desktop
             publishing program), but will never print plot files.  You could
             install a Printerleaf conversion filter under the
             <literal>gf</literal> capability and then educate your users that
             <command>lpr -g</command> mean <quote>print Printerleaf
             files.</quote></para>
         </sect4>
 
         <sect4>
           <title>Installing Conversion Filters</title>
           
           <para>Since conversion filters are programs you install outside of
             the base FreeBSD installation, they should probably go under
             <filename>/usr/local</filename>.  The directory
             <filename>/usr/local/libexec</filename> is a popular location,
             since they are specialized programs that only 
 	    <application>LPD</application> will run;
             regular users should not ever need to run them.</para>
               
           <para>To enable a conversion filter, specify its pathname under the
             appropriate capability for the destination printer in
             <filename>/etc/printcap</filename>.</para>
               
           <para>In our example, we will add the DVI conversion filter to the
             entry for the printer named <literal>bamboo</literal>.  Here is
             the example <filename>/etc/printcap</filename> file again, with
             the new <literal>df</literal> capability for the printer
             <literal>bamboo</literal>.</para>
 
           <programlisting>#
 #  /etc/printcap for host rose - added df filter for bamboo
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :sh:sd=/var/spool/lpd/rattan:\
         :lp=/dev/lpt0:\
         :if=/usr/local/libexec/if-simple:
 
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:sd=/var/spool/lpd/bamboo:\
         :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
         :if=/usr/local/libexec/psif:\
         :df=/usr/local/libexec/psdf:</programlisting>
 
           <para>The DVI filter is a shell script named
             <filename>/usr/local/libexec/psdf</filename>.  Here is that
             script:</para>
 
           <programlisting>#!/bin/sh
 #
 #  psdf - DVI to PostScript printer filter
 #  Installed in /usr/local/libexec/psdf
 #
 # Invoked by lpd when user runs lpr -d
 #
 exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"</programlisting>
 
           <para>This script runs <command>dvips</command> in filter mode (the
             <option>-f</option> argument) on standard input, which is the job
             to print.  It then starts the PostScript printer filter
             <command>lprps</command> (see section <link
               linkend="printing-advanced-if-conversion">Accommodating Plain
               Text Jobs on PostScript Printers</link>) with the arguments 
 	    <application>LPD</application>
             passed to this script. <command>lprps</command> will use those
             arguments to account for the pages printed.</para>
         </sect4>
             
         <sect4>
           <title>More Conversion Filter Examples</title>
               
           <para>Since there is no fixed set of steps to install conversion
             filters, let me instead provide more examples.  Use these as
             guidance to making your own filters.  Use them directly, if
             appropriate.</para>
               
           <para>This example script is a raster (well, GIF file, actually)
             conversion filter for a Hewlett Packard LaserJet III-Si
             printer:</para>
 
           <programlisting>#!/bin/sh
 #
 #  hpvf - Convert GIF files into HP/PCL, then print
 #  Installed in /usr/local/libexec/hpvf
                   
 PATH=/usr/X11R6/bin:$PATH; export PATH
 giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \
     &amp;&amp; exit 0 \
     || exit 2</programlisting>
 
           <para>It works by converting the GIF file into a portable anymap,
             converting that into a portable graymap, converting that into a
             portable bitmap, and converting that into LaserJet/PCL-compatible
             data.</para>
               
           <para>Here is the <filename>/etc/printcap</filename> file with an
             entry for a printer using the above filter:</para>
 
           <programlisting>#
 #  /etc/printcap for host orchid
 #
 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
         :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\
         :if=/usr/local/libexec/hpif:\
         :vf=/usr/local/libexec/hpvf:</programlisting>
               
           <para>The following script is a conversion filter for troff data
             from the groff typesetting system for the PostScript printer named
             <literal>bamboo</literal>:</para>
 
           <programlisting>#!/bin/sh
 #
 #  pstf - Convert groff's troff data into PS, then print.
 #  Installed in /usr/local/libexec/pstf
 #
 exec grops | /usr/local/libexec/lprps "$@"</programlisting>
               
           <para>The above script makes use of <command>lprps</command> again
             to handle the communication with the printer.  If the printer were
             on a parallel port, we would use this script instead:</para>
 
           <programlisting>#!/bin/sh
 #
 #  pstf - Convert groff's troff data into PS, then print.
 #  Installed in /usr/local/libexec/pstf
 #
 exec grops</programlisting>
           
           <para>That is it.  Here is the entry we need to add to
             <filename>/etc/printcap</filename> to enable the filter:</para>
                 
           <programlisting>:tf=/usr/local/libexec/pstf:</programlisting>
               
           <para>Here is an example that might make old hands at FORTRAN blush.
             It is a FORTRAN-text filter for any printer that can directly
             print plain text.  We will install it for the printer
             <literal>teak</literal>:</para>
 
           <programlisting>#!/bin/sh
 #
 # hprf - FORTRAN text filter for LaserJet 3si:
 # Installed in /usr/local/libexec/hprf
 #
 
 printf "\033&amp;k2G" &amp;&amp; fpr &amp;&amp; printf "\033&amp;l0H" &amp;&amp;
  exit 0
 exit 2</programlisting>
               
           <para>And we will add this line to the
             <filename>/etc/printcap</filename> for the printer
             <literal>teak</literal> to enable this filter:</para>
               
           <programlisting>:rf=/usr/local/libexec/hprf:</programlisting>
               
           <para>Here is one final, somewhat complex example.  We will add a
             DVI filter to the LaserJet printer <literal>teak</literal>
             introduced earlier.  First, the easy part: updating
             <filename>/etc/printcap</filename> with the location of the DVI
             filter:</para>
               
           <programlisting>:df=/usr/local/libexec/hpdf:</programlisting>
               
           <para>Now, for the hard part: making the filter.  For that, we need
             a DVI-to-LaserJet/PCL conversion program.  The FreeBSD Ports
             Collection (see <link linkend="ports">The Ports Collection</link>)
             has one: <command>dvi2xx</command> is the name of the package.
             Installing this package gives us the program we need,
             <command>dvilj2p</command>, which converts DVI into LaserJet IIp,
             LaserJet III, and LaserJet 2000 compatible codes.</para>
               
           <para><command>dvilj2p</command> makes the filter
             <command>hpdf</command> quite complex since
             <command>dvilj2p</command> cannot read from standard input.  It
             wants to work with a filename. What is worse, the filename has to
             end in <filename>.dvi</filename> so using
             <filename>/dev/fd/0</filename> for standard input is problematic.
             We can get around that problem by linking (symbolically) a
             temporary file name (one that ends in <filename>.dvi</filename>)
             to <filename>/dev/fd/0</filename>, thereby forcing
             <command>dvilj2p</command> to read from standard input.</para>
               
           <para>The only other fly in the ointment is the fact that we cannot
             use <filename>/tmp</filename> for the temporary link. Symbolic
             links are owned by user and group <username>bin</username>.  The
             filter runs as user <username>daemon</username>.  And the
             <filename>/tmp</filename> directory has the sticky bit set. The
             filter can create the link, but it will not be able clean up when
             done and remove it since the link will belong to a different
             user.</para>
               
           <para>Instead, the filter will make the symbolic link in the current
             working directory, which is the spooling directory (specified by
             the <literal>sd</literal> capability in
             <filename>/etc/printcap</filename>).  This is a perfect place for
             filters to do their work, especially since there is (sometimes)
             more free disk space in the spooling directory than under
             <filename>/tmp</filename>.</para>
               
           <para>Here, finally, is the filter:</para>
 
           <programlisting>#!/bin/sh
 #
 #  hpdf - Print DVI data on HP/PCL printer
 #  Installed in /usr/local/libexec/hpdf
 
 PATH=/usr/local/bin:$PATH; export PATH
 
 #
 #  Define a function to clean up our temporary files.  These exist
 #  in the current directory, which will be the spooling directory
 #  for the printer.
 #
 cleanup() {
    rm -f hpdf$$.dvi
 }
 
 #
 #  Define a function to handle fatal errors: print the given message
 #  and exit 2.  Exiting with 2 tells LPD to do not try to reprint the
 #  job.
 #
 fatal() {
     echo "$@" 1&gt;&amp;2
     cleanup
     exit 2
 }
 
 #
 #  If user removes the job, LPD will send SIGINT, so trap SIGINT
 #  (and a few other signals) to clean up after ourselves.
 #
 trap cleanup 1 2 15 
 
 #
 #  Make sure we are not colliding with any existing files.
 #
 cleanup
 
 #
 #  Link the DVI input file to standard input (the file to print).
 #
 ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0"
 
 #
 #  Make LF = CR+LF
 #
 printf "\033&amp;k2G" || fatal "Cannot initialize printer"
 
 # 
 #  Convert and print.  Return value from dvilj2p does not seem to be
 #  reliable, so we ignore it.
 #
 dvilj2p -M1 -q -e- dfhp$$.dvi
 
 #
 #  Clean up and exit
 #
 cleanup
 exit 0</programlisting>
         </sect4>
 
         <sect4 id="printing-advanced-autoconv">
           <title>Automated Conversion: An Alternative To Conversion
             Filters</title>
               
           <para>All these conversion filters accomplish a lot for your
             printing environment, but at the cost forcing the user to specify
             (on the &man.lpr.1; command line) which one to use.
             If your users are not particularly computer literate, having to
             specify a filter option will become annoying.  What is worse,
             though, is that an incorrectly specified filter option may run a
             filter on the wrong type of file and cause your printer to spew
             out hundreds of sheets of paper.</para>
               
           <para>Rather than install conversion filters at all, you might want
             to try having the text filter (since it is the default filter)
             detect the type of file it has been asked to print and then
             automatically run the right conversion filter.  Tools such as
             <command>file</command> can be of help here.  Of course, it will
             be hard to determine the differences between
             <emphasis>some</emphasis> file types&mdash;and, of course, you can
             still provide conversion filters just for them.</para>
               
           <indexterm><primary>apsfilter</primary></indexterm>
           <indexterm>
             <primary>printer</primary>
             <secondary>filters</secondary>
             <tertiary>apsfilter</tertiary>
           </indexterm>
           <para>The FreeBSD Ports Collection has a text filter that performs
             automatic conversion called <command>apsfilter</command>.  It can
             detect plain text, PostScript, and DVI files, run the proper
             conversions, and print.</para>
         </sect4>
       </sect3>
       
       <sect3 id="printing-advanced-of">
         <title>Output Filters</title>
 
         <para>The <application>LPD</application> spooling system supports one 
 	  other type of filter that
           we have not yet explored: an output filter.  An output filter is
           intended for printing plain text only, like the text filter, but
           with many simplifications.  If you are using an output filter but no
           text filter, then:</para>
 
         <itemizedlist>
           <listitem>
             <para><application>LPD</application> starts an output filter once
 	      for the entire job instead
               of once for each file in the job.</para>
           </listitem>
           
           <listitem>
             <para><application>LPD</application> does not make any provision
 	      to identify the start or the
               end of files within the job for the output filter.</para>
           </listitem>
           
           <listitem>
             <para><application>LPD</application> does not pass the user's 
 	      login or host to the filter, so
               it is not intended to do accounting.  In fact, it gets only two
               arguments:</para>
                     
             <cmdsynopsis>
               <command>filter-name</command>
               <arg choice="plain">-w<replaceable>width</replaceable></arg>
               <arg choice="plain">-l<replaceable>length</replaceable></arg>
             </cmdsynopsis>
             
             <para>Where <replaceable>width</replaceable> is from the
               <literal>pw</literal> capability and
               <replaceable>length</replaceable> is from the
               <literal>pl</literal> capability for the printer in
               question.</para>
           </listitem>
         </itemizedlist>
 
         <para>Do not be seduced by an output filter's simplicity.  If you
           would like each file in a job to start on a different page an output
           filter <emphasis>will not work</emphasis>.  Use a text filter (also
           known as an input filter); see section <link
             linkend="printing-textfilter">Installing the Text Filter</link>.
           Furthermore, an output filter is actually <emphasis>more
             complex</emphasis> in that it has to examine the byte stream being
           sent to it for special flag characters and must send signals to
           itself on behalf of <application>LPD</application>.</para>
             
         <para>However, an output filter is <emphasis>necessary</emphasis> if
           you want header pages and need to send escape sequences or other
           initialization strings to be able to print the header page.  (But it
           is also <emphasis>futile</emphasis> if you want to charge header
           pages to the requesting user's account, since 
 	  <application>LPD</application> does not give any
           user or host information to the output filter.)</para>
             
         <para>On a single printer, <application>LPD</application>
 	  allows both an output filter and text or other filters.  In
 	  such cases, <application>LPD</application> will start the
 	  output filter
           to print the header page (see section <link
             linkend="printing-advanced-header-pages">Header Pages</link>)
           only.  <application>LPD</application> then expects the
 	  output filter to <emphasis>stop
             itself</emphasis> by sending two bytes to the filter: ASCII 031
           followed by ASCII 001.  When an output filter sees these two bytes
           (031, 001), it should stop by sending <literal>SIGSTOP</literal>
 	  to itself.  When 
 	  <application>LPD</application>'s
           done running other filters, it will restart the output filter by
           sending <literal>SIGCONT</literal> to it.</para>
             
         <para>If there is an output filter but <emphasis>no</emphasis> text
           filter and <application>LPD</application> is working on a plain
 	  text job, <application>LPD</application> uses the output
           filter to do the job.  As stated before, the output filter will
           print each file of the job in sequence with no intervening form
           feeds or other paper advancement, and this is probably
           <emphasis>not</emphasis> what you want.  In almost all cases, you
           need a text filter.</para>
             
         <para>The program <command>lpf</command>, which we introduced earlier
           as a text filter, can also run as an output filter.  If you need a
           quick-and-dirty output filter but do not want to write the byte
           detection and signal sending code, try <command>lpf</command>.  You
           can also wrap <command>lpf</command> in a shell script to handle any
           initialization codes the printer might require.</para>
       </sect3>
       
       <sect3 id="printing-advanced-lpf">
         <title><command>lpf</command>: a Text Filter</title>
 
         <para>The program <filename>/usr/libexec/lpr/lpf</filename> that comes
           with FreeBSD binary distribution is a text filter (input filter)
           that can indent output (job submitted with <command>lpr
             -i</command>), allow literal characters to pass (job submitted
           with <command>lpr -l</command>), adjust the printing position for
           backspaces and tabs in the job, and account for pages printed.  It
           can also act like an output filter.</para>
             
         <para><command>lpf</command> is suitable for many printing
           environments.  And although it has no capability to send
           initialization sequences to a printer, it is easy to write a shell
           script to do the needed initialization and then execute
           <command>lpf</command>.</para>
             
         <indexterm><primary>page accounting</primary></indexterm>
         <indexterm>
           <primary>accounting</primary>
           <secondary>printer</secondary>
         </indexterm>
         <para>In order for <command>lpf</command> to do page accounting
           correctly, it needs correct values filled in for the
           <literal>pw</literal> and <literal>pl</literal> capabilities in the
           <filename>/etc/printcap</filename> file.  It uses these values to
           determine how much text can fit on a page and how many pages were in
           a user's job.  For more information on printer accounting, see <link
             linkend="printing-advanced-acct">Accounting for Printer
             Usage</link>.</para>
       </sect3>
     </sect2>
     
     <sect2 id="printing-advanced-header-pages">
       <title>Header Pages</title>
       
       <para>If you have <emphasis>lots</emphasis> of users, all of them using
         various printers, then you probably want to consider <emphasis>header
           pages</emphasis> as a necessary evil.</para>
           
       <indexterm>
         <primary>banner pages</primary>
 	<see>header pages</see>
       </indexterm>
       <indexterm><primary>header pages</primary></indexterm>
       <para>Header pages, also known as <emphasis>banner</emphasis> or
         <emphasis>burst pages</emphasis> identify to whom jobs belong after
         they are printed.  They are usually printed in large, bold letters,
         perhaps with decorative borders, so that in a stack of printouts they
         stand out from the real documents that comprise users' jobs.  They
         enable users to locate their jobs quickly.  The obvious drawback to a
         header page is that it is yet one more sheet that has to be printed
         for every job, their ephemeral usefulness lasting not more than a few
         minutes, ultimately finding themselves in a recycling bin or rubbish
         heap.  (Note that header pages go with each job, not each file in a
         job, so the paper waste might not be that bad.)</para>
           
       <para>The <application>LPD</application> system can provide header
 	pages automatically for your
         printouts <emphasis>if</emphasis> your printer can directly print
        plain text.  If you have a PostScript printer, you will need an
         external program to generate the header page; see <link
           linkend="printing-advanced-header-pages-ps">Header Pages on
           PostScript Printers</link>.</para>
       
           <sect3 id="printing-advanced-header-pages-enabling">
         <title>Enabling Header Pages</title>
 
         <para>In the <link linkend="printing-simple">Simple Printer
             Setup</link> section, we turned off header pages by specifying
           <literal>sh</literal> (meaning <quote>suppress header</quote>) in the
           <filename>/etc/printcap</filename> file.  To enable header pages for
           a printer, just remove the <literal>sh</literal> capability.</para>
 
         <para>Sounds too easy, right?</para>
 
         <para>You are right.  You <emphasis>might</emphasis> have to provide
           an output filter to send initialization strings to the printer.
           Here is an example output filter for Hewlett Packard PCL-compatible
           printers:</para>
 
         <programlisting>#!/bin/sh
 #
 #  hpof - Output filter for Hewlett Packard PCL-compatible printers
 #  Installed in /usr/local/libexec/hpof
 
 printf "\033&amp;k2G" || exit 2
 exec /usr/libexec/lpr/lpf</programlisting>
             
         <para>Specify the path to the output filter in the
           <literal>of</literal> capability.  See the <link
             linkend="printing-advanced-of">Output Filters</link> section for more
           information.</para>
             
         <para>Here is an example <filename>/etc/printcap</filename> file for
           the printer <literal>teak</literal> that we introduced earlier; we
           enabled header pages and added the above output filter:</para>
 
         <programlisting>#
 #  /etc/printcap for host orchid
 #
 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
         :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
         :if=/usr/local/libexec/hpif:\
         :vf=/usr/local/libexec/hpvf:\
         :of=/usr/local/libexec/hpof:</programlisting>
             
         <para>Now, when users print jobs to <literal>teak</literal>, they get
           a header page with each job.  If users want to spend time searching
           for their printouts, they can suppress header pages by submitting
           the job with <command>lpr -h</command>; see the <link
             linkend="printing-lpr-options-misc">Header Page Options</link> section for
           more &man.lpr.1; options.</para>
 
         <note>
           <para><application>LPD</application> prints a form feed character
 	    after the header page. If
             your printer uses a different character or sequence of characters
             to eject a page, specify them with the <literal>ff</literal>
             capability in <filename>/etc/printcap</filename>.</para>
         </note>
       </sect3>
       
       <sect3 id="printing-advanced-header-pages-controlling">
         <title>Controlling Header Pages</title>
 
         <para>By enabling header pages, <application>LPD</application> will
 	  produce a <emphasis>long
             header</emphasis>, a full page of large letters identifying the
           user, host, and job.  Here is an example (kelly printed the job
           named outline from host <hostid>rose</hostid>):</para>
             
         <programlisting>      k                   ll       ll
       k                    l        l
       k                    l        l
       k   k     eeee       l        l     y    y
       k  k     e    e      l        l     y    y
       k k      eeeeee      l        l     y    y
       kk k     e           l        l     y    y
       k   k    e    e      l        l     y   yy
       k    k    eeee      lll      lll     yyy y
                                                y
                                           y    y
                                            yyyy
 
 
                                    ll
                           t         l        i
                           t         l
        oooo    u    u   ttttt       l       ii     n nnn     eeee
       o    o   u    u     t         l        i     nn   n   e    e
       o    o   u    u     t         l        i     n    n   eeeeee
       o    o   u    u     t         l        i     n    n   e
       o    o   u   uu     t  t      l        i     n    n   e    e
        oooo     uuu u      tt      lll      iii    n    n    eeee
 
 
 
 
 
 
 
 
 
       r rrr     oooo     ssss     eeee
       rr   r   o    o   s    s   e    e
       r        o    o    ss      eeeeee
       r        o    o      ss    e
       r        o    o   s    s   e    e
       r         oooo     ssss     eeee
 
 
 
 
 
 
 
                                               Job:  outline
                                               Date: Sun Sep 17 11:04:58 1995</programlisting>
 
         <para><application>LPD</application> appends a form feed after this
 	  text so the job starts on a
           new page (unless you have <literal>sf</literal> (suppress form
           feeds) in the destination printer's entry in
           <filename>/etc/printcap</filename>).</para>
             
         <para>If you prefer, <application>LPD</application> can make a 
 	  <emphasis>short header</emphasis>;
           specify <literal>sb</literal> (short banner) in the
           <filename>/etc/printcap</filename> file. The header page will look
           like this:</para>
             
         <programlisting>rose:kelly  Job: outline  Date: Sun Sep 17 11:07:51 1995</programlisting>
 
         <para>Also by default, <application>LPD</application> prints the
 	  header page first, then the job.
           To reverse that, specify <literal>hl</literal> (header last) in
           <filename>/etc/printcap</filename>.</para>
       </sect3>
       
       <sect3 id="printing-advanced-header-pages-accounting">
         <title>Accounting for Header Pages</title>
 
         <para>Using <application>LPD</application>'s built-in header pages
 	  enforces a particular paradigm
           when it comes to printer accounting: header pages must be
           <emphasis>free of charge</emphasis>.</para>
             
         <para>Why?</para>
 
         <para>Because the output filter is the only external program that will
           have control when the header page is printed that could do
           accounting, and it is not provided with any <emphasis>user or
             host</emphasis> information or an accounting file, so it has no
           idea whom to charge for printer use.  It is also not enough to just
           <quote>add one page</quote> to the text filter or any of the
           conversion filters (which do have user and host information) since
           users can suppress header pages with <command>lpr -h</command>.
           They could still be charged for header pages they did not print.
           Basically, <command>lpr -h</command> will be the preferred option of
           environmentally-minded users, but you cannot offer any incentive to
           use it.</para>
             
         <para>It is <emphasis>still not enough</emphasis> to have each of the
           filters generate their own header pages (thereby being able to
           charge for them).  If users wanted the option of suppressing the
           header pages with <command>lpr -h</command>, they will still get
           them and be charged for them since <application>LPD</application>
 	  does not pass any knowledge
           of the <option>-h</option> option to any of the filters.</para>
 
         <para>So, what are your options?</para>
 
         <para>You can:</para>
 
         <itemizedlist>
           <listitem>
             <para>Accept <application>LPD</application>'s paradigm and make
 	      header pages free.</para>
           </listitem>
           
           <listitem>
             <para>Install an alternative to <application>LPD</application>,
 	      such as 
 		<application>LPRng</application>. Section
               <link linkend="printing-lpd-alternatives">Alternatives to the
                 Standard Spooler</link> tells more about other spooling
               software you can substitute for <application>LPD</application>.
 	    </para>
           </listitem>
           
           <listitem>
             <para>Write a <emphasis>smart</emphasis> output filter. Normally,
               an output filter is not meant to do anything more than
               initialize a printer or do some simple character conversion.  It
               is suited for header pages and plain text jobs (when there is no
               text (input) filter).  But, if there is a text filter for the
               plain text jobs, then <application>LPD</application> will start
 	      the output filter only for
               the header pages.  And the output filter can parse the header
               page text that <application>LPD</application> generates to
 	      determine what user and host to
               charge for the header page.  The only other problem with this
               method is that the output filter still does not know what
               accounting file to use (it is not passed the name of the file
               from the <literal>af</literal> capability), but if you have a
               well-known accounting file, you can hard-code that into the
               output filter.  To facilitate the parsing step, use the
               <literal>sh</literal> (short header) capability in
               <filename>/etc/printcap</filename>.  Then again, all that might
               be too much trouble, and users will certainly appreciate the
               more generous system administrator who makes header pages
               free.</para>
           </listitem>
         </itemizedlist>
       </sect3>
       
       <sect3 id="printing-advanced-header-pages-ps">
         <title>Header Pages on PostScript Printers</title>
 
         <para>As described above, <application>LPD</application> can generate
 	  a plain text header page
           suitable for many printers.  Of course, PostScript cannot directly
           print plain text, so the header page feature of 
 	  <application>LPD</application> is
           useless&mdash;or mostly so.</para>
             
         <para>One obvious way to get header pages is to have every conversion
           filter and the text filter generate the header page. The filters
           should use the user and host arguments to generate a suitable
           header page.  The drawback of this method is that users will always
           get a header page, even if they submit jobs with <command>lpr
             -h</command>.</para>
             
         <para>Let us explore this method.  The following script takes three
           arguments (user login name, host name, and job name) and makes a
           simple PostScript header page:</para>
 
         <programlisting>#!/bin/sh
 #
 #  make-ps-header - make a PostScript header page on stdout
 #  Installed in /usr/local/libexec/make-ps-header
 #
 
 #
 #  These are PostScript units (72 to the inch).  Modify for A4 or
 #  whatever size paper you are using:
 #
 page_width=612
 page_height=792
 border=72
 
 #
 #  Check arguments
 #
 if [ $# -ne 3 ]; then
     echo "Usage: `basename $0` &lt;user&gt; &lt;host&gt; &lt;job&gt;" 1&gt;&amp;2
     exit 1
 fi
 
 #
 #  Save these, mostly for readability in the PostScript, below.
 #
 user=$1
 host=$2
 job=$3
 date=`date`
 
 #
 #  Send the PostScript code to stdout.
 #
 exec cat &lt;&lt;EOF
 %!PS
 
 %
 %  Make sure we do not interfere with user's job that will follow
 %
 save
 
 %
 %  Make a thick, unpleasant border around the edge of the paper.
 %
 $border $border moveto
 $page_width $border 2 mul sub 0 rlineto
 0 $page_height $border 2 mul sub rlineto
 currentscreen 3 -1 roll pop 100 3 1 roll setscreen
 $border 2 mul $page_width sub 0 rlineto closepath
 0.8 setgray 10 setlinewidth stroke 0 setgray
 
 %
 %  Display user's login name, nice and large and prominent
 %
 /Helvetica-Bold findfont 64 scalefont setfont
 $page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto
 ($user) show
 
 %
 %  Now show the boring particulars
 %
 /Helvetica findfont 14 scalefont setfont
 /y 200 def
 [ (Job:) (Host:) (Date:) ] {
 200 y moveto show /y y 18 sub def }
 forall
 
 /Helvetica-Bold findfont 14 scalefont setfont
 /y 200 def
 [ ($job) ($host) ($date) ] {
         270 y moveto show /y y 18 sub def
 } forall
 
 %
 % That is it
 %
 restore
 showpage
 EOF</programlisting>
 
         <para>Now, each of the conversion filters and the text filter can call
           this script to first generate the header page, and then print the
           user's job.  Here is the DVI conversion filter from earlier in this
           document, modified to make a header page:</para>
 
         <programlisting>#!/bin/sh
 #
 #  psdf - DVI to PostScript printer filter
 #  Installed in /usr/local/libexec/psdf
 #
 #  Invoked by lpd when user runs lpr -d
 #
                 
 orig_args="$@"
 
 fail() {
     echo "$@" 1&gt;&amp;2
     exit 2
 }
 
 while getopts "x:y:n:h:" option; do
     case $option in
         x|y)  ;; # Ignore
         n)    login=$OPTARG ;;
         h)    host=$OPTARG ;;
         *)    echo "LPD started `basename $0` wrong." 1&gt;&amp;2
               exit 2
               ;;
     esac
 done
 
 [ "$login" ] || fail "No login name"
 [ "$host" ] || fail "No host name"
 
 ( /usr/local/libexec/make-ps-header $login $host "DVI File"
   /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args</programlisting>
 
         <para>Notice how the filter has to parse the argument list in order to
           determine the user and host name.  The parsing for the other
           conversion filters is identical.  The text filter takes a slightly
           different set of arguments, though (see section <link
             linkend="printing-advanced-filters">How      Filters
             Work</link>).</para>
             
         <para>As we have mentioned before, the above scheme, though fairly
           simple, disables the <quote>suppress header page</quote> option (the
           <option>-h</option> option) to <command>lpr</command>.  If users
           wanted to save a tree (or a few pennies, if you charge for header
           pages), they would not be able to do so, since every filter's going
           to print a header page with every job.</para>
             
         <para>To allow users to shut off header pages on a per-job basis, you
           will need to use the trick introduced in section <link
             linkend="printing-advanced-header-pages-accounting">Accounting for
             Header Pages</link>: write an output filter that parses the
           LPD-generated header page and produces a PostScript version.  If the
           user submits the job with <command>lpr -h</command>, then 
 	  <application>LPD</application> will
           not generate a header page, and neither will your output filter.
           Otherwise, your output filter will read the text from 
 	  <application>LPD</application> and send
           the appropriate header page PostScript code to the printer.</para>
             
         <para>If you have a PostScript printer on a serial line, you can make
           use of <command>lprps</command>, which comes with an output filter,
           <command>psof</command>, which does the above.  Note that
           <command>psof</command> does not charge for header pages.</para>
       </sect3>
     </sect2>
     
     <sect2 id="printing-advanced-network-printers">
       <title>Networked Printing</title>
       
       <indexterm>
         <primary>printer</primary>
         <secondary>network</secondary>
       </indexterm>
       <indexterm><primary>network printing</primary></indexterm>
       <para>FreeBSD supports networked printing: sending jobs to remote
         printers.  Networked printing generally refers to two different
         things:</para>
       
       <itemizedlist>
         <listitem>
           <para>Accessing a printer attached to a remote host.  You install a
             printer that has a conventional serial or parallel interface on
             one host.  Then, you set up <application>LPD</application> to 
 	    enable access to the printer
             from other hosts on the network. Section <link
               linkend="printing-advanced-network-rm">Printers Installed on
               Remote Hosts</link> tells how to do this.</para>
         </listitem>
 
         <listitem>
           <para>Accessing a printer attached directly to a network.  The
             printer has a network interface in addition (or in place of) a
             more conventional serial or parallel interface.  Such a printer
             might work as follows:</para>
           
           <itemizedlist>
             <listitem>
               <para>It might understand the <application>LPD</application>
 		protocol and can even queue
                 jobs from remote hosts.  In this case, it acts just like a
                 regular host running <application>LPD</application>.  Follow 
 		the same procedure in
                 section <link linkend="printing-advanced-network-rm">Printers
                   Installed on Remote Hosts</link> to set up such a
                 printer.</para>
             </listitem>
             
             <listitem>
               <para>It might support a data stream network connection. In this
                 case, you <quote>attach</quote> the printer to one host on the
                 network by making that host responsible for spooling jobs and
                 sending them to the printer. Section <link
                   linkend="printing-advanced-network-net-if">Printers with
                   Networked Data Stream Interfaces</link> gives some
                 suggestions on installing such printers.</para>
             </listitem>
           </itemizedlist>
         </listitem>
       </itemizedlist>
           
       <sect3 id="printing-advanced-network-rm">
         <title>Printers Installed on Remote Hosts</title>
 
         <para>The <application>LPD</application> spooling system has built-in
 	  support for sending jobs to
           other hosts also running <application>LPD</application> (or are 
 	  compatible with <application>LPD</application>).  This
           feature enables you to install a printer on one host and make it
           accessible from other hosts.  It also works with printers that have
           network interfaces that understand the 
 	  <application>LPD</application> protocol.</para>
             
         <para>To enable this kind of remote printing, first install a printer
           on one host, the <emphasis>printer host</emphasis>, using the simple
           printer setup described in the <link linkend="printing-simple">Simple
             Printer Setup</link> section.  Do any advanced setup in <link
             linkend="printing-advanced">Advanced Printer Setup</link> that you
           need.  Make sure to test the printer and see if it works with the
           features of <application>LPD</application> you have enabled.  
 	  Also ensure that the
           <emphasis>local host</emphasis> has authorization to use the 
 	  <application>LPD</application>
           service in the <emphasis>remote host</emphasis> (see <link
             linkend="printing-advanced-restricting-remote">Restricting Jobs
             from Remote Printers</link>).</para>
             
         <indexterm>
           <primary>printer</primary>
           <secondary>network</secondary>
         </indexterm>
         <indexterm><primary>network printing</primary></indexterm>
         <para>If you are using a printer with a network interface that is
           compatible with <application>LPD</application>, then the 
 	  <emphasis>printer host</emphasis> in
           the discussion below is the printer itself, and the
           <emphasis>printer name</emphasis> is the name you configured for the
           printer.  See the documentation that accompanied your printer and/or
           printer-network interface.</para>
 
         <tip>
           <para>If you are using a Hewlett Packard Laserjet then the printer
             name <literal>text</literal> will automatically perform the LF to
             CRLF conversion for you, so you will not require the
             <filename>hpif</filename> script.</para>
         </tip>
             
         <para>Then, on the other hosts you want to have access to the printer,
           make an entry in their <filename>/etc/printcap</filename> files with
           the following:</para>
 
         <orderedlist>
           <listitem>
             <para>Name the entry anything you want.  For simplicity, though,
               you probably want to use the same name and aliases as on the
               printer host.</para>
           </listitem>
           
           <listitem>
             <para>Leave the <literal>lp</literal> capability blank, explicitly
               (<literal>:lp=:</literal>).</para>
           </listitem>
           
           <listitem>
             <para>Make a spooling directory and specify its location in the
               <literal>sd</literal> capability.  <application>LPD</application>
 	      will store jobs here
               before they get sent to the printer host.</para>
           </listitem>
           
           <listitem>
             <para>Place the name of the printer host in the
               <literal>rm</literal> capability.</para>
           </listitem>
           
           <listitem>
             <para>Place the printer name on the <emphasis>printer
                 host</emphasis> in the <literal>rp</literal>
               capability.</para>
           </listitem>
         </orderedlist>
 
         <para>That is it.  You do not need to list conversion filters, page
           dimensions, or anything else in the
           <filename>/etc/printcap</filename> file.</para>
 
         <para>Here is an example.  The host <hostid>rose</hostid> has two
           printers, <literal>bamboo</literal> and <literal>rattan</literal>.
           We will enable users on the host <hostid>orchid</hostid> to print
           to those printers.
           Here is the <filename>/etc/printcap</filename> file for
           <hostid>orchid</hostid> (back from section <link
             linkend="printing-advanced-header-pages-enabling">Enabling Header
             Pages</link>).  It already had the entry for the printer
           <literal>teak</literal>; we have added entries for the two printers
           on the host <hostid>rose</hostid>:</para>
 
         <programlisting>#
 #  /etc/printcap for host orchid - added (remote) printers on rose
 #
 
 #
 #  teak is local; it is connected directly to orchid:
 #
 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
         :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
         :if=/usr/local/libexec/ifhp:\
         :vf=/usr/local/libexec/vfhp:\
         :of=/usr/local/libexec/ofhp:
 
 #
 #  rattan is connected to rose; send jobs for rattan to rose:
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
 
 #
 #  bamboo is connected to rose as well:
 #
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:</programlisting>
 
         <para>Then, we just need to make spooling directories on
           <hostid>orchid</hostid>:</para>
               
         <screen>&prompt.root; <userinput>mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput>
 &prompt.root; <userinput>chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput>
 &prompt.root; <userinput>chown daemon:daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput></screen>
               
         <para>Now, users on <hostid>orchid</hostid> can print to
           <literal>rattan</literal> and <literal>bamboo</literal>.  If, for
           example, a user on <hostid>orchid</hostid> typed
               
           <screen>&prompt.user; <userinput>lpr -P bamboo -d sushi-review.dvi</userinput></screen>
 
           the <application>LPD</application> system on <hostid>orchid</hostid>
 	  would copy the job to the spooling
           directory <filename>/var/spool/lpd/bamboo</filename> and note that it was a
           DVI job.  As soon as the host <hostid>rose</hostid> has room in its
           <literal>bamboo</literal> spooling directory, the two 
 	  <application>LPDs</application> would transfer the
           file to <hostid>rose</hostid>.  The file would wait in <hostid>rose</hostid>'s
           queue until it was finally printed.  It would be converted from DVI to
           PostScript (since <literal>bamboo</literal> is a PostScript printer) on
           <hostid>rose</hostid>.</para>
       </sect3>
       
       <sect3 id="printing-advanced-network-net-if">
         <title>Printers with Networked Data Stream Interfaces</title>
 
         <para>Often, when you buy a network interface card for a printer, you
           can get two versions: one which emulates a spooler (the more
           expensive version), or one which just lets you send data to it as if
           you were using a serial or parallel port (the cheaper version).
           This section tells how to use the cheaper version. For the more
           expensive one, see the previous section <link
             linkend="printing-advanced-network-rm">Printers Installed on
             Remote Hosts</link>.</para>
             
         <para>The format of the <filename>/etc/printcap</filename> file lets
           you specify what serial or parallel interface to use, and (if you
           are using a serial interface), what baud rate, whether to use flow
           control, delays for tabs, conversion of newlines, and more.  But
           there is no way to specify a connection to a printer that is
           listening on a TCP/IP or other network port.</para>
             
         <para>To send data to a networked printer, you need to develop a
           communications program that can be called by the text and conversion
           filters.  Here is one such example: the script
           <command>netprint</command> takes all data on standard input and
           sends it to a network-attached printer.  We specify the hostname of
           the printer as the first argument and the port number to which to
           connect as the second argument to <command>netprint</command>.  Note
           that this supports one-way communication only (FreeBSD to printer);
           many network printers support two-way communication, and you might
           want to take advantage of that (to get printer status, perform
           accounting, etc.).</para>
 
         <programlisting>#!/usr/bin/perl
 #
 #  netprint - Text filter for printer attached to network
 #  Installed in /usr/local/libexec/netprint
 #
 $#ARGV eq 1 || die "Usage: $0 &lt;printer-hostname&gt; &lt;port-number&gt;";
 
 $printer_host = $ARGV[0];
 $printer_port = $ARGV[1];
 
 require 'sys/socket.ph';
 
 ($ignore, $ignore, $protocol) = getprotobyname('tcp');
 ($ignore, $ignore, $ignore, $ignore, $address)
     = gethostbyname($printer_host);
 
 $sockaddr = pack('S n a4 x8', &amp;AF_INET, $printer_port, $address);
 
 socket(PRINTER, &amp;PF_INET, &amp;SOCK_STREAM, $protocol)
     || die "Can't create TCP/IP stream socket: $!";
 connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!";
 while (&lt;STDIN&gt;) { print PRINTER; }
 exit 0;</programlisting>
             
         <para>We can then use this script in various filters.  Suppose we had
           a Diablo 750-N line printer connected to the network.  The printer
           accepts data to print on port number 5100.  The host name of the
           printer is scrivener.  Here is the text filter for the
           printer:</para>
 
         <programlisting>#!/bin/sh
 #
 #  diablo-if-net - Text filter for Diablo printer `scrivener' listening
 #  on port 5100.   Installed in /usr/local/libexec/diablo-if-net
 #
 exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100</programlisting>
       </sect3>
     </sect2>
     
     <sect2 id="printing-advanced-restricting">
       <title>Restricting Printer Usage</title>
       
       <indexterm>
         <primary>printer</primary>
         <secondary>restricting access to</secondary>
       </indexterm>
       <para>This section gives information on restricting printer usage. The
         <application>LPD</application> system lets you control who can access
 	a printer, both locally or
         remotely, whether they can print multiple copies, how large their jobs
         can be, and how large the printer queues can get.</para>
       
       <sect3 id="printing-advanced-restricting-copies">
         <title>Restricting Multiple Copies</title>
 
         <para>The <application>LPD</application> system makes it easy for
 	  users to print multiple copies
           of a file.  Users can print jobs with <command>lpr -#5</command>
           (for example) and get five copies of each file in the job.  Whether
           this is a good thing is up to you.</para>
             
         <para>If you feel multiple copies cause unnecessary wear and tear on
           your printers, you can disable the <option>-#</option> option to
             &man.lpr.1; by adding the <literal>sc</literal> capability to the
           <filename>/etc/printcap</filename> file.  When users submit jobs
           with the <option>-#</option> option, they will see:</para>
               
         <screen>lpr: multiple copies are not allowed</screen>
 
 
         <para>Note that if you have set up access to a printer remotely (see
           section <link linkend="printing-advanced-network-rm">Printers
             Installed on Remote Hosts</link>), you need the
           <literal>sc</literal> capability on the remote
           <filename>/etc/printcap</filename> files as well, or else users will
           still be able to submit multiple-copy jobs by using another
           host.</para>
 
         <para>Here is an example.  This is the
           <filename>/etc/printcap</filename> file for the host
           <hostid>rose</hostid>.  The printer <literal>rattan</literal> is
           quite hearty, so we will allow multiple copies, but the laser
           printer <literal>bamboo</literal> is a bit more delicate, so we will
           disable multiple copies by adding the <literal>sc</literal>
           capability:</para>
 
         <programlisting>#
 #  /etc/printcap for host rose - restrict multiple copies on bamboo
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :sh:sd=/var/spool/lpd/rattan:\
         :lp=/dev/lpt0:\
         :if=/usr/local/libexec/if-simple:
 
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:sd=/var/spool/lpd/bamboo:sc:\
         :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
         :if=/usr/local/libexec/psif:\
         :df=/usr/local/libexec/psdf:</programlisting>
             
         <para>Now, we also need to add the <literal>sc</literal> capability on
           the host <hostid>orchid</hostid>'s
           <filename>/etc/printcap</filename> (and while we are at it, let us
           disable multiple copies for the printer
           <literal>teak</literal>):</para>
 
         <programlisting>#
 #  /etc/printcap for host orchid - no multiple copies for local
 #  printer teak or remote printer bamboo
 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
         :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:sc:\
         :if=/usr/local/libexec/ifhp:\
         :vf=/usr/local/libexec/vfhp:\
         :of=/usr/local/libexec/ofhp:
 
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
 
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc:</programlisting>
             
         <para>By using the <literal>sc</literal> capability, we prevent the
           use of <command>lpr -#</command>, but that still does not prevent
           users from running &man.lpr.1;
           multiple times, or from submitting the same file multiple times in
           one job like this:</para>
               
         <screen>&prompt.user; <userinput>lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign</userinput></screen>
               
         <para>There are many ways to prevent this abuse (including ignoring
           it) which you are free to explore.</para>
       </sect3>
       
       <sect3 id="printing-advanced-restricting-access">
         <title>Restricting Access To Printers</title>
 
         <para>You can control who can print to what printers by using the Unix
           group mechanism and the <literal>rg</literal> capability in
           <filename>/etc/printcap</filename>.  Just place the users you want
           to have access to a printer in a certain group, and then name that
           group in the <literal>rg</literal> capability.</para>
             
         <para>Users outside the group (including <username>root</username>)
 	  will be greeted with
           
           <errorname>lpr: Not a member of the restricted group</errorname>
           
           if they try to print to the controlled printer.</para>
 
         <para>As with the <literal>sc</literal> (suppress multiple copies)
           capability, you need to specify <literal>rg</literal> on remote
           hosts that also have access to your printers, if you feel it is
           appropriate (see section <link
             linkend="printing-advanced-network-rm">Printers Installed on
             Remote Hosts</link>).</para>
             
         <para>For example, we will let anyone access the printer
           <literal>rattan</literal>, but only those in group
           <literal>artists</literal> can use <literal>bamboo</literal>.  Here
           is the familiar <filename>/etc/printcap</filename> for host
           <hostid>rose</hostid>:</para>
 
         <programlisting>#
 #  /etc/printcap for host rose - restricted group for bamboo
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :sh:sd=/var/spool/lpd/rattan:\
         :lp=/dev/lpt0:\
         :if=/usr/local/libexec/if-simple:
 
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:\
         :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
         :if=/usr/local/libexec/psif:\
         :df=/usr/local/libexec/psdf:</programlisting>
 
         <para>Let us leave the other example
           <filename>/etc/printcap</filename> file (for the host
           <hostid>orchid</hostid>) alone.  Of course, anyone on
           <hostid>orchid</hostid> can print to <literal>bamboo</literal>.  It
           might be the case that we only allow certain logins on
           <hostid>orchid</hostid> anyway, and want them to have access to the
           printer.  Or not.</para>
 
         <note>
           <para>There can be only one restricted group per printer.</para>
         </note>
       </sect3>
       
       <sect3 id="printing-advanced-restricting-sizes">
         <title>Controlling Sizes of Jobs Submitted</title>
 
         <indexterm><primary>print jobs</primary></indexterm>
         <para>If you have many users accessing the printers, you probably need
           to put an upper limit on the sizes of the files users can submit to
           print.  After all, there is only so much free space on the
           filesystem that houses the spooling directories, and you also need
           to make sure there is room for the jobs of other users.</para>
             
         <indexterm>
           <primary>print jobs</primary>
           <secondary>controlling</secondary>
         </indexterm>
         <para><application>LPD</application> enables you to limit the maximum
 	  byte size a file in a job
           can be with the <literal>mx</literal> capability. The units are in
           <literal>BUFSIZ</literal> blocks, which are 1024 bytes.  If you put
 	  a zero for this
           capability, there will be no limit on file size; however, if no
           <literal>mx</literal> capability is specified, then a default limit
           of 1000 blocks will be used.</para>
 
         <note>
           <para>The limit applies to <emphasis>files</emphasis> in a job, and
             <emphasis>not</emphasis> the total job size.</para>
         </note>
 
         <para><application>LPD</application> will not refuse a file that is
 	  larger than the limit you
           place on a printer.  Instead, it will queue as much of the file up
           to the limit, which will then get printed.  The rest will be
           discarded.  Whether this is correct behavior is up for
           debate.</para>
             
         <para>Let us add limits to our example printers
           <literal>rattan</literal> and <literal>bamboo</literal>.  Since
           those artists' PostScript files tend to be large, we will limit them
           to five megabytes. We will put no limit on the plain text line
           printer:</para>
 
         <programlisting>#
 #  /etc/printcap for host rose
 #
 
 #
 #  No limit on job size:
 #
 rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :sh:mx#0:sd=/var/spool/lpd/rattan:\
         :lp=/dev/lpt0:\
         :if=/usr/local/libexec/if-simple:
 
 #
 #  Limit of five megabytes:
 #
 bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
         :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
         :if=/usr/local/libexec/psif:\
         :df=/usr/local/libexec/psdf:</programlisting>
 
         <para>Again, the limits apply to the local users only.  If you have
           set up access to your printers remotely, remote users will not get
           those limits.  You will need to specify the <literal>mx</literal>
           capability in the remote <filename>/etc/printcap</filename> files as
           well.  See section <link
             linkend="printing-advanced-network-rm">Printers Installed      on
             Remote Hosts</link> for more information on remote
           printing.</para>
             
         <para>There is another specialized way to limit job sizes from remote
           printers; see section <link
             linkend="printing-advanced-restricting-remote">Restricting Jobs
             from Remote Printers</link>.</para>
       </sect3>
       
       <sect3 id="printing-advanced-restricting-remote">
         <title>Restricting Jobs from Remote Printers</title>
 
         <para>The <application>LPD</application> spooling system provides 
 	  several ways to restrict print
           jobs submitted from remote hosts:</para>
             
         <variablelist>
           <varlistentry>
             <term>Host restrictions</term>
 
             <listitem>
               <para>You can control from which remote hosts a local 
 		<application>LPD</application> accepts requests with the files
                 <filename>/etc/hosts.equiv</filename> and
                 <filename>/etc/hosts.lpd</filename>.
 		<application>LPD</application> checks to see if an
                 incoming request is from a host listed in either one of these
                 files.  If not, <application>LPD</application> refuses the
 		request.</para>
                     
               <para>The format of these files is simple: one host name per
                 line.  Note that the file
                 <filename>/etc/hosts.equiv</filename> is also used by the
                   &man.ruserok.3; protocol, and affects programs like
                   &man.rsh.1; and &man.rcp.1;, so be careful.</para>
               
               <para>For example, here is the
                 <filename>/etc/hosts.lpd</filename> file on the host
                 <hostid>rose</hostid>:</para>
 
               <programlisting>orchid
 violet
 madrigal.fishbaum.de</programlisting>
 
               <para>This means <hostid>rose</hostid> will accept requests from
                 the hosts <hostid>orchid</hostid>, <hostid>violet</hostid>,
                 and <hostid role="fqdn">madrigal.fishbaum.de</hostid>. If any
                 other host tries to access <hostid>rose</hostid>'s
                 <application>LPD</application>, the job will be refused.</para>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term>Size restrictions</term>
             
             <listitem>
               <para>You can control how much free space there needs to remain
                 on the filesystem where a spooling directory resides.  Make a
                 file called <filename>minfree</filename> in the spooling
                 directory for the local printer.  Insert in that file a number
                 representing how many disk blocks (512 bytes) of free space
                 there has to be for a remote job to be accepted.</para>
                     
               <para>This lets you insure that remote users will not fill your
                 filesystem.  You can also use it to give a certain priority to
                 local users: they will be able to queue jobs long after the
                 free disk space has fallen below the amount specified in the
                 <filename>minfree</filename> file.</para>
                     
               <para>For example, let us add a <filename>minfree</filename>
                 file for the printer <literal>bamboo</literal>.  We examine
                 <filename>/etc/printcap</filename> to find the spooling
                 directory for this printer; here is <literal>bamboo</literal>'s
                 entry:</para>
                   
               <programlisting>bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
         :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
         :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:mx#5000:\
         :if=/usr/local/libexec/psif:\
         :df=/usr/local/libexec/psdf:</programlisting>
 
               <para>The spooling directory is given in the <literal>sd</literal>
                 capability.  We will make three megabytes (which is 6144 disk blocks)
                 the amount of free disk space that must exist on the filesystem for
                 <application>LPD</application> to accept remote jobs:</para>
                   
               <screen>&prompt.root; <userinput>echo 6144 &gt; /var/spool/lpd/bamboo/minfree
               </userinput></screen>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term>User restrictions</term>
             
             <listitem>
               <para>You can control which remote users can print to local
                 printers by specifying the <literal>rs</literal> capability in
                 <filename>/etc/printcap</filename>.  When
                 <literal>rs</literal> appears in the entry for a
                 locally-attached printer, <application>LPD</application> will
 		accept jobs from remote
                 hosts <emphasis>if</emphasis> the user submitting the job also
                 has an account of the same login name on the local host.
                 Otherwise, <application>LPD</application> refuses the job.</para>
                     
               <para>This capability is particularly useful in an environment
                 where there are (for example) different departments sharing a
                 network, and some users transcend departmental boundaries.  By
                 giving them accounts on your systems, they can use your
                 printers from their own departmental systems.  If you would
                 rather allow them to use <emphasis>only</emphasis> your
                 printers and not your computer resources, you can give them
                 <quote>token</quote> accounts, with no home directory and a
                 useless shell like <filename>/usr/bin/false</filename>.</para>
             </listitem>
           </varlistentry>
         </variablelist>
       </sect3>
     </sect2>
     
     <sect2 id="printing-advanced-acct">
       <title>Accounting for Printer Usage</title>
           
       <indexterm>
         <primary>accounting</primary>
         <secondary>printer</secondary>
       </indexterm>
       <para>So, you need to charge for printouts.  And why not? Paper and ink
         cost money.  And then there are maintenance costs&mdash;printers are
         loaded with moving parts and tend to break down.  You have examined
         your printers, usage patterns, and maintenance fees and have come up
         with a per-page (or per-foot, per-meter, or per-whatever) cost.  Now,
         how do you actually start accounting for printouts?</para>
           
       <para>Well, the bad news is the <application>LPD</application> spooling
 	system does not provide
         much help in this department.  Accounting is highly dependent on the
         kind of printer in use, the formats being printed, and
         <emphasis>your</emphasis> requirements in charging for printer
         usage.</para>
       
       <para>To implement accounting, you have to modify a printer's text
         filter (to charge for plain text jobs) and the conversion filters (to
         charge for other file formats), to count pages or query the printer
         for pages printed.  You cannot get away with using the simple output
         filter, since it cannot do accounting.  See section <link
           linkend="printing-advanced-filter-intro">Filters</link>.</para>
           
       <para>Generally, there are two ways to do accounting:</para>
       
       <itemizedlist>
         <listitem>
           <para><emphasis>Periodic accounting</emphasis> is the more common
             way, possibly because it is easier.  Whenever someone prints a
             job, the filter logs the user, host, and number of pages to an
             accounting file.  Every month, semester, year, or whatever time
             period you prefer, you collect the accounting files for the
             various printers, tally up the pages printed by users, and charge
             for usage.  Then you truncate all the logging files, starting with
             a clean slate for the next period.</para>
         </listitem>
               
         <listitem>
           <para><emphasis>Timely accounting</emphasis> is less common,
             probably because it is more difficult.  This method has the
             filters charge users for printouts as soon as they use the
             printers.  Like disk quotas, the accounting is immediate. You can
             prevent users from printing when their account goes in the red,
             and might provide a way for users to check and adjust their
             <quote>print quotas.</quote> But this method requires some database
             code to track users and their quotas.</para>
         </listitem>
       </itemizedlist>
       
       <para>The <application>LPD</application> spooling system supports both 
 	methods easily: since you
         have to provide the filters (well, most of the time), you also have to
         provide the accounting code.  But there is a bright side: you have
         enormous flexibility in your accounting methods.  For example, you
         choose whether to use periodic or timely accounting. You choose what
         information to log: user names, host names, job types, pages printed,
         square footage of paper used, how long the job took to print, and so
         forth.  And you do so by modifying the filters to save this
         information.</para>
           
       <sect3>
         <title>Quick and Dirty Printer Accounting</title>
 
         <para>FreeBSD comes with two programs that can get you set up with
           simple periodic accounting right away.  They are the text filter
           <command>lpf</command>, described in section <link
             linkend="printing-advanced-lpf">lpf: a Text Filter</link>, and
             &man.pac.8;, a program to gather and total
           entries from printer accounting files.</para>
 
         <para>As mentioned in the section on filters (<link
             linkend="printing-advanced-filters">Filters</link>), 
 	  <application>LPD</application> starts
           the text and the conversion filters with the name of the accounting
           file to use on the filter command line.  The filters can use this
           argument to know where to write an accounting file entry.  The name
           of this file comes from the <literal>af</literal> capability in
           <filename>/etc/printcap</filename>, and if not specified as an
           absolute path, is relative to the spooling directory.</para>
 
         <para><application>LPD</application> starts <command>lpf</command>
 	  with page width and length
           arguments (from the <literal>pw</literal> and <literal>pl</literal>
           capabilities).  <command>lpf</command> uses these arguments to
           determine how much paper will be used.  After sending the file to
           the printer, it then writes an accounting entry in the accounting
           file.  The entries look like this:</para>
 
         <programlisting>2.00 rose:andy
 3.00 rose:kelly
 3.00 orchid:mary
 5.00 orchid:mary
 2.00 orchid:zhang</programlisting>
             
         <para>You should use a separate accounting file for each printer, as
           <command>lpf</command> has no file locking logic built into it, and
           two <command>lpf</command>s might corrupt each other's entries if
           they were to write to the same file at the same time.  An easy way
           to insure a separate accounting file for each printer is to use
           <literal>af=acct</literal> in <filename>/etc/printcap</filename>.
           Then, each accounting file will be in the spooling directory for a
           printer, in a file named <filename>acct</filename>.</para>
             
         <para>When you are ready to charge users for printouts, run the
             &man.pac.8; program.  Just change to the spooling directory for
           the printer you want to collect on and type <literal>pac</literal>.
           You will get a dollar-centric summary like the following:</para>
             
         <screen>  Login               pages/feet   runs    price
 orchid:kelly                5.00    1   $  0.10
 orchid:mary                31.00    3   $  0.62
 orchid:zhang                9.00    1   $  0.18
 rose:andy                   2.00    1   $  0.04
 rose:kelly                177.00  104   $  3.54
 rose:mary                  87.00   32   $  1.74
 rose:root                  26.00   12   $  0.52
 
 total                     337.00  154   $  6.74</screen>
               
         <para>These are the arguments &man.pac.8; expects:</para>
 
         <variablelist>
           <varlistentry>
             <term><option>-P<replaceable>printer</replaceable></option></term>
 
             <listitem>
               <para>Which <replaceable>printer</replaceable> to summarize.
                 This option works only if there is an absolute path in the
                 <literal>af</literal> capability in
                 <filename>/etc/printcap</filename>.</para>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term><option>-c</option></term>
             
             <listitem>
               <para>Sort the output by cost instead of alphabetically by user
                 name.</para>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term><option>-m</option></term>
             
             <listitem>
               <para>Ignore host name in the accounting files.  With this
                 option, user <username>smith</username> on host
                 <hostid>alpha</hostid> is the same user
                 <username>smith</username> on host <hostid>gamma</hostid>.
                 Without, they are different users.</para>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term><option>-p<replaceable>price</replaceable></option></term>
             
             <listitem>
               <para>Compute charges with <replaceable>price</replaceable>
                 dollars per page or per foot instead of the price from the
                 <literal>pc</literal> capability in
                 <filename>/etc/printcap</filename>, or two cents (the
                 default).  You can specify <replaceable>price</replaceable> as
                 a floating point number.</para>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term><option>-r</option></term>
             
             <listitem>
               <para>Reverse the sort order.</para>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term><option>-s</option></term>
             
             <listitem>
               <para>Make an accounting summary file and truncate the
                 accounting file.</para>
             </listitem>
           </varlistentry>
           
           <varlistentry>
             <term><replaceable>name</replaceable>
               <replaceable>&hellip;</replaceable></term>
             
             <listitem>
               <para>Print accounting information for the given user
                 <replaceable>names</replaceable> only.</para>
             </listitem>
           </varlistentry>
         </variablelist>
 
         <para>In the default summary that &man.pac.8; produces, you see the
           number of pages printed by each user from various hosts.  If, at
           your site, host does not matter (because users can use any host),
           run <command>pac -m</command>, to produce the following
           summary:</para>
               
         <screen>  Login               pages/feet   runs    price
 andy                        2.00    1   $  0.04
 kelly                     182.00  105   $  3.64
 mary                      118.00   35   $  2.36
 root                       26.00   12   $  0.52
 zhang                       9.00    1   $  0.18
 
 total                     337.00  154   $  6.74</screen>
               
 
         <para>To compute the dollar amount due,
             &man.pac.8; uses the <literal>pc</literal> capability in the
           <filename>/etc/printcap</filename> file (default of 200, or 2 cents
           per page).  Specify, in hundredths of cents, the price per page or
           per foot you want to charge for printouts in this capability.  You
           can override this value when you run &man.pac.8; with the
           <option>-p</option> option.  The units for the <option>-p</option>
           option are in dollars, though, not hundredths of cents.  For
           example,
               
           <screen>&prompt.root; <userinput>pac -p1.50</userinput></screen>
               
           makes each page cost one dollar and fifty cents.  You can really
           rake in the profits by using this option.</para>
 
         <para>Finally, running <command>pac -s</command> will save the summary
           information in a summary accounting file, which is named the same as
           the printer's accounting file, but with <literal>_sum</literal>
           appended to the name.  It then truncates the accounting file.  When
           you run &man.pac.8; again, it rereads the
           summary file to get starting totals, then adds information from the
           regular accounting file.</para>
       </sect3>
       
       <sect3>
         <title>How Can You Count Pages Printed?</title>
 
         <para>In order to perform even remotely accurate accounting, you need
           to be able to determine how much paper a job uses.  This is the
           essential problem of printer accounting.</para>
             
         <para>For plain text jobs, the problem is not that hard to solve: you
           count how many lines are in a job and compare it to how many lines
           per page your printer supports.  Do not forget to take into account
           backspaces in the file which overprint lines, or long logical lines
           that wrap onto one or more additional physical lines.</para>
             
         <para>The text filter <command>lpf</command> (introduced in <link
             linkend="printing-advanced-lpf">lpf: a Text Filter</link>) takes
           into account these things when it does accounting.  If you are
           writing a text filter which needs to do accounting, you might want
           to examine <command>lpf</command>'s source code.</para>
             
         <para>How do you handle other file formats, though?</para>
 
         <para>Well, for DVI-to-LaserJet or DVI-to-PostScript conversion, you
           can have your filter parse the diagnostic output of
           <command>dvilj</command> or <command>dvips</command> and look to see
           how many pages were converted.  You might be able to do similar
           things with other file formats and conversion programs.</para>
 
         <para>But these methods suffer from the fact that the printer may not
           actually print all those pages.  For example, it could jam, run out
           of toner, or explode&mdash;and the user would still get
           charged.</para>
             
         <para>So, what can you do?</para>
 
         <para>There is only one <emphasis>sure</emphasis> way to do
           <emphasis>accurate</emphasis> accounting.  Get a printer that can
           tell you how much paper it uses, and attach it via a serial line or
           a network connection.  Nearly all PostScript printers support this
           notion.  Other makes and models do as well (networked Imagen laser
           printers, for example).  Modify the filters for these printers to
           get the page usage after they print each job and have them log
           accounting information based on that value
           <emphasis>only</emphasis>.  There is no line counting nor
           error-prone file examination required.</para>
             
         <para>Of course, you can always be generous and make all printouts
           free.</para>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="printing-using">
     <title>Using Printers</title>
     
     <indexterm>
       <primary>printer</primary>
       <secondary>usage</secondary>
    </indexterm>
     <para>This section tells you how to use printers you have setup with
       FreeBSD.  Here is an overview of the user-level commands:</para>
 
     <variablelist>
       <varlistentry>
 	<term>&man.lpr.1;</term>
 
 	<listitem>
 	  <para>Print jobs</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term>&man.lpq.1;</term>
 
 	<listitem>
 	  <para>Check printer queues</para>
 	</listitem>
       </varlistentry>
       
       <varlistentry>
 	<term>&man.lprm.1;</term>
 
 	<listitem>
 	  <para>Remove jobs from a printer's queue</para>
 	</listitem>
       </varlistentry>
     </variablelist>
     
     <para>There is also an administrative command, &man.lpc.8;, described in
       the section <link linkend="printing-lpc">Administrating the 
 	<application>LPD</application>
 	Spooler</link>, used to control printers and their queues.</para>
 
     <para>All three of the commands &man.lpr.1;, &man.lprm.1;, and &man.lpq.1;
       accept an option <option>-P
 	<replaceable>printer-name</replaceable></option> to specify on which
       printer/queue to operate, as listed in the
       <filename>/etc/printcap</filename> file.  This enables you to submit,
       remove, and check on jobs for various printers.  If you do not use the
       <option>-P</option> option, then these commands use the printer
       specified in the <envar>PRINTER</envar> environment variable.  Finally,
       if you do not have a <envar>PRINTER</envar> environment variable, these
       commands default to the printer named <literal>lp</literal>.</para>
 
     <para>Hereafter, the terminology <emphasis>default printer</emphasis>
       means the printer named in the <envar>PRINTER</envar> environment
       variable, or the printer named <literal>lp</literal> when there is no
       <envar>PRINTER</envar> environment variable.</para>
     
     <sect2 id="printing-lpr">
       <title>Printing Jobs</title>
       
       <para>To print files, type:</para>
       
       <screen>&prompt.user; <userinput>lpr <replaceable>filename</replaceable> <replaceable>...</replaceable></userinput></screen>
 	    
       <indexterm><primary>printing</primary></indexterm>
       <para>This prints each of the listed files to the default printer.  If
 	you list no files, &man.lpr.1; reads data to
 	print from standard input.  For example, this command prints some
 	important system files:</para>
 
       <screen>&prompt.user; <userinput>lpr /etc/host.conf /etc/hosts.equiv</userinput></screen>
 	    
       <para>To select a specific printer, type:</para>
 		    
       <screen>&prompt.user; <userinput>lpr -P <replaceable>printer-name</replaceable> <replaceable>filename</replaceable> <replaceable>...</replaceable></userinput></screen>
 
       <para>This example prints a long listing of the current directory to the
 	printer named <literal>rattan</literal>:</para>
 	    
       <screen>&prompt.user; <userinput>ls -l | lpr -P rattan</userinput></screen>
 	    
       <para>Because no files were listed for the
 	  &man.lpr.1; command, <command>lpr</command> read the data to print
 	from standard input, which was the output of the <command>ls
 	  -l</command> command.</para>
       
       <para>The &man.lpr.1; command can also accept a wide variety of options
 	to control formatting, apply file conversions, generate multiple
 	copies, and so forth. For more information, see the section <link
 	  linkend="printing-lpr-options">Printing Options</link>.</para>
     </sect2>
     
     <sect2 id="printing-lpq">
       <title>Checking Jobs</title>
       
       <indexterm><primary>print jobs</primary></indexterm>
       <para>When you print with &man.lpr.1;, the data you wish to print is put
 	together in a package called a <quote>print job</quote>, which is sent
 	to the <application>LPD</application> spooling system.  Each printer 
 	has a queue of jobs, and
 	your job waits in that queue along with other jobs from yourself and
 	from other users.  The printer prints those jobs in a first-come,
 	first-served order.</para>
 
       <para>To display the queue for the default printer, type &man.lpq.1;.
 	For a specific printer, use the <option>-P</option> option.  For
 	example, the command
 
 	<screen>&prompt.user; <userinput>lpq -P bamboo</userinput></screen>
 
 	shows the queue for the printer named <literal>bamboo</literal>.  Here
 	is an example of the output of the <command>lpq</command>
 	command:</para>
 	    
       <screen>bamboo is ready and printing
 Rank   Owner    Job  Files                              Total Size
 active kelly    9    /etc/host.conf, /etc/hosts.equiv   88 bytes
 2nd    kelly    10   (standard input)                   1635 bytes
 3rd    mary     11   ...                                78519 bytes</screen>
 	    
       <para>This shows three jobs in the queue for <literal>bamboo</literal>.
 	The first job, submitted by user kelly, got assigned <quote>job
 	number</quote> 9.  Every job for a printer gets a unique job number.
 	Most of the time you can ignore the job number, but you will need it
 	if you want to cancel the job; see section <link
 	  linkend="printing-lprm">Removing Jobs</link> for details.</para>
 	  
       <para>Job number nine consists of two files; multiple files given on the
 	  &man.lpr.1; command line are treated as part of a single job.  It
 	is the currently active job (note the word <literal>active</literal>
 	under the <quote>Rank</quote> column), which means the printer should
 	be currently printing that job.  The second job consists of data
 	passed as the standard input to the &man.lpr.1; command.  The third
 	  job came from user <username>mary</username>; it is a much larger
 	  job. The pathname of the file she is trying to print is too long to
 	  fit, so the &man.lpq.1; command just shows three dots.</para>
 
       <para>The very first line of the output from &man.lpq.1; is also useful:
 	it tells what the printer is currently doing (or at least what 
 	<application>LPD</application> thinks the printer is doing).</para>
 
       <para>The &man.lpq.1; command also support a <option>-l</option> option
 	to generate a detailed long listing.  Here is an example of
 	<command>lpq -l</command>:</para>
 	    
       <screen>waiting for bamboo to become ready (offline ?)
 kelly: 1st				 [job 009rose]
        /etc/host.conf                    73 bytes
        /etc/hosts.equiv                  15 bytes
 
 kelly: 2nd				 [job 010rose]
        (standard input)                  1635 bytes
 
 mary: 3rd                                [job 011rose]
       /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes</screen>
     </sect2>
 
     <sect2 id="printing-lprm">
       <title>Removing Jobs</title>
       
       <para>If you change your mind about printing a job, you can remove the
 	job from the queue with the &man.lprm.1; command.  Often, you can
 	even use &man.lprm.1; to remove an active job, but some or all of the
 	job might still get printed.</para>
 	  
       <para>To remove a job from the default printer, first use
 	  &man.lpq.1; to find the job number.  Then type:</para>
 	  
       <screen>&prompt.user; <userinput>lprm <replaceable>job-number</replaceable></userinput></screen>
 	    
       <para>To remove the job from a specific printer, add the
 	<option>-P</option> option.  The following command removes job number
 	10 from the queue for the printer <literal>bamboo</literal>:</para>
 	    
       <screen>&prompt.user; <userinput>lprm -P bamboo 10</userinput></screen>
       
       <para>The &man.lprm.1; command has a few shortcuts:</para>
       
       <variablelist>
 	<varlistentry>
 	  <term>lprm -</term>
 
 	  <listitem>
 	    <para>Removes all jobs (for the default printer) belonging to
 	      you.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>lprm <replaceable>user</replaceable></term>
 	  
 	  <listitem>
 	    <para>Removes all jobs (for the default printer) belonging to
 	      <replaceable>user</replaceable>.  The superuser can remove other
 	      users' jobs; you can remove only your own jobs.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term>lprm</term>
 	  
 	  <listitem>
 	    <para>With no job number, user name, or <option>-</option>
 	      appearing on the command line,
 		    &man.lprm.1; removes the currently active job on the
 	      default printer, if it belongs to you.  The superuser can remove
 	      any active job.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <para>Just use the <option>-P</option> option with the above shortcuts
 	to operate on a specific printer instead of the default. For example,
 	the following command removes all jobs for the current user in the
 	queue for the printer named <literal>rattan</literal>:</para>
 	  
       <screen>&prompt.user; <userinput>lprm -P rattan -</userinput></screen>
 	  
       <note>
 	<para>If you are working in a networked environment, &man.lprm.1; will
 	  let you remove jobs only from the
 	  host from which the jobs were submitted, even if the same printer is
 	  available from other hosts. The following command sequence
 	  demonstrates this:</para>
 	      
 	<screen>&prompt.user; <userinput>lpr -P rattan myfile</userinput>
 &prompt.user; <userinput>rlogin orchid</userinput>
 &prompt.user; <userinput>lpq -P rattan</userinput>
 Rank   Owner	  Job  Files                          Total Size
 active seeyan	  12	...                           49123 bytes
 2nd    kelly      13   myfile                         12 bytes
 &prompt.user; <userinput>lprm -P rattan 13</userinput>
 rose: Permission denied
 &prompt.user; <userinput>logout</userinput>
 &prompt.user; <userinput>lprm -P rattan 13</userinput>
 dfA013rose dequeued
 cfA013rose dequeued
 	</screen>
       </note>
     </sect2>
     
     <sect2 id="printing-lpr-options">
       <title>Beyond Plain Text: Printing Options</title>
       
       <para>The &man.lpr.1; command supports a number of options that control
 	formatting text, converting graphic and other file formats, producing
 	multiple copies, handling of the job, and more.  This section
 	describes the options.</para>
 	  
       <sect3 id="printing-lpr-options-format">
 	<title>Formatting and Conversion Options</title>
 
 	<para>The following &man.lpr.1; options control formatting of the
 	  files in the job.  Use these options if the job does not contain
 	  plain text or if you want plain text formatted through the
 	    &man.pr.1; utility.</para>
 	    
         <indexterm><primary>TeX</primary></indexterm>
 	<para>For example, the following command prints a DVI file (from the
 	  TeX typesetting system) named <filename>fish-report.dvi</filename>
 	  to the printer named <literal>bamboo</literal>:</para>
 	      
 	<screen>&prompt.user; <userinput>lpr -P bamboo -d fish-report.dvi</userinput></screen>
 	      
 	<para>These options apply to every file in the job, so you cannot mix
 	  (say) DVI and ditroff files together in a job. Instead, submit the
 	  files as separate jobs, using a different conversion option for each
 	  job.</para>
 
 	<note>
 	  <para>All of these options except <option>-p</option> and
 	    <option>-T</option> require conversion filters installed for the
 	    destination printer.  For example, the <option>-d</option> option
 	    requires the DVI conversion filter.  Section <link
 	      linkend="printing-advanced-convfilters">Conversion
 	      Filters</link> gives details.</para>
 	</note>
 
 	<variablelist>
 	  <varlistentry>
 	    <term><option>-c</option></term>
 
 	    <listitem>
 	      <para>Print cifplot files.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><option>-d</option></term>
 	    
 	    <listitem>
 	      <para>Print DVI files.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><option>-f</option></term>
 	    
 	    <listitem>
 	      <para>Print FORTRAN text files.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><option>-g</option></term>
 	    
 	    <listitem>
 	      <para>Print plot data.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><option>-i <replaceable>number</replaceable></option></term>
 		  
 	    <listitem>
 	      <para>Indent the output by <replaceable>number</replaceable>
 		columns; if you omit <replaceable>number</replaceable>, indent
 		by 8 columns.  This option works only with certain conversion
 		filters.</para>
 
 	      <note>
 		<para>Do not put any space between the <option>-i</option> and
 		  the number.</para>
 	      </note>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><option>-l</option></term>
 	    
 	    <listitem>
 	      <para>Print literal text data, including control
 		characters.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><option>-n</option></term>
 	    
 	    <listitem>
 	      <para>Print ditroff (device independent troff) data.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-p</term>
 	    
 	    <listitem>
 	      <para>Format plain text with &man.pr.1; before printing.  See
 		  &man.pr.1; for more information.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><option>-T <replaceable>title</replaceable></option></term>
 	    
 	    <listitem>
 	      <para>Use <replaceable>title</replaceable> on the
 		  &man.pr.1; header instead of the file name.  This option has
 		effect only when used with the <option>-p</option>
 		option.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><option>-t</option></term>
 	    
 	    <listitem>
 	      <para>Print troff data.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term><option>-v</option></term>
 	    
 	    <listitem>
 	      <para>Print raster data.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 		    
 	<para>Here is an example: this command prints a nicely formatted
 	  version of the &man.ls.1; manual page on the default printer:</para>
 	    
 	<screen>&prompt.user; <userinput>zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t</userinput></screen>
 	      
 	<para>The &man.zcat.1; command uncompresses the source of the
 	  &man.ls.1; manual page and passes it to the &man.troff.1;
 	  command, which formats that source and makes GNU troff
 	  output and passes it to &man.lpr.1;, which submits the job
 	  to the <application>LPD</application> spooler.  Because we 
 	  used the <option>-t</option>
 	  option to &man.lpr.1;, the spooler will convert the GNU
 	  troff output into a format the default printer can
 	  understand when it prints the job.</para>
       </sect3>
       
       <sect3 id="printing-lpr-options-job-handling">
 	<title>Job Handling Options</title>
 
 	<para>The following options to &man.lpr.1; tell 
 	  <application>LPD</application> to handle the job
 	  specially:</para>
       
 	<variablelist>
 	  <varlistentry>
 	    <term>-# <replaceable>copies</replaceable></term>
 
 	    <listitem>
 	      <para>Produce a number of <replaceable>copies</replaceable> of
 		each file in the job instead of just one copy.  An
 		administrator may disable this option to reduce printer
 		wear-and-tear and encourage photocopier usage.  See section
 		<link
 		  linkend="printing-advanced-restricting-copies">Restricting
 		  Multiple Copies</link>.</para>
 
 	      <para>This example prints three copies of
 		<filename>parser.c</filename> followed by three copies of
 		<filename>parser.h</filename> to the default printer:</para>
 		      
 	      <screen>&prompt.user; <userinput>lpr -#3 parser.c parser.h</userinput></screen>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-m</term>
 	    
 	    <listitem>
 	      <para>Send mail after completing the print job.  With this
 		option, the <application>LPD</application> system will send
 		mail to your account when it
 		finishes handling your job.  In its message, it will tell you
 		if the job completed successfully or if there was an error,
 		and (often) what the error was.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-s</term>
 	    
 	    <listitem>
 	      <para>Do not copy the files to the spooling directory, but make
 		symbolic links to them instead.</para>
 		    
 	      <para>If you are printing a large job, you probably want to use
 		this option.  It saves space in the spooling directory (your
 		job might overflow the free space on the filesystem where the
 		spooling directory resides).  It saves time as well since 
 		<application>LPD</application>
 		will not have to copy each and every byte of your job to the
 		spooling directory.</para>
 		    
 	      <para>There is a drawback, though: since 
 		<application>LPD</application> will refer to the
 		original files directly, you cannot modify or remove them
 		until they have been printed.</para>
 	      
 	      <note>
 		<para>If you are printing to a remote printer, 
 		  <application>LPD</application> will
 		  eventually have to copy files from the local host to the
 		  remote host, so the <option>-s</option> option will save
 		  space only on the local spooling directory, not the remote.
 		  It is still useful, though.</para>
 	      </note>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-r</term>
 	    
 	    <listitem>
 	      <para>Remove the files in the job after copying them to the
 		spooling directory, or after printing them with the
 		<option>-s</option> option.  Be careful with this
 		option!</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
       </sect3>
 	  
       <sect3 id="printing-lpr-options-misc">
 	<title>Header Page Options</title>
 
 	<para>These options to &man.lpr.1; adjust the text that normally
 	  appears on a job's header page. If header pages are suppressed for
 	  the destination printer, these options have no effect.  See section
 	  <link linkend="printing-advanced-header-pages">Header Pages</link>
 	  for information about setting up header pages.</para>
 	    
 	<variablelist>
 	  <varlistentry>
 	    <term>-C <replaceable>text</replaceable></term>
 
 	    <listitem>
 	      <para>Replace the hostname on the header page with
 		<replaceable>text</replaceable>.  The hostname is normally the
 		name of the host from which the job was submitted.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-J <replaceable>text</replaceable></term>
 	    
 	    <listitem>
 	      <para>Replace the job name on the header page with
 		<replaceable>text</replaceable>.  The job name is normally the
 		name of the first file of the job, or
 		<filename>stdin</filename> if you are printing standard
 		input.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-h</term>
 	    
 	    <listitem>
 	      <para>Do not print any header page.</para>
 	      
 	      <note>
 		<para>At some sites, this option may have no effect due to the
 		  way header pages are generated.  See <link
 		    linkend="printing-advanced-header-pages">Header
 		    Pages</link> for details.</para>
 	      </note>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
       </sect3>
     </sect2>
     
     <sect2 id="printing-lpc">
       <title>Administrating Printers</title>
       
       <para>As an administrator for your printers, you have had to install,
 	set up, and test them.  Using the &man.lpc.8; command, you
 	can interact with your printers in yet more ways. With &man.lpc.8;,
 	you can</para>
       
       <itemizedlist>
 	<listitem>
 	  <para>Start and stop the printers</para>
 	</listitem>
 
 	<listitem>
 	  <para>Enable and disable their queues</para>
 	</listitem>
 
 	<listitem>
 	  <para>Rearrange the order of the jobs in each queue.</para>
 	</listitem>
       </itemizedlist>
       
       <para>First, a note about terminology: if a printer is
 	<emphasis>stopped</emphasis>, it will not print anything in its queue.
 	Users can still submit jobs, which will wait in the queue until the
 	printer is <emphasis>started</emphasis> or the queue is
 	cleared.</para>
 	  
       <para>If a queue is <emphasis>disabled</emphasis>, no user (except
 	<username>root</username>) can submit jobs for the printer.  An
 	<emphasis>enabled</emphasis> queue allows jobs to be submitted.  A
 	printer can be <emphasis>started</emphasis> for a disabled queue, in
 	which case it will continue to print jobs in the queue until the queue
 	is empty.</para>
 	  
       <para>In general, you have to have <username>root</username> privileges
 	to use the &man.lpc.8; command.  Ordinary users can use the &man.lpc.8;
 	command to get printer status and to restart a hung printer only.</para>
 
       <para>Here is a summary of the &man.lpc.8; commands.  Most of the
 	commands take a <replaceable>printer-name</replaceable> argument to
 	tell on which printer to operate.  You can use <literal>all</literal>
 	for the <replaceable>printer-name</replaceable> to mean all printers
 	listed in <filename>/etc/printcap</filename>.</para>
       
       <variablelist>
 	<varlistentry>
 	  <term><command>abort
 	      <replaceable>printer-name</replaceable></command></term>
 
 	  <listitem>
 	    <para>Cancel the current job and stop the printer.  Users can
 	      still submit jobs if the queue is enabled.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>clean
 	      <replaceable>printer-name</replaceable></command></term>
 	  
 	  <listitem>
 	    <para>Remove old files from the printer's spooling directory.
 	      Occasionally, the files that make up a job are not properly
 	      removed by <application>LPD</application>, particularly if 
 	      there have been errors during
 	      printing or a lot of administrative activity.  This command
 	      finds files that do not belong in the spooling directory and
 	      removes them.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>disable
 	      <replaceable>printer-name</replaceable></command></term>
 	  
 	  <listitem>
 	    <para>Disable queuing of new jobs.  If the printer is running, it
 	      will continue to print any jobs remaining in the queue.  The
 	      superuser (<username>root</username>) can always submit jobs,
 	      even to a disabled queue.</para>
 		  
 	    <para>This command is useful while you are testing a new printer
 	      or filter installation: disable the queue and submit jobs as
 	      <username>root</username>.  Other users will not be able to submit
 	      jobs until you complete your testing and re-enable the queue with
 	      the <command>enable</command> command.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>down <replaceable>printer-name</replaceable>
 	      <replaceable>message</replaceable></command></term>
 		
 	  <listitem>
 	    <para>Take a printer down.  Equivalent to
 	      <command>disable</command> followed by <command>stop</command>.
 	      The <replaceable>message</replaceable> appears as the printer's
 	      status whenever a user checks the printer's queue with
 		    &man.lpq.1; or status with <command>lpc
 		status</command>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>enable
 	      <replaceable>printer-name</replaceable></command></term>
 		
 	  <listitem>
 	    <para>Enable the queue for a printer.  Users can submit jobs but
 	      the printer will not print anything until it is started.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>help
 	      <replaceable>command-name</replaceable></command></term>
 		
 	  <listitem>
 	    <para>Print help on the command
 	      <replaceable>command-name</replaceable>.  With no
 	      <replaceable>command-name</replaceable>, print a summary of the
 	      commands available.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>restart
 	      <replaceable>printer-name</replaceable></command></term>
 	  
 	  <listitem>
 	    <para>Start the printer.  Ordinary users can use this command if
 	      some extraordinary circumstance hangs 
 	      <application>LPD</application>, but they cannot start
 	      a printer stopped with either the <command>stop</command> or
 	      <command>down</command> commands.  The
 	      <command>restart</command> command is equivalent to
 	      <command>abort</command> followed by
 	      <command>start</command>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>start
 	      <replaceable>printer-name</replaceable></command></term>
 		
 	  <listitem>
 	    <para>Start the printer.  The printer will print jobs in its
 	      queue.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>stop
 	      <replaceable>printer-name</replaceable></command></term>
 	  
 	  <listitem>
 	    <para>Stop the printer.  The printer will finish the current job
 	      and will not print anything else in its queue.  Even though the
 	      printer is stopped, users can still submit jobs to an enabled
 	      queue.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>topq <replaceable>printer-name</replaceable>
 	      <replaceable>job-or-username</replaceable></command></term>
 		
 	  <listitem>
 	    <para>Rearrange the queue for
 	      <replaceable>printer-name</replaceable> by placing the jobs with
 	      the listed <replaceable>job</replaceable> numbers or the jobs
 	      belonging to <replaceable>username</replaceable> at the top of
 	      the queue. For this command, you cannot use
 	      <literal>all</literal> as the
 	      <replaceable>printer-name</replaceable>.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><command>up
 	      <replaceable>printer-name</replaceable></command></term>
 		
 	  <listitem>
 	    <para>Bring a printer up; the opposite of the
 	      <command>down</command> command.  Equivalent to
 	      <command>start</command> followed by
 	      <command>enable</command>.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <para>&man.lpc.8; accepts the above commands on the command line.  If
 	you do not enter any commands, &man.lpc.8; enters an interactive mode,
 	where you can enter commands until you type <command>exit</command>,
 	<command>quit</command>, or end-of-file.</para>
     </sect2>
   </sect1>
   
   <sect1 id="printing-lpd-alternatives">
     <title>Alternatives to the Standard Spooler</title>
     
     <para>If you have been reading straight through this manual, by now you
       have learned just about everything there is to know about the 
       <application>LPD</application>
       spooling system that comes with FreeBSD.  You can probably appreciate
       many of its shortcomings, which naturally leads to the question:
       <quote>What other spooling systems are out there (and work with
       FreeBSD)?</quote></para>
 
     <variablelist>
       <varlistentry>
 	<term>LPRng</term>
 
  	<indexterm><primary>LPRng</primary></indexterm>	  
 	<listitem>
 	  <para><application>LPRng</application>, which purportedly means
 	    <quote>LPR: the Next
 	    Generation</quote> is a complete rewrite of PLP.  Patrick Powell
 	    and Justin Mason (the principal maintainer of PLP) collaborated to
 	    make <application>LPRng</application>.  The main site for 
 	    <application>LPRng</application> is <ulink
 	      url="http://www.astart.com/lprng/LPRng.html">http://www.astart.com/lprng/LPRng.html</ulink>.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 
   <sect1 id="printing-troubleshooting">
     <title>Troubleshooting</title>
 
     <para>After performing the simple test with &man.lptest.1;, you might
       have gotten one of the following results instead of the correct
       printout:</para>
 
     <variablelist>
       <varlistentry>
 	<term>It worked, after awhile; or, it did not eject a full
 	  sheet.</term>
 
 	<listitem>
 	  <para>The printer printed the above, but it sat for awhile and
 	    did nothing.  In fact, you might have needed to press a
 	    PRINT REMAINING or FORM FEED button on the printer to get any
 	    results to appear.</para>
 
 	  <para>If this is the case, the printer was probably waiting to
 	    see if there was any more data for your job before it printed
 	    anything.  To fix this problem, you can have the text filter
 	    send a FORM FEED character (or whatever is necessary) to the
 	    printer.  This is usually sufficient to have the printer
 	    immediately print any text remaining in its internal buffer.
 	    It is also useful to make sure each print job ends on a full
 	    sheet, so the next job does not start somewhere on the middle
 	    of the last page of the previous job.</para>
 
 	  <para>The following replacement for the shell script
 	    <filename>/usr/local/libexec/if-simple</filename> prints a
 	    form feed after it sends the job to the printer:</para>
 
 	  <programlisting>#!/bin/sh
 #
 # if-simple - Simple text input filter for lpd
 # Installed in /usr/local/libexec/if-simple
 #
 # Simply copies stdin to stdout.  Ignores all filter arguments.
 # Writes a form feed character (\f) after printing job.
 
 /bin/cat &amp;&amp; printf "\f" &amp;&amp; exit 0
 exit 2</programlisting>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>It produced the <quote>staircase effect.</quote></term>
 
 	<listitem>
 	  <para>You got the following on paper:</para>
 
 	  <programlisting>!"#$%&amp;'()*+,-./01234
                 "#$%&amp;'()*+,-./012345
                                  #$%&amp;'()*+,-./0123456</programlisting>
 
 	  <indexterm><primary>MS-DOS</primary></indexterm>
  	  <indexterm><primary>OS/2</primary></indexterm>
  	  <indexterm><primary>ASCII</primary></indexterm>
 	  <para>You have become another victim of the <emphasis>staircase
 	    effect</emphasis>, caused by conflicting interpretations of
 	    what characters should indicate a new line.  Unix-style
 	    operating systems use a single character:  ASCII code 10, the
 	    line feed (LF). MS-DOS, OS/2, and others uses a pair of
 	    characters, ASCII code 10 <emphasis>and</emphasis> ASCII code
 	    13 (the carriage return or CR).  Many printers use the MS-DOS
 	    convention for representing new-lines.</para>
 
 	  <para>When you print with FreeBSD, your text used just the line
 	    feed character.  The printer, upon seeing a line feed
 	    character, advanced the paper one line, but maintained the
 	    same horizontal position on the page for the next character
 	    to print.  That is what the carriage return is for:  to move
 	    the location of the next character to print to the left edge
 	    of the paper.</para>
 
 	  <para>Here is what FreeBSD wants your printer to do:</para>
 
 	  <informaltable frame="none">
 	    <tgroup cols="2">
 	      <tbody>
 		<row>
 		  <entry>Printer received CR</entry>
 		  <entry>Printer prints CR</entry>
 		</row>
 
 		<row>
 		  <entry>Printer received LF</entry>
 		  <entry>Printer prints CR + LF</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 
 	  <para>Here are some ways to achieve this:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>Use the printer's configuration switches or control
 		panel to alter its interpretation of these characters.
 		Check your printer's manual to find out how to do
 		this.</para>
 
 	      <note>
 	        <para>If you boot your system into other operating systems
 		  besides FreeBSD, you may have to
 		  <emphasis>reconfigure</emphasis> the printer to use a an
 		  interpretation for CR and LF characters that those other
 		  operating systems use.  You might prefer one of the other
 		  solutions, below.</para>
 	      </note>
 	    </listitem>
 
 	    <listitem>
 	      <para>Have FreeBSD's serial line driver automatically
 		convert LF to CR+LF.  Of course, this works with printers
 		on serial ports <emphasis>only</emphasis>.  To enable this
 		feature, set the <literal>CRMOD</literal> bit 
 		in <literal>fs</literal>
 		capability in the <filename>/etc/printcap</filename> file
 		for the printer.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Send an <emphasis>escape code</emphasis> to the
 	        printer to have it temporarily treat LF characters
 		differently.  Consult your printer's manual for escape
 		codes that your printer might support.  When you find the
 		proper escape code, modify the text filter to send the
 		code first, then send the print job.</para>
 
 	      <indexterm><primary>PCL</primary></indexterm>
 	      <para>Here is an example text filter for printers that
 		understand the Hewlett-Packard PCL escape codes.  This
 		filter makes the printer treat LF characters as a LF and
 		CR; then it sends the job; then it sends a form feed to
 		eject the last page of the job.  It should work with
 		nearly all Hewlett Packard printers.</para>
 
 	      <programlisting>#!/bin/sh
 #
 # hpif - Simple text input filter for lpd for HP-PCL based printers
 # Installed in /usr/local/libexec/hpif
 #
 # Simply copies stdin to stdout.  Ignores all filter arguments.
 # Tells printer to treat LF as CR+LF.  Ejects the page when done.
 
 printf "\033&amp;k2G" &amp;&amp; cat &amp;&amp; printf "\033&amp;l0H" &amp;&amp; exit 0
 exit 2</programlisting>
 
 	      <para>Here is an example <filename>/etc/printcap</filename>
 		from a host called <hostid>orchid</hostid>.  It has a single printer
 		attached to its first parallel port, a Hewlett Packard
 		LaserJet 3Si named <literal>teak</literal>.  It is using the
 		above script as its text filter:</para>
 
 	      <programlisting>#
 #  /etc/printcap for host orchid
 #
 teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
         :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\
         :if=/usr/local/libexec/hpif:</programlisting>
 	    </listitem>
           </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>It overprinted each line.</term>
 
 	<listitem>
 	  <para>The printer never advanced a line.  All of the lines of
 	    text were printed on top of each other on one line.</para>
 
 	  <para>This problem is the <quote>opposite</quote> of the
 	    staircase effect, described above, and is much rarer.
 	    Somewhere, the LF characters that FreeBSD uses to end a line
 	    are being treated as CR characters to return the print
 	    location to the left edge of the paper, but not also down a
 	    line.</para>
 
 	  <para>Use the printer's configuration switches or control panel
 	    to enforce the following interpretation of LF and CR
 	    characters:</para>
 
 	  <informaltable frame="none">
 	    <tgroup cols="2">
 	      <thead>
 		<row>
 		  <entry>Printer receives</entry>
 		  <entry>Printer prints</entry>
 		</row>
 	      </thead>
 
 	      <tbody>
 		<row>
 		  <entry>CR</entry>
 		  <entry>CR</entry>
 		</row>
 
 		<row>
 		  <entry>LF</entry>
 		  <entry>CR + LF</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
 	  </informaltable>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>The printer lost characters.</term>
 
 	<listitem>
 	  <para>While printing, the printer did not print a few characters
 	    in each line.  The problem might have gotten worse as the
 	    printer ran, losing more and more characters.</para>
 
 	  <para>The problem is that the printer cannot keep up with the
 	    speed at which the computer sends data over a serial line
 	    (this problem should not occur with printers on parallel
 	    ports).  There are two ways to overcome the problem:</para>
 
 	  <itemizedlist>
 	    <listitem>
 	      <para>If the printer supports XON/XOFF flow control, have
 		FreeBSD use it by specifying the TANDEM bit in the
 		<literal>fs</literal> capability.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>If the printer supports carrier flow control, specify
 		the <literal>MDMBUF</literal> bit in the 
 		<literal>fs</literal> capability.
 		Make sure the cable connecting the printer to the computer
 		is correctly wired for carrier flow control.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>If the printer does not support any flow control, use
 		some combination of the <literal>NLDELAY</literal>,
 		<literal>TBDELAY</literal>, <literal>CRDELAY</literal>,
 		<literal>VTDELAY</literal>, and <literal>BSDELAY</literal>
 		bits in the <literal>fs</literal> capability
 		to add appropriate delays to the stream of data sent to
 		the printer.</para>
 	    </listitem>
 	  </itemizedlist>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>It printed garbage.</term>
 
 	<listitem>
 	  <para>The printer printed what appeared to be random garbage,
 	    but not the desired text.</para>
 
 	  <para>This is usually another symptom of incorrect
 	    communications parameters with a serial printer.  Double-check
 	    the bps rate in the <literal>br</literal> capability, and the
 	    parity bits in the <literal>fs</literal> and
 	    <literal>fc</literal> capabilities; make sure the printer is
 	    using the same settings as specified in the
 	    <filename>/etc/printcap</filename> file.</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>Nothing happened.</term>
 
 	<listitem>
 	  <para>If nothing happened, the problem is probably within
 	    FreeBSD and not the hardware.  Add the log file
 	    (<literal>lf</literal>) capability to the entry for the
 	    printer you are debugging in the
 	    <filename>/etc/printcap</filename> file.  For example, here is
 	    the entry for <literal>rattan</literal>, with the
 	    <literal>lf</literal> capability:</para>
 
 	  <programlisting>rattan|line|diablo|lp|Diablo 630 Line Printer:\
         :sh:sd=/var/spool/lpd/rattan:\
         :lp=/dev/lpt0:\
         :if=/usr/local/libexec/if-simple:\
         :lf=/var/log/rattan.log</programlisting>
 
 	  <para>Then, try printing again.  Check the log file (in our
 	    example, <filename>/var/log/rattan.log</filename>) to see any
 	    error messages that might appear.  Based on the messages you
 	    see, try to correct the problem.</para>
 
 	  <para>If you do not specify a <literal>lf</literal> capability,
 	    <application>LPD</application> uses 
 	    <filename>/dev/console</filename> as a default.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
 </chapter>
 
 <!-- 
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
 
diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
index f8cb0ebd5f..1153a69aba 100644
--- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
@@ -1,3779 +1,3779 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="security">
   <chapterinfo>
     <authorgroup>
       <author>
 	<firstname>Matthew</firstname>
 	<surname>Dillon</surname>
 	<contrib>Much of this chapter has been taken from the
 	security(7) manual page by </contrib>
       </author>
     </authorgroup>
   </chapterinfo>
 
   <title>Security</title>
   <indexterm><primary>security</primary></indexterm>
 
-  <sect1>
+  <sect1 id="security-synopsis">
     <title>Synopsis</title>
 
     <para>This chapter will provide a basic introduction to system security
       concepts, some general good rules of thumb, and some advanced topics
       under FreeBSD.  A lot of the topics covered here can be applied
       to system and Internet security in general as well.  The Internet
       is no longer a <quote>friendly</quote> place in which everyone
       wants to be your kind neighbor.  Securing your system is imperative
       to protect your data, intellectual property, time, and much more
       from the hands of hackers and the like.</para>
 
     <para>FreeBSD provides an array of utilities and mechanisms to
       ensure the integrity and security of your system and
       network.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Basic system security concepts, in respect to FreeBSD.</para>
       </listitem>
 
       <listitem>
 	<para>About the various crypt mechanisms available in FreeBSD,
 	  such as DES and MD5.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup S/Key, an alternative, one-time password
 	  authentication system.</para>
       </listitem>
 
       <listitem>
 	<para>How to setup Kerberos, another alternative
 	  authentication system.</para>
       </listitem>
 
       <listitem>
 	<para>How to create firewalls using IPFW.</para>
       </listitem>
 
       <listitem>
 	<para>How to configure IPsec.</para>
       </listitem>
      
       <listitem>
 	<para>How to configure and use OpenSSH, FreeBSD's SSH
 	  implementation.</para>
       </listitem>
 
       <listitem>
 	<para>How to configure and load access control extension
 	  modules using the TrustedBSD MAC Framework.</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Understand basic FreeBSD and Internet concepts.</para>
       </listitem>
     </itemizedlist>
 
   </sect1>
 
   <sect1 id="security-intro">
     <title>Introduction</title>
 
     <para>Security is a function that begins and ends with the system
       administrator.  While all BSD Unix multi-user systems have some
       inherent security, the job of building and maintaining additional
       security mechanisms to keep those users <quote>honest</quote> is
       probably one of the single largest undertakings of the sysadmin.
       Machines are only as secure as you make them, and security concerns
       are ever competing with the human necessity for convenience.  Unix
       systems, in general, are capable of running a huge number of
       simultaneous processes and many of these processes operate as
       servers &ndash; meaning that external entities can connect and talk
       to them.  As yesterday's mini-computers and mainframes become
       today's desktops, and as computers become networked and
       internetworked, security becomes an even bigger issue.</para>
 
     <para>Security is best implemented through a layered
       <quote>onion</quote> approach.  In a nutshell, what you want to do is
       to create as many layers of security as are convenient and then
       carefully monitor the system for intrusions.  You do not want to
       overbuild your security or you will interfere with the detection
       side, and detection is one of the single most important aspects of
       any security mechanism.  For example, it makes little sense to set
       the <literal>schg</literal> flags (see &man.chflags.1;) on every 
       system binary because
       while this may temporarily protect the binaries, it prevents an
       attacker who has broken in from making an easily detectable change
       that may result in your security mechanisms not detecting the attacker
       at all.</para>
 
     <para>System security also pertains to dealing with various forms of
       attack, including attacks that attempt to crash, or otherwise make a
       system unusable, but do not attempt to compromise the
       <username>root</username> account (<quote>break root</quote>).
       Security concerns
       can be split up into several categories:</para>
 
     <orderedlist>
       <listitem>
 	<para>Denial of service attacks.</para>
       </listitem>
 
       <listitem>
 	<para>User account compromises.</para>
       </listitem>
 
       <listitem>
 	<para>Root compromise through accessible servers.</para>
       </listitem>
 
       <listitem>
 	<para>Root compromise via user accounts.</para>
       </listitem>
 
       <listitem>
 	<para>Backdoor creation.</para>
       </listitem>
     </orderedlist>
 
     <indexterm>
       <primary>DoS attacks</primary>
       <see>Denial of Service (DoS)</see>
     </indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>DoS attacks</secondary>
       <see>Denial of Service (DoS)</see>
     </indexterm>
     <indexterm><primary>Denial of Service (DoS)</primary></indexterm>
 
     <para>A denial of service attack is an action that deprives the
       machine of needed resources.  Typically, DoS attacks are
       brute-force mechanisms that attempt to crash or otherwise make a
       machine unusable by overwhelming its servers or network stack.  Some
       DoS attacks try to take advantage of bugs in the networking
       stack to crash a machine with a single packet.  The latter can only
       be fixed by applying a bug fix to the kernel.  Attacks on servers
       can often be fixed by properly specifying options to limit the load
       the servers incur on the system under adverse conditions.
       Brute-force network attacks are harder to deal with.  A
       spoofed-packet attack, for example, is nearly impossible to stop,
       short of cutting your system off from the Internet.  It may not be
       able to take your machine down, but it can saturate your
       Internet connection.</para>
 
     <indexterm>
       <primary>security</primary>
       <secondary>account compromises</secondary>
     </indexterm>
 
     <para>A user account compromise is even more common than a DoS
       attack.  Many sysadmins still run standard 
       <application>telnetd</application>, <application>rlogind</application>,
       <application>rshd</application>,
       and <application>ftpd</application> servers on their machines.
       These servers, by default, do
       not operate over encrypted connections.  The result is that if you
       have any moderate-sized user base, one or more of your users logging
       into your system from a remote location (which is the most common
       and convenient way to login to a system) will have his or her
       password sniffed.  The attentive system admin will analyze his
       remote access logs looking for suspicious source addresses even for
       successful logins.</para>
 
     <para>One must always assume that once an attacker has access to a
       user account, the attacker can break <username>root</username>.
       However, the reality is that in a well secured and maintained system,
       access to a user account does not necessarily give the attacker
       access to <username>root</username>.  The distinction is important
       because without access to <username>root</username> the attacker
       cannot generally hide his tracks and may, at best, be able to do
       nothing more than mess with the user's files, or crash the machine.
       User account compromises are very common because users tend not to
       take the precautions that sysadmins take.</para>
 
     <indexterm>
       <primary>security</primary>
       <secondary>backdoors</secondary>
     </indexterm>
 
     <para>System administrators must keep in mind that there are
       potentially many ways to break <username>root</username> on a machine.
       The attacker may know the <username>root</username> password,
       the attacker may find a bug in a root-run server and be able
       to break <username>root</username> over a network
       connection to that server, or the attacker may know of a bug in
       a suid-root program that allows the attacker to break
       <username>root</username> once he has broken into a user's account.
       If an attacker has found a way to break <username>root</username>
       on a machine, the attacker may not have a need
       to install a backdoor.  Many of the <username>root</username> holes
       found and closed to date involve a considerable amount of work
       by the attacker to cleanup after himself, so most attackers install
       backdoors.  A backdoor provides the attacker with a way to easily
       regain <username>root</username> access to the system, but it
       also gives the smart system administrator a convenient way
       to detect the intrusion.
       Making it impossible for an attacker to install a backdoor may
       actually be detrimental to your security, because it will not
       close off the hole the attacker found to break in the first
       place.</para>
 
 
     <para>Security remedies should always be implemented with a
       multi-layered <quote>onion peel</quote> approach and can be
       categorized as follows:</para>
 
     <orderedlist>
       <listitem>
 	<para>Securing <username>root</username> and staff accounts.</para>
       </listitem>
 
       <listitem>
 	<para>Securing <username>root</username> &ndash; root-run servers
 	  and suid/sgid binaries.</para>
       </listitem>
 
       <listitem>
 	<para>Securing user accounts.</para>
       </listitem>
 
       <listitem>
 	<para>Securing the password file.</para>
       </listitem>
 
       <listitem>
 	<para>Securing the kernel core, raw devices, and
 	  filesystems.</para>
       </listitem>
 
       <listitem>
 	<para>Quick detection of inappropriate changes made to the
 	  system.</para>
       </listitem>
 
       <listitem>
 	<para>Paranoia.</para>
       </listitem>
     </orderedlist>
 
     <para>The next section of this chapter will cover the above bullet
       items in greater depth.</para>
   </sect1>
 
   <indexterm>
     <primary>security</primary>
     <secondary>securing</secondary>
   </indexterm>
 
   <sect1 id="securing-freebsd">
     <title>Securing FreeBSD</title>
 
     <note>
       <title>Command vs. Protocol</title>
       <para>Throughout this document, we will use
        <application>bold</application> text to refer to a command or
        application.  This is used for instances such as ssh, since it is
        a protocol as well as command.</para>
     </note>
 
     <para>The sections that follow will cover the methods of securing your
       FreeBSD system that were mentioned in the <link
         linkend="security-intro">last section</link> of this chapter.</para>
 
     <sect2 id="securing-root-and-staff">
       <title>Securing the <username>root</username> Account and
 	Staff Accounts</title>
       <indexterm>
         <primary><command>su</command></primary>
       </indexterm>
 
       <para>First off, do not bother securing staff accounts if you have
 	not secured the <username>root</username> account.
 	Most systems have a password assigned to the <username>root</username>
 	account.  The first thing you do is assume
 	that the password is <emphasis>always</emphasis> compromised.
 	This does not mean that you should remove the password.  The
 	password is almost always necessary for console access to the
 	machine.  What it does mean is that you should not make it
 	possible to use the password outside of the console or possibly
 	even with the &man.su.1; command.  For example, make sure that
 	your pty's are specified as being insecure in the
 	<filename>/etc/ttys</filename> file so that direct
 	<username>root</username> logins
 	via <command>telnet</command> or <command>rlogin</command> are
 	disallowed.  If using other login services such as
         <application>sshd</application>, make sure that direct
 	<username>root</username> logins are disabled there as well.
 	You can do this by editing
         your <filename>/etc/ssh/sshd_config</filename> file, and making
         sure that <literal>PermitRootLogin</literal> is set to
         <literal>NO</literal>.  Consider every access method &ndash;
         services such as FTP often fall through the cracks.
 	Direct <username>root</username> logins should only be allowed
 	via the system console.</para>
       <indexterm>
         <primary><groupname>wheel</groupname></primary>
       </indexterm>
 
       <para>Of course, as a sysadmin you have to be able to get to
 	<username>root</username>, so we open up a few holes.
 	But we make sure these holes require additional password
 	verification to operate.  One way to make <username>root</username>
 	accessible is to add appropriate staff accounts to the
 	<groupname>wheel</groupname> group (in
 	<filename>/etc/group</filename>).  The staff members placed in the
 	<groupname>wheel</groupname> group are allowed to
 	<command>su</command> to <username>root</username>.
 	You should never give staff
 	members native <groupname>wheel</groupname> access by putting them in the
 	<groupname>wheel</groupname> group in their password entry.  Staff
 	accounts should be placed in a <groupname>staff</groupname> group, and
 	then added to the <groupname>wheel</groupname> group via the
 	<filename>/etc/group</filename> file.  Only those staff members
 	who actually need to have <username>root</username> access
 	should be placed in the
 	<groupname>wheel</groupname> group.  It is also possible, when using
 	an authentication method such as Kerberos, to use Kerberos'
 	<filename>.k5login</filename> file in the <username>root</username>
 	account to allow a &man.ksu.1; to <username>root</username>
 	without having to place anyone at all in the
 	<groupname>wheel</groupname> group.  This may be the better solution
 	since the <groupname>wheel</groupname> mechanism still allows an
 	intruder to break <username>root</username> if the intruder
 	has gotten hold of your
 	password file and can break into a staff account.  While having
 	the <groupname>wheel</groupname> mechanism is better than having
 	nothing at all, it is not necessarily the safest option.</para>
 
       <para>An indirect way to secure staff accounts, and ultimately
         <username>root</username> access is to use an alternative
 	login access method and
         do what is known as <quote>starring</quote> out the encrypted
         password for the staff accounts.  Using the &man.vipw.8;
         command, one can replace each instance of an encrypted password
         with a single <quote><literal>*</literal></quote> character.
 	This command will update the <filename>/etc/master.passwd</filename>
 	file and user/password database to disable password-authenticated
         logins.</para>
 
       <para>A staff account entry such as:</para>
 
       <programlisting>foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>
 
       <para>Should be changed to this:</para>
 
       <programlisting>foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>
 
       <para>This change will prevent normal logins from occurring,
         since the encrypted password will never match
         <quote><literal>*</literal></quote>.  With this done,
 	staff members must use
         another mechanism to authenticate themselves such as
         &man.kerberos.1; or &man.ssh.1; using a public/private key
         pair.  When using something like Kerberos, one generally must
         secure the machines which run the Kerberos servers and your
         desktop workstation.  When using a public/private key pair
         with ssh, one must generally secure
         the machine used to login <emphasis>from</emphasis> (typically
         one's workstation).  An additional layer of protection can be
         added to the key pair by password protecting the key pair when
         creating it with &man.ssh-keygen.1;.  Being able to
         <quote>star</quote> out the passwords for staff accounts also
         guarantees that staff members can only login through secure
         access methods that you have setup.  This forces all staff
         members to use secure, encrypted connections for all of their
         sessions, which closes an important hole used by many
         intruders: sniffing the network from an unrelated,
         less secure machine.</para>
 
       <para>The more indirect security mechanisms also assume that you are
 	logging in from a more restrictive server to a less restrictive
 	server.  For example, if your main box is running all sorts of
 	servers, your workstation should not be running any.  In order for
 	your workstation to be reasonably secure you should run as few
 	servers as possible, up to and including no servers at all, and
 	you should run a password-protected screen blanker.  Of course,
 	given physical access to a workstation an attacker can break any
 	sort of security you put on it.  This is definitely a problem that
 	you should consider, but you should also consider the fact that the
 	vast majority of break-ins occur remotely, over a network, from
 	people who do not have physical access to your workstation or
 	servers.</para>
       <indexterm><primary>Kerberos</primary></indexterm>
 
       <para>Using something like Kerberos also gives you the ability to
 	disable or change the password for a staff account in one place,
 	and have it immediately effect all the machines on which the staff
 	member may have an account.  If a staff member's account gets
 	compromised, the ability to instantly change his password on all
 	machines should not be underrated.  With discrete passwords,
 	changing a password on N machines can be a mess.  You can also
 	impose re-passwording restrictions with Kerberos:  not only can a
 	Kerberos ticket be made to timeout after a while, but the Kerberos
 	system can require that the user choose a new password after a
 	certain period of time (say, once a month).</para>
     </sect2>
 
     <sect2>
       <title>Securing Root-run Servers and SUID/SGID Binaries</title>
 
       <indexterm>
         <primary><command>ntalk</command></primary>
       </indexterm>
       <indexterm>
         <primary><command>comsat</command></primary>
       </indexterm>
       <indexterm>
         <primary><command>finger</command></primary>
       </indexterm>
       <indexterm>
         <primary>sandboxes</primary>
       </indexterm>
       <indexterm>
         <primary><application>sshd</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>telnetd</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>rshd</application></primary>
       </indexterm>
       <indexterm>
         <primary><application>rlogind</application></primary>
       </indexterm>
 
       <para>The prudent sysadmin only runs the servers he needs to, no
 	more, no less.  Be aware that third party servers are often the
 	most bug-prone.  For example, running an old version of
 	<application>imapd</application> or
 	<application>popper</application> is like giving a universal
 	<username>root</username> ticket out to the entire world.
 	Never run a server that you have not checked out carefully.
 	Many servers do not need to be run as <username>root</username>.
 	For example, the <application>ntalk</application>,
 	<application>comsat</application>, and
 	<application>finger</application> daemons can be run in special
 	user <firstterm>sandboxes</firstterm>.  A sandbox is not perfect,
 	unless you go through a large amount of trouble, but the onion
 	approach to security still stands: If someone is able to break
 	in through a server running in a sandbox, they still have to
 	break out of the sandbox.  The more layers the attacker must
 	break through, the lower the likelihood of his success.  Root
 	holes have historically been found in virtually every server
 	ever run as <username>root</username>, including basic system servers.
 	If you are running a machine through which people only login via
 	<application>sshd</application> and never login via
 	<application>telnetd</application> or
 	<application>rshd</application> or
 	<application>rlogind</application>, then turn off those
 	services!</para>
       
       <para>FreeBSD now defaults to running
 	<application>ntalkd</application>,
 	<application>comsat</application>, and
 	<application>finger</application> in a sandbox.  Another program
 	which may be a candidate for running in a sandbox is &man.named.8;.
 	<filename>/etc/defaults/rc.conf</filename> includes the arguments
 	necessary to run <application>named</application> in a sandbox in a
 	commented-out form.  Depending on whether you are installing a new
 	system or upgrading an existing system, the special user accounts
 	used by these sandboxes may not be installed.  The prudent
 	sysadmin would research and implement sandboxes for servers
 	whenever possible.</para>
       <indexterm>
         <primary><application>sendmail</application></primary>
       </indexterm>
 
       <para>There are a number of other servers that typically do not run
 	in sandboxes: <application>sendmail</application>,
 	<application>popper</application>,
 	<application>imapd</application>, <application>ftpd</application>,
 	and others.  There are alternatives to some of these, but
 	installing them may require more work than you are willing to
 	perform (the convenience factor strikes again).  You may have to
 	run these servers as <username>root</username> and rely on other
 	mechanisms to detect break-ins that might occur through them.</para>
 
       <para>The other big potential <username>root</username> holes in a
 	system are the
 	suid-root and sgid binaries installed on the system.  Most of
 	these binaries, such as <application>rlogin</application>, reside
 	in <filename>/bin</filename>, <filename>/sbin</filename>,
 	<filename>/usr/bin</filename>, or <filename>/usr/sbin</filename>.
 	While nothing is 100% safe, the system-default suid and sgid
 	binaries can be considered reasonably safe.  Still,
 	<username>root</username> holes are occasionally found in these
 	binaries.  A <username>root</username> hole was found in
 	<literal>Xlib</literal> in 1998 that made
 	<application>xterm</application> (which is typically suid)
 	vulnerable.  It is better to be safe than sorry and the prudent
 	sysadmin will restrict suid binaries, that only staff should run,
 	to a special group that only staff can access, and get rid of
 	(<command>chmod 000</command>) any suid binaries that nobody uses.
 	A server with no display generally does not need an
 	<application>xterm</application> binary.  Sgid binaries can be
 	almost as dangerous.  If an intruder can break an sgid-kmem binary,
 	the intruder might be able to read <filename>/dev/kmem</filename>
 	and thus read the encrypted password file, potentially compromising
 	any passworded account.  Alternatively an intruder who breaks
 	group <literal>kmem</literal> can monitor keystrokes sent through
 	pty's, including pty's used by users who login through secure
 	methods.  An intruder that breaks the <groupname>tty</groupname>
 	group can write to
 	almost any user's tty.  If a user is running a terminal program or
 	emulator with a keyboard-simulation feature, the intruder can
 	potentially generate a data stream that causes the user's terminal
 	to echo a command, which is then run as that user.</para>
     </sect2>
 
     <sect2 id="secure-users">
       <title>Securing User Accounts</title>
 
       <para>User accounts are usually the most difficult to secure.  While
 	you can impose Draconian access restrictions on your staff and
 	<quote>star</quote> out their passwords, you may not be able to
 	do so with any general user accounts you might have.  If you do
 	have sufficient control, then you may win out and be able to secure
 	the user accounts properly.  If not, you simply have to be more
 	vigilant in your monitoring of those accounts.  Use of
 	ssh and Kerberos for user accounts is
 	more problematic, due to the extra administration and technical
 	support required, but still a very good solution compared to a
 	crypted password file.</para>
     </sect2>
 
     <sect2>
       <title>Securing the Password File</title>
 
       <para>The only sure fire way is to <literal>*</literal> out as many
 	passwords as you can and use ssh or
 	Kerberos for access to those accounts.  Even though the encrypted
 	password file (<filename>/etc/spwd.db</filename>) can only be read
 	by <username>root</username>, it may be possible for an intruder
 	to obtain read access to that file even if the attacker cannot
 	obtain root-write access.</para>
 
       <para>Your security scripts should always check for and report
 	changes to the password file (see the <link
 	  linkend="security-integrity">Checking file integrity</link> section
 	below).</para>
     </sect2>
 
     <sect2>
       <title>Securing the Kernel Core, Raw Devices, and
 	Filesystems</title>
 
       <para>If an attacker breaks <username>root</username> he can do
         just about anything, but
 	there are certain conveniences.  For example, most modern kernels
 	have a packet sniffing device driver built in.  Under FreeBSD it
 	is called the <devicename>bpf</devicename> device.  An intruder
 	will commonly attempt to run a packet sniffer on a compromised
 	machine.  You do not need to give the intruder the capability and
 	most systems do not have the need for the
 	<devicename>bpf</devicename> device compiled in.</para>
 
       <indexterm>
         <primary><command>sysctl</command></primary>
       </indexterm>
       <para>But even if you turn off the <devicename>bpf</devicename>
 	device, you still have
 	<devicename>/dev/mem</devicename> and 
 	<devicename>/dev/kmem</devicename>
 	to worry about.  For that matter, the intruder can still write to
 	raw disk devices.  Also, there is another kernel feature called
 	the module loader, &man.kldload.8;.  An enterprising intruder can
 	use a KLD module to install his own <devicename>bpf</devicename>
 	device, or other sniffing
 	device, on a running kernel.  To avoid these problems you have to
 	run the kernel at a higher secure level, at least securelevel 1.
 	The securelevel can be set with a <command>sysctl</command> on
 	the <varname>kern.securelevel</varname> variable.  Once you have
 	set the securelevel to 1, write access to raw devices will be
 	denied and special <command>chflags</command> flags,
 	such as <literal>schg</literal>,
 	will be enforced.  You must also ensure that the
 	<literal>schg</literal> flag is set on critical startup binaries,
 	directories, and script files &ndash; everything that gets run up
 	to the point where the securelevel is set.  This might be overdoing
 	it, and upgrading the system is much more difficult when you
 	operate at a higher secure level.  You may compromise and run the
 	system at a higher secure level but not set the
 	<literal>schg</literal> flag for every system file and directory
 	under the sun.  Another possibility is to simply mount
 	<filename>/</filename> and <filename>/usr</filename> read-only.
 	It should be noted that being too Draconian in what you attempt to
 	protect may prevent the all-important detection of an
 	intrusion.</para>
     </sect2>
 
     <sect2 id="security-integrity">
       <title>Checking File Integrity: Binaries, Configuration Files,
 	Etc.</title>
 
       <para>When it comes right down to it, you can only protect your core
 	system configuration and control files so much before the
 	convenience factor rears its ugly head.  For example, using
 	<command>chflags</command> to set the <literal>schg</literal> bit
 	on most of the files in <filename>/</filename> and
 	<filename>/usr</filename> is probably counterproductive, because
 	while it may protect the files, it also closes a detection window.
 	The last layer of your security onion is perhaps the most
 	important &ndash; detection.  The rest of your security is pretty
 	much useless (or, worse, presents you with a false sense of
 	safety) if you cannot detect potential incursions.  Half the job
 	of the onion is to slow down the attacker, rather than stop him, in
 	order to give the detection side of the equation a chance to catch
 	him in the act.</para>
 
       <para>The best way to detect an incursion is to look for modified,
 	missing, or unexpected files.  The best way to look for modified
 	files is from another (often centralized) limited-access system.
 	Writing your security scripts on the extra-secure limited-access
 	system makes them mostly invisible to potential attackers, and this
 	is important.  In order to take maximum advantage you generally
 	have to give the limited-access box significant access to the
 	other machines in the business, usually either by doing a
 	read-only NFS export of the other machines to the limited-access
 	box, or by setting up ssh key-pairs to
 	allow the limited-access box to ssh to
 	the other machines.  Except for its network traffic, NFS is the
 	least visible method &ndash; allowing you to monitor the
 	filesystems on each client box virtually undetected.  If your
 	limited-access server is connected to the client boxes through a
 	switch, the NFS method is often the better choice.  If your
 	limited-access server is connected to the client boxes through a
 	hub, or through several layers of routing, the NFS method may be
 	too insecure (network-wise) and using
 	ssh may be the better choice even with
 	the audit-trail tracks that ssh
 	lays.</para>
 
       <para>Once you give a limited-access box, at least read access to the
 	client systems it is supposed to monitor, you must write scripts
 	to do the actual monitoring.  Given an NFS mount, you can write
 	scripts out of simple system utilities such as &man.find.1; and
 	&man.md5.1;.  It is best to physically md5 the client-box files
 	at least once a day, and to test control files such as those
 	found in <filename>/etc</filename> and
 	<filename>/usr/local/etc</filename> even more often.  When
 	mismatches are found, relative to the base md5 information the
 	limited-access machine knows is valid, it should scream at a
 	sysadmin to go check it out.  A good security script will also
 	check for inappropriate suid binaries and for new or deleted files
 	on system partitions such as <filename>/</filename> and
 	<filename>/usr</filename>.</para>
 
       <para>When using ssh rather than NFS,
 	writing the security script is much more difficult.   You
 	essentially have to <command>scp</command> the scripts to the client 
 	box in order to
 	run them, making them visible, and for safety you also need to
 	<command>scp</command> the binaries (such as find) that those
 	scripts use.  The <application>ssh</application> client on the
 	client box may already be compromised.  All in all, using
 	ssh may be necessary when running over
 	insecure links, but it is also a lot harder to deal with.</para>
 
       <para>A good security script will also check for changes to user and
 	staff members access configuration files:
 	<filename>.rhosts</filename>, <filename>.shosts</filename>,
 	<filename>.ssh/authorized_keys</filename> and so forth&hellip;
 	files that might fall outside the purview of the
 	<literal>MD5</literal> check.</para>
 
       <para>If you have a huge amount of user disk space, it may take too
 	long to run through every file on those partitions.  In this case,
 	setting mount flags to disallow suid binaries and devices on those
 	partitions is a good idea.  The <literal>nodev</literal> and
 	<literal>nosuid</literal> options (see &man.mount.8;) are what you
 	want to look into.  You should probably scan them anyway, at least
 	once a week, since the object of this layer is to detect a break-in
 	whether or not the break-in is effective.</para>
 
       <para>Process accounting (see &man.accton.8;) is a relatively
 	low-overhead feature of the operating system which might help
 	as a post-break-in evaluation mechanism.  It is especially
 	useful in tracking down how an intruder has actually broken into
 	a system, assuming the file is still intact after the break-in
 	occurs.</para>
 
       <para>Finally, security scripts should process the log files, and the
 	logs themselves should be generated in as secure a manner as
 	possible &ndash; remote syslog can be very useful.  An intruder
 	tries to cover his tracks, and log files are critical to the
 	sysadmin trying to track down the time and method of the initial
 	break-in.  One way to keep a permanent record of the log files is
 	to run the system console to a serial port and collect the
 	information on a continuing basis through a secure machine
 	monitoring the consoles.</para>
     </sect2>
 
     <sect2>
       <title>Paranoia</title>
 
       <para>A little paranoia never hurts.  As a rule, a sysadmin can add
 	any number of security features, as long as they do not effect
 	convenience, and can add security features that
 	<emphasis>do</emphasis> effect convenience with some added thought.
 	Even more importantly, a security administrator should mix it up a
 	bit &ndash; if you use recommendations such as those given by this
 	document verbatim, you give away your methodologies to the
 	prospective attacker who also has access to this document.</para>
     </sect2>
 
     <sect2>
       <title>Denial of Service Attacks</title>
       <indexterm><primary>Denial of Service (DoS)</primary></indexterm>
 
       <para>This section covers Denial of Service attacks.  A DoS attack
 	is typically a packet attack.  While there is not much you can do
 	about modern spoofed packet attacks that saturate your network,
 	you can generally limit the damage by ensuring that the attacks
 	cannot take down your servers.</para>
 
       <orderedlist>
 	<listitem>
 	  <para>Limiting server forks.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Limiting springboard attacks (ICMP response attacks, ping
 	    broadcast, etc.).</para>
 	</listitem>
 
 	<listitem>
 	  <para>Kernel Route Cache.</para>
 	</listitem>
       </orderedlist>
 
       <para>A common DoS attack is against a forking server that attempts
 	to cause the server to eat processes, file descriptors, and memory,
 	until the machine dies.  <application>inetd</application>
 	(see &man.inetd.8;) has several
 	options to limit this sort of attack.  It should be noted that
 	while it is possible to prevent a machine from going down, it is
 	not generally possible to prevent a service from being disrupted
 	by the attack.  Read the <application>inetd</application> manual
 	page carefully and pay
 	specific attention to the <option>-c</option>, <option>-C</option>,
 	and <option>-R</option> options.  Note that spoofed-IP attacks
 	will circumvent the <option>-C</option> option to 
 	<application>inetd</application>, so
 	typically a combination of options must be used.  Some standalone
 	servers have self-fork-limitation parameters.</para>
 
       <para><application>Sendmail</application> has its
 	<option>-OMaxDaemonChildren</option> option, which tends to work
 	much better than trying to use sendmail's load limiting options
 	due to the load lag.  You should specify a
 	<literal>MaxDaemonChildren</literal> parameter, when you start
 	<application>sendmail</application>, high enough to handle your
 	expected load, but not so high that the computer cannot handle that
 	number of <application>sendmails</application> without falling on
 	its face.  It is also prudent to run sendmail in queued mode
 	(<option>-ODeliveryMode=queued</option>) and to run the daemon
 	(<command>sendmail -bd</command>) separate from the queue-runs
 	(<command>sendmail -q15m</command>).  If you still want real-time
 	delivery you can run the queue at a much lower interval, such as
 	<option>-q1m</option>, but be sure to specify a reasonable
 	<literal>MaxDaemonChildren</literal> option for
 	<emphasis>that</emphasis> sendmail to prevent cascade failures.</para>
 
       <para><application>Syslogd</application> can be attacked directly
 	and it is strongly recommended that you use the <option>-s</option>
 	option whenever possible, and the <option>-a</option> option
 	otherwise.</para>
 
       <para>You should also be fairly careful with connect-back services
 	such as <application>tcpwrapper</application>'s reverse-identd,
 	which can be attacked directly.  You generally do not want to use
 	the reverse-ident feature of
 	<application>tcpwrappers</application> for this reason.</para>
 
       <para>It is a very good idea to protect internal services from
 	external access by firewalling them off at your border routers.
 	The idea here is to prevent saturation attacks from outside your
 	LAN, not so much to protect internal services from network-based
 	<username>root</username> compromise.
 	Always configure an exclusive firewall, i.e.,
 	<quote>firewall everything <emphasis>except</emphasis> ports A, B,
 	C, D, and M-Z</quote>.  This way you can firewall off all of your
 	low ports except for certain specific services such as
 	<application>named</application> (if you are primary for a zone),
 	<application>ntalkd</application>,
 	<application>sendmail</application>, and other Internet-accessible
 	services.  If you try to configure the firewall the other way
 	&ndash; as an inclusive or permissive firewall, there is a good
 	chance that you will forget to <quote>close</quote> a couple of
 	services, or that you will add a new internal service and forget
 	to update the firewall.  You can still open up the high-numbered
 	port range on the firewall, to allow permissive-like operation,
 	without compromising your low ports.  Also take note that FreeBSD
 	allows you to control the range of port numbers used for dynamic
 	binding, via the various <varname>net.inet.ip.portrange</varname>
 	<command>sysctl</command>'s (<command>sysctl -a | fgrep
 	portrange</command>), which can also ease the complexity of your
 	firewall's configuration.  For example, you might use a normal
 	first/last range of 4000 to 5000, and a hiport range of 49152 to
 	65535, then block off everything under 4000 in your firewall
 	(except for certain specific Internet-accessible ports, of
 	course).</para>
 
       <indexterm><primary>ICMP_BANDLIM</primary></indexterm>
 
       <para>Another common DoS attack is called a springboard attack
 	&ndash; to attack a server in a manner that causes the server to
 	generate responses which overloads the server, the local
 	network, or some other machine.  The most common attack of this
 	nature is the <emphasis>ICMP ping broadcast attack</emphasis>.
 	The attacker spoofs ping packets sent to your LAN's broadcast
 	address with the source IP address set to the actual machine they
 	wish to attack.  If your border routers are not configured to
 	stomp on ping's to broadcast addresses, your LAN winds up
 	generating sufficient responses to the spoofed source address to
 	saturate the victim, especially when the attacker uses the same
 	trick on several dozen broadcast addresses over several dozen
 	different networks at once.  Broadcast attacks of over a hundred
 	and twenty megabits have been measured.  A second common
 	springboard attack is against the ICMP error reporting system.
 	By constructing packets that generate ICMP error responses, an
 	attacker can saturate a server's incoming network and cause the
 	server to saturate its outgoing network with ICMP responses.  This
 	type of attack can also crash the server by running it out of
 	mbuf's, especially if the server cannot drain the ICMP responses
 	it generates fast enough.  The FreeBSD kernel has a new kernel
 	compile option called <option>ICMP_BANDLIM</option>
 	which limits the effectiveness
 	of these sorts of attacks.  The last major class of springboard
 	attacks is related to certain internal 
 	<application>inetd</application> services such as the
 	udp echo service.  An attacker simply spoofs a UDP packet with the
 	source address being server A's echo port, and the destination
 	address being server B's echo port, where server A and B are both
 	on your LAN.  The two servers then bounce this one packet back and
 	forth between each other.  The attacker can overload both servers
 	and their LANs simply by injecting a few packets in this manner.
 	Similar problems exist with the internal 
 	<application>chargen</application> port.  A
 	competent sysadmin will turn off all of these inetd-internal test
 	services.</para>
 
       <para>Spoofed packet attacks may also be used to overload the kernel
 	route cache.  Refer to the <varname>net.inet.ip.rtexpire</varname>,
 	<varname>rtminexpire</varname>, and <varname>rtmaxcache</varname>
 	<command>sysctl</command> parameters.  A spoofed packet attack
 	that uses a random source IP will cause the kernel to generate a
 	temporary cached route in the route table, viewable with
 	<command>netstat -rna | fgrep W3</command>.  These routes
 	typically timeout in 1600 seconds or so.  If the kernel detects
 	that the cached route table has gotten too big it will dynamically
 	reduce the <varname>rtexpire</varname> but will never decrease it 
 	to less than <varname>rtminexpire</varname>.  There are two 
 	problems:</para>
 	
       <orderedlist>
 	<listitem>
 	  <para>The kernel does not react quickly enough when a lightly
 	    loaded server is suddenly attacked.</para>
 	</listitem>
 	
 	<listitem>
 	  <para>The <varname>rtminexpire</varname> is not low enough for
 	    the kernel to survive a sustained attack.</para>
 	</listitem>
       </orderedlist>
       
       <para>If your servers are connected to the Internet via a T3 or
         better, it may be prudent to manually override both
 	<varname>rtexpire</varname> and <varname>rtminexpire</varname>
 	via &man.sysctl.8;.  Never set either parameter to zero (unless
 	you want to crash the machine).  Setting both
 	parameters to 2 seconds should be sufficient to protect the route
 	table from attack.</para>
     </sect2>
 
     <sect2>
       <title>Access Issues with Kerberos and SSH</title>
       <indexterm><primary><command>ssh</command></primary></indexterm>
       <indexterm><primary>Kerberos</primary></indexterm>
 
       <para>There are a few issues with both Kerberos and
 	ssh that need to be addressed if
 	you intend to use them.  Kerberos V is an excellent
 	authentication protocol, but there are bugs in the kerberized
 	<application>telnet</application> and
 	<application>rlogin</application> applications that make them
 	unsuitable for dealing with binary streams.  Also, by default
 	Kerberos does not encrypt a session unless you use the
 	<option>-x</option> option.  <application>ssh</application>
 	encrypts everything by default.</para>
 
       <para>ssh works quite well in every
 	respect except that it forwards encryption keys by default.  What
 	this means is that if you have a secure workstation holding keys
 	that give you access to the rest of the system, and you
 	ssh to an insecure machine, your keys
 	are usable.  The actual keys themselves are not exposed, but
 	ssh installs a forwarding port for the
 	duration of your login, and if an attacker has broken
 	<username>root</username> on the
 	insecure machine he can utilize that port to use your keys to gain
 	access to any other machine that your keys unlock.</para>
 
       <para>We recommend that you use ssh in
 	combination with Kerberos whenever possible for staff logins.
 	<application>ssh</application> can be compiled with Kerberos
 	support.  This reduces your reliance on potentially exposable
 	ssh keys while at the same time
 	protecting passwords via Kerberos.  ssh
 	keys should only be used for automated tasks from secure machines
 	(something that Kerberos is unsuited to do).  We also recommend that
 	you either turn off key-forwarding in the
 	ssh configuration, or that you make use
 	of the <literal>from=IP/DOMAIN</literal> option that
 	ssh allows in its
 	<filename>authorized_keys</filename> file to make the key only
 	usable to entities logging in from specific machines.</para>
     </sect2>
   </sect1>
 
   <sect1 id="crypt">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Bill</firstname>
 	  <surname>Swingle</surname>
 	  <contrib>Parts rewritten and updated by </contrib>
 	</author>
       </authorgroup>
       <!-- 21 Mar 2000 -->
     </sect1info>
 
     <title>DES, MD5, and Crypt</title>
     <indexterm>
       <primary>security</primary>
       <secondary>crypt</secondary>
     </indexterm>
 
     <indexterm><primary>crypt</primary></indexterm>
     <indexterm><primary>DES</primary></indexterm>
     <indexterm><primary>MD5</primary></indexterm>
 
     <para>Every user on a Unix system has a password associated with
       their account.  It seems obvious that these passwords need to be
       known only to the user and the actual operating system.  In
       order to keep these passwords secret, they are encrypted with
       what is known as a <quote>one-way hash</quote>, that is, they can
       only be easily encrypted but not decrypted.  In other words, what
       we told you a moment ago was obvious is not even true:  the
       operating system itself does not <emphasis>really</emphasis> know
       the password.  It only knows the <emphasis>encrypted</emphasis>
       form of the password.  The only way to get the
       <quote>plain-text</quote> password is by a brute force search of the
       space of possible passwords.</para>
 
     <para>Unfortunately the only secure way to encrypt passwords when
       Unix came into being was based on DES, the Data Encryption
       Standard.  This was not such a problem for users resident in
       the US, but since the source code for DES could not be exported
       outside the US, FreeBSD had to find a way to both comply with
       US law and retain compatibility with all the other Unix
       variants that still used DES.</para>
 
     <para>The solution was to divide up the encryption libraries 
       so that US users could install the DES libraries and use
       DES but international users still had an encryption method
       that could be exported abroad.  This is how FreeBSD came to
       use MD5 as its default encryption method.  MD5 is believed to
       be more secure than DES, so installing DES is offered primarily
       for compatibility reasons.</para>
 
     <sect2>
       <title>Recognizing Your Crypt Mechanism</title>
 
       <para>Before FreeBSD&nbsp;4.4 <filename>libcrypt.a</filename> was a
 	symbolic link pointing to the library which was used for
 	encryption.  FreeBSD&nbsp;4.4 changed <filename>libcrypt.a</filename> to
 	provide a configurable password authentication hash library.
 	Currently the library supports DES, MD5 and Blowfish hash
 	functions.  By default FreeBSD uses MD5 to encrypt
 	passwords.</para>
 
       <para>It is pretty easy to identify which encryption method 
 	FreeBSD is set up to use.  Examining the encrypted passwords in
 	the <filename>/etc/master.passwd</filename> file is one way.
 	Passwords encrypted with the MD5 hash are longer than those
 	encrypted with the DES hash and also begin with the characters
 	<literal>&dollar;1&dollar;</literal>.  Passwords starting with
 	<literal>&dollar;2&dollar;</literal> are encrypted with the
 	Blowfish hash function.  DES password strings do not
 	have any particular identifying characteristics, but they are
 	shorter than MD5 passwords, and are coded in a 64-character
 	alphabet which does not include the <literal>&dollar;</literal>
 	character, so a relatively short string which does not begin with
 	a dollar sign is very likely a DES password.</para>
 
       <para>The password format used for new passwords is controlled
 	by the <quote>passwd_format</quote> login capability in
 	<filename>/etc/login.conf</filename>, which takes values of
 	<quote>des</quote> or <quote>md5</quote> or
 	<quote>blf</quote>.  See the &man.login.conf.5; manual page
 	for more information about login capabilities.</para>
 
     </sect2>
   </sect1>
 
   <sect1 id="skey">
     <title>S/Key</title>
     <indexterm><primary>S/Key</primary></indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>S/Key</secondary>
     </indexterm>
 
     <para>S/Key is a one-time password scheme based on a one-way hash
       function.  FreeBSD uses the MD4 hash for compatibility but other
       systems have used MD5 and DES-MAC.  S/Key has been part of the
       FreeBSD base system since version 1.1.5 and is also used on a
       growing number of other operating systems.  S/Key is a registered
       trademark of Bell Communications Research, Inc.</para>
 
     <para>From version 5.0 of FreeBSD, S/Key has been replaced with
       the functionally equivalent OPIE (Onetime Passwords In
       Everything).  OPIE uses the MD5 hash by default.</para>
 
     <para>There are three different sorts of passwords which we will talk
       about in the discussion below.  The first is your usual Unix-style or
       Kerberos password; we will call this a <quote>Unix password</quote>.
       The second sort is the one-time password which is generated by the
       S/Key <command>key</command> program or the OPIE
       <command>opiekey</command> program and accepted by the
       <command>keyinit</command> or <command>opiepasswd</command> programs
       and the login prompt; we will
       call this a <quote>one-time password</quote>.  The final sort of
       password is the secret password which you give to the
       <command>key</command>/<command>opiekey</command> programs (and
       sometimes the
       <command>keyinit</command>/<command>opiepasswd</command> programs)
       which it uses to generate
       one-time passwords; we will call it a <quote>secret password</quote>
       or just unqualified <quote>password</quote>.</para>
 
     <para>The secret password does not have anything to do with your Unix
       password; they can be the same but this is not recommended.  S/Key
       and OPIE secret passwords are not limited to 8 characters like Unix
       passwords, they can be as long as you like.  Passwords of six or
       seven word long phrases are fairly common.  For the most part, the
       S/Key or OPIE system operates completely independently of the Unix
       password system.</para>
 
     <para>Besides the password, there are two other pieces of data that
       are important to S/Key and OPIE.  One is what is known as the
       <quote>seed</quote> or <quote>key</quote>, consisting of two letters
       and five digits.  The other is what is called the <quote>iteration
       count</quote>, a number between 1 and 100.  S/Key creates the
       one-time password by concatenating the seed and the secret password,
       then applying the MD4/MD5 hash as many times as specified by the
       iteration count and turning the result into six short English words.
       These six English words are your one-time password.  The
       authentication system (primarily PAM) keeps
       track of the last one-time password used, and the user is
       authenticated if the hash of the user-provided password is equal to
       the previous password.  Because a one-way hash is used it is
       impossible to generate future one-time passwords if a successfully
       used password is captured; the iteration count is decremented after
       each successful login to keep the user and the login program in
       sync.  When the iteration count gets down to 1, S/Key and OPIE must be
       reinitialized.</para>
 
     <para>There are three programs involved in each system
       which we will discuss below.  The <command>key</command> and
       <command>opiekey</command> programs accept an iteration
       count, a seed, and a secret password, and generate a one-time
       password or a consecutive list of one-time passwords.  The
       <command>keyinit</command> and <command>opiepasswd</command>
       programs are used to initialize S/Key and OPIE respectively,
       and to change passwords, iteration counts, or seeds; they
       take either a secret passphrase, or an iteration count,
       seed, and one-time password.  The <command>keyinfo</command>
       and <command>opieinfo</command> programs examine the
       relevant credentials files (<filename>/etc/skeykeys</filename> or
       <filename>/etc/opiekeys</filename>) and print out the invoking user's
       current iteration count and seed.</para>
 
     <para>There are four different sorts of operations we will cover.  The
       first is using <command>keyinit</command> or
       <command>opiepasswd</command> over a secure connection to set up
       one-time-passwords for the first time,  or to change your password
       or seed.  The second operation is using <command>keyinit</command>
       or <command>opiepasswd</command> over an insecure connection, in
       conjunction with <command>key</command> or <command>opiekey</command>
       over a secure connection,  to do the same.  The third is using
       <command>key</command>/<command>opiekey</command> to log in over
       an insecure connection.  The fourth is using <command>key</command>
       or <command>opiekey</command> to generate a number of keys which
       can be written down or printed out to carry with you when going to
       some location without secure connections to anywhere.</para>
 
     <sect2>
       <title>Secure Connection Initialization</title>
 
       <para>To initialize S/Key for the first time, change your password,
 	or change your seed while logged in over a secure connection
 	(e.g., on the console of a machine or via ssh), use the
 	<command>keyinit</command> command without any parameters while
 	logged in as yourself:</para>
 
       <screen>&prompt.user; <userinput>keyinit</userinput>
 Adding unfurl:
 Reminder - Only use this method if you are directly connected.
 If you are using telnet or rlogin exit with no password and use keyinit -s.
 Enter secret password: 
 Again secret password: 
 
 ID unfurl s/key is 99 to17757
 DEFY CLUB PRO NASH LACE SOFT</screen>
 
       <para>For OPIE, <command>opiepasswd</command> is used instead:</para>
 
       <screen>&prompt.user; <userinput>opiepasswd -c</userinput>
 [grimreaper] ~ $ opiepasswd -f -c
 Adding unfurl:
 Only use this method from the console; NEVER from remote. If you are using
 telnet, xterm, or a dial-in, type ^C now or exit with no password.
 Then run opiepasswd without the -c parameter.
 Using MD5 to compute responses.
 Enter new secret pass phrase:
 Again new secret pass phrase:
 ID unfurl OTP key is 499 to4268
 MOS MALL GOAT ARM AVID COED
 </screen>
 
       <para>At the <prompt>Enter new secret pass phrase:</prompt> or
         <prompt>Enter secret password:</prompt> prompts, you
 	should enter a password or phrase.  Remember, this is not the
 	password that you will use to login with, this is used to generate
 	your one-time login keys.  The <quote>ID</quote> line gives the
 	parameters of your particular instance; your login name, the
         iteration count, and seed.  When logging in the system
 	will remember these parameters and present them back to you so you
 	do not have to remember them.  The last line gives the particular
 	one-time password which corresponds to those parameters and your
 	secret password; if you were to re-login immediately, this
 	one-time password is the one you would use.</para>
     </sect2>
 
     <sect2>
       <title>Insecure Connection Initialization</title>
       
       <para>To initialize or change your secret password over an
 	insecure connection, you will need to already have a secure
 	connection to some place where you can run <command>key</command>
         or <command>opiekey</command>; this might be in the form of a
 	desk accessory on a Macintosh, or a shell prompt on a machine you
 	trust.  You will also need to make up an iteration count (100 is
 	probably a good value), and you may make up your own seed or use a
 	randomly-generated one.  Over on the insecure connection (to the
 	machine you are initializing), use the <command>keyinit
 	-s</command> command:</para>
 
       <screen>&prompt.user; <userinput>keyinit -s</userinput>
 Updating unfurl:
 Old key: to17758
 Reminder you need the 6 English words from the key command.
 Enter sequence count from 1 to 9999: <userinput>100</userinput>
 Enter new key [default to17759]: 
 s/key 100 to 17759
 s/key access password:
 s/key access password:<userinput>CURE MIKE BANE HIM RACY GORE</userinput>
 </screen>
 
       <para>For OPIE, you need to use <command>opiepasswd</command>:</para>
 
       <screen>&prompt.user; <userinput>opiepasswd</userinput>
 
 Updating unfurl:
 You need the response from an OTP generator.
 Old secret pass phrase:
         otp-md5 498 to4268 ext
         Response: GAME GAG WELT OUT DOWN CHAT
 New secret pass phrase:
         otp-md5 499 to4269
         Response: LINE PAP MILK NELL BUOY TROY
 
 ID mark OTP key is 499 gr4269
 LINE PAP MILK NELL BUOY TROY
 </screen>
 
       <para>To accept the default seed (which the
 	<command>keyinit</command> program confusingly calls a
 	<literal>key</literal>), press <keycap>Return</keycap>.
 	Then before entering an
 	access password, move over to your secure connection or S/Key desk
 	accessory, and give it the same parameters:</para>
 
       <screen>&prompt.user; <userinput>key 100 to17759</userinput>
 Reminder - Do not use this program while logged in via telnet or rlogin.
 Enter secret password: <userinput>&lt;secret password&gt;</userinput>
 CURE MIKE BANE HIM RACY GORE</screen>
 
       <para>Or for OPIE:</para>
 
       <screen>&prompt.user; <userinput>opiekey 498 to4268</userinput>
 Using the MD5 algorithm to compute response.
 Reminder: Don't use opiekey from telnet or dial-in sessions.
 Enter secret pass phrase:
 GAME GAG WELT OUT DOWN CHAT
 </screen>
 
       <para>Now switch back over to the insecure connection, and copy the
 	one-time password generated over to the relevant program.</para>
     </sect2>
 
     <sect2>
       <title>Generating a Single one-time Password</title>
 
       <para>Once you have initialized S/Key or OPIE, when you login you will be 
 	presented with a prompt like this:</para>
 
 <screen>&prompt.user; <userinput>telnet example.com</userinput>
 Trying 10.0.0.1...
 Connected to example.com
 Escape character is '^]'.
 
 FreeBSD/i386 (example.com) (ttypa)
 
 login: <userinput>&lt;username&gt;</userinput>
 s/key 97 fw13894
 Password: </screen>
 
       <para>Or for OPIE:</para>
 
 <screen>&prompt.user; <userinput>telnet example.com</userinput>
 Trying 10.0.0.1...
 Connected to example.com
 Escape character is '^]'.
 
 FreeBSD/i386 (example.com) (ttypa)
 
 login: <userinput>&lt;username&gt;</userinput>
 otp-md5 498 gr4269 ext
 Password: </screen>
 
       <para>As a side note, the S/Key and OPIE prompts have a useful feature
 	(not shown here): if you press <keycap>Return</keycap>
 	at the password prompt, the
 	prompter will turn echo on, so you can see what you are
 	typing.  This can be extremely useful if you are attempting to
 	type in a password by hand, such as from a printout.</para>
 
       <indexterm><primary>MS-DOS</primary></indexterm>
       <indexterm><primary>Windows</primary></indexterm>
       <indexterm><primary>MacOS</primary></indexterm>
 
       <para>At this point you need to generate your one-time password to
 	answer this login prompt.  This must be done on a trusted system
 	that you can run <command>key</command> or
         <command>opiekey</command> on.  (There are versions of these for DOS,
 	Windows and MacOS as well.) They need both the iteration count and
 	the seed as command line options.  You can cut-and-paste these
         right from the login prompt on the machine that you are logging
         in to.</para>
 
       <para>On the trusted system:</para>
 
       <screen>&prompt.user; <userinput>key 97 fw13894</userinput>
 Reminder - Do not use this program while logged in via telnet or rlogin.
 Enter secret password: 
 WELD LIP ACTS ENDS ME HAAG</screen>
 
       <para>For OPIE:</para>
 
       <screen>&prompt.user; <userinput>opiekey 498 to4268</userinput>
 Using the MD5 algorithm to compute response.
 Reminder: Don't use opiekey from telnet or dial-in sessions.
 Enter secret pass phrase:
 GAME GAG WELT OUT DOWN CHAT</screen>
 
       <para>Now that you have your one-time password you can continue
 	logging in:</para>
 
       <screen>login: <userinput>&lt;username&gt;</userinput>
 s/key 97 fw13894
 Password: <userinput>&lt;return to enable echo&gt;</userinput>
 s/key 97 fw13894
 Password [echo on]: WELD LIP ACTS ENDS ME HAAG
 Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ... </screen>
 
     </sect2>
 
     <sect2>
       <title>Generating Multiple one-time Passwords</title>
 
       <para>Sometimes you have to go places where you do not have
 	access to a trusted machine or secure connection.  In this case,
 	it is possible to use the <command>key</command> command to
 	generate a number of one-time passwords before hand to be printed
 	out and taken with you.  For example:</para>
 
       <screen>&prompt.user; <userinput>key -n 5 30 zz99999</userinput>
 Reminder - Do not use this program while logged in via telnet or rlogin.
 Enter secret password: <userinput>&lt;secret password&gt;</userinput>
 26: SODA RUDE LEA LIND BUDD SILT 
 27: JILT SPY DUTY GLOW COWL ROT  
 28: THEM OW COLA RUNT BONG SCOT  
 29: COT MASH BARR BRIM NAN FLAG  
 30: CAN KNEE CAST NAME FOLK BILK</screen>
 
       <para>The <option>-n 5</option> requests five keys in sequence, the
 	<option>30</option> specifies what the last iteration number
 	should be.  Note that these are printed out in
 	<emphasis>reverse</emphasis> order of eventual use.  If you are
 	really paranoid, you might want to write the results down by hand;
 	otherwise you can cut-and-paste into <command>lpr</command>.  Note
 	that each line shows both the iteration count and the one-time
 	password; you may still find it handy to scratch off passwords as
 	you use them.</para>
     </sect2>
 
     <sect2>
       <title>Restricting Use of Unix Passwords</title>
 
       <para>Restrictions can be placed on the use of Unix passwords based
 	on the host name, user name, terminal port, or IP address of a
 	login session.  These restrictions can be found in the
 	configuration file <filename>/etc/skey.access</filename>.  The
 	&man.skey.access.5; manual page has more information on the complete
 	format of the file and also details some security cautions to be
 	aware of before depending on this file for security.</para>
 
       <para>If there is no <filename>/etc/skey.access</filename> file
 	(this is the FreeBSD default), then all users will be allowed to
 	use Unix passwords.  If the file exists, however, then all users
 	will be required to use S/Key unless explicitly permitted to do
 	otherwise by configuration statements in the
 	<filename>skey.access</filename> file.  In all cases, Unix
 	passwords are permitted on the console.</para>
 
       <para>Here is a sample configuration file which illustrates the
 	three most common sorts of configuration statements:</para>
 
       <programlisting>permit internet 192.168.0.0 255.255.0.0
 permit user fnord
 permit port ttyd0</programlisting>
 
       <para>The first line (<literal>permit internet</literal>) allows
 	users whose IP source address (which is vulnerable to spoofing)
 	matches the specified value and mask, to use Unix passwords.  This
 	should not be considered a security mechanism, but rather, a means
 	to remind authorized users that they are using an insecure network
 	and need to use S/Key for authentication.</para>
 
       <para>The second line (<literal>permit user</literal>) allows the
 	specified username, in this case <username>fnord</username>, to use
 	Unix passwords at any time.  Generally speaking, this should only
 	be used for people who are either unable to use the
 	<command>key</command> program, like those with dumb terminals, or
 	those who are uneducable.</para>
 
       <para>The third line (<literal>permit port</literal>) allows all
 	users logging in on the specified terminal line to use Unix
 	passwords; this would be used for dial-ups.</para>
     </sect2>
   </sect1>
 
   <sect1 id="kerberos">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Mark</firstname>
 	  <surname>Murray</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
       </authorgroup>
       <authorgroup>
 	<author>
 	  <firstname>Mark</firstname>
 	  <surname>Dapoz</surname>
 	  <contrib>Based on a contribution by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title>Kerberos</title>
     <indexterm><primary>Kerberos</primary></indexterm>
     
     <para>Kerberos is a network add-on system/protocol that allows users to
       authenticate themselves through the services of a secure server.
       Services such as remote login, remote copy, secure inter-system file
       copying and other high-risk tasks are made considerably safer and more
       controllable.</para>
 
     <para>The following instructions can be used as a guide on how to set up
       Kerberos as distributed for FreeBSD.  However, you should refer to the
       relevant manual pages for a complete description.</para>
 
     <sect2>
       <title>Installing Kerberos</title>
 
       <indexterm><primary>MIT</primary></indexterm>
       <indexterm>
 	<primary>Kerberos</primary>
 	<secondary>installing</secondary>
       </indexterm>
       <para>Kerberos is an optional component of FreeBSD.  The easiest
         way to install this software is by selecting the 'krb4' or
         'krb5' distribution in <application>sysinstall</application>
         during the initial installation of FreeBSD.  This will install
         the 'eBones' (KerberosIV) or 'Heimdal' (Kerberos5)
         implementation of Kerberos.  These implementations are
         included because they are developed outside the USA/Canada and
         were thus available to system owners outside those countries
         during the era of restrictive export controls on cryptographic
         code from the USA.</para>
 
       <para>Alternatively, the MIT implementation of Kerberos is
         available from the ports collection as
         <filename role="package">security/krb5</filename>.</para>
     </sect2>
 
     <sect2>
       <title>Creating the Initial Database</title>
       
       <para>This is done on the Kerberos server only.  First make sure that
 	you do not have any old Kerberos databases around.  You should change
 	to the directory <filename>/etc/kerberosIV</filename> and check that
 	only the following files are present:</para>
 	  
       <screen>&prompt.root; <userinput>cd /etc/kerberosIV</userinput>
 &prompt.root; <userinput>ls</userinput>
 README		krb.conf        krb.realms</screen>
 	  
       <para>If any additional files (such as <filename>principal.*</filename>
 	or <filename>master_key</filename>) exist, then use the
 	<command>kdb_destroy</command> command to destroy the old Kerberos
 	database, or if Kerberos is not running, simply delete the extra
 	files.</para>
 	  
       <para>You should now edit the <filename>krb.conf</filename> and
 	<filename>krb.realms</filename> files to define your Kerberos realm.
 	In this case the realm will be <filename>EXAMPLE.COM</filename> and the
 	server is <hostid role="fqdn">grunt.example.com</hostid>.  We edit
 	or create the <filename>krb.conf</filename> file:</para>
 	  
       <screen>&prompt.root; <userinput>cat krb.conf</userinput>
 EXAMPLE.COM
 EXAMPLE.COM grunt.example.com admin server
 CS.BERKELEY.EDU okeeffe.berkeley.edu
 ATHENA.MIT.EDU kerberos.mit.edu
 ATHENA.MIT.EDU kerberos-1.mit.edu
 ATHENA.MIT.EDU kerberos-2.mit.edu
 ATHENA.MIT.EDU kerberos-3.mit.edu
 LCS.MIT.EDU kerberos.lcs.mit.edu
 TELECOM.MIT.EDU bitsy.mit.edu
 ARC.NASA.GOV trident.arc.nasa.gov</screen>
 	  
       <para>In this case, the other realms do not need to be there.  They are
 	here as an example of how a machine may be made aware of multiple
 	realms.  You may wish to not include them for simplicity.</para>
 	  
       <para>The first line names the realm in which this system works.  The
 	other lines contain realm/host entries.  The first item on a line is a
 	realm, and the second is a host in that realm that is acting as a
 	<quote>key distribution center</quote>.  The words <literal>admin
 	  server</literal> following a host's name means that host also
 	provides an administrative database server.  For further explanation
 	of these terms, please consult the Kerberos manual pages.</para>
 	  
       <para>Now we have to add <hostid role="fqdn">grunt.example.com</hostid>
 	to the <filename>EXAMPLE.COM</filename> realm and also add an entry to
 	put all hosts in the <hostid role="domainname">.example.com</hostid>
 	domain in the <filename>EXAMPLE.COM</filename> realm.  The
 	<filename>krb.realms</filename> file would be updated as
 	follows:</para>
 	  
       <screen>&prompt.root; <userinput>cat krb.realms</userinput>
 grunt.example.com EXAMPLE.COM
 .example.com EXAMPLE.COM
 .berkeley.edu CS.BERKELEY.EDU
 .MIT.EDU ATHENA.MIT.EDU
 .mit.edu ATHENA.MIT.EDU</screen>
 	  
       <para>Again, the other realms do not need to be there.  They are here as
 	an example of how a machine may be made aware of multiple realms.  You
 	may wish to remove them to simplify things.</para>
 	  
       <para>The first line puts the <emphasis>specific</emphasis> system into
 	the named realm.  The rest of the lines show how to default systems of
 	a particular subdomain to a named realm.</para>
 	  
       <para>Now we are ready to create the database.  This only needs to run
 	on the Kerberos server (or Key Distribution Center).  Issue the
 	<command>kdb_init</command> command to do this:</para>
 	  
       <screen>&prompt.root; <userinput>kdb_init</userinput>
 <prompt>Realm name [default  ATHENA.MIT.EDU ]:</prompt> <userinput>EXAMPLE.COM</userinput>
 You will be prompted for the database Master Password.
 It is important that you NOT FORGET this password.
 		
 <prompt>Enter Kerberos master key:</prompt> </screen>
 	  
       <para>Now we have to save the key so that servers on the local machine
 	can pick it up.  Use the <command>kstash</command> command to do
 	this.</para>
 	  
       <screen>&prompt.root; <userinput>kstash</userinput>
 	      
 <prompt>Enter Kerberos master key:</prompt>
 
 Current Kerberos master key version is 1.
 
 Master key entered. BEWARE!</screen>
 	  
       <para>This saves the encrypted master password in
 	<filename>/etc/kerberosIV/master_key</filename>.</para>
     </sect2>
     
     <sect2>
       <title>Making It All Run</title>
 	  
       <para>Two principals need to be added to the database for
 	<emphasis>each</emphasis> system that will be secured with Kerberos.
 	Their names are <literal>kpasswd</literal> and <literal>rcmd</literal>
 	These two principals are made for each system, with the instance being
 	the name of the individual system.</para>
 	  
       <para>These daemons, <command>kpasswd</command> and
 	<command>rcmd</command> allow other systems to change Kerberos
 	passwords and run commands like <command>rcp</command>,
 	<command>rlogin</command> and <command>rsh</command>.</para>
 	  
       <para>Now let us add these entries:</para>
 	    
       <screen>&prompt.root; <userinput>kdb_edit</userinput>
 Opening database...
 
 <prompt>Enter Kerberos master key:</prompt>
 
 Current Kerberos master key version is 1.
 
 Master key entered.  BEWARE!
 Previous or default values are in [brackets] ,
 enter return to leave the same, or new value.
 
 <prompt>Principal name:</prompt> <userinput>passwd</userinput>
 <prompt>Instance:</prompt> <userinput>grunt</userinput>
 
 &lt;Not found&gt;, <prompt>Create [y] ?</prompt> <userinput>y</userinput>
 
 Principal: passwd, Instance: grunt, kdc_key_ver: 1
 <prompt>New Password:</prompt>                    &lt;---- enter RANDOM here
 Verifying password
 
 <prompt>New Password:</prompt> &lt;---- enter RANDOM here
 
 <prompt>Random password [y] ?</prompt> <userinput>y</userinput>
 
 Principal's new key version = 1
 <prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
 <prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt>
 <prompt>Attributes [ 0 ] ?</prompt>
 Edit O.K.
 <prompt>Principal name:</prompt> <userinput>rcmd</userinput>
 <prompt>Instance:</prompt> <userinput>grunt</userinput>
 
 &lt;Not found&gt;, <prompt>Create [y] ?</prompt>
 
 Principal: rcmd, Instance: grunt, kdc_key_ver: 1
 <prompt>New Password:</prompt>		&lt;---- enter RANDOM here
 Verifying password
 
 <prompt>New Password:</prompt>           &lt;---- enter RANDOM here
 
 <prompt>Random password [y] ?</prompt>
 
 Principal's new key version = 1
 <prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
 <prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt>
 <prompt>Attributes [ 0 ] ?</prompt>
 Edit O.K.
 <prompt>Principal name:</prompt>         &lt;---- null entry here will cause an exit</screen>
     </sect2>
 
     <sect2>
       <title>Creating the Server File</title>
       
       <para>We now have to extract all the instances which define the
 	services on each machine.  For this we use the
 	<command>ext_srvtab</command> command.  This will create a file
 	which must be copied or moved <emphasis>by secure
 	  means</emphasis> to each Kerberos client's
 	<filename>/etc/kerberosIV</filename> directory.  This file must
 	be present on each server and client, and is crucial to the
 	operation of Kerberos.</para>
 	  
 	  
       <screen>&prompt.root; <userinput>ext_srvtab grunt</userinput>
 <prompt>Enter Kerberos master key:</prompt>
 		
 Current Kerberos master key version is 1.
 
 Master key entered. BEWARE!
 Generating 'grunt-new-srvtab'....</screen>
 	  
       <para>Now, this command only generates a temporary file which must be
 	renamed to <filename>srvtab</filename> so that all the servers can pick
 	it up.  Use the <command>mv</command> command to move it into place on
 	the original system:</para>
 	  
       <screen>&prompt.root; <userinput>mv grunt-new-srvtab srvtab</userinput></screen>
 	  
       <para>If the file is for a client system, and the network is not deemed
 	safe, then copy the
 	<filename><replaceable>client</replaceable>-new-srvtab</filename> to
 	removable media and transport it by secure physical means.  Be sure to
 	rename it to <filename>srvtab</filename> in the client's
 	<filename>/etc/kerberosIV</filename> directory, and make sure it is
 	mode 600:</para>
 	  
       <screen>&prompt.root; <userinput>mv grumble-new-srvtab srvtab</userinput>
 &prompt.root; <userinput>chmod 600 srvtab</userinput></screen>
     </sect2>
     
     <sect2>
       <title>Populating the Database</title>
       
       <para>We now have to add some user entries into the database.  First
 	let us create an entry for the user <username>jane</username>.  Use the
 	<command>kdb_edit</command> command to do this:</para>
 	  
       <screen>&prompt.root; <userinput>kdb_edit</userinput>
 Opening database...
 
 <prompt>Enter Kerberos master key:</prompt>
 
 Current Kerberos master key version is 1.
 
 Master key entered.  BEWARE!
 Previous or default values are in [brackets] ,
 enter return to leave the same, or new value.
 
 <prompt>Principal name:</prompt> <userinput>jane</userinput>
 <prompt>Instance:</prompt>
 
 &lt;Not found&gt;, <prompt>Create [y] ?</prompt> <userinput>y</userinput>
 
 Principal: jane, Instance: , kdc_key_ver: 1
 <prompt>New Password:</prompt>                &lt;---- enter a secure password here
 Verifying password
 
 <prompt>New Password:</prompt>                &lt;---- re-enter the password here
 Principal's new key version = 1
 <prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
 <prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt>
 <prompt>Attributes [ 0 ] ?</prompt>
 Edit O.K.
 <prompt>Principal name:</prompt>		   &lt;---- null entry here will cause an exit</screen>
     </sect2>
 
     <sect2>
       <title>Testing It All Out</title>
       
       <para>First we have to start the Kerberos daemons.  NOTE that if you
 	have correctly edited your <filename>/etc/rc.conf</filename> then this
 	will happen automatically when you reboot.  This is only necessary on
 	the Kerberos server.  Kerberos clients will automagically get what
 	they need from the <filename>/etc/kerberosIV</filename>
 	directory.</para>
 	  
       <screen>&prompt.root; <userinput>kerberos &amp;</userinput>
 Kerberos server starting
 Sleep forever on error
 Log file is /var/log/kerberos.log
 Current Kerberos master key version is 1.
 
 Master key entered. BEWARE!
 
 Current Kerberos master key version is 1
 Local realm: EXAMPLE.COM
 &prompt.root; <userinput>kadmind -n &amp;</userinput>
 KADM Server KADM0.0A initializing
 Please do not use 'kill -9' to kill this job, use a
 regular kill instead
 
 Current Kerberos master key version is 1.
 
 Master key entered.  BEWARE!</screen>
 	  
       <para>Now we can try using the <command>kinit</command> command to get a
 	ticket for the id <username>jane</username> that we created
 	above:</para>
 	  
       <screen>&prompt.user; <userinput>kinit jane</userinput>
 MIT Project Athena (grunt.example.com)
 Kerberos Initialization for "jane"
 <prompt>Password:</prompt> </screen>
 	  
       <para>Try listing the tokens using <command>klist</command> to see if we
 	really have them:</para>
 	  
       <screen>&prompt.user; <userinput>klist</userinput>
 Ticket file:    /tmp/tkt245
 Principal:      jane@EXAMPLE.COM
 
   Issued           Expires          Principal
 Apr 30 11:23:22  Apr 30 19:23:22  krbtgt.EXAMPLE.COM@EXAMPLE.COM</screen>
 	  
       <para>Now try changing the password using <command>passwd</command> to
 	check if the <application>kpasswd</application> daemon can get 
 	authorization to the Kerberos database:</para>
 	  
       <screen>&prompt.user; <userinput>passwd</userinput>
 realm EXAMPLE.COM
 <prompt>Old password for jane:</prompt>
 <prompt>New Password for jane:</prompt>
 Verifying password
 <prompt>New Password for jane:</prompt>
 Password changed.</screen>
     </sect2>
 
     <sect2>
       <title>Adding <command>su</command> Privileges</title>
       
       <para>Kerberos allows us to give <emphasis>each</emphasis> user
 	who needs <username>root</username> privileges their own
 	<emphasis>separate</emphasis> <command>su</command> password.
 	We could now add an id which is authorized to
 	<command>su</command> to <username>root</username>.  This is
 	controlled by having an instance of <username>root</username>
 	associated with a principal.  Using <command>kdb_edit</command>
 	we can create the entry <literal>jane.root</literal> in the
 	Kerberos database:</para>
 	  
       <screen>&prompt.root; <userinput>kdb_edit</userinput>
 Opening database...
 
 <prompt>Enter Kerberos master key:</prompt>
 
 Current Kerberos master key version is 1.
 
 Master key entered.  BEWARE!
 Previous or default values are in [brackets] ,
 enter return to leave the same, or new value.
 
 <prompt>Principal name:</prompt> <userinput>jane</userinput>
 <prompt>Instance:</prompt> <userinput>root</userinput>
 
 &lt;Not found&gt;, Create [y] ? y
 
 Principal: jane, Instance: root, kdc_key_ver: 1
 <prompt>New Password:</prompt>                    &lt;---- enter a SECURE password here
 Verifying password
 
 <prompt>New Password:</prompt>    	 	 &lt;---- re-enter the password here
 
 Principal's new key version = 1
 <prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
 <prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> <userinput>12</userinput> &lt;--- Keep this short!
 <prompt>Attributes [ 0 ] ?</prompt>
 Edit O.K.
 <prompt>Principal name:</prompt>		         &lt;---- null entry here will cause an exit</screen>
 	  
       <para>Now try getting tokens for it to make sure it works:</para>
       
       <screen>&prompt.root; <userinput>kinit jane.root</userinput>
 MIT Project Athena (grunt.example.com)
 Kerberos Initialization for "jane.root"
 <prompt>Password:</prompt></screen>
 	  
       <para>Now we need to add the user to <username>root</username>'s
 	  <filename>.klogin</filename> file:</para>
 	  
       <screen>&prompt.root; <userinput>cat /root/.klogin</userinput>
 jane.root@EXAMPLE.COM</screen>
 	  
       <para>Now try doing the <command>su</command>:</para>
 	  
       <screen>&prompt.user; <userinput>su</userinput>
 <prompt>Password:</prompt></screen>
 	  
       <para>and take a look at what tokens we have:</para>
 	  
       <screen>&prompt.root; <userinput>klist</userinput>
 Ticket file:	/tmp/tkt_root_245
 Principal:      jane.root@EXAMPLE.COM
 
   Issued           Expires          Principal
 May  2 20:43:12  May  3 04:43:12  krbtgt.EXAMPLE.COM@EXAMPLE.COM</screen>
     </sect2>
 
     <sect2>
       <title>Using Other Commands</title>
       
       <para>In an earlier example, we created a principal called
 	<literal>jane</literal> with an instance <literal>root</literal>.
 	This was based on a user with the same name as the principal, and this
 	is a Kerberos default; that a
 	<literal>&lt;principal&gt;.&lt;instance&gt;</literal> of the form
 	<literal>&lt;username&gt;.</literal><username>root</username> will allow
 	that <literal>&lt;username&gt;</literal> to <command>su</command> to
 	<username>root</username> if the necessary entries are in the
 	<filename>.klogin</filename> file in <username>root</username>'s
 	home directory:</para>
 	  
       <screen>&prompt.root; <userinput>cat /root/.klogin</userinput>
 jane.root@EXAMPLE.COM</screen>
       
       <para>Likewise, if a user has in their own home directory lines of the
 	form:</para>
       
       <screen>&prompt.user; <userinput>cat ~/.klogin</userinput>
 jane@EXAMPLE.COM
 jack@EXAMPLE.COM</screen>
 	  
       <para>This allows anyone in the <filename>EXAMPLE.COM</filename> realm
 	who has authenticated themselves to <username>jane</username> or
 	<username>jack</username> (via <command>kinit</command>, see above)
 	access to <command>rlogin</command> to <username>jane</username>'s
 	account or files on this system (<hostid>grunt</hostid>) via
 	<command>rlogin</command>, <command>rsh</command> or
 	<command>rcp</command>.</para>
 	  
       <para>For example, <username>jane</username> now logs into another system using
 	Kerberos:</para>
 	  
 	    <screen>&prompt.user; <userinput>kinit</userinput>
 MIT Project Athena (grunt.example.com)
 <prompt>Password:</prompt>
 &prompt.user; <userinput>rlogin grunt</userinput>
 Last login: Mon May  1 21:14:47 from grumble
 Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
         The Regents of the University of California.   All rights reserved.
 
 FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
 	  
       <para>Or Jack logs into Jane's account on the same machine
 	(<username>jane</username> having
 	set up the <filename>.klogin</filename> file as above, and the person
 	in charge of Kerberos having set up principal
 	<emphasis>jack</emphasis> with a null instance:</para>
 	  
       <screen>&prompt.user; <userinput>kinit</userinput>
 &prompt.user; <userinput>rlogin grunt -l jane</userinput>
 MIT Project Athena (grunt.example.com)
 <prompt>Password:</prompt>
 Last login: Mon May  1 21:16:55 from grumble
 Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
         The Regents of the University of California.   All rights reserved.
 FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
     </sect2>
   </sect1>
   
   <sect1 id="firewalls">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Gary</firstname>
 	  <surname>Palmer</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<author>
 	  <firstname>Alex</firstname>
 	  <surname>Nash</surname>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title>Firewalls</title>
     <indexterm><primary>firewall</primary></indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>firewalls</secondary>
     </indexterm>
 
     <para>Firewalls are an area of increasing interest for people who are
       connected to the Internet, and are even finding applications on private
       networks to provide enhanced security.  This section will hopefully
       explain what firewalls are, how to use them, and how to use the
       facilities provided in the FreeBSD kernel to implement them.</para>
 
     <note>
       <para>People often think that having a firewall between your
 	internal network and the <quote>Big Bad Internet</quote> will solve all
 	your security problems.  It may help, but a poorly setup firewall
 	system is more of a security risk than not having one at all.  A
 	firewall can add another layer of security to your systems, but it
 	cannot stop a really determined cracker from penetrating your internal
 	network.  If you let internal security lapse because you believe your
 	firewall to be impenetrable, you have just made the crackers job that
 	much easier.</para>
     </note>
 
     <sect2>
       <title>What Is a Firewall?</title>
       
       <para>There are currently two distinct types of firewalls in common use
 	on the Internet today.  The first type is more properly called a
 	<emphasis>packet filtering router</emphasis>, where the kernel on a
 	multi-homed machine chooses whether to forward or block packets based
 	on a set of rules.  The second type, known as a <emphasis>proxy
 	  server</emphasis>, relies on daemons to provide authentication and to
 	forward packets, possibly on a multi-homed machine which has kernel
 	packet forwarding disabled.</para>
 	  
       <para>Sometimes sites combine the two types of firewalls, so that only a
 	certain machine (known as a <emphasis>bastion host</emphasis>) is
 	allowed to send packets through a packet filtering router onto an
 	internal network.  Proxy services are run on the bastion host, which
 	are generally more secure than normal authentication
 	mechanisms.</para>
 	  
       <para>FreeBSD comes with a kernel packet filter (known as
 	IPFW), which is what the rest of this
 	section will concentrate on.  Proxy servers can be built on FreeBSD
 	from third party software, but there is such a variety of proxy
 	servers available that it would be impossible to cover them in this
 	section.</para>
 	  
       <sect3 id="firewalls-packet-filters">
 	<title>Packet Filtering Routers</title>
 
 	<para>A router is a machine which forwards packets between two or more
 	  networks.  A packet filtering router has an extra piece of code in
 	  its kernel which compares each packet to a list of rules before
 	  deciding if it should be forwarded or not.  Most modern IP routing
 	  software has packet filtering code within it that defaults to
 	  forwarding all packets.  To enable the filters, you need to define a
 	  set of rules for the filtering code so it can decide if the
 	  packet should be allowed to pass or not.</para>
 	    
 	<para>To decide whether a packet should be passed on, the code looks
 	  through its set of rules for a rule which matches the contents of
 	  this packets headers.  Once a match is found, the rule action is
 	  obeyed.  The rule action could be to drop the packet, to forward the
 	  packet, or even to send an ICMP message back to the originator.
 	  Only the first match counts, as the rules are searched in order.
 	  Hence, the list of rules can be referred to as a <quote>rule
 	  chain</quote>.</para>
 	    
 	<para>The packet matching criteria varies depending on the software
 	  used, but typically you can specify rules which depend on the source
 	  IP address of the packet, the destination IP address, the source
 	  port number, the destination port number (for protocols which
 	  support ports), or even the packet type (UDP, TCP, ICMP,
 	  etc).</para>
       </sect3>
 	  
       <sect3 id="firewalls-proxy-servers">
 	<title>Proxy Servers</title>
 	    
 	<para>Proxy servers are machines which have had the normal system
 	  daemons (<application>telnetd</application>, 
 	  <application>ftpd</application>, etc) replaced with special servers.
 	  These
 	  servers are called <emphasis>proxy servers</emphasis> as they
 	  normally only allow onward connections to be made.  This enables you
 	  to run (for example) a proxy telnet server on your firewall host,
 	  and people can telnet in to your firewall from the outside, go
 	  through some authentication mechanism, and then gain access to the
 	  internal network (alternatively, proxy servers can be used for
 	  signals coming from the internal network and heading out).</para>
 	    
 	<para>Proxy servers are normally more secure than normal servers, and
 	  often have a wider variety of authentication mechanisms available,
 	  including <quote>one-shot</quote> password systems so that even if
 	  someone manages to discover what password you used, they will not be
 	  able to use it to gain access to your systems as the password
 	  instantly expires.  As they do not actually give users access to the
 	  host machine, it becomes a lot more difficult for someone to install
 	  backdoors around your security system.</para>
 	    
 	<para>Proxy servers often have ways of restricting access further, so
 	  that only certain hosts can gain access to the servers, and often
 	  they can be set up so that you can limit which users can talk to
 	  which destination machine.  Again, what facilities are available
 	  depends largely on what proxy software you choose.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>What Does IPFW Allow Me to Do?</title>
       <indexterm><primary><command>ipfw</command></primary></indexterm>
       
       <para>IPFW, the software supplied with
 	FreeBSD, is a packet filtering and accounting system which resides in
 	the kernel, and has a user-land control utility,
 	    &man.ipfw.8;.  Together, they allow you to define and query the
 	rules currently used by the kernel in its routing decisions.</para>
 	  
       <para>There are two related parts to IPFW.
 	The firewall section allows you to perform packet filtering.  There is
 	also an IP accounting section which allows you to track usage of your
 	router, based on similar rules to the firewall section.  This allows
 	you to see (for example) how much traffic your router is getting from
 	a certain machine, or how much WWW (World Wide Web) traffic it is
 	forwarding.</para>
 	  
       <para>As a result of the way that IPFW is
 	designed, you can use IPFW on non-router
 	machines to perform packet filtering on incoming and outgoing
 	connections.  This is a special case of the more general use of
 	IPFW, and the same commands and techniques
 	should be used in this situation.</para>
     </sect2>
 
     <sect2>
       <title>Enabling IPFW on FreeBSD</title>
       <indexterm>
         <primary><command>ipfw</command></primary>
         <secondary>enabling</secondary>
       </indexterm>
       
       <para>As the main part of the IPFW system
 	lives in the kernel, you will need to add one or more options to your
 	kernel configuration file, depending on what facilities you want, and
 	recompile your kernel.  See "Reconfiguring your Kernel" (<xref
 	linkend="kernelconfig">)
 	for more details on how to recompile your
 	kernel.</para>
 
       <warning>
 	<para>IPFW defaults to a policy of <literal>deny ip from any to
 	  any</literal>.  If you do not add other rules during startup to
 	  allow access, <emphasis>you will lock yourself out</emphasis> of the
 	  server upon rebooting into a firewall-enabled kernel.  We suggest
 	  that you set <literal>firewall_type=open</literal> in your
 	  <filename>/etc/rc.conf</filename> file when first enabling this
 	  feature, then refining the firewall rules in
 	  <filename>/etc/rc.firewall</filename> after you have tested that the
 	  new kernel feature works properly.  To be on the safe side, you may
 	  wish to consider performing the initial firewall configuration from
 	  the local console rather than via
 	  <application>ssh</application>.  Another option is to build a kernel
 	  using both the <literal>IPFIREWALL</literal> and
 	  <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal> options.  This will
 	  change the default rule of IPFW to <literal>allow ip from any to
 	  any</literal> and avoid the possibility of a lockout.</para>
       </warning>
 
       <para>There are currently four kernel configuration options relevant to
 	IPFW:</para>
 	  
       <variablelist>
 	<varlistentry>
 	  <term><literal>options IPFIREWALL</literal></term>
 
 	  <listitem>
 	    <para>Compiles into the kernel the code for packet
 	      filtering.</para>
 	  </listitem>
 	</varlistentry>
 	      
 	<varlistentry>
 	  <term><literal>options IPFIREWALL_VERBOSE</literal></term>
 		
 	  <listitem>
 	    <para>Enables code to allow logging of packets through
 		&man.syslogd.8;.  Without this option, even if you specify
 	      that packets should be logged in the filter rules, nothing will
 	      happen.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>options IPFIREWALL_VERBOSE_LIMIT=10</literal></term>
 		
 	  <listitem>
 	    <para>Limits the number of packets logged through
 		&man.syslogd.8; on a per entry basis.  You may wish to use
 	      this option in hostile environments in which you want to log
 	      firewall activity, but do not want to be open to a denial of
 	      service attack via syslog flooding.</para>
 
 	    <para>When a chain entry reaches the packet limit specified,
 	      logging is turned off for that particular entry.  To resume
 	      logging, you will need to reset the associated counter using the
 		&man.ipfw.8; utility:</para>
 	    
 	    <screen>&prompt.root; <userinput>ipfw zero 4500</userinput></screen>
 	    <para>Where 4500 is the chain entry you wish to continue
 	      logging.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><literal>options IPFIREWALL_DEFAULT_TO_ACCEPT</literal></term>
 
 	  <listitem>
 	    <para>This changes the default rule action from <quote>deny</quote>
 	      to <quote>allow</quote>.  This avoids the possibility of locking
 	      yourself out if you happen to boot a kernel with
 	      <literal>IPFIREWALL</literal> support but have not configured
 	      your firewall yet.  It is also very useful if you often use
 	      &man.ipfw.8; as a filter for specific problems as they arise.
 	      Use with care though, as this opens up the firewall and changes
 	      the way it works.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
       
       <note><para>Previous versions of FreeBSD contained an
 	<literal>IPFIREWALL_ACCT</literal>  option.  This is now obsolete as
 	the firewall code automatically  includes accounting
 	facilities.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Configuring IPFW</title>
       <indexterm>
         <primary><command>ipfw</command></primary>
         <secondary>configuring</secondary>
       </indexterm>
       
       <para>The configuration of the IPFW software
 	is done through the &man.ipfw.8; utility.  The syntax for this
 	command looks quite complicated, but it is relatively simple once you
 	understand its structure.</para>
 
       <para>There are currently four different command categories used by the
 	utility: addition/deletion, listing, flushing, and clearing.
 	Addition/deletion is used to build the rules that control how packets
 	are accepted, rejected, and logged.  Listing is used to examine the
 	contents of your rule set (otherwise known as the chain) and packet
 	counters (accounting).  Flushing is used to remove all entries from
 	the chain.  Clearing is used to zero out one or more accounting
 	entries.</para>
 	  
       <sect3>
 	<title>Altering the IPFW Rules</title>
 
 	<para>The syntax for this form of the command is:
 	  <cmdsynopsis>
 	    <command>ipfw</command>
 	    <arg>-N</arg>
 	    <arg choice="plain">command</arg>
 	    <arg>index</arg>
 	    <arg choice="plain">action</arg>
 	    <arg>log</arg>
 	    <arg choice="plain">protocol</arg>
 	    <arg choice="plain">addresses</arg>
 	    <arg>options</arg>
 	  </cmdsynopsis></para>
 
 	<para>There is one valid flag when using this form of the
 	  command:</para>
 
 	<variablelist>
 	  <varlistentry>
 	    <term>-N</term>
 
 	    <listitem>
 	      <para>Resolve addresses and service names in output.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
 	<para>The <emphasis>command</emphasis> given can be shortened to the
 	  shortest unique form.  The valid <emphasis>commands</emphasis>
 	  are:</para>
 	    
 	<variablelist>
 	  <varlistentry>
 	    <term>add</term>
 
 	    <listitem>
 	      <para>Add an entry to the firewall/accounting rule list</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>delete</term>
 	    
 	    <listitem>
 	      <para>Delete an entry from the firewall/accounting rule
 		list</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
 	<para>Previous versions of IPFW used
 	  separate firewall and accounting entries.  The present version
 	  provides packet accounting with each firewall entry.</para>
 	    
 	<para>If an <emphasis>index</emphasis> value is supplied, it is used to
 	  place the entry at a specific point in the chain.  Otherwise, the
 	  entry is placed at the end of the chain at an index 100 greater than
 	  the last chain entry (this does not include the default policy, rule
 	  65535, deny).</para>
 	    
 	<para>The <literal>log</literal> option causes matching rules to be
 	  output to the system console if the kernel was compiled with
 	  <literal>IPFIREWALL_VERBOSE</literal>.</para>
 	    
 	<para>Valid <emphasis>actions</emphasis> are:</para>
 	    
 	<variablelist>
 	  <varlistentry>
 	    <term>reject</term>
 
 	    <listitem>
 	      <para>Drop the packet, and send an ICMP host or port unreachable
 		(as appropriate) packet to the source.</para>
 	    </listitem>
 	  </varlistentry>
 		
 	  <varlistentry>
 	    <term>allow</term>
 	    
 	    <listitem>
 	      <para>Pass the packet on as normal.  (aliases:
 		<literal>pass</literal> and
 		<literal>accept</literal>)</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>deny</term>
 	    
 	    <listitem>
 	      <para>Drop the packet.  The source is not notified via an
 		ICMP message (thus it appears that the packet never
 		arrived at the destination).</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>count</term>
 	    
 	    <listitem>
 	      <para>Update packet counters but do not allow/deny the packet
 		based on this rule.  The search continues with the next chain
 		entry.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
 	<para>Each <emphasis>action</emphasis> will be recognized by the
 	  shortest unambiguous prefix.</para>
 	    
 	<para>The <emphasis>protocols</emphasis> which can be specified
 	  are:</para>
 	    
 	<variablelist>
 	  <varlistentry>
 	    <term>all</term>
 
 	    <listitem>
 	      <para>Matches any IP packet</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>icmp</term>
 	    
 	    <listitem>
 	      <para>Matches ICMP packets</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>tcp</term>
 	    
 	    <listitem>
 	      <para>Matches TCP packets</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>udp</term>
 	    
 	    <listitem>
 	      <para>Matches UDP packets</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
 
 	<para>The <emphasis>address</emphasis> specification is:</para>
 
 	<cmdsynopsis>
 	  <arg choice="plain">from</arg>
 	  <arg choice="plain"><replaceable>address/mask</replaceable></arg><arg><replaceable>port</replaceable></arg>
 	  <arg choice="plain">to</arg>
 	  <arg choice="plain"><replaceable>address/mask</replaceable></arg><arg><replaceable>port</replaceable></arg>
 	  <arg>via <replaceable>interface</replaceable></arg>
 	</cmdsynopsis>
 	    
 	<para>You can only specify <replaceable>port</replaceable> in
 	  conjunction with <emphasis>protocols</emphasis> which support ports
 	  (UDP and TCP).</para>
 	    
 	<para>The <option>via</option> is optional and may specify the IP
 	  address or domain name of a local IP interface, or an interface name
 	  (e.g.  <devicename>ed0</devicename>) to match only packets coming
 	  through this interface.  Interface unit numbers can be specified
 	  with an optional wildcard.  For example, <literal>ppp*</literal>
 	  would match all kernel PPP interfaces.</para>
 	    
 	<para>The syntax used to specify an
 	  <replaceable>address/mask</replaceable> is:
 	  
 	  <screen><replaceable>address</replaceable></screen>
 	      
 	  or
 	      
 	  <screen><replaceable>address</replaceable>/<replaceable>mask-bits</replaceable></screen>
 	      
 	  or
 	      
 	  <screen><replaceable>address</replaceable>:<replaceable>mask-pattern</replaceable></screen>
 	</para>
 
 	<para>A valid hostname may be specified in place of the IP address.
 	  <option><replaceable>mask-bits</replaceable></option> is a decimal
 	  number representing how many bits in the address mask should be set.
 	  e.g.  specifying <hostid role="netmask">192.216.222.1/24</hostid>
 	  will create a
 	  mask which will allow any address in a class C subnet (in this case,
 	  <hostid role="ipaddr">192.216.222</hostid>) to be matched.
 	  <option><replaceable>mask-pattern</replaceable></option> is an IP
 	  address which will be logically AND'ed with the address given.  The
 	  keyword <literal>any</literal> may be used to specify <quote>any IP
 	  address</quote>.</para>
 	    
 	<para>The port numbers to be blocked are specified as:
 	  
 	  <cmdsynopsis>
 	    <arg choice="plain"><replaceable>port</replaceable><arg>,<replaceable>port</replaceable><arg>,<replaceable>port</replaceable><arg>&hellip;</arg></arg></arg></arg>
 	  </cmdsynopsis>
 
 	  to specify either a single port or a list of ports, or
 	  
 	  <cmdsynopsis>
 	    <arg choice="plain"><replaceable>port</replaceable>-<replaceable>port</replaceable></arg>
 	  </cmdsynopsis>
 
 	  to specify a range of ports.  You may also combine a single range
 	  with a list, but the range must always be specified first.</para>
 	    
 	<para>The <emphasis>options</emphasis> available are:</para>
 
 	<variablelist>
 	  <varlistentry>
 	    <term>frag</term>
 
 	    <listitem>
 	      <para>Matches if the packet is not the first fragment of the
 		datagram.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>in</term>
 	    
 	    <listitem>
 	      <para>Matches if the packet is on the way in.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>out</term>
 	    
 	    <listitem>
 	      <para>Matches if the packet is on the way out.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>ipoptions <replaceable>spec</replaceable></term>
 	    
 	    <listitem>
 	      <para>Matches if the IP header contains the comma separated list
 		of options specified in <replaceable>spec</replaceable>.  The
 		supported list of IP options are: <literal>ssrr</literal>
 		(strict source route), <literal>lsrr</literal> (loose source
 		route), <literal>rr</literal> (record packet route), and
 		<literal>ts</literal> (time stamp).  The absence of a
 		particular option may be denoted with a leading
 		<literal>!</literal>.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>established</term>
 	    
 	    <listitem>
 	      <para>Matches if the packet is part of an already established
 		TCP connection (i.e. it has the RST or ACK bits set).  You can
 		optimize the performance of the firewall by placing
 		<emphasis>established</emphasis> rules early in the
 		chain.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>setup</term>
 	    
 	    <listitem>
 	      <para>Matches if the packet is an attempt to establish a TCP
 		connection (the SYN bit is set but the ACK bit is
 		not).</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>tcpflags <replaceable>flags</replaceable></term>
 	    
 	    <listitem>
 	      <para>Matches if the TCP header contains the comma separated
 		list of <replaceable>flags</replaceable>.  The supported flags
 		are <literal>fin</literal>, <literal>syn</literal>,
 		<literal>rst</literal>, <literal>psh</literal>,
 		<literal>ack</literal>, and <literal>urg</literal>.  The
 		absence of a particular flag may be indicated by a leading
 		<literal>!</literal>.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>icmptypes <replaceable>types</replaceable></term>
 	    
 	    <listitem>
 	      <para>Matches if the ICMP type is present in the list
 		<replaceable>types</replaceable>.  The list may be specified
 		as any combination of ranges and/or individual types separated
 		by commas.  Commonly used ICMP types are: <literal>0</literal>
 		echo reply (ping reply), <literal>3</literal> destination
 		unreachable, <literal>5</literal> redirect,
 		<literal>8</literal> echo request (ping request), and
 		<literal>11</literal> time exceeded (used to indicate TTL
 		expiration as with &man.traceroute.8;).</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
       </sect3>
       
       <sect3>
 	<title>Listing the IPFW Rules</title>
 
 	<para>The syntax for this form of the command is:
 	  <cmdsynopsis>
 	    <command>ipfw</command>
 	    <arg>-a</arg>
 	    <arg>-t</arg>
 	    <arg>-N</arg>
 	    <arg choice="plain">l</arg>
 	  </cmdsynopsis></para>
 
 	<para>There are three valid flags when using this form of the
 	  command:</para>
 	    
 	<variablelist>
 	  <varlistentry>
 	    <term>-a</term>
 
 	    <listitem>
 	      <para>While listing, show counter values.  This option is the
 		only way to see accounting counters.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-t</term>
 	    
 	    <listitem>
 	      <para>Display the last match times for each chain entry.  The
 		time listing is incompatible with the input syntax used by the
 		  &man.ipfw.8; utility.</para>
 	    </listitem>
 	  </varlistentry>
 	  
 	  <varlistentry>
 	    <term>-N</term>
 	    
 	    <listitem>
 	      <para>Attempt to resolve given addresses and service
 		names.</para>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
       </sect3>
       
       <sect3>
 	<title>Flushing the IPFW Rules</title>
 
 	<para>The syntax for flushing the chain is:
 	  <cmdsynopsis>
 	    <command>ipfw</command>
 	    <arg choice="plain">flush</arg>
 	  </cmdsynopsis></para>
 
 	<para>This causes all entries in the firewall chain to be removed
 	  except the fixed default policy enforced by the kernel (index
 	  65535).  Use caution when flushing rules, the default deny policy
 	  will leave your system cut off from the network until allow entries
 	  are added to the chain.</para>
       </sect3>
       
       <sect3>
 	<title>Clearing the IPFW Packet Counters</title>
 
 	<para>The syntax for clearing one or more packet counters is:
 	  <cmdsynopsis>
 	    <command>ipfw</command>
 	    <arg choice="plain">zero</arg>
 	    <arg choice="opt"><replaceable>index</replaceable></arg>
 	  </cmdsynopsis></para>
 
 	<para>When used without an <replaceable>index</replaceable> argument,
 	  all packet counters are cleared.  If an
 	  <replaceable>index</replaceable> is supplied, the clearing operation
 	  only affects a specific chain entry.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Example Commands for <application>ipfw</application></title>
       
       <para>This command will deny all packets from the host <hostid
 	  role="fqdn">evil.crackers.org</hostid> to the telnet port of the
 	host <hostid role="fqdn">nice.people.org</hostid>:</para>
 	  	  
       <screen>&prompt.root; <userinput>ipfw add deny tcp from evil.crackers.org to nice.people.org 23</userinput></screen>
 	  
       <para>The next example denies and logs any TCP traffic from the entire
 	<hostid role="domainname">crackers.org</hostid> network (a class C) to
 	the <hostid role="fqdn">nice.people.org</hostid> machine (any
 	port).</para>
 	  
       <screen>&prompt.root; <userinput>ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org</userinput></screen>
 	  
       <para>If you do not want people sending X sessions to your internal
 	network (a subnet of a class C), the following command will do the
 	necessary filtering:</para>
 	  
       <screen>&prompt.root; <userinput>ipfw add deny tcp from any to my.org/28 6000 setup</userinput></screen>
 	  
       <para>To see the accounting records:
 	    
 	<screen>&prompt.root; <userinput>ipfw -a list</userinput></screen>
 
 	or in the short form
 	    
 	<screen>&prompt.root; <userinput>ipfw -a l</userinput></screen>
       </para>
 
       <para>You can also see the last time a chain entry was matched
 	with:</para>
       
       <screen>&prompt.root; <userinput>ipfw -at l</userinput></screen>
     </sect2>
     
     <sect2>
       <title>Building a Packet Filtering Firewall</title>
       
       <note>
 	<para>The following suggestions are just that: suggestions.  The
 	  requirements of each firewall are different and we cannot tell you
 	  how to build a firewall to meet your particular requirements.</para>
       </note>
 	  
       <para>When initially setting up your firewall, unless you have a test
 	bench setup where you can configure your firewall host in a controlled
 	environment, it is strongly recommend you use the logging version of the
 	commands and enable logging in the kernel.  This will allow you to
 	quickly identify problem areas and cure them without too much
 	disruption.  Even after the initial setup phase is complete, I
 	recommend using the logging for `deny' as it allows tracing of
 	possible attacks and also modification of the firewall rules if your
 	requirements alter.</para>
 	  
       <note>
 	<para>If you use the logging versions of the <command>accept</command>
 	  command, it can generate <emphasis>large</emphasis> amounts of log
 	  data as one log line will be generated for every packet that passes
 	  through the firewall, so large FTP/http transfers, etc, will really
 	  slow the system down.  It also increases the latencies on those
 	  packets as it requires more work to be done by the kernel before the
 	  packet can be passed on.  <application>syslogd</application> will 
 	  also start using up a lot
 	  more processor time as it logs all the extra data to disk, and it
 	  could quite easily fill the partition <filename>/var/log</filename>
 	  is located on.</para>
       </note>
 	  
       <para>You should enable your firewall from
 	<filename>/etc/rc.conf.local</filename> or
 	<filename>/etc/rc.conf</filename>.  The associated manual page explains
 	which knobs to fiddle and lists some preset firewall configurations.
 	If you do not use a preset configuration, <command>ipfw list</command>
 	will output the current ruleset into a file that you can
 	pass to <filename>rc.conf</filename>.  If you do not use
 	<filename>/etc/rc.conf.local</filename> or
 	<filename>/etc/rc.conf</filename> to enable your firewall,
 	it is important to make sure your firewall is enabled before
 	any IP interfaces are configured.</para>
 	  
       <para>The next problem is what your firewall should actually
 	<emphasis>do</emphasis>! This is largely dependent on what access to
 	your network you want to allow from the outside, and how much access
 	to the outside world you want to allow from the inside.  Some general
 	rules are:</para>
       
       <itemizedlist>
 	<listitem>
 	  <para>Block all incoming access to ports below 1024 for TCP.  This is
 	    where most of the security sensitive services are, like finger,
 	    SMTP (mail) and telnet.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Block <emphasis>all</emphasis> incoming UDP traffic.  There
 	    are very few useful services that travel over UDP, and what useful
 	    traffic there is, is normally a security threat (e.g. Suns RPC and
 	    NFS protocols).  This has its disadvantages also, since UDP is a
 	    connectionless protocol, denying incoming UDP traffic also blocks
 	    the replies to outgoing UDP traffic.  This can cause a problem for
 	    people (on the inside) using external archie (prospero) servers.
 	    If you want to allow access to archie, you will have to allow
 	    packets coming from ports 191 and 1525 to any internal UDP port
 	    through the firewall.  <application>ntp</application> is another
 	    service you may consider allowing through, which comes from port
 	    123.</para>
 	</listitem>
 	      
 	<listitem>
 	  <para>Block traffic to port 6000 from the outside.  Port 6000 is the
 	    port used for access to X11 servers, and can be a security threat
 	    (especially if people are in the habit of doing <command>xhost
 	      +</command> on their workstations).  X11 can actually use a
 	    range of ports starting at 6000, the upper limit being how many X
 	    displays you can run on the machine.  The upper limit as defined
 	    by RFC 1700 (Assigned Numbers) is 6063.</para>
 	</listitem>
 	      
 	<listitem>
 	  <para>Check what ports any internal servers use (e.g. SQL servers,
 	    etc).  It is probably a good idea to block those as well, as they
 	    normally fall outside the 1-1024 range specified above.</para>
 	</listitem>
       </itemizedlist>
 	  
       <para>Another checklist for firewall configuration is available from
 	CERT at <ulink
 	  url="http://www.cert.org/tech_tips/packet_filtering.html">http://www.cert.org/tech_tips/packet_filtering.html</ulink></para>
 	  
       <para>As stated above, these are only <emphasis>guidelines</emphasis>.
 	You will have to decide what filter rules you want to use on your
 	firewall yourself.  We cannot accept ANY responsibility if someone
 	breaks into your network, even if you follow the advice given
 	above.</para>
     </sect2>
 
     <sect2 id="ipfw-overhead">
       <title>IPFW Overhead and Optimization</title>
 
       <para>Many people want to know how much overhead IPFW adds to a
 	system.  The answer to this depends mostly on your rule set and
 	processor speed.  For most applications dealing with Ethernet
 	and small rule sets, the answer is
 	<quote>negligible</quote>.  For those of you that need actual
 	measurements to satisfy your curiosity, read on.</para>
 
       <para>The following measurements were made using 2.2.5-STABLE on
 	a 486-66.  (While IPFW has changed slightly in later releases
 	of FreeBSD, it still performs with similar speed.) IPFW was
 	modified to measure the time spent within the
 	<literal>ip_fw_chk</literal> routine, displaying the results
 	to the console every 1000 packets.</para>
 
       <para>Two rule sets, each with 1000 rules were tested.  The
 	first set was designed to demonstrate a worst case scenario by
 	repeating the rule:</para>
 
       <screen>&prompt.root; <userinput>ipfw add deny tcp from any to any 55555</userinput></screen>
 
       <para>This demonstrates worst case by causing most of IPFW's
 	packet check routine to be executed before finally deciding
 	that the packet does not match the rule (by virtue of the port
 	number).  Following the 999th iteration of this rule was an
 	<literal>allow ip from any to any</literal>.</para>
 
       <para>The second set of rules were designed to abort the rule
 	check quickly:</para>
 
       <screen>&prompt.root; <userinput>ipfw add deny ip from 1.2.3.4 to 1.2.3.4</userinput></screen>
 
       <para>The non-matching source IP address for the above rule
 	causes these rules to be skipped very quickly.  As before, the
 	1000th rule was an <literal>allow ip from any to
 	any</literal>.</para>
 
       <para>The per-packet processing overhead in the former case was
 	approximately 2.703&nbsp;ms/packet, or roughly 2.7&nbsp;microseconds per
 	rule.  Thus the theoretical packet processing limit with these
 	rules is around 370&nbsp;packets per second.  Assuming 10&nbsp;Mbps
 	Ethernet and a ~1500&nbsp;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.172&nbsp;ms, or roughly 1.2&nbsp;microseconds per rule.
 	The theoretical packet processing limit here would be about
 	853&nbsp;packets per second, which could consume 10&nbsp;Mbps Ethernet
 	bandwidth.</para>
 
       <para>The excessive number of rules tested and the nature of
 	those rules do not provide a real-world scenario -- they were
 	used only to generate the timing information presented here.
 	Here are a few things to keep in mind when building an
 	efficient rule set:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>Place an <literal>established</literal> rule early on
 	    to handle the majority of TCP traffic.  Do not put any
 	    <literal>allow tcp</literal> statements before this
 	    rule.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Place heavily triggered rules earlier in the rule set
 	    than those rarely used (<emphasis>without changing the
 	    permissiveness of the firewall</emphasis>, of course).
 	    You can see which rules are used most often by examining
 	    the packet counting statistics with <command>ipfw -a
 	    l</command>.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
   </sect1>
 
   <sect1 id="openssl">
     <title>OpenSSL</title>
     <indexterm>
       <primary>security</primary>
       <secondary>OpenSSL</secondary>
     </indexterm>
     <indexterm><primary>OpenSSL</primary></indexterm>
 
     <para>As of FreeBSD&nbsp;4.0, the OpenSSL toolkit is a part of the base
       system.  <ulink url="http://www.openssl.org/">OpenSSL</ulink>
       provides a general-purpose cryptography library, as well as the
       Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer
       Security v1 (TLSv1) network security protocols.</para>
 
     <para>However, one of the algorithms (specifically IDEA)
       included in OpenSSL is protected by patents in the USA and
       elsewhere, and is not available for unrestricted use.
       IDEA is included in the OpenSSL sources in FreeBSD, but it is not
       built by default.  If you wish to use it, and you comply with the
       license terms, enable the <literal>MAKE_IDEA</literal> switch in
       <filename>/etc/make.conf</filename> and
       rebuild your sources using <command>make world</command>.</para>
 
     <para>Today, the RSA algorithm is free for use in USA and other
       countries.  In the past it was protected by a patent.</para>
 
     <indexterm>
       <primary>OpenSSL</primary>
       <secondary>install</secondary>
     </indexterm>
 
     <sect2>
       <title>Source Code Installations</title>
       
       <para>OpenSSL is part of the <literal>src-crypto</literal> and
 	<literal>src-secure</literal> cvsup collections.  See the <link
 	linkend="mirrors">Obtaining FreeBSD</link> section for more
 	information about obtaining and updating FreeBSD source
 	code.</para>
     </sect2>
   </sect1>
 
   <sect1 id="ipsec">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Yoshinobu</firstname>
 	  <surname>Inoue</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<!-- 5 Mar 2000 -->
       </authorgroup>
     </sect1info>
 
     <title>IPsec</title>
     <indexterm><primary>IPsec</primary></indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>IPsec</secondary>
     </indexterm>
 
     <note>
       <title>Terminating Characters</title>
       <para>Throughout examples in this section, and other sections,
 	you will notice that there is a <quote>^D</quote> at the end
 	of some examples.  This means to hold down the <keycap>Control</keycap>
 	key and hit the <keycap>D</keycap> key.  Another commonly used
 	character is <quote>^C</quote>, which respectively means to hold
 	down <keycap>Control</keycap> and press <keycap>C</keycap>.</para>
     </note>
 
     <tip>
       <para>For other HOWTOs detailing IPsec implementation in
         FreeBSD, take a look at <ulink
         url="http://www.daemonnews.org/200101/ipsec-howto.html"></ulink>
         and <ulink
         url="http://www.freebsddiary.org/ipsec.php"></ulink>.</para>
     </tip>
 
     <para>The IPsec mechanism provides secure communication for IP
       layer and socket layer communication.  This section should
       explain how to use them.  For implementation details, please
       refer to <ulink
       url="../developers-handbook/ipv6.html">The
       Developers' Handbook</ulink>.</para>
 
     <para>The current IPsec implementation supports both transport mode
       and tunnel mode.  However, tunnel mode comes with some restrictions.
       <ulink url="http://www.kame.net/newsletter/">http://www.kame.net/newsletter/
       </ulink> has more comprehensive examples.</para>
 
     <para>Please be aware that in order to use this functionality, you
       must have the following options compiled into your kernel:</para>
 
     <programlisting>options          IPSEC              #IP security
 options          IPSEC_ESP          #IP security (crypto; define w/IPSEC)</programlisting>
 
     <sect2>
       <title>Transport Mode Example with IPv4</title>
 
       <para>Let us setup security association to deploy a secure channel
         between HOST A (<hostid role="ipaddr">10.2.3.4</hostid>) and
         HOST B (<hostid role="ipaddr">10.6.7.8</hostid>).
         Here we show a little
         complicated example.  From HOST A to HOST B, only old AH is used.
         From HOST B to HOST A, new AH and new ESP are combined.</para>
 
       <para>Now we should choose an algorithm to be used corresponding to
         <quote>AH</quote>/<quote>new AH</quote>/<quote>ESP</quote>/
 	<quote>new ESP</quote>.  Please refer to the &man.setkey.8; man
         page to know algorithm names.  Our choice is MD5 for AH, new-HMAC-SHA1
         for new AH, and new-DES-expIV with 8 byte IV for new ESP.</para>
 
       <para>Key length highly depends on each algorithm.  For example, key
         length must be equal to 16 bytes for MD5, 20 for new-HMAC-SHA1,
         and 8 for new-DES-expIV.  Now we choose <quote>MYSECRETMYSECRET</quote>,
         <quote>KAMEKAMEKAMEKAMEKAME</quote>, <quote>PASSWORD</quote>,
 	respectively.</para>
 
       <para>OK, let us assign SPI (Security Parameter Index) for each protocol.
         Please note that we need 3 SPIs for this secure channel since three
         security headers are produced (one for from HOST A to HOST B, two for
         from HOST B to HOST A).  Please also note that SPI MUST be greater
         than or equal to 256.  We choose, 1000, 2000, and 3000,
 	respectively.</para>
 
       <screen>
 	         (1)
 	HOST A ------> HOST B
 
 	(1)PROTO=AH
 		ALG=MD5(RFC1826)
 		KEY=MYSECRETMYSECRET
 		SPI=1000
 
 	         (2.1)
 	HOST A <------ HOST B
 	       <------
 	         (2.2)
 
 	(2.1)
 	PROTO=AH
 		ALG=new-HMAC-SHA1(new AH)
 		KEY=KAMEKAMEKAMEKAMEKAME
 		SPI=2000
 
 	(2.2)
 	PROTO=ESP
 		ALG=new-DES-expIV(new ESP)
 			IV length = 8
 		KEY=PASSWORD
 		SPI=3000
 </screen>
 
       <para>Now, let us setup security association.  Execute &man.setkey.8;
         on both HOST A and B:</para>
 
       <screen>&prompt.root; <userinput>setkey -c
     add 10.2.3.4 10.6.7.8 ah-old  1000 -m transport -A keyed-md5 "MYSECRETMYSECRET" ;
     add 10.6.7.8 10.2.3.4 ah  2000 -m transport -A hmac-sha1 "KAMEKAMEKAMEKAMEKAME" ;
     add 10.6.7.8 10.2.3.4 esp 3000 -m transport -E des-cbc "PASSWORD" ;
     ^D</userinput></screen>
 
      <para>Actually, IPsec communication does not process until security policy
        entries are defined.  In this case, you must setup each host.</para>
 
      <screen>
 At A:
 
 &prompt.root; <userinput>setkey -c
     spdadd 10.2.3.4 10.6.7.8 any -P out ipsec
 	ah/transport/10.2.3.4-10.6.7.8/require ;
     ^D</userinput>
 
 At B:
 
 &prompt.root; <userinput>setkey -c
     spdadd 10.6.7.8 10.2.3.4 any -P out ipsec
 	esp/transport/10.6.7.8-10.2.3.4/require ;
     spdadd 10.6.7.8 10.2.3.4 any -P out ipsec
 	ah/transport/10.6.7.8-10.2.3.4/require ;
     ^D</userinput>
 
 
    HOST A --------------------------------------> HOST E
   10.2.3.4                                       10.6.7.8
           |                                     |
           ========== old AH keyed-md5 ==========>
 
           <========= new AH hmac-sha1 ===========
           <========= new ESP des-cbc ============
 </screen>
     </sect2>
 
     <sect2>
       <title>Transport Mode Example with IPv6</title>
 
       <para>Another example using IPv6.</para>
 
       <para>ESP transport mode is recommended for TCP port number 110 between
         Host-A and Host-B.</para>
 
       <screen>
               ============ ESP ============
               |                           |
            Host-A                        Host-B
           fec0::10 -------------------- fec0::11
 </screen>
 
       <para>Encryption algorithm is blowfish-cbc whose key is
 	<quote>kamekame</quote>, and authentication algorithm is hmac-sha1
 	whose key is <quote>this is the test key</quote>.
 	Configuration at Host-A:</para>
 
       <screen>&prompt.root; <userinput>setkey -c &lt;&lt;<filename>EOF</filename>
     spdadd fec0::10[any] fec0::11[110] tcp -P out ipsec
 	esp/transport/fec0::10-fec0::11/use ;
     spdadd fec0::11[110] fec0::10[any] tcp -P in ipsec
 	esp/transport/fec0::11-fec0::10/use ;
     add fec0::10 fec0::11 esp 0x10001
 	-m transport
 	-E blowfish-cbc "kamekame"
 	-A hmac-sha1 "this is the test key" ;
     add fec0::11 fec0::10 esp 0x10002
 	-m transport
 	-E blowfish-cbc "kamekame"
 	-A hmac-sha1 "this is the test key" ;
     EOF</userinput></screen>
 
       <para>and at Host-B:</para>
 
       <screen>&prompt.root; <userinput>setkey -c &lt;&lt;<filename>EOF</filename>
     spdadd fec0::11[110] fec0::10[any] tcp -P out ipsec
 	esp/transport/fec0::11-fec0::10/use ;
     spdadd fec0::10[any] fec0::11[110] tcp -P in ipsec
 	esp/transport/fec0::10-fec0::11/use ;
     add fec0::10 fec0::11 esp 0x10001 -m transport
 	-E blowfish-cbc "kamekame"
 	-A hmac-sha1 "this is the test key" ;
     add fec0::11 fec0::10 esp 0x10002 -m transport
 	-E blowfish-cbc "kamekame"
 	-A hmac-sha1 "this is the test key" ;
     EOF</userinput></screen>
 
       <para>Note the direction of SP.</para>
     </sect2>
 
     <sect2>
       <title>Tunnel Mode Example with IPv4</title>
 
       <para>Tunnel mode between two security gateways</para>
 
       <para>Security protocol is old AH tunnel mode, i.e. specified by
         RFC1826, with keyed-md5 whose key is <quote>this is the test</quote> as
         authentication algorithm.</para>
 
       <screen>
                              ======= AH =======
                              |                |
          Network-A       Gateway-A        Gateway-B        Network-B
         10.0.1.0/24 ---- 172.16.0.1 ----- 172.16.0.2 ---- 10.0.2.0/24
 </screen>
 
       <para>Configuration at Gateway-A:</para>
 
       <screen>&prompt.root; <userinput>setkey -c &lt;&lt;<filename>EOF</filename>
     spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec
 	ah/tunnel/172.16.0.1-172.16.0.2/require ;
     spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec
 	ah/tunnel/172.16.0.2-172.16.0.1/require ;
     add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any
 	-A keyed-md5 "this is the test" ;
     add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any
 	-A keyed-md5 "this is the test" ;
 
 EOF</userinput></screen>
 
       <para>If the port number field is omitted such as above then
 	<literal>[any]</literal> is employed.  <literal>-m</literal>
 	specifies the mode of SA to be used.  <literal>-m any</literal> means
 	wild-card of mode of security protocol.  You can use this SA for both
 	tunnel and transport mode.</para>
 
       <para>and at Gateway-B:</para>
 
       <screen>&prompt.root; <userinput>setkey -c &lt;&lt;<filename>EOF</filename>
     spdadd 10.0.2.0/24 10.0.1.0/24 any -P out ipsec
 	ah/tunnel/172.16.0.2-172.16.0.1/require ;
     spdadd 10.0.1.0/24 10.0.2.0/24 any -P in ipsec
 	ah/tunnel/172.16.0.1-172.16.0.2/require ;
     add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any
 	-A keyed-md5 "this is the test" ;
     add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any
 	-A keyed-md5 "this is the test" ;
 
 EOF</userinput></screen>
 
       <para>Making SA bundle between two security gateways</para>
 
       <para>AH transport mode and ESP tunnel mode is required between
         Gateway-A and Gateway-B.  In this case, ESP tunnel mode is
         applied first, and AH transport mode is next.</para>
 
       <screen>
                             ========== AH =========
                             |  ======= ESP =====  |
                             |  |               |  |
        Network-A          Gateway-A        Gateway-B           Network-B
     fec0:0:0:1::/64 --- fec0:0:0:1::1 ---- fec0:0:0:2::1 --- fec0:0:0:2::/64
 </screen>
     </sect2>
 
     <sect2>
       <title>Tunnel Mode Example with IPv6</title>
 
       <para>Encryption algorithm is 3des-cbc, and authentication algorithm
         for ESP is hmac-sha1.  Authentication algorithm for AH is hmac-md5.
         Configuration at Gateway-A:</para>
 
       <screen>&prompt.root; <userinput>setkey -c &lt;&lt;<filename>EOF</filename>
     spdadd fec0:0:0:1::/64 fec0:0:0:2::/64 any -P out ipsec
 	esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require
 	ah/transport/fec0:0:0:1::1-fec0:0:0:2::1/require ;
     spdadd fec0:0:0:2::/64 fec0:0:0:1::/64 any -P in ipsec
 	esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require
 	ah/transport/fec0:0:0:2::1-fec0:0:0:1::1/require ;
     add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10001 -m tunnel
 	-E 3des-cbc "kamekame12341234kame1234"
 	-A hmac-sha1 "this is the test key" ;
     add fec0:0:0:1::1 fec0:0:0:2::1 ah 0x10001 -m transport
 	-A hmac-md5 "this is the test" ;
     add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10001 -m tunnel
 	-E 3des-cbc "kamekame12341234kame1234"
 	-A hmac-sha1 "this is the test key" ;
     add fec0:0:0:2::1 fec0:0:0:1::1 ah 0x10001 -m transport
 	-A hmac-md5 "this is the test" ;
 
     EOF</userinput></screen>
 
       <para>Making SAs with the different end</para>
 
       <para>ESP tunnel mode is required between Host-A and Gateway-A.
 	Encryption algorithm is cast128-cbc, and authentication algorithm
 	for ESP is hmac-sha1.  ESP transport mode is recommended between
 	Host-A and Host-B.  Encryption algorithm is rc5-cbc, and
 	authentication algorithm for ESP is hmac-md5.</para>
 
       <screen>
               ================== ESP =================
               |  ======= ESP =======                 |
               |  |                 |                 |
              Host-A            Gateway-A           Host-B
           fec0:0:0:1::1 ---- fec0:0:0:2::1 ---- fec0:0:0:2::2
 </screen>
 
       <para>Configuration at Host-A:</para>
 
       <screen>&prompt.root; <userinput>setkey -c &lt;&lt;<filename>EOF</filename>
     spdadd fec0:0:0:1::1[any] fec0:0:0:2::2[80] tcp -P out ipsec
 	esp/transport/fec0:0:0:1::1-fec0:0:0:2::2/use
 	esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ;
     spdadd fec0:0:0:2::1[80] fec0:0:0:1::1[any] tcp -P in ipsec
 	esp/transport/fec0:0:0:2::2-fec0:0:0:l::1/use
 	esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ;
     add fec0:0:0:1::1 fec0:0:0:2::2 esp 0x10001
 	-m transport
 	-E cast128-cbc "12341234"
 	-A hmac-sha1 "this is the test key" ;
     add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10002
 	-E rc5-cbc "kamekame"
 	-A hmac-md5 "this is the test" ;
     add fec0:0:0:2::2 fec0:0:0:1::1 esp 0x10003
 	-m transport
 	-E cast128-cbc "12341234"
 	-A hmac-sha1 "this is the test key" ;
     add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10004
 	-E rc5-cbc "kamekame"
 	-A hmac-md5 "this is the test" ;
 
     EOF</userinput></screen>
     </sect2>
   </sect1>
 
   <sect1 id="openssh">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Chern</firstname>
 	  <surname>Lee</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
 	<!-- 21 April 2001 -->
       </authorgroup>
     </sect1info>
 
     <title>OpenSSH</title>
     <indexterm><primary>OpenSSH</primary></indexterm>
     <indexterm>
       <primary>security</primary>
       <secondary>OpenSSH</secondary>
     </indexterm>
 
     <para>Secure shell is a set of network connectivity tools used to
       access remote machines securely.  It can be used as a direct
       replacement for <command>rlogin</command>,
       <command>rsh</command>, <command>rcp</command>, and
       <command>telnet</command>.  Additionally, any other TCP/IP
       connections can be tunneled/forwarded securely through ssh.
       ssh encrypts all traffic to effectively eliminate eavesdropping,
       connection hijacking, and other network-level attacks.</para>
 
     <para>OpenSSH is maintained by the OpenBSD project, and is based
       upon SSH v1.2.12 with all the recent bug fixes and updates.  It
       is compatible with both SSH protocols 1 and 2.  OpenSSH has been
       in the base system since FreeBSD&nbsp;4.0.</para>
 
     <sect2>
       <title>Advantages of Using OpenSSH</title>
   
       <para>Normally, when using &man.telnet.1; or &man.rlogin.1;,
         data is sent over the network in an clear, un-encrypted form.
         Network sniffers anywhere in between the client and server can
         steal your user/password information or data transferred in
         your session.  OpenSSH offers a variety of authentication and
         encryption methods to prevent this from happening.</para>
     </sect2>
 
     <sect2>
       <title>Enabling sshd</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>enabling</secondary>
       </indexterm>
 
       <para>Be sure to make the following additions to your 
         <filename>rc.conf</filename> file:</para>
       <screen>sshd_enable="YES"</screen>
       <para>This will load the <application>ssh</application> daemon
 	the next time your system initializes.  Alternatively, you can
 	simply run the <application>sshd</application> daemon.</para>
     </sect2>
 
     <sect2>
       <title>SSH Client</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>client</secondary>
       </indexterm>
 
       <para>The &man.ssh.1; utility works similarly to 
         &man.rlogin.1;.</para>
 
       <screen>&prompt.root; <userinput>ssh <replaceable>user@example.com</replaceable></userinput>
 Host key not found from the list of known hosts.
 Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput>
 Host 'example.com' added to the list of known hosts.
 user@example.com's password: <userinput>*******</userinput></screen>
 
       <para>The login will continue just as it would have if a session was
         created using <command>rlogin</command> or
         <command>telnet</command>.  SSH utilizes a key fingerprint
         system for verifying the authenticity of the server when the 
         client connects.  The user is prompted to enter
 	<literal>yes</literal> only when
         connecting for the first time.  Future attempts to login are all
         verified against the saved fingerprint key.  The SSH client
         will alert you if the saved fingerprint differs from the
         received fingerprint on future login attempts.  The fingerprints
         are saved in <filename>~/.ssh/known_hosts</filename>, or
 	<filename>~/.ssh/known_hosts2</filename> for SSH v2
 	fingerprints.</para>
 
       <para>By default, OpenSSH servers are configured to accept both
 	SSH v1 and SSH v2 connections.  The client, however, can choose
 	between the two.  Version 2 is known to be more robust and
 	secure than its predecessor.</para>
 
       <para><command>ssh</command> can be forced to use either protocol
 	by passing it the <option>-1</option> or <option>-2</option> argument
 	for v1 and v2, respectively.</para>
     </sect2>
     
     <sect2>
       <title>Secure Copy</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>secure copy</secondary>
       </indexterm>
       <indexterm><primary><command>scp</command></primary></indexterm>
 
       <para>The <command>scp</command> command works similarly to
 	<command>rcp</command>; it copies a file to or from a remote machine,
 	except in a secure fashion.</para>
 
       <screen>&prompt.root; <userinput> scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput>
 user@example.com's password: <userinput>*******</userinput>
 COPYRIGHT            100% |*****************************|  4735       
 00:00    
 &prompt.root;</screen>
       <para>Since the fingerprint was already saved for this host in the
         previous example, it is verified when using <command>scp</command>
         here.</para>
 
       <para>The arguments passed to <command>scp</command> are similar
 	to <command>cp</command>, with the file or files in the first
 	argument, and the destination in the second.  Since the file is
 	fetched over the network, through SSH, one or more of the file
 	arguments takes on the form
 	<option>user@host:&lt;path_to_remote_file></option>.</para>
 
     </sect2>
 
     <sect2>
       <title>Configuration</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>configuration</secondary>
       </indexterm>
 
       <para>The system-wide configuration files for both the OpenSSH 
         daemon and client reside within the <filename>/etc/ssh</filename> 
         directory.</para>
 
       <para><filename>ssh_config</filename> configures the client 
         settings, while <filename>sshd_config</filename> configures the 
         daemon.</para>
 
       <para>Additionally, the <option>sshd_program</option>
 	(<filename>/usr/sbin/sshd</filename> by default), and
 	<option>sshd_flags</option> <filename>rc.conf</filename>
 	options can provide more levels of configuration.</para>
     </sect2>
 
     <sect2>
       <title>ssh-keygen</title>
 
       <para>Instead of using passwords, &man.ssh-keygen.1; can
         be used to generate RSA keys to authenticate a user.</para>
 
       <screen>&prompt.user; <userinput>ssh-keygen</userinput>
 Initializing random number generator...
 Generating p:  .++ (distance 66)
 Generating q:  ..............................++ (distance 498)
 Computing the keys...
 Key generation complete.
 Enter file in which to save the key (/home/user/.ssh/identity):
 Enter passphrase:
 Enter the same passphrase again:
 Your identification has been saved in /home/user/.ssh/identity.
 ...</screen>
 
       <para>&man.ssh-keygen.1; will create a public and private
         key pair for use in authentication.  The private key is stored in
         <filename>~/.ssh/identity</filename>, whereas the public key is
         stored in <filename>~/.ssh/identity.pub</filename>.  The public
         key must be placed in <filename>~/.ssh/authorized_keys</filename>
         of the remote machine in order for the setup to work.</para>
 
       <para>This will allow connection to the remote machine based upon
         RSA authentication instead of passwords.</para>
 
       <para>If a passphrase is used in &man.ssh-keygen.1;, the user
         will be prompted for a password each time in order to use the private
         key.</para>
 
       <para>A SSH v2 DSA key can be created for the same purpose by using
 	the <command>ssh-keygen -d</command> command (or
 	<command>ssh-keygen -t dsa</command> for FreeBSD &os.current;).
 	This will
 	create a public/private DSA key for use in SSH v2 sessions only.
 	The public key is stored in <filename>~/.ssh/id_dsa.pub</filename>,
 	while the private key is in <filename>~/.ssh/id_dsa</filename>.</para>
 
       <para>DSA public keys are placed in
 	<filename>~/.ssh/authorized_keys2</filename> on the remote
 	machine.</para>
 
       <para>&man.ssh-agent.1; and &man.ssh-add.1; are 
         utilities used in managing multiple passworded private keys.</para>
     </sect2>
 
     <sect2>
       <title>SSH Tunneling</title>
       <indexterm>
         <primary>OpenSSH</primary>
         <secondary>tunneling</secondary>
       </indexterm>
 
       <para>OpenSSH has the ability to create a tunnel to encapsulate
         another protocol in an encrypted session.</para>
 
       <para>The following command tells &man.ssh.1; to create a tunnel 
          for telnet.</para>
 
        <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5023:localhost:23 user@foo.example.com</replaceable></userinput>
 &prompt.user;</screen>
 
       <para>The <command>ssh</command> command is used with the
 	following options:</para>
 
       <variablelist>
 	<varlistentry>
 	  <term><option>-2</option></term>
 	  
 	  <listitem>
 	    <para>Forces <command>ssh</command> to use version 2 of
 	      the protocol. (Do not use if you are working with older
 	      ssh servers)</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-N</option></term>
 
 	  <listitem>
 	    <para>Indicates no command, or tunnel only.  If omitted,
 	      <command>ssh</command> would initiate a normal
 	      session.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-f</option></term>
 
 	  <listitem>
 	    <para>Forces <command>ssh</command> to run in the
 	      background.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
 	  <term><option>-L</option></term>
 
 	  <listitem>
 	    <para>Indicates a local tunnel in
 	      <replaceable>localport:remotehost:remoteport</replaceable>
 	      fashion.</para>
 	  </listitem>
 	  </varlistentry>
 
 	<varlistentry>
 	  <term><option>user@foo.example.com</option></term>
 
 	  <listitem>
 	    <para>The remote SSH server.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
 
       <para>An SSH tunnel works by creating a listen socket on
 	<hostid>localhost</hostid> on the specified port.
 	It then forwards any connection received
 	on the local host/port via the SSH connection to the specified
 	remote host and port.</para>
 
       <para>In the example, port <replaceable>5023</replaceable> on
 	<hostid>localhost</hostid> is being forwarded to port
 	<replaceable>23</replaceable> on <hostid>localhost</hostid>
 	of the remote machine.  Since <replaceable>23</replaceable> is telnet,
 	this would create a secure telnet session through an SSH tunnel.</para>
 
       <para>This can be used to wrap any number of insecure TCP protocols 
         such as SMTP, POP3, FTP, etc.</para>
 
       <example>
 	<title>Using SSH to create a secure tunnel for SMTP</title>
 
         <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput>
 user@mailserver.example.com's password: <userinput>*****</userinput>
 &prompt.user; <userinput>telnet localhost 5025</userinput>
 Trying 127.0.0.1...
 Connected to localhost.
 Escape character is '^]'.
 220 mailserver.example.com ESMTP</screen>     
 
         <para>This can be used in conjunction with an
           &man.ssh-keygen.1; and additional user accounts to create a
           more seamless/hassle-free SSH tunneling environment.  Keys
           can be used in place of typing a password, and the tunnels
           can be run as a separate user.</para>
       </example>
 
       <sect3>
 	<title>Practical SSH Tunneling Examples</title>
 
 	<sect4>
 	  <title>Secure Access of a POP3 server</title>
 
 	  <para>At work, there is an SSH server that accepts
 	    connections from the outside.  On the same office network
 	    resides a mail server running a POP3 server.  The network,
 	    or network path between your home and office may or may not
 	    be completely trustable.  Because of this, you need to check
 	    your e-mail in a secure manner.  The solution is to create
 	    an SSH connection to your office's SSH server, and tunnel
 	    through to the mail server.</para>
 
 	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput>
 user@ssh-server.example.com's password: <userinput>******</userinput></screen>
 
 	  <para>When the tunnel is up and running, you can point your
 	    mail client to send POP3 requests to <hostid>localhost</hostid>
 	    port 2110.  A connection here will be forwarded securely across
 	    the tunnel to <hostid>mail.example.com</hostid>.</para>
 	</sect4>
 
 	<sect4>
 	  <title>Bypassing a Draconian Firewall</title>
 
 	  <para>Some network administrators impose extremely Draconian
 	    firewall rules, filtering not only incoming connections,
 	    but outgoing connections.  You may be only given access
 	    to contact remote machines on ports 22 and 80 for SSH
 	    and web surfing.</para>
 
 	  <para>You may wish to access another (perhaps non-work
 	    related) service, such as an Ogg Vorbis server to stream
 	    music.  If this Ogg Vorbis server is streaming on some other
 	    port than 22 or 80, you will not be able to access it.</para>
 
 	  <para>The solution is to create an SSH connection to a machine
 	    outside of your network's firewall, and use it to tunnel to
 	    the Ogg Vorbis server.</para>
 
 	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled.myserver.com</replaceable></userinput>
 user@unfirewalled.myserver.com's password: <userinput>*******</userinput></screen>
 
 	  <para>Your streaming client can now be pointed to
 	    <hostid>localhost</hostid> port 8888, which will be
 	    forwarded over to <hostid>music.example.com</hostid> port
 	    8000, successfully evading the firewall.</para>
         </sect4>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
       <para><ulink url="http://www.openssh.com/">OpenSSH</ulink></para>
       <para>&man.ssh.1; &man.scp.1; &man.ssh-keygen.1; 
         &man.ssh-agent.1; &man.ssh-add.1;</para>
       <para>&man.sshd.8; &man.sftp-server.8;</para>
     </sect2>
   </sect1>
 
   <sect1 id="mac">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Robert</firstname>
 	  <surname>Watson</surname>
 	  <contrib>Sponsored by DARPA and Network Associates Laboratories.
 	    Contributed by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
     <indexterm>
       <primary>MAC</primary>
     </indexterm>
     <title>Mandatory Access Control (MAC)</title>
 
     <para>FreeBSD 5.0 includes a new kernel security framework, the
       TrustedBSD MAC Framework.  The MAC Framework permits compile-time,
       boot-time, and run-time extension of the kernel access control
       policy, and can be used to load support for Mandatory Access
       Control (<acronym>MAC</acronym>), and custom security modules
       such as hardening modules.  The MAC Framework is currently
       considered to be an experimental feature, and should not yet
       be used in production environments without careful consideration.
       It is anticipated that the MAC Framework will be appropriate for
       more widespread production use by FreeBSD 5.2.</para>
 
     <para>When configured into a kernel, the MAC Framework permits
       security modules to augment the existing kernel access control
       model, restricting access to system services and objects.  For
       example, the &man.mac.bsdextended.4; module augments file system
       access control, permitting administrators to provide a
       firewall-like ruleset constraining access to file system objects
       based on user ids and group membership.  Some modules require
       little or no configuration, such as &man.mac.seeotheruids.4,
       whereas others perform ubiquitous object labeling, such as
       &man.mac.biba.4; and &man.mac.mls.4;, and require extensive
       configuration.</para>
 
     <para>To enable the MAC Framework in your system kernel, you must
       add the following entry to your kernel configuration:</para>
 
     <programlisting>options MAC</programlisting>
 
     <para>Security policy modules shipped with the base system may
      be loaded using &man.kldload.8; or in the boot &man.loader.8;
      They may also be compiled directly into the kernel using the
      following options, if the use of modules is not desired.</para>
 
     <para>Different MAC policies may be configured in different ways;
       frequently, MAC policy modules export configuration parameters
       using the &man.sysctl.8; <acronym>MIB</acronym> using the
       <varname>security.mac</varname> namespace.  Policies relying on
       file system or other labels may require a configuration step
       that involes assigning initial labels to system objects or
       creating a policy configuration file.  For information on how to
       configure and use each policy module, see its man page.</para>
 
     <para>A variety of tools are available to configure the MAC Framework
       and labels maintained by various policies.  Extensions have been
       made to the login and credential management mechanisms
       (&man.setusercontext.3;) to support initial user labeling using
       &man.login.conf.5;.  In addition, modifications have been made
       to &man.su.1;, &man.ps.1;, &man.ls.1;, and &man.ifconfig.8; to
       inspect and set labels on processes, files, and interfaces.  In
       addition, several new tools have been added to manage labels
       on objects, including &man.getfmac.8;, &man.setfmac.8;, and
       &man.setfsmac.8; to manage labels on files, and &man.getpmac.8; and
       &man.setpmac.8;.</para>
 
     <para>What follows is a list of policy modules shipped with FreeBSD
       5.0.</para>
     <sect2 id="mac-policy-biba">
       <title>Biba Integrity Policy (mac_biba)</title>
       <indexterm>
 	<primary>Biba Integrity Policy</primary>
       </indexterm>
       <para>Vendor: TrustedBSD Project</para>
       <para>Module name: mac_biba.ko</para>
       <para>Kernel option: <literal>MAC_BIBA</literal></para>
       <indexterm>
 	<primary>TCB</primary>
       </indexterm>
       <para>The Biba Integrity Policy (&man.mac.biba.4;) provides
 	for hierarchical and non-hierarchical labeling of all system
 	objects with integrity data, and the strict enforcement of
 	an information flow policy to prevent corruption of high
 	integrity subjects and data by low-integrity subjects.
 	Integrity is enforced by preventing high integrity
 	subjects (generally processes) from reading low integrity
 	objects (often files), and preventing low integrity
 	subjects from writing to high integrity objects.
 	This security policy is frequently used in commercial
 	trusted systems to provide strong protection for the
 	Trusted Code Base (<acronym>TCB</acronym>).  Because it
 	provides ubiquitous labeling, the Biba integrity policy
 	must be compiled into the kernel or loaded at boot.</para>
     </sect2>
     <sect2 id="mac-policy-bsdextended">
       <title>File System Firewall Policy (mac_bsdextended)</title>
       <indexterm>
 	<primary>File System Firewall Policy</primary>
       </indexterm>
       <para>Vendor: TrustedBSD Project</para>
       <para>Module name: mac_bsdextended.ko</para>
       <para>Kernel option: <literal>MAC_BSDEXTENDED</literal></para>
       <para> The File System Firewall Policy (&man.mac.bsdextended.4;)
 	provides an extension to the BSD file system permission model,
 	permitting the administrator to define a set of firewall-like
 	rules for limiting access to file system objects owned by
 	other users and groups.  Managed using &man.ugidfw.8;, rules
 	may limit access to files and directories based on the uid
 	and gids of the process attempting the access, and the owner
 	and group of the target of the access attempt.  All rules
 	are restrictive, so they may be placed in any order.  This policy
 	requires no prior configuration or labeling, and may be
 	appropriate in multi-user environments where mandatory limits
 	on inter-user data exchange are required.  Caution should be
 	exercised in limiting access to files owned by the super-user or
 	other system user ids, as many useful programs and directories
 	are owned by these users.  As with a network firewall,
 	improper application of file system firewall rules may render
 	the system unusable.  New tools to manage the rule set may be
 	easily written using the &man.libugidfw.3; library.</para>
     </sect2>
     <sect2 id="mac-policy-ifoff">
       <title>Interface Silencing Policy (mac_ifoff)</title>
       <indexterm>
 	<primary>Interface Silencing Policy</primary>
       </indexterm>
       <para>Vendor: TrustedBSD Project</para>
       <para>Module name: mac_ifoff.ko</para>
       <para>Kernel option: <literal>MAC_IFOFF</literal></para>
       <para>The interface silencing policy (&man.mac.ifoff.4;)
 	prohibits the use of network interfaces during the boot
 	until explicitly enabled, preventing spurious stack output
 	stack response to incoming packets.  This is appropriate
 	for use in environments where the monitoring of packets
 	is required, but no traffic may be generated.</para>
     </sect2>
     <sect2 id="mac-policy-lomac">
       <title>Low-Watermark Mandatory Access Control (LOMAC)
 	(mac_lomac)</title>
       <indexterm>
 	<primary>Low-Watermark Mandatory Access Control</primary>
       </indexterm>
       <indexterm>
 	<primary>LOMAC</primary>
       </indexterm>
       <para>Vendor: Network Associates Laboratories</para>
       <para>Module name: mac_lomac.ko</para>
       <para>Kernel option: <literal>MAC_LOMAC</literal></para>
       <para>Similar to the Biba Integrity Policy, the LOMAC
 	policy (&man.mac.lomac.4;) relies on the ubiquitous
 	labeling of all system objects with integrity labels.
 	Unlike Biba, LOMAC permits high integrity subjects to
 	read from low integrity objects, but then downgrades the
 	label on the subject to prevent future writes to high
 	integrity objects.  This policy may provide for greater
 	compatibility, as well as require less initial
 	configuration than Biba.  However, as with Biba, it
 	ubiquitously labels objects and must therefore be
 	compiled into the kernel or loaded at boot.</para>
     </sect2>
     <sect2 id="mac-policy-mls">
       <title>Multi-Level Security Policy (MLS) (mac_mls)</title>
       <indexterm>
 	<primary>Multi-Level Security Policy</primary>
       </indexterm>
       <indexterm>
 	<primary>MLS</primary>
       </indexterm>
       <para>Vendor: TrustedBSD Project</para>
       <para>Module name: mac_mls.ko</para>
       <para>Kernel option: <literal>MAC_MLS</literal></para>
       <para>Multi-Level Security (<acronym>MLS</acronym>)
         (&man.mac.mls.4;) provides for hierarchical and non-hierarchical
         labeling of all system objects with sensitivity data, and the
         strict enforcement of an information flow policy to prevent
         the leakage of confidential data to untrusted parties.  The
         logical conjugate of the Biba Integrity Policy,
         <acronym>MLS</acronym> is frequently shipped in commercial
         trusted operating systems to protect data secrecy in
         multi-user environments.  Hierarchal labels provide support
         for the notion of clearances and classifications in
         traditional parlance; non-hierarchical labels provide support
         for <quote>need-to-know.</quote>  As with Biba, ubiquitous
         labeling of objects occurs, and it must therefore be compiled
         into the kernel or loaded at boot.  As with Biba, extensive
         initial configuration may be required.</para>
     </sect2>
     <sect2 id="mac-policy-none">
       <title>MAC Stub Policy (mac_none)</title>
       <indexterm>
 	<primary>MAC Stub Policy</primary>
       </indexterm>
       <para>Vendor: TrustedBSD Project</para>
       <para>Module name: mac_none.ko</para>
       <para>Kernel option: <literal>MAC_NONE</literal></para>
       <para>The None policy (&man.mac.none.4;) provides a stub
 	sample policy for developers, implementing all entry
 	points, but not changing the system access control
 	policy.  Running this on a production system would
 	not be highly beneficial.</para>
     </sect2>
     <sect2 id="mac-policy-partition">
       <title>Process Partition Policy (mac_partition)</title>
       <indexterm>
 	<primary>Process Partition Policy</primary>
       </indexterm>
       <para>Vendor: TrustedBSD Project</para>
       <para>Module name: mac_partition.ko</para>
       <para>Kernel option: <literal>MAC_PARTITION</literal></para>
       <para>The Partition policy (&man.mac.partition.4;) provides for a
 	simple process visibility limitation, assigning labels to
 	processes identifying what numeric system partition they
 	are present in.  If none, all other processes are visible
 	using standard monitoring tools; if a partition identifier
 	is present, then only other processes in the same
 	partition are visible.  This policy may be compiled into
 	the kernel, loaded at boot, or loaded at run-time.</para>
     </sect2>
     <sect2 id="mac-policy-seeotheruids">
       <title>See Other Uids Policy (mac_seeotheruids)</title>
       <indexterm>
 	<primary>See Other Uids Policy</primary>
       </indexterm>
       <para>Vendor: TrustedBSD Project</para>
       <para>Module name: mac_seeotheruids.ko</para>
       <para>Kernel option: <literal>MAC_SEEOTHERUIDS</literal></para>
       <para>The See Other Uids policy (&man.mac.seeotheruids.4;)
         implements a similar process visibility model to
         mac_partition, except that it relies on process credentials to
         control visibility of processes, rather than partition labels.
         This policy may be configured to exempt certain users and
         groups, including permitting system operators to view all
         processes without special privilege.  This policy may be
         compiled into the kernel, loaded at boot, or loaded at
         run-time.</para>
     </sect2>
     <sect2 id="mac-policy-test">
       <title>MAC Framework Test Policy (mac_test)</title>
       <indexterm>
 	<primary>MAC Framework Test Policy</primary>
       </indexterm>
       <para>Vendor: TrustedBSD Project</para>
       <para>Module name: mac_test.ko</para>
       <para>Kernel option: <literal>MAC_TEST</literal></para>
       <para>The Test policy (&man.mac.test.4;) provides a regression
         test environment for the MAC Framework, and will cause a
         fail-stop in the event that internal MAC Framework assertions
         about proper data labeling fail.  This module can be used to
         detect failures to properly label system objects in the kernel
         implementation.  This policy may be compiled into the kernel,
         loaded at boot, or loaded at run-time.</para>
     </sect2>
 
   </sect1>
  
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
 
diff --git a/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml b/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml
index f458862d41..74d3b49cb6 100644
--- a/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml
@@ -1,930 +1,930 @@
 <!--
 	The Vinum Volume Manager
 	By Greg Lehey (grog at lemis dot com)
 
 	Added to the Handbook by Hiten Pandya <hiten@uk.FreeBSD.org>
 	and Tom Rhodes <trhodes@FreeBSD.org>
 
 	For the FreeBSD Documentation Project
 	$FreeBSD$
 -->
 
 <chapter id="vinum-vinum">
   <title>The Vinum Volume Manager</title>
   
   <sect1 id="vinum-synopsis">
     <title>Synopsis</title>
 
     <para>No matter what disks you have, there will always be limitations:</para>
       <itemizedlist>
 	<listitem>
 	  <para>They can be too small.</para>
 	</listitem>
 
 	<listitem>
 	  <para>They can be too slow.</para>
 	</listitem>
 
 	<listitem>
 	  <para>They can be too unreliable.</para>
 	</listitem>
       </itemizedlist>
   </sect1>
 
   <sect1 id="vinum-intro">
     <sect1info>
       <authorgroup>
 	<author>
 	  <firstname>Greg</firstname>
 	  <surname>Lehey</surname>
 	  <contrib>Originally written by </contrib>
 	</author>
       </authorgroup>
     </sect1info>
 
     <title>Disks are too small</title>
 
     <indexterm><primary>Vinum</primary></indexterm>
     <indexterm><primary>Volume</primary>
     <secondary>Manager</secondary></indexterm>
     
     <para><emphasis>Vinum</emphasis> is a
       so-called <emphasis>Volume Manager</emphasis>, a virtual disk driver that
       addresses these three problems.  Let us look at them in more detail.  Various
       solutions to these problems have been proposed and implemented:</para>
 
 
     <para>Disks are getting bigger, but so are data storage requirements.
       Often you will find you want a file system that is bigger than the disks
       you have available.  Admittedly, this problem is not as acute as it was
       ten years ago, but it still exists.  Some systems have solved this by
       creating an abstract device which stores its data on a number of disks.</para>
   </sect1>
 
-  <sect1>
+  <sect1 id="vinum-access-bottlenecks">
     <title>Access bottlenecks</title>
     <para>Modern systems frequently need to access data in a highly
       concurrent manner.  For example, large FTP or HTTP servers can maintain
       thousands of concurrent sessions and have multiple 100&nbsp;Mbit/s connections
       to the outside world, well beyond the sustained transfer rate of most
       disks.</para>
 
     <para>Current disk drives can transfer data sequentially at up to
       70&nbsp;MB/s, but this value is of little importance in an environment
       where many independent processes access a drive, where they may
       achieve only a fraction of these values.  In such cases it is more
       interesting to view the problem from the viewpoint of the disk
       subsystem: the important parameter is the load that a transfer places
       on the subsystem, in other words the time for which a transfer occupies
       the drives involved in the transfer.</para>
 
     <para>In any disk transfer, the drive must first position the heads, wait
       for the first sector to pass under the read head, and then perform the
       transfer.  These actions can be considered to be atomic: it does not make
       any sense to interrupt them.</para>
 
     <para><anchor id="vinum-latency">
       Consider a typical transfer of about 10&nbsp;kB: the current generation of
       high-performance disks can position the heads in an average of 3.5&nbsp;ms.  The
       fastest drives spin at 15,000&nbsp;rpm, so the average rotational latency
       (half a revolution) is 2&nbsp;ms.  At 70&nbsp;MB/s, the transfer itself takes about
       150&nbsp;&mu;s, almost nothing compared to the positioning time.  In such a
       case, the effective  transfer rate drops to a little over 1&nbsp;MB/s and is
       clearly highly dependent on the transfer size.</para>
 
     <para>The traditional and obvious solution to this bottleneck is
       <quote>more spindles</quote>: rather than using one large disk, it uses
       several smaller disks with the same aggregate storage space.  Each disk is
       capable of positioning and transferring independently, so the effective
       throughput increases by a factor close to the number of disks used.
     </para>
 
     <para>The exact throughput improvement is, of course, smaller than the
       number of disks involved: although each drive is capable of transferring
       in parallel, there is no way to ensure that the requests are evenly
       distributed across the drives.  Inevitably the load on one drive will be
       higher than on another.</para>
 
     <indexterm>
       <primary>concatenation</primary>
       <secondary>Vinum</secondary>
     </indexterm>
     <indexterm>
       <primary>Vinum</primary>
       <secondary>concatenation</secondary>
     </indexterm>
 
     <para>The evenness of the load on the disks is strongly dependent on
       the way the data is shared across the drives.  In the following
       discussion, it is convenient to think of the disk storage as a large
       number of data sectors which are addressable by number, rather like the
       pages in a book.  The most obvious method is to divide the virtual disk
       into groups of consecutive sectors the size of the individual physical
       disks and store them in this manner, rather like taking a large book and
       tearing it into smaller sections.  This method is called
       <emphasis>concatenation</emphasis> and has the advantage that the disks
       are not required to have any specific size relationships.  It works
       well when the access to the virtual disk is spread evenly about its
       address space.  When access is concentrated on a smaller area, the
       improvement is less marked.  <xref linkend="vinum-concat"> illustrates
       the sequence in which storage units are allocated in a concatenated
       organization.</para>
 
     <para>
       <figure id="vinum-concat">
 	<title>Concatenated organization</title>
 	<graphic fileref="vinum/vinum-concat">
       </figure>
     </para>
 
     <indexterm>
       <primary>striping</primary>
       <secondary>Vinum</secondary>
     </indexterm>
     <indexterm>
       <primary>Vinum</primary>
       <secondary>striping</secondary>
     </indexterm>
 
     <para>An alternative mapping is to divide the address space into smaller,
       equal-sized components and store them sequentially on different devices.
       For example, the first 256 sectors may be stored on the first disk, the
       next 256 sectors on the next disk and so on.  After filling the last
       disk, the process repeats until the disks are full.  This mapping is called
       <emphasis>striping</emphasis> or <acronym>RAID-0</acronym>
 
     <footnote>
       <indexterm>
 	<primary>RAID</primary>
       </indexterm>
       <indexterm>
 	<primary>Redundant</primary>
 	<secondary>Array of Inexpensive Disks</secondary>
       </indexterm>
     
       <para><acronym>RAID</acronym> stands for <emphasis>Redundant Array of
       Inexpensive Disks</emphasis> and offers various forms of fault tolerance,
       though the latter term is somewhat misleading: it provides no redundancy.</para>
     </footnote>.
 
     Striping requires somewhat more effort to locate the data, and it can cause
     additional I/O load where a transfer is spread over multiple disks, but it
     can also provide a more constant load across the disks.
     <xref linkend="vinum-striped"> illustrates the sequence in which storage
     units are allocated in a striped organization.</para>
 
     <para>
       <figure id="vinum-striped">
         <title>Striped organization</title>
 	<graphic fileref="vinum/vinum-striped">
       </figure>
     </para>
   </sect1>
 
-  <sect1>
+  <sect1 id="vinum-data-integrity">
     <title>Data integrity</title>
       <para>The final problem with current disks is that they are unreliable.
 	Although disk drive reliability has increased tremendously over the last
 	few years, they are still the most likely core component of a server to
 	fail.  When they do, the results can be catastrophic: replacing a failed
 	disk drive and restoring data to it can take days.</para>
 
       <indexterm>
 	<primary>mirroring</primary>
 	<secondary>Vinum</secondary>
       </indexterm>
       <indexterm>
 	<primary>Vinum</primary>
 	<secondary>mirroring</secondary>
       </indexterm>
       <indexterm>
 	<primary>RAID</primary>
 	<secondary>level 1</secondary>
       </indexterm>
       <indexterm>
 	<primary>RAID-1</primary>
       </indexterm>
       
       <para>The traditional way to approach this problem has been
 	<emphasis>mirroring</emphasis>, keeping two copies of the data
 	on different physical hardware.  Since the advent of the
 	<acronym>RAID</acronym> levels, this technique has also been called
 	<acronym>RAID level 1</acronym> or <acronym>RAID-1</acronym>.  Any
 	write to the volume writes to both locations; a read can be satisfied from
 	either, so if one drive fails, the data is still available on the other
 	drive.</para>
     
       <para>Mirroring has two problems:</para>
     
 	<itemizedlist>
 	  <listitem>
 	    <para>The price.  It requires twice as much disk storage as
 	      a non-redundant solution.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The performance impact.  Writes must be performed to
 	      both drives, so they take up twice the bandwidth of a non-mirrored
 	      volume.  Reads do not suffer from a performance penalty: it even looks
 	      as if they are faster.</para>
 	  </listitem>
 	</itemizedlist>
 
       <para><indexterm><primary>RAID-5</primary></indexterm>An alternative
 	solution is <emphasis>parity</emphasis>, implemented in the
 	<acronym>RAID</acronym> levels 2, 3, 4 and 5.  Of these,
 	<acronym>RAID-5</acronym> is the most interesting. As implemented
 	in Vinum, it is a variant on a striped organization which dedicates
 	one block of each stripe to parity of the other blocks. As implemented
 	by Vinum, a <acronym>RAID-5</acronym> plex is similar to a
 	striped plex, except that it implements <acronym>RAID-5</acronym> by
 	including a parity block in each stripe.  As required by
 	<acronym>RAID-5</acronym>, the location of this parity block changes from one
 	stripe to the next.  The numbers in the data blocks indicate the relative
 	block numbers.</para>
 
       <para>
 	<figure id="vinum-raid5-org">
 	  <title>RAID-5 organization</title>
 	  <graphic fileref="vinum/vinum-raid5-org">
 	</figure>
       </para>
 
       <para>Compared to mirroring, <acronym>RAID-5</acronym> has the advantage of requiring
 	significantly less storage space.  Read access is similar to that of
 	striped organizations, but write access is significantly slower,
 	approximately 25% of the read performance.  If one drive fails, the array
 	can continue to operate in degraded mode: a read from one of the remaining
 	accessible drives continues normally, but a read from the failed drive is
 	recalculated from the corresponding block from all the remaining drives.
       </para>
   </sect1>
 
   <sect1 id="vinum-objects">
     <title>Vinum objects</title>
       <para>In order to address these problems, Vinum implements a four-level
 	hierarchy of objects:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>The most visible object is the virtual disk, called a
 	    <emphasis>volume</emphasis>.  Volumes have essentially the same
 	    properties as a UNIX&trade; disk drive, though there are some minor
 	    differences.  They have no size limitations.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Volumes are composed of <emphasis>plexes</emphasis>, each of which
 	    represent the total address space of a volume.  This level in the
 	    hierarchy thus provides redundancy.  Think of plexes as individual
 	    disks in a mirrored array, each containing the same data.</para>
 	</listitem>
 
 	<listitem>
 	  <para>Since Vinum exists within the UNIX&trade; disk storage framework,
 	    it would be possible to use UNIX&trade; partitions as the building
 	    block for multi-disk plexes, but in fact this turns out to be too
 	    inflexible: UNIX&trade; disks can have only a limited number of partitions.
 	    Instead, Vinum subdivides a single UNIX&trade; partition (the
 	    <emphasis>drive</emphasis>) into contiguous areas called
 	    <emphasis>subdisks</emphasis>, which it uses as building blocks for plexes.</para>
 	</listitem>
       
 	<listitem>
 	  <para>Subdisks reside on Vinum <emphasis>drives</emphasis>,
 	    currently UNIX&trade; partitions.  Vinum drives can contain any number of
 	    subdisks.  With the exception of a small area at the beginning of the
 	    drive, which is used for storing configuration and state information,
 	    the entire drive is available for data storage.</para>
 	</listitem>
       </itemizedlist>
 
       <para>The following sections describe the way these objects provide the
 	functionality required of Vinum.</para>
 
     <sect2>
       <title>Volume size considerations</title>
 
       <para>Plexes can include multiple subdisks spread over all drives in the
 	Vinum configuration.  As a result, the size of an individual drive does
 	not limit the size of a plex, and thus of a volume.</para>
     </sect2>
     
     <sect2>
       <title>Redundant data storage</title>
       <para>Vinum implements mirroring by attaching multiple plexes to a
 	volume.  Each plex is a representation of the data in a volume.  A
 	volume may contain between one and eight plexes.</para>
 
       <para>Although a plex represents the complete data of a volume, it is
 	possible for parts of the representation to be physically missing,
 	either by design (by not defining a subdisk for parts of the plex) or by
 	accident (as a result of the failure of a drive).  As long as at least
 	one plex can provide the data for the complete address range of the
 	volume, the volume is fully functional.</para>
     </sect2>
     
     <sect2>
       <title>Performance issues</title>
       <para>Vinum implements both concatenation and striping at the plex
 	level:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>A <emphasis>concatenated plex</emphasis> uses the
 	    address space of each subdisk in turn.</para>
 	</listitem>
 
 	<listitem>
 	  <para>A <emphasis>striped plex</emphasis> stripes the data
 	  across each subdisk.  The subdisks must all have the same size, and
 	  there must be at least two subdisks in order to distinguish it from a
 	  concatenated plex.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Which plex organization?</title>
       <para>The version of Vinum supplied with FreeBSD &rel.current; implements
 	two kinds of plex:</para>
     
       <itemizedlist>
 	<listitem>
 	  <para>Concatenated plexes are the most flexible: they can
 	    contain any number of subdisks, and the subdisks may be of different
 	    length.  The plex may be extended by adding additional subdisks.  They
 	    require less <acronym>CPU</acronym> time than striped plexes, though
 	    the difference in <acronym>CPU</acronym> overhead is not measurable.
 	    On the other hand, they are most susceptible to hot spots, where one
 	    disk is very active and others are idle.</para>
         </listitem>
 
 	<listitem>
 	  <para>The greatest advantage of striped (<acronym>RAID-0</acronym>)
 	    plexes is that they reduce hot spots: by choosing an optimum sized stripe
 	    (about 256&nbsp;kB), you can even out the load on the component drives.
 	    The disadvantages of this approach are (fractionally) more complex
 	    code and restrictions on subdisks: they must be all the same size, and
 	    extending a plex by adding new subdisks is so complicated that Vinum
 	    currently does not implement it.  Vinum imposes an additional, trivial
 	    restriction: a striped plex must have at least two subdisks, since
 	    otherwise it is indistinguishable from a concatenated plex.</para>
 	</listitem>
       </itemizedlist>
     
       <para><xref linkend="vinum-comparison"> summarizes the advantages
 	and disadvantages of each plex organization.</para>
     
       <table id="vinum-comparison">
 	<title>Vinum Plex organizations</title>
 	<tgroup cols="5">
 	  <thead>
 	    <row>
 	      <entry>Plex type</entry>
 	  	<entry>Minimum subdisks</entry>
 	  	<entry>Can add subdisks</entry>
 	  	<entry>Must be equal size</entry>
 	  	<entry>Application</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry>concatenated</entry>
 	      <entry>1</entry>
 	      <entry>yes</entry>
 	      <entry>no</entry>
 	      <entry>Large data storage with maximum placement flexibility
 	        and moderate performance</entry>
 	    </row>
 	    
 	    <row>
 	      <entry>striped</entry>
 	      <entry>2</entry>
 	      <entry>no</entry>
 	      <entry>yes</entry>
 	      <entry>High performance in combination with highly concurrent
 		access</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
     </sect2>
   </sect1>
   
   <sect1 id="vinum-examples">
     <title>Some examples</title>
     <para>Vinum maintains a <emphasis>configuration database</emphasis>
       which describes the objects known to an individual system.  Initially, the
       user creates the configuration database from one or more configuration files
       with the aid of the &man.vinum.8; utility program.  Vinum stores a copy of
       its configuration database on each disk slice (which Vinum calls a
       <emphasis>device</emphasis>) under its control.  This database is updated on
       each state change, so that a restart accurately restores the state of each
       Vinum object.</para>
   
     <sect2>
       <title>The configuration file</title>
       <para>The configuration file describes individual Vinum objects.  The
 	definition of a simple volume might be:</para>
 
       <programlisting>
     drive a device /dev/da3h
     volume myvol
       plex org concat
         sd length 512m drive a</programlisting>
 
       <para>This file describes four Vinum objects:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para>The <emphasis>drive</emphasis> line describes a disk
 	    partition (<emphasis>drive</emphasis>) and its location relative to the
 	    underlying hardware.  It is given the symbolic name
 	    <emphasis>a</emphasis>.  This separation of the symbolic names from the
 	    device names allows disks to be moved from one location to another
 	    without confusion.</para>
 	</listitem>
 
 	<listitem>
 	  <para>The <emphasis>volume</emphasis> line describes a volume.
 	    The only required attribute is the name, in this case
 	    <emphasis>myvol</emphasis>.</para>
 	</listitem>
 
 	<listitem>
 	  <para>The <emphasis>plex</emphasis> line defines a plex.  The
 	    only required parameter is the organization, in this case
 	    <emphasis>concat</emphasis>.  No name is necessary: the system
 	    automatically generates a name from the volume name by adding the suffix
 	    <emphasis>.p</emphasis><emphasis>x</emphasis>, where
 	    <emphasis>x</emphasis> is the number of the plex in the volume.  Thus
 	    this plex will be called <emphasis>myvol.p0</emphasis>.</para>
 	</listitem>
 
 	<listitem>
 	  <para>The <emphasis>sd</emphasis> line describes a subdisk.
 	    The minimum specifications are the name of a drive on which to store it,
 	    and the length of the subdisk.  As with plexes, no name is necessary:
 	    the system automatically assigns names derived from the plex name by
 	    adding the suffix <emphasis>.s</emphasis><emphasis>x</emphasis>, where
 	    <emphasis>x</emphasis> is the number of the subdisk in the plex.  Thus
 	    Vinum gives this subdisk the name <emphasis>myvol.p0.s0</emphasis>.</para>
 	</listitem>
       </itemizedlist>
 
       <para>After processing this file, &man.vinum.8; produces the following
 	output:</para>
 
       <programlisting>
       &prompt.root; vinum -&gt; <command>create config1</command>
       Configuration summary
       Drives:         1 (4 configured)
       Volumes:        1 (4 configured)
       Plexes:         1 (8 configured)
       Subdisks:       1 (16 configured)
      
 	D a                     State: up       Device /dev/da3h        Avail: 2061/2573 MB (80%)
 	
 	V myvol                 State: up       Plexes:       1 Size:        512 MB
 	
 	P myvol.p0            C State: up       Subdisks:     1 Size:        512 MB
 	
 	S myvol.p0.s0           State: up       PO:        0  B Size:        512 MB</programlisting>
 
       <para>This output shows the brief listing format of &man.vinum.8;.  It
 	is represented graphically in <xref linkend="vinum-simple-vol">.</para>
 
       <para>
 	<figure id="vinum-simple-vol">
 	  <title>A simple Vinum volume</title>
 	  <graphic fileref="vinum/vinum-simple-vol">
 	</figure>
       </para>
 
       <para>This figure, and the ones which follow, represent a volume, which
 	contains the plexes, which in turn contain the subdisks.  In this trivial
 	example, the volume contains one plex, and the plex contains one subdisk.</para>
 
       <para>This particular volume has no specific advantage over a conventional
 	disk partition.  It contains a single plex, so it is not redundant.  The
 	plex contains a single subdisk, so there is no difference in storage
 	allocation from a conventional disk partition.  The following sections
 	illustrate various more interesting configuration methods.</para>
     </sect2>
 
     <sect2>
       <title>Increased resilience: mirroring</title>
       <para>The resilience of a volume can be increased by mirroring.  When
 	laying out a mirrored volume, it is important to ensure that the subdisks
 	of each plex are on different drives, so that a drive failure will not
 	take down both plexes.  The following configuration mirrors a volume:</para>
 
       <programlisting>
 	drive b device /dev/da4h
 	volume mirror
       plex org concat
         sd length 512m drive a
 	  plex org concat
 	    sd length 512m drive b</programlisting>
 
       <para>In this example, it was not necessary to specify a definition of
 	drive <emphasis>a</emphasis> again, since Vinum keeps track of all
 	objects in its configuration database.  After processing this
 	definition, the configuration looks like:</para>
 
 
       <programlisting>
 	Drives:         2 (4 configured)
 	Volumes:        2 (4 configured)
 	Plexes:         3 (8 configured)
 	Subdisks:       3 (16 configured)
 	
 	D a                     State: up       Device /dev/da3h        Avail: 1549/2573 MB (60%)
 	D b                     State: up       Device /dev/da4h        Avail: 2061/2573 MB (80%)
 
     V myvol                 State: up       Plexes:       1 Size:        512 MB
     V mirror                State: up       Plexes:       2 Size:        512 MB
   
     P myvol.p0            C State: up       Subdisks:     1 Size:        512 MB
     P mirror.p0           C State: up       Subdisks:     1 Size:        512 MB
     P mirror.p1           C State: initializing     Subdisks:     1 Size:        512 MB
   
     S myvol.p0.s0           State: up       PO:        0  B Size:        512 MB
 	S mirror.p0.s0          State: up       PO:        0  B Size:        512 MB
 	S mirror.p1.s0          State: empty    PO:        0  B Size:        512 MB</programlisting>
 	
       <para><xref linkend="vinum-mirrored-vol"> shows the structure
 	graphically.</para>
 
       <para>
 	<figure id="vinum-mirrored-vol">
 	  <title>A mirrored Vinum volume</title>
 	  <graphic fileref="vinum/vinum-mirrored-vol">
 	</figure>
       </para>
 
       <para>In this example, each plex contains the full 512&nbsp;MB of address
 	space.  As in the previous example, each plex contains only a single
 	subdisk.</para>
     </sect2>
 
     <sect2>
       <title>Optimizing performance</title>
       <para>The mirrored volume in the previous example is more resistant to
 	failure than an unmirrored volume, but its performance is less: each write
 	to the volume requires a write to both drives, using up a greater
 	proportion of the total disk bandwidth.  Performance considerations demand
 	a different approach: instead of mirroring, the data is striped across as
 	many disk drives as possible.  The following configuration shows a volume
 	with a plex striped across four disk drives:</para>
 
 	<programlisting>
 	drive c device /dev/da5h
 	drive d device /dev/da6h
 	volume stripe
 	plex org striped 512k
 	  sd length 128m drive a
 	  sd length 128m drive b
 	  sd length 128m drive c
 	  sd length 128m drive d</programlisting>
 
       <para>As before, it is not necessary to define the drives which are
 	already known to Vinum.  After processing this definition, the
 	configuration looks like:</para>
 
       <programlisting>
 	Drives:         4 (4 configured)
 	Volumes:        3 (4 configured)
 	Plexes:         4 (8 configured)
 	Subdisks:       7 (16 configured)
   
     D a                     State: up       Device /dev/da3h        Avail: 1421/2573 MB (55%)
     D b                     State: up       Device /dev/da4h        Avail: 1933/2573 MB (75%)
     D c                     State: up       Device /dev/da5h        Avail: 2445/2573 MB (95%)
     D d                     State: up       Device /dev/da6h        Avail: 2445/2573 MB (95%)
   
     V myvol                 State: up       Plexes:       1 Size:        512 MB
     V mirror                State: up       Plexes:       2 Size:        512 MB
     V striped               State: up       Plexes:       1 Size:        512 MB
   
     P myvol.p0            C State: up       Subdisks:     1 Size:        512 MB
     P mirror.p0           C State: up       Subdisks:     1 Size:        512 MB
     P mirror.p1           C State: initializing     Subdisks:     1 Size:        512 MB
     P striped.p1            State: up       Subdisks:     1 Size:        512 MB
   
     S myvol.p0.s0           State: up       PO:        0  B Size:        512 MB
     S mirror.p0.s0          State: up       PO:        0  B Size:        512 MB
     S mirror.p1.s0          State: empty    PO:        0  B Size:        512 MB
     S striped.p0.s0         State: up       PO:        0  B Size:        128 MB
     S striped.p0.s1         State: up       PO:      512 kB Size:        128 MB
     S striped.p0.s2         State: up       PO:     1024 kB Size:        128 MB
     S striped.p0.s3         State: up       PO:     1536 kB Size:        128 MB</programlisting>
 
       <para>
 	<figure id="vinum-striped-vol">
 	  <title>A striped Vinum volume</title>
 	  <graphic fileref="vinum/vinum-striped-vol">
 	</figure>
       </para>
 
       <para>This volume is represented in
 	<xref linkend="vinum-striped-vol">.  The darkness of the stripes
 	indicates the position within the plex address space: the lightest stripes
 	come first, the darkest last.</para>
     </sect2>
 
     <sect2>
       <title>Resilience and performance</title>
       <para><anchor id="vinum-resilience">With sufficient hardware, it is
 	possible to build volumes which show both increased resilience and
 	increased performance compared to standard UNIX&trade; partitions.  A typical
 	configuration file might be:</para>
 
       <programlisting>
 	volume raid10
       plex org striped 512k
         sd length 102480k drive a
         sd length 102480k drive b
         sd length 102480k drive c
         sd length 102480k drive d
         sd length 102480k drive e
       plex org striped 512k
         sd length 102480k drive c
         sd length 102480k drive d
         sd length 102480k drive e
         sd length 102480k drive a
         sd length 102480k drive b</programlisting>
 
       <para>The subdisks of the second plex are offset by two drives from those
 	of the first plex: this helps ensure that writes do not go to the same
 	subdisks even if a transfer goes over two drives.</para>
 
       <para><xref linkend="vinum-raid10-vol"> represents the structure
 	of this volume.</para>
 
       <para>
 	<figure id="vinum-raid10-vol">
 	  <title>A mirrored, striped Vinum volume</title>
 	  <graphic fileref="vinum/vinum-raid10-vol">
         </figure>
       </para>
     </sect2>
   </sect1>
   
-  <sect1>
+  <sect1 id="vinum-object-naming">
     <title>Object naming</title>
     <para>As described above, Vinum assigns default names to plexes and
       subdisks, although they may be overridden.  Overriding the default names
       is not recommended: experience with the VERITAS volume manager, which
       allows arbitrary naming of objects, has shown that this flexibility does
       not bring a significant advantage, and it can cause confusion.</para>
 
     <para>Names may contain any non-blank character, but it is recommended to
       restrict them to letters, digits and the underscore characters.  The names
       of volumes, plexes and subdisks may be up to 64 characters long, and the
       names of drives may be up to 32 characters long.</para>
 
     <para><indexterm><primary>/dev/vinum</primary></indexterm>Vinum objects
       are assigned device nodes in the hierarchy <filename>/dev/vinum</filename>.
       The configuration shown above would cause Vinum to create the following
       device nodes:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The control devices <devicename>/dev/vinum/control</devicename> and
 	  <devicename>/dev/vinum/controld</devicename>, which are used by 
 	  &man.vinum.8; and the Vinum daemon respectively.</para>
       </listitem>
 
       <listitem>
 	<para>Block and character device entries for each volume.
 	  These are the main devices used by Vinum.  The block device names are
 	  the name of the volume, while the character device names follow the BSD 
 	  tradition of prepending the letter <emphasis>r</emphasis> to the name.  
 	  Thus the configuration above would include the block devices 
 	  <devicename>/dev/vinum/myvol</devicename>, 
 	  <devicename>/dev/vinum/mirror</devicename>,  
 	  <devicename>/dev/vinum/striped</devicename>, 
 	  <devicename>/dev/vinum/raid5</devicename> and 
 	  <devicename>/dev/vinum/raid10</devicename>, and the character devices 
 	  <devicename>/dev/vinum/rmyvol</devicename>, 
 	  <devicename>/dev/vinum/rmirror</devicename>,
 	  <devicename>/dev/vinum/rstriped</devicename>, 
 	  <devicename>/dev/vinum/rraid5</devicename> and 
 	  <devicename>/dev/vinum/rraid10</devicename>.  
 	  There is obviously a problem here: it is possible to have two volumes 
 	  called <emphasis>r</emphasis> and <emphasis>rr</emphasis>, but there 
 	  will be a conflict creating the device node 
 	  <devicename>/dev/vinum/rr</devicename>: is it a character device for 
 	  volume <emphasis>r</emphasis> or a block device for volume 
 	  <emphasis>rr</emphasis>?  Currently Vinum does not address this 
 	  conflict: the first-defined volume will get the name.</para>
       </listitem>
 
       <listitem>
 	<para>A directory <devicename>/dev/vinum/drive</devicename>
 	  with entries for each drive.  These entries are in fact symbolic links
 	  to the corresponding disk nodes.</para>
       </listitem>
 
       <listitem>
 	<para>A directory <filename>/dev/vinum/volume</filename> with
 	  entries for each volume.  It contains subdirectories for each plex, 
 	  which in turn contain subdirectories for their component subdisks.</para>
       </listitem>
 
       <listitem>
 	<para>The directories <devicename>/dev/vinum/plex</devicename>,
 	  <devicename>/dev/vinum/sd</devicename>, and
 	  <devicename>/dev/vinum/rsd</devicename>, which contain block device
 	  nodes for each plex and block and character device nodes respectively 
 	  for each subdisk.</para>
       </listitem>
     </itemizedlist>
 
     <para>For example, consider the following configuration file:</para>
 	<programlisting>
 	drive drive1 device /dev/sd1h
 	drive drive2 device /dev/sd2h
 	drive drive3 device /dev/sd3h
 	drive drive4 device /dev/sd4h
     volume s64 setupstate
       plex org striped 64k
         sd length 100m drive drive1
         sd length 100m drive drive2
         sd length 100m drive drive3
         sd length 100m drive drive4</programlisting>
 
     <para>After processing this file, &man.vinum.8; creates the following
       structure in <filename>/dev/vinum</filename>:</para>
 
     <programlisting>
 	brwx------  1 root  wheel   25, 0x40000001 Apr 13 16:46 Control
 	brwx------  1 root  wheel   25, 0x40000002 Apr 13 16:46 control
 	brwx------  1 root  wheel   25, 0x40000000 Apr 13 16:46 controld
 	drwxr-xr-x  2 root  wheel       512 Apr 13 16:46 drive
 	drwxr-xr-x  2 root  wheel       512 Apr 13 16:46 plex
 	crwxr-xr--  1 root  wheel   91,   2 Apr 13 16:46 rs64
 	drwxr-xr-x  2 root  wheel       512 Apr 13 16:46 rsd
 	drwxr-xr-x  2 root  wheel       512 Apr 13 16:46 rvol
 	brwxr-xr--  1 root  wheel   25,   2 Apr 13 16:46 s64
 	drwxr-xr-x  2 root  wheel       512 Apr 13 16:46 sd
 	drwxr-xr-x  3 root  wheel       512 Apr 13 16:46 vol
 
 	/dev/vinum/drive:
     total 0
     lrwxr-xr-x  1 root  wheel  9 Apr 13 16:46 drive1 -&gt; /dev/sd1h
     lrwxr-xr-x  1 root  wheel  9 Apr 13 16:46 drive2 -&gt; /dev/sd2h
     lrwxr-xr-x  1 root  wheel  9 Apr 13 16:46 drive3 -&gt; /dev/sd3h
     lrwxr-xr-x  1 root  wheel  9 Apr 13 16:46 drive4 -&gt; /dev/sd4h
   
     /dev/vinum/plex:
     total 0
     brwxr-xr--  1 root  wheel   25, 0x10000002 Apr 13 16:46 s64.p0
     
     /dev/vinum/rsd:
     total 0
     crwxr-xr--  1 root  wheel   91, 0x20000002 Apr 13 16:46 s64.p0.s0
     crwxr-xr--  1 root  wheel   91, 0x20100002 Apr 13 16:46 s64.p0.s1
     crwxr-xr--  1 root  wheel   91, 0x20200002 Apr 13 16:46 s64.p0.s2
     crwxr-xr--  1 root  wheel   91, 0x20300002 Apr 13 16:46 s64.p0.s3
   
     /dev/vinum/rvol:
     total 0
     crwxr-xr--  1 root  wheel   91,   2 Apr 13 16:46 s64
   
     /dev/vinum/sd:
     total 0
     brwxr-xr--  1 root  wheel   25, 0x20000002 Apr 13 16:46 s64.p0.s0
     brwxr-xr--  1 root  wheel   25, 0x20100002 Apr 13 16:46 s64.p0.s1
     brwxr-xr--  1 root  wheel   25, 0x20200002 Apr 13 16:46 s64.p0.s2
     brwxr-xr--  1 root  wheel   25, 0x20300002 Apr 13 16:46 s64.p0.s3
   
     /dev/vinum/vol:
     total 1
     brwxr-xr--  1 root  wheel   25,   2 Apr 13 16:46 s64
     drwxr-xr-x  3 root  wheel       512 Apr 13 16:46 s64.plex
   
     /dev/vinum/vol/s64.plex:
     total 1
     brwxr-xr--  1 root  wheel   25, 0x10000002 Apr 13 16:46 s64.p0
     drwxr-xr-x  2 root  wheel       512 Apr 13 16:46 s64.p0.sd
   
     /dev/vinum/vol/s64.plex/s64.p0.sd:
     total 0
     brwxr-xr--  1 root  wheel   25, 0x20000002 Apr 13 16:46 s64.p0.s0
     brwxr-xr--  1 root  wheel   25, 0x20100002 Apr 13 16:46 s64.p0.s1
     brwxr-xr--  1 root  wheel   25, 0x20200002 Apr 13 16:46 s64.p0.s2
     brwxr-xr--  1 root  wheel   25, 0x20300002 Apr 13 16:46 s64.p0.s3</programlisting>
 
     <para>Although it is recommended that plexes and subdisks should not be
       allocated specific names, Vinum drives must be named.  This makes it
       possible to move a drive to a different location and still recognize it
       automatically.  Drive names may be up to 32 characters long.</para>
 
     <sect2>
       <title>Creating file systems</title>
 	<para>Volumes appear to the system to be identical to disks, with one exception.
 	  Unlike UNIX&trade; drives, Vinum does not partition volumes, which thus do
 	  not contain a partition table.  This has required modification to some disk
 	  utilities, notably &man.newfs.8;, which previously tried to
 	  interpret the last letter of a Vinum volume name as a partition identifier.
 	  For example, a disk drive may have a name like <devicename>/dev/ad0a</devicename>
 	  or <devicename>/dev/da2h</devicename>.  These names represent the first
 	  partition (<devicename>a</devicename>) on the first (0) IDE disk
 	  (<devicename>ad</devicename>) and the eighth partition
 	  (<devicename>h</devicename>) on the third (2) SCSI disk
 	  (<devicename>da</devicename>) respectively.  By contrast, a Vinum volume
 	  might be called <devicename>/dev/vinum/concat</devicename>, a name which
 	  has no relationship with a partition name.</para>
 
 	<para>Normally, &man.newfs.8; interprets the name of the disk and
 	  complains if it cannot understand it.  For example:</para>
 
 	<screen>&prompt.root; <userinput>newfs /dev/vinum/concat</userinput>
 newfs: /dev/vinum/concat: can't figure out file system partition</screen>
 
 	<para>In order to create a file system on this volume, use the
 	  <option>-v</option> option to &man.newfs.8;:</para>
 
 	<screen>&prompt.root; <userinput>newfs -v /dev/vinum/concat</userinput></screen>
 
     </sect2>
   </sect1>
   
   <sect1 id="vinum-config">
     <title>Configuring Vinum</title>
     <para>The <filename>GENERIC</filename> kernel does not contain Vinum.  It is
 	possible to build a special kernel which includes Vinum, but this is not
 	recommended.  The standard way to start Vinum is as a kernel module
 	(<acronym>kld</acronym>).  You do not even need to use &man.kldload.8; 
 	for Vinum: when you start &man.vinum.8;, it checks whether the module 
 	has been loaded, and if it is not, it loads it automatically.</para>
 
 
     <sect2>
       <title>Startup</title>
 	<para>Vinum stores configuration information on the disk slices in
 	  essentially the same form as in the configuration files.  When reading
 	  from the configuration database, Vinum recognizes a number of keywords
 	  which are not allowed in the configuration files.  For example, a disk
 	  configuration might contain the following text:</para>
 
 	<programlisting>volume myvol state up
 volume bigraid state down
 plex name myvol.p0 state up org concat vol myvol
 plex name myvol.p1 state up org concat vol myvol
 plex name myvol.p2 state init org striped 512b vol myvol
 plex name bigraid.p0 state initializing org raid5 512b vol bigraid
 sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b
 sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b
 sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b
 sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b
 sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b
 sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b
 sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b
 sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b
 sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b
 sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b
 sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b
 sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b
 sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b</programlisting>
   
 	<para>The obvious differences here are the presence of explicit location
 	  information and naming (both of which are also allowed, but discouraged, for
 	  use by the user) and the information on the states (which are not available
 	  to the user).  Vinum does not store information about drives in the
 	  configuration information: it finds the drives by scanning the configured
 	  disk drives for partitions with a Vinum label.  This enables Vinum to
 	  identify drives correctly even if they have been assigned different UNIX&trade;
 	  drive IDs.</para>
   
       <sect3>
 	<title>Automatic startup</title>
 	  <para>In order to start Vinum automatically when you boot the system,
 	    ensure that you have the following line in your
 	    <filename>/etc/rc.conf</filename>:</para>
 
 	<programlisting>start_vinum="YES"		# set to YES to start vinum</programlisting>
 
 	<para>If you do not have a file <filename>/etc/rc.conf</filename>, create
 	  one with this content.  This will cause the system to load the Vinum
 	  <acronym>kld</acronym> at startup, and to start any objects mentioned in
 	  the configuration.  This is done before mounting file systems, so it is
 	  possible to automatically &man.fsck.8; and mount file systems on Vinum
 	  volumes.</para>
 
 	<para>When you start Vinum with the <command>vinum start</command> command,
 	  Vinum reads the configuration database from one of the Vinum drives.
 	  Under normal circumstances, each drive contains an identical copy of the
 	  configuration database, so it does not matter which drive is read.  After
 	  a crash, however, Vinum must determine which drive was updated most
 	  recently and read the configuration from this drive.  It then updates the
 	  configuration if necessary from progressively older drives.</para>
 
       </sect3>
     </sect2>
   </sect1>
 </chapter>
diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
index 77deac8f62..a506bb00d4 100644
--- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
@@ -1,1526 +1,1526 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <chapter id="x11">
   <title>The X Window System</title>
 
-  <sect1>
+  <sect1 id="x11-synopsis">
     <title>Synopsis</title>
 
     <para>FreeBSD uses <application>XFree86</application> to provide users with
       a powerful graphical user interface.  <application>XFree86</application>
       is an open-source implementation of the X Window System.  This chapter
       will cover installation and configuration of
       <application>XFree86</application> on a FreeBSD system.  For more
       information on <application>XFree86</application> and video hardware that
       it supports, check the <ulink
         url="http://www.XFree86.org/">XFree86</ulink> web site.</para>
 
     <para>After reading this chapter, you will know:</para>
 
     <itemizedlist>
       <listitem>
         <para>The various components of the X Window System, and how they
           interoperate.</para>
       </listitem>
 
       <listitem>
         <para>How to install and configure
           <application>XFree86</application>.</para>
       </listitem>
 
       <listitem>
         <para>How to install and use different window managers.</para>
       </listitem>
 
       <listitem>
         <para>How to use TrueType fonts in
           <application>XFree86</application>.</para>
       </listitem>
 
       <listitem>
         <para>How to setup your system for graphical logins
           (<application>XDM</application>).</para>
       </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
 
     <itemizedlist>
       <listitem><para>Know how to install additional third-party
         software (<xref linkend="ports">).</para></listitem>
     </itemizedlist>
   </sect1>
 
   <sect1 id="x-understanding">
     <title>Understanding X</title>
 
     <para>Using X for the first time can be somewhat of a shock to someone
       familiar with other graphical environments, such as Microsoft Windows or
       MacOS.</para>
 
     <para>It is not necessary to understand all of the details of various
       X components and how they interact; however, some basic knowledge makes
       it possible to take advantage of X's strengths.</para>
 
     <sect2>
       <title>Why X?</title>
 
       <para>X is not the first window system written for Unix, but it is the
         most popular.  X's original development team had worked on another
         window system before writing X.  That system's name was
         <quote>W</quote> (for <quote>Window</quote>).  X is just the next
         letter in the Roman alphabet.</para>
 
       <para>X can be called <quote>X</quote>, <quote>X Window System</quote>,
           <quote>X11</quote>, and other terms.  Calling X11
           <quote>X Windows</quote> can offend some people;
           see &man.X.1; for a bit more insight on this.</para>
     </sect2>
 
     <sect2>
       <title>The X Client/Server Model</title>
 
       <para>X was designed from the beginning to be network-centric, and
         adopts a <quote>client-server</quote> model.  In the X model, the
         <quote>X server</quote> runs on the computer that has the keyboard,
         monitor, and mouse attached.  The server is responsible for managing
         the display, handling input from the keyboard and mouse, and so on.
         Each X application (such as <application>XTerm</application>, or
         <application>Netscape</application>) is a <quote>client</quote>.  A
         client sends messages to the server such as <quote>Please draw a
           window at these coordinates</quote>, and the server sends back
           messages such as <quote>The user just clicked on the OK
           button</quote>.</para>
 
       <para>If there is only one computer involved, such as in a home or small
         office environment, the X server and the X clients will be running on
         the same computer.  However, it is perfectly possible to run the X
         server on a less powerful desktop computer, and run X applications
         (the clients) on, say, the powerful and expensive machine that serves
         the office.  In this scenario the communication between the X client
         and server takes place over the network.</para>
 
       <para>This confuses some people, because the X terminology is
         exactly backward to what they expect.  They expect the <quote>X
           server</quote> to be the big powerful machine down the hall, and
         the <quote>X client</quote> to be the machine on their desk.</para>
 
       <para>Remember that the X server is the machine with the monitor and
         keyboard, and the X clients are the programs that display the
         windows.</para>
 
       <para>There is nothing in the protocol that forces the client and
         server machines to be running the same operating system, or even to
         be running on the same type of computer.  It is certainly possible to
         run an X server on Microsoft Windows or Apple's MacOS, and there are
         various free and commercial applications available that do exactly
         that.</para>
 
       <para>The X server that ships with FreeBSD is called
         <application>XFree86</application>, and is available for free, under a
         license very similar to the FreeBSD license.  Commercial X servers for
         FreeBSD are also available.</para>
     </sect2>
 
     <sect2>
       <title>The Window Manager</title>
 
       <para>The X design philosophy is much like the Unix design philosophy,
         <quote>tools, not policy</quote>.  This means that X does not try to
         dictate how a task is to be accomplished.  Instead, tools are provided
         to the user, and it is the user's responsibility to decide how to use
         those tools.</para>
 
       <para>This philosophy extends to X not dictating what windows should
         look like on screen, how to move them around with the mouse, what
         keystrokes should be used to move between windows (i.e.,
         <keycombo action="simul">
           <keycap>Alt</keycap>
           <keycap>Tab</keycap>
         </keycombo>, in the case of Microsoft Windows), what the title bars
         on each window should look like, whether or not they have close
         buttons on them, and so on.</para>
 
       <para>Instead, X delegates this responsibility to an application called
         a <quote>Window Manager</quote>.  There are dozens of window
         managers available for X: <application>AfterStep</application>,
         <application>Blackbox</application>, <application>ctwm</application>,
         <application>Enlightenment</application>,
         <application>fvwm</application>, <application>Sawfish</application>,
         <application>twm</application>,
         <application>Window Maker</application>, and more.  Each of these
         window managers provides a different look and feel; some of them
         support <quote>virtual desktops</quote>; some of them allow customized
         keystrokes to manage the desktop; some have a <quote>Start</quote>
         button or similar device; some are <quote>themeable</quote>, allowing
         a complete change of look-and-feel by applying a new theme.  These
         window managers, and many more, are available in the
         <filename>x11-wm</filename> category of the Ports Collection.</para>
 
       <para>In addition, the <application>KDE</application> and
 	<application>GNOME</application> desktop environments both have their
 	own window managers which integrate with the desktop.</para>
 
       <para>Each window manager also has a different configuration mechanism;
         some expect configuration file written by hand, others feature
         GUI tools for most of the configuration tasks; at least one
         (<application>sawfish</application>) has a configuration file written
         in a dialect of the Lisp language.</para>
 
       <note>
         <title>Focus Policy</title>
 
         <para>Another feature the window manager is responsible for is the
           mouse <quote>focus policy</quote>.  Every windowing system
           needs some means of choosing a window to be actively receiving
           keystrokes, and should visibly indicate which window is active as
           well.</para>
 
         <para>A familiar focus policy is called <quote>click-to-focus</quote>.
           This is the model utilized by Microsoft Windows, in which a window
           becomes active upon receiving a mouse click.</para>
 
         <para>X does not support any particular focus policy.  Instead, the
           window manager controls which window has the focus at any one time.
           Different window managers will support different focus methods.  All
           of them support click to focus, and the majority of them support
           several others.</para>
 
         <para>The most popular focus policies are:</para>
 
         <variablelist>
           <varlistentry>
             <term>focus-follows-mouse</term>
 
             <listitem>
               <para>The window that is under the mouse pointer is the
                 window that has the focus.  This may not necessarily be
                 the window that is on top of all the other windows.
                 The focus is changed by pointing at another window, there
                 is no need to click in it as well.</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>sloppy-focus</term>
 
             <listitem>
               <para>This policy is a small extension to focus-follows-mouse.
                 With focus-follows-mouse, if the mouse is moved over the
                 root window (or background) then no window has the focus,
                 and keystrokes are simply lost.  With sloppy-focus, focus is
                 only changed when the cursor enters a new window, and not
                 when exiting the current window.</para>
             </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>click-to-focus</term>
 
             <listitem>
               <para>The active window is selected by mouse click.  The
                 window may then be <quote>raised</quote>, and appear in
                 front of all other windows.  All keystrokes will now be
                 directed to this window, even if the cursor is moved to
                 another window.</para>
             </listitem>
           </varlistentry>
         </variablelist>
 
         <para>Many window managers support other policies, as well as
           variations on these.  Be sure to consult the documentation for
           the window manager itself.</para>
       </note>
     </sect2>
 
     <sect2>
       <title>Widgets</title>
 
       <para>The X approach of providing tools and not policy extends to the
         widgets that seen on screen in each application.</para>
 
       <para><quote>Widget</quote> is a term for all the items in the user
         interface that can be clicked or manipulated in some way; buttons,
         check boxes, radio buttons, icons, lists, and so on.  Microsoft
         Windows calls these <quote>controls</quote>.</para>
 
       <para>Microsoft Windows and Apple's MacOS both have a very rigid widget
         policy.  Application developers are supposed to ensure that their
         applications share a common look and feel.  With X, it was not
         considered sensible to mandate a particular graphical style, or set
         of widgets to adhere to.</para>
 
       <para>As a result, do not expect X applications to have a common
         look and feel.  There are several popular widget sets and
         variations, including the original Athena widget set from MIT,
         <application>Motif</application> (on which the widget set in
         Microsoft Windows was modeled, all bevelled edges and three shades of
         grey), <application>OpenLook</application>, and others.</para>
 
       <para>Most newer X applications today will use a modern-looking widget
         set, either Qt, used by <application>KDE</application>, or
         <application>GTK</application>, used by the
         <application>GNOME</application>
         project.  In this respect, there is some convergence in
         look-and-feel of the Unix desktop, which certainly makes things
         easier for the novice user.</para>
     </sect2>
   </sect1>
 
   <sect1 id="x-install">
     <title>Installing XFree86</title>
 
     <para>Before installing <application>XFree86</application>, decide on which
       version to run.  <application>XFree86 3.X</application> is a maintenance
       branch of <application>XFree86</application> development.  It is very
       stable, and it supports a huge number of graphics cards.  However, no new
       development is being done on the software.  <application>XFree86
       4.X</application> is a complete redesign of the system with many new
       features such as better support for fonts and anti-aliasing.
       Unfortunately this new architecture requires that the video drivers be
       rewritten, and some of the older cards that were supported in 3.X are not
       yet supported in 4.X.  As all new developments and support for new
       graphics cards are done on that branch, <application>XFree86
       4.X</application> is now the default version of the X Window System on
       FreeBSD.</para>
 
     <para>The FreeBSD setup program offers users the opportunity to install
       and configure <application>XFree86 4.X</application> during installation
       (covered in <xref linkend="x-server">).  To install and run
       <application>XFree86 3.X</application>, wait until after the base
       FreeBSD system is installed, and then install
       <application>XFree86</application>.  For example, to build and install
       <application>XFree86 3.X</application> from the ports collection:</para>
 
     <screen>&prompt.root; <userinput>cd /usr/ports/x11/XFree86</userinput>
 &prompt.root; <userinput>make all install clean</userinput></screen>
 
     <para>Alternatively, either version of <application>XFree86</application>
       can be installed directly from the FreeBSD binaries provided on the
       <ulink url="http://www.XFree86.org/">XFree86 web site</ulink>.  A binary
       package to use with &man.pkg.add.1; tool is also available for
       <application>XFree86 4.X</application>.  When the remote fetching
       feature of &man.pkg.add.1; is used, the version number of the
       package must be removed.  &man.pkg.add.1; will automatically fetch
       the latest version of the application.  So to fetch and install the
       package of <application>XFree86 4.X</application>, simply type:</para>
 
     <screen>&prompt.root; <userinput>pkg_add -r XFree86</userinput></screen>
 
     <para>You can also use the ports collection to install
       <application>XFree86 4.X</application>, for that you simply need
       to type the following commands:</para>
 
     <screen>&prompt.root; <userinput>cd /usr/ports/x11/XFree86-4</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
     <para>The rest of this chapter will explain how to configure
       <application>XFree86</application>, and how to setup a productive desktop
       environment.</para>
 
 <!-- Easiest way is from sysinstall for XFree86 4.X -->
 
   </sect1>
 
   <sect1 id="x-config">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Christopher</firstname>
           <surname>Shumway</surname>
           <contrib>Contributed by </contrib>
           <!-- July 2001 -->
         </author>
       </authorgroup>
     </sect1info>
     <title>XFree86 Configuration</title>
 
 
     <indexterm><primary>XFree86 4.X</primary></indexterm>
     <indexterm><primary>XFree86</primary></indexterm>
 
     <sect2>
       <title>Before Starting</title>
 
       <para>Before configuration of <application>XFree86 4.X</application>,
         the following information about the target system is needed:</para>
 
       <itemizedlist>
         <listitem><para>Monitor specifications</para></listitem>
         <listitem><para>Video Adapter chipset</para></listitem>
         <listitem><para>Video Adapter memory</para></listitem>
       </itemizedlist>
 
       <indexterm><primary>horizontal scan rate</primary></indexterm>
       <indexterm><primary>vertical scan rate</primary></indexterm>
 
       <para>The specifications for the monitor are used by
         <application>XFree86</application> to determine the resolution and
         refresh rate to run at.  These specifications can usually be
         obtained from the documentation that came with the monitor or from
         the manufacturer's website.  There are two ranges of numbers that
         are needed, the horizontal scan rate and the vertical synchronization
         rate.</para>
 
       <para>The video adapter's chipset defines what driver module
         <application>XFree86</application> uses to talk to the graphics
         hardware.  With most chipsets, this can be automatically
         determined, but it is still useful to know in case the automatic
         detection does not work correctly.</para>
 
       <para>Video memory on the graphic adapter determines the
         resolution and color depth which the system can run at.  This is
         important to know so the user knows the limitations of the
         system.</para>
 
     </sect2>
 
     <sect2>
       <title>Configuring XFree86 4.X</title>
 
       <para>Configuration of <application>XFree86 4.X</application> is
         a multi-step process.  The first step is to build an initial
         configuration file with the <option>-configure</option> option to
         <application>XFree86</application>.  As the super user, simply
         run:</para>
 
       <screen>&prompt.root; <userinput>XFree86 -configure</userinput></screen>
 
       <para>This will generate a skeleton
         <application>XFree86</application> configuration file in the
         <filename>/root</filename> directory called
         <filename>XF86Config.new</filename> (in fact the directory used is the one covered by the environment variable <envar>$HOME</envar>, and it will depend from the way you got the superuser rights).  The
         <application>XFree86</application> 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 existing
         configuration to verify that <application>XFree86</application>
         can work with the graphics
         hardware on the target system.  To perform this task, the user
         needs to run:</para>
 
       <screen>&prompt.root; <userinput>XFree86 -xf86config XF86Config.new</userinput></screen>
 
       <para>If a black and grey grid and an X mouse cursor appear,
         the configuration was successful.  To exit the test, just press
         <keycombo action="simul">
           <keycap>Ctrl</keycap>
           <keycap>Alt</keycap>
           <keycap>Backspace</keycap>
         </keycombo> simultaneously.</para>
 
 	<note><para>If the mouse does not work, be sure the device
 	  has been configured.  See <ulink url="install-post.html#MOUSE">
 	  mouse configuration</ulink> in the &os; install chapter.</para></note>
 
       <indexterm><primary>XFree86 4 Tuning</primary></indexterm>
 
       <para>Next, tune the <filename>XF86Config.new</filename>
         configuration file to taste.  Open the file in a text editor such
         as &man.emacs.1; or &man.ee.1;.  First, add the
         frequencies for the target system's monitor.  These are usually
         expressed as a horizontal and vertical synchronization rate.  These
         values are added to the <filename>XF86Config.new</filename> file
         under the <literal>"Monitor"</literal> section:</para>
 
       <programlisting>Section "Monitor"
         Identifier   "Monitor0"
         VendorName   "Monitor Vendor"
         ModelName    "Monitor Model"
         HorizSync    30-107
         VertRefresh  48-120
 EndSection</programlisting>
 
       <para>The <varname>HorizSync</varname> and
         <varname>VertRefresh</varname> keywords may not exist in the
         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 were
         entered.</para>
 
       <para>X allows DPMS (Energy Star) features to be used with capable
         monitors. The &man.xset.1; program controls the time-outs and can force
         standby, suspend, or off modes.  If you wish to enable DPMS features
         for your monitor, you must add the following line to the monitor
         section:</para>
 
       <programlisting>
         Option       "DPMS"</programlisting>
 
       <indexterm>
         <primary><command>XF86Config</command></primary>
       </indexterm>
 
       <para>While the <filename>XF86Config.new</filename>
         configuration file is still open in an editor, select
         the default resolution and color depth desired.  This is
         defined in the <literal>"Screen"</literal> section:</para>
 
       <programlisting>Section "Screen"
         Identifier "Screen0"
         Device     "Card0"
         Monitor    "Monitor0"
         DefaultDepth 24
         SubSection "Display"
                 Depth     24
                 Modes     "1024x768"
         EndSubSection
 EndSection</programlisting>
 
       <para>The <varname>DefaultDepth</varname> keyword describes
         the color depth to run at by default.  This can be overridden
         with the <command>-bpp</command> command line switch to
         &man.XFree86.1;.
         The <varname>Modes</varname> keyword
         describes the resolution to run at for the given color depth.
         Note that only VESA standard modes are supported as defined by
         the target system's graphics hardware.
         In the example above, the default color depth is twenty-four
         bits per pixel.  At this color depth, the accepted resolution is
         one thousand twenty-four pixels by seven hundred and sixty-eight
         pixels.</para>
 
       <para>Finally, write the configuration file and test it using
         the test mode given above.  If all is well, the configuration
         file needs to be installed in a common location where
         &man.XFree86.1;
         can find it.
         This is typically <filename>/etc/X11/XF86Config</filename> or
         <filename>/usr/X11R6/etc/X11/XF86Config</filename>.</para>
 
       <screen>&prompt.root; <userinput>cp XF86Config.new /etc/X11/XF86Config</userinput></screen>
 
       <para>Once the configuration file has been placed in a common
         location, configuration is complete.  In order to start
         <application>XFree86 4.X</application> with &man.startx.1;,
         install the <filename role="package">x11/wrapper</filename> port.
         <application>XFree86 4.X</application> can also be started with
         &man.xdm.1;.</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 <devicename>agpgart</devicename>
           AGP programming interface for <application>XFree86</application>
           to drive the card.  To use <devicename>agpgart</devicename>,
           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; at boot time.
           Simply add this line to
           <filename>/boot/loader.conf</filename>:</para>
 
         <programlisting>agp_load="YES"</programlisting>
 
         <para>Next, if you are running FreeBSD&nbsp;4.X or earlier, a device node needs to be created for the
           programming interface.  To create the AGP device node, run
           &man.MAKEDEV.8; in the <filename>/dev</filename>
           directory:</para>
 
         <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV agpgart</userinput></screen>
 
 	<note>
 	  <para>FreeBSD&nbsp;5.X or later, use &man.devfs.5; to allocate
 	    device nodes transparently for the user, therefore you do
 	    not have to run &man.MAKEDEV.8;.</para>
 	</note>
 
         <para>This will allow configuration of the hardware as any other
           graphics board.</para>
 
 	<para>If you are using <application>XFree86 4.1.0</application> (or
 	  later) and messages about unresolved symbols like
           <literal>fbPictureInit</literal> appear, try adding the
           following line after <literal>Driver "i810"</literal> in the
           <application>XFree86</application> configuration file:</para>
         <programlisting>Option "NoDDC"</programlisting>
       </sect3>
     </sect2>
   </sect1>
 
   <sect1 id="x-fonts">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Murray</firstname>
           <surname>Stokely</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>Using Fonts in 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
     <application>Netscape</application> 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 role="package">x11-fonts/urwfonts</filename>) includes
     high quality versions of standard type1 fonts (Times Roman,
     Helvetica, Palatino and others).  The Freefont collection
     (<filename role="package">x11-fonts/freefont</filename>) includes
     many more fonts, but most of them are intended for use in
     graphics software such as the <application>Gimp</application>, and are not
     complete enough to serve as screen fonts.  In addition,
     <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, 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, add an appropriate line to the
       <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 the X session
         run:</para>
 
       <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/URW</userinput>
 &prompt.user; <userinput>xset fp rehash</userinput></screen>
 
       <para>This will work but will be lost when the X session is closed,
     unless it is added to the startup file (<filename>~/.xinitrc</filename>
     for a normal <command>startx</command> session,
     or <filename>~/.xsession</filename> when logging in through a
     graphical login manager like <application>XDM</application>).
     A third way is to use the new
     <filename>XftConfig</filename> file: see the
     section on <link linkend="antialias">anti-aliasing</link>.
     </para>
     </sect2>
 
     <sect2 id="truetype">
     <title>TrueType Fonts</title>
 
     <para><application>XFree86 4.X</application> 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 back-ends.  To enable the freetype module just add the
     following line to the <literal>"Module"</literal> section of the
     <filename>/etc/X11/XF86Config</filename> file.</para>
 
     <programlisting>Load  "freetype"</programlisting>
 
     <para>For <application>XFree86 3.3.X</application>, a separate
       TrueType font server is needed.
       <application>Xfstt</application> is commonly used for
       this purpose.  To install <application>Xfstt</application>,
       simply install the port
       <filename role="package">x11-servers/Xfstt</filename>.</para>
 
     <para>Now make a directory for the TrueType fonts (for example,
       <filename>/usr/X11R6/lib/X11/fonts/TrueType</filename>)
       and copy all of the TrueType fonts into this directory.  Keep in
       mind that TrueType fonts cannot be directly taken from a
       Macintosh; they must be in Unix/DOS/Windows format for use by
       <application>XFree86</application>.  Once the files have been
       copied into this directory, use
       <application>ttmkfdir</application> to create a
       <filename>fonts.dir</filename> file, so that the X font renderer
       knows that these new files have been installed.
       <command>ttmkfdir</command> is available from the FreeBSD
       Ports Collection as
       <filename role="package">x11-fonts/ttmkfdir</filename>.</para>
 
     <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/TrueType</userinput>
 &prompt.root; <userinput>ttmkfdir > fonts.dir</userinput></screen>
 
     <para>Now add the TrueType directory to the font
       path.  This is just the same as described above for <link
       linkend="type1">Type1</link> fonts, that is, use</para>
 
     <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/TrueType</userinput>
 &prompt.user; <userinput>xset fp rehash</userinput></screen>
 
     <para>or add a <option>FontPath</option> line to the
        <filename>XF86Config</filename> file.</para>
 
       <para>That's it.  Now <application>Netscape</application>,
         <application>Gimp</application>,
         <application>StarOffice</application>, and all of the other X
         applications should now recognize the installed TrueType
         fonts.  Extremely small fonts (as with text in a high resolution
         display on a web page) and extremely large fonts (within
         <application>StarOffice</application>) will look much better
         now.</para>
     </sect2>
 
     <sect2 id="antialias">
     <title>Anti-Aliased Fonts</title>
 
     <para>Starting with version 4.0.2, <application>XFree86</application>
       supports anti-aliased
       fonts.  Currently, most software has not been updated to take
       advantage of this new functionality.  However, Qt (the toolkit
       for the <application>KDE</application> desktop) does; so if
       <application>XFree86 4.0.2</application> is used
       (or higher), Qt 2.3 (or higher) and <application>KDE</application>,
       all KDE/Qt applications can be made to use anti-aliased
       fonts.</para>
 
     <para>To configure anti-aliasing, 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, tell the X server about the fonts that are to be
       anti-aliased.  For each font directory, add a line similar
       to this:</para>
 
       <programlisting>dir "/usr/X11R6/lib/X11/fonts/Type1"</programlisting>
 
     <para>Likewise for the other font directories (URW, TrueType, etc)
       containing fonts to be anti-aliased.  Anti-aliasing makes
       sense only for scalable fonts (basically, Type1 and TrueType) so
       do not include bitmap font directories here.  The
       directories included here can now be commented out
       of the <filename>XF86Config</filename> file.</para>
 
     <para>Anti-aliasing makes borders slightly fuzzy, which makes very
       small text more readable and removes <quote>staircases</quote> from
       large text, but can cause eyestrain if applied to normal text.  To
       exclude 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>Spacing for some monospaced fonts may also be inappropriate
       with anti-aliasing.  This seems to be an issue with
       <application>KDE</application>, in particular.  One possible fix for
       this is to force the spacing for such fonts to be 100.  Add the
       following lines:</para>
 
       <programlisting>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
        <literal>"mono"</literal>), and then add:</para>
 
       <programlisting>match any family == "mono" edit spacing = 100;</programlisting>
 
       <para>Supposing the
         <literal>Lucidux</literal> fonts as desired whenever
         monospaced fonts are required (these look nice, and do not seem
         to suffer from the spacing problem), 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, it is nice 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>One last point: with an LCD screen, sub-pixel sampling may be
         desired.  This basically treats the (horizontally separated)
         red, green and blue components separately to improve the horizontal
         resolution; the results can be dramatic.  To enable this, add the
         line somewhere in the <filename>XftConfig</filename> file:</para>
 
        <programlisting>match edit rgba=rgb;</programlisting>
 
        <para>(depending on the sort of display, the last word may need to
 	be changed from <quote>rgb</quote> to <quote>bgr</quote>,
 	<quote>vrgb</quote> or <quote>vbgr</quote>: experiment and see which
 	works best.)</para>
 
        <para>Anti-aliasing should be enabled the next time the X server is
         started.  However, note that programs must know how to take
         advantage of it.  At the present time, the toolkit
         Qt does, so the entire <application>KDE</application> environment
         can use anti-aliased fonts
         (see <xref linkend="x11-wm-kde-antialias"> on
         <application>KDE</application> for
         details); 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.  In fact, there
 	is now a port called <filename role="package">x11/gdkxft</filename>
 	which allows one to use antialiased fonts without recompiling: see
         <xref linkend="x11-wm-gnome-antialias"> for details.</para>
 
        <para>Anti-aliasing is still new to FreeBSD and
         <application>XFree86</application>;
         configuring it should get easier with time, and it will soon be
         supported by many more applications.</para>
     </sect2>
   </sect1>
 
   <sect1 id="x-xdm">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Seth</firstname>
           <surname>Kingsley</surname>
           <contrib>Contributed by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>The X Display Manager</title>
     <sect2>
       <title>Overview</title>
       <para>The X Display Manager (<application>XDM</application>) is
         an optional part of the X Window System that is used for login
         session management.  This is useful for several types of
         situations, including minimal <quote>X Terminals</quote>,
         desktops, and large network display
         servers.  Since the X Window System is network and protocol
         independent, there are a wide variety of possible configurations
         for running X clients and servers on different machines
         connected by a network.  <application>XDM</application> provides
         a graphical interface for choosing which display server to
         connect to, and entering authorization information such as a
         login and password combination.</para>
 
       <para>Think of <application>XDM</application> as
         providing the same functionality to the user as the
         &man.getty.8; utility (see <xref linkend="term-config"> for
           details).  That is, it performs system logins to the display
           being connected to and then runs a session manager on behalf of
           the user (usually an X window
           manager).  <application>XDM</application> then waits for this
           program to exit, signaling that the user is done and should be
           logged out of the display.  At this point,
           <application>XDM</application> can display the login and display
           chooser screens for the next user to login.</para>
     </sect2>
 
     <sect2>
       <title>Using XDM</title>
 
       <para>The <application>XDM</application> daemon program is
         located in <filename>/usr/X11R6/bin/xdm</filename>.  This program
         can be run at any time as <username>root</username> and it will
         start managing the X display on the local machine.  If
         <application>XDM</application> is to be run every
         time the machine boots up, a convenient way to do this is by
         adding an entry to <filename>/etc/ttys</filename>.  For more
         information about the format and usage of this file, see <xref
         linkend="term-etcttys">.  There is a line in the default
         <filename>/etc/ttys</filename> file for running the
         <application>XDM</application> daemon on a virtual terminal:</para>
 
       <screen>ttyv8   "/usr/X11R6/bin/xdm -nodaemon"  xterm   off secure</screen>
 
       <para>By default this entry is disabled; in order to enable it
         change field 5 from <literal>off</literal> to
         <literal>on</literal> and restart &man.init.8; using the
         directions in <xref linkend="term-hup">.  The first field, the
         name of the terminal this program will manage, is
         <literal>ttyv8</literal>.  This means that
         <application>XDM</application> will start running on the 9th
         virtual terminal.</para>
     </sect2>
 
     <sect2>
       <title>Configuring XDM</title>
 
       <para>The <application>XDM</application> configuration directory
         is located in <filename>/usr/X11R6/lib/X11/xdm</filename>.  In
         this directory there are several files used to change the
         behavior and appearance of
         <application>XDM</application>.  Typically these files will
         be found:</para>
 
         <informaltable frame="none">
           <tgroup cols="2">
             <thead>
               <row>
                 <entry>File</entry>
                 <entry>Description</entry>
               </row>
             </thead>
 
             <tbody>
               <row>
                 <entry><filename>Xaccess</filename></entry>
                 <entry>Client authorization ruleset.</entry>
               </row>
 
               <row>
                 <entry><filename>Xresources</filename></entry>
                 <entry>Default X resource values.</entry>
               </row>
 
               <row>
                 <entry><filename>Xservers</filename></entry>
                 <entry>List of remote and local displays to manage.</entry>
               </row>
 
               <row>
                 <entry><filename>Xsession</filename></entry>
                 <entry>Default session script for logins.</entry>
               </row>
 
               <row>
                 <entry><filename>Xsetup_</filename>*</entry>
                 <entry>Script to launch applications before the login
                   interface.</entry>
               </row>
 
               <row>
                 <entry><filename>xdm-config</filename></entry>
                 <entry>Global configuration for all displays running on
                   this machine.</entry>
               </row>
 
               <row>
                 <entry><filename>xdm-errors</filename></entry>
                 <entry>Errors generated by the server program.</entry>
               </row>
 
               <row>
                 <entry><filename>xdm-pid</filename></entry>
                 <entry>The process ID of the currently running XDM.</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
 
       <para>Also in this directory are a few scripts and programs used
         to setup the desktop when <application>XDM</application> is
         running.  The purpose of each of these files will be briefly
         described.  The exact syntax and usage of all of these files is
         described in &man.xdm.1;.</para>
 
       <para>The default configuration is a simple rectangular login
         window with the hostname of the machine displayed at the top in
         a large font and <quote>Login:</quote> and
         <quote>Password:</quote> prompts below.  This is a good starting
         point for changing the look and feel of
         <application>XDM</application> screens.</para>
 
       <sect3>
         <title>Xaccess</title>
 
         <para>The protocol for connecting to
           <application>XDM</application> controlled displays is called
           the X Display Manager Connection Protocol (XDMCP).  This file
           is a ruleset for controlling XDMCP connections from remote
           machines.  By default, it allows any client to connect, but
           that does not matter unless the <filename>xdm-config</filename>
           is changed to listen for remote connections.</para>
       </sect3>
 
       <sect3>
         <title>Xresources</title>
         <para>This is an application-defaults file for the display
           chooser and the login screens.  This is where the appearance
           of the login program can be modified.  The format is identical
           to the app-defaults file described in the
           <application>XFree86</application> documentation.</para>
       </sect3>
 
       <sect3>
         <title>Xservers</title>
         <para>This is a list of the remote displays the chooser should
           provide as choices.</para>
       </sect3>
 
       <sect3>
         <title>Xsession</title>
         <para>This is the default session script for
           <application>XDM</application> to run after a user has logged
           in.  Normally each user will have a customized session script
           in <filename>~/.xsession</filename> that overrides this
           script.</para>
       </sect3>
 
       <sect3>
         <title>Xsetup_*</title>
         <para>These will be run automatically before displaying the
           chooser or login interfaces.  There is a script for each
           display being used, named <filename>Xsetup_</filename> followed
           by the local display number (for instance
           <filename>Xsetup_0</filename>).  Typically these scripts will
           run one or two programs in the background such as
           <command>xconsole</command>.</para>
       </sect3>
 
       <sect3>
         <title>xdm-config</title>
         <para>This contains settings in the form of app-defaults
           that are applicable to every display that this installation
           manages.</para>
       </sect3>
 
       <sect3>
         <title>xdm-errors</title>
         <para>This contains the output of the X servers that
           <application>XDM</application> is trying to run.  If a display
           that <application>XDM</application> is trying to start hangs
           for some reason, this is a good place to look for error
           messages.  These messages are also written to the user's
           <filename>~/.xsession-errors</filename> file on a per-session
           basis.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>Running a Network Display Server</title>
 
       <para>In order for other clients to connect to the display
         server, edit the access control rules, and enable the connection
         listener.  By default these are set to conservative values.
         To make <application>XDM</application> listen for connections,
         first comment out a line in the <filename>xdm-config</filename>
         file:</para>
 
       <screen>! SECURITY: do not listen for XDMCP or Chooser requests
 ! Comment out this line if you want to manage X terminals with xdm
 DisplayManager.requestPort:     0</screen>
 
       <para>and then restart <application>XDM</application>.  Remember that
         comments in app-defaults files begin with a <quote>!</quote>
         character, not the usual <quote>#</quote>.  More strict
         access controls may be desired.  Look at the example
         entries in <filename>Xaccess</filename>, and refer to the
         &man.xdm.1; manual page.</para>
     </sect2>
 
      <sect2>
         <title>Replacements for XDM</title>
 
         <para>Several replacements for the default
           <application>XDM</application> program exist.  One of them,
           <application>KDM</application> (bundled with
           <application>KDE</application>) is described later in this
           chapter.  <application>KDM</application> offers many visual
           improvements and cosmetic frills, as well as the
           functionality to allow users to choose their window manager
           of choice at login time.</para>
      </sect2>
   </sect1>
 
   <sect1 id="x11-wm">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Valentino</firstname>
           <surname>Vaschetto</surname>
           <contrib>Contributed by </contrib>
         </author>
         <!-- June 2001 -->
       </authorgroup>
     </sect1info>
 
     <title>Desktop Environments</title>
 
     <para>This section describes the different desktop environments
       available for X on FreeBSD.  A <quote>desktop environment</quote>
       can mean anything ranging from a simple window manager to a
       complete suite of desktop applications, such as
       <application>KDE</application> or <application>GNOME</application>.
     </para>
 
     <sect2 id="x11-wm-gnome">
       <title>GNOME</title>
 
       <sect3 id="x11-wm-gnome-about">
         <title>About GNOME</title>
 
         <para><application>GNOME</application> is a user-friendly
           desktop environment that enables users to easily use and
           configure their computers.  <application>GNOME</application>
           includes a panel (for starting applications and displaying
           status), a desktop (where data and applications can be
           placed), a set of standard desktop tools and applications, and
           a set of conventions that make it easy for applications to
           cooperate and be consistent with each other.  Users of other
           operating systems or environments should feel right at home
           using the powerful graphics-driven environment that
           <application>GNOME</application> provides.</para>
       </sect3>
 
       <sect3 id="x11-wm-gnome-install">
         <title>Installing GNOME</title>
 
         <para>The easiest way to install
           <application>GNOME</application> is through the
           <quote>Desktop Configuration</quote> menu during the FreeBSD
 	  installation process as described in <xref
 	  linkend="default-desktop"> of Chapter&nbsp;2.  It can also
           be easily installed from a package or the ports
           collection:</para>
 
         <para>To install the <application>GNOME</application> package
           from the network, simply type:</para>
 
         <screen>&prompt.root; <userinput>pkg_add -r gnome</userinput></screen>
 
         <para>To build <application>GNOME</application> from source, 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 <application>GNOME</application> is installed,
           the X server must be told to start
           <application>GNOME</application> instead of a default window
           manager.  If a custom <filename>.xinitrc</filename> is already in
           place, simply replace the line that starts the current window
           manager with one that starts
           <application>/usr/X11R6/bin/gnome-session</application> instead.
           If nothing special has been done to configuration file,
           then it is enough to simply type:</para>
 
         <screen>&prompt.user; <userinput>echo "/usr/X11R6/bin/gnome-session" &gt; ~/.xinitrc</userinput></screen>
 
         <para>Next, type <command>startx</command>, and the
           <application>GNOME</application> desktop environment will be
           started.</para>
 
         <note><para>If a display manager, like
           <application>XDM</application>, is being used, this will not work.
           Instead, create an executable <filename>.xsession</filename>
           file with the same command in it.  To do this, edit the file
           and replace the existing window manager command with
           <application>/usr/X11R6/bin/gnome-session</application>:
           </para></note>
 
         <screen>&prompt.user; <userinput>echo "#!/bin/sh" > ~/.xsession</userinput>
 &prompt.user; <userinput>echo "/usr/X11R6/bin/gnome-session" >> ~/.xsession</userinput>
 &prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
 
         <para>Another option is to configure the display manager to
           allow choosing the window manager at login time; the section on
           <link linkend="x11-wm-kde-details">KDE details</link>
           explains how to do this for <application>kdm</application>, the
           display manager of <application>KDE</application>.</para>
       </sect3>
 
       <sect3 id="x11-wm-gnome-antialias">
         <title>Anti-aliased fonts with GNOME</title>
 
         <para>While anti-aliased fonts made their first appearance on
 	  <application>XFree86</application> desktops in the
 	  <application>KDE</application> environment and are supported there
 	  in the standard installation, it is also possible to use them with
 	  GTK applications such as the <application>GNOME</application>
 	  environment.  The most straightforward way is probably by
           using the <application>libgdkxft</application> library, in
 	  the <filename role="package">x11/gdkxft</filename> port.  After
 	  installing this port, read the
           <filename>/usr/X11R6/share/doc/gdkxft/README</filename> file
           carefully.</para>
 
         <para>Then, all that is needed is to tell GTK
           applications to look for their font-rendering functions in
           <filename>libgdkxft.so</filename> before looking in the
           standard place, <filename>libgdk.so</filename>.  This is
           easily accomplished by setting an environment variable to
           point to the right place; with the Bourne shell
           (<application>/bin/sh</application>) or similar shells, type
           the command (to start <application>The Gimp</application>,
           say)</para>
 
 	<screen>&prompt.user; <userinput>LD_PRELOAD=/usr/X11R6/lib/libgdkxft.so gimp</userinput></screen>
 
         <para>and with csh and similar shells, type</para>
 
 	<screen>&prompt.user; <userinput>setenv LD_PRELOAD /usr/X11R6/lib/libgdkxft.so</userinput>
 &prompt.user; <userinput>gimp</userinput></screen>
 
         <para>Or, the commands</para>
 
 	<programlisting>LD_PRELOAD=/usr/X11R6/lib/libgdkxft.so
 export LD_PRELOAD</programlisting>
 
         <para>can be put into <filename>.xinitrc</filename>,
           <filename>.xsession</filename> or in the appropriate
           place(s) in
           <filename>/usr/X11R6/lib/X11/xdm/Xsession</filename>,
           depending on how X is normally started.  However, this
           short-cut may cause problems if Linux GTK binaries are
           run.</para>
       </sect3>
     </sect2>
 
     <sect2 id="x11-wm-kde">
       <title>KDE</title>
 
       <sect3 id="x11-wm-kde-about">
         <title>About KDE</title>
 
         <para><application>KDE</application> is an easy to use
           contemporary desktop environment.  Some of the things that
           <application>KDE</application> brings to the user are:</para>
 
         <itemizedlist>
           <listitem>
 	    <para>A beautiful contemporary desktop</para>
 	  </listitem>
 
           <listitem>
 	    <para>A desktop exhibiting complete network transparency</para>
 	  </listitem>
 
           <listitem>
 	    <para>An integrated help system allowing for convenient,
 	      consistent access to help on the use of the
 	      <application>KDE</application> desktop and its
 	      applications</para>
 	  </listitem>
 
           <listitem>
 	    <para>Consistent look and feel of all
               <application>KDE</application> applications</para>
 	  </listitem>
 
           <listitem>
 	    <para>Standardized menu and toolbars, keybindings, color-schemes,
 	      etc.</para>
 	  </listitem>
 
           <listitem>
 	    <para>Internationalization: <application>KDE</application>
               is available in more than 40 languages</para>
 	  </listitem>
 
           <listitem>
 	    <para>Centralized consisted dialog driven desktop
 	      configuration</para>
 	  </listitem>
 
           <listitem>
 	    <para>A great number of useful
               <application>KDE</application> applications</para>
 	  </listitem>
         </itemizedlist>
 
         <para><application>KDE</application> has an office application
           suite based on <application>KDE</application>'s
           <quote>KParts</quote> technology consisting
           of a spread-sheet, a presentation application, an organizer, a
           news client and more.  <application>KDE</application> also
           comes with a web browser called
           <application>Konqueror</application>, which represents
           a solid competitor to other existing web browsers on Unix
           systems.  More information on <application>KDE</application>
           can be found on the <ulink url="http://www.kde.org/">KDE
           website.</ulink></para>
       </sect3>
 
       <sect3 id="x11-wm-kde-install">
         <title>Installing KDE</title>
 
         <para>Just as with <application>GNOME</application> or any
           other desktop environment, the easiest way to install
           <application>KDE</application> is through the <quote>Desktop
           Configuration</quote> menu during the FreeBSD installation
 	  process as described in <xref linkend="default-desktop"> of Chapter
 	  2.  Once again, the software can be easily installed from a package
 	  or from the ports collection:</para>
 
         <para>To install the <application>KDE</application> package
           from the network, simply type:</para>
 
         <screen>&prompt.root; <userinput>pkg_add -r kde3</userinput></screen>
 
         <para>To build <application>KDE</application> from source,
           use the ports tree:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde3</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
         <para>After <application>KDE</application> has been installed,
           the X server must be told to launch this application
           instead of the default window manager.  This is accomplished
           by editing the <filename>.xinitrc</filename> file:</para>
 
         <screen>&prompt.user; <userinput>echo "exec startkde" &gt; ~/.xinitrc</userinput></screen>
 
 	<para>Now, whenever the X Window System is invoked with
 	  <command>startx</command>,
           <application>KDE</application> will be the desktop.</para>
 
         <para>If a display manager such as
           <application>xdm</application> is being used, the
           configuration is slightly different.  Edit the
           <filename>.xsession</filename> file instead.  Instructions
           for <application>kdm</application> are described later in
           this chapter.</para>
       </sect3>
     </sect2>
 
     <sect2 id="x11-wm-kde-details">
         <title>More Details on KDE</title>
 
         <para>Now that <application>KDE</application> is installed on
           the system, most things can be discovered through the
           help pages, or just by pointing and clicking at various menus.
           Windows or Mac users will feel quite at home.</para>
 
         <para>The best reference for <application>KDE</application> is
           the on-line documentation.  <application>KDE</application>
           comes with its own web browser,
           <application>Konqueror</application>, dozens of useful
           applications, and extensive documentation.  The remainder of
           this section discusses the technical items that are
           difficult to learn by random exploration.</para>
 
       <sect3 id="x11-wm-kde-kdm">
         <title>The KDE display manager</title>
 
         <para>An administrator of a multi-user system may wish to have
           a graphical login screen to welcome users.
           <link linkend="x-xdm"><filename>xdm</filename></link> can be
           used, as described earlier.  However,
           <application>KDE</application> includes an
           alternative, <application>kdm</application>, which is designed
           to look more attractive and include more login-time options.
           In particular, users can easily choose (via a menu) which
           desktop environment (<application>KDE</application>,
           <application>GNOME</application>, or something else) to run
           after logging on.</para>
 
         <para>To begin with, run the <application>KDE</application>
           control panel, <command>kcontrol</command>, as
           <username>root</username>.  It is generally considered
           unsafe to run the entire X environment as
           <username>root</username>.  Instead, run the window manager
           as a normal user, open a terminal window (such as
           <filename>xterm</filename> or <application>KDE</application>'s
           <filename>konsole</filename>), become <username>root</username>
           with <userinput>su</userinput> (the user must be in the
           <groupname>wheel</groupname>
           group in <filename>/etc/group</filename> for this), and then
           type <userinput>kcontrol</userinput>.</para>
 
 	<para>Click on the icon on the left marked
 	  <guibutton>System</guibutton>, then on <guibutton>Login
 	  manager</guibutton>.  On the right there are
           various configurable options, which the
           <application>KDE</application> manual will explain in greater
           detail.  Click on <guibutton>sessions</guibutton> on the right.
           Click <guibutton>New type</guibutton> to add various window
           managers and desktop environments.  These are just labels,
           so they can say <application>KDE</application> and
           <application>GNOME</application> rather than
           <application>startkde</application> or
           <application>gnome-session</application>.
           Include a label <literal>failsafe</literal>.</para>
 
         <para>Play with the other menus as well, they are mainly
           cosmetic and self-explanatory.  When you are done, click on
           <guibutton>Apply</guibutton> at the bottom, and quit the
           control center.</para>
 
         <para>To make sure <application>kdm</application> understands
           what the labels (<application>KDE</application>,
           <application>GNOME</application> etc) mean, edit the files used
           by <link linkend="x-xdm">xdm</link>.
           <note><para>In <application>KDE 2.2</application> this has
             changed: <application>kdm</application> now uses its own
             configuration files.  Please see the <application>KDE
             2.2</application> documentation for details.</para>
           </note>
           In a terminal window, as <username>root</username>,
           edit the file
           <filename>/usr/X11R6/lib/X11/xdm/Xsession</filename>.  There is
           a section in the middle like this:</para>
 
 	<screen>case $# in
 1)
         case $1 in
         failsafe)
                 exec xterm -geometry 80x24-0-0
                 ;;
         esac
 esac</screen>
 
         <para>A few lines need to be added to this section.
           Assuming the labels from used were <quote>KDE</quote> and
           <quote>GNOME</quote>,
           use the following:</para>
 
 	<screen>case $# in
 1)
         case $1 in
         kde)
                 exec /usr/local/bin/startkde
                 ;;
         GNOME)
                 exec /usr/X11R6/bin/gnome-session
                 ;;
         failsafe)
                 exec xterm -geometry 80x24-0-0
                 ;;
         esac
 esac</screen>
 
         <para>For the <application>KDE</application>
           login-time desktop background to be honored,
           the following line needs to be added to
           <filename>/usr/X11R6/lib/X11/xdm/Xsetup_0</filename>:</para>
 
         <screen>/usr/local/bin/kdmdesktop</screen>
 
         <para>Now, make sure <application>kdm</application> is listed in
           <filename>/etc/ttys</filename> to be started at the next bootup.
           To do this, simply follow the instructions from the previous
           section on <link linkend="x-xdm">xdm</link> and replace
           references to the <command>/usr/X11R6/bin/xdm</command>
           program with <command>/usr/local/bin/kdm</command>.</para>
       </sect3>
 
       <sect3 id="x11-wm-kde-antialias">
         <title>Anti-aliased Fonts</title>
 
         <para>Starting with version 4.0.2,
           <application>XFree86</application> supports anti-aliasing via
 	  its <quote>RENDER</quote> extension, and starting with version 2.3,
 	  Qt (the toolkit used by <application>KDE</application>) supports
 	  this extension.  Configuring this is described in <xref
           linkend="antialias"> on antialiasing X11 fonts.  So, with
           up-to-date software, anti-aliasing is possible on a
           <application>KDE</application> desktop.  Just go to the KDE
 	  menu, go to <guimenuitem>Preferences</guimenuitem> -&gt;
 	  <guimenuitem>Look and Feel</guimenuitem> -&gt;
 	  <guimenuitem>Fonts</guimenuitem>, and click on the check box
           <guibutton>Use Anti-Aliasing for Fonts and Icons</guibutton>.
           For a Qt application which is not part of
 	  <application>KDE</application>, the environment variable
 	  <varname>QT_XFT</varname> needs to be set to <literal>true</literal>
 	  before starting the program.</para>
 
        </sect3>
      </sect2>
 
      <sect2 id="x11-wm-xfce">
          <title>XFce</title>
        <sect3 id="x11-wm-xfce-about">
          <title>About XFce</title>
 
         <para><application>XFce</application> is a desktop environment
           based on the GTK
           toolkit used by <application>GNOME</application>, but is much
           more lightweight and meant for those who want a simple,
           efficient desktop which is nevertheless easy to use and
           configure.  Visually, it looks very much like
           <application>CDE</application>, found on commercial Unix
           systems.  Some of <application>XFce</application>'s features
           are:</para>
 
          <itemizedlist>
            <listitem>
 	     <para>A simple, easy-to-handle desktop</para>
            </listitem>
 
            <listitem>
 	     <para>Fully configurable via mouse, with drag and
                drop, etc </para>
            </listitem>
 
            <listitem>
 	     <para>Main panel similar to <application>CDE</application>, with
 	       menus, applets and app launchers</para>
            </listitem>
 
            <listitem>
 	     <para>Integrated window manager, file manager, sound manager,
 	       <application>GNOME</application> compliance module, and other
 	       things</para>
            </listitem>
 
            <listitem>
 	     <para>Themeable (since it uses GTK)</para>
            </listitem>
 
            <listitem>
 	     <para>Fast, light and efficient: ideal for older/slower machines
 	       or machines with memory limitations</para>
            </listitem>
          </itemizedlist>
 
          <para>More information on <application>XFce</application>
           can be found on the <ulink url="http://www.xfce.org/">XFce
             website</ulink>.</para>
        </sect3>
 
        <sect3 id="x11-wm-xfce-install">
          <title>Installing XFce</title>
 
         <para>A binary package for <application>XFce</application>
           exists (at the time of writing).  To install, simply type:</para>
 
         <screen>&prompt.root; <userinput>pkg_add -r xfce</userinput></screen>
 
         <para>Alternatively, to build from source, use the ports
           collection:</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
         <para>Now, tell the X server to launch
          <application>XFce</application> the next time X is started.
          Simply type this:</para>
 
         <screen>&prompt.user; <userinput>echo "/usr/X11R6/bin/startxfce" &gt; ~/.xinitrc</userinput></screen>
 
         <para>The next time X is started,
           <application>XFce</application> will be the desktop.
           As before, if a display manager like
           <filename>xdm</filename> is being used, create an
           <filename>.xsession</filename>, as described in the
           section on <link linkend="x11-wm-gnome">GNOME</link>, but
           with the <filename>/usr/X11R6/bin/startxfce</filename>
           command; or, configure the display manager to allow
           choosing a desktop at login time, as explained in
           the section on <link linkend="x11-wm-kde-kdm">kdm</link>.</para>
       </sect3>
     </sect2>
   </sect1>
 
 </chapter>
 
 <!--
      Local Variables:
      mode: sgml
      sgml-declaration: "../chapter.decl"
      sgml-indent-data: t
      sgml-omittag: nil
      sgml-always-quote-attributes: t
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index 1f3329500e..5c8b8c5b22 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -1,6158 +1,6158 @@
 <!--
      The FreeBSD Documentation Project
 
      $FreeBSD$
 -->
 
 <!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 PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"> %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>
       <year>2001</year>
       <year>2002</year>
       <holder role="mailto:doc@FreeBSD.org">The FreeBSD Documentation
 	Project</holder>
     </copyright>
 
     &bookinfo.legalnotice;
   </bookinfo>
 
 
-    <chapter>
+    <chapter id="own-port">
       <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>
+      <sect1 id="porting-makefile">
         <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>
+      <sect1 id="porting-desc">
         <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 <quote>packing list</quote> 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; manual 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>
+      <sect1 id="porting-checksum">
         <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="../../articles/contributing/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>After you have submitted your port, please be patient.
 	  Sometimes it can take a few months before a port is included
 	  in FreeBSD, although it might only take a few days.  You can
 	  view the list of <ulink
 	  url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports
 	  waiting to be committed to FreeBSD</ulink>.</para>
 
         <para>Once we have looked at your port, we will get back to you if necessary, and put
           it in the tree.  Your name will also appear in the list of
           <ulink url="../../articles/contributors/contrib-additional.html">Additional FreeBSD Contributors</ulink>
           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
             <quote>New port: &lt;short description of the port&gt;</quote> for
             new ports and
             <quote>Update port: &lt;category&gt;/&lt;port&gt; &lt;short description
             of the update&gt;</quote> 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>
+    <chapter id="slow">
       <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>
+      <sect1 id="slow-work">
         <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 <quote>main</quote> 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>
+      <sect1 id="slow-sources">
         <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 <quote>house</quote> 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>
+      <sect1 id="slow-modifying">
         <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 <quote>plug-and-play</quote> 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>
+      <sect1 id="slow-patch">
         <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>
 
         <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>
 
         <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>
+      <sect1 id="slow-configure">
         <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>
+      <sect1 id="slow-user-input">
         <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 <quote>overnight builds</quote> 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 CDROMs and FTP.</para>
       </sect1>
     </chapter>
 
-    <chapter>
+    <chapter id="makefile">
       <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>
+      <sect1 id="makefile-source">
         <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>
+    <sect1 id="makefile-naming">
       <title>Naming</title>
 
       <para>The first part of the port's <filename>Makefile</filename> names
 	the port, describes its version number, and lists it in the correct
 	category.</para>
 
       <sect2>
         <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>
       </sect2>
 
       <sect2>
 	<title><makevar>PORTREVISION</makevar> and
 	  <makevar>PORTEPOCH</makevar></title>
 
 	<sect3>
 	  <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 structure 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
 		behavior 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
 		affect 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>
 	</sect3>
 
 	<sect3>
 	  <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 (20000801), but
 	    the <literal>,1</literal> suffix is treated specially by
 	    automated tools and found to be greater than the implied
 	    suffix <literal>,0</literal> 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 &mdash; such as a code
 	    <quote>snapshot</quote> release.  The temptation is to label the
 	    release with the release date, which will cause problems
 	    as in the example above when a new <quote>official</quote> 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>
 	</sect3>
 
 	<sect3>
 	  <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 <literal>0.2</literal>
 	    (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 <quote>newer</quote>. 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>
         </sect3>
       </sect2>
 
       <sect2>
         <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>
       </sect2>
 
     <sect2 id="porting-pkgname">
       <title>Package Naming Conventions</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 <quote>patchlevel</quote>), 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 <quote>alpha</quote>, <quote>beta</quote>, <quote>rc</quote>, or <quote>pre</quote>, 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>
     </sect2>
     </sect1>
 
-    <sect1>
+    <sect1 id="makefile-categories">
       <title>Categorisation</title>
 
       <sect2>
         <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 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>
       </sect2>
 
       <sect2 id="porting-categories">
         <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>accessibility*</filename></entry>
                 <entry>Ports to help disabled users.</entry>
               </row>
 
               <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>finance</filename></entry>
                 <entry>Monetary, financial and related applications.</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>haskell*</filename></entry>
                 <entry>Software related to the Haskell language.</entry>
               </row>
 
               <row>
                 <entry><filename>hebrew</filename></entry>
                 <entry>Hebrew language support.</entry>
               </row>
 
               <row>
                 <entry><filename>hungarian</filename></entry>
                 <entry>Hungarian language support.</entry>
               </row>
 
               <row>
                 <entry><filename>ipv6*</filename></entry>
                 <entry>IPv6 related software.</entry>
               </row>
 
               <row>
                 <entry><filename>irc</filename></entry>
                 <entry>Internet Relay Chat utilities.</entry>
               </row>
 
               <row>
                 <entry><filename>japanese</filename></entry>
                 <entry>Japanese language support.</entry>
               </row>
 
               <row>
                 <entry><filename>java</filename></entry>
                 <entry>Software related to the Java language.</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>multimedia</filename></entry>
                 <entry>Multimedia software.</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 Palm(tm) series.</entry>
               </row>
 
               <row>
                 <entry><filename>parallel*</filename></entry>
                 <entry>Applications dealing with parallelism in computing.</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>portuguese</filename></entry>
                 <entry>Portuguese language support.</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 related to the Python language.</entry>
               </row>
 
               <row>
                 <entry><filename>ruby*</filename></entry>
                 <entry>Software related to the Ruby language.</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>tcl83*</filename></entry>
                 <entry>Ports that use Tcl version 8.3 to run.</entry>
               </row>
 
               <row>
                 <entry><filename>textproc</filename></entry>
                 <entry>Text processing utilities.  It does not include
                   desktop publishing tools, which go to <filename>print</filename>.</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>tk83*</filename></entry>
                 <entry>Ports that use Tk version 8.3 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><filename>x11</filename></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>
       </sect2>
 
       <sect2>
         <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 <filename>japanese
                 x11-fonts</filename>.</para>
           </listitem>
 
           <listitem>
             <para>Specific categories win over less-specific ones.  For
               instance, an HTML editor should be listed as <filename>www
                 editors</filename>, not the other way around.  Also, you do not
               need to list <filename>net</filename> when the port belongs to
               any of <filename>irc</filename>, <filename>mail</filename>,
               <filename>mbone</filename>, <filename>news</filename>,
               <filename>security</filename>, or <filename>www</filename>.</para>
           </listitem>
 
           <listitem>
             <para><filename>x11</filename> is used as a secondary category only
               when the primary category is a natural language.  In particular,
               you should not put <filename>x11</filename> 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
               <filename>misc</filename>.</para>
           </listitem>
         </itemizedlist>
 
         <para>If you are not sure about the category, please put a comment to
           that effect in your &man.send-pr.1; 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>
       </sect2>
     </sect1>
 
-    <sect1>
+    <sect1 id="makefile-distfiles">
       <title>The distribution files</title>
 
       <para>The second part of the <filename>Makefile</filename> describes the
 	files that must be downloaded in order to build the port, and where
 	they can be downloaded from.</para>
 
       <sect2>
         <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>
       </sect2>
 
       <sect2>
         <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>
       </sect2>
 
       <sect2>
 	<title><makevar>EXTRACT_SUFX</makevar></title>
 
 	<para>If you have one distribution file, and it uses an odd suffix to
 	  indicate the compression mechanism, set
 	  <makevar>EXTRACT_SUFX</makevar>.</para>
 	
 	<para>For example, if the distribution file was named
 	  <filename>foo.tgz</filename> instead of the more normal
 	  <filename>foo.tar.gz</filename>, you would write:</para>
 
 	<programlisting>DISTNAME=      foo
 EXTRACT_SUFX=  .tgz</programlisting>
 
 	<para>The <makevar>USE_BZIP2</makevar> and <makevar>USE_ZIP</makevar>
 	  variables automatically set <makevar>EXTRACT_SUFX</makevar> to
 	  <literal>.bz2</literal> or <literal>.zip</literal> as necessary.  If
 	  neither of these are set then <makevar>EXTRACT_SUFX</makevar>
 	  defaults to <literal>.tar.gz</literal>.</para>
 
 	<para>You never need to set both <makevar>EXTRACT_SUFX</makevar> and
 	  <makevar>DISTFILES</makevar>.</para>
       </sect2>
 
       <sect2>
 	<title><makevar>DISTFILES</makevar></title>
 
 	<para>Sometimes the names of the files to be downloaded have no
 	  resemblance to the name of the port.  For example, it might be
 	  called <filename>source.tar.gz</filename> or similar.  In other
 	  cases the application's source code might be in several different
 	  archives, all of which must be downloaded.</para>
 
 	<para>If this is the case, set <makevar>DISTFILES</makevar> to be a
 	  space separated list of all the files that must be
 	  downloaded.</para>
 
 	<programlisting>DISTFILES=     source1.tar.gz source2.tar.gz</programlisting>
 
 	<para>If not explicitly set, <makevar>DISTFILES</makevar> defaults to
 	  <literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para>
       </sect2>
 
       <sect2>
 	<title><makevar>EXTRACT_ONLY</makevar></title>
 
 	<para>If only some of the <makevar>DISTFILES</makevar> must be
 	  extracted&mdash;for example, one of them is the source code, while
 	  another is an uncompressed document&mdash;list the filenames that
 	  must be extracted in <makevar>EXTRACT_ONLY</makevar>.</para>
 
 	<programlisting>DISTFILES=     source.tar.gz manual.html
 EXTRACT_ONLY=  source.tar.gz</programlisting>
 
 	<para>If <emphasis>none</emphasis> of the <makevar>DISTFILES</makevar>
 	  should be uncompressed then set <makevar>EXTRACT_ONLY</makevar> to
 	  the empty string.</para>
 
 	<programlisting>EXTRACT_ONLY=</programlisting>
       </sect2>
 
       <sect2 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>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>
       </sect2>
 
       <sect2 id="porting-master-sites-n">
 	<title>Multiple distribution files or patches from different
 	  sites and subdirectories
 	  (<literal>MASTER_SITES:n</literal>)</title>
 
 	<para>This section has information on the fetching mechanism
 	  known as both <literal>MASTER_SITES:n</literal> and
 	  <literal>MASTER_SITES_NN</literal>.  We will refer to this
 	  mechanism as <literal>MASTER_SITES:n</literal>
 	  hereon.</para>
 
 	<para>A little background first.  OpenBSD has a neat feature
 	  inside both <makevar>DISTFILES</makevar> and
 	  <makevar>PATCHFILES</makevar> variables, both files and
 	  patches can be postfixed with <literal>:n</literal>
 	  identifiers where <literal>n</literal> both can be
 	  <literal>[0-9]</literal> and denote a group designation.
 	  For example:</para>
 
 	<programlisting>DISTFILES=      alpha:0 beta:1</programlisting>
 
 	<para>In OpenBSD, distribution file <filename>alpha</filename>
 	  will be associated with variable
 	  <makevar>MASTER_SITES0</makevar> instead of our common
 	  <makevar>MASTER_SITES</makevar> and
 	  <filename>beta</filename> with
 	  <makevar>MASTER_SITES1</makevar>.</para>
 
 	<para>This is a very interesting feature which can decrease
 	  that endless search for the correct download site.</para>
 
 	<para>Just picture 2 files in <makevar>DISTFILES</makevar> and
 	  20 sites in <makevar>MASTER_SITES</makevar>, the sites slow
 	  as hell where <filename>beta</filename> is carried by all
 	  sites in <makevar>MASTER_SITES</makevar>, and
 	  <filename>alpha</filename> can only be found in the 20th
 	  site.  It would be such a waste to check all of them if
 	  maintainer knew this beforehand, would not it?  Not a good
 	  start for that lovely weekend!</para>
 
 	<para>Now that you got the picture, just imagine more
 	  <makevar>DISTFILES</makevar> and more
 	  <makevar>MASTER_SITES</makevar>.  Surely our
 	  <quote>distfiles survey meister</quote> would appreciate the
 	  network strain relieve this would bring.</para>
 
 	<para>In the next sections, information will follow on the
 	  FreeBSD implementation of this idea.	We improved a bit on
 	  OpenBSD's concept.</para>
 
 	<sect3>
 	  <title>Simplified information</title>
 
 	  <para>This section tells you how to quickly prepare fine
 	    grained fetching of multiple distribution files and
 	    patches from different sites and subdirectories.  We
 	    describe here a case of simplified
 	    <literal>MASTER_SITES:n</literal> usage.  This will be
 	    sufficient for most scenarios.  However, if you need
 	    further information, you will have to refer to the next
 	    section.</para>
 
 	  <para>Some applications consist of multiple distribution
 	    files that must be downloaded from a number of different
 	    sites.  For example,
 	    <application>Ghostscript</application> consists of the
 	    core of the program, and then a large number of driver
 	    files that are used depending on the user's printer.  Some
 	    of these driver files are supplied with the core, but many
 	    others must be downloaded from a variety of different
 	    sites.</para>
 
 	  <para>To support this, each entry in
 	    <makevar>DISTFILES</makevar> may be followed by a colon
 	    and a <quote>tag name</quote>.  Each site listed in
 	    <makevar>MASTER_SITES</makevar> is then followed by a
 	    colon, and the tag that indicates which distribution files
 	    should be downloaded from this site.</para>
 
 	  <para>For example, consider an application with the source
 	    split in two parts, <filename>source1.tar.gz</filename>
 	    and <filename>source2.tar.gz</filename>, which must be
 	    downloaded from two different sites.  The port's
 	    <filename>Makefile</filename> would include lines like
 	    <xref
 	      linkend="ports-master-sites-n-example-simple-use-one-file-per-site">.</para>
 
 	  <example
 	    id="ports-master-sites-n-example-simple-use-one-file-per-site">
 	    <title>Simplified use of <literal>MASTER_SITES:n</literal>
 	      with 1 file per site</title>
 
 	    <programlisting>MASTER_SITES=   ftp://ftp.example1.com/:source1 \
                 ftp://ftp.example2.com/:source2
 DISTFILES=      source1.tar.gz:source1 \
                 source2.tar.gz:source2</programlisting>
 	  </example>
 
 	  <para>Multiple distribution files can have the same tag.
 	    Continuing the previous example, suppose that there was a
 	    third distfile, <filename>source3.tar.gz</filename>, that
 	    should be downloaded from
 	    <hostid>ftp.example2.com</hostid>.	The
 	    <filename>Makefile</filename> would then be written like
 	    <xref
 	      linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site">.</para>
 
 	  <example
 	    id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site">
 	    <title>Simplified use of <literal>MASTER_SITES:n</literal>
 	      with more than 1 file per site</title>
 
 	    <programlisting>MASTER_SITES=   ftp://ftp.example1.com/:source1 \
                 ftp://ftp.example2.com/:source2
 DISTFILES=      source1.tar.gz:source1 \
                 source2.tar.gz:source2 \
                 source3.tar.gz:source2</programlisting>
 	  </example>
 	</sect3>
 
 	<sect3>
 	  <title>Detailed information</title>
 
 	  <para>Okay, so the previous section example did not reflect
 	    your needs?	 In this section we will explain in detail how
 	    the fine grained fetching mechanism
 	    <literal>MASTER_SITES:n</literal> works and how you can
 	    modify your ports to use it.</para>
 
 	  <orderedlist>
 	    <listitem>
 	      <para>Elements can be postfixed with
 		<literal>:<replaceable>n</replaceable></literal> where
 		<replaceable>n</replaceable> is
 		<literal>[^:,]+</literal>, i.e.,
 		<replaceable>n</replaceable> could conceptually be any
 		alphanumerical string but we will limit it to
 		<literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> for
 		now.</para>
 
 	      <para>Moreover, string matching is case sensitive;
 		i.e., <literal>n</literal> is different from
 		<literal>N</literal>.</para>
 
 	      <para>However, the following words cannot be used for
 		postfixing purposes since they yield special meaning:
 		<literal>default</literal>, <literal>all</literal> and
 		<literal>ALL</literal> (they are used internally in
 		item <xref
 		  linkend="porting-master-sites-n-what-changes-in-port-targets">).
 		Furthermore, <literal>DEFAULT</literal> is a special
 		purpose word (check item <xref
 		  linkend="porting-master-sites-n-DEFAULT-group">).</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Elements postfixed with <literal>:n</literal>
 		belong to the group <literal>n</literal>,
 		<literal>:m</literal> belong to group
 		<literal>m</literal> and so forth.</para>
 	    </listitem>
 
 	    <listitem id="porting-master-sites-n-DEFAULT-group">
 	      <para>Elements without a postfix are groupless, i.e.,
 		they all belong to the special group
 		<literal>DEFAULT</literal>.  If you postfix any
 		elements with <literal>DEFAULT</literal>, you are just
 		being reduntant unless you want to have an element
 		belonging to both <literal>DEFAULT</literal> and other
 		groups at the same time (check item <xref
 		  linkend="porting-master-sites-n-comma-operator">).</para>
 
 	      <para>The following examples are equivalent but the
 		first one is preferred:</para>
 
 	      <programlisting>MASTER_SITES=   alpha
 
 MASTER_SITES=   alpha:DEFAULT</programlisting>
 	    </listitem>
 
 	    <listitem>
 	      <para>Groups are not exclusive, an element may belong to
 		several different groups at the same time and a group
 		can either have either several different elements or
 		none at all.  Repeated elements within the same group
 		will be simply that, repeated elements.</para>
 	    </listitem>
 
 	    <listitem id="porting-master-sites-n-comma-operator">
 	      <para>When you want an element to belong to several
 		groups at the same time, you can use the comma
 		operator (<literal>,</literal>).</para>
 
 	      <para>Instead of repeating it several times, each time
 		with a different postfix, we can list several groups
 		at once in a single postfix.  For instance,
 		<literal>:m,n,o</literal> marks an element that
 		belongs to group <literal>m</literal>,
 		<literal>n</literal> and <literal>o</literal>.</para>
 
 	      <para>All the following examples are equivalent but the
 		last one is preferred:</para>
 
 	      <programlisting>MASTER_SITES=   alpha alpha:SOME_SITE
 
 MASTER_SITES=   alpha:DEFAULT alpha:SOME_SITE
 
 MASTER_SITES=   alpha:SOME_SITE,DEFAULT
 
 MASTER_SITES=   alpha:DEFAULT,SOME_SITE</programlisting>
 	    </listitem>
 
 	    <listitem>
 	      <para>All sites within a given group are sorted
 		according to <makevar>MASTER_SORT_AWK</makevar>.  All
 		groups within <makevar>MASTER_SITES</makevar> and
 		<makevar>PATCH_SITES</makevar> are sorted as
 		well.</para>
 	    </listitem>
 
 	    <listitem id="porting-master-sites-n-group-semantics">
 	      <para>Group semantics can be used in any of the
 		following variables <makevar>MASTER_SITES</makevar>,
 		<makevar>PATCH_SITES</makevar>,
 		<makevar>MASTER_SITE_SUBDIR</makevar>,
 		<makevar>PATCH_SITE_SUBDIR</makevar>,
 		<makevar>DISTFILES</makevar>, and
 		<makevar>PATCHFILES</makevar> according to the
 		following syntax:</para>
 
 	      <orderedlist>
 		<listitem>
 		  <para>All <makevar>MASTER_SITES</makevar>,
 		    <makevar>PATCH_SITES</makevar>,
 		    <makevar>MASTER_SITE_SUBDIR</makevar> and
 		    <makevar>PATCH_SITE_SUBDIR</makevar> elements must
 		    be terminated with the forward slash
 		    <literal>/</literal> character.  If any elements
 		    belong to any groups, the group postfix
 		    <literal>:<replaceable>n</replaceable></literal>
 		    must come right after the terminator
 		    <literal>/</literal>.  The
 		    <literal>MASTER_SITES:n</literal> mechanism relies
 		    on the existence of the terminator
 		    <literal>/</literal> to avoid confusing elements
 		    where a <literal>:n</literal> is a valid part of
 		    the element with occurences where
 		    <literal>:n</literal> denotes group
 		    <literal>n</literal>.  For compatibility purposes,
 		    since the <literal>/</literal> terminator was not
 		    required before in both
 		    <makevar>MASTER_SITE_SUBDIR</makevar> and
 		    <makevar>PATCH_SITE_SUBDIR</makevar> elements, if
 		    the postfix immediate preceeding character is not
 		    a <literal>/</literal> then <literal>:n</literal>
 		    will be considered a valid part of the element
 		    instead of a group postfix even if an element is
 		    postfixed with <literal>:n</literal>.  See both
 		    <xref
 		      linkend="ports-master-sites-n-example-detailed-use-master-site-subdir">
 		    and <xref
 		      linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites">.</para>
 
 		  <example id="ports-master-sites-n-example-detailed-use-master-site-subdir">
 		    <title>Detailed use of
 		      <literal>MASTER_SITES:n</literal> in
 		      <makevar>MASTER_SITE_SUBDIR</makevar></title>
 
 		    <programlisting>MASTER_SITE_SUBDIR=     old:n new/:NEW</programlisting>
 
 		    <itemizedlist>
 		      <listitem>
 			<para>Directories within group
 			  <literal>DEFAULT</literal> -> old:n</para>
 		      </listitem>
 
 		      <listitem>
 			<para>Directories within group
 			  <literal>NEW</literal> -> new</para>
 		      </listitem>
 		    </itemizedlist>
 		  </example>
 
 		  <example
 		    id="ports-master-sites-n-example-detailed-use-complete-example-master-sites">
 		      <title>Detailed use of
 			<literal>MASTER_SITES:n</literal> with comma
 			operator, multiple files, multiple sites and
 			multiple subdirectories</title>
 
 		    <programlisting>MASTER_SITES=   http://site1/%SUBDIR%/ http://site2/:DEFAULT \
                 http://site3/:group3 http://site4/:group4 \
                 http://site5/:group5 http://site6/:group6 \
                 http://site7/:DEFAULT,group6 \
                 http://site8/%SUBDIR%/:group6,group7 \
                 http://site9/:group8
 DISTFILES=      file1 file2:DEFAULT file3:group3 \
                 file4:group4,group5,group6 file5:grouping \
                 file6:group7
 MASTER_SITE_SUBDIR=     directory-trial:1 directory-n/:groupn \
                         directory-one/:group6,DEFAULT \
                         directory</programlisting>
 
 		    <para>The previous example results in the
 		      following fine grained fetching.	Sites are
 		      listed in the exact order they will be
 		      used.</para>
 
 		    <itemizedlist>
 		      <listitem>
 			<para><filename>file1</filename> will be
 			  fetched from</para>
 
 			<itemizedlist>
 			  <listitem>
 			    <para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site1/directory/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site1/directory-one/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site1/directory-trial:1/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site2/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site7/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para><makevar>MASTER_SITE_BACKUP</makevar></para>
 			  </listitem>
 			</itemizedlist>
 		      </listitem>
 
 		      <listitem>
 			<para><filename>file2</filename> will be
 			  fetched exactly as
 			  <filename>file1</filename> since they
 			  both belong to the same group</para>
 
 			<itemizedlist>
 			  <listitem>
 			    <para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site1/directory/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site1/directory-one/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site1/directory-trial:1/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site2/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site7/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para><makevar>MASTER_SITE_BACKUP</makevar></para>
 			  </listitem>
 			</itemizedlist>
 		      </listitem>
 
 		      <listitem>
 			<para><filename>file3</filename> will be
 			  fetched from</para>
 
 			<itemizedlist>
 			  <listitem>
 			    <para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site3/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para><makevar>MASTER_SITE_BACKUP</makevar></para>
 			  </listitem>
 			</itemizedlist>
 		      </listitem>
 
 		      <listitem>
 			<para><filename>file4</filename> will be
 			  fetched from</para>
 
 			<itemizedlist>
 			  <listitem>
 			    <para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site4/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site5/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site6/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site7/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site8/directory-one/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para><makevar>MASTER_SITE_BACKUP</makevar></para>
 			  </listitem>
 			</itemizedlist>
 		      </listitem>
 
 		      <listitem>
 			<para><filename>file5</filename> will be
 			  fetched from</para>
 
 			<itemizedlist>
 			  <listitem>
 			    <para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
 			  </listitem>
 
 			  <listitem>
 			    <para><makevar>MASTER_SITE_BACKUP</makevar></para>
 			  </listitem>
 			</itemizedlist>
 		      </listitem>
 
 		      <listitem>
 			<para><filename>file6</filename> will be
 			  fetched from</para>
 
 			<itemizedlist>
 			  <listitem>
 			    <para><makevar>MASTER_SITE_OVERRIDE</makevar></para>
 			  </listitem>
 
 			  <listitem>
 			    <para>http://site8/directory-one/</para>
 			  </listitem>
 
 			  <listitem>
 			    <para><makevar>MASTER_SITE_BACKUP</makevar></para>
 			  </listitem>
 			</itemizedlist>
 		      </listitem>
 		    </itemizedlist>
 		  </example>
 		</listitem>
 	      </orderedlist>
 	    </listitem>
 
 	    <listitem>
 	      <para>How do I group one of the special variables from
 		<filename>bsd.sites.mk</filename>, e.g.,
 		<makevar>MASTER_SITE_SOURCEFORGE</makevar>?</para>
 
 	      <para>See <xref
 		  linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge">.</para>
 
 	      <example
 		id="ports-master-sites-n-example-detailed-use-master-site-sourceforge">
 		<title>Detailed use of
 		  <literal>MASTER_SITES:n</literal> with
 		  <makevar>MASTER_SITE_SOURCEFORGE</makevar></title>
 
 		<programlisting>MASTER_SITES=   http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/}
 DISTFILES=      something.tar.gz:sourceforge</programlisting>
 	      </example>
 
 	      <para><filename>something.tar.gz</filename> will be
 		fetched from all sites within
 		<makevar>MASTER_SITE_SOURCEFORGE</makevar>.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>How do I use this with <makevar>PATCH*</makevar>
 		variables?</para>
 
 	      <para>All examples were done with
 		<makevar>MASTER*</makevar> variables but they work
 		exactly the same for <makevar>PATCH*</makevar> ones as
 		can be seen in <xref
 		  linkend="ports-master-sites-n-example-detailed-use-patch-sites">.</para>
 
 	      <example
 		id="ports-master-sites-n-example-detailed-use-patch-sites">
 		<title>Simplified use of
 		  <literal>MASTER_SITES:n</literal> with
 		  <makevar>PATCH_SITES</makevar>.</title>
 
 		<programlisting>PATCH_SITES=    http://site1/ http://site2/:test
 PATCHFILES=     patch1:test</programlisting>
 	      </example>
 	    </listitem>
 	  </orderedlist>
 	</sect3>
 
 	<sect3>
 	  <title>What does change for ports?  What does not?</title>
 
 	  <orderedlist numeration="lowerroman">
 	    <listitem>
 	      <para>All current ports remain the same.  The
 		<literal>MASTER_SITES:n</literal> feature code is only
 		activated if there are elements postfixed with
 		<literal>:<replaceable>n</replaceable></literal> like
 		elements according to the aforementioned syntax rules,
 		especially as shown in item <xref
 		  linkend="porting-master-sites-n-group-semantics">.</para>
 	    </listitem>
 
 	    <listitem id="porting-master-sites-n-what-changes-in-port-targets">
 	      <para>The port targets remain the same:
 		<maketarget>checksum</maketarget>,
 		<maketarget>makesum</maketarget>,
 		<maketarget>patch</maketarget>,
 		<maketarget>configure</maketarget>,
 		<maketarget>build</maketarget>, etc.  With the obvious
 		exceptions of <maketarget>do-fetch</maketarget>,
 		<maketarget>fetch-list</maketarget>,
 		<maketarget>master-sites</maketarget> and
 		<maketarget>patch-sites</maketarget>.</para>
 
 	      <itemizedlist>
 		<listitem>
 		  <para><maketarget>do-fetch</maketarget>: deploys the
 		    new grouping postfixed
 		    <makevar>DISTFILES</makevar> and
 		    <makevar>PATCHFILES</makevar> with their matching
 		    group elements within both
 		    <makevar>MASTER_SITES</makevar> and
 		    <makevar>PATCH_SITES</makevar> which use matching
 		    group elements within both
 		    <makevar>MASTER_SITE_SUBDIR</makevar> and
 		    <makevar>PATCH_SITE_SUBDIR</makevar>.  Check <xref
 		      linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites">.</para>
 		</listitem>
 
 		<listitem>
 		  <para><maketarget>fetch-list</maketarget>: works
 		    like old <maketarget>fetch-list</maketarget> with
 		    the exception that it groups just like
 		    <maketarget>do-fetch</maketarget>.</para>
 		</listitem>
 
 		<listitem>
 		  <para><maketarget>master-sites</maketarget> and
 		    <maketarget>patch-sites</maketarget>:
 		    (incompatible with older versions) only return the
 		    elements of group <literal>DEFAULT</literal>;  in
 		    fact, they execute targets
 		    <maketarget>master-sites-default</maketarget> and
 		    <maketarget>patch-sites-default</maketarget>
 		    respectively.</para>
 
 		  <para>Furthermore, using target either
 		    <maketarget>master-sites-all</maketarget> or
 		    <maketarget>patch-sites-all</maketarget> is
 		    preferred to directly checking either
 		    <maketarget>MASTER_SITES</maketarget> or
 		    <maketarget>PATCH_SITES</maketarget>.  Also,
 		    directly checking is not guaranteed to work in any
 		    future versions.  Check item <xref
 		      linkend="porting-master-sites-n-new-port-targets-master-sites-all">
 		    for more information on these new port
 		    targets.</para>
 		</listitem>
 
 	      </itemizedlist>
 	    </listitem>
 
 	    <listitem>
 	      <para>New port targets</para>
 
 	      <orderedlist>
 		<listitem>
 		  <para>There are
 		    <maketarget>master-sites-<replaceable>n</replaceable></maketarget>
 		    and
 		    <maketarget>patch-sites-<replaceable>n</replaceable></maketarget>
 		    targets which will list the elements of the
 		    respective group <replaceable>n</replaceable>
 		    within <makevar>MASTER_SITES</makevar> and
 		    <makevar>PATCH_SITES</makevar> respectively.  For
 		    instance, both
 		    <maketarget>master-sites-DEFAULT</maketarget> and
 		    <maketarget>patch-sites-DEFAULT</maketarget> will
 		    return the elements of group
 		    <literal>DEFAULT</literal>,
 		    <maketarget>master-sites-test</maketarget> and
 		    <maketarget>patch-sites-test</maketarget> of group
 		    <literal>test</literal>, and thereon.</para>
 		</listitem>
 
 		<listitem id="porting-master-sites-n-new-port-targets-master-sites-all">
 		  <para>There are new targets
 		    <maketarget>master-sites-all</maketarget> and
 		    <maketarget>patch-sites-all</maketarget> which do
 		    the work of the old
 		    <maketarget>master-sites</maketarget> and
 		    <maketarget>patch-sites</maketarget> ones.  They
 		    return the elements of all groups as if they all
 		    belonged to the same group with the caveat that it
 		    lists as many
 		    <makevar>MASTER_SITE_BACKUP</makevar> and
 		    <makevar>MASTER_SITE_OVERRIDE</makevar> as there
 		    are groups defined within either
 		    <makevar>DISTFILES</makevar> or
 		    <makevar>PATCHFILES</makevar>;  respectively for
 		    <maketarget>master-sites-all</maketarget> and
 		    <maketarget>patch-sites-all</maketarget>.</para>
 		</listitem>
 	      </orderedlist>
 	    </listitem>
 	  </orderedlist>
 	</sect3>
       </sect2>
 
       <sect2>
         <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>
       </sect2>
     </sect1>
 
-      <sect1>
+      <sect1 id="makefile-maintainer">
         <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="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
             Makefiles</ulink> section.</para>
       </sect1>
 
-      <sect1>
+      <sect1 id="makefile-depend">
         <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 behavior
           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=   ${LOCALBASE}/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 into 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><quote>build</quote> 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><makevar>USE_<replaceable>*</replaceable></makevar></title>
 
 	<para>A number of variables exist in order to encapsulate common
 	  dependencies that many ports have.</para>
 
 	<table frame="none">
 	  <title>The <makevar>USE_<replaceable>*</replaceable></makevar>
 	    variables</title>
 
 	  <tgroup cols="2">
 	    <thead>
 	      <row>
 		<entry>Variable</entry>
 
 		<entry>Means</entry>
 	      </row>
 	    </thead>
 
 	    <tbody>
 	      <row>
 		<entry><makevar>USE_BZIP2</makevar></entry>
 
 		<entry>The port's tarballs are compressed with
 		  <command>bzip2</command>.</entry>
 	      </row>
 
 	      <row>
 		<entry><makevar>USE_ZIP</makevar></entry>
 
 		<entry>The port's tarballs are compressed with
 		  <command>zip</command>.</entry>
 	      </row>
 
 	      <row>
 		<entry><makevar>USE_GMAKE</makevar></entry>
 
 		<entry>The port requires <command>gmake</command> to
 		  build.</entry>
 
 	      </row>
 
 	      <row>
 		<entry><makevar>USE_PERL5</makevar></entry>
 
 		<entry>The port requires Perl 5 to build and install.  See
 		  <xref linkend="using-perl"> for additional variables that
 		  can be set relating to Perl.</entry>
 	      </row>
 
 	      <row>
 		<entry><makevar>USE_X_PREFIX</makevar></entry>
 
 		<entry>The port installs in to <makevar>X11BASE</makevar>
 		  rather than <makevar>PREFIX</makevar>.  See 
 		  <xref linkend="using-x11"> for additional variables that 
 		  can be set relating to X11.</entry>
 	      </row>
 
 	      <row>
 		<entry><makevar>USE_AUTOMAKE</makevar></entry>
 
 		<entry>The port uses GNU <command>automake</command> as part
 		  of its build process.  See <xref linkend="using-automake">
 		  for additional variables that can be set relating to
 		  <command>automake</command>.</entry>
 	      </row>
 
 	      <row>
 		<entry><makevar>USE_AUTOCONF</makevar></entry>
 
 		<entry>The port uses GNU <command>autoconf</command> as part
 		  of its build process.  See <xref linkend="using-automake">
 		  for additional variables that can be set relating to
 		  <command>autoconf</command>.</entry>
 	      </row>
 
 	      <row>
 		<entry><makevar>USE_LIBTOOL</makevar></entry>
 
 		<entry>The port uses GNU <command>libtool</command> as part of
 		  its build process.  See <xref linkend="using-automake"> for
 		  additional variables that can be set relating to
 		  <command>libtool</command>.</entry>
 	      </row>
 
 	      <row>
 		<entry><makevar>GMAKE</makevar></entry>
 
 		<entry>The full path for <command>gmake</command> if it is not
 		  in the <envar>PATH</envar>.</entry>
 	      </row>
 
 	      <row>
 		<entry><makevar>USE_BISON</makevar></entry>
 
 		<entry>The port uses <command>bison</command> for
 		  building.</entry>
 	      </row>
 
 	      <row>
 		<entry><makevar>NO_INSTALL_MANPAGES</makevar></entry>
 
 		<entry>Do not use the <maketarget>install.man</maketarget>
 		  target.</entry>
 	      </row>
 
 	  </tgroup>
 	</table>
 
           <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
             get 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 behavior 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>
 
      <sect2>
       <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 users 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>
       </sect2>
     </sect1>
 
-    <sect1>
+    <sect1 id="makefile-wrkdir">
       <title>Specifying the working directory</title>
 
       <para>Each port is extracted in to a working directory, which must be
 	writeable.  The ports system assumes that the
 	<makevar>DISTFILES</makevar> unpack in to a directory called
 	<literal>${DISTNAME}</literal>.  In other words, if you have
 	set:</para>
 
       <programlisting>PORTNAME=      foo
 PORTVERSION=   1.0</programlisting>
 
       <para>then the port's distribution files contain a top-level directory,
 	<filename>foo-1.0</filename>, and the rest of the files are located
 	under that directory.</para>
 
       <para>There are a number of variables you can set if that is not the
 	case.</para>
 
       <sect2>
 	<title><makevar>WRKSRC</makevar></title>
 
 	<para>The variable lists the name of the directory that is created when
 	  the application's distfiles are extracted.  If our previous example
 	  extracted into a directory called <filename>foo</filename> (and not
 	  <filename>foo-1.0</filename>) you would write:</para>
 
 	<programlisting>WRKSRC=      foo</programlisting>
 
 	<para>or possibly</para>
 
 	<programlisting>WRKSRC=      ${PORTNAME}</programlisting>
       </sect2>
 
       <sect2>
 	<title><makevar>NO_WRKSUBDIR</makevar></title>
 
 	<para>If the port does not extract in to a subdirectory at all then
 	  you should set <makevar>NO_WRKSUBDIR</makevar> to indicate
 	  that.</para>
 
 	<programlisting>NO_WRKSUBDIR= yes</programlisting>
       </sect2>
     </sect1>
 
-      <sect1>
+      <sect1 id="makefile-build">
         <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>
+    <chapter id="special">
       <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 the default location where the new
           library is installed by defining the <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>
 
     <sect1 id="porting-restrictions">
       <title>Ports with distribution restrictions</title>
 
       <para>Licenses vary, and some of them place restrictions on how the
 	application can be packaged, whether it can be sold for profit, and so
 	on.</para> 
 
       <important>
 	<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 CDROM. If in doubt,
 	  please contact the FreeBSD ports mailing list
 	  <email>freebsd-ports@FreeBSD.org</email>.</para>
       </important>
       
       <para>In situations like this, the following variables can be set.  In
 	addition, <filename>ports/LEGAL</filename> should also be
 	updated.</para>
 
       <sect2>
 	<title><makevar>NO_PACKAGE</makevar></title>
 
 	<para>This variable indicates that we may not generate a binary
 	  package of the application.  However, the port's
 	  <makevar>DISTFILES</makevar> files may be freely distributed.</para>
 
 	<para><makevar>NO_PACKAGE</makevar> should also be used if the binary
 	  package is not generally useful, and the application should always
 	  be compiled from the source code.  For example, if the application
 	  has configuration information that is site specific hard coded in to
 	  it at compile time.</para>
 
 	<para><makevar>NO_PACKAGE</makevar> should be set to a string
 	  describing the reason why the package should not be
 	  generated.</para>
       </sect2>
 
       <sect2>
 	<title><makevar>NO_CDROM</makevar></title>
 
 	<para>This variable indicates that although we are allowed to generate
 	  binary packages, we are not allowed to put those packages, or the
 	  port's <makevar>DISTFILES</makevar>, on to CDROM for resale.  The
 	  <makevar>DISTFILES</makevar> will still be available via FTP.</para>
 
 	<para><makevar>NO_PACKAGE</makevar> and <makevar>NO_CDROM</makevar>
 	  can be set simultaneously.</para>
       </sect2>
 
       <sect2>
 	<title><makevar>RESTRICTED</makevar></title>
 
 	<para>Set this variable if the application's license also forbids us
 	  from mirroring the application's <makevar>DISTFILES</makevar> via
 	  FTP.</para>
 
 	<para>Also set this if the application's license has general
 	  restrictions on who may use it.  Examples include:</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para>The application is for non-commercial use only.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The application contains cryptography code which is
 	      forbidden in some countries.</para>
 	  </listitem>
 	</itemizedlist>
       </sect2>
 
       <sect2>
 	<title><makevar>RESTRICTED_FILES</makevar></title>
 
 	<para>If only some of the distribution files are restricted then set
 	  this variable to list them.  It defaults to <literal>${DISTFILES}
 	    ${PATCHFILES}</literal>.</para>
       </sect2>
     </sect1>
 
     <sect1 id="using-perl">
       <title>Using Perl</title>
 
       <table frame="none">
 	<title>Variables for ports that use Perl</title>
 
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Variable</entry>
 	      
 	      <entry>Means</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><makevar>USE_PERL5</makevar></entry>
 
 	      <entry>Says that the port uses Perl 5 to build and run.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><makevar>PERL</makevar></entry>
 	    </row>
 	    
 	    <row>
 	      <entry><makevar>PERL_VERSION</makevar></entry>
 	      
 	      <entry>The full version of Perl installed (e.g.,
 		<literal>5.00503</literal>).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><makevar>PERL_VER</makevar></entry>
 	      
 	      <entry>The short version of Perl installed (e.g.,
 		<literal>5.005</literal>).</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><makevar>PERL_ARCH</makevar></entry>
 	      
 	      <entry>Where Perl stores architecture dependent libraries.
 		Defaults to <literal>${ARCH}-freebsd</literal>.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
     </sect1>
 
     <sect1 id="using-x11">
       <title>Using X11</title>
 
       <table frame="none">
 	<title>Variables for ports that use X</title>
 
 	<tgroup cols="2">
 	  <tbody>
 	    <row>
 	      <entry><makevar>USE_X_PREFIX</makevar></entry>
 
 	      <entry>The port installs in <makevar>X11BASE</makevar>, not
 		<makevar>PREFIX</makevar>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>USE_XLIB</makevar></entry>
 
 	      <entry>The port uses the X libraries.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>USE_MOTIF</makevar></entry>
 
 	      <entry>The port uses the Motif toolkit.  Implies
 		<makevar>USE_XPM</makevar>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>USE_IMAKE</makevar></entry>
 	      
 	      <entry>The port uses <command>imake</command>.  Implies
 		<makevar>USE_X_PREFIX</makevar>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>XMKMF</makevar></entry>
 	      
 	      <entry>Set to the path of <command>xmkmf</command> if not in the
 		<envar>PATH</envar>.  Defaults to <literal>xmkmf
 		  -a</literal>.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
     </sect1>
 
     <sect1 id="using-automake">
       <title>Using <command>automake</command>, <command>autoconf</command>,
 	and <command>libtool</command></title>
 
       <table frame="none">
 	<title>Variables for ports that use automake, autoconf or
 	  libtool</title>
 
 	<tgroup cols="2">
 	  <thead>
 	    <row>
 	      <entry>Variable</entry>
 
 	      <entry>Means</entry>
 	    </row>
 	  </thead>
 
 	  <tbody>
 	    <row>
 	      <entry><makevar>USE_AUTOMAKE</makevar></entry>
 
 	      <entry>The port uses <command>automake</command>.  Implies
 		<makevar>USE_AUTOCONF</makevar> and
 		<literal><makevar>USE_AUTOMAKE_VER</makevar>?=14</literal>.</entry>
 	      </row>
 		
 	    <row>
 	      <entry><makevar>AUTOMAKE</makevar></entry>
 
 	      <entry>The full path for <command>automake</command> if it is
 		not in the <envar>PATH</envar>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>USE_AUTOMAKE_VER</makevar></entry>
 
 	      <entry>The port uses <command>automake</command>.  Valid values
 		for this variable are <literal>14</literal> and
 		<literal>15</literal>, and sets the
 		<makevar>AUTOMAKE_DIR</makevar> and
 		<makevar>ACLOCAL_DIR</makevar> variables
 		appropriately.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTOMAKE_ARGS</makevar></entry>
 
 	      <entry>One or more command line arguments to pass to
 		<makevar>AUTOMAKE</makevar> if
 		<makevar>USE_AUTOMAKE_VER</makevar> is set.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTOMAKE_ENV</makevar></entry>
 
 	      <entry>One or more environment variables to set (and their
 		values) before running <makevar>AUTOMAKE</makevar>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>ACLOCAL</makevar></entry>
 
 	      <entry>Set to the path of the GNU <command>aclocal</command> if
 		it is not in the <envar>PATH</envar>.  The default is set
 		according to the <makevar>USE_AUTOMAKE_VER</makevar>
 		variable.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>ACLOCAL_DIR</makevar></entry>
 	      
 	      <entry>Set to the path of the GNU <command>aclocal</command>
 		shared directory.  The default is set according to the
 		<makevar>USE_AUTOMAKE_VER</makevar> variable.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTOMAKE_DIR</makevar></entry>
 
 	      <entry>Set to the path of the GNU <command>automake</command>
 		shared directory.  The default is set according to the
 		<makevar>USE_AUTOMAKE_VER</makevar> variable.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>USE_AUTOCONF_VER</makevar></entry>
 
 	      <entry>Specifies that the port uses <command>autoconf</command>.
 		The default value is 213.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>USE_AUTOCONF</makevar></entry>
 
 	      <entry>Specifies that the port uses <command>autoconf</command>.
 		Implies <literal>GNU_CONFIGURE</literal> and
 		<literal>USE_AUTOCONF_VER?=213</literal>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTOCONF</makevar></entry>
 
 	      <entry>Set to the path of GNU <command>autoconf</command> if it
 		is not in the <envar>PATH</envar>.  The default is set
 		according to the <makevar>USE_AUTOCONF_VER</makevar>
 		variable.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTOCONF_ARGS</makevar></entry>
 
 	      <entry>Command line arguments to pass to
 		<command>autoconf</command>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTOCONF_ENV</makevar></entry>
 
 	      <entry>Set these
 		<literal><replaceable>variable</replaceable>=<replaceable>value</replaceable></literal> 
 		pairs in the environment before running
 		<command>autoconf</command>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTOHEADER</makevar></entry>
 
 	      <entry>Set to the path of GNU <command>autoheader</command> if
 		it is not in the <envar>PATH</envar>.  The default is set
 		according to <makevar>USE_AUTOCONF_VER</makevar>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTORECONF</makevar></entry>
 
 	      <entry>Set to the path of GNU <command>autoreconf</command> if
 		it is not in the <envar>PATH</envar>.  The default is set
 		according to <makevar>USE_AUTOCONF_VER</makevar>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTOSCAN</makevar></entry>
 
 	      <entry>Set to the path of GNU <command>autoscan</command> if it
 		is not set in the <envar>PATH</envar>.  The default is set
 		according to <makevar>USE_AUTOCONF_VER</makevar>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>AUTOIFNAMES</makevar></entry>
 
 	      <entry>Set to the path of GNU <command>autoifnames</command> if
 		it is not set in the <envar>PATH</envar>.  The default is set
 		according to <makevar>USE_AUTOCONF_VER</makevar>.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>USE_LIBTOOL</makevar></entry>
 
 	      <entry>The port uses <command>libtool</command>.  Implies
 		<makevar>GNU_CONFIGURE</makevar>.</entry>
 	      </row>
 	    
 	    <row>
 	      <entry><makevar>LIBTOOL</makevar></entry>
 
 	      <entry>Set to the path of <command>libtool</command> if it is
 		not set in the <envar>PATH</envar>.</entry>
 	    </row>
 	    
 	    <row>
 	      <entry><makevar>LIBTOOLFILES</makevar></entry>
 
 	      <entry>The files to patch for <command>libtool</command>.
 		Defaults to <literal>aclocal.m4</literal> if
 		<makevar>USE_AUTOCONF</makevar> is defined,
 		<literal>configure</literal> otherwise.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>LIBTOOLFLAGS</makevar></entry>
 
 	      <entry>Additional flags to pass to
 		<command>ltconfig</command>.  Defaults to
 		<literal>--disable-ltlibs</literal>.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
     </sect1>
 
-    <sect1>
+    <sect1 id="using-gnome">
       <title>Using GNOME</title>
 
       <para>The FreeBSD/GNOME project uses a system called
 	<literal>GNOMENG</literal> to define which GNOME components a
 	particular port uses. A
 	<ulink url="http://www.freebsd.org/gnome/docs/porting.html">comprehensive
 	list of these variables</ulink> exists within the FreeBSD/GNOME
 	project's homepage.</para>
 
     </sect1>
 
-    <sect1>
+    <sect1 id="using-kde">
       <title>Using KDE</title>
 
       <table frame="none">
 	<title>Variables for ports that use KDE</title>
 
 	<tgroup cols="2">
 	  <tbody>
 	    <row>
 	      <entry><makevar>USE_QT_VER</makevar></entry>
 
 	      <entry>The port uses Qt toolkit.  Possible values are
 		<literal>1</literal>, <literal>2</literal> and
 		<literal>3</literal>;  each specify the major version
 		of Qt to use.  Sets both <makevar>MOC</makevar> and
 		<makevar>QTCPPFLAGS</makevar>to default appropriate
 		values.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>USE_KDELIBS_VER</makevar></entry>
 
 	      <entry>The port uses KDE libraries.  Possible values are
 		<literal>1</literal>, <literal>2</literal> and
 		<literal>3</literal>;  each specify the major version
 		of KDE to use.  Implies <makevar>USE_QT_VER</makevar>
 		of the appropriate version.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>USE_KDEBASE_VER</makevar></entry>
 
 	      <entry>The port uses KDE base.  Possible values are
 		<literal>1</literal>, <literal>2</literal> and
 		<literal>3</literal>;  each specify the major version
 		of KDE to use.  Implies <makevar>USE_KDELIBS_VER</makevar>
 		of the appropriate version.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>MOC</makevar></entry>
 
 	      <entry>Set to the path of <command>moc</command>.
 		Default set according to <makevar>USE_QT_VER</makevar>
 		value.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>QTCPPFLAGS</makevar></entry>
 
 	      <entry>Set the <makevar>CPPFLAGS</makevar> to use when
 		processing Qt code.  Default set according to
 		<makevar>USE_QT_VER</makevar> value.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
     </sect1>
 
-    <sect1>
+    <sect1 id="using-bison">
       <title>Using Bison</title>
 
       <para></para>
     </sect1>
 
-    <sect1>
+    <sect1 id="using-java">
       <title>Using Java</title>
 
       <para></para>
     </sect1>
 
-    <sect1>
+    <sect1 id="using-python">
       <title>Using Python</title>
 
       <para></para>
     </sect1>
 
-    <sect1>
+    <sect1 id="using-emacs">
       <title>Using Emacs</title>
 
       <para></para>
     </sect1>
 
-    <sect1>
+    <sect1 id="using-ruby">
       <title>Using Ruby</title>
 
       <para></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 role="package">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>
+    <chapter id="shared">
       <title>Shared library versions</title>
 
       <para>Please read our <ulink url="../developers-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 role="package">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>
+      <sect1 id="motif-use">
         <title><makevar>USE_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>
+      <sect1 id="motif-lib">
         <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>
+    <chapter id="x11-fonts">
       <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 <application>XFree86 3.3.3</application>.  If it does not exist,
         please create it, and print out a message urging the user to update
         their <application>XFree86</application> 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 role="package">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 role="package">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
             <application>Emacs</application>' 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>
+    <chapter id="pkg-files">
       <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>
+      <sect1 id="pkg-install">
         <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>
+      <sect1 id="pkg-req">
         <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> <quote>requirements</quote>
           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">manual 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>
+      <sect1 id="pkg-names">
         <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 into 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 id="testing">
     <title>Testing your port</title>
 
-      <sect1>
+      <sect1 id="testing-portlint">
         <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 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 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>
+      <sect1 id="testing-freshports">
 	<title>FreshPorts sanity tests</title>
 
 	<para><ulink url="http://www.FreshPorts.org/">FreshPorts</ulink> has
 	  a sanity test feature which automatically tests each commit to the
 	  FreeBSD ports tree.  If subscribed to this service, you will be
 	  notified of any errors which FreshPorts detects during sanity
 	  testing of your commits.</para>
 
 	<para>If you wish to use this service, all you need is a FreshPorts
 	  account.  If your registered email address is @FreeBSD.org,
 	  you'll see the opt-in link on the right hand side of the webpages.
 	  For those of you who already have a FreshPorts account, but are not
 	  using your @FreeBSD.org email address, just change your email to
 	  @FreeBSD.org, subscribe, then change it back again.</para>
       </sect1>
   </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 <application>CVSup</application> to keep your whole ports collection
         up-to-date, as described in the <ulink url="../handbook/synching.html#CVSUP-CONFIG">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 id="porting-dads">
       <title>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="../../articles/contributing/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>
+      <sect1 id="dads-strip">
         <title>Stripping Binaries</title>
 
         <para>Do not strip binaries manually unless you have to.  All binaries
           should be stripped, but the <maketarget>INSTALL_PROGRAM</maketarget>
           macro will install and strip a binary at the same time (see the next
           section).</para>
 
         <para>If you need to strip a file, but do not wish to use the
           <makevar>INSTALL_PROGRAM</makevar> macro,
           <makevar>${STRIP}</makevar> will strip your program.  This is
           typically done within the <literal>post-install</literal>
           target.  For 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.  Additionally,
           &man.strip.1; will not strip a previously stripped program; it
           will instead exit cleanly.</para>
       </sect1>
 
-      <sect1>
+      <sect1 id="dads-install">
         <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
           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>
 	  </listitem>
 	</itemizedlist>
 
         <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 id="freebsd-versions">
         <title>__FreeBSD_version values</title>
 
 		<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>3.5-RELEASE</entry>
 		    <entry>350000</entry>
 		  </row>
 
 		  <row>
 		    <entry>3.5-STABLE</entry>
 		    <entry>350001</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 the introduction of delayed
 		      checksums.</entry>
 		    <entry>400019</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>4.3-RELEASE</entry>
 		    <entry>430000</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.3-STABLE after wint_t introduction.</entry>
 		    <entry>430001</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.3-STABLE after PCI powerstate API merge.</entry>
 		    <entry>430002</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.4-RELEASE</entry>
 		    <entry>440000</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.4-STABLE after d_thread_t introduction.</entry>
 		    <entry>440001</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.4-STABLE after mount structure changes (affects
 		      filesystem klds).</entry>
 		    <entry>440002</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.4-STABLE after the userland components of smbfs
 		      were imported.</entry>
 		    <entry>440003</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.5-RELEASE</entry>
 		    <entry>450000</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.5-STABLE after the usb structure element rename.</entry>
 		    <entry>450001</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.5-STABLE after the
 		      <literal>sendmail_enable</literal> &man.rc.conf.5;
 		      variable was made to take the value
 		      <literal>NONE</literal>.</entry>
 		    <entry>450004</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.5-STABLE after moving to XFree86 4 by default
 		      for package builds.</entry>
 		    <entry>450005</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.5-STABLE after accept filtering was fixed so
 		      that is no longer susceptible to an easy DoS.</entry>
 		    <entry>450006</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.6-RELEASE</entry>
 		    <entry>460000</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.6-STABLE &man.sendfile.2; fixed to comply with
 		      documentation, not to count any headers sent against
 		      the amount of data to be sent from the file.</entry>
 		    <entry>460001</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.6.2-RELEASE</entry>
 		    <entry>460002</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.6-STABLE</entry>
 		    <entry>460100</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.6-STABLE after MFC of `sed -i'.</entry>
 		    <entry>460101</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.6-STABLE after MFC of many new pkg_install
 		      features from the HEAD.</entry>
 		    <entry>460102</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.7-RELEASE</entry>
 		    <entry>470000</entry>
 		  </row>
 
 		  <row>
 		    <entry>4.7-STABLE</entry>
 		    <entry>470100</entry>
 		  </row>
 
 		  <row>
 		    <entry>Start generated __std{in,out,err}p references rather
 		      than __sF.  This changes std{in,out,err} from a 
 		      compile time expression to a runtime one.</entry>
 		    <entry>470101</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.
 		    Also signifies removal of S/Key.</entry>
 		    <entry>500021</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after SSE support.</entry>
 		    <entry>500022</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after KSE Milestone 2.</entry>
 		    <entry>500023</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after d_thread_t,
 		      and moving UUCP to ports.</entry>
 		    <entry>500024</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after ABI change for discriptor
 		      and creds passing on 64 bit platforms.</entry>
 		    <entry>500025</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after moving to XFree86 4 by default for
 		      package builds, and after the new libc strnstr() function
 		      was added.</entry>
 		    <entry>500026</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the new libc strcasestr() function
 		      was added.</entry>
 		    <entry>500027</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the userland components of smbfs
 		      were imported.</entry>
 		    <entry>500028</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the new C99 specific-width
 		      integer types were added.</entry>
 		    <entry>(Not incremented.)</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after a change was made in the return
 		      value of sendfile(2).</entry>
 		    <entry>500029</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the introduction of the
 		      type <literal>fflags_t</literal>, which is the
 		      appropriate size for file flags.</entry>
 		    <entry>500030</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the usb structure element rename.</entry>
 		    <entry>500031</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the introduction of
 		      Perl 5.6.1.</entry>
 		    <entry>500032</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the
 		      <literal>sendmail_enable</literal> &man.rc.conf.5;
 		      variable was made to take the value
 		      <literal>NONE</literal>.</entry>
 		    <entry>500033</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after mtx_init() grew a third argument.</entry>
 		    <entry>500034</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT with Gcc 3.1.</entry>
 		    <entry>500035</entry>
 	          </row>
 
 		  <row>
 		    <entry>5.0-CURRENT without Perl in /usr/src</entry>
 		    <entry>500036</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the addition of dlfunc(3)</entry>
 		    <entry>500037</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after the types of some struct
 		      sockbuf members were changed and the structure was
 		      reordered.</entry>
 		    <entry>500038</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after headers stopped using
 		      _BSD_FOO_T_ and started using _FOO_T_DECLARED.
 		      This value can also be used as a conservative
 		      estimate of the start of &man.bzip2.1; package
 		      support.</entry>
 		    <entry>500039</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after various changes to disk functions
 		      were made in the name of removing dependancy on disklabel
 		      structure internals.</entry>
 		    <entry>500040</entry>
 
 		  <row>
 		    <entry>5.0-CURRENT after the addition of getopt_long(3)
 		      to libc.</entry>
 		    <entry>500041</entry>
 		  </row>
 
 		  <row>
 		    <entry>5.0-CURRENT after adding weak pthread_XXX stubs
 		      to libc, obsoleting libXThrStub.so.</entry>
 		    <entry>500043</entry>
 		  </row>
                 </tbody>
               </tgroup>
             </informaltable>
 
         <note>
           <para>Note that 2.2-STABLE sometimes identifies itself as
             <quote>2.2.5-STABLE</quote> 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>
       </sect1>
 
-      <sect1>
+      <sect1 id="dads-after-port-mk">
         <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="freebsd-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 <quote>local</quote> tree (e.g.,
                   <literal>/usr/local/</literal>)</entry>
               </row>
 
               <row>
                 <entry><makevar>X11BASE</makevar></entry>
                 <entry>The base of the <quote>X11</quote> 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>
+      <sect1 id="dads-documentation">
         <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>All documentation files and directories installed should
 	  be included in <filename>pkg-plist</filename> with the
 	  <literal>%%PORTDOCS%%</literal> prefix, for example:</para>
 
 	<programlisting>%%PORTDOCS%%share/doc/pure-ftpd/AUTHORS
 %%PORTDOCS%%share/doc/pure-ftpd/CONTACT
 %%PORTDOCS%%@dirrm share/doc/pure-ftpd</programlisting>
 
         <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>
+      <sect1 id="dads-subdirs">
         <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 <quote>news</quote>.  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>
+      <sect1 id="dads-uid">
         <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 role="package">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 999 and register it below.  Look at
           <filename role="package">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
           999.</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:/sbin/nologin
 wnn:*:69:7:Wnn:/nonexistent:/nonexistent
 pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
 ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
 ifmail:*:75:66:Ifmail user:/nonexistent:/nonexistent
 www:*:80:80:World Wide Web Owner:/nonexistent:/sbin/nologin
 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:VPop Mail User:/usr/local/vpopmail:/nonexistent
 smmsp:*:90:90:Sendmail Queue:/nonexistent:/nonexistent
 mailman:*:91:91:Mailman User:/usr/local/mailman:/sbin/nologin
 gdm:*:92:92:GDM Sandbox:/:/sbin/nologin
 jabber:*:93:93:Jabber Daemon:/nonexistent:/nonexistent
 p4admin:*:94:94:Perforce admin:/usr/local/perforce:/sbin/nologin
 interch:*:95:95:Interchange user:/usr/local/interchange:/sbin/nologin
 drweb:*:426:426:Dr.Web Mail Scanner:/nonexistent:/sbin/nologin</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>
+      <sect1 id="dads-rational">
         <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>
+      <sect1 id="dads-cc">
 	<title>Respect both <makevar>CC</makevar> and
 	  <makevar>CXX</makevar></title>
 
 	<para>The port should respect both <makevar>CC</makevar>
 	  and <makevar>CXX</makevar> variables.  If it does not,
 	  please add <literal>NO_PACKAGE=ignores either cc or
 	  cxx</literal> to the <filename>Makefile</filename>.</para>
 
 	<para>An example of a <filename>Makefile</filename> respecting
 	  both <makevar>CC</makevar> and <makevar>CXX</makevar>
 	  variables follows.  Note the <makevar>?=</makevar>:</para>
 
 	<programlisting>CC ?= gcc</programlisting>
 	<programlisting>CXX ?= g++</programlisting>
 
 	<para>Here is an example which respects neither
 	  <makevar>CC</makevar> nor <makevar>CXX</makevar>
 	  variables:</para>
       
 	<programlisting>CC = gcc</programlisting>
 	<programlisting>CXX = g++</programlisting>
 
 	<para>Both <makevar>CC</makevar> and <makevar>CFLAGS</makevar>
 	  variables can be defined on FreeBSD systems in
 	  <filename>/etc/make.conf</filename>.  The first example
 	  defines a value if it was not previously set in
 	  <filename>/etc/make.conf</filename>, preserving any
 	  system-wide definitions.  The second example clobbers
 	  anything previously defined.</para>
       </sect1>
 
-      <sect1>
+      <sect1 id="dads-cflags">
         <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>
+      <sect1 id="dads-config">
         <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>
+      <sect1 id="dads-freedback">
         <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>
+      <sect1 id="dads-readme">
         <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>
+      <sect1 id="dads-misc">
         <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>
+      <sect1 id="dads-stuck">
         <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>mkdir /var/tmp/<replaceable>port-name</replaceable></userinput>
 &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 -d * -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 -d * \! -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 -d * -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>
+    <chapter id="changes">
       <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>
 
       <para>Other resources to assist port maintainers include a list of
 	<ulink url="http://bento.FreeBSD.org/">package building logs and
 	errors </ulink> and the <ulink
 	  url="http://people.FreeBSD.org/~fenner/portsurvey/">FreeBSD
 	  Ports distfiles survey</ulink>.</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/share/sgml/legalnotice.sgml b/en_US.ISO8859-1/share/sgml/legalnotice.sgml
index ecb8ba6cee..95c2fd15d2 100644
--- a/en_US.ISO8859-1/share/sgml/legalnotice.sgml
+++ b/en_US.ISO8859-1/share/sgml/legalnotice.sgml
@@ -1,44 +1,44 @@
 <!-- 
      Standard FreeBSD Documentation Project Legal Notice.
 
      $FreeBSD$
 -->
 
-<legalnotice>
+<legalnotice id="legalnotice">
   <para>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:</para>
 
   <orderedlist>
     <listitem>
       <para>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.</para>
     </listitem>
 
     <listitem>
       <para>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.</para>
     </listitem>
   </orderedlist>
 
   <important>
     <para>THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION 
       PROJECT "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 
       THE FREEBSD DOCUMENTATION PROJECT 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.</para>
   </important>
 </legalnotice>